diff --git a/.env.example b/.env.example
index 396d74e..96f3b7b 100644
--- a/.env.example
+++ b/.env.example
@@ -15,11 +15,19 @@ WEB_PORT=3000
 # ======================
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 NEXT_PUBLIC_API_URL=http://localhost:3001
+# Frontend auth mode:
+# - real: Normal auth/session flow
+# - mock: Local-only seeded user for FE development (blocked outside NODE_ENV=development)
+#   Use `mock` locally to continue FE work when auth flow is unstable.
+# If omitted, web runtime defaults:
+# - development -> mock
+# - production -> real
+NEXT_PUBLIC_AUTH_MODE=real
 
 # ======================
 # PostgreSQL Database
 # ======================
-# Bundled PostgreSQL (when database profile enabled)
+# Bundled PostgreSQL
 # SECURITY: Change POSTGRES_PASSWORD to a strong random password in production
 DATABASE_URL=postgresql://mosaic:REPLACE_WITH_SECURE_PASSWORD@postgres:5432/mosaic
 POSTGRES_USER=mosaic
@@ -28,7 +36,7 @@ POSTGRES_DB=mosaic
 POSTGRES_PORT=5432
 
 # External PostgreSQL (managed service)
-# Disable 'database' profile and point DATABASE_URL to your external instance
+# To use an external instance, update DATABASE_URL above
 # Example: DATABASE_URL=postgresql://user:pass@rds.amazonaws.com:5432/mosaic
 
 # PostgreSQL Performance Tuning (Optional)
@@ -39,7 +47,7 @@ POSTGRES_MAX_CONNECTIONS=100
 # ======================
 # Valkey Cache (Redis-compatible)
 # ======================
-# Bundled Valkey (when cache profile enabled)
+# Bundled Valkey
 VALKEY_URL=redis://valkey:6379
 VALKEY_HOST=valkey
 VALKEY_PORT=6379
@@ -47,7 +55,7 @@ VALKEY_PORT=6379
 VALKEY_MAXMEMORY=256mb
 
 # External Redis/Valkey (managed service)
-# Disable 'cache' profile and point VALKEY_URL to your external instance
+# To use an external instance, update VALKEY_URL above
 # Example: VALKEY_URL=redis://elasticache.amazonaws.com:6379
 # Example with auth: VALKEY_URL=redis://:password@redis.example.com:6379
 
@@ -70,9 +78,9 @@ OIDC_ISSUER=https://auth.example.com/application/o/mosaic-stack/
 OIDC_CLIENT_ID=your-client-id-here
 OIDC_CLIENT_SECRET=your-client-secret-here
 # Redirect URI must match what's configured in Authentik
-# Development: http://localhost:3001/auth/callback/authentik
-# Production: https://api.mosaicstack.dev/auth/callback/authentik
-OIDC_REDIRECT_URI=http://localhost:3001/auth/callback/authentik
+# Development: http://localhost:3001/auth/oauth2/callback/authentik
+# Production: https://api.mosaicstack.dev/auth/oauth2/callback/authentik
+OIDC_REDIRECT_URI=http://localhost:3001/auth/oauth2/callback/authentik
 
 # Authentik PostgreSQL Database
 AUTHENTIK_POSTGRES_USER=authentik
@@ -116,6 +124,9 @@ JWT_EXPIRATION=24h
 # This is used by BetterAuth for session management and CSRF protection
 # Example: openssl rand -base64 32
 BETTER_AUTH_SECRET=REPLACE_WITH_RANDOM_SECRET_MINIMUM_32_CHARS
+# Optional explicit BetterAuth origin for callback/error URL generation.
+# When empty, backend falls back to NEXT_PUBLIC_API_URL.
+BETTER_AUTH_URL=
 
 # Trusted Origins (comma-separated list of additional trusted origins for CORS and auth)
 # These are added to NEXT_PUBLIC_APP_URL and NEXT_PUBLIC_API_URL automatically
@@ -244,12 +255,16 @@ MOSAIC_API_DOMAIN=api.mosaic.local
 MOSAIC_WEB_DOMAIN=mosaic.local
 MOSAIC_AUTH_DOMAIN=auth.mosaic.local
 
-# External Traefik network name (for upstream mode)
+# External Traefik network name (for upstream mode and swarm)
 # Must match the network name of your existing Traefik instance
 TRAEFIK_NETWORK=traefik-public
+TRAEFIK_DOCKER_NETWORK=traefik-public
 
 # TLS/SSL Configuration
 TRAEFIK_TLS_ENABLED=true
+TRAEFIK_ENTRYPOINT=websecure
+# Cert resolver name (leave empty if TLS is handled externally or using self-signed certs)
+TRAEFIK_CERTRESOLVER=
 # For Let's Encrypt (production):
 TRAEFIK_ACME_EMAIL=admin@example.com
 # For self-signed certificates (development), leave TRAEFIK_ACME_EMAIL empty
@@ -285,6 +300,15 @@ GITEA_WEBHOOK_SECRET=REPLACE_WITH_RANDOM_WEBHOOK_SECRET
 # The coordinator service uses this key to authenticate with the API
 COORDINATOR_API_KEY=REPLACE_WITH_RANDOM_API_KEY_MINIMUM_32_CHARS
 
+# Anthropic API Key (used by coordinator for issue parsing)
+# Get your API key from: https://console.anthropic.com/
+ANTHROPIC_API_KEY=REPLACE_WITH_ANTHROPIC_API_KEY
+
+# Coordinator tuning
+COORDINATOR_POLL_INTERVAL=5.0
+COORDINATOR_MAX_CONCURRENT_AGENTS=10
+COORDINATOR_ENABLED=true
+
 # ======================
 # Rate Limiting
 # ======================
@@ -329,16 +353,34 @@ RATE_LIMIT_STORAGE=redis
 # ======================
 # Matrix bot integration for chat-based control via Matrix protocol
 # Requires a Matrix account with an access token for the bot user
-# MATRIX_HOMESERVER_URL=https://matrix.example.com
-# MATRIX_ACCESS_TOKEN=
-# MATRIX_BOT_USER_ID=@mosaic-bot:example.com
-# MATRIX_CONTROL_ROOM_ID=!roomid:example.com
-# MATRIX_WORKSPACE_ID=your-workspace-uuid
+# Set these AFTER deploying Synapse and creating the bot account.
 #
 # SECURITY: MATRIX_WORKSPACE_ID must be a valid workspace UUID from your database.
 # All Matrix commands will execute within this workspace context for proper
 # multi-tenant isolation. Each Matrix bot instance should be configured for
 # a single workspace.
+MATRIX_HOMESERVER_URL=http://synapse:8008
+MATRIX_ACCESS_TOKEN=
+MATRIX_BOT_USER_ID=@mosaic-bot:matrix.example.com
+MATRIX_SERVER_NAME=matrix.example.com
+# MATRIX_CONTROL_ROOM_ID=!roomid:matrix.example.com
+# MATRIX_WORKSPACE_ID=your-workspace-uuid
+
+# ======================
+# Matrix / Synapse Deployment
+# ======================
+# Domains for Traefik routing to Matrix services
+MATRIX_DOMAIN=matrix.example.com
+ELEMENT_DOMAIN=chat.example.com
+
+# Synapse database (created automatically by synapse-db-init in the swarm compose)
+SYNAPSE_POSTGRES_DB=synapse
+SYNAPSE_POSTGRES_USER=synapse
+SYNAPSE_POSTGRES_PASSWORD=REPLACE_WITH_SECURE_SYNAPSE_DB_PASSWORD
+
+# Image tags for Matrix services
+SYNAPSE_IMAGE_TAG=latest
+ELEMENT_IMAGE_TAG=latest
 
 # ======================
 # Orchestrator Configuration
@@ -350,6 +392,17 @@ RATE_LIMIT_STORAGE=redis
 # Health endpoints (/health/*) remain unauthenticated
 ORCHESTRATOR_API_KEY=REPLACE_WITH_RANDOM_API_KEY_MINIMUM_32_CHARS
 
+# Runtime safety defaults (recommended for low-memory hosts)
+MAX_CONCURRENT_AGENTS=2
+SESSION_CLEANUP_DELAY_MS=30000
+ORCHESTRATOR_QUEUE_NAME=orchestrator-tasks
+ORCHESTRATOR_QUEUE_CONCURRENCY=1
+ORCHESTRATOR_QUEUE_MAX_RETRIES=3
+ORCHESTRATOR_QUEUE_BASE_DELAY_MS=1000
+ORCHESTRATOR_QUEUE_MAX_DELAY_MS=60000
+SANDBOX_DEFAULT_MEMORY_MB=256
+SANDBOX_DEFAULT_CPU_LIMIT=1.0
+
 # ======================
 # AI Provider Configuration
 # ======================
@@ -363,11 +416,10 @@ AI_PROVIDER=ollama
 # For remote Ollama: http://your-ollama-server:11434
 OLLAMA_MODEL=llama3.1:latest
 
-# Claude API Configuration (when AI_PROVIDER=claude)
-# OPTIONAL: Only required if AI_PROVIDER=claude
+# Claude API Key
+# Required only when AI_PROVIDER=claude.
 # Get your API key from: https://console.anthropic.com/
-# Note: Claude Max subscription users should use AI_PROVIDER=ollama instead
-# CLAUDE_API_KEY=sk-ant-...
+CLAUDE_API_KEY=REPLACE_WITH_CLAUDE_API_KEY
 
 # OpenAI API Configuration (when AI_PROVIDER=openai)
 # OPTIONAL: Only required if AI_PROVIDER=openai
@@ -405,6 +457,9 @@ TTS_PREMIUM_URL=http://chatterbox-tts:8881/v1
 TTS_FALLBACK_ENABLED=false
 TTS_FALLBACK_URL=http://openedai-speech:8000/v1
 
+# Whisper model for Speaches STT engine
+SPEACHES_WHISPER_MODEL=Systran/faster-whisper-large-v3-turbo
+
 # Speech Service Limits
 # Maximum upload file size in bytes (default: 25MB)
 SPEECH_MAX_UPLOAD_SIZE=25000000
@@ -439,28 +494,6 @@ MOSAIC_TELEMETRY_INSTANCE_ID=your-instance-uuid-here
 # Useful for development and debugging telemetry payloads
 MOSAIC_TELEMETRY_DRY_RUN=false
 
-# ======================
-# Matrix Dev Environment (docker-compose.matrix.yml overlay)
-# ======================
-# These variables configure the local Matrix dev environment.
-# Only used when running: docker compose -f docker/docker-compose.yml -f docker/docker-compose.matrix.yml up
-#
-# Synapse homeserver
-# SYNAPSE_CLIENT_PORT=8008
-# SYNAPSE_FEDERATION_PORT=8448
-# SYNAPSE_POSTGRES_DB=synapse
-# SYNAPSE_POSTGRES_USER=synapse
-# SYNAPSE_POSTGRES_PASSWORD=synapse_dev_password
-#
-# Element Web client
-# ELEMENT_PORT=8501
-#
-# Matrix bridge connection (set after running docker/matrix/scripts/setup-bot.sh)
-# MATRIX_HOMESERVER_URL=http://localhost:8008
-# MATRIX_ACCESS_TOKEN=<obtained from setup-bot.sh>
-# MATRIX_BOT_USER_ID=@mosaic-bot:localhost
-# MATRIX_SERVER_NAME=localhost
-
 # ======================
 # Logging & Debugging
 # ======================
diff --git a/.env.prod.example b/.env.prod.example
deleted file mode 100644
index 1b21644..0000000
--- a/.env.prod.example
+++ /dev/null
@@ -1,66 +0,0 @@
-# ==============================================
-# Mosaic Stack Production Environment
-# ==============================================
-# Copy to .env and configure for production deployment
-
-# ======================
-# PostgreSQL Database
-# ======================
-# CRITICAL: Use a strong, unique password
-POSTGRES_USER=mosaic
-POSTGRES_PASSWORD=REPLACE_WITH_SECURE_PASSWORD
-POSTGRES_DB=mosaic
-POSTGRES_SHARED_BUFFERS=256MB
-POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
-POSTGRES_MAX_CONNECTIONS=100
-
-# ======================
-# Valkey Cache
-# ======================
-VALKEY_MAXMEMORY=256mb
-
-# ======================
-# API Configuration
-# ======================
-API_PORT=3001
-API_HOST=0.0.0.0
-
-# ======================
-# Web Configuration
-# ======================
-WEB_PORT=3000
-NEXT_PUBLIC_API_URL=https://api.mosaicstack.dev
-
-# ======================
-# Authentication (Authentik OIDC)
-# ======================
-OIDC_ISSUER=https://auth.diversecanvas.com/application/o/mosaic-stack/
-OIDC_CLIENT_ID=your-client-id
-OIDC_CLIENT_SECRET=your-client-secret
-OIDC_REDIRECT_URI=https://api.mosaicstack.dev/auth/callback/authentik
-
-# ======================
-# JWT Configuration
-# ======================
-# CRITICAL: Generate a random secret (openssl rand -base64 32)
-JWT_SECRET=REPLACE_WITH_RANDOM_SECRET
-JWT_EXPIRATION=24h
-
-# ======================
-# Traefik Integration
-# ======================
-# Set to true if using external Traefik
-TRAEFIK_ENABLE=true
-TRAEFIK_ENTRYPOINT=websecure
-TRAEFIK_TLS_ENABLED=true
-TRAEFIK_DOCKER_NETWORK=traefik-public
-TRAEFIK_CERTRESOLVER=letsencrypt
-
-# Domain configuration
-MOSAIC_API_DOMAIN=api.mosaicstack.dev
-MOSAIC_WEB_DOMAIN=app.mosaicstack.dev
-
-# ======================
-# Optional: Ollama
-# ======================
-# OLLAMA_ENDPOINT=http://ollama.diversecanvas.com:11434
diff --git a/.env.swarm.example b/.env.swarm.example
deleted file mode 100644
index efa9d8a..0000000
--- a/.env.swarm.example
+++ /dev/null
@@ -1,161 +0,0 @@
-# ==============================================
-# Mosaic Stack - Docker Swarm Configuration
-# ==============================================
-# Copy this file to .env for Docker Swarm deployment
-
-# ======================
-# Application Ports (Internal)
-# ======================
-API_PORT=3001
-API_HOST=0.0.0.0
-WEB_PORT=3000
-
-# ======================
-# Domain Configuration (Traefik)
-# ======================
-# These domains must be configured in your DNS or /etc/hosts
-MOSAIC_API_DOMAIN=api.mosaicstack.dev
-MOSAIC_WEB_DOMAIN=mosaic.mosaicstack.dev
-MOSAIC_AUTH_DOMAIN=auth.mosaicstack.dev
-
-# ======================
-# Web Configuration
-# ======================
-# Use the Traefik domain for the API URL
-NEXT_PUBLIC_APP_URL=http://mosaic.mosaicstack.dev
-NEXT_PUBLIC_API_URL=http://api.mosaicstack.dev
-
-# ======================
-# PostgreSQL Database
-# ======================
-DATABASE_URL=postgresql://mosaic:REPLACE_WITH_SECURE_PASSWORD@postgres:5432/mosaic
-POSTGRES_USER=mosaic
-POSTGRES_PASSWORD=REPLACE_WITH_SECURE_PASSWORD
-POSTGRES_DB=mosaic
-POSTGRES_PORT=5432
-
-# PostgreSQL Performance Tuning
-POSTGRES_SHARED_BUFFERS=256MB
-POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
-POSTGRES_MAX_CONNECTIONS=100
-
-# ======================
-# Valkey Cache
-# ======================
-VALKEY_URL=redis://valkey:6379
-VALKEY_HOST=valkey
-VALKEY_PORT=6379
-VALKEY_MAXMEMORY=256mb
-
-# Knowledge Module Cache Configuration
-KNOWLEDGE_CACHE_ENABLED=true
-KNOWLEDGE_CACHE_TTL=300
-
-# ======================
-# Authentication (Authentik OIDC)
-# ======================
-# NOTE: Authentik services are COMMENTED OUT in docker-compose.swarm.yml by default
-# Uncomment those services if you want to run Authentik internally
-# Otherwise, use external Authentik by configuring OIDC_* variables below
-
-# External Authentik Configuration (default)
-OIDC_ENABLED=true
-OIDC_ISSUER=https://auth.example.com/application/o/mosaic-stack/
-OIDC_CLIENT_ID=your-client-id-here
-OIDC_CLIENT_SECRET=your-client-secret-here
-OIDC_REDIRECT_URI=https://api.mosaicstack.dev/auth/callback/authentik
-
-# Internal Authentik Configuration (only needed if uncommenting Authentik services)
-# Authentik PostgreSQL Database
-AUTHENTIK_POSTGRES_USER=authentik
-AUTHENTIK_POSTGRES_PASSWORD=REPLACE_WITH_SECURE_PASSWORD
-AUTHENTIK_POSTGRES_DB=authentik
-
-# Authentik Server Configuration
-AUTHENTIK_SECRET_KEY=REPLACE_WITH_RANDOM_SECRET_MINIMUM_50_CHARS
-AUTHENTIK_ERROR_REPORTING=false
-AUTHENTIK_BOOTSTRAP_PASSWORD=REPLACE_WITH_SECURE_PASSWORD
-AUTHENTIK_BOOTSTRAP_EMAIL=admin@mosaicstack.dev
-AUTHENTIK_COOKIE_DOMAIN=.mosaicstack.dev
-
-# ======================
-# JWT Configuration
-# ======================
-JWT_SECRET=REPLACE_WITH_RANDOM_SECRET_MINIMUM_32_CHARS
-JWT_EXPIRATION=24h
-
-# ======================
-# Encryption (Credential Security)
-# ======================
-# Generate with: openssl rand -hex 32
-ENCRYPTION_KEY=REPLACE_WITH_64_CHAR_HEX_STRING_GENERATE_WITH_OPENSSL_RAND_HEX_32
-
-# ======================
-# OpenBao Secrets Management
-# ======================
-OPENBAO_ADDR=http://openbao:8200
-OPENBAO_PORT=8200
-# For development only - remove in production
-OPENBAO_DEV_ROOT_TOKEN_ID=root
-
-# ======================
-# Ollama (Optional AI Service)
-# ======================
-OLLAMA_ENDPOINT=http://ollama:11434
-OLLAMA_PORT=11434
-OLLAMA_EMBEDDING_MODEL=mxbai-embed-large
-
-# Semantic Search Configuration
-SEMANTIC_SEARCH_SIMILARITY_THRESHOLD=0.5
-
-# ======================
-# OpenAI API (Optional)
-# ======================
-# OPENAI_API_KEY=sk-...
-
-# ======================
-# Application Environment
-# ======================
-NODE_ENV=production
-
-# ======================
-# Gitea Integration (Coordinator)
-# ======================
-GITEA_URL=https://git.mosaicstack.dev
-GITEA_BOT_USERNAME=mosaic
-GITEA_BOT_TOKEN=REPLACE_WITH_COORDINATOR_BOT_API_TOKEN
-GITEA_BOT_PASSWORD=REPLACE_WITH_COORDINATOR_BOT_PASSWORD
-GITEA_REPO_OWNER=mosaic
-GITEA_REPO_NAME=stack
-GITEA_WEBHOOK_SECRET=REPLACE_WITH_RANDOM_WEBHOOK_SECRET
-COORDINATOR_API_KEY=REPLACE_WITH_RANDOM_API_KEY_MINIMUM_32_CHARS
-
-# ======================
-# Coordinator Service
-# ======================
-ANTHROPIC_API_KEY=REPLACE_WITH_ANTHROPIC_API_KEY
-COORDINATOR_POLL_INTERVAL=5.0
-COORDINATOR_MAX_CONCURRENT_AGENTS=10
-COORDINATOR_ENABLED=true
-
-# ======================
-# Rate Limiting
-# ======================
-RATE_LIMIT_TTL=60
-RATE_LIMIT_GLOBAL_LIMIT=100
-RATE_LIMIT_WEBHOOK_LIMIT=60
-RATE_LIMIT_COORDINATOR_LIMIT=100
-RATE_LIMIT_HEALTH_LIMIT=300
-RATE_LIMIT_STORAGE=redis
-
-# ======================
-# Orchestrator Configuration
-# ======================
-ORCHESTRATOR_API_KEY=REPLACE_WITH_RANDOM_API_KEY_MINIMUM_32_CHARS
-CLAUDE_API_KEY=REPLACE_WITH_CLAUDE_API_KEY
-
-# ======================
-# Logging & Debugging
-# ======================
-LOG_LEVEL=info
-DEBUG=false
diff --git a/.gitignore b/.gitignore
index 1ce13dc..7e684f0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -59,3 +59,13 @@ yarn-error.log*
 
 # Orchestrator reports (generated by QA automation, cleaned up after processing)
 docs/reports/qa-automation/
+
+# Repo-local orchestrator runtime artifacts
+.mosaic/orchestrator/orchestrator.pid
+.mosaic/orchestrator/state.json
+.mosaic/orchestrator/tasks.json
+.mosaic/orchestrator/matrix_state.json
+.mosaic/orchestrator/logs/*.log
+.mosaic/orchestrator/results/*
+!.mosaic/orchestrator/logs/.gitkeep
+!.mosaic/orchestrator/results/.gitkeep
diff --git a/.mosaic/README.md b/.mosaic/README.md
index 606f88a..3e13da9 100644
--- a/.mosaic/README.md
+++ b/.mosaic/README.md
@@ -4,12 +4,12 @@ This repository is attached to the machine-wide Mosaic framework.
 
 ## Load Order for Agents
 
-1. `~/.mosaic/STANDARDS.md`
+1. `~/.config/mosaic/STANDARDS.md`
 2. `AGENTS.md` (this repository)
 3. `.mosaic/repo-hooks.sh` (repo-specific automation hooks)
 
 ## Purpose
 
-- Keep universal standards in `~/.mosaic`
+- Keep universal standards in `~/.config/mosaic`
 - Keep repo-specific behavior in this repo
 - Avoid copying large runtime configs into each project
diff --git a/.mosaic/orchestrator/config.json b/.mosaic/orchestrator/config.json
new file mode 100644
index 0000000..ec50f98
--- /dev/null
+++ b/.mosaic/orchestrator/config.json
@@ -0,0 +1,18 @@
+{
+  "enabled": true,
+  "transport": "matrix",
+  "matrix": {
+    "control_room_id": "",
+    "workspace_id": "",
+    "homeserver_url": "",
+    "access_token": "",
+    "bot_user_id": ""
+  },
+  "worker": {
+    "runtime": "codex",
+    "command_template": "bash scripts/agent/orchestrator-worker.sh {task_file}",
+    "timeout_seconds": 7200,
+    "max_attempts": 1
+  },
+  "quality_gates": ["pnpm lint", "pnpm typecheck", "pnpm test"]
+}
diff --git a/.mosaic/orchestrator/logs/.gitkeep b/.mosaic/orchestrator/logs/.gitkeep
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/.mosaic/orchestrator/logs/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/.mosaic/orchestrator/results/.gitkeep b/.mosaic/orchestrator/results/.gitkeep
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/.mosaic/orchestrator/results/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/.mosaic/quality-rails.yml b/.mosaic/quality-rails.yml
new file mode 100644
index 0000000..816ea24
--- /dev/null
+++ b/.mosaic/quality-rails.yml
@@ -0,0 +1,10 @@
+enabled: false
+template: ""
+
+# Set enabled: true and choose one template:
+# - typescript-node
+# - typescript-nextjs
+# - monorepo
+#
+# Apply manually:
+#   ~/.config/mosaic/bin/mosaic-quality-apply --template <template> --target <repo>
diff --git a/.woodpecker/api.yml b/.woodpecker/api.yml
index fa1abb5..42220a8 100644
--- a/.woodpecker/api.yml
+++ b/.woodpecker/api.yml
@@ -113,7 +113,7 @@ steps:
       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'
+      - 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
 
@@ -155,7 +155,7 @@ steps:
         elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
           DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-api:dev"
         fi
-        /kaniko/executor --context . --dockerfile apps/api/Dockerfile $DESTINATIONS
+        /kaniko/executor --context . --dockerfile apps/api/Dockerfile --snapshot-mode=redo $DESTINATIONS
     when:
       - branch: [main, develop]
         event: [push, manual, tag]
diff --git a/.woodpecker/coordinator.yml b/.woodpecker/coordinator.yml
index 1af4c5f..fa1aa8d 100644
--- a/.woodpecker/coordinator.yml
+++ b/.woodpecker/coordinator.yml
@@ -95,7 +95,7 @@ steps:
         elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
           DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-coordinator:dev"
         fi
-        /kaniko/executor --context apps/coordinator --dockerfile apps/coordinator/Dockerfile $DESTINATIONS
+        /kaniko/executor --context apps/coordinator --dockerfile apps/coordinator/Dockerfile --snapshot-mode=redo $DESTINATIONS
     when:
       - branch: [main, develop]
         event: [push, manual, tag]
diff --git a/.woodpecker/infra.yml b/.woodpecker/infra.yml
index 230bfbc..881fb83 100644
--- a/.woodpecker/infra.yml
+++ b/.woodpecker/infra.yml
@@ -39,7 +39,7 @@ steps:
         elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
           DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-postgres:dev"
         fi
-        /kaniko/executor --context docker/postgres --dockerfile docker/postgres/Dockerfile $DESTINATIONS
+        /kaniko/executor --context docker/postgres --dockerfile docker/postgres/Dockerfile --snapshot-mode=redo $DESTINATIONS
     when:
       - branch: [main, develop]
         event: [push, manual, tag]
@@ -64,7 +64,7 @@ steps:
         elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
           DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-openbao:dev"
         fi
-        /kaniko/executor --context docker/openbao --dockerfile docker/openbao/Dockerfile $DESTINATIONS
+        /kaniko/executor --context docker/openbao --dockerfile docker/openbao/Dockerfile --snapshot-mode=redo $DESTINATIONS
     when:
       - branch: [main, develop]
         event: [push, manual, tag]
diff --git a/.woodpecker/orchestrator.yml b/.woodpecker/orchestrator.yml
index 308a9fb..072a572 100644
--- a/.woodpecker/orchestrator.yml
+++ b/.woodpecker/orchestrator.yml
@@ -112,7 +112,7 @@ steps:
         elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
           DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-orchestrator:dev"
         fi
-        /kaniko/executor --context . --dockerfile apps/orchestrator/Dockerfile $DESTINATIONS
+        /kaniko/executor --context . --dockerfile apps/orchestrator/Dockerfile --snapshot-mode=redo $DESTINATIONS
     when:
       - branch: [main, develop]
         event: [push, manual, tag]
diff --git a/.woodpecker/web.yml b/.woodpecker/web.yml
index 615df31..cb17486 100644
--- a/.woodpecker/web.yml
+++ b/.woodpecker/web.yml
@@ -123,7 +123,7 @@ steps:
         elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
           DESTINATIONS="--destination git.mosaicstack.dev/mosaic/stack-web:dev"
         fi
-        /kaniko/executor --context . --dockerfile apps/web/Dockerfile --build-arg NEXT_PUBLIC_API_URL=https://api.mosaicstack.dev $DESTINATIONS
+        /kaniko/executor --context . --dockerfile apps/web/Dockerfile --snapshot-mode=redo --build-arg NEXT_PUBLIC_API_URL=https://api.mosaicstack.dev $DESTINATIONS
     when:
       - branch: [main, develop]
         event: [push, manual, tag]
diff --git a/AGENTS.md b/AGENTS.md
index 0486a43..bd92747 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,7 +3,7 @@
 ## Load Order
 
 1. `SOUL.md` (repo identity + behavior invariants)
-2. `~/.mosaic/STANDARDS.md` (machine-wide standards rails)
+2. `~/.config/mosaic/STANDARDS.md` (machine-wide standards rails)
 3. `AGENTS.md` (repo-specific overlay)
 4. `.mosaic/repo-hooks.sh` (repo lifecycle hooks)
 
@@ -11,7 +11,7 @@
 
 - This file is authoritative for repo-local operations.
 - `CLAUDE.md` is a compatibility pointer to `AGENTS.md`.
-- Follow universal rails from `~/.mosaic/guides/` and `~/.mosaic/rails/`.
+- Follow universal rails from `~/.config/mosaic/guides/` and `~/.config/mosaic/rails/`.
 
 ## Session Lifecycle
 
@@ -25,6 +25,8 @@ Optional:
 
 ```bash
 bash scripts/agent/log-limitation.sh "Short Name"
+bash scripts/agent/orchestrator-daemon.sh status
+bash scripts/agent/orchestrator-events.sh recent --limit 50
 ```
 
 ## Repo Context
diff --git a/CLAUDE.md b/CLAUDE.md
index 5057017..3358471 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,14 +1,10 @@
-# Compatibility Pointer
+# CLAUDE Compatibility Pointer
 
-This repository uses an agent-neutral Mosaic standards model.
+This file exists so Claude Code sessions load Mosaic standards.
 
-Authoritative repo guidance is in `AGENTS.md`.
+## MANDATORY — Read Before Any Response
 
-Load order for Claude sessions:
+BEFORE responding to any user message, READ `~/.config/mosaic/AGENTS.md`.
 
-1. `SOUL.md`
-2. `~/.mosaic/STANDARDS.md`
-3. `AGENTS.md`
-4. `.mosaic/repo-hooks.sh`
-
-If you were started from `CLAUDE.md`, continue by reading `AGENTS.md` now.
+That file is the universal agent configuration. Do NOT respond until you have loaded it.
+Then read the project-local `AGENTS.md` in this repository for project-specific guidance.
diff --git a/SOUL.md b/SOUL.md
index c961098..11f7bf0 100644
--- a/SOUL.md
+++ b/SOUL.md
@@ -10,7 +10,7 @@ You are Jarvis for the Mosaic Stack repository, running on the current agent run
 - Be calm and clear: keep responses concise, chunked, and PDA-friendly.
 - Respect canonical sources:
   - Repo operations and conventions: `AGENTS.md`
-  - Machine-wide rails: `~/.mosaic/STANDARDS.md`
+  - Machine-wide rails: `~/.config/mosaic/STANDARDS.md`
   - Repo lifecycle hooks: `.mosaic/repo-hooks.sh`
 
 ## Guardrails
diff --git a/apps/api/Dockerfile b/apps/api/Dockerfile
index b4ae23d..cdd1d81 100644
--- a/apps/api/Dockerfile
+++ b/apps/api/Dockerfile
@@ -1,6 +1,3 @@
-# syntax=docker/dockerfile:1
-# Enable BuildKit features for cache mounts
-
 # Base image for all stages
 # Uses Debian slim (glibc) instead of Alpine (musl) because native Node.js addons
 # (matrix-sdk-crypto-nodejs, Prisma engines) require glibc-compatible binaries.
@@ -27,9 +24,8 @@ COPY packages/ui/package.json ./packages/ui/
 COPY packages/config/package.json ./packages/config/
 COPY apps/api/package.json ./apps/api/
 
-# Install dependencies with pnpm store cache
-RUN --mount=type=cache,id=pnpm-store,target=/root/.local/share/pnpm/store \
-    pnpm install --frozen-lockfile
+# Install dependencies (no cache mount — Kaniko builds are ephemeral in CI)
+RUN pnpm install --frozen-lockfile
 
 # ======================
 # Builder stage
@@ -57,15 +53,14 @@ RUN pnpm turbo build --filter=@mosaic/api --force
 # ======================
 FROM node:24-slim AS production
 
-# Remove npm (unused in production — we use pnpm) to reduce attack surface
-RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx
+# Install dumb-init for proper signal handling (static binary from GitHub,
+# avoids apt-get which fails under Kaniko with bookworm GPG signature errors)
+ADD https://github.com/Yelp/dumb-init/releases/download/v1.2.5/dumb-init_1.2.5_x86_64 /usr/local/bin/dumb-init
 
-# Install dumb-init for proper signal handling
-RUN apt-get update && apt-get install -y --no-install-recommends dumb-init \
-    && rm -rf /var/lib/apt/lists/*
-
-# Create non-root user
-RUN groupadd -g 1001 nodejs && useradd -m -u 1001 -g nodejs nestjs
+# Single RUN to minimize Kaniko filesystem snapshots (each RUN = full snapshot)
+RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx \
+    && chmod 755 /usr/local/bin/dumb-init \
+    && groupadd -g 1001 nodejs && useradd -m -u 1001 -g nodejs nestjs
 
 WORKDIR /app
 
diff --git a/apps/api/src/auth/auth-rls.integration.spec.ts b/apps/api/src/auth/auth-rls.integration.spec.ts
index cb78bbc..c2c1690 100644
--- a/apps/api/src/auth/auth-rls.integration.spec.ts
+++ b/apps/api/src/auth/auth-rls.integration.spec.ts
@@ -12,7 +12,10 @@ import { PrismaClient, Prisma } from "@prisma/client";
 import { randomUUID as uuid } from "crypto";
 import { runWithRlsClient, getRlsClient } from "../prisma/rls-context.provider";
 
-describe.skipIf(!process.env.DATABASE_URL)(
+const shouldRunDbIntegrationTests =
+  process.env.RUN_DB_TESTS === "true" && Boolean(process.env.DATABASE_URL);
+
+describe.skipIf(!shouldRunDbIntegrationTests)(
   "Auth Tables RLS Policies (requires DATABASE_URL)",
   () => {
     let prisma: PrismaClient;
@@ -28,7 +31,7 @@ describe.skipIf(!process.env.DATABASE_URL)(
 
     beforeAll(async () => {
       // Skip setup if DATABASE_URL is not available
-      if (!process.env.DATABASE_URL) {
+      if (!shouldRunDbIntegrationTests) {
         return;
       }
 
@@ -49,7 +52,7 @@ describe.skipIf(!process.env.DATABASE_URL)(
 
     afterAll(async () => {
       // Skip cleanup if DATABASE_URL is not available or prisma not initialized
-      if (!process.env.DATABASE_URL || !prisma) {
+      if (!shouldRunDbIntegrationTests || !prisma) {
         return;
       }
 
diff --git a/apps/api/src/auth/auth.config.spec.ts b/apps/api/src/auth/auth.config.spec.ts
index 794ebb6..892a18a 100644
--- a/apps/api/src/auth/auth.config.spec.ts
+++ b/apps/api/src/auth/auth.config.spec.ts
@@ -18,7 +18,13 @@ vi.mock("better-auth/adapters/prisma", () => ({
   prismaAdapter: (...args: unknown[]) => mockPrismaAdapter(...args),
 }));
 
-import { isOidcEnabled, validateOidcConfig, createAuth, getTrustedOrigins } from "./auth.config";
+import {
+  isOidcEnabled,
+  validateOidcConfig,
+  createAuth,
+  getTrustedOrigins,
+  getBetterAuthBaseUrl,
+} from "./auth.config";
 
 describe("auth.config", () => {
   // Store original env vars to restore after each test
@@ -32,6 +38,7 @@ describe("auth.config", () => {
     delete process.env.OIDC_CLIENT_SECRET;
     delete process.env.OIDC_REDIRECT_URI;
     delete process.env.NODE_ENV;
+    delete process.env.BETTER_AUTH_URL;
     delete process.env.NEXT_PUBLIC_APP_URL;
     delete process.env.NEXT_PUBLIC_API_URL;
     delete process.env.TRUSTED_ORIGINS;
@@ -95,7 +102,7 @@ describe("auth.config", () => {
       it("should throw when OIDC_ISSUER is missing", () => {
         process.env.OIDC_CLIENT_ID = "test-client-id";
         process.env.OIDC_CLIENT_SECRET = "test-client-secret";
-        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
 
         expect(() => validateOidcConfig()).toThrow("OIDC_ISSUER");
         expect(() => validateOidcConfig()).toThrow("OIDC authentication is enabled");
@@ -104,7 +111,7 @@ describe("auth.config", () => {
       it("should throw when OIDC_CLIENT_ID is missing", () => {
         process.env.OIDC_ISSUER = "https://auth.example.com/";
         process.env.OIDC_CLIENT_SECRET = "test-client-secret";
-        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
 
         expect(() => validateOidcConfig()).toThrow("OIDC_CLIENT_ID");
       });
@@ -112,7 +119,7 @@ describe("auth.config", () => {
       it("should throw when OIDC_CLIENT_SECRET is missing", () => {
         process.env.OIDC_ISSUER = "https://auth.example.com/";
         process.env.OIDC_CLIENT_ID = "test-client-id";
-        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
 
         expect(() => validateOidcConfig()).toThrow("OIDC_CLIENT_SECRET");
       });
@@ -146,7 +153,7 @@ describe("auth.config", () => {
         process.env.OIDC_ISSUER = "   ";
         process.env.OIDC_CLIENT_ID = "test-client-id";
         process.env.OIDC_CLIENT_SECRET = "test-client-secret";
-        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
 
         expect(() => validateOidcConfig()).toThrow("OIDC_ISSUER");
       });
@@ -155,7 +162,7 @@ describe("auth.config", () => {
         process.env.OIDC_ISSUER = "https://auth.example.com/application/o/mosaic";
         process.env.OIDC_CLIENT_ID = "test-client-id";
         process.env.OIDC_CLIENT_SECRET = "test-client-secret";
-        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
 
         expect(() => validateOidcConfig()).toThrow("OIDC_ISSUER must end with a trailing slash");
         expect(() => validateOidcConfig()).toThrow("https://auth.example.com/application/o/mosaic");
@@ -165,7 +172,7 @@ describe("auth.config", () => {
         process.env.OIDC_ISSUER = "https://auth.example.com/application/o/mosaic-stack/";
         process.env.OIDC_CLIENT_ID = "test-client-id";
         process.env.OIDC_CLIENT_SECRET = "test-client-secret";
-        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+        process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
 
         expect(() => validateOidcConfig()).not.toThrow();
       });
@@ -189,30 +196,30 @@ describe("auth.config", () => {
           expect(() => validateOidcConfig()).toThrow("Parse error:");
         });
 
-        it("should throw when OIDC_REDIRECT_URI path does not start with /auth/callback", () => {
+        it("should throw when OIDC_REDIRECT_URI path does not start with /auth/oauth2/callback", () => {
           process.env.OIDC_REDIRECT_URI = "https://app.example.com/oauth/callback";
 
           expect(() => validateOidcConfig()).toThrow(
-            'OIDC_REDIRECT_URI path must start with "/auth/callback"'
+            'OIDC_REDIRECT_URI path must start with "/auth/oauth2/callback"'
           );
           expect(() => validateOidcConfig()).toThrow("/oauth/callback");
         });
 
-        it("should accept a valid OIDC_REDIRECT_URI with /auth/callback path", () => {
-          process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+        it("should accept a valid OIDC_REDIRECT_URI with /auth/oauth2/callback path", () => {
+          process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
 
           expect(() => validateOidcConfig()).not.toThrow();
         });
 
-        it("should accept OIDC_REDIRECT_URI with exactly /auth/callback path", () => {
-          process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback";
+        it("should accept OIDC_REDIRECT_URI with exactly /auth/oauth2/callback path", () => {
+          process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback";
 
           expect(() => validateOidcConfig()).not.toThrow();
         });
 
         it("should warn but not throw when using localhost in production", () => {
           process.env.NODE_ENV = "production";
-          process.env.OIDC_REDIRECT_URI = "http://localhost:3000/auth/callback/authentik";
+          process.env.OIDC_REDIRECT_URI = "http://localhost:3000/auth/oauth2/callback/authentik";
 
           const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
 
@@ -226,7 +233,7 @@ describe("auth.config", () => {
 
         it("should warn but not throw when using 127.0.0.1 in production", () => {
           process.env.NODE_ENV = "production";
-          process.env.OIDC_REDIRECT_URI = "http://127.0.0.1:3000/auth/callback/authentik";
+          process.env.OIDC_REDIRECT_URI = "http://127.0.0.1:3000/auth/oauth2/callback/authentik";
 
           const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
 
@@ -240,7 +247,7 @@ describe("auth.config", () => {
 
         it("should not warn about localhost when not in production", () => {
           process.env.NODE_ENV = "development";
-          process.env.OIDC_REDIRECT_URI = "http://localhost:3000/auth/callback/authentik";
+          process.env.OIDC_REDIRECT_URI = "http://localhost:3000/auth/oauth2/callback/authentik";
 
           const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
 
@@ -265,16 +272,19 @@ describe("auth.config", () => {
       process.env.OIDC_ISSUER = "https://auth.example.com/application/o/mosaic-stack/";
       process.env.OIDC_CLIENT_ID = "test-client-id";
       process.env.OIDC_CLIENT_SECRET = "test-client-secret";
-      process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+      process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
 
       const mockPrisma = {} as PrismaClient;
       createAuth(mockPrisma);
 
       expect(mockGenericOAuth).toHaveBeenCalledOnce();
       const callArgs = mockGenericOAuth.mock.calls[0][0] as {
-        config: Array<{ pkce?: boolean }>;
+        config: Array<{ pkce?: boolean; redirectURI?: string }>;
       };
       expect(callArgs.config[0].pkce).toBe(true);
+      expect(callArgs.config[0].redirectURI).toBe(
+        "https://app.example.com/auth/oauth2/callback/authentik"
+      );
     });
 
     it("should not call genericOAuth when OIDC is disabled", () => {
@@ -290,7 +300,7 @@ describe("auth.config", () => {
       process.env.OIDC_ENABLED = "true";
       process.env.OIDC_ISSUER = "https://auth.example.com/application/o/mosaic-stack/";
       process.env.OIDC_CLIENT_SECRET = "test-client-secret";
-      process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+      process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
       // OIDC_CLIENT_ID deliberately not set
 
       // validateOidcConfig will throw first, so we need to bypass it
@@ -307,7 +317,7 @@ describe("auth.config", () => {
       process.env.OIDC_ENABLED = "true";
       process.env.OIDC_ISSUER = "https://auth.example.com/application/o/mosaic-stack/";
       process.env.OIDC_CLIENT_ID = "test-client-id";
-      process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+      process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
       // OIDC_CLIENT_SECRET deliberately not set
 
       const mockPrisma = {} as PrismaClient;
@@ -318,7 +328,7 @@ describe("auth.config", () => {
       process.env.OIDC_ENABLED = "true";
       process.env.OIDC_CLIENT_ID = "test-client-id";
       process.env.OIDC_CLIENT_SECRET = "test-client-secret";
-      process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/callback/authentik";
+      process.env.OIDC_REDIRECT_URI = "https://app.example.com/auth/oauth2/callback/authentik";
       // OIDC_ISSUER deliberately not set
 
       const mockPrisma = {} as PrismaClient;
@@ -354,8 +364,7 @@ describe("auth.config", () => {
     });
 
     it("should parse TRUSTED_ORIGINS comma-separated values", () => {
-      process.env.TRUSTED_ORIGINS =
-        "https://app.mosaicstack.dev,https://api.mosaicstack.dev";
+      process.env.TRUSTED_ORIGINS = "https://app.mosaicstack.dev,https://api.mosaicstack.dev";
 
       const origins = getTrustedOrigins();
 
@@ -364,8 +373,7 @@ describe("auth.config", () => {
     });
 
     it("should trim whitespace from TRUSTED_ORIGINS entries", () => {
-      process.env.TRUSTED_ORIGINS =
-        " https://app.mosaicstack.dev , https://api.mosaicstack.dev ";
+      process.env.TRUSTED_ORIGINS = " https://app.mosaicstack.dev , https://api.mosaicstack.dev ";
 
       const origins = getTrustedOrigins();
 
@@ -516,6 +524,21 @@ describe("auth.config", () => {
       expect(config.session.updateAge).toBe(7200);
     });
 
+    it("should configure BetterAuth database ID generation as UUID", () => {
+      const mockPrisma = {} as PrismaClient;
+      createAuth(mockPrisma);
+
+      expect(mockBetterAuth).toHaveBeenCalledOnce();
+      const config = mockBetterAuth.mock.calls[0][0] as {
+        advanced: {
+          database: {
+            generateId: string;
+          };
+        };
+      };
+      expect(config.advanced.database.generateId).toBe("uuid");
+    });
+
     it("should set httpOnly cookie attribute to true", () => {
       const mockPrisma = {} as PrismaClient;
       createAuth(mockPrisma);
@@ -552,6 +575,7 @@ describe("auth.config", () => {
 
     it("should set secure cookie attribute to true in production", () => {
       process.env.NODE_ENV = "production";
+      process.env.NEXT_PUBLIC_API_URL = "https://api.example.com";
       const mockPrisma = {} as PrismaClient;
       createAuth(mockPrisma);
 
@@ -624,4 +648,69 @@ describe("auth.config", () => {
       expect(config.advanced.defaultCookieAttributes.domain).toBeUndefined();
     });
   });
+
+  describe("getBetterAuthBaseUrl", () => {
+    it("should prefer BETTER_AUTH_URL when set", () => {
+      process.env.BETTER_AUTH_URL = "https://auth-base.example.com";
+      process.env.NEXT_PUBLIC_API_URL = "https://api.example.com";
+
+      expect(getBetterAuthBaseUrl()).toBe("https://auth-base.example.com");
+    });
+
+    it("should fall back to NEXT_PUBLIC_API_URL when BETTER_AUTH_URL is not set", () => {
+      process.env.NEXT_PUBLIC_API_URL = "https://api.example.com";
+
+      expect(getBetterAuthBaseUrl()).toBe("https://api.example.com");
+    });
+
+    it("should throw when base URL is invalid", () => {
+      process.env.BETTER_AUTH_URL = "not-a-url";
+
+      expect(() => getBetterAuthBaseUrl()).toThrow("BetterAuth base URL must be a valid URL");
+    });
+
+    it("should throw when base URL is missing in production", () => {
+      process.env.NODE_ENV = "production";
+
+      expect(() => getBetterAuthBaseUrl()).toThrow("Missing BetterAuth base URL in production");
+    });
+
+    it("should throw when base URL is not https in production", () => {
+      process.env.NODE_ENV = "production";
+      process.env.BETTER_AUTH_URL = "http://api.example.com";
+
+      expect(() => getBetterAuthBaseUrl()).toThrow(
+        "BetterAuth base URL must use https in production"
+      );
+    });
+  });
+
+  describe("createAuth - baseURL wiring", () => {
+    beforeEach(() => {
+      mockBetterAuth.mockClear();
+      mockPrismaAdapter.mockClear();
+    });
+
+    it("should pass BETTER_AUTH_URL into BetterAuth config", () => {
+      process.env.BETTER_AUTH_URL = "https://api.mosaicstack.dev";
+
+      const mockPrisma = {} as PrismaClient;
+      createAuth(mockPrisma);
+
+      expect(mockBetterAuth).toHaveBeenCalledOnce();
+      const config = mockBetterAuth.mock.calls[0][0] as { baseURL?: string };
+      expect(config.baseURL).toBe("https://api.mosaicstack.dev");
+    });
+
+    it("should pass NEXT_PUBLIC_API_URL into BetterAuth config when BETTER_AUTH_URL is absent", () => {
+      process.env.NEXT_PUBLIC_API_URL = "https://api.fallback.dev";
+
+      const mockPrisma = {} as PrismaClient;
+      createAuth(mockPrisma);
+
+      expect(mockBetterAuth).toHaveBeenCalledOnce();
+      const config = mockBetterAuth.mock.calls[0][0] as { baseURL?: string };
+      expect(config.baseURL).toBe("https://api.fallback.dev");
+    });
+  });
 });
diff --git a/apps/api/src/auth/auth.config.ts b/apps/api/src/auth/auth.config.ts
index afaf19e..d1c1554 100644
--- a/apps/api/src/auth/auth.config.ts
+++ b/apps/api/src/auth/auth.config.ts
@@ -13,6 +13,41 @@ const REQUIRED_OIDC_ENV_VARS = [
   "OIDC_REDIRECT_URI",
 ] as const;
 
+/**
+ * Resolve BetterAuth base URL from explicit auth URL or API URL.
+ * BetterAuth uses this to generate absolute callback/error URLs.
+ */
+export function getBetterAuthBaseUrl(): string | undefined {
+  const configured = process.env.BETTER_AUTH_URL ?? process.env.NEXT_PUBLIC_API_URL;
+
+  if (!configured || configured.trim() === "") {
+    if (process.env.NODE_ENV === "production") {
+      throw new Error(
+        "Missing BetterAuth base URL in production. Set BETTER_AUTH_URL (preferred) or NEXT_PUBLIC_API_URL."
+      );
+    }
+    return undefined;
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(configured);
+  } catch (urlError: unknown) {
+    const detail = urlError instanceof Error ? urlError.message : String(urlError);
+    throw new Error(
+      `BetterAuth base URL must be a valid URL. Current value: "${configured}". Parse error: ${detail}.`
+    );
+  }
+
+  if (process.env.NODE_ENV === "production" && parsed.protocol !== "https:") {
+    throw new Error(
+      `BetterAuth base URL must use https in production. Current value: "${configured}".`
+    );
+  }
+
+  return parsed.origin;
+}
+
 /**
  * Check if OIDC authentication is enabled via environment variable
  */
@@ -58,17 +93,17 @@ export function validateOidcConfig(): void {
     );
   }
 
-  // Additional validation: OIDC_REDIRECT_URI must be a valid URL with /auth/callback path
+  // Additional validation: OIDC_REDIRECT_URI must be a valid URL with /auth/oauth2/callback path
   validateRedirectUri();
 }
 
 /**
  * Validates the OIDC_REDIRECT_URI environment variable.
  * - Must be a parseable URL
- * - Path must start with /auth/callback
+ * - Path must start with /auth/oauth2/callback
  * - Warns (but does not throw) if using localhost in production
  *
- * @throws Error if URL is invalid or path does not start with /auth/callback
+ * @throws Error if URL is invalid or path does not start with /auth/oauth2/callback
  */
 function validateRedirectUri(): void {
   const redirectUri = process.env.OIDC_REDIRECT_URI;
@@ -85,14 +120,14 @@ function validateRedirectUri(): void {
     throw new Error(
       `OIDC_REDIRECT_URI must be a valid URL. Current value: "${redirectUri}". ` +
         `Parse error: ${detail}. ` +
-        `Example: "https://app.example.com/auth/callback/authentik".`
+        `Example: "https://api.example.com/auth/oauth2/callback/authentik".`
     );
   }
 
-  if (!parsed.pathname.startsWith("/auth/callback")) {
+  if (!parsed.pathname.startsWith("/auth/oauth2/callback")) {
     throw new Error(
-      `OIDC_REDIRECT_URI path must start with "/auth/callback". Current path: "${parsed.pathname}". ` +
-        `Example: "https://app.example.com/auth/callback/authentik".`
+      `OIDC_REDIRECT_URI path must start with "/auth/oauth2/callback". Current path: "${parsed.pathname}". ` +
+        `Example: "https://api.example.com/auth/oauth2/callback/authentik".`
     );
   }
 
@@ -119,6 +154,7 @@ function getOidcPlugins(): ReturnType<typeof genericOAuth>[] {
   const clientId = process.env.OIDC_CLIENT_ID;
   const clientSecret = process.env.OIDC_CLIENT_SECRET;
   const issuer = process.env.OIDC_ISSUER;
+  const redirectUri = process.env.OIDC_REDIRECT_URI;
 
   if (!clientId) {
     throw new Error("OIDC_CLIENT_ID is required when OIDC is enabled but was not set.");
@@ -129,6 +165,9 @@ function getOidcPlugins(): ReturnType<typeof genericOAuth>[] {
   if (!issuer) {
     throw new Error("OIDC_ISSUER is required when OIDC is enabled but was not set.");
   }
+  if (!redirectUri) {
+    throw new Error("OIDC_REDIRECT_URI is required when OIDC is enabled but was not set.");
+  }
 
   return [
     genericOAuth({
@@ -138,6 +177,7 @@ function getOidcPlugins(): ReturnType<typeof genericOAuth>[] {
           clientId,
           clientSecret,
           discoveryUrl: `${issuer}.well-known/openid-configuration`,
+          redirectURI: redirectUri,
           pkce: true,
           scopes: ["openid", "profile", "email"],
         },
@@ -202,7 +242,10 @@ export function createAuth(prisma: PrismaClient) {
   // Validate OIDC configuration at startup - fail fast if misconfigured
   validateOidcConfig();
 
+  const baseURL = getBetterAuthBaseUrl();
+
   return betterAuth({
+    baseURL,
     basePath: "/auth",
     database: prismaAdapter(prisma, {
       provider: "postgresql",
@@ -216,6 +259,10 @@ export function createAuth(prisma: PrismaClient) {
       updateAge: 60 * 60 * 2, // 2 hours — minimum session age before BetterAuth refreshes the expiry on next request
     },
     advanced: {
+      database: {
+        // BetterAuth's default ID generator emits opaque strings; our auth tables use UUID PKs.
+        generateId: "uuid",
+      },
       defaultCookieAttributes: {
         httpOnly: true,
         secure: process.env.NODE_ENV === "production",
diff --git a/apps/api/src/auth/auth.controller.spec.ts b/apps/api/src/auth/auth.controller.spec.ts
index 2bec348..8f54a32 100644
--- a/apps/api/src/auth/auth.controller.spec.ts
+++ b/apps/api/src/auth/auth.controller.spec.ts
@@ -102,11 +102,46 @@ describe("AuthController", () => {
         expect(err).toBeInstanceOf(HttpException);
         expect((err as HttpException).getStatus()).toBe(HttpStatus.INTERNAL_SERVER_ERROR);
         expect((err as HttpException).getResponse()).toBe(
-          "Unable to complete authentication. Please try again in a moment.",
+          "Unable to complete authentication. Please try again in a moment."
         );
       }
     });
 
+    it("should preserve better-call status and body for handler APIError", async () => {
+      const apiError = {
+        statusCode: HttpStatus.BAD_REQUEST,
+        message: "Invalid OAuth configuration",
+        body: {
+          message: "Invalid OAuth configuration",
+          code: "INVALID_OAUTH_CONFIGURATION",
+        },
+      };
+      mockNodeHandler.mockRejectedValueOnce(apiError);
+
+      const mockRequest = {
+        method: "POST",
+        url: "/auth/sign-in/oauth2",
+        headers: {},
+        ip: "192.168.1.10",
+        socket: { remoteAddress: "192.168.1.10" },
+      } as unknown as ExpressRequest;
+
+      const mockResponse = {
+        headersSent: false,
+      } as unknown as ExpressResponse;
+
+      try {
+        await controller.handleAuth(mockRequest, mockResponse);
+        expect.unreachable("Expected HttpException to be thrown");
+      } catch (err) {
+        expect(err).toBeInstanceOf(HttpException);
+        expect((err as HttpException).getStatus()).toBe(HttpStatus.BAD_REQUEST);
+        expect((err as HttpException).getResponse()).toMatchObject({
+          message: "Invalid OAuth configuration",
+        });
+      }
+    });
+
     it("should log warning and not throw when handler throws after headers sent", async () => {
       const handlerError = new Error("Stream interrupted");
       mockNodeHandler.mockRejectedValueOnce(handlerError);
@@ -142,9 +177,7 @@ describe("AuthController", () => {
         headersSent: false,
       } as unknown as ExpressResponse;
 
-      await expect(controller.handleAuth(mockRequest, mockResponse)).rejects.toThrow(
-        HttpException,
-      );
+      await expect(controller.handleAuth(mockRequest, mockResponse)).rejects.toThrow(HttpException);
     });
   });
 
@@ -187,7 +220,7 @@ describe("AuthController", () => {
         OIDC_CLIENT_SECRET: "test-client-secret",
         OIDC_CLIENT_ID: "test-client-id",
         OIDC_ISSUER: "https://auth.test.com/",
-        OIDC_REDIRECT_URI: "https://app.test.com/auth/callback/authentik",
+        OIDC_REDIRECT_URI: "https://app.test.com/auth/oauth2/callback/authentik",
         BETTER_AUTH_SECRET: "test-better-auth-secret",
         JWT_SECRET: "test-jwt-secret",
         CSRF_SECRET: "test-csrf-secret",
@@ -296,11 +329,9 @@ describe("AuthController", () => {
         },
       };
 
+      expect(() => controller.getSession(mockRequest as never)).toThrow(UnauthorizedException);
       expect(() => controller.getSession(mockRequest as never)).toThrow(
-        UnauthorizedException,
-      );
-      expect(() => controller.getSession(mockRequest as never)).toThrow(
-        "Missing authentication context",
+        "Missing authentication context"
       );
     });
 
@@ -313,22 +344,18 @@ describe("AuthController", () => {
         },
       };
 
+      expect(() => controller.getSession(mockRequest as never)).toThrow(UnauthorizedException);
       expect(() => controller.getSession(mockRequest as never)).toThrow(
-        UnauthorizedException,
-      );
-      expect(() => controller.getSession(mockRequest as never)).toThrow(
-        "Missing authentication context",
+        "Missing authentication context"
       );
     });
 
     it("should throw UnauthorizedException when both req.user and req.session are undefined", () => {
       const mockRequest = {};
 
+      expect(() => controller.getSession(mockRequest as never)).toThrow(UnauthorizedException);
       expect(() => controller.getSession(mockRequest as never)).toThrow(
-        UnauthorizedException,
-      );
-      expect(() => controller.getSession(mockRequest as never)).toThrow(
-        "Missing authentication context",
+        "Missing authentication context"
       );
     });
   });
@@ -401,9 +428,7 @@ describe("AuthController", () => {
 
       await controller.handleAuth(mockRequest, mockResponse);
 
-      expect(debugSpy).toHaveBeenCalledWith(
-        expect.stringContaining("203.0.113.50"),
-      );
+      expect(debugSpy).toHaveBeenCalledWith(expect.stringContaining("203.0.113.50"));
     });
 
     it("should extract first IP from X-Forwarded-For with comma-separated IPs", async () => {
@@ -423,13 +448,9 @@ describe("AuthController", () => {
 
       await controller.handleAuth(mockRequest, mockResponse);
 
-      expect(debugSpy).toHaveBeenCalledWith(
-        expect.stringContaining("203.0.113.50"),
-      );
+      expect(debugSpy).toHaveBeenCalledWith(expect.stringContaining("203.0.113.50"));
       // Ensure it does NOT contain the second IP in the extracted position
-      expect(debugSpy).toHaveBeenCalledWith(
-        expect.not.stringContaining("70.41.3.18"),
-      );
+      expect(debugSpy).toHaveBeenCalledWith(expect.not.stringContaining("70.41.3.18"));
     });
 
     it("should extract first IP from X-Forwarded-For as array", async () => {
@@ -449,9 +470,7 @@ describe("AuthController", () => {
 
       await controller.handleAuth(mockRequest, mockResponse);
 
-      expect(debugSpy).toHaveBeenCalledWith(
-        expect.stringContaining("203.0.113.50"),
-      );
+      expect(debugSpy).toHaveBeenCalledWith(expect.stringContaining("203.0.113.50"));
     });
 
     it("should fallback to req.ip when no X-Forwarded-For header", async () => {
@@ -471,9 +490,7 @@ describe("AuthController", () => {
 
       await controller.handleAuth(mockRequest, mockResponse);
 
-      expect(debugSpy).toHaveBeenCalledWith(
-        expect.stringContaining("192.168.1.100"),
-      );
+      expect(debugSpy).toHaveBeenCalledWith(expect.stringContaining("192.168.1.100"));
     });
   });
 });
diff --git a/apps/api/src/auth/auth.controller.ts b/apps/api/src/auth/auth.controller.ts
index 0152b81..573dda5 100644
--- a/apps/api/src/auth/auth.controller.ts
+++ b/apps/api/src/auth/auth.controller.ts
@@ -133,6 +133,11 @@ export class AuthController {
       );
 
       if (!res.headersSent) {
+        const mappedError = this.mapToHttpException(error);
+        if (mappedError) {
+          throw mappedError;
+        }
+
         throw new HttpException(
           "Unable to complete authentication. Please try again in a moment.",
           HttpStatus.INTERNAL_SERVER_ERROR
@@ -159,4 +164,45 @@ export class AuthController {
     // Fall back to direct IP
     return req.ip ?? req.socket.remoteAddress ?? "unknown";
   }
+
+  /**
+   * Preserve known HTTP errors from BetterAuth/better-call instead of converting
+   * every failure into a generic 500.
+   */
+  private mapToHttpException(error: unknown): HttpException | null {
+    if (error instanceof HttpException) {
+      return error;
+    }
+
+    if (!error || typeof error !== "object") {
+      return null;
+    }
+
+    const statusCode = "statusCode" in error ? error.statusCode : undefined;
+    if (!this.isHttpStatus(statusCode)) {
+      return null;
+    }
+
+    const responseBody = "body" in error && error.body !== undefined ? error.body : undefined;
+    if (
+      responseBody !== undefined &&
+      responseBody !== null &&
+      (typeof responseBody === "string" || typeof responseBody === "object")
+    ) {
+      return new HttpException(responseBody, statusCode);
+    }
+
+    const message =
+      "message" in error && typeof error.message === "string" && error.message.length > 0
+        ? error.message
+        : "Authentication request failed";
+    return new HttpException(message, statusCode);
+  }
+
+  private isHttpStatus(value: unknown): value is number {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+      return false;
+    }
+    return value >= 400 && value <= 599;
+  }
 }
diff --git a/apps/api/src/auth/auth.service.spec.ts b/apps/api/src/auth/auth.service.spec.ts
index 5cc01b9..ca72b8e 100644
--- a/apps/api/src/auth/auth.service.spec.ts
+++ b/apps/api/src/auth/auth.service.spec.ts
@@ -410,7 +410,7 @@ describe("AuthService", () => {
       },
     };
 
-    it("should return session data for valid token", async () => {
+    it("should validate session token using secure BetterAuth cookie header", async () => {
       const auth = service.getAuth();
       const mockGetSession = vi.fn().mockResolvedValue(mockSessionData);
       auth.api = { getSession: mockGetSession } as any;
@@ -418,7 +418,58 @@ describe("AuthService", () => {
       const result = await service.verifySession("valid-token");
 
       expect(result).toEqual(mockSessionData);
+      expect(mockGetSession).toHaveBeenCalledTimes(1);
       expect(mockGetSession).toHaveBeenCalledWith({
+        headers: {
+          cookie: "__Secure-better-auth.session_token=valid-token",
+        },
+      });
+    });
+
+    it("should preserve raw cookie token value without URL re-encoding", async () => {
+      const auth = service.getAuth();
+      const mockGetSession = vi.fn().mockResolvedValue(mockSessionData);
+      auth.api = { getSession: mockGetSession } as any;
+
+      const result = await service.verifySession("tok/with+=chars=");
+
+      expect(result).toEqual(mockSessionData);
+      expect(mockGetSession).toHaveBeenCalledWith({
+        headers: {
+          cookie: "__Secure-better-auth.session_token=tok/with+=chars=",
+        },
+      });
+    });
+
+    it("should fall back to Authorization header when cookie-based lookups miss", async () => {
+      const auth = service.getAuth();
+      const mockGetSession = vi
+        .fn()
+        .mockResolvedValueOnce(null)
+        .mockResolvedValueOnce(null)
+        .mockResolvedValueOnce(null)
+        .mockResolvedValueOnce(mockSessionData);
+      auth.api = { getSession: mockGetSession } as any;
+
+      const result = await service.verifySession("valid-token");
+
+      expect(result).toEqual(mockSessionData);
+      expect(mockGetSession).toHaveBeenNthCalledWith(1, {
+        headers: {
+          cookie: "__Secure-better-auth.session_token=valid-token",
+        },
+      });
+      expect(mockGetSession).toHaveBeenNthCalledWith(2, {
+        headers: {
+          cookie: "better-auth.session_token=valid-token",
+        },
+      });
+      expect(mockGetSession).toHaveBeenNthCalledWith(3, {
+        headers: {
+          cookie: "__Host-better-auth.session_token=valid-token",
+        },
+      });
+      expect(mockGetSession).toHaveBeenNthCalledWith(4, {
         headers: {
           authorization: "Bearer valid-token",
         },
@@ -517,14 +568,10 @@ describe("AuthService", () => {
 
     it("should re-throw 'certificate has expired' as infrastructure error (not auth)", async () => {
       const auth = service.getAuth();
-      const mockGetSession = vi
-        .fn()
-        .mockRejectedValue(new Error("certificate has expired"));
+      const mockGetSession = vi.fn().mockRejectedValue(new Error("certificate has expired"));
       auth.api = { getSession: mockGetSession } as any;
 
-      await expect(service.verifySession("any-token")).rejects.toThrow(
-        "certificate has expired"
-      );
+      await expect(service.verifySession("any-token")).rejects.toThrow("certificate has expired");
     });
 
     it("should re-throw 'Unauthorized: Access denied for user' as infrastructure error (not auth)", async () => {
diff --git a/apps/api/src/auth/auth.service.ts b/apps/api/src/auth/auth.service.ts
index 97e8d4b..44f5a6c 100644
--- a/apps/api/src/auth/auth.service.ts
+++ b/apps/api/src/auth/auth.service.ts
@@ -21,6 +21,10 @@ interface VerifiedSession {
   session: Record<string, unknown>;
 }
 
+interface SessionHeaderCandidate {
+  headers: Record<string, string>;
+}
+
 @Injectable()
 export class AuthService {
   private readonly logger = new Logger(AuthService.name);
@@ -103,36 +107,27 @@ export class AuthService {
    * Only known-safe auth errors return null; everything else propagates as 500.
    */
   async verifySession(token: string): Promise<VerifiedSession | null> {
-    try {
-      // TODO(#411): BetterAuth getSession returns opaque types — replace when upstream exports typed interfaces
-      const session = await this.auth.api.getSession({
-        headers: {
-          authorization: `Bearer ${token}`,
-        },
-      });
+    let sawNonError = false;
 
-      if (!session) {
-        return null;
-      }
+    for (const candidate of this.buildSessionHeaderCandidates(token)) {
+      try {
+        // TODO(#411): BetterAuth getSession returns opaque types — replace when upstream exports typed interfaces
+        const session = await this.auth.api.getSession(candidate);
 
-      return {
-        user: session.user as Record<string, unknown>,
-        session: session.session as Record<string, unknown>,
-      };
-    } catch (error: unknown) {
-      // Only known-safe auth errors return null
-      if (error instanceof Error) {
-        const msg = error.message.toLowerCase();
-        const isExpectedAuthError =
-          msg.includes("invalid token") ||
-          msg.includes("token expired") ||
-          msg.includes("session expired") ||
-          msg.includes("session not found") ||
-          msg.includes("invalid session") ||
-          msg === "unauthorized" ||
-          msg === "expired";
+        if (!session) {
+          continue;
+        }
+
+        return {
+          user: session.user as Record<string, unknown>,
+          session: session.session as Record<string, unknown>,
+        };
+      } catch (error: unknown) {
+        if (error instanceof Error) {
+          if (this.isExpectedAuthError(error.message)) {
+            continue;
+          }
 
-        if (!isExpectedAuthError) {
           // Infrastructure or unexpected — propagate as 500
           const safeMessage = (error.stack ?? error.message).replace(
             /Bearer\s+\S+/gi,
@@ -141,14 +136,55 @@ export class AuthService {
           this.logger.error("Session verification failed due to unexpected error", safeMessage);
           throw error;
         }
+
+        // Non-Error thrown values — log once for observability, treat as auth failure
+        if (!sawNonError) {
+          const errorDetail = typeof error === "string" ? error : JSON.stringify(error);
+          this.logger.warn("Session verification received non-Error thrown value", errorDetail);
+          sawNonError = true;
+        }
       }
-      // Non-Error thrown values — log for observability, treat as auth failure
-      if (!(error instanceof Error)) {
-        const errorDetail = typeof error === "string" ? error : JSON.stringify(error);
-        this.logger.warn("Session verification received non-Error thrown value", errorDetail);
-      }
-      return null;
     }
+
+    return null;
+  }
+
+  private buildSessionHeaderCandidates(token: string): SessionHeaderCandidate[] {
+    return [
+      {
+        headers: {
+          cookie: `__Secure-better-auth.session_token=${token}`,
+        },
+      },
+      {
+        headers: {
+          cookie: `better-auth.session_token=${token}`,
+        },
+      },
+      {
+        headers: {
+          cookie: `__Host-better-auth.session_token=${token}`,
+        },
+      },
+      {
+        headers: {
+          authorization: `Bearer ${token}`,
+        },
+      },
+    ];
+  }
+
+  private isExpectedAuthError(message: string): boolean {
+    const normalized = message.toLowerCase();
+    return (
+      normalized.includes("invalid token") ||
+      normalized.includes("token expired") ||
+      normalized.includes("session expired") ||
+      normalized.includes("session not found") ||
+      normalized.includes("invalid session") ||
+      normalized === "unauthorized" ||
+      normalized === "expired"
+    );
   }
 
   /**
diff --git a/apps/api/src/auth/guards/auth.guard.ts b/apps/api/src/auth/guards/auth.guard.ts
index 9e4c21d..b1f758c 100644
--- a/apps/api/src/auth/guards/auth.guard.ts
+++ b/apps/api/src/auth/guards/auth.guard.ts
@@ -1,10 +1,18 @@
-import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from "@nestjs/common";
+import {
+  Injectable,
+  CanActivate,
+  ExecutionContext,
+  UnauthorizedException,
+  Logger,
+} from "@nestjs/common";
 import { AuthService } from "../auth.service";
 import type { AuthUser } from "@mosaic/shared";
 import type { MaybeAuthenticatedRequest } from "../types/better-auth-request.interface";
 
 @Injectable()
 export class AuthGuard implements CanActivate {
+  private readonly logger = new Logger(AuthGuard.name);
+
   constructor(private readonly authService: AuthService) {}
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
@@ -59,7 +67,8 @@ export class AuthGuard implements CanActivate {
   }
 
   /**
-   * Extract token from cookie (BetterAuth stores session token in better-auth.session_token cookie)
+   * Extract token from cookie.
+   * BetterAuth may prefix the cookie name with "__Secure-" when running on HTTPS.
    */
   private extractTokenFromCookie(request: MaybeAuthenticatedRequest): string | undefined {
     // Express types `cookies` as `any`; cast to a known shape for type safety.
@@ -68,8 +77,23 @@ export class AuthGuard implements CanActivate {
       return undefined;
     }
 
-    // BetterAuth uses 'better-auth.session_token' as the cookie name by default
-    return cookies["better-auth.session_token"];
+    // BetterAuth default cookie name is "better-auth.session_token"
+    // When Secure cookies are enabled, BetterAuth prefixes with "__Secure-".
+    const candidates = [
+      "__Secure-better-auth.session_token",
+      "better-auth.session_token",
+      "__Host-better-auth.session_token",
+    ] as const;
+
+    for (const name of candidates) {
+      const token = cookies[name];
+      if (token) {
+        this.logger.debug(`Session cookie found: ${name}`);
+        return token;
+      }
+    }
+
+    return undefined;
   }
 
   /**
diff --git a/apps/api/src/common/interceptors/rls-context.integration.spec.ts b/apps/api/src/common/interceptors/rls-context.integration.spec.ts
index 6d52614..27b9531 100644
--- a/apps/api/src/common/interceptors/rls-context.integration.spec.ts
+++ b/apps/api/src/common/interceptors/rls-context.integration.spec.ts
@@ -137,13 +137,13 @@ describe("RLS Context Integration", () => {
         queries: ["findMany"],
       });
 
-      // Verify SET LOCAL was called
+      // Verify transaction-local set_config calls were made
       expect(mockTransactionClient.$executeRaw).toHaveBeenCalledWith(
-        expect.arrayContaining(["SET LOCAL app.current_user_id = ", ""]),
+        expect.arrayContaining(["SELECT set_config('app.current_user_id', ", ", true)"]),
         userId
       );
       expect(mockTransactionClient.$executeRaw).toHaveBeenCalledWith(
-        expect.arrayContaining(["SET LOCAL app.current_workspace_id = ", ""]),
+        expect.arrayContaining(["SELECT set_config('app.current_workspace_id', ", ", true)"]),
         workspaceId
       );
     });
diff --git a/apps/api/src/common/interceptors/rls-context.interceptor.spec.ts b/apps/api/src/common/interceptors/rls-context.interceptor.spec.ts
index c21be1f..1eda38b 100644
--- a/apps/api/src/common/interceptors/rls-context.interceptor.spec.ts
+++ b/apps/api/src/common/interceptors/rls-context.interceptor.spec.ts
@@ -80,7 +80,7 @@ describe("RlsContextInterceptor", () => {
 
       expect(result).toEqual({ data: "test response" });
       expect(mockTransactionClient.$executeRaw).toHaveBeenCalledWith(
-        expect.arrayContaining(["SET LOCAL app.current_user_id = ", ""]),
+        expect.arrayContaining(["SELECT set_config('app.current_user_id', ", ", true)"]),
         userId
       );
     });
@@ -111,13 +111,13 @@ describe("RlsContextInterceptor", () => {
       // Check that user context was set
       expect(mockTransactionClient.$executeRaw).toHaveBeenNthCalledWith(
         1,
-        expect.arrayContaining(["SET LOCAL app.current_user_id = ", ""]),
+        expect.arrayContaining(["SELECT set_config('app.current_user_id', ", ", true)"]),
         userId
       );
       // Check that workspace context was set
       expect(mockTransactionClient.$executeRaw).toHaveBeenNthCalledWith(
         2,
-        expect.arrayContaining(["SET LOCAL app.current_workspace_id = ", ""]),
+        expect.arrayContaining(["SELECT set_config('app.current_workspace_id', ", ", true)"]),
         workspaceId
       );
     });
diff --git a/apps/api/src/common/interceptors/rls-context.interceptor.ts b/apps/api/src/common/interceptors/rls-context.interceptor.ts
index b6921c9..0b3886d 100644
--- a/apps/api/src/common/interceptors/rls-context.interceptor.ts
+++ b/apps/api/src/common/interceptors/rls-context.interceptor.ts
@@ -100,12 +100,12 @@ export class RlsContextInterceptor implements NestInterceptor {
       this.prisma
         .$transaction(
           async (tx) => {
-            // Set user context (always present for authenticated requests)
-            await tx.$executeRaw`SET LOCAL app.current_user_id = ${userId}`;
+            // Use set_config(..., true) so values are transaction-local and parameterized safely.
+            // Direct SET LOCAL with bind parameters produces invalid SQL on PostgreSQL.
+            await tx.$executeRaw`SELECT set_config('app.current_user_id', ${userId}, true)`;
 
-            // Set workspace context (if present)
             if (workspaceId) {
-              await tx.$executeRaw`SET LOCAL app.current_workspace_id = ${workspaceId}`;
+              await tx.$executeRaw`SELECT set_config('app.current_workspace_id', ${workspaceId}, true)`;
             }
 
             // Propagate the transaction client via AsyncLocalStorage
diff --git a/apps/api/src/credentials/user-credential.model.spec.ts b/apps/api/src/credentials/user-credential.model.spec.ts
index 612505f..e61da36 100644
--- a/apps/api/src/credentials/user-credential.model.spec.ts
+++ b/apps/api/src/credentials/user-credential.model.spec.ts
@@ -15,7 +15,12 @@
 import { describe, it, expect, beforeAll, afterAll } from "vitest";
 import { PrismaClient, CredentialType, CredentialScope } from "@prisma/client";
 
-describe("UserCredential Model", () => {
+const shouldRunDbIntegrationTests =
+  process.env.RUN_DB_TESTS === "true" && Boolean(process.env.DATABASE_URL);
+
+const describeFn = shouldRunDbIntegrationTests ? describe : describe.skip;
+
+describeFn("UserCredential Model", () => {
   let prisma: PrismaClient;
   let testUserId: string;
   let testWorkspaceId: string;
@@ -23,8 +28,8 @@ describe("UserCredential Model", () => {
   beforeAll(async () => {
     // Note: These tests require a running database
     // They will be skipped in CI if DATABASE_URL is not set
-    if (!process.env.DATABASE_URL) {
-      console.warn("DATABASE_URL not set, skipping UserCredential model tests");
+    if (!shouldRunDbIntegrationTests) {
+      console.warn("Skipping UserCredential model tests (set RUN_DB_TESTS=true and DATABASE_URL)");
       return;
     }
 
diff --git a/apps/api/src/job-events/job-events.performance.spec.ts b/apps/api/src/job-events/job-events.performance.spec.ts
index 48f1a30..ace0c97 100644
--- a/apps/api/src/job-events/job-events.performance.spec.ts
+++ b/apps/api/src/job-events/job-events.performance.spec.ts
@@ -16,7 +16,9 @@ import { JOB_CREATED, JOB_STARTED, STEP_STARTED } from "./event-types";
  * NOTE: These tests require a real database connection with realistic data volume.
  * Run with: pnpm test:api -- job-events.performance.spec.ts
  */
-const describeFn = process.env.DATABASE_URL ? describe : describe.skip;
+const shouldRunDbIntegrationTests =
+  process.env.RUN_DB_TESTS === "true" && Boolean(process.env.DATABASE_URL);
+const describeFn = shouldRunDbIntegrationTests ? describe : describe.skip;
 
 describeFn("JobEventsService Performance", () => {
   let service: JobEventsService;
diff --git a/apps/api/src/knowledge/services/fulltext-search.spec.ts b/apps/api/src/knowledge/services/fulltext-search.spec.ts
index 853c78d..0a698f0 100644
--- a/apps/api/src/knowledge/services/fulltext-search.spec.ts
+++ b/apps/api/src/knowledge/services/fulltext-search.spec.ts
@@ -27,7 +27,9 @@ async function isFulltextSearchConfigured(prisma: PrismaClient): Promise<boolean
  * Skip when DATABASE_URL is not set. Tests that require the trigger/index
  * will be skipped if the database migration hasn't been applied.
  */
-const describeFn = process.env.DATABASE_URL ? describe : describe.skip;
+const shouldRunDbIntegrationTests =
+  process.env.RUN_DB_TESTS === "true" && Boolean(process.env.DATABASE_URL);
+const describeFn = shouldRunDbIntegrationTests ? describe : describe.skip;
 
 describeFn("Full-Text Search Setup (Integration)", () => {
   let prisma: PrismaClient;
diff --git a/apps/api/src/main.ts b/apps/api/src/main.ts
index 19d7150..647f5bd 100644
--- a/apps/api/src/main.ts
+++ b/apps/api/src/main.ts
@@ -49,8 +49,10 @@ async function bootstrap() {
 
   // Configure CORS for cookie-based authentication
   // Origin list is shared with BetterAuth trustedOrigins via getTrustedOrigins()
+  const trustedOrigins = getTrustedOrigins();
+  console.log(`[CORS] Trusted origins: ${JSON.stringify(trustedOrigins)}`);
   app.enableCors({
-    origin: getTrustedOrigins(),
+    origin: trustedOrigins,
     credentials: true, // Required for cookie-based authentication
     methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
     allowedHeaders: ["Content-Type", "Authorization", "Cookie", "X-CSRF-Token", "X-Workspace-Id"],
diff --git a/apps/api/src/mosaic-telemetry/mosaic-telemetry.module.spec.ts b/apps/api/src/mosaic-telemetry/mosaic-telemetry.module.spec.ts
index 37420ec..8d45559 100644
--- a/apps/api/src/mosaic-telemetry/mosaic-telemetry.module.spec.ts
+++ b/apps/api/src/mosaic-telemetry/mosaic-telemetry.module.spec.ts
@@ -3,6 +3,7 @@ import { Test, TestingModule } from "@nestjs/testing";
 import { ConfigModule } from "@nestjs/config";
 import { MosaicTelemetryModule } from "./mosaic-telemetry.module";
 import { MosaicTelemetryService } from "./mosaic-telemetry.service";
+import { PrismaService } from "../prisma/prisma.service";
 
 // Mock the telemetry client to avoid real HTTP calls
 vi.mock("@mosaicstack/telemetry-client", async (importOriginal) => {
@@ -56,6 +57,30 @@ vi.mock("@mosaicstack/telemetry-client", async (importOriginal) => {
 
 describe("MosaicTelemetryModule", () => {
   let module: TestingModule;
+  const sharedTestEnv = {
+    ENCRYPTION_KEY: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+  };
+  const mockPrismaService = {
+    onModuleInit: vi.fn(),
+    onModuleDestroy: vi.fn(),
+    $connect: vi.fn(),
+    $disconnect: vi.fn(),
+  };
+
+  const buildTestModule = async (env: Record<string, string>): Promise<TestingModule> =>
+    Test.createTestingModule({
+      imports: [
+        ConfigModule.forRoot({
+          isGlobal: true,
+          envFilePath: [],
+          load: [() => ({ ...env, ...sharedTestEnv })],
+        }),
+        MosaicTelemetryModule,
+      ],
+    })
+      .overrideProvider(PrismaService)
+      .useValue(mockPrismaService)
+      .compile();
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -63,40 +88,18 @@ describe("MosaicTelemetryModule", () => {
 
   describe("module initialization", () => {
     it("should compile the module successfully", async () => {
-      module = await Test.createTestingModule({
-        imports: [
-          ConfigModule.forRoot({
-            isGlobal: true,
-            envFilePath: [],
-            load: [
-              () => ({
-                MOSAIC_TELEMETRY_ENABLED: "false",
-              }),
-            ],
-          }),
-          MosaicTelemetryModule,
-        ],
-      }).compile();
+      module = await buildTestModule({
+        MOSAIC_TELEMETRY_ENABLED: "false",
+      });
 
       expect(module).toBeDefined();
       await module.close();
     });
 
     it("should provide MosaicTelemetryService", async () => {
-      module = await Test.createTestingModule({
-        imports: [
-          ConfigModule.forRoot({
-            isGlobal: true,
-            envFilePath: [],
-            load: [
-              () => ({
-                MOSAIC_TELEMETRY_ENABLED: "false",
-              }),
-            ],
-          }),
-          MosaicTelemetryModule,
-        ],
-      }).compile();
+      module = await buildTestModule({
+        MOSAIC_TELEMETRY_ENABLED: "false",
+      });
 
       const service = module.get<MosaicTelemetryService>(MosaicTelemetryService);
       expect(service).toBeDefined();
@@ -106,20 +109,9 @@ describe("MosaicTelemetryModule", () => {
     });
 
     it("should export MosaicTelemetryService for injection in other modules", async () => {
-      module = await Test.createTestingModule({
-        imports: [
-          ConfigModule.forRoot({
-            isGlobal: true,
-            envFilePath: [],
-            load: [
-              () => ({
-                MOSAIC_TELEMETRY_ENABLED: "false",
-              }),
-            ],
-          }),
-          MosaicTelemetryModule,
-        ],
-      }).compile();
+      module = await buildTestModule({
+        MOSAIC_TELEMETRY_ENABLED: "false",
+      });
 
       const service = module.get(MosaicTelemetryService);
       expect(service).toBeDefined();
@@ -130,24 +122,13 @@ describe("MosaicTelemetryModule", () => {
 
   describe("lifecycle integration", () => {
     it("should initialize service on module init when enabled", async () => {
-      module = await Test.createTestingModule({
-        imports: [
-          ConfigModule.forRoot({
-            isGlobal: true,
-            envFilePath: [],
-            load: [
-              () => ({
-                MOSAIC_TELEMETRY_ENABLED: "true",
-                MOSAIC_TELEMETRY_SERVER_URL: "https://tel.test.local",
-                MOSAIC_TELEMETRY_API_KEY: "a".repeat(64),
-                MOSAIC_TELEMETRY_INSTANCE_ID: "550e8400-e29b-41d4-a716-446655440000",
-                MOSAIC_TELEMETRY_DRY_RUN: "false",
-              }),
-            ],
-          }),
-          MosaicTelemetryModule,
-        ],
-      }).compile();
+      module = await buildTestModule({
+        MOSAIC_TELEMETRY_ENABLED: "true",
+        MOSAIC_TELEMETRY_SERVER_URL: "https://tel.test.local",
+        MOSAIC_TELEMETRY_API_KEY: "a".repeat(64),
+        MOSAIC_TELEMETRY_INSTANCE_ID: "550e8400-e29b-41d4-a716-446655440000",
+        MOSAIC_TELEMETRY_DRY_RUN: "false",
+      });
 
       await module.init();
 
@@ -158,20 +139,9 @@ describe("MosaicTelemetryModule", () => {
     });
 
     it("should not start client when disabled via env", async () => {
-      module = await Test.createTestingModule({
-        imports: [
-          ConfigModule.forRoot({
-            isGlobal: true,
-            envFilePath: [],
-            load: [
-              () => ({
-                MOSAIC_TELEMETRY_ENABLED: "false",
-              }),
-            ],
-          }),
-          MosaicTelemetryModule,
-        ],
-      }).compile();
+      module = await buildTestModule({
+        MOSAIC_TELEMETRY_ENABLED: "false",
+      });
 
       await module.init();
 
@@ -182,24 +152,13 @@ describe("MosaicTelemetryModule", () => {
     });
 
     it("should cleanly shut down on module destroy", async () => {
-      module = await Test.createTestingModule({
-        imports: [
-          ConfigModule.forRoot({
-            isGlobal: true,
-            envFilePath: [],
-            load: [
-              () => ({
-                MOSAIC_TELEMETRY_ENABLED: "true",
-                MOSAIC_TELEMETRY_SERVER_URL: "https://tel.test.local",
-                MOSAIC_TELEMETRY_API_KEY: "a".repeat(64),
-                MOSAIC_TELEMETRY_INSTANCE_ID: "550e8400-e29b-41d4-a716-446655440000",
-                MOSAIC_TELEMETRY_DRY_RUN: "false",
-              }),
-            ],
-          }),
-          MosaicTelemetryModule,
-        ],
-      }).compile();
+      module = await buildTestModule({
+        MOSAIC_TELEMETRY_ENABLED: "true",
+        MOSAIC_TELEMETRY_SERVER_URL: "https://tel.test.local",
+        MOSAIC_TELEMETRY_API_KEY: "a".repeat(64),
+        MOSAIC_TELEMETRY_INSTANCE_ID: "550e8400-e29b-41d4-a716-446655440000",
+        MOSAIC_TELEMETRY_DRY_RUN: "false",
+      });
 
       await module.init();
 
diff --git a/apps/api/src/prisma/prisma.service.spec.ts b/apps/api/src/prisma/prisma.service.spec.ts
index bfe3925..19eaea2 100644
--- a/apps/api/src/prisma/prisma.service.spec.ts
+++ b/apps/api/src/prisma/prisma.service.spec.ts
@@ -156,7 +156,7 @@ describe("PrismaService", () => {
     it("should set workspace context variables in transaction", async () => {
       const userId = "user-123";
       const workspaceId = "workspace-456";
-      const executeRawSpy = vi.spyOn(service, "$executeRaw").mockResolvedValue(0);
+      vi.spyOn(service, "$executeRaw").mockResolvedValue(0);
 
       // Mock $transaction to execute the callback with a mock tx client
       const mockTx = {
@@ -195,7 +195,6 @@ describe("PrismaService", () => {
       };
 
       // Mock both methods at the same time to avoid spy issues
-      const originalSetContext = service.setWorkspaceContext.bind(service);
       const setContextCalls: [string, string, unknown][] = [];
       service.setWorkspaceContext = vi.fn().mockImplementation((uid, wid, tx) => {
         setContextCalls.push([uid, wid, tx]);
diff --git a/apps/api/src/prisma/prisma.service.ts b/apps/api/src/prisma/prisma.service.ts
index 8ffad80..66cfbfd 100644
--- a/apps/api/src/prisma/prisma.service.ts
+++ b/apps/api/src/prisma/prisma.service.ts
@@ -3,6 +3,7 @@ import { PrismaClient } from "@prisma/client";
 import { VaultService } from "../vault/vault.service";
 import { createAccountEncryptionExtension } from "./account-encryption.extension";
 import { createLlmEncryptionExtension } from "./llm-encryption.extension";
+import { getRlsClient } from "./rls-context.provider";
 
 /**
  * Prisma service that manages database connection lifecycle
@@ -177,6 +178,13 @@ export class PrismaService extends PrismaClient implements OnModuleInit, OnModul
     workspaceId: string,
     fn: (tx: PrismaClient) => Promise<T>
   ): Promise<T> {
+    const rlsClient = getRlsClient();
+
+    if (rlsClient) {
+      await this.setWorkspaceContext(userId, workspaceId, rlsClient as unknown as PrismaClient);
+      return fn(rlsClient as unknown as PrismaClient);
+    }
+
     return this.$transaction(async (tx) => {
       await this.setWorkspaceContext(userId, workspaceId, tx as PrismaClient);
       return fn(tx as PrismaClient);
diff --git a/apps/api/src/tasks/tasks.controller.spec.ts b/apps/api/src/tasks/tasks.controller.spec.ts
index 152bf4b..6489184 100644
--- a/apps/api/src/tasks/tasks.controller.spec.ts
+++ b/apps/api/src/tasks/tasks.controller.spec.ts
@@ -25,6 +25,8 @@ describe("TasksController", () => {
       const request = context.switchToHttp().getRequest();
       request.user = {
         id: "550e8400-e29b-41d4-a716-446655440002",
+        email: "test@example.com",
+        name: "Test User",
         workspaceId: "550e8400-e29b-41d4-a716-446655440001",
       };
       return true;
@@ -46,6 +48,8 @@ describe("TasksController", () => {
   const mockRequest = {
     user: {
       id: mockUserId,
+      email: "test@example.com",
+      name: "Test User",
       workspaceId: mockWorkspaceId,
     },
   };
@@ -132,13 +136,16 @@ describe("TasksController", () => {
 
       mockTasksService.findAll.mockResolvedValue(paginatedResult);
 
-      const result = await controller.findAll(query, mockWorkspaceId);
+      const result = await controller.findAll(query, mockWorkspaceId, mockRequest.user);
 
       expect(result).toEqual(paginatedResult);
-      expect(service.findAll).toHaveBeenCalledWith({
-        ...query,
-        workspaceId: mockWorkspaceId,
-      });
+      expect(service.findAll).toHaveBeenCalledWith(
+        {
+          ...query,
+          workspaceId: mockWorkspaceId,
+        },
+        mockUserId
+      );
     });
 
     it("should extract workspaceId from request.user if not in query", async () => {
@@ -149,12 +156,13 @@ describe("TasksController", () => {
         meta: { total: 0, page: 1, limit: 50, totalPages: 0 },
       });
 
-      await controller.findAll(query as any, mockWorkspaceId);
+      await controller.findAll(query as any, mockWorkspaceId, mockRequest.user);
 
       expect(service.findAll).toHaveBeenCalledWith(
         expect.objectContaining({
           workspaceId: mockWorkspaceId,
-        })
+        }),
+        mockUserId
       );
     });
   });
@@ -163,10 +171,10 @@ describe("TasksController", () => {
     it("should return a task by id", async () => {
       mockTasksService.findOne.mockResolvedValue(mockTask);
 
-      const result = await controller.findOne(mockTaskId, mockWorkspaceId);
+      const result = await controller.findOne(mockTaskId, mockWorkspaceId, mockRequest.user);
 
       expect(result).toEqual(mockTask);
-      expect(service.findOne).toHaveBeenCalledWith(mockTaskId, mockWorkspaceId);
+      expect(service.findOne).toHaveBeenCalledWith(mockTaskId, mockWorkspaceId, mockUserId);
     });
 
     it("should throw error if workspaceId not found", async () => {
@@ -175,10 +183,10 @@ describe("TasksController", () => {
       // We can test that the controller properly uses the provided workspaceId instead
       mockTasksService.findOne.mockResolvedValue(mockTask);
 
-      const result = await controller.findOne(mockTaskId, mockWorkspaceId);
+      const result = await controller.findOne(mockTaskId, mockWorkspaceId, mockRequest.user);
 
       expect(result).toEqual(mockTask);
-      expect(service.findOne).toHaveBeenCalledWith(mockTaskId, mockWorkspaceId);
+      expect(service.findOne).toHaveBeenCalledWith(mockTaskId, mockWorkspaceId, mockUserId);
     });
   });
 
diff --git a/apps/api/src/tasks/tasks.controller.ts b/apps/api/src/tasks/tasks.controller.ts
index 0da02fb..1a031a9 100644
--- a/apps/api/src/tasks/tasks.controller.ts
+++ b/apps/api/src/tasks/tasks.controller.ts
@@ -53,8 +53,12 @@ export class TasksController {
    */
   @Get()
   @RequirePermission(Permission.WORKSPACE_ANY)
-  async findAll(@Query() query: QueryTasksDto, @Workspace() workspaceId: string) {
-    return this.tasksService.findAll(Object.assign({}, query, { workspaceId }));
+  async findAll(
+    @Query() query: QueryTasksDto,
+    @Workspace() workspaceId: string,
+    @CurrentUser() user: AuthenticatedUser
+  ) {
+    return this.tasksService.findAll(Object.assign({}, query, { workspaceId }), user.id);
   }
 
   /**
@@ -64,8 +68,12 @@ export class TasksController {
    */
   @Get(":id")
   @RequirePermission(Permission.WORKSPACE_ANY)
-  async findOne(@Param("id") id: string, @Workspace() workspaceId: string) {
-    return this.tasksService.findOne(id, workspaceId);
+  async findOne(
+    @Param("id") id: string,
+    @Workspace() workspaceId: string,
+    @CurrentUser() user: AuthenticatedUser
+  ) {
+    return this.tasksService.findOne(id, workspaceId, user.id);
   }
 
   /**
diff --git a/apps/api/src/tasks/tasks.service.spec.ts b/apps/api/src/tasks/tasks.service.spec.ts
index 24621e0..e751af5 100644
--- a/apps/api/src/tasks/tasks.service.spec.ts
+++ b/apps/api/src/tasks/tasks.service.spec.ts
@@ -21,6 +21,7 @@ describe("TasksService", () => {
       update: vi.fn(),
       delete: vi.fn(),
     },
+    withWorkspaceContext: vi.fn(),
   };
 
   const mockActivityService = {
@@ -75,6 +76,9 @@ describe("TasksService", () => {
 
     // Clear all mocks before each test
     vi.clearAllMocks();
+    mockPrismaService.withWorkspaceContext.mockImplementation(async (_userId, _workspaceId, fn) => {
+      return fn(mockPrismaService as unknown as PrismaService);
+    });
   });
 
   it("should be defined", () => {
@@ -95,6 +99,11 @@ describe("TasksService", () => {
       const result = await service.create(mockWorkspaceId, mockUserId, createDto);
 
       expect(result).toEqual(mockTask);
+      expect(prisma.withWorkspaceContext).toHaveBeenCalledWith(
+        mockUserId,
+        mockWorkspaceId,
+        expect.any(Function)
+      );
       expect(prisma.task.create).toHaveBeenCalledWith({
         data: {
           title: createDto.title,
@@ -177,6 +186,29 @@ describe("TasksService", () => {
       });
     });
 
+    it("should use workspace context when userId is provided", async () => {
+      mockPrismaService.task.findMany.mockResolvedValue([mockTask]);
+      mockPrismaService.task.count.mockResolvedValue(1);
+
+      await service.findAll({ workspaceId: mockWorkspaceId }, mockUserId);
+
+      expect(prisma.withWorkspaceContext).toHaveBeenCalledWith(
+        mockUserId,
+        mockWorkspaceId,
+        expect.any(Function)
+      );
+    });
+
+    it("should fallback to direct Prisma access when userId is missing", async () => {
+      mockPrismaService.task.findMany.mockResolvedValue([mockTask]);
+      mockPrismaService.task.count.mockResolvedValue(1);
+
+      await service.findAll({ workspaceId: mockWorkspaceId });
+
+      expect(prisma.withWorkspaceContext).not.toHaveBeenCalled();
+      expect(prisma.task.findMany).toHaveBeenCalled();
+    });
+
     it("should filter by status", async () => {
       mockPrismaService.task.findMany.mockResolvedValue([mockTask]);
       mockPrismaService.task.count.mockResolvedValue(1);
diff --git a/apps/api/src/tasks/tasks.service.ts b/apps/api/src/tasks/tasks.service.ts
index e0d1829..aecf1b0 100644
--- a/apps/api/src/tasks/tasks.service.ts
+++ b/apps/api/src/tasks/tasks.service.ts
@@ -1,8 +1,7 @@
 import { Injectable, NotFoundException } from "@nestjs/common";
-import { Prisma, Task } from "@prisma/client";
+import { Prisma, Task, TaskStatus, TaskPriority, type PrismaClient } from "@prisma/client";
 import { PrismaService } from "../prisma/prisma.service";
 import { ActivityService } from "../activity/activity.service";
-import { TaskStatus, TaskPriority } from "@prisma/client";
 import type { CreateTaskDto, UpdateTaskDto, QueryTasksDto } from "./dto";
 
 type TaskWithRelations = Task & {
@@ -24,6 +23,18 @@ export class TasksService {
     private readonly activityService: ActivityService
   ) {}
 
+  private async withWorkspaceContextIfAvailable<T>(
+    workspaceId: string | undefined,
+    userId: string | undefined,
+    fn: (client: PrismaClient) => Promise<T>
+  ): Promise<T> {
+    if (workspaceId && userId && typeof this.prisma.withWorkspaceContext === "function") {
+      return this.prisma.withWorkspaceContext(userId, workspaceId, fn);
+    }
+
+    return fn(this.prisma);
+  }
+
   /**
    * Create a new task
    */
@@ -66,19 +77,21 @@ export class TasksService {
       data.completedAt = new Date();
     }
 
-    const task = await this.prisma.task.create({
-      data,
-      include: {
-        assignee: {
-          select: { id: true, name: true, email: true },
+    const task = await this.withWorkspaceContextIfAvailable(workspaceId, userId, async (client) => {
+      return client.task.create({
+        data,
+        include: {
+          assignee: {
+            select: { id: true, name: true, email: true },
+          },
+          creator: {
+            select: { id: true, name: true, email: true },
+          },
+          project: {
+            select: { id: true, name: true, color: true },
+          },
         },
-        creator: {
-          select: { id: true, name: true, email: true },
-        },
-        project: {
-          select: { id: true, name: true, color: true },
-        },
-      },
+      });
     });
 
     // Log activity
@@ -92,7 +105,10 @@ export class TasksService {
   /**
    * Get paginated tasks with filters
    */
-  async findAll(query: QueryTasksDto): Promise<{
+  async findAll(
+    query: QueryTasksDto,
+    userId?: string
+  ): Promise<{
     data: Omit<TaskWithRelations, "subtasks">[];
     meta: {
       total: number;
@@ -143,28 +159,34 @@ export class TasksService {
     }
 
     // Execute queries in parallel
-    const [data, total] = await Promise.all([
-      this.prisma.task.findMany({
-        where,
-        include: {
-          assignee: {
-            select: { id: true, name: true, email: true },
-          },
-          creator: {
-            select: { id: true, name: true, email: true },
-          },
-          project: {
-            select: { id: true, name: true, color: true },
-          },
-        },
-        orderBy: {
-          createdAt: "desc",
-        },
-        skip,
-        take: limit,
-      }),
-      this.prisma.task.count({ where }),
-    ]);
+    const [data, total] = await this.withWorkspaceContextIfAvailable(
+      query.workspaceId,
+      userId,
+      async (client) => {
+        return Promise.all([
+          client.task.findMany({
+            where,
+            include: {
+              assignee: {
+                select: { id: true, name: true, email: true },
+              },
+              creator: {
+                select: { id: true, name: true, email: true },
+              },
+              project: {
+                select: { id: true, name: true, color: true },
+              },
+            },
+            orderBy: {
+              createdAt: "desc",
+            },
+            skip,
+            take: limit,
+          }),
+          client.task.count({ where }),
+        ]);
+      }
+    );
 
     return {
       data,
@@ -180,30 +202,32 @@ export class TasksService {
   /**
    * Get a single task by ID
    */
-  async findOne(id: string, workspaceId: string): Promise<TaskWithRelations> {
-    const task = await this.prisma.task.findUnique({
-      where: {
-        id,
-        workspaceId,
-      },
-      include: {
-        assignee: {
-          select: { id: true, name: true, email: true },
+  async findOne(id: string, workspaceId: string, userId?: string): Promise<TaskWithRelations> {
+    const task = await this.withWorkspaceContextIfAvailable(workspaceId, userId, async (client) => {
+      return client.task.findUnique({
+        where: {
+          id,
+          workspaceId,
         },
-        creator: {
-          select: { id: true, name: true, email: true },
-        },
-        project: {
-          select: { id: true, name: true, color: true },
-        },
-        subtasks: {
-          include: {
-            assignee: {
-              select: { id: true, name: true, email: true },
+        include: {
+          assignee: {
+            select: { id: true, name: true, email: true },
+          },
+          creator: {
+            select: { id: true, name: true, email: true },
+          },
+          project: {
+            select: { id: true, name: true, color: true },
+          },
+          subtasks: {
+            include: {
+              assignee: {
+                select: { id: true, name: true, email: true },
+              },
             },
           },
         },
-      },
+      });
     });
 
     if (!task) {
@@ -222,82 +246,89 @@ export class TasksService {
     userId: string,
     updateTaskDto: UpdateTaskDto
   ): Promise<Omit<TaskWithRelations, "subtasks">> {
-    // Verify task exists
-    const existingTask = await this.prisma.task.findUnique({
-      where: { id, workspaceId },
-    });
+    const { task, existingTask } = await this.withWorkspaceContextIfAvailable(
+      workspaceId,
+      userId,
+      async (client) => {
+        const existingTask = await client.task.findUnique({
+          where: { id, workspaceId },
+        });
 
-    if (!existingTask) {
-      throw new NotFoundException(`Task with ID ${id} not found`);
-    }
+        if (!existingTask) {
+          throw new NotFoundException(`Task with ID ${id} not found`);
+        }
 
-    // Build update data - only include defined fields
-    const data: Prisma.TaskUpdateInput = {};
+        // Build update data - only include defined fields
+        const data: Prisma.TaskUpdateInput = {};
 
-    if (updateTaskDto.title !== undefined) {
-      data.title = updateTaskDto.title;
-    }
-    if (updateTaskDto.description !== undefined) {
-      data.description = updateTaskDto.description;
-    }
-    if (updateTaskDto.status !== undefined) {
-      data.status = updateTaskDto.status;
-    }
-    if (updateTaskDto.priority !== undefined) {
-      data.priority = updateTaskDto.priority;
-    }
-    if (updateTaskDto.dueDate !== undefined) {
-      data.dueDate = updateTaskDto.dueDate;
-    }
-    if (updateTaskDto.sortOrder !== undefined) {
-      data.sortOrder = updateTaskDto.sortOrder;
-    }
-    if (updateTaskDto.metadata !== undefined) {
-      data.metadata = updateTaskDto.metadata as unknown as Prisma.InputJsonValue;
-    }
-    if (updateTaskDto.assigneeId !== undefined && updateTaskDto.assigneeId !== null) {
-      data.assignee = { connect: { id: updateTaskDto.assigneeId } };
-    }
-    if (updateTaskDto.projectId !== undefined && updateTaskDto.projectId !== null) {
-      data.project = { connect: { id: updateTaskDto.projectId } };
-    }
-    if (updateTaskDto.parentId !== undefined && updateTaskDto.parentId !== null) {
-      data.parent = { connect: { id: updateTaskDto.parentId } };
-    }
+        if (updateTaskDto.title !== undefined) {
+          data.title = updateTaskDto.title;
+        }
+        if (updateTaskDto.description !== undefined) {
+          data.description = updateTaskDto.description;
+        }
+        if (updateTaskDto.status !== undefined) {
+          data.status = updateTaskDto.status;
+        }
+        if (updateTaskDto.priority !== undefined) {
+          data.priority = updateTaskDto.priority;
+        }
+        if (updateTaskDto.dueDate !== undefined) {
+          data.dueDate = updateTaskDto.dueDate;
+        }
+        if (updateTaskDto.sortOrder !== undefined) {
+          data.sortOrder = updateTaskDto.sortOrder;
+        }
+        if (updateTaskDto.metadata !== undefined) {
+          data.metadata = updateTaskDto.metadata as unknown as Prisma.InputJsonValue;
+        }
+        if (updateTaskDto.assigneeId !== undefined && updateTaskDto.assigneeId !== null) {
+          data.assignee = { connect: { id: updateTaskDto.assigneeId } };
+        }
+        if (updateTaskDto.projectId !== undefined && updateTaskDto.projectId !== null) {
+          data.project = { connect: { id: updateTaskDto.projectId } };
+        }
+        if (updateTaskDto.parentId !== undefined && updateTaskDto.parentId !== null) {
+          data.parent = { connect: { id: updateTaskDto.parentId } };
+        }
 
-    // Handle completedAt based on status changes
-    if (updateTaskDto.status) {
-      if (
-        updateTaskDto.status === TaskStatus.COMPLETED &&
-        existingTask.status !== TaskStatus.COMPLETED
-      ) {
-        data.completedAt = new Date();
-      } else if (
-        updateTaskDto.status !== TaskStatus.COMPLETED &&
-        existingTask.status === TaskStatus.COMPLETED
-      ) {
-        data.completedAt = null;
+        // Handle completedAt based on status changes
+        if (updateTaskDto.status) {
+          if (
+            updateTaskDto.status === TaskStatus.COMPLETED &&
+            existingTask.status !== TaskStatus.COMPLETED
+          ) {
+            data.completedAt = new Date();
+          } else if (
+            updateTaskDto.status !== TaskStatus.COMPLETED &&
+            existingTask.status === TaskStatus.COMPLETED
+          ) {
+            data.completedAt = null;
+          }
+        }
+
+        const task = await client.task.update({
+          where: {
+            id,
+            workspaceId,
+          },
+          data,
+          include: {
+            assignee: {
+              select: { id: true, name: true, email: true },
+            },
+            creator: {
+              select: { id: true, name: true, email: true },
+            },
+            project: {
+              select: { id: true, name: true, color: true },
+            },
+          },
+        });
+
+        return { task, existingTask };
       }
-    }
-
-    const task = await this.prisma.task.update({
-      where: {
-        id,
-        workspaceId,
-      },
-      data,
-      include: {
-        assignee: {
-          select: { id: true, name: true, email: true },
-        },
-        creator: {
-          select: { id: true, name: true, email: true },
-        },
-        project: {
-          select: { id: true, name: true, color: true },
-        },
-      },
-    });
+    );
 
     // Log activities
     await this.activityService.logTaskUpdated(workspaceId, userId, id, {
@@ -332,20 +363,23 @@ export class TasksService {
    * Delete a task
    */
   async remove(id: string, workspaceId: string, userId: string): Promise<void> {
-    // Verify task exists
-    const task = await this.prisma.task.findUnique({
-      where: { id, workspaceId },
-    });
+    const task = await this.withWorkspaceContextIfAvailable(workspaceId, userId, async (client) => {
+      const task = await client.task.findUnique({
+        where: { id, workspaceId },
+      });
 
-    if (!task) {
-      throw new NotFoundException(`Task with ID ${id} not found`);
-    }
+      if (!task) {
+        throw new NotFoundException(`Task with ID ${id} not found`);
+      }
 
-    await this.prisma.task.delete({
-      where: {
-        id,
-        workspaceId,
-      },
+      await client.task.delete({
+        where: {
+          id,
+          workspaceId,
+        },
+      });
+
+      return task;
     });
 
     // Log activity
diff --git a/apps/api/src/telemetry/telemetry.interceptor.spec.ts b/apps/api/src/telemetry/telemetry.interceptor.spec.ts
index 8aadeac..504bb8d 100644
--- a/apps/api/src/telemetry/telemetry.interceptor.spec.ts
+++ b/apps/api/src/telemetry/telemetry.interceptor.spec.ts
@@ -50,6 +50,8 @@ describe("TelemetryInterceptor", () => {
         getResponse: vi.fn().mockReturnValue({
           statusCode: 200,
           setHeader: vi.fn(),
+          headersSent: false,
+          writableEnded: false,
         }),
       }),
       getClass: vi.fn().mockReturnValue({ name: "TestController" }),
@@ -101,6 +103,35 @@ describe("TelemetryInterceptor", () => {
       expect(mockResponse.setHeader).toHaveBeenCalledWith("x-trace-id", "test-trace-id");
     });
 
+    it("should not set trace header when response is already committed", async () => {
+      const committedResponseContext = {
+        ...mockContext,
+        switchToHttp: vi.fn().mockReturnValue({
+          getRequest: vi.fn().mockReturnValue({
+            method: "GET",
+            url: "/api/test",
+            path: "/api/test",
+          }),
+          getResponse: vi.fn().mockReturnValue({
+            statusCode: 200,
+            setHeader: vi.fn(),
+            headersSent: true,
+            writableEnded: true,
+          }),
+        }),
+      } as unknown as ExecutionContext;
+
+      mockHandler = {
+        handle: vi.fn().mockReturnValue(of({ data: "test" })),
+      } as unknown as CallHandler;
+
+      const committedResponse = committedResponseContext.switchToHttp().getResponse();
+
+      await lastValueFrom(interceptor.intercept(committedResponseContext, mockHandler));
+
+      expect(committedResponse.setHeader).not.toHaveBeenCalled();
+    });
+
     it("should record exception on error", async () => {
       const error = new Error("Test error");
       mockHandler = {
diff --git a/apps/api/src/telemetry/telemetry.interceptor.ts b/apps/api/src/telemetry/telemetry.interceptor.ts
index 5f9449e..d85a544 100644
--- a/apps/api/src/telemetry/telemetry.interceptor.ts
+++ b/apps/api/src/telemetry/telemetry.interceptor.ts
@@ -88,7 +88,7 @@ export class TelemetryInterceptor implements NestInterceptor {
 
       // Add trace context to response headers for distributed tracing
       const spanContext = span.spanContext();
-      if (spanContext.traceId) {
+      if (spanContext.traceId && !response.headersSent && !response.writableEnded) {
         response.setHeader("x-trace-id", spanContext.traceId);
       }
     } catch (error) {
diff --git a/apps/coordinator/Dockerfile b/apps/coordinator/Dockerfile
index 04d85a2..c20f1b1 100644
--- a/apps/coordinator/Dockerfile
+++ b/apps/coordinator/Dockerfile
@@ -1,14 +1,10 @@
 # Multi-stage build for mosaic-coordinator
-FROM python:3.11-slim AS builder
+# Builder uses the full Python image which already includes gcc/g++/make,
+# avoiding a 336 MB build-essential install that exceeds Kaniko disk budget.
+FROM python:3.11 AS builder
 
 WORKDIR /app
 
-# Install build dependencies
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends \
-    build-essential \
-    && rm -rf /var/lib/apt/lists/*
-
 # Copy dependency files and private registry config
 COPY pyproject.toml .
 COPY pip.conf /etc/pip.conf
diff --git a/apps/orchestrator/.env.example b/apps/orchestrator/.env.example
index b17fe0d..383b4d3 100644
--- a/apps/orchestrator/.env.example
+++ b/apps/orchestrator/.env.example
@@ -1,6 +1,8 @@
 # Orchestrator Configuration
 ORCHESTRATOR_PORT=3001
 NODE_ENV=development
+# AI provider for orchestrator agents: ollama, claude, openai
+AI_PROVIDER=ollama
 
 # Valkey
 VALKEY_HOST=localhost
@@ -8,6 +10,7 @@ VALKEY_PORT=6379
 VALKEY_URL=redis://localhost:6379
 
 # Claude API
+# Required only when AI_PROVIDER=claude.
 CLAUDE_API_KEY=your-api-key-here
 
 # Docker
diff --git a/apps/orchestrator/Dockerfile b/apps/orchestrator/Dockerfile
index 1ec9d4e..4d0a979 100644
--- a/apps/orchestrator/Dockerfile
+++ b/apps/orchestrator/Dockerfile
@@ -1,6 +1,3 @@
-# syntax=docker/dockerfile:1
-# Enable BuildKit features for cache mounts
-
 # Base image for all stages
 # Uses Debian slim (glibc) instead of Alpine (musl) for native addon compatibility.
 FROM node:24-slim AS base
@@ -26,9 +23,8 @@ COPY packages/config/package.json ./packages/config/
 COPY apps/orchestrator/package.json ./apps/orchestrator/
 
 # Install ALL dependencies (not just production)
-# This ensures NestJS packages and other required deps are available
-RUN --mount=type=cache,id=pnpm-store,target=/root/.local/share/pnpm/store \
-    pnpm install --frozen-lockfile
+# No cache mount — Kaniko builds are ephemeral in CI
+RUN pnpm install --frozen-lockfile
 
 # ======================
 # Builder stage
@@ -69,15 +65,14 @@ LABEL org.opencontainers.image.vendor="Mosaic Stack"
 LABEL org.opencontainers.image.title="Mosaic Orchestrator"
 LABEL org.opencontainers.image.description="Agent orchestration service for Mosaic Stack"
 
-# Remove npm (unused in production — we use pnpm) to reduce attack surface
-RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx
+# Install dumb-init for proper signal handling (static binary from GitHub,
+# avoids apt-get which fails under Kaniko with bookworm GPG signature errors)
+ADD https://github.com/Yelp/dumb-init/releases/download/v1.2.5/dumb-init_1.2.5_x86_64 /usr/local/bin/dumb-init
 
-# Install wget and dumb-init
-RUN apt-get update && apt-get install -y --no-install-recommends wget dumb-init \
-    && rm -rf /var/lib/apt/lists/*
-
-# Create non-root user
-RUN groupadd -g 1001 nodejs && useradd -m -u 1001 -g nodejs nestjs
+# Single RUN to minimize Kaniko filesystem snapshots (each RUN = full snapshot)
+RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx \
+    && chmod 755 /usr/local/bin/dumb-init \
+    && groupadd -g 1001 nodejs && useradd -m -u 1001 -g nodejs nestjs
 
 WORKDIR /app
 
@@ -105,7 +100,7 @@ EXPOSE 3001
 
 # Health check
 HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
-  CMD wget --no-verbose --tries=1 --spider http://localhost:3001/health || exit 1
+  CMD node -e "require('http').get('http://localhost:3001/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"
 
 # Use dumb-init to handle signals properly
 ENTRYPOINT ["dumb-init", "--"]
diff --git a/apps/orchestrator/README.md b/apps/orchestrator/README.md
index 3621f7d..529e3ad 100644
--- a/apps/orchestrator/README.md
+++ b/apps/orchestrator/README.md
@@ -45,12 +45,22 @@ Monitored via `apps/web/` (Agent Dashboard).
 
 ### Agents
 
-| Method | Path                      | Description            |
-| ------ | ------------------------- | ---------------------- |
-| POST   | `/agents/spawn`           | Spawn a new agent      |
-| GET    | `/agents/:agentId/status` | Get agent status       |
-| POST   | `/agents/:agentId/kill`   | Kill a single agent    |
-| POST   | `/agents/kill-all`        | Kill all active agents |
+| Method | Path                      | Description               |
+| ------ | ------------------------- | ------------------------- |
+| POST   | `/agents/spawn`           | Spawn a new agent         |
+| GET    | `/agents/:agentId/status` | Get agent status          |
+| POST   | `/agents/:agentId/kill`   | Kill a single agent       |
+| POST   | `/agents/kill-all`        | Kill all active agents    |
+| GET    | `/agents/events`          | SSE lifecycle/task events |
+| GET    | `/agents/events/recent`   | Recent events (polling)   |
+
+### Queue
+
+| Method | Path            | Description                  |
+| ------ | --------------- | ---------------------------- |
+| GET    | `/queue/stats`  | Queue depth and worker stats |
+| POST   | `/queue/pause`  | Pause queue processing       |
+| POST   | `/queue/resume` | Resume queue processing      |
 
 #### POST /agents/spawn
 
@@ -176,14 +186,18 @@ pnpm --filter @mosaic/orchestrator lint
 
 Environment variables loaded via `@nestjs/config`. Key variables:
 
-| Variable            | Description                            |
-| ------------------- | -------------------------------------- |
-| `ORCHESTRATOR_PORT` | HTTP port (default: 3001)              |
-| `CLAUDE_API_KEY`    | Claude API key for agents              |
-| `VALKEY_HOST`       | Valkey/Redis host (default: localhost) |
-| `VALKEY_PORT`       | Valkey/Redis port (default: 6379)      |
-| `COORDINATOR_URL`   | Quality Coordinator base URL           |
-| `SANDBOX_ENABLED`   | Enable Docker sandbox (true/false)     |
+| Variable                         | Description                                                  |
+| -------------------------------- | ------------------------------------------------------------ |
+| `ORCHESTRATOR_PORT`              | HTTP port (default: 3001)                                    |
+| `AI_PROVIDER`                    | LLM provider for orchestrator (`ollama`, `claude`, `openai`) |
+| `CLAUDE_API_KEY`                 | Required only when `AI_PROVIDER=claude`                      |
+| `VALKEY_HOST`                    | Valkey/Redis host (default: localhost)                       |
+| `VALKEY_PORT`                    | Valkey/Redis port (default: 6379)                            |
+| `COORDINATOR_URL`                | Quality Coordinator base URL                                 |
+| `SANDBOX_ENABLED`                | Enable Docker sandbox (true/false)                           |
+| `MAX_CONCURRENT_AGENTS`          | Maximum concurrent in-memory sessions (default: 2)           |
+| `ORCHESTRATOR_QUEUE_CONCURRENCY` | BullMQ worker concurrency (default: 1)                       |
+| `SANDBOX_DEFAULT_MEMORY_MB`      | Sandbox memory limit in MB (default: 256)                    |
 
 ## Related Documentation
 
diff --git a/apps/orchestrator/SECURITY.md b/apps/orchestrator/SECURITY.md
index 02e719a..d750b18 100644
--- a/apps/orchestrator/SECURITY.md
+++ b/apps/orchestrator/SECURITY.md
@@ -192,7 +192,8 @@ LABEL com.mosaic.security.non-root=true
 
 Sensitive configuration is passed via environment variables:
 
-- `CLAUDE_API_KEY`: Claude API credentials
+- `AI_PROVIDER`: Orchestrator LLM provider
+- `CLAUDE_API_KEY`: Claude credentials (required only for `AI_PROVIDER=claude`)
 - `VALKEY_URL`: Cache connection string
 
 **Best Practices:**
diff --git a/apps/orchestrator/src/api/agents/agent-events.service.ts b/apps/orchestrator/src/api/agents/agent-events.service.ts
new file mode 100644
index 0000000..1941309
--- /dev/null
+++ b/apps/orchestrator/src/api/agents/agent-events.service.ts
@@ -0,0 +1,89 @@
+import { Injectable, Logger, OnModuleInit } from "@nestjs/common";
+import { randomUUID } from "crypto";
+import { ValkeyService } from "../../valkey/valkey.service";
+import type { EventHandler, OrchestratorEvent } from "../../valkey/types";
+
+type UnsubscribeFn = () => void;
+const MAX_RECENT_EVENTS = 500;
+
+@Injectable()
+export class AgentEventsService implements OnModuleInit {
+  private readonly logger = new Logger(AgentEventsService.name);
+  private readonly subscribers = new Map<string, EventHandler>();
+  private readonly recentEvents: OrchestratorEvent[] = [];
+  private connected = false;
+
+  constructor(private readonly valkeyService: ValkeyService) {}
+
+  async onModuleInit(): Promise<void> {
+    if (this.connected) return;
+
+    await this.valkeyService.subscribeToEvents(
+      (event) => {
+        this.appendRecentEvent(event);
+        this.subscribers.forEach((handler) => {
+          void handler(event);
+        });
+      },
+      (error, _raw, channel) => {
+        this.logger.warn(`Event stream parse/validation warning on ${channel}: ${error.message}`);
+      }
+    );
+
+    this.connected = true;
+    this.logger.log("Agent event stream subscription active");
+  }
+
+  subscribe(handler: EventHandler): UnsubscribeFn {
+    const id = randomUUID();
+    this.subscribers.set(id, handler);
+    return () => {
+      this.subscribers.delete(id);
+    };
+  }
+
+  async getInitialSnapshot(): Promise<{
+    type: "stream.snapshot";
+    timestamp: string;
+    agents: number;
+    tasks: number;
+  }> {
+    const [agents, tasks] = await Promise.all([
+      this.valkeyService.listAgents(),
+      this.valkeyService.listTasks(),
+    ]);
+
+    return {
+      type: "stream.snapshot",
+      timestamp: new Date().toISOString(),
+      agents: agents.length,
+      tasks: tasks.length,
+    };
+  }
+
+  createHeartbeat(): OrchestratorEvent {
+    return {
+      type: "task.processing",
+      timestamp: new Date().toISOString(),
+      data: {
+        heartbeat: true,
+      },
+    };
+  }
+
+  getRecentEvents(limit = 100): OrchestratorEvent[] {
+    const safeLimit = Math.min(Math.max(Math.floor(limit), 1), MAX_RECENT_EVENTS);
+    if (safeLimit >= this.recentEvents.length) {
+      return [...this.recentEvents];
+    }
+
+    return this.recentEvents.slice(-safeLimit);
+  }
+
+  private appendRecentEvent(event: OrchestratorEvent): void {
+    this.recentEvents.push(event);
+    if (this.recentEvents.length > MAX_RECENT_EVENTS) {
+      this.recentEvents.shift();
+    }
+  }
+}
diff --git a/apps/orchestrator/src/api/agents/agents-killswitch.controller.spec.ts b/apps/orchestrator/src/api/agents/agents-killswitch.controller.spec.ts
index 9fd7b50..a10fb7e 100644
--- a/apps/orchestrator/src/api/agents/agents-killswitch.controller.spec.ts
+++ b/apps/orchestrator/src/api/agents/agents-killswitch.controller.spec.ts
@@ -4,6 +4,7 @@ import { QueueService } from "../../queue/queue.service";
 import { AgentSpawnerService } from "../../spawner/agent-spawner.service";
 import { AgentLifecycleService } from "../../spawner/agent-lifecycle.service";
 import { KillswitchService } from "../../killswitch/killswitch.service";
+import { AgentEventsService } from "./agent-events.service";
 import type { KillAllResult } from "../../killswitch/killswitch.service";
 
 describe("AgentsController - Killswitch Endpoints", () => {
@@ -20,6 +21,12 @@ describe("AgentsController - Killswitch Endpoints", () => {
   };
   let mockLifecycleService: {
     getAgentLifecycleState: ReturnType<typeof vi.fn>;
+    registerSpawnedAgent: ReturnType<typeof vi.fn>;
+  };
+  let mockEventsService: {
+    subscribe: ReturnType<typeof vi.fn>;
+    getInitialSnapshot: ReturnType<typeof vi.fn>;
+    createHeartbeat: ReturnType<typeof vi.fn>;
   };
 
   beforeEach(() => {
@@ -38,13 +45,30 @@ describe("AgentsController - Killswitch Endpoints", () => {
 
     mockLifecycleService = {
       getAgentLifecycleState: vi.fn(),
+      registerSpawnedAgent: vi.fn(),
+    };
+
+    mockEventsService = {
+      subscribe: vi.fn().mockReturnValue(() => {}),
+      getInitialSnapshot: vi.fn().mockResolvedValue({
+        type: "stream.snapshot",
+        timestamp: new Date().toISOString(),
+        agents: 0,
+        tasks: 0,
+      }),
+      createHeartbeat: vi.fn().mockReturnValue({
+        type: "task.processing",
+        timestamp: new Date().toISOString(),
+        data: { heartbeat: true },
+      }),
     };
 
     controller = new AgentsController(
       mockQueueService as unknown as QueueService,
       mockSpawnerService as unknown as AgentSpawnerService,
       mockLifecycleService as unknown as AgentLifecycleService,
-      mockKillswitchService as unknown as KillswitchService
+      mockKillswitchService as unknown as KillswitchService,
+      mockEventsService as unknown as AgentEventsService
     );
   });
 
diff --git a/apps/orchestrator/src/api/agents/agents.controller.spec.ts b/apps/orchestrator/src/api/agents/agents.controller.spec.ts
index c63f8b6..75393ec 100644
--- a/apps/orchestrator/src/api/agents/agents.controller.spec.ts
+++ b/apps/orchestrator/src/api/agents/agents.controller.spec.ts
@@ -3,6 +3,7 @@ import { QueueService } from "../../queue/queue.service";
 import { AgentSpawnerService } from "../../spawner/agent-spawner.service";
 import { AgentLifecycleService } from "../../spawner/agent-lifecycle.service";
 import { KillswitchService } from "../../killswitch/killswitch.service";
+import { AgentEventsService } from "./agent-events.service";
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 
 describe("AgentsController", () => {
@@ -17,11 +18,18 @@ describe("AgentsController", () => {
   };
   let lifecycleService: {
     getAgentLifecycleState: ReturnType<typeof vi.fn>;
+    registerSpawnedAgent: ReturnType<typeof vi.fn>;
   };
   let killswitchService: {
     killAgent: ReturnType<typeof vi.fn>;
     killAllAgents: ReturnType<typeof vi.fn>;
   };
+  let eventsService: {
+    subscribe: ReturnType<typeof vi.fn>;
+    getInitialSnapshot: ReturnType<typeof vi.fn>;
+    createHeartbeat: ReturnType<typeof vi.fn>;
+    getRecentEvents: ReturnType<typeof vi.fn>;
+  };
 
   beforeEach(() => {
     // Create mock services
@@ -37,6 +45,7 @@ describe("AgentsController", () => {
 
     lifecycleService = {
       getAgentLifecycleState: vi.fn(),
+      registerSpawnedAgent: vi.fn().mockResolvedValue(undefined),
     };
 
     killswitchService = {
@@ -44,12 +53,29 @@ describe("AgentsController", () => {
       killAllAgents: vi.fn(),
     };
 
+    eventsService = {
+      subscribe: vi.fn().mockReturnValue(() => {}),
+      getInitialSnapshot: vi.fn().mockResolvedValue({
+        type: "stream.snapshot",
+        timestamp: new Date().toISOString(),
+        agents: 0,
+        tasks: 0,
+      }),
+      createHeartbeat: vi.fn().mockReturnValue({
+        type: "task.processing",
+        timestamp: new Date().toISOString(),
+        data: { heartbeat: true },
+      }),
+      getRecentEvents: vi.fn().mockReturnValue([]),
+    };
+
     // Create controller with mocked services
     controller = new AgentsController(
       queueService as unknown as QueueService,
       spawnerService as unknown as AgentSpawnerService,
       lifecycleService as unknown as AgentLifecycleService,
-      killswitchService as unknown as KillswitchService
+      killswitchService as unknown as KillswitchService,
+      eventsService as unknown as AgentEventsService
     );
   });
 
@@ -195,6 +221,10 @@ describe("AgentsController", () => {
       expect(queueService.addTask).toHaveBeenCalledWith(validRequest.taskId, validRequest.context, {
         priority: 5,
       });
+      expect(lifecycleService.registerSpawnedAgent).toHaveBeenCalledWith(
+        agentId,
+        validRequest.taskId
+      );
       expect(result).toEqual({
         agentId,
         status: "spawning",
@@ -334,4 +364,39 @@ describe("AgentsController", () => {
       });
     });
   });
+
+  describe("getRecentEvents", () => {
+    it("should return recent events with default limit", () => {
+      eventsService.getRecentEvents.mockReturnValue([
+        {
+          type: "task.completed",
+          timestamp: "2026-02-17T15:00:00.000Z",
+          taskId: "task-123",
+        },
+      ]);
+
+      const result = controller.getRecentEvents();
+
+      expect(eventsService.getRecentEvents).toHaveBeenCalledWith(100);
+      expect(result).toEqual({
+        events: [
+          {
+            type: "task.completed",
+            timestamp: "2026-02-17T15:00:00.000Z",
+            taskId: "task-123",
+          },
+        ],
+      });
+    });
+
+    it("should parse and pass custom limit", () => {
+      controller.getRecentEvents("25");
+      expect(eventsService.getRecentEvents).toHaveBeenCalledWith(25);
+    });
+
+    it("should fallback to default when limit is invalid", () => {
+      controller.getRecentEvents("invalid");
+      expect(eventsService.getRecentEvents).toHaveBeenCalledWith(100);
+    });
+  });
 });
diff --git a/apps/orchestrator/src/api/agents/agents.controller.ts b/apps/orchestrator/src/api/agents/agents.controller.ts
index 1d54ea9..687129e 100644
--- a/apps/orchestrator/src/api/agents/agents.controller.ts
+++ b/apps/orchestrator/src/api/agents/agents.controller.ts
@@ -11,8 +11,12 @@ import {
   HttpCode,
   UseGuards,
   ParseUUIDPipe,
+  Sse,
+  MessageEvent,
+  Query,
 } from "@nestjs/common";
 import { Throttle } from "@nestjs/throttler";
+import { Observable } from "rxjs";
 import { QueueService } from "../../queue/queue.service";
 import { AgentSpawnerService } from "../../spawner/agent-spawner.service";
 import { AgentLifecycleService } from "../../spawner/agent-lifecycle.service";
@@ -20,6 +24,7 @@ import { KillswitchService } from "../../killswitch/killswitch.service";
 import { SpawnAgentDto, SpawnAgentResponseDto } from "./dto/spawn-agent.dto";
 import { OrchestratorApiKeyGuard } from "../../common/guards/api-key.guard";
 import { OrchestratorThrottlerGuard } from "../../common/guards/throttler.guard";
+import { AgentEventsService } from "./agent-events.service";
 
 /**
  * Controller for agent management endpoints
@@ -41,7 +46,8 @@ export class AgentsController {
     private readonly queueService: QueueService,
     private readonly spawnerService: AgentSpawnerService,
     private readonly lifecycleService: AgentLifecycleService,
-    private readonly killswitchService: KillswitchService
+    private readonly killswitchService: KillswitchService,
+    private readonly eventsService: AgentEventsService
   ) {}
 
   /**
@@ -67,6 +73,9 @@ export class AgentsController {
         context: dto.context,
       });
 
+      // Persist initial lifecycle state in Valkey.
+      await this.lifecycleService.registerSpawnedAgent(spawnResponse.agentId, dto.taskId);
+
       // Queue task in Valkey
       await this.queueService.addTask(dto.taskId, dto.context, {
         priority: 5, // Default priority
@@ -85,6 +94,55 @@ export class AgentsController {
     }
   }
 
+  /**
+   * Stream orchestrator events as server-sent events (SSE)
+   */
+  @Sse("events")
+  @Throttle({ status: { limit: 200, ttl: 60000 } })
+  streamEvents(): Observable<MessageEvent> {
+    return new Observable<MessageEvent>((subscriber) => {
+      let isClosed = false;
+
+      const unsubscribe = this.eventsService.subscribe((event) => {
+        if (!isClosed) {
+          subscriber.next({ data: event });
+        }
+      });
+
+      void this.eventsService.getInitialSnapshot().then((snapshot) => {
+        if (!isClosed) {
+          subscriber.next({ data: snapshot });
+        }
+      });
+
+      const heartbeat = setInterval(() => {
+        if (!isClosed) {
+          subscriber.next({ data: this.eventsService.createHeartbeat() });
+        }
+      }, 15000);
+
+      return () => {
+        isClosed = true;
+        clearInterval(heartbeat);
+        unsubscribe();
+      };
+    });
+  }
+
+  /**
+   * Return recent orchestrator events for non-streaming consumers.
+   */
+  @Get("events/recent")
+  @Throttle({ status: { limit: 200, ttl: 60000 } })
+  getRecentEvents(@Query("limit") limit?: string): {
+    events: ReturnType<AgentEventsService["getRecentEvents"]>;
+  } {
+    const parsedLimit = Number.parseInt(limit ?? "100", 10);
+    return {
+      events: this.eventsService.getRecentEvents(Number.isNaN(parsedLimit) ? 100 : parsedLimit),
+    };
+  }
+
   /**
    * List all agents
    * @returns Array of all agent sessions with their status
diff --git a/apps/orchestrator/src/api/agents/agents.module.ts b/apps/orchestrator/src/api/agents/agents.module.ts
index c6e071a..029c3c2 100644
--- a/apps/orchestrator/src/api/agents/agents.module.ts
+++ b/apps/orchestrator/src/api/agents/agents.module.ts
@@ -5,10 +5,11 @@ import { SpawnerModule } from "../../spawner/spawner.module";
 import { KillswitchModule } from "../../killswitch/killswitch.module";
 import { ValkeyModule } from "../../valkey/valkey.module";
 import { OrchestratorApiKeyGuard } from "../../common/guards/api-key.guard";
+import { AgentEventsService } from "./agent-events.service";
 
 @Module({
   imports: [QueueModule, SpawnerModule, KillswitchModule, ValkeyModule],
   controllers: [AgentsController],
-  providers: [OrchestratorApiKeyGuard],
+  providers: [OrchestratorApiKeyGuard, AgentEventsService],
 })
 export class AgentsModule {}
diff --git a/apps/orchestrator/src/api/queue/queue-api.module.ts b/apps/orchestrator/src/api/queue/queue-api.module.ts
new file mode 100644
index 0000000..89e3f10
--- /dev/null
+++ b/apps/orchestrator/src/api/queue/queue-api.module.ts
@@ -0,0 +1,11 @@
+import { Module } from "@nestjs/common";
+import { QueueController } from "./queue.controller";
+import { QueueModule } from "../../queue/queue.module";
+import { OrchestratorApiKeyGuard } from "../../common/guards/api-key.guard";
+
+@Module({
+  imports: [QueueModule],
+  controllers: [QueueController],
+  providers: [OrchestratorApiKeyGuard],
+})
+export class QueueApiModule {}
diff --git a/apps/orchestrator/src/api/queue/queue.controller.spec.ts b/apps/orchestrator/src/api/queue/queue.controller.spec.ts
new file mode 100644
index 0000000..d1a8fc5
--- /dev/null
+++ b/apps/orchestrator/src/api/queue/queue.controller.spec.ts
@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { QueueController } from "./queue.controller";
+import { QueueService } from "../../queue/queue.service";
+
+describe("QueueController", () => {
+  let controller: QueueController;
+  let queueService: {
+    getStats: ReturnType<typeof vi.fn>;
+    pause: ReturnType<typeof vi.fn>;
+    resume: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    queueService = {
+      getStats: vi.fn(),
+      pause: vi.fn(),
+      resume: vi.fn(),
+    };
+
+    controller = new QueueController(queueService as unknown as QueueService);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return queue stats", async () => {
+    queueService.getStats.mockResolvedValue({
+      pending: 5,
+      active: 1,
+      completed: 10,
+      failed: 2,
+      delayed: 0,
+    });
+
+    const result = await controller.getStats();
+
+    expect(queueService.getStats).toHaveBeenCalledOnce();
+    expect(result).toEqual({
+      pending: 5,
+      active: 1,
+      completed: 10,
+      failed: 2,
+      delayed: 0,
+    });
+  });
+
+  it("should pause queue processing", async () => {
+    queueService.pause.mockResolvedValue(undefined);
+
+    const result = await controller.pause();
+
+    expect(queueService.pause).toHaveBeenCalledOnce();
+    expect(result).toEqual({ message: "Queue processing paused" });
+  });
+
+  it("should resume queue processing", async () => {
+    queueService.resume.mockResolvedValue(undefined);
+
+    const result = await controller.resume();
+
+    expect(queueService.resume).toHaveBeenCalledOnce();
+    expect(result).toEqual({ message: "Queue processing resumed" });
+  });
+});
diff --git a/apps/orchestrator/src/api/queue/queue.controller.ts b/apps/orchestrator/src/api/queue/queue.controller.ts
new file mode 100644
index 0000000..85cc986
--- /dev/null
+++ b/apps/orchestrator/src/api/queue/queue.controller.ts
@@ -0,0 +1,39 @@
+import { Controller, Get, HttpCode, Post, UseGuards } from "@nestjs/common";
+import { Throttle } from "@nestjs/throttler";
+import { QueueService } from "../../queue/queue.service";
+import { OrchestratorApiKeyGuard } from "../../common/guards/api-key.guard";
+import { OrchestratorThrottlerGuard } from "../../common/guards/throttler.guard";
+
+@Controller("queue")
+@UseGuards(OrchestratorApiKeyGuard, OrchestratorThrottlerGuard)
+export class QueueController {
+  constructor(private readonly queueService: QueueService) {}
+
+  @Get("stats")
+  @Throttle({ status: { limit: 200, ttl: 60000 } })
+  async getStats(): Promise<{
+    pending: number;
+    active: number;
+    completed: number;
+    failed: number;
+    delayed: number;
+  }> {
+    return this.queueService.getStats();
+  }
+
+  @Post("pause")
+  @Throttle({ strict: { limit: 10, ttl: 60000 } })
+  @HttpCode(200)
+  async pause(): Promise<{ message: string }> {
+    await this.queueService.pause();
+    return { message: "Queue processing paused" };
+  }
+
+  @Post("resume")
+  @Throttle({ strict: { limit: 10, ttl: 60000 } })
+  @HttpCode(200)
+  async resume(): Promise<{ message: string }> {
+    await this.queueService.resume();
+    return { message: "Queue processing resumed" };
+  }
+}
diff --git a/apps/orchestrator/src/app.module.ts b/apps/orchestrator/src/app.module.ts
index bb84567..23c00c1 100644
--- a/apps/orchestrator/src/app.module.ts
+++ b/apps/orchestrator/src/app.module.ts
@@ -1,9 +1,10 @@
 import { Module } from "@nestjs/common";
-import { ConfigModule } from "@nestjs/config";
+import { ConfigModule, ConfigService } from "@nestjs/config";
 import { BullModule } from "@nestjs/bullmq";
 import { ThrottlerModule } from "@nestjs/throttler";
 import { HealthModule } from "./api/health/health.module";
 import { AgentsModule } from "./api/agents/agents.module";
+import { QueueApiModule } from "./api/queue/queue-api.module";
 import { CoordinatorModule } from "./coordinator/coordinator.module";
 import { BudgetModule } from "./budget/budget.module";
 import { CIModule } from "./ci";
@@ -21,11 +22,15 @@ import { orchestratorConfig } from "./config/orchestrator.config";
       isGlobal: true,
       load: [orchestratorConfig],
     }),
-    BullModule.forRoot({
-      connection: {
-        host: process.env.VALKEY_HOST ?? "localhost",
-        port: parseInt(process.env.VALKEY_PORT ?? "6379"),
-      },
+    BullModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService) => ({
+        connection: {
+          host: configService.get<string>("orchestrator.valkey.host", "localhost"),
+          port: configService.get<number>("orchestrator.valkey.port", 6379),
+          password: configService.get<string>("orchestrator.valkey.password"),
+        },
+      }),
     }),
     ThrottlerModule.forRoot([
       {
@@ -46,6 +51,7 @@ import { orchestratorConfig } from "./config/orchestrator.config";
     ]),
     HealthModule,
     AgentsModule,
+    QueueApiModule,
     CoordinatorModule,
     BudgetModule,
     CIModule,
diff --git a/apps/orchestrator/src/config/orchestrator.config.spec.ts b/apps/orchestrator/src/config/orchestrator.config.spec.ts
index 5e9b6b8..c74fc16 100644
--- a/apps/orchestrator/src/config/orchestrator.config.spec.ts
+++ b/apps/orchestrator/src/config/orchestrator.config.spec.ts
@@ -120,6 +120,42 @@ describe("orchestratorConfig", () => {
       expect(config.valkey.port).toBe(6379);
       expect(config.valkey.url).toBe("redis://localhost:6379");
     });
+
+    it("should derive valkey host and port from VALKEY_URL when VALKEY_HOST/VALKEY_PORT are not set", () => {
+      delete process.env.VALKEY_HOST;
+      delete process.env.VALKEY_PORT;
+      process.env.VALKEY_URL = "redis://valkey:6380";
+
+      const config = orchestratorConfig();
+
+      expect(config.valkey.host).toBe("valkey");
+      expect(config.valkey.port).toBe(6380);
+      expect(config.valkey.url).toBe("redis://valkey:6380");
+    });
+
+    it("should derive valkey password from VALKEY_URL when VALKEY_PASSWORD is not set", () => {
+      delete process.env.VALKEY_PASSWORD;
+      delete process.env.VALKEY_HOST;
+      delete process.env.VALKEY_PORT;
+      process.env.VALKEY_URL = "redis://:url-secret@valkey:6379";
+
+      const config = orchestratorConfig();
+
+      expect(config.valkey.password).toBe("url-secret");
+    });
+
+    it("should prefer explicit valkey env vars over VALKEY_URL values", () => {
+      process.env.VALKEY_HOST = "explicit-host";
+      process.env.VALKEY_PORT = "6390";
+      process.env.VALKEY_PASSWORD = "explicit-password";
+      process.env.VALKEY_URL = "redis://:url-secret@valkey:6380";
+
+      const config = orchestratorConfig();
+
+      expect(config.valkey.host).toBe("explicit-host");
+      expect(config.valkey.port).toBe(6390);
+      expect(config.valkey.password).toBe("explicit-password");
+    });
   });
 
   describe("valkey timeout config (SEC-ORCH-28)", () => {
@@ -157,12 +193,12 @@ describe("orchestratorConfig", () => {
   });
 
   describe("spawner config", () => {
-    it("should use default maxConcurrentAgents of 20 when not set", () => {
+    it("should use default maxConcurrentAgents of 2 when not set", () => {
       delete process.env.MAX_CONCURRENT_AGENTS;
 
       const config = orchestratorConfig();
 
-      expect(config.spawner.maxConcurrentAgents).toBe(20);
+      expect(config.spawner.maxConcurrentAgents).toBe(2);
     });
 
     it("should use provided maxConcurrentAgents when MAX_CONCURRENT_AGENTS is set", () => {
@@ -181,4 +217,30 @@ describe("orchestratorConfig", () => {
       expect(config.spawner.maxConcurrentAgents).toBe(10);
     });
   });
+
+  describe("AI provider config", () => {
+    it("should default aiProvider to ollama when unset", () => {
+      delete process.env.AI_PROVIDER;
+
+      const config = orchestratorConfig();
+
+      expect(config.aiProvider).toBe("ollama");
+    });
+
+    it("should normalize AI provider to lowercase", () => {
+      process.env.AI_PROVIDER = "  cLaUdE  ";
+
+      const config = orchestratorConfig();
+
+      expect(config.aiProvider).toBe("claude");
+    });
+
+    it("should fallback unsupported AI provider to ollama", () => {
+      process.env.AI_PROVIDER = "bad-provider";
+
+      const config = orchestratorConfig();
+
+      expect(config.aiProvider).toBe("ollama");
+    });
+  });
 });
diff --git a/apps/orchestrator/src/config/orchestrator.config.ts b/apps/orchestrator/src/config/orchestrator.config.ts
index 66ef1a4..203d088 100644
--- a/apps/orchestrator/src/config/orchestrator.config.ts
+++ b/apps/orchestrator/src/config/orchestrator.config.ts
@@ -1,55 +1,96 @@
 import { registerAs } from "@nestjs/config";
 
-export const orchestratorConfig = registerAs("orchestrator", () => ({
-  host: process.env.HOST ?? process.env.BIND_ADDRESS ?? "127.0.0.1",
-  port: parseInt(process.env.ORCHESTRATOR_PORT ?? "3001", 10),
-  valkey: {
-    host: process.env.VALKEY_HOST ?? "localhost",
-    port: parseInt(process.env.VALKEY_PORT ?? "6379", 10),
-    password: process.env.VALKEY_PASSWORD,
-    url: process.env.VALKEY_URL ?? "redis://localhost:6379",
-    connectTimeout: parseInt(process.env.VALKEY_CONNECT_TIMEOUT_MS ?? "5000", 10),
-    commandTimeout: parseInt(process.env.VALKEY_COMMAND_TIMEOUT_MS ?? "3000", 10),
-  },
-  claude: {
-    apiKey: process.env.CLAUDE_API_KEY,
-  },
-  docker: {
-    socketPath: process.env.DOCKER_SOCKET ?? "/var/run/docker.sock",
-  },
-  git: {
-    userName: process.env.GIT_USER_NAME ?? "Mosaic Orchestrator",
-    userEmail: process.env.GIT_USER_EMAIL ?? "orchestrator@mosaicstack.dev",
-  },
-  killswitch: {
-    enabled: process.env.KILLSWITCH_ENABLED === "true",
-  },
-  sandbox: {
-    enabled: process.env.SANDBOX_ENABLED !== "false",
-    defaultImage: process.env.SANDBOX_DEFAULT_IMAGE ?? "node:20-alpine",
-    defaultMemoryMB: parseInt(process.env.SANDBOX_DEFAULT_MEMORY_MB ?? "512", 10),
-    defaultCpuLimit: parseFloat(process.env.SANDBOX_DEFAULT_CPU_LIMIT ?? "1.0"),
-    networkMode: process.env.SANDBOX_NETWORK_MODE ?? "bridge",
-  },
-  coordinator: {
-    url: process.env.COORDINATOR_URL ?? "http://localhost:8000",
-    timeout: parseInt(process.env.COORDINATOR_TIMEOUT_MS ?? "30000", 10),
-    retries: parseInt(process.env.COORDINATOR_RETRIES ?? "3", 10),
-    apiKey: process.env.COORDINATOR_API_KEY,
-  },
-  yolo: {
-    enabled: process.env.YOLO_MODE === "true",
-  },
-  spawner: {
-    maxConcurrentAgents: parseInt(process.env.MAX_CONCURRENT_AGENTS ?? "20", 10),
-  },
-  queue: {
-    completedRetentionCount: parseInt(process.env.QUEUE_COMPLETED_RETENTION_COUNT ?? "100", 10),
-    completedRetentionAgeSeconds: parseInt(
-      process.env.QUEUE_COMPLETED_RETENTION_AGE_S ?? "3600",
-      10
-    ),
-    failedRetentionCount: parseInt(process.env.QUEUE_FAILED_RETENTION_COUNT ?? "1000", 10),
-    failedRetentionAgeSeconds: parseInt(process.env.QUEUE_FAILED_RETENTION_AGE_S ?? "86400", 10),
-  },
-}));
+const normalizeAiProvider = (): "ollama" | "claude" | "openai" => {
+  const provider = process.env.AI_PROVIDER?.trim().toLowerCase();
+
+  if (!provider) {
+    return "ollama";
+  }
+
+  if (provider !== "ollama" && provider !== "claude" && provider !== "openai") {
+    return "ollama";
+  }
+
+  return provider;
+};
+
+const parseValkeyUrl = (url: string): { host?: string; port?: number; password?: string } => {
+  try {
+    const parsed = new URL(url);
+    const port = parsed.port ? parseInt(parsed.port, 10) : undefined;
+
+    return {
+      host: parsed.hostname || undefined,
+      port: Number.isNaN(port) ? undefined : port,
+      password: parsed.password ? decodeURIComponent(parsed.password) : undefined,
+    };
+  } catch {
+    return {};
+  }
+};
+
+export const orchestratorConfig = registerAs("orchestrator", () => {
+  const valkeyUrl = process.env.VALKEY_URL ?? "redis://localhost:6379";
+  const parsedValkeyUrl = parseValkeyUrl(valkeyUrl);
+
+  return {
+    host: process.env.HOST ?? process.env.BIND_ADDRESS ?? "127.0.0.1",
+    port: parseInt(process.env.ORCHESTRATOR_PORT ?? "3001", 10),
+    valkey: {
+      host: process.env.VALKEY_HOST ?? parsedValkeyUrl.host ?? "localhost",
+      port: parseInt(process.env.VALKEY_PORT ?? String(parsedValkeyUrl.port ?? 6379), 10),
+      password: process.env.VALKEY_PASSWORD ?? parsedValkeyUrl.password,
+      url: valkeyUrl,
+      connectTimeout: parseInt(process.env.VALKEY_CONNECT_TIMEOUT_MS ?? "5000", 10),
+      commandTimeout: parseInt(process.env.VALKEY_COMMAND_TIMEOUT_MS ?? "3000", 10),
+    },
+    claude: {
+      apiKey: process.env.CLAUDE_API_KEY,
+    },
+    aiProvider: normalizeAiProvider(),
+    docker: {
+      socketPath: process.env.DOCKER_SOCKET ?? "/var/run/docker.sock",
+    },
+    git: {
+      userName: process.env.GIT_USER_NAME ?? "Mosaic Orchestrator",
+      userEmail: process.env.GIT_USER_EMAIL ?? "orchestrator@mosaicstack.dev",
+    },
+    killswitch: {
+      enabled: process.env.KILLSWITCH_ENABLED === "true",
+    },
+    sandbox: {
+      enabled: process.env.SANDBOX_ENABLED !== "false",
+      defaultImage: process.env.SANDBOX_DEFAULT_IMAGE ?? "node:20-alpine",
+      defaultMemoryMB: parseInt(process.env.SANDBOX_DEFAULT_MEMORY_MB ?? "256", 10),
+      defaultCpuLimit: parseFloat(process.env.SANDBOX_DEFAULT_CPU_LIMIT ?? "1.0"),
+      networkMode: process.env.SANDBOX_NETWORK_MODE ?? "none",
+    },
+    coordinator: {
+      url: process.env.COORDINATOR_URL ?? "http://localhost:8000",
+      timeout: parseInt(process.env.COORDINATOR_TIMEOUT_MS ?? "30000", 10),
+      retries: parseInt(process.env.COORDINATOR_RETRIES ?? "3", 10),
+      apiKey: process.env.COORDINATOR_API_KEY,
+    },
+    yolo: {
+      enabled: process.env.YOLO_MODE === "true",
+    },
+    spawner: {
+      maxConcurrentAgents: parseInt(process.env.MAX_CONCURRENT_AGENTS ?? "2", 10),
+      sessionCleanupDelayMs: parseInt(process.env.SESSION_CLEANUP_DELAY_MS ?? "30000", 10),
+    },
+    queue: {
+      name: process.env.ORCHESTRATOR_QUEUE_NAME ?? "orchestrator-tasks",
+      maxRetries: parseInt(process.env.ORCHESTRATOR_QUEUE_MAX_RETRIES ?? "3", 10),
+      baseDelay: parseInt(process.env.ORCHESTRATOR_QUEUE_BASE_DELAY_MS ?? "1000", 10),
+      maxDelay: parseInt(process.env.ORCHESTRATOR_QUEUE_MAX_DELAY_MS ?? "60000", 10),
+      concurrency: parseInt(process.env.ORCHESTRATOR_QUEUE_CONCURRENCY ?? "1", 10),
+      completedRetentionCount: parseInt(process.env.QUEUE_COMPLETED_RETENTION_COUNT ?? "100", 10),
+      completedRetentionAgeSeconds: parseInt(
+        process.env.QUEUE_COMPLETED_RETENTION_AGE_S ?? "3600",
+        10
+      ),
+      failedRetentionCount: parseInt(process.env.QUEUE_FAILED_RETENTION_COUNT ?? "1000", 10),
+      failedRetentionAgeSeconds: parseInt(process.env.QUEUE_FAILED_RETENTION_AGE_S ?? "86400", 10),
+    },
+  };
+});
diff --git a/apps/orchestrator/src/queue/queue.module.ts b/apps/orchestrator/src/queue/queue.module.ts
index 95dc52c..3a0132e 100644
--- a/apps/orchestrator/src/queue/queue.module.ts
+++ b/apps/orchestrator/src/queue/queue.module.ts
@@ -2,9 +2,10 @@ import { Module } from "@nestjs/common";
 import { ConfigModule } from "@nestjs/config";
 import { QueueService } from "./queue.service";
 import { ValkeyModule } from "../valkey/valkey.module";
+import { SpawnerModule } from "../spawner/spawner.module";
 
 @Module({
-  imports: [ConfigModule, ValkeyModule],
+  imports: [ConfigModule, ValkeyModule, SpawnerModule],
   providers: [QueueService],
   exports: [QueueService],
 })
diff --git a/apps/orchestrator/src/queue/queue.service.spec.ts b/apps/orchestrator/src/queue/queue.service.spec.ts
index 8174cae..69e1582 100644
--- a/apps/orchestrator/src/queue/queue.service.spec.ts
+++ b/apps/orchestrator/src/queue/queue.service.spec.ts
@@ -991,12 +991,17 @@ describe("QueueService", () => {
         success: true,
         metadata: { attempt: 1 },
       });
-      expect(mockValkeyService.updateTaskStatus).toHaveBeenCalledWith("task-123", "executing");
+      expect(mockValkeyService.updateTaskStatus).toHaveBeenCalledWith(
+        "task-123",
+        "executing",
+        undefined
+      );
       expect(mockValkeyService.publishEvent).toHaveBeenCalledWith({
-        type: "task.processing",
+        type: "task.executing",
         timestamp: expect.any(String),
         taskId: "task-123",
-        data: { attempt: 1 },
+        agentId: undefined,
+        data: { attempt: 1, dispatchedByQueue: true },
       });
     });
 
diff --git a/apps/orchestrator/src/queue/queue.service.ts b/apps/orchestrator/src/queue/queue.service.ts
index 4bfc741..50f0148 100644
--- a/apps/orchestrator/src/queue/queue.service.ts
+++ b/apps/orchestrator/src/queue/queue.service.ts
@@ -1,7 +1,9 @@
-import { Injectable, OnModuleDestroy, OnModuleInit } from "@nestjs/common";
+import { Injectable, OnModuleDestroy, OnModuleInit, Optional, Logger } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { Queue, Worker, Job } from "bullmq";
 import { ValkeyService } from "../valkey/valkey.service";
+import { AgentSpawnerService } from "../spawner/agent-spawner.service";
+import { AgentLifecycleService } from "../spawner/agent-lifecycle.service";
 import type { TaskContext } from "../valkey/types";
 import type {
   QueuedTask,
@@ -16,6 +18,7 @@ import type {
  */
 @Injectable()
 export class QueueService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(QueueService.name);
   private queue!: Queue<QueuedTask>;
   private worker!: Worker<QueuedTask, TaskProcessingResult>;
   private readonly queueName: string;
@@ -23,7 +26,9 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
 
   constructor(
     private readonly valkeyService: ValkeyService,
-    private readonly configService: ConfigService
+    private readonly configService: ConfigService,
+    @Optional() private readonly spawnerService?: AgentSpawnerService,
+    @Optional() private readonly lifecycleService?: AgentLifecycleService
   ) {
     this.queueName = this.configService.get<string>(
       "orchestrator.queue.name",
@@ -132,6 +137,16 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
       context,
     };
 
+    // Ensure task state exists before queue lifecycle updates.
+    const getTaskState = (this.valkeyService as Partial<ValkeyService>).getTaskState;
+    const createTask = (this.valkeyService as Partial<ValkeyService>).createTask;
+    if (typeof getTaskState === "function" && typeof createTask === "function") {
+      const existingTask = await getTaskState.call(this.valkeyService, taskId);
+      if (!existingTask) {
+        await createTask.call(this.valkeyService, taskId, context);
+      }
+    }
+
     // Add to BullMQ queue
     await this.queue.add(taskId, queuedTask, {
       priority: 10 - priority + 1, // BullMQ: lower number = higher priority, so invert
@@ -214,23 +229,35 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
     const { taskId } = job.data;
 
     try {
+      const session = this.spawnerService?.findAgentSessionByTaskId(taskId);
+      const agentId = session?.agentId;
+
+      if (agentId) {
+        if (this.lifecycleService) {
+          await this.lifecycleService.transitionToRunning(agentId);
+        }
+        this.spawnerService?.setSessionState(agentId, "running");
+      }
+
       // Update task state to executing
-      await this.valkeyService.updateTaskStatus(taskId, "executing");
+      await this.valkeyService.updateTaskStatus(taskId, "executing", agentId);
 
       // Publish event
       await this.valkeyService.publishEvent({
-        type: "task.processing",
+        type: "task.executing",
         timestamp: new Date().toISOString(),
         taskId,
-        data: { attempt: job.attemptsMade + 1 },
+        agentId,
+        data: {
+          attempt: job.attemptsMade + 1,
+          dispatchedByQueue: true,
+        },
       });
-
-      // Task processing will be handled by agent spawner
-      // For now, just mark as processing
       return {
         success: true,
         metadata: {
           attempt: job.attemptsMade + 1,
+          ...(agentId && { agentId }),
         },
       };
     } catch (error) {
@@ -270,6 +297,14 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
    * Handle task failure
    */
   private async handleTaskFailure(taskId: string, error: Error): Promise<void> {
+    const session = this.spawnerService?.findAgentSessionByTaskId(taskId);
+    if (session) {
+      this.spawnerService?.setSessionState(session.agentId, "failed", error.message, new Date());
+      if (this.lifecycleService) {
+        await this.lifecycleService.transitionToFailed(session.agentId, error.message);
+      }
+    }
+
     await this.valkeyService.updateTaskStatus(taskId, "failed", undefined, error.message);
 
     await this.valkeyService.publishEvent({
@@ -284,12 +319,25 @@ export class QueueService implements OnModuleInit, OnModuleDestroy {
    * Handle task completion
    */
   private async handleTaskCompletion(taskId: string): Promise<void> {
+    const session = this.spawnerService?.findAgentSessionByTaskId(taskId);
+    if (session) {
+      this.spawnerService?.setSessionState(session.agentId, "completed", undefined, new Date());
+      if (this.lifecycleService) {
+        await this.lifecycleService.transitionToCompleted(session.agentId);
+      }
+    } else {
+      this.logger.warn(
+        `Queue completed task ${taskId} but no session was found; using queue-only completion state`
+      );
+    }
+
     await this.valkeyService.updateTaskStatus(taskId, "completed");
 
     await this.valkeyService.publishEvent({
       type: "task.completed",
       timestamp: new Date().toISOString(),
       taskId,
+      ...(session && { agentId: session.agentId }),
     });
   }
 }
diff --git a/apps/orchestrator/src/spawner/agent-lifecycle.service.ts b/apps/orchestrator/src/spawner/agent-lifecycle.service.ts
index 942cb08..cc9b57c 100644
--- a/apps/orchestrator/src/spawner/agent-lifecycle.service.ts
+++ b/apps/orchestrator/src/spawner/agent-lifecycle.service.ts
@@ -37,6 +37,24 @@ export class AgentLifecycleService {
     this.logger.log("AgentLifecycleService initialized");
   }
 
+  /**
+   * Register a newly spawned agent in persistent state and emit spawned event.
+   */
+  async registerSpawnedAgent(agentId: string, taskId: string): Promise<AgentState> {
+    await this.valkeyService.createAgent(agentId, taskId);
+    const createdState = await this.getAgentState(agentId);
+
+    const event: AgentEvent = {
+      type: "agent.spawned",
+      agentId,
+      taskId,
+      timestamp: new Date().toISOString(),
+    };
+    await this.valkeyService.publishEvent(event);
+
+    return createdState;
+  }
+
   /**
    * Acquire a per-agent mutex to serialize state transitions.
    * Uses promise chaining: each caller chains onto the previous lock,
diff --git a/apps/orchestrator/src/spawner/agent-spawner.service.spec.ts b/apps/orchestrator/src/spawner/agent-spawner.service.spec.ts
index 6cc0ff0..a6fb0de 100644
--- a/apps/orchestrator/src/spawner/agent-spawner.service.spec.ts
+++ b/apps/orchestrator/src/spawner/agent-spawner.service.spec.ts
@@ -12,6 +12,9 @@ describe("AgentSpawnerService", () => {
     // Create mock ConfigService
     mockConfigService = {
       get: vi.fn((key: string) => {
+        if (key === "orchestrator.aiProvider") {
+          return "ollama";
+        }
         if (key === "orchestrator.claude.apiKey") {
           return "test-api-key";
         }
@@ -31,19 +34,80 @@ describe("AgentSpawnerService", () => {
       expect(service).toBeDefined();
     });
 
-    it("should initialize with Claude API key from config", () => {
+    it("should initialize with default AI provider when API key is omitted", () => {
+      const noClaudeConfigService = {
+        get: vi.fn((key: string) => {
+          if (key === "orchestrator.aiProvider") {
+            return "ollama";
+          }
+          if (key === "orchestrator.spawner.maxConcurrentAgents") {
+            return 20;
+          }
+          if (key === "orchestrator.spawner.sessionCleanupDelayMs") {
+            return 30000;
+          }
+          return undefined;
+        }),
+      } as unknown as ConfigService;
+
+      const serviceNoKey = new AgentSpawnerService(noClaudeConfigService);
+      expect(serviceNoKey).toBeDefined();
+    });
+
+    it("should initialize with Claude provider when key is present", () => {
       expect(mockConfigService.get).toHaveBeenCalledWith("orchestrator.claude.apiKey");
     });
 
-    it("should throw error if Claude API key is missing", () => {
+    it("should initialize with CLAUDE provider when API key is present", () => {
+      const claudeConfigService = {
+        get: vi.fn((key: string) => {
+          if (key === "orchestrator.aiProvider") {
+            return "claude";
+          }
+          if (key === "orchestrator.claude.apiKey") {
+            return "test-api-key";
+          }
+          if (key === "orchestrator.spawner.maxConcurrentAgents") {
+            return 20;
+          }
+          return undefined;
+        }),
+      } as unknown as ConfigService;
+
+      const claudeService = new AgentSpawnerService(claudeConfigService);
+      expect(claudeService).toBeDefined();
+    });
+
+    it("should throw error if Claude API key is missing when provider is claude", () => {
       const badConfigService = {
-        get: vi.fn(() => undefined),
+        get: vi.fn((key: string) => {
+          if (key === "orchestrator.aiProvider") {
+            return "claude";
+          }
+          return undefined;
+        }),
       } as unknown as ConfigService;
 
       expect(() => new AgentSpawnerService(badConfigService)).toThrow(
-        "CLAUDE_API_KEY is not configured"
+        "CLAUDE_API_KEY is required when AI_PROVIDER is set to 'claude'"
       );
     });
+
+    it("should still initialize when CLAUDE_API_KEY is missing for non-Claude provider", () => {
+      const nonClaudeConfigService = {
+        get: vi.fn((key: string) => {
+          if (key === "orchestrator.aiProvider") {
+            return "ollama";
+          }
+          if (key === "orchestrator.spawner.maxConcurrentAgents") {
+            return 20;
+          }
+          return undefined;
+        }),
+      } as unknown as ConfigService;
+
+      expect(() => new AgentSpawnerService(nonClaudeConfigService)).not.toThrow();
+    });
   });
 
   describe("spawnAgent", () => {
diff --git a/apps/orchestrator/src/spawner/agent-spawner.service.ts b/apps/orchestrator/src/spawner/agent-spawner.service.ts
index e3ce4ba..c91971a 100644
--- a/apps/orchestrator/src/spawner/agent-spawner.service.ts
+++ b/apps/orchestrator/src/spawner/agent-spawner.service.ts
@@ -14,6 +14,8 @@ import {
  * This allows time for status queries before the session is removed
  */
 const DEFAULT_SESSION_CLEANUP_DELAY_MS = 30000; // 30 seconds
+const SUPPORTED_AI_PROVIDERS = ["ollama", "claude", "openai"] as const;
+type SupportedAiProvider = (typeof SUPPORTED_AI_PROVIDERS)[number];
 
 /**
  * Service responsible for spawning Claude agents using Anthropic SDK
@@ -21,22 +23,38 @@ const DEFAULT_SESSION_CLEANUP_DELAY_MS = 30000; // 30 seconds
 @Injectable()
 export class AgentSpawnerService implements OnModuleDestroy {
   private readonly logger = new Logger(AgentSpawnerService.name);
-  private readonly anthropic: Anthropic;
+  private readonly anthropic: Anthropic | undefined;
+  private readonly aiProvider: SupportedAiProvider;
   private readonly sessions = new Map<string, AgentSession>();
   private readonly maxConcurrentAgents: number;
   private readonly sessionCleanupDelayMs: number;
   private readonly cleanupTimers = new Map<string, NodeJS.Timeout>();
 
   constructor(private readonly configService: ConfigService) {
+    const configuredProvider = this.configService.get<string>("orchestrator.aiProvider");
+    this.aiProvider = this.normalizeAiProvider(configuredProvider);
+
+    this.logger.log(`AgentSpawnerService resolved AI provider: ${this.aiProvider}`);
+
     const apiKey = this.configService.get<string>("orchestrator.claude.apiKey");
 
-    if (!apiKey) {
-      throw new Error("CLAUDE_API_KEY is not configured");
-    }
+    if (this.aiProvider === "claude") {
+      if (!apiKey) {
+        throw new Error("CLAUDE_API_KEY is required when AI_PROVIDER is set to 'claude'");
+      }
 
-    this.anthropic = new Anthropic({
-      apiKey,
-    });
+      this.logger.log("CLAUDE_API_KEY is configured. Initializing Anthropic client.");
+      this.anthropic = new Anthropic({ apiKey });
+    } else {
+      if (apiKey) {
+        this.logger.debug(
+          `CLAUDE_API_KEY is set but ignored because AI provider is '${this.aiProvider}'`
+        );
+      } else {
+        this.logger.log(`CLAUDE_API_KEY not required for AI provider '${this.aiProvider}'.`);
+      }
+      this.anthropic = undefined;
+    }
 
     // Default to 20 if not configured
     this.maxConcurrentAgents =
@@ -48,10 +66,27 @@ export class AgentSpawnerService implements OnModuleDestroy {
       DEFAULT_SESSION_CLEANUP_DELAY_MS;
 
     this.logger.log(
-      `AgentSpawnerService initialized with Claude SDK (max concurrent agents: ${String(this.maxConcurrentAgents)}, cleanup delay: ${String(this.sessionCleanupDelayMs)}ms)`
+      `AgentSpawnerService initialized with ${this.aiProvider} AI provider (max concurrent agents: ${String(
+        this.maxConcurrentAgents
+      )}, cleanup delay: ${String(this.sessionCleanupDelayMs)}ms)`
     );
   }
 
+  private normalizeAiProvider(provider?: string): SupportedAiProvider {
+    const normalizedProvider = provider?.trim().toLowerCase();
+
+    if (!normalizedProvider) {
+      return "ollama";
+    }
+
+    if (!SUPPORTED_AI_PROVIDERS.includes(normalizedProvider as SupportedAiProvider)) {
+      this.logger.warn(`Unsupported AI provider '${normalizedProvider}'. Defaulting to 'ollama'.`);
+      return "ollama";
+    }
+
+    return normalizedProvider as SupportedAiProvider;
+  }
+
   /**
    * Clean up all pending cleanup timers on module destroy
    */
@@ -116,6 +151,33 @@ export class AgentSpawnerService implements OnModuleDestroy {
     return this.sessions.get(agentId);
   }
 
+  /**
+   * Find an active session by task ID.
+   */
+  findAgentSessionByTaskId(taskId: string): AgentSession | undefined {
+    return Array.from(this.sessions.values()).find((session) => session.taskId === taskId);
+  }
+
+  /**
+   * Update in-memory session state for visibility in list/status endpoints.
+   */
+  setSessionState(
+    agentId: string,
+    state: AgentSession["state"],
+    error?: string,
+    completedAt?: Date
+  ): void {
+    const session = this.sessions.get(agentId);
+    if (!session) return;
+
+    session.state = state;
+    session.error = error;
+    if (completedAt) {
+      session.completedAt = completedAt;
+    }
+    this.sessions.set(agentId, session);
+  }
+
   /**
    * List all agent sessions
    * @returns Array of all agent sessions
diff --git a/apps/web/Dockerfile b/apps/web/Dockerfile
index 7caec12..740edd6 100644
--- a/apps/web/Dockerfile
+++ b/apps/web/Dockerfile
@@ -1,6 +1,3 @@
-# syntax=docker/dockerfile:1
-# Enable BuildKit features for cache mounts
-
 # Base image for all stages
 # Uses Debian slim (glibc) for consistency with API/orchestrator and to prevent
 # future native addon compatibility issues with Alpine's musl libc.
@@ -27,9 +24,22 @@ COPY packages/ui/package.json ./packages/ui/
 COPY packages/config/package.json ./packages/config/
 COPY apps/web/package.json ./apps/web/
 
-# Install dependencies with pnpm store cache
-RUN --mount=type=cache,id=pnpm-store,target=/root/.local/share/pnpm/store \
-    pnpm install --frozen-lockfile
+# Install dependencies (no cache mount — Kaniko builds are ephemeral in CI)
+RUN pnpm install --frozen-lockfile
+
+# ======================
+# Production dependencies stage
+# ======================
+FROM base AS prod-deps
+
+# Copy all package.json files for workspace resolution
+COPY packages/shared/package.json ./packages/shared/
+COPY packages/ui/package.json ./packages/ui/
+COPY packages/config/package.json ./packages/config/
+COPY apps/web/package.json ./apps/web/
+
+# Install production dependencies only
+RUN pnpm install --frozen-lockfile --prod
 
 # ======================
 # Builder stage
@@ -79,23 +89,19 @@ RUN mkdir -p ./apps/web/public
 # ======================
 FROM node:24-slim AS production
 
-# Remove npm (unused in production — we use pnpm) to reduce attack surface
-RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx
+# Install dumb-init for proper signal handling (static binary from GitHub,
+# avoids apt-get which fails under Kaniko with bookworm GPG signature errors)
+ADD https://github.com/Yelp/dumb-init/releases/download/v1.2.5/dumb-init_1.2.5_x86_64 /usr/local/bin/dumb-init
 
-# Install pnpm (needed for pnpm start command)
-RUN corepack enable && corepack prepare pnpm@10.27.0 --activate
-
-# Install dumb-init for proper signal handling
-RUN apt-get update && apt-get install -y --no-install-recommends dumb-init \
-    && rm -rf /var/lib/apt/lists/*
-
-# Create non-root user
-RUN groupadd -g 1001 nodejs && useradd -m -u 1001 -g nodejs nextjs
+# Single RUN to minimize Kaniko filesystem snapshots (each RUN = full snapshot)
+RUN rm -rf /usr/local/lib/node_modules/npm /usr/local/bin/npm /usr/local/bin/npx \
+    && chmod 755 /usr/local/bin/dumb-init \
+    && groupadd -g 1001 nodejs && useradd -m -u 1001 -g nodejs nextjs
 
 WORKDIR /app
 
 # Copy node_modules from builder (includes all dependencies in pnpm store)
-COPY --from=builder --chown=nextjs:nodejs /app/node_modules ./node_modules
+COPY --from=prod-deps --chown=nextjs:nodejs /app/node_modules ./node_modules
 
 # Copy built packages (includes dist/ directories)
 COPY --from=builder --chown=nextjs:nodejs /app/packages ./packages
@@ -106,7 +112,7 @@ COPY --from=builder --chown=nextjs:nodejs /app/apps/web/public ./apps/web/public
 COPY --from=builder --chown=nextjs:nodejs /app/apps/web/next.config.ts ./apps/web/
 COPY --from=builder --chown=nextjs:nodejs /app/apps/web/package.json ./apps/web/
 # Copy app's node_modules which contains symlinks to root node_modules
-COPY --from=builder --chown=nextjs:nodejs /app/apps/web/node_modules ./apps/web/node_modules
+COPY --from=prod-deps --chown=nextjs:nodejs /app/apps/web/node_modules ./apps/web/node_modules
 
 # Set working directory to web app
 WORKDIR /app/apps/web
@@ -120,6 +126,7 @@ EXPOSE ${PORT:-3000}
 # Environment variables
 ENV NODE_ENV=production
 ENV HOSTNAME="0.0.0.0"
+ENV PATH="/app/apps/web/node_modules/.bin:${PATH}"
 
 # Health check uses PORT env var (set by docker-compose or defaults to 3000)
 HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
@@ -129,4 +136,4 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
 ENTRYPOINT ["dumb-init", "--"]
 
 # Start the application
-CMD ["pnpm", "start"]
+CMD ["next", "start"]
diff --git a/apps/web/next-env.d.ts b/apps/web/next-env.d.ts
index 9edff1c..c4b7818 100644
--- a/apps/web/next-env.d.ts
+++ b/apps/web/next-env.d.ts
@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/apps/web/next.config.ts b/apps/web/next.config.ts
index c7682de..424f3a9 100644
--- a/apps/web/next.config.ts
+++ b/apps/web/next.config.ts
@@ -1,5 +1,16 @@
 import type { NextConfig } from "next";
 
+const defaultAuthMode = process.env.NODE_ENV === "development" ? "mock" : "real";
+const authMode = (process.env.NEXT_PUBLIC_AUTH_MODE ?? defaultAuthMode).toLowerCase();
+
+if (!["real", "mock"].includes(authMode)) {
+  throw new Error(`Invalid NEXT_PUBLIC_AUTH_MODE "${authMode}". Expected one of: real, mock.`);
+}
+
+if (authMode === "mock" && process.env.NODE_ENV !== "development") {
+  throw new Error("NEXT_PUBLIC_AUTH_MODE=mock is only allowed for local development.");
+}
+
 const nextConfig: NextConfig = {
   transpilePackages: ["@mosaic/ui", "@mosaic/shared"],
 };
diff --git a/apps/web/src/app/(auth)/login/page.mock-mode.test.tsx b/apps/web/src/app/(auth)/login/page.mock-mode.test.tsx
new file mode 100644
index 0000000..f1f3ced
--- /dev/null
+++ b/apps/web/src/app/(auth)/login/page.mock-mode.test.tsx
@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach, type Mock } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import LoginPage from "./page";
+
+const { mockPush, mockReplace, mockSearchParams, authState } = vi.hoisted(() => ({
+  mockPush: vi.fn(),
+  mockReplace: vi.fn(),
+  mockSearchParams: new URLSearchParams(),
+  authState: {
+    isAuthenticated: false,
+    refreshSession: vi.fn(),
+  },
+}));
+
+const { mockFetchWithRetry } = vi.hoisted(() => ({
+  mockFetchWithRetry: vi.fn(),
+}));
+
+vi.mock("next/navigation", () => ({
+  useRouter: (): { push: Mock; replace: Mock } => ({
+    push: mockPush,
+    replace: mockReplace,
+  }),
+  useSearchParams: (): URLSearchParams => mockSearchParams,
+}));
+
+vi.mock("@/lib/config", () => ({
+  API_BASE_URL: "http://localhost:3001",
+  IS_MOCK_AUTH_MODE: true,
+}));
+
+vi.mock("@/lib/auth-client", () => ({
+  signIn: {
+    oauth2: vi.fn(),
+    email: vi.fn(),
+  },
+}));
+
+vi.mock("@/lib/auth/auth-context", () => ({
+  useAuth: (): { isAuthenticated: boolean; refreshSession: Mock } => ({
+    isAuthenticated: authState.isAuthenticated,
+    refreshSession: authState.refreshSession,
+  }),
+}));
+
+vi.mock("@/lib/auth/fetch-with-retry", () => ({
+  fetchWithRetry: mockFetchWithRetry,
+}));
+
+describe("LoginPage (mock auth mode)", (): void => {
+  beforeEach((): void => {
+    vi.clearAllMocks();
+    mockSearchParams.delete("error");
+    authState.isAuthenticated = false;
+    authState.refreshSession.mockResolvedValue(undefined);
+  });
+
+  it("should render mock auth controls", (): void => {
+    render(<LoginPage />);
+
+    expect(screen.getByText(/local mock auth mode is active/i)).toBeInTheDocument();
+    expect(screen.getByTestId("mock-auth-login")).toBeInTheDocument();
+    expect(mockFetchWithRetry).not.toHaveBeenCalled();
+  });
+
+  it("should continue with mock session and navigate to tasks", async (): Promise<void> => {
+    const user = userEvent.setup();
+    render(<LoginPage />);
+
+    await user.click(screen.getByTestId("mock-auth-login"));
+
+    await waitFor(() => {
+      expect(authState.refreshSession).toHaveBeenCalledTimes(1);
+      expect(mockPush).toHaveBeenCalledWith("/tasks");
+    });
+  });
+
+  it("should auto-redirect authenticated mock users to tasks", async (): Promise<void> => {
+    authState.isAuthenticated = true;
+    render(<LoginPage />);
+
+    await waitFor(() => {
+      expect(mockReplace).toHaveBeenCalledWith("/tasks");
+    });
+  });
+});
diff --git a/apps/web/src/app/(auth)/login/page.test.tsx b/apps/web/src/app/(auth)/login/page.test.tsx
index dc75f8b..f88ec68 100644
--- a/apps/web/src/app/(auth)/login/page.test.tsx
+++ b/apps/web/src/app/(auth)/login/page.test.tsx
@@ -16,6 +16,11 @@ const { mockOAuth2, mockSignInEmail, mockPush, mockReplace, mockSearchParams } =
   mockSearchParams: new URLSearchParams(),
 }));
 
+const { mockRefreshSession, mockIsAuthenticated } = vi.hoisted(() => ({
+  mockRefreshSession: vi.fn(),
+  mockIsAuthenticated: false,
+}));
+
 vi.mock("next/navigation", () => ({
   useRouter: (): { push: Mock; replace: Mock } => ({
     push: mockPush,
@@ -33,6 +38,14 @@ vi.mock("@/lib/auth-client", () => ({
 
 vi.mock("@/lib/config", () => ({
   API_BASE_URL: "http://localhost:3001",
+  IS_MOCK_AUTH_MODE: false,
+}));
+
+vi.mock("@/lib/auth/auth-context", () => ({
+  useAuth: (): { isAuthenticated: boolean; refreshSession: Mock } => ({
+    isAuthenticated: mockIsAuthenticated,
+    refreshSession: mockRefreshSession,
+  }),
 }));
 
 // Mock fetchWithRetry to behave like fetch for test purposes
@@ -91,6 +104,7 @@ describe("LoginPage", (): void => {
     mockSearchParams.delete("error");
     // Default: OAuth2 returns a resolved promise (fire-and-forget redirect)
     mockOAuth2.mockResolvedValue(undefined);
+    mockRefreshSession.mockResolvedValue(undefined);
   });
 
   it("renders loading state initially", (): void => {
@@ -104,19 +118,28 @@ describe("LoginPage", (): void => {
     expect(screen.getByText("Loading authentication options")).toBeInTheDocument();
   });
 
-  it("renders the page heading and description", (): void => {
+  it("renders the page heading and description", async (): Promise<void> => {
     mockFetchConfig(EMAIL_ONLY_CONFIG);
 
     render(<LoginPage />);
 
+    await waitFor((): void => {
+      expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+    });
+
     expect(screen.getByRole("heading", { level: 1 })).toHaveTextContent("Welcome to Mosaic Stack");
     expect(screen.getByText(/Your personal assistant platform/i)).toBeInTheDocument();
   });
 
-  it("has proper layout styling", (): void => {
+  it("has proper layout styling", async (): Promise<void> => {
     mockFetchConfig(EMAIL_ONLY_CONFIG);
 
     const { container } = render(<LoginPage />);
+
+    await waitFor((): void => {
+      expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+    });
+
     const main = container.querySelector("main");
     expect(main).toHaveClass("flex", "min-h-screen");
   });
@@ -267,7 +290,7 @@ describe("LoginPage", (): void => {
 
     expect(mockOAuth2).toHaveBeenCalledWith({
       providerId: "authentik",
-      callbackURL: "/",
+      callbackURL: "http://localhost:3000/",
     });
   });
 
@@ -430,37 +453,56 @@ describe("LoginPage", (): void => {
   /* ------------------------------------------------------------------ */
 
   describe("responsive layout", (): void => {
-    it("applies mobile-first padding to main element", (): void => {
+    it("applies mobile-first padding to main element", async (): Promise<void> => {
       mockFetchConfig(EMAIL_ONLY_CONFIG);
 
       const { container } = render(<LoginPage />);
+
+      await waitFor((): void => {
+        expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+      });
+
       const main = container.querySelector("main");
 
       expect(main).toHaveClass("p-4", "sm:p-8");
     });
 
-    it("applies responsive text size to heading", (): void => {
+    it("applies responsive text size to heading", async (): Promise<void> => {
       mockFetchConfig(EMAIL_ONLY_CONFIG);
 
       render(<LoginPage />);
 
+      await waitFor((): void => {
+        expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+      });
+
       const heading = screen.getByRole("heading", { level: 1 });
       expect(heading).toHaveClass("text-2xl", "sm:text-4xl");
     });
 
-    it("applies responsive padding to card container", (): void => {
+    it("applies responsive padding to card container", async (): Promise<void> => {
       mockFetchConfig(EMAIL_ONLY_CONFIG);
 
       const { container } = render(<LoginPage />);
+
+      await waitFor((): void => {
+        expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+      });
+
       const card = container.querySelector(".bg-white");
 
       expect(card).toHaveClass("p-4", "sm:p-8");
     });
 
-    it("card container has full width with max-width constraint", (): void => {
+    it("card container has full width with max-width constraint", async (): Promise<void> => {
       mockFetchConfig(EMAIL_ONLY_CONFIG);
 
       const { container } = render(<LoginPage />);
+
+      await waitFor((): void => {
+        expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
+      });
+
       const wrapper = container.querySelector(".max-w-md");
 
       expect(wrapper).toHaveClass("w-full", "max-w-md");
@@ -539,7 +581,9 @@ describe("LoginPage", (): void => {
       });
 
       // LoginForm auto-focuses the email input on mount
-      expect(screen.getByLabelText(/email/i)).toHaveFocus();
+      await waitFor((): void => {
+        expect(screen.getByLabelText(/email/i)).toHaveFocus();
+      });
 
       // Tab forward through form: email -> password -> submit
       await user.tab();
diff --git a/apps/web/src/app/(auth)/login/page.tsx b/apps/web/src/app/(auth)/login/page.tsx
index 1565d8d..4a58376 100644
--- a/apps/web/src/app/(auth)/login/page.tsx
+++ b/apps/web/src/app/(auth)/login/page.tsx
@@ -5,10 +5,11 @@ import type { ReactElement } from "react";
 import { useRouter, useSearchParams } from "next/navigation";
 import { Loader2 } from "lucide-react";
 import type { AuthConfigResponse, AuthProviderConfig } from "@mosaic/shared";
-import { API_BASE_URL } from "@/lib/config";
+import { API_BASE_URL, IS_MOCK_AUTH_MODE } from "@/lib/config";
 import { signIn } from "@/lib/auth-client";
 import { fetchWithRetry } from "@/lib/auth/fetch-with-retry";
 import { parseAuthError } from "@/lib/auth/auth-errors";
+import { useAuth } from "@/lib/auth/auth-context";
 import { OAuthButton } from "@/components/auth/OAuthButton";
 import { LoginForm } from "@/components/auth/LoginForm";
 import { AuthDivider } from "@/components/auth/AuthDivider";
@@ -45,6 +46,7 @@ export default function LoginPage(): ReactElement {
 function LoginPageContent(): ReactElement {
   const router = useRouter();
   const searchParams = useSearchParams();
+  const { isAuthenticated, refreshSession } = useAuth();
   const [config, setConfig] = useState<AuthConfigResponse | null | undefined>(undefined);
   const [loadingConfig, setLoadingConfig] = useState(true);
   const [retryCount, setRetryCount] = useState(0);
@@ -68,6 +70,18 @@ function LoginPageContent(): ReactElement {
   }, [searchParams, router]);
 
   useEffect(() => {
+    if (IS_MOCK_AUTH_MODE && isAuthenticated) {
+      router.replace("/tasks");
+    }
+  }, [isAuthenticated, router]);
+
+  useEffect(() => {
+    if (IS_MOCK_AUTH_MODE) {
+      setConfig({ providers: [] });
+      setLoadingConfig(false);
+      return;
+    }
+
     let cancelled = false;
 
     async function fetchConfig(): Promise<void> {
@@ -113,7 +127,9 @@ function LoginPageContent(): ReactElement {
   const handleOAuthLogin = useCallback((providerId: string): void => {
     setOauthLoading(providerId);
     setError(null);
-    signIn.oauth2({ providerId, callbackURL: "/" }).catch((err: unknown) => {
+    const callbackURL =
+      typeof window !== "undefined" ? new URL("/", window.location.origin).toString() : "/";
+    signIn.oauth2({ providerId, callbackURL }).catch((err: unknown) => {
       const message = err instanceof Error ? err.message : String(err);
       console.error(`[Auth] OAuth sign-in initiation failed for ${providerId}:`, message);
       setError("Unable to connect to the sign-in provider. Please try again in a moment.");
@@ -156,6 +172,48 @@ function LoginPageContent(): ReactElement {
     setRetryCount((c) => c + 1);
   }, []);
 
+  const handleMockLogin = useCallback(async (): Promise<void> => {
+    setError(null);
+    try {
+      await refreshSession();
+      router.push("/tasks");
+    } catch (err: unknown) {
+      const parsed = parseAuthError(err);
+      setError(parsed.message);
+    }
+  }, [refreshSession, router]);
+
+  if (IS_MOCK_AUTH_MODE) {
+    return (
+      <main className="flex min-h-screen flex-col items-center justify-center p-4 sm:p-8 bg-gray-50">
+        <div className="w-full max-w-md space-y-8">
+          <div className="text-center">
+            <h1 className="text-2xl sm:text-4xl font-bold mb-4">Welcome to Mosaic Stack</h1>
+            <p className="text-base sm:text-lg text-gray-600">
+              Local mock auth mode is active. Real sign-in is bypassed for frontend development.
+            </p>
+          </div>
+          <div className="bg-white p-4 sm:p-8 rounded-lg shadow-md space-y-4">
+            <div className="rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-900">
+              Mock auth mode is local-only and blocked outside development.
+            </div>
+            {error && <AuthErrorBanner message={error} />}
+            <button
+              type="button"
+              onClick={() => {
+                void handleMockLogin();
+              }}
+              className="w-full rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 transition-colors"
+              data-testid="mock-auth-login"
+            >
+              Continue with Mock Session
+            </button>
+          </div>
+        </div>
+      </main>
+    );
+  }
+
   return (
     <main className="flex min-h-screen flex-col items-center justify-center p-4 sm:p-8 bg-gray-50">
       <div className="w-full max-w-md space-y-8">
diff --git a/apps/web/src/app/(authenticated)/layout.tsx b/apps/web/src/app/(authenticated)/layout.tsx
index ea3f8fd..2580c03 100644
--- a/apps/web/src/app/(authenticated)/layout.tsx
+++ b/apps/web/src/app/(authenticated)/layout.tsx
@@ -3,6 +3,7 @@
 import { useEffect } from "react";
 import { useRouter } from "next/navigation";
 import { useAuth } from "@/lib/auth/auth-context";
+import { IS_MOCK_AUTH_MODE } from "@/lib/config";
 import { Navigation } from "@/components/layout/Navigation";
 import { ChatOverlay } from "@/components/chat";
 import type { ReactNode } from "react";
@@ -36,8 +37,18 @@ export default function AuthenticatedLayout({
   return (
     <div className="min-h-screen bg-gray-50">
       <Navigation />
-      <div className="pt-16">{children}</div>
-      <ChatOverlay />
+      <div className="pt-16">
+        {IS_MOCK_AUTH_MODE && (
+          <div
+            className="border-b border-amber-300 bg-amber-50 px-4 py-2 text-sm text-amber-900"
+            data-testid="mock-auth-banner"
+          >
+            Mock Auth Mode (Local Only): Real authentication is bypassed for frontend development.
+          </div>
+        )}
+        {children}
+      </div>
+      {!IS_MOCK_AUTH_MODE && <ChatOverlay />}
     </div>
   );
 }
diff --git a/apps/web/src/app/(authenticated)/usage/page.test.tsx b/apps/web/src/app/(authenticated)/usage/page.test.tsx
index 4d97ff6..c136ffb 100644
--- a/apps/web/src/app/(authenticated)/usage/page.test.tsx
+++ b/apps/web/src/app/(authenticated)/usage/page.test.tsx
@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render, screen, waitFor, fireEvent } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import type { ReactNode } from "react";
 import UsagePage from "./page";
 
@@ -113,6 +114,15 @@ function setupMocks(overrides?: { empty?: boolean; error?: boolean }): void {
   vi.mocked(fetchTaskOutcomes).mockResolvedValue(mockTaskOutcomes);
 }
 
+function setupPendingMocks(): void {
+  // eslint-disable-next-line @typescript-eslint/no-empty-function -- intentionally unresolved for loading-state test
+  const pending = new Promise<never>(() => {});
+  vi.mocked(fetchUsageSummary).mockReturnValue(pending);
+  vi.mocked(fetchTokenUsage).mockReturnValue(pending);
+  vi.mocked(fetchCostBreakdown).mockReturnValue(pending);
+  vi.mocked(fetchTaskOutcomes).mockReturnValue(pending);
+}
+
 // ─── Tests ───────────────────────────────────────────────────────────
 
 describe("UsagePage", (): void => {
@@ -120,23 +130,32 @@ describe("UsagePage", (): void => {
     vi.clearAllMocks();
   });
 
-  it("should render the page title and subtitle", (): void => {
+  it("should render the page title and subtitle", async (): Promise<void> => {
     setupMocks();
     render(<UsagePage />);
 
+    await waitFor((): void => {
+      expect(screen.getByTestId("summary-cards")).toBeInTheDocument();
+    });
+
     expect(screen.getByRole("heading", { level: 1 })).toHaveTextContent("Usage");
     expect(screen.getByText("Token usage and cost overview")).toBeInTheDocument();
   });
 
-  it("should have proper layout structure", (): void => {
+  it("should have proper layout structure", async (): Promise<void> => {
     setupMocks();
     const { container } = render(<UsagePage />);
+
+    await waitFor((): void => {
+      expect(screen.getByTestId("summary-cards")).toBeInTheDocument();
+    });
+
     const main = container.querySelector("main");
     expect(main).toBeInTheDocument();
   });
 
   it("should show loading skeleton initially", (): void => {
-    setupMocks();
+    setupPendingMocks();
     render(<UsagePage />);
     expect(screen.getByTestId("loading-skeleton")).toBeInTheDocument();
   });
@@ -171,25 +190,34 @@ describe("UsagePage", (): void => {
     });
   });
 
-  it("should render the time range selector with three options", (): void => {
+  it("should render the time range selector with three options", async (): Promise<void> => {
     setupMocks();
     render(<UsagePage />);
 
+    await waitFor((): void => {
+      expect(screen.getByTestId("summary-cards")).toBeInTheDocument();
+    });
+
     expect(screen.getByText("7 Days")).toBeInTheDocument();
     expect(screen.getByText("30 Days")).toBeInTheDocument();
     expect(screen.getByText("90 Days")).toBeInTheDocument();
   });
 
-  it("should have 30 Days selected by default", (): void => {
+  it("should have 30 Days selected by default", async (): Promise<void> => {
     setupMocks();
     render(<UsagePage />);
 
+    await waitFor((): void => {
+      expect(screen.getByTestId("summary-cards")).toBeInTheDocument();
+    });
+
     const button30d = screen.getByText("30 Days");
     expect(button30d).toHaveAttribute("aria-pressed", "true");
   });
 
   it("should change time range when a different option is clicked", async (): Promise<void> => {
     setupMocks();
+    const user = userEvent.setup();
     render(<UsagePage />);
 
     // Wait for initial load
@@ -199,7 +227,11 @@ describe("UsagePage", (): void => {
 
     // Click 7 Days
     const button7d = screen.getByText("7 Days");
-    fireEvent.click(button7d);
+    await user.click(button7d);
+
+    await waitFor((): void => {
+      expect(fetchUsageSummary).toHaveBeenCalledWith("7d");
+    });
 
     expect(button7d).toHaveAttribute("aria-pressed", "true");
     expect(screen.getByText("30 Days")).toHaveAttribute("aria-pressed", "false");
diff --git a/apps/web/src/app/api/orchestrator/agents/route.ts b/apps/web/src/app/api/orchestrator/agents/route.ts
new file mode 100644
index 0000000..3bd8901
--- /dev/null
+++ b/apps/web/src/app/api/orchestrator/agents/route.ts
@@ -0,0 +1,59 @@
+import { NextResponse } from "next/server";
+
+const DEFAULT_ORCHESTRATOR_URL = "http://localhost:3001";
+
+function getOrchestratorUrl(): string {
+  return (
+    process.env.ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_API_URL ??
+    DEFAULT_ORCHESTRATOR_URL
+  );
+}
+
+/**
+ * Server-side proxy for orchestrator agent status.
+ * Keeps ORCHESTRATOR_API_KEY out of browser code.
+ */
+export async function GET(): Promise<NextResponse> {
+  const orchestratorApiKey = process.env.ORCHESTRATOR_API_KEY;
+  if (!orchestratorApiKey) {
+    return NextResponse.json(
+      { error: "ORCHESTRATOR_API_KEY is not configured on the web server." },
+      { status: 503 }
+    );
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    controller.abort();
+  }, 10_000);
+
+  try {
+    const response = await fetch(`${getOrchestratorUrl()}/agents`, {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": orchestratorApiKey,
+      },
+      cache: "no-store",
+      signal: controller.signal,
+    });
+
+    const text = await response.text();
+    return new NextResponse(text, {
+      status: response.status,
+      headers: {
+        "Content-Type": response.headers.get("Content-Type") ?? "application/json",
+      },
+    });
+  } catch (error) {
+    const message =
+      error instanceof Error && error.name === "AbortError"
+        ? "Orchestrator request timed out."
+        : "Unable to reach orchestrator.";
+    return NextResponse.json({ error: message }, { status: 502 });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
diff --git a/apps/web/src/app/api/orchestrator/events/recent/route.ts b/apps/web/src/app/api/orchestrator/events/recent/route.ts
new file mode 100644
index 0000000..a680c63
--- /dev/null
+++ b/apps/web/src/app/api/orchestrator/events/recent/route.ts
@@ -0,0 +1,47 @@
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+const DEFAULT_ORCHESTRATOR_URL = "http://localhost:3001";
+
+function getOrchestratorUrl(): string {
+  return (
+    process.env.ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_API_URL ??
+    DEFAULT_ORCHESTRATOR_URL
+  );
+}
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const orchestratorApiKey = process.env.ORCHESTRATOR_API_KEY;
+  if (!orchestratorApiKey) {
+    return NextResponse.json(
+      { error: "ORCHESTRATOR_API_KEY is not configured on the web server." },
+      { status: 503 }
+    );
+  }
+
+  const limit = request.nextUrl.searchParams.get("limit");
+  const query = limit ? `?limit=${encodeURIComponent(limit)}` : "";
+
+  try {
+    const response = await fetch(`${getOrchestratorUrl()}/agents/events/recent${query}`, {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": orchestratorApiKey,
+      },
+      cache: "no-store",
+    });
+
+    const text = await response.text();
+    return new NextResponse(text, {
+      status: response.status,
+      headers: {
+        "Content-Type": response.headers.get("Content-Type") ?? "application/json",
+      },
+    });
+  } catch {
+    return NextResponse.json({ error: "Unable to reach orchestrator." }, { status: 502 });
+  }
+}
diff --git a/apps/web/src/app/api/orchestrator/events/route.ts b/apps/web/src/app/api/orchestrator/events/route.ts
new file mode 100644
index 0000000..18d0e02
--- /dev/null
+++ b/apps/web/src/app/api/orchestrator/events/route.ts
@@ -0,0 +1,50 @@
+import { NextResponse } from "next/server";
+
+const DEFAULT_ORCHESTRATOR_URL = "http://localhost:3001";
+
+function getOrchestratorUrl(): string {
+  return (
+    process.env.ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_API_URL ??
+    DEFAULT_ORCHESTRATOR_URL
+  );
+}
+
+export async function GET(): Promise<Response> {
+  const orchestratorApiKey = process.env.ORCHESTRATOR_API_KEY;
+  if (!orchestratorApiKey) {
+    return NextResponse.json(
+      { error: "ORCHESTRATOR_API_KEY is not configured on the web server." },
+      { status: 503 }
+    );
+  }
+
+  try {
+    const upstream = await fetch(`${getOrchestratorUrl()}/agents/events`, {
+      method: "GET",
+      headers: {
+        "X-API-Key": orchestratorApiKey,
+      },
+      cache: "no-store",
+    });
+
+    if (!upstream.ok || !upstream.body) {
+      const text = await upstream.text();
+      return new NextResponse(text || "Failed to connect to orchestrator events stream", {
+        status: upstream.status || 502,
+      });
+    }
+
+    return new Response(upstream.body, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive",
+      },
+    });
+  } catch {
+    return NextResponse.json({ error: "Unable to reach orchestrator." }, { status: 502 });
+  }
+}
diff --git a/apps/web/src/app/api/orchestrator/health/route.ts b/apps/web/src/app/api/orchestrator/health/route.ts
new file mode 100644
index 0000000..233cce2
--- /dev/null
+++ b/apps/web/src/app/api/orchestrator/health/route.ts
@@ -0,0 +1,43 @@
+import { NextResponse } from "next/server";
+
+const DEFAULT_ORCHESTRATOR_URL = "http://localhost:3001";
+
+function getOrchestratorUrl(): string {
+  return (
+    process.env.ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_API_URL ??
+    DEFAULT_ORCHESTRATOR_URL
+  );
+}
+
+export async function GET(): Promise<NextResponse> {
+  const orchestratorApiKey = process.env.ORCHESTRATOR_API_KEY;
+  if (!orchestratorApiKey) {
+    return NextResponse.json(
+      { error: "ORCHESTRATOR_API_KEY is not configured on the web server." },
+      { status: 503 }
+    );
+  }
+
+  try {
+    const response = await fetch(`${getOrchestratorUrl()}/health/ready`, {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": orchestratorApiKey,
+      },
+      cache: "no-store",
+    });
+
+    const text = await response.text();
+    return new NextResponse(text, {
+      status: response.status,
+      headers: {
+        "Content-Type": response.headers.get("Content-Type") ?? "application/json",
+      },
+    });
+  } catch {
+    return NextResponse.json({ error: "Unable to reach orchestrator." }, { status: 502 });
+  }
+}
diff --git a/apps/web/src/app/api/orchestrator/queue/pause/route.ts b/apps/web/src/app/api/orchestrator/queue/pause/route.ts
new file mode 100644
index 0000000..1c27cfd
--- /dev/null
+++ b/apps/web/src/app/api/orchestrator/queue/pause/route.ts
@@ -0,0 +1,43 @@
+import { NextResponse } from "next/server";
+
+const DEFAULT_ORCHESTRATOR_URL = "http://localhost:3001";
+
+function getOrchestratorUrl(): string {
+  return (
+    process.env.ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_API_URL ??
+    DEFAULT_ORCHESTRATOR_URL
+  );
+}
+
+export async function POST(): Promise<NextResponse> {
+  const orchestratorApiKey = process.env.ORCHESTRATOR_API_KEY;
+  if (!orchestratorApiKey) {
+    return NextResponse.json(
+      { error: "ORCHESTRATOR_API_KEY is not configured on the web server." },
+      { status: 503 }
+    );
+  }
+
+  try {
+    const response = await fetch(`${getOrchestratorUrl()}/queue/pause`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": orchestratorApiKey,
+      },
+      cache: "no-store",
+    });
+
+    const text = await response.text();
+    return new NextResponse(text, {
+      status: response.status,
+      headers: {
+        "Content-Type": response.headers.get("Content-Type") ?? "application/json",
+      },
+    });
+  } catch {
+    return NextResponse.json({ error: "Unable to reach orchestrator." }, { status: 502 });
+  }
+}
diff --git a/apps/web/src/app/api/orchestrator/queue/resume/route.ts b/apps/web/src/app/api/orchestrator/queue/resume/route.ts
new file mode 100644
index 0000000..635ef63
--- /dev/null
+++ b/apps/web/src/app/api/orchestrator/queue/resume/route.ts
@@ -0,0 +1,43 @@
+import { NextResponse } from "next/server";
+
+const DEFAULT_ORCHESTRATOR_URL = "http://localhost:3001";
+
+function getOrchestratorUrl(): string {
+  return (
+    process.env.ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_API_URL ??
+    DEFAULT_ORCHESTRATOR_URL
+  );
+}
+
+export async function POST(): Promise<NextResponse> {
+  const orchestratorApiKey = process.env.ORCHESTRATOR_API_KEY;
+  if (!orchestratorApiKey) {
+    return NextResponse.json(
+      { error: "ORCHESTRATOR_API_KEY is not configured on the web server." },
+      { status: 503 }
+    );
+  }
+
+  try {
+    const response = await fetch(`${getOrchestratorUrl()}/queue/resume`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": orchestratorApiKey,
+      },
+      cache: "no-store",
+    });
+
+    const text = await response.text();
+    return new NextResponse(text, {
+      status: response.status,
+      headers: {
+        "Content-Type": response.headers.get("Content-Type") ?? "application/json",
+      },
+    });
+  } catch {
+    return NextResponse.json({ error: "Unable to reach orchestrator." }, { status: 502 });
+  }
+}
diff --git a/apps/web/src/app/api/orchestrator/queue/stats/route.ts b/apps/web/src/app/api/orchestrator/queue/stats/route.ts
new file mode 100644
index 0000000..d089094
--- /dev/null
+++ b/apps/web/src/app/api/orchestrator/queue/stats/route.ts
@@ -0,0 +1,43 @@
+import { NextResponse } from "next/server";
+
+const DEFAULT_ORCHESTRATOR_URL = "http://localhost:3001";
+
+function getOrchestratorUrl(): string {
+  return (
+    process.env.ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_ORCHESTRATOR_URL ??
+    process.env.NEXT_PUBLIC_API_URL ??
+    DEFAULT_ORCHESTRATOR_URL
+  );
+}
+
+export async function GET(): Promise<NextResponse> {
+  const orchestratorApiKey = process.env.ORCHESTRATOR_API_KEY;
+  if (!orchestratorApiKey) {
+    return NextResponse.json(
+      { error: "ORCHESTRATOR_API_KEY is not configured on the web server." },
+      { status: 503 }
+    );
+  }
+
+  try {
+    const response = await fetch(`${getOrchestratorUrl()}/queue/stats`, {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": orchestratorApiKey,
+      },
+      cache: "no-store",
+    });
+
+    const text = await response.text();
+    return new NextResponse(text, {
+      status: response.status,
+      headers: {
+        "Content-Type": response.headers.get("Content-Type") ?? "application/json",
+      },
+    });
+  } catch {
+    return NextResponse.json({ error: "Unable to reach orchestrator." }, { status: 502 });
+  }
+}
diff --git a/apps/web/src/components/hud/HUD.tsx b/apps/web/src/components/hud/HUD.tsx
index b9078ab..6341be7 100644
--- a/apps/web/src/components/hud/HUD.tsx
+++ b/apps/web/src/components/hud/HUD.tsx
@@ -55,6 +55,15 @@ const WIDGET_REGISTRY = {
     minWidth: 1,
     minHeight: 1,
   },
+  OrchestratorEventsWidget: {
+    name: "orchestrator-events",
+    displayName: "Orchestrator Events",
+    description: "Recent events and stream health for orchestration",
+    defaultWidth: 2,
+    defaultHeight: 2,
+    minWidth: 1,
+    minHeight: 1,
+  },
 } as const;
 
 type WidgetRegistryKey = keyof typeof WIDGET_REGISTRY;
@@ -73,7 +82,7 @@ export function HUD({ className = "" }: HUDProps): React.JSX.Element {
 
   const handleAddWidget = (widgetType: WidgetRegistryKey): void => {
     const widgetConfig = WIDGET_REGISTRY[widgetType];
-    const widgetId = `${widgetType.toLowerCase()}-${String(Date.now())}`;
+    const widgetId = `${widgetConfig.name}-${String(Date.now())}`;
 
     // Find the next available position
     const maxY = currentLayout?.layout.reduce((max, w): number => Math.max(max, w.y + w.h), 0) ?? 0;
diff --git a/apps/web/src/components/hud/WidgetRenderer.test.tsx b/apps/web/src/components/hud/WidgetRenderer.test.tsx
new file mode 100644
index 0000000..a5b0b1a
--- /dev/null
+++ b/apps/web/src/components/hud/WidgetRenderer.test.tsx
@@ -0,0 +1,47 @@
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import { WidgetRenderer } from "./WidgetRenderer";
+import type { WidgetPlacement } from "@mosaic/shared";
+
+vi.mock("@/components/widgets", () => ({
+  TasksWidget: ({ id }: { id: string }): React.JSX.Element => <div>Tasks Widget {id}</div>,
+  CalendarWidget: ({ id }: { id: string }): React.JSX.Element => <div>Calendar Widget {id}</div>,
+  QuickCaptureWidget: ({ id }: { id: string }): React.JSX.Element => (
+    <div>Quick Capture Widget {id}</div>
+  ),
+  AgentStatusWidget: ({ id }: { id: string }): React.JSX.Element => (
+    <div>Agent Status Widget {id}</div>
+  ),
+  OrchestratorEventsWidget: ({ id }: { id: string }): React.JSX.Element => (
+    <div>Orchestrator Events Widget {id}</div>
+  ),
+}));
+
+function createWidgetPlacement(id: string): WidgetPlacement {
+  return {
+    i: id,
+    x: 0,
+    y: 0,
+    w: 2,
+    h: 2,
+  };
+}
+
+describe("WidgetRenderer", () => {
+  it("renders hyphenated quick-capture widget IDs correctly", () => {
+    render(<WidgetRenderer widget={createWidgetPlacement("quick-capture-123")} />);
+    expect(screen.getByText("Quick Capture Widget quick-capture-123")).toBeInTheDocument();
+  });
+
+  it("renders hyphenated agent-status widget IDs correctly", () => {
+    render(<WidgetRenderer widget={createWidgetPlacement("agent-status-123")} />);
+    expect(screen.getByText("Agent Status Widget agent-status-123")).toBeInTheDocument();
+  });
+
+  it("renders hyphenated orchestrator-events widget IDs correctly", () => {
+    render(<WidgetRenderer widget={createWidgetPlacement("orchestrator-events-123")} />);
+    expect(
+      screen.getByText("Orchestrator Events Widget orchestrator-events-123")
+    ).toBeInTheDocument();
+  });
+});
diff --git a/apps/web/src/components/hud/WidgetRenderer.tsx b/apps/web/src/components/hud/WidgetRenderer.tsx
index 9555aed..d05551b 100644
--- a/apps/web/src/components/hud/WidgetRenderer.tsx
+++ b/apps/web/src/components/hud/WidgetRenderer.tsx
@@ -10,6 +10,7 @@ import {
   CalendarWidget,
   QuickCaptureWidget,
   AgentStatusWidget,
+  OrchestratorEventsWidget,
 } from "@/components/widgets";
 import type { WidgetPlacement } from "@mosaic/shared";
 
@@ -24,6 +25,7 @@ const WIDGET_COMPONENTS = {
   calendar: CalendarWidget,
   "quick-capture": QuickCaptureWidget,
   "agent-status": AgentStatusWidget,
+  "orchestrator-events": OrchestratorEventsWidget,
 };
 
 const WIDGET_CONFIG = {
@@ -43,6 +45,10 @@ const WIDGET_CONFIG = {
     displayName: "Agent Status",
     description: "View running agent sessions",
   },
+  "orchestrator-events": {
+    displayName: "Orchestrator Events",
+    description: "Recent orchestration events and stream health",
+  },
 };
 
 export function WidgetRenderer({
@@ -50,8 +56,12 @@ export function WidgetRenderer({
   isEditing = false,
   onRemove,
 }: WidgetRendererProps): React.JSX.Element {
-  // Extract widget type from ID (e.g., "tasks-123" -> "tasks")
-  const widgetType = widget.i.split("-")[0] as keyof typeof WIDGET_COMPONENTS;
+  // Extract widget type from ID by removing the trailing unique suffix
+  // (e.g., "agent-status-123" -> "agent-status").
+  const separatorIndex = widget.i.lastIndexOf("-");
+  const widgetType = (
+    separatorIndex > 0 ? widget.i.substring(0, separatorIndex) : widget.i
+  ) as keyof typeof WIDGET_COMPONENTS;
   const WidgetComponent = WIDGET_COMPONENTS[widgetType];
   const config = WIDGET_CONFIG[widgetType] || { displayName: "Widget", description: "" };
 
diff --git a/apps/web/src/components/knowledge/__tests__/LinkAutocomplete.test.tsx b/apps/web/src/components/knowledge/__tests__/LinkAutocomplete.test.tsx
index 8ec8985..dae1d99 100644
--- a/apps/web/src/components/knowledge/__tests__/LinkAutocomplete.test.tsx
+++ b/apps/web/src/components/knowledge/__tests__/LinkAutocomplete.test.tsx
@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-non-null-assertion */
 /* eslint-disable @typescript-eslint/no-unnecessary-condition */
 import React from "react";
 import { render, screen, waitFor, fireEvent, act } from "@testing-library/react";
@@ -352,10 +351,7 @@ describe("LinkAutocomplete", (): void => {
     vi.useRealTimers();
   });
 
-  // TODO: Fix async/timer interaction - component works but test has timing issues with fake timers
-  it.skip("should perform debounced search when typing query", async (): Promise<void> => {
-    vi.useFakeTimers();
-
+  it("should perform debounced search when typing query", async (): Promise<void> => {
     const mockResults = {
       data: [
         {
@@ -395,11 +391,6 @@ describe("LinkAutocomplete", (): void => {
     // Should not call API immediately
     expect(mockApiRequest).not.toHaveBeenCalled();
 
-    // Fast-forward 300ms and let promises resolve
-    await act(async () => {
-      await vi.runAllTimersAsync();
-    });
-
     await waitFor(() => {
       expect(mockApiRequest).toHaveBeenCalledWith(
         "/api/knowledge/search?q=test&limit=10",
@@ -411,14 +402,9 @@ describe("LinkAutocomplete", (): void => {
     await waitFor(() => {
       expect(screen.getByText("Test Entry")).toBeInTheDocument();
     });
-
-    vi.useRealTimers();
   });
 
-  // TODO: Fix async/timer interaction - component works but test has timing issues with fake timers
-  it.skip("should navigate results with arrow keys", async (): Promise<void> => {
-    vi.useFakeTimers();
-
+  it("should navigate results with arrow keys", async (): Promise<void> => {
     const mockResults = {
       data: [
         {
@@ -471,10 +457,6 @@ describe("LinkAutocomplete", (): void => {
       fireEvent.input(textarea);
     });
 
-    await act(async () => {
-      await vi.runAllTimersAsync();
-    });
-
     await waitFor(() => {
       expect(screen.getByText("Entry One")).toBeInTheDocument();
     });
@@ -484,7 +466,9 @@ describe("LinkAutocomplete", (): void => {
     expect(firstItem).toHaveClass("bg-blue-50");
 
     // Press ArrowDown
-    fireEvent.keyDown(textarea, { key: "ArrowDown" });
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "ArrowDown" });
+    });
 
     // Second item should now be selected
     await waitFor(() => {
@@ -493,21 +477,18 @@ describe("LinkAutocomplete", (): void => {
     });
 
     // Press ArrowUp
-    fireEvent.keyDown(textarea, { key: "ArrowUp" });
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "ArrowUp" });
+    });
 
     // First item should be selected again
     await waitFor(() => {
       const firstItem = screen.getByText("Entry One").closest("li");
       expect(firstItem).toHaveClass("bg-blue-50");
     });
-
-    vi.useRealTimers();
   });
 
-  // TODO: Fix async/timer interaction - component works but test has timing issues with fake timers
-  it.skip("should insert link on Enter key", async (): Promise<void> => {
-    vi.useFakeTimers();
-
+  it("should insert link on Enter key", async (): Promise<void> => {
     const mockResults = {
       data: [
         {
@@ -544,10 +525,6 @@ describe("LinkAutocomplete", (): void => {
       fireEvent.input(textarea);
     });
 
-    await act(async () => {
-      await vi.runAllTimersAsync();
-    });
-
     await waitFor(() => {
       expect(screen.getByText("Test Entry")).toBeInTheDocument();
     });
@@ -558,14 +535,9 @@ describe("LinkAutocomplete", (): void => {
     await waitFor(() => {
       expect(onInsertMock).toHaveBeenCalledWith("[[test-entry|Test Entry]]");
     });
-
-    vi.useRealTimers();
   });
 
-  // TODO: Fix async/timer interaction - component works but test has timing issues with fake timers
-  it.skip("should insert link on click", async (): Promise<void> => {
-    vi.useFakeTimers();
-
+  it("should insert link on click", async (): Promise<void> => {
     const mockResults = {
       data: [
         {
@@ -602,10 +574,6 @@ describe("LinkAutocomplete", (): void => {
       fireEvent.input(textarea);
     });
 
-    await act(async () => {
-      await vi.runAllTimersAsync();
-    });
-
     await waitFor(() => {
       expect(screen.getByText("Test Entry")).toBeInTheDocument();
     });
@@ -616,14 +584,9 @@ describe("LinkAutocomplete", (): void => {
     await waitFor(() => {
       expect(onInsertMock).toHaveBeenCalledWith("[[test-entry|Test Entry]]");
     });
-
-    vi.useRealTimers();
   });
 
-  // TODO: Fix async/timer interaction - component works but test has timing issues with fake timers
-  it.skip("should close dropdown on Escape key", async (): Promise<void> => {
-    vi.useFakeTimers();
-
+  it("should close dropdown on Escape key", async (): Promise<void> => {
     render(<LinkAutocomplete textareaRef={textareaRef} onInsert={onInsertMock} />);
 
     const textarea = textareaRef.current;
@@ -636,28 +599,19 @@ describe("LinkAutocomplete", (): void => {
       fireEvent.input(textarea);
     });
 
-    await act(async () => {
-      await vi.runAllTimersAsync();
-    });
-
     await waitFor(() => {
-      expect(screen.getByText(/Start typing to search/)).toBeInTheDocument();
+      expect(screen.getByText("↑↓ Navigate • Enter Select • Esc Cancel")).toBeInTheDocument();
     });
 
     // Press Escape
     fireEvent.keyDown(textarea, { key: "Escape" });
 
     await waitFor(() => {
-      expect(screen.queryByText(/Start typing to search/)).not.toBeInTheDocument();
+      expect(screen.queryByText("↑↓ Navigate • Enter Select • Esc Cancel")).not.toBeInTheDocument();
     });
-
-    vi.useRealTimers();
   });
 
-  // TODO: Fix async/timer interaction - component works but test has timing issues with fake timers
-  it.skip("should close dropdown when closing brackets are typed", async (): Promise<void> => {
-    vi.useFakeTimers();
-
+  it("should close dropdown when closing brackets are typed", async (): Promise<void> => {
     render(<LinkAutocomplete textareaRef={textareaRef} onInsert={onInsertMock} />);
 
     const textarea = textareaRef.current;
@@ -670,12 +624,8 @@ describe("LinkAutocomplete", (): void => {
       fireEvent.input(textarea);
     });
 
-    await act(async () => {
-      await vi.runAllTimersAsync();
-    });
-
     await waitFor(() => {
-      expect(screen.getByText(/Start typing to search/)).toBeInTheDocument();
+      expect(screen.getByText("↑↓ Navigate • Enter Select • Esc Cancel")).toBeInTheDocument();
     });
 
     // Type closing brackets
@@ -686,16 +636,11 @@ describe("LinkAutocomplete", (): void => {
     });
 
     await waitFor(() => {
-      expect(screen.queryByText(/Start typing to search/)).not.toBeInTheDocument();
+      expect(screen.queryByText("↑↓ Navigate • Enter Select • Esc Cancel")).not.toBeInTheDocument();
     });
-
-    vi.useRealTimers();
   });
 
-  // TODO: Fix async/timer interaction - component works but test has timing issues with fake timers
-  it.skip("should show 'No entries found' when search returns no results", async (): Promise<void> => {
-    vi.useFakeTimers();
-
+  it("should show 'No entries found' when search returns no results", async (): Promise<void> => {
     mockApiRequest.mockResolvedValue({
       data: [],
       meta: { total: 0, page: 1, limit: 10, totalPages: 0 },
@@ -713,32 +658,24 @@ describe("LinkAutocomplete", (): void => {
       fireEvent.input(textarea);
     });
 
-    await act(async () => {
-      await vi.runAllTimersAsync();
-    });
-
     await waitFor(() => {
       expect(screen.getByText("No entries found")).toBeInTheDocument();
     });
-
-    vi.useRealTimers();
   });
 
-  // TODO: Fix async/timer interaction - component works but test has timing issues with fake timers
-  it.skip("should show loading state while searching", async (): Promise<void> => {
-    vi.useFakeTimers();
-
+  it("should show loading state while searching", async (): Promise<void> => {
     // Mock a slow API response
-    let resolveSearch: (value: unknown) => void;
-    const searchPromise = new Promise((resolve) => {
+    let resolveSearch: (value: {
+      data: unknown[];
+      meta: { total: number; page: number; limit: number; totalPages: number };
+    }) => void = () => undefined;
+    const searchPromise = new Promise<{
+      data: unknown[];
+      meta: { total: number; page: number; limit: number; totalPages: number };
+    }>((resolve) => {
       resolveSearch = resolve;
     });
-    mockApiRequest.mockReturnValue(
-      searchPromise as Promise<{
-        data: unknown[];
-        meta: { total: number; page: number; limit: number; totalPages: number };
-      }>
-    );
+    mockApiRequest.mockReturnValue(searchPromise);
 
     render(<LinkAutocomplete textareaRef={textareaRef} onInsert={onInsertMock} />);
 
@@ -752,16 +689,12 @@ describe("LinkAutocomplete", (): void => {
       fireEvent.input(textarea);
     });
 
-    await act(async () => {
-      await vi.runAllTimersAsync();
-    });
-
     await waitFor(() => {
       expect(screen.getByText("Searching...")).toBeInTheDocument();
     });
 
     // Resolve the search
-    resolveSearch!({
+    resolveSearch({
       data: [],
       meta: { total: 0, page: 1, limit: 10, totalPages: 0 },
     });
@@ -769,14 +702,9 @@ describe("LinkAutocomplete", (): void => {
     await waitFor(() => {
       expect(screen.queryByText("Searching...")).not.toBeInTheDocument();
     });
-
-    vi.useRealTimers();
   });
 
-  // TODO: Fix async/timer interaction - component works but test has timing issues with fake timers
-  it.skip("should display summary preview for entries", async (): Promise<void> => {
-    vi.useFakeTimers();
-
+  it("should display summary preview for entries", async (): Promise<void> => {
     const mockResults = {
       data: [
         {
@@ -813,14 +741,8 @@ describe("LinkAutocomplete", (): void => {
       fireEvent.input(textarea);
     });
 
-    await act(async () => {
-      await vi.runAllTimersAsync();
-    });
-
     await waitFor(() => {
       expect(screen.getByText("This is a helpful summary")).toBeInTheDocument();
     });
-
-    vi.useRealTimers();
   });
 });
diff --git a/apps/web/src/components/widgets/AgentStatusWidget.tsx b/apps/web/src/components/widgets/AgentStatusWidget.tsx
index 3a329a5..adb6a03 100644
--- a/apps/web/src/components/widgets/AgentStatusWidget.tsx
+++ b/apps/web/src/components/widgets/AgentStatusWidget.tsx
@@ -2,10 +2,9 @@
  * Agent Status Widget - shows running agents
  */
 
-import { useState, useEffect } from "react";
+import { useState, useEffect, useCallback } from "react";
 import { Bot, Activity, AlertCircle, CheckCircle, Clock } from "lucide-react";
 import type { WidgetProps } from "@mosaic/shared";
-import { ORCHESTRATOR_URL } from "@/lib/config";
 
 interface Agent {
   agentId: string;
@@ -22,46 +21,57 @@ export function AgentStatusWidget({ id: _id, config: _config }: WidgetProps): Re
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
 
+  const fetchAgents = useCallback(async (): Promise<void> => {
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const response = await fetch("/api/orchestrator/agents", {
+        headers: {
+          "Content-Type": "application/json",
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch agents: ${response.statusText}`);
+      }
+
+      const data = (await response.json()) as Agent[];
+      setAgents(data);
+    } catch (err: unknown) {
+      const errorMessage = err instanceof Error ? err.message : "Unknown error";
+      console.error("Failed to fetch agents:", errorMessage);
+      setError(errorMessage);
+      setAgents([]); // Clear agents on error
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
   // Fetch agents from orchestrator API
   useEffect(() => {
-    const fetchAgents = async (): Promise<void> => {
-      setIsLoading(true);
-      setError(null);
-
-      try {
-        const response = await fetch(`${ORCHESTRATOR_URL}/agents`, {
-          headers: {
-            "Content-Type": "application/json",
-          },
-        });
-
-        if (!response.ok) {
-          throw new Error(`Failed to fetch agents: ${response.statusText}`);
-        }
-
-        const data = (await response.json()) as Agent[];
-        setAgents(data);
-      } catch (err: unknown) {
-        const errorMessage = err instanceof Error ? err.message : "Unknown error";
-        console.error("Failed to fetch agents:", errorMessage);
-        setError(errorMessage);
-        setAgents([]); // Clear agents on error
-      } finally {
-        setIsLoading(false);
-      }
-    };
-
     void fetchAgents();
 
     // Refresh every 30 seconds
     const interval = setInterval(() => {
       void fetchAgents();
-    }, 30000);
+    }, 20000);
+
+    const eventSource =
+      typeof EventSource !== "undefined" ? new EventSource("/api/orchestrator/events") : null;
+    if (eventSource) {
+      eventSource.onmessage = (): void => {
+        void fetchAgents();
+      };
+      eventSource.onerror = (): void => {
+        // polling remains fallback
+      };
+    }
 
     return (): void => {
       clearInterval(interval);
+      eventSource?.close();
     };
-  }, []);
+  }, [fetchAgents]);
 
   const getStatusIcon = (status: string): React.JSX.Element => {
     const statusLower = status.toLowerCase();
diff --git a/apps/web/src/components/widgets/OrchestratorEventsWidget.tsx b/apps/web/src/components/widgets/OrchestratorEventsWidget.tsx
new file mode 100644
index 0000000..4719a8d
--- /dev/null
+++ b/apps/web/src/components/widgets/OrchestratorEventsWidget.tsx
@@ -0,0 +1,190 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Activity, DatabaseZap, Loader2, Wifi, WifiOff } from "lucide-react";
+import type { WidgetProps } from "@mosaic/shared";
+
+interface OrchestratorEvent {
+  type: string;
+  timestamp: string;
+  agentId?: string;
+  taskId?: string;
+  data?: Record<string, unknown>;
+}
+
+interface RecentEventsResponse {
+  events: OrchestratorEvent[];
+}
+
+function isMatrixSignal(event: OrchestratorEvent): boolean {
+  const text = JSON.stringify(event).toLowerCase();
+  return (
+    text.includes("matrix") ||
+    text.includes("room") ||
+    text.includes("channel") ||
+    text.includes("thread")
+  );
+}
+
+export function OrchestratorEventsWidget({
+  id: _id,
+  config: _config,
+}: WidgetProps): React.JSX.Element {
+  const [events, setEvents] = useState<OrchestratorEvent[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [streamConnected, setStreamConnected] = useState(false);
+  const [backendReady, setBackendReady] = useState<boolean | null>(null);
+
+  const loadRecentEvents = useCallback(async (): Promise<void> => {
+    try {
+      const response = await fetch("/api/orchestrator/events/recent?limit=25");
+      if (!response.ok) {
+        throw new Error(`Unable to load events: HTTP ${String(response.status)}`);
+      }
+      const payload = (await response.json()) as unknown;
+      const events =
+        payload &&
+        typeof payload === "object" &&
+        "events" in payload &&
+        Array.isArray(payload.events)
+          ? (payload.events as RecentEventsResponse["events"])
+          : [];
+      setEvents(events);
+      setError(null);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Unable to load events.");
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  const loadHealth = useCallback(async (): Promise<void> => {
+    try {
+      const response = await fetch("/api/orchestrator/health");
+      setBackendReady(response.ok);
+    } catch {
+      setBackendReady(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadRecentEvents();
+    void loadHealth();
+
+    const eventSource =
+      typeof EventSource !== "undefined" ? new EventSource("/api/orchestrator/events") : null;
+    if (eventSource) {
+      eventSource.onopen = (): void => {
+        setStreamConnected(true);
+      };
+      eventSource.onmessage = (): void => {
+        void loadRecentEvents();
+        void loadHealth();
+      };
+      eventSource.onerror = (): void => {
+        setStreamConnected(false);
+      };
+    }
+
+    const interval = setInterval(() => {
+      void loadRecentEvents();
+      void loadHealth();
+    }, 15000);
+
+    return (): void => {
+      clearInterval(interval);
+      eventSource?.close();
+    };
+  }, [loadHealth, loadRecentEvents]);
+
+  const matrixSignals = useMemo(
+    () => events.filter((event) => isMatrixSignal(event)).length,
+    [events]
+  );
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center h-full">
+        <Loader2 className="w-5 h-5 text-gray-400 animate-spin" />
+        <span className="ml-2 text-gray-500 text-sm">Loading orchestrator events...</span>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="flex flex-col items-center justify-center h-full text-center">
+        <WifiOff className="w-5 h-5 text-amber-500 mb-2" />
+        <span className="text-sm text-amber-600">{error}</span>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col h-full space-y-3">
+      <div className="flex items-center justify-between text-xs">
+        <div className="flex items-center gap-2 text-gray-600 dark:text-gray-300">
+          {streamConnected ? (
+            <Wifi className="w-3 h-3 text-green-500" />
+          ) : (
+            <WifiOff className="w-3 h-3 text-gray-400" />
+          )}
+          <span>{streamConnected ? "Live stream connected" : "Polling mode"}</span>
+          <span
+            className={`rounded px-1.5 py-0.5 ${
+              backendReady === true
+                ? "bg-green-100 text-green-700 dark:bg-green-950 dark:text-green-300"
+                : backendReady === false
+                  ? "bg-amber-100 text-amber-700 dark:bg-amber-950 dark:text-amber-300"
+                  : "bg-gray-100 text-gray-600 dark:bg-gray-800 dark:text-gray-300"
+            }`}
+          >
+            {backendReady === true ? "ready" : backendReady === false ? "degraded" : "unknown"}
+          </span>
+        </div>
+        <div className="flex items-center gap-1 rounded bg-blue-50 dark:bg-blue-950 px-2 py-1 text-blue-700 dark:text-blue-300">
+          <DatabaseZap className="w-3 h-3" />
+          <span>Matrix signals: {matrixSignals}</span>
+        </div>
+      </div>
+
+      <div className="flex-1 overflow-auto space-y-2">
+        {events.length === 0 ? (
+          <div className="text-center text-sm text-gray-500 py-4">
+            No recent orchestration events.
+          </div>
+        ) : (
+          events
+            .slice()
+            .reverse()
+            .map((event, index) => (
+              <div
+                key={`${event.timestamp}-${event.type}-${String(index)}`}
+                className="rounded border border-gray-200 dark:border-gray-700 bg-gray-50 dark:bg-gray-900 px-2 py-2"
+              >
+                <div className="flex items-center justify-between gap-2">
+                  <div className="flex items-center gap-2 min-w-0">
+                    <Activity className="w-3 h-3 text-blue-500 shrink-0" />
+                    <span className="text-xs font-medium text-gray-900 dark:text-gray-100 truncate">
+                      {event.type}
+                    </span>
+                    {isMatrixSignal(event) && (
+                      <span className="text-[10px] rounded bg-indigo-100 dark:bg-indigo-950 text-indigo-700 dark:text-indigo-300 px-1.5 py-0.5">
+                        matrix
+                      </span>
+                    )}
+                  </div>
+                  <span className="text-[10px] text-gray-500">
+                    {new Date(event.timestamp).toLocaleTimeString()}
+                  </span>
+                </div>
+                <div className="mt-1 text-[11px] text-gray-600 dark:text-gray-300">
+                  {event.taskId ? `Task ${event.taskId}` : "Task n/a"}
+                  {event.agentId ? ` · Agent ${event.agentId.slice(0, 8)}` : ""}
+                </div>
+              </div>
+            ))
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/widgets/TaskProgressWidget.tsx b/apps/web/src/components/widgets/TaskProgressWidget.tsx
index 18a917e..850c262 100644
--- a/apps/web/src/components/widgets/TaskProgressWidget.tsx
+++ b/apps/web/src/components/widgets/TaskProgressWidget.tsx
@@ -5,10 +5,9 @@
  * including status, elapsed time, and work item details.
  */
 
-import { useState, useEffect } from "react";
-import { Activity, CheckCircle, XCircle, Clock, Loader2 } from "lucide-react";
+import { useState, useEffect, useCallback } from "react";
+import { Activity, CheckCircle, XCircle, Clock, Loader2, Pause, Play } from "lucide-react";
 import type { WidgetProps } from "@mosaic/shared";
-import { ORCHESTRATOR_URL } from "@/lib/config";
 
 interface AgentTask {
   agentId: string;
@@ -20,6 +19,21 @@ interface AgentTask {
   error?: string;
 }
 
+interface QueueStats {
+  pending: number;
+  active: number;
+  completed: number;
+  failed: number;
+  delayed: number;
+}
+
+interface RecentOrchestratorEvent {
+  type: string;
+  timestamp: string;
+  taskId?: string;
+  agentId?: string;
+}
+
 function getElapsedTime(spawnedAt: string, completedAt?: string): string {
   const start = new Date(spawnedAt).getTime();
   const end = completedAt ? new Date(completedAt).getTime() : Date.now();
@@ -95,34 +109,108 @@ function getAgentTypeLabel(agentType: string): string {
 
 export function TaskProgressWidget({ id: _id, config: _config }: WidgetProps): React.JSX.Element {
   const [tasks, setTasks] = useState<AgentTask[]>([]);
+  const [queueStats, setQueueStats] = useState<QueueStats | null>(null);
+  const [recentEvents, setRecentEvents] = useState<RecentOrchestratorEvent[]>([]);
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
+  const [isQueuePaused, setIsQueuePaused] = useState(false);
+  const [isActionPending, setIsActionPending] = useState(false);
+
+  const fetchTasks = useCallback(async (): Promise<void> => {
+    try {
+      const res = await fetch("/api/orchestrator/agents");
+      if (!res.ok) throw new Error(`HTTP ${String(res.status)}`);
+      const data = (await res.json()) as AgentTask[];
+      setTasks(data);
+      setError(null);
+      setIsLoading(false);
+    } catch {
+      setError("Unable to reach orchestrator");
+      setIsLoading(false);
+    }
+  }, []);
+
+  const fetchQueueStats = useCallback(async (): Promise<void> => {
+    try {
+      const res = await fetch("/api/orchestrator/queue/stats");
+      if (!res.ok) throw new Error(`HTTP ${String(res.status)}`);
+      const data = (await res.json()) as QueueStats;
+      setQueueStats(data);
+      // Heuristic: active=0 with pending>0 for sustained windows usually means paused.
+      setIsQueuePaused(data.active === 0 && data.pending > 0);
+    } catch {
+      // Keep widget functional even if queue controls are temporarily unavailable.
+    }
+  }, []);
+
+  const fetchRecentEvents = useCallback(async (): Promise<void> => {
+    try {
+      const res = await fetch("/api/orchestrator/events/recent?limit=5");
+      if (!res.ok) throw new Error(`HTTP ${String(res.status)}`);
+      const payload = (await res.json()) as unknown;
+      const events =
+        payload &&
+        typeof payload === "object" &&
+        "events" in payload &&
+        Array.isArray(payload.events)
+          ? (payload.events as RecentOrchestratorEvent[])
+          : [];
+      setRecentEvents(events);
+    } catch {
+      // Optional enhancement path; do not fail widget if recent-events endpoint is unavailable.
+    }
+  }, []);
+
+  const setQueueState = useCallback(
+    async (action: "pause" | "resume"): Promise<void> => {
+      setIsActionPending(true);
+      try {
+        const res = await fetch(`/api/orchestrator/queue/${action}`, {
+          method: "POST",
+        });
+        if (!res.ok) throw new Error(`HTTP ${String(res.status)}`);
+        setIsQueuePaused(action === "pause");
+        await fetchQueueStats();
+      } catch {
+        setError("Unable to control queue state");
+      } finally {
+        setIsActionPending(false);
+      }
+    },
+    [fetchQueueStats]
+  );
 
   useEffect(() => {
-    const fetchTasks = (): void => {
-      fetch(`${ORCHESTRATOR_URL}/agents`)
-        .then((res) => {
-          if (!res.ok) throw new Error(`HTTP ${String(res.status)}`);
-          return res.json() as Promise<AgentTask[]>;
-        })
-        .then((data) => {
-          setTasks(data);
-          setError(null);
-          setIsLoading(false);
-        })
-        .catch(() => {
-          setError("Unable to reach orchestrator");
-          setIsLoading(false);
-        });
-    };
+    void fetchTasks();
+    void fetchQueueStats();
+    void fetchRecentEvents();
 
-    fetchTasks();
-    const interval = setInterval(fetchTasks, 15000);
+    const interval = setInterval(() => {
+      void fetchTasks();
+      void fetchQueueStats();
+      void fetchRecentEvents();
+    }, 15000);
+
+    const eventSource =
+      typeof EventSource !== "undefined" ? new EventSource("/api/orchestrator/events") : null;
+    if (eventSource) {
+      eventSource.onmessage = (): void => {
+        void fetchTasks();
+        void fetchQueueStats();
+        void fetchRecentEvents();
+      };
+      eventSource.onerror = (): void => {
+        // Polling remains the resilience path.
+      };
+    }
 
     return (): void => {
       clearInterval(interval);
+      eventSource?.close();
     };
-  }, []);
+  }, [fetchTasks, fetchQueueStats, fetchRecentEvents]);
+
+  const latestEvent = recentEvents.length > 0 ? recentEvents[recentEvents.length - 1] : null;
 
   const stats = {
     total: tasks.length,
@@ -152,6 +240,30 @@ export function TaskProgressWidget({ id: _id, config: _config }: WidgetProps): R
 
   return (
     <div className="flex flex-col h-full space-y-3">
+      <div className="flex items-center justify-between">
+        <div className="text-xs text-gray-500 dark:text-gray-400">
+          Queue: {isQueuePaused ? "Paused" : "Running"}
+        </div>
+        <button
+          type="button"
+          onClick={(): void => {
+            void setQueueState(isQueuePaused ? "resume" : "pause");
+          }}
+          disabled={isActionPending}
+          className="inline-flex items-center gap-1 rounded border border-gray-300 dark:border-gray-700 px-2 py-1 text-xs hover:bg-gray-100 dark:hover:bg-gray-800 disabled:opacity-50"
+        >
+          {isQueuePaused ? <Play className="w-3 h-3" /> : <Pause className="w-3 h-3" />}
+          {isQueuePaused ? "Resume" : "Pause"}
+        </button>
+      </div>
+
+      {latestEvent && (
+        <div className="rounded bg-gray-50 dark:bg-gray-800 px-2 py-1 text-xs text-gray-600 dark:text-gray-300">
+          Latest: {latestEvent.type}
+          {latestEvent.taskId ? ` · ${latestEvent.taskId}` : ""}
+        </div>
+      )}
+
       {/* Summary stats */}
       <div className="grid grid-cols-4 gap-1 text-center text-xs">
         <div className="bg-gray-50 dark:bg-gray-800 rounded p-2">
@@ -174,6 +286,29 @@ export function TaskProgressWidget({ id: _id, config: _config }: WidgetProps): R
         </div>
       </div>
 
+      {queueStats && (
+        <div className="grid grid-cols-3 gap-1 text-center text-xs">
+          <div className="bg-gray-50 dark:bg-gray-800 rounded p-1">
+            <div className="font-semibold text-gray-700 dark:text-gray-200">
+              {queueStats.pending}
+            </div>
+            <div className="text-gray-500">Queued</div>
+          </div>
+          <div className="bg-gray-50 dark:bg-gray-800 rounded p-1">
+            <div className="font-semibold text-gray-700 dark:text-gray-200">
+              {queueStats.active}
+            </div>
+            <div className="text-gray-500">Workers</div>
+          </div>
+          <div className="bg-gray-50 dark:bg-gray-800 rounded p-1">
+            <div className="font-semibold text-gray-700 dark:text-gray-200">
+              {queueStats.failed}
+            </div>
+            <div className="text-gray-500">Failed</div>
+          </div>
+        </div>
+      )}
+
       {/* Task list */}
       <div className="flex-1 overflow-auto space-y-2">
         {tasks.length === 0 ? (
diff --git a/apps/web/src/components/widgets/WidgetRegistry.tsx b/apps/web/src/components/widgets/WidgetRegistry.tsx
index 614f30f..ec811b4 100644
--- a/apps/web/src/components/widgets/WidgetRegistry.tsx
+++ b/apps/web/src/components/widgets/WidgetRegistry.tsx
@@ -10,6 +10,7 @@ import { QuickCaptureWidget } from "./QuickCaptureWidget";
 import { AgentStatusWidget } from "./AgentStatusWidget";
 import { ActiveProjectsWidget } from "./ActiveProjectsWidget";
 import { TaskProgressWidget } from "./TaskProgressWidget";
+import { OrchestratorEventsWidget } from "./OrchestratorEventsWidget";
 
 export interface WidgetDefinition {
   name: string;
@@ -95,6 +96,17 @@ export const widgetRegistry: Record<string, WidgetDefinition> = {
     minHeight: 2,
     maxWidth: 3,
   },
+  OrchestratorEventsWidget: {
+    name: "OrchestratorEventsWidget",
+    displayName: "Orchestrator Events",
+    description: "Recent orchestration events with stream/Matrix visibility",
+    component: OrchestratorEventsWidget,
+    defaultWidth: 2,
+    defaultHeight: 2,
+    minWidth: 1,
+    minHeight: 2,
+    maxWidth: 4,
+  },
 };
 
 /**
diff --git a/apps/web/src/components/widgets/__tests__/CalendarWidget.test.tsx b/apps/web/src/components/widgets/__tests__/CalendarWidget.test.tsx
index beb5a35..daad555 100644
--- a/apps/web/src/components/widgets/__tests__/CalendarWidget.test.tsx
+++ b/apps/web/src/components/widgets/__tests__/CalendarWidget.test.tsx
@@ -1,126 +1,55 @@
-/**
- * CalendarWidget Component Tests
- * Following TDD principles
- */
-
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, waitFor } from "@testing-library/react";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { act, render, screen } from "@testing-library/react";
 import { CalendarWidget } from "../CalendarWidget";
 
-global.fetch = vi.fn() as typeof global.fetch;
+async function finishWidgetLoad(): Promise<void> {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(500);
+  });
+}
 
 describe("CalendarWidget", (): void => {
   beforeEach((): void => {
-    vi.clearAllMocks();
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-02-01T08:00:00Z"));
   });
 
-  it("should render loading state initially", (): void => {
-    vi.mocked(global.fetch).mockImplementation(
-      () =>
-        new Promise(() => {
-          // Intentionally never resolves to keep loading state
-        })
-    );
-
-    render(<CalendarWidget id="calendar-1" />);
-
-    expect(screen.getByText(/loading/i)).toBeInTheDocument();
+  afterEach((): void => {
+    vi.useRealTimers();
   });
 
-  // TODO: Re-enable when CalendarWidget uses fetch API instead of setTimeout mock data
-  it.skip("should render upcoming events", async (): Promise<void> => {
-    const mockEvents = [
-      {
-        id: "1",
-        title: "Team Meeting",
-        startTime: new Date(Date.now() + 3600000).toISOString(),
-        endTime: new Date(Date.now() + 7200000).toISOString(),
-      },
-      {
-        id: "2",
-        title: "Project Review",
-        startTime: new Date(Date.now() + 86400000).toISOString(),
-        endTime: new Date(Date.now() + 90000000).toISOString(),
-      },
-    ];
-
-    vi.mocked(global.fetch).mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(mockEvents),
-    } as unknown as Response);
-
+  it("renders loading state initially", (): void => {
     render(<CalendarWidget id="calendar-1" />);
 
-    await waitFor(() => {
-      expect(screen.getByText("Team Meeting")).toBeInTheDocument();
-      expect(screen.getByText("Project Review")).toBeInTheDocument();
-    });
+    expect(screen.getByText("Loading events...")).toBeInTheDocument();
   });
 
-  // TODO: Re-enable when CalendarWidget uses fetch API instead of setTimeout mock data
-  it.skip("should handle empty event list", async (): Promise<void> => {
-    vi.mocked(global.fetch).mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve([]),
-    } as unknown as Response);
-
+  it("renders upcoming events after loading", async (): Promise<void> => {
     render(<CalendarWidget id="calendar-1" />);
 
-    await waitFor(() => {
-      expect(screen.getByText(/no upcoming events/i)).toBeInTheDocument();
-    });
+    await finishWidgetLoad();
+
+    expect(screen.getByText("Upcoming Events")).toBeInTheDocument();
+    expect(screen.getByText("Team Standup")).toBeInTheDocument();
+    expect(screen.getByText("Project Review")).toBeInTheDocument();
+    expect(screen.getByText("Sprint Planning")).toBeInTheDocument();
   });
 
-  // TODO: Re-enable when CalendarWidget uses fetch API instead of setTimeout mock data
-  it.skip("should handle API errors gracefully", async (): Promise<void> => {
-    vi.mocked(global.fetch).mockRejectedValueOnce(new Error("API Error"));
-
+  it("shows relative day labels", async (): Promise<void> => {
     render(<CalendarWidget id="calendar-1" />);
 
-    await waitFor(() => {
-      expect(screen.getByText(/error/i)).toBeInTheDocument();
-    });
+    await finishWidgetLoad();
+
+    expect(screen.getAllByText("Today").length).toBeGreaterThan(0);
+    expect(screen.getByText("Tomorrow")).toBeInTheDocument();
   });
 
-  // TODO: Re-enable when CalendarWidget uses fetch API instead of setTimeout mock data
-  it.skip("should format event times correctly", async (): Promise<void> => {
-    const now = new Date();
-    const startTime = new Date(now.getTime() + 3600000); // 1 hour from now
-
-    const mockEvents = [
-      {
-        id: "1",
-        title: "Meeting",
-        startTime: startTime.toISOString(),
-        endTime: new Date(startTime.getTime() + 3600000).toISOString(),
-      },
-    ];
-
-    vi.mocked(global.fetch).mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(mockEvents),
-    } as unknown as Response);
-
+  it("shows event locations when present", async (): Promise<void> => {
     render(<CalendarWidget id="calendar-1" />);
 
-    await waitFor(() => {
-      expect(screen.getByText("Meeting")).toBeInTheDocument();
-      // Should show time in readable format
-    });
-  });
+    await finishWidgetLoad();
 
-  // TODO: Re-enable when CalendarWidget uses fetch API and adds calendar-header test id
-  it.skip("should display current date", async (): Promise<void> => {
-    vi.mocked(global.fetch).mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve([]),
-    } as unknown as Response);
-
-    render(<CalendarWidget id="calendar-1" />);
-
-    await waitFor(() => {
-      // Widget should display current date or month
-      expect(screen.getByTestId("calendar-header")).toBeInTheDocument();
-    });
+    expect(screen.getByText("Zoom")).toBeInTheDocument();
+    expect(screen.getByText("Conference Room A")).toBeInTheDocument();
   });
 });
diff --git a/apps/web/src/components/widgets/__tests__/OrchestratorEventsWidget.test.tsx b/apps/web/src/components/widgets/__tests__/OrchestratorEventsWidget.test.tsx
new file mode 100644
index 0000000..35f1577
--- /dev/null
+++ b/apps/web/src/components/widgets/__tests__/OrchestratorEventsWidget.test.tsx
@@ -0,0 +1,82 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { OrchestratorEventsWidget } from "../OrchestratorEventsWidget";
+
+describe("OrchestratorEventsWidget", () => {
+  const mockFetch = vi.fn();
+
+  beforeEach(() => {
+    global.fetch = mockFetch as unknown as typeof fetch;
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("renders loading state initially", () => {
+    mockFetch.mockImplementation(
+      // eslint-disable-next-line @typescript-eslint/no-empty-function
+      () => new Promise(() => {})
+    );
+
+    render(<OrchestratorEventsWidget id="orchestrator-events-1" config={{}} />);
+    expect(screen.getByText("Loading orchestrator events...")).toBeInTheDocument();
+  });
+
+  it("renders events and matrix signal count", async () => {
+    mockFetch.mockImplementation((input: RequestInfo | URL) => {
+      const url =
+        typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+
+      if (url.includes("/api/orchestrator/health")) {
+        return Promise.resolve({
+          ok: true,
+          json: () => Promise.resolve({ status: "ok" }),
+        } as unknown as Response);
+      }
+
+      return Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            events: [
+              {
+                type: "task.completed",
+                timestamp: "2026-02-17T16:40:00.000Z",
+                taskId: "TASK-1",
+                data: { channelId: "room-123" },
+              },
+              {
+                type: "agent.running",
+                timestamp: "2026-02-17T16:41:00.000Z",
+                taskId: "TASK-2",
+                agentId: "agent-abc12345",
+              },
+            ],
+          }),
+      } as unknown as Response);
+    });
+
+    render(<OrchestratorEventsWidget id="orchestrator-events-1" config={{}} />);
+
+    await waitFor(() => {
+      expect(screen.getByText("task.completed")).toBeInTheDocument();
+      expect(screen.getByText("agent.running")).toBeInTheDocument();
+      expect(screen.getByText(/Matrix signals: 1/)).toBeInTheDocument();
+      expect(screen.getByText("ready")).toBeInTheDocument();
+    });
+  });
+
+  it("renders error state when API fails", async () => {
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 503,
+    });
+
+    render(<OrchestratorEventsWidget id="orchestrator-events-1" config={{}} />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Unable to load events: HTTP 503/)).toBeInTheDocument();
+    });
+  });
+});
diff --git a/apps/web/src/components/widgets/__tests__/TaskProgressWidget.test.tsx b/apps/web/src/components/widgets/__tests__/TaskProgressWidget.test.tsx
index 47fd72d..a6b038e 100644
--- a/apps/web/src/components/widgets/__tests__/TaskProgressWidget.test.tsx
+++ b/apps/web/src/components/widgets/__tests__/TaskProgressWidget.test.tsx
@@ -242,4 +242,58 @@ describe("TaskProgressWidget", (): void => {
       expect(taskElements[1]?.textContent).toBe("COMPLETED-TASK");
     });
   });
+
+  it("should display latest orchestrator event when available", async (): Promise<void> => {
+    mockFetch.mockImplementation((input: RequestInfo | URL) => {
+      let url = "";
+      if (typeof input === "string") {
+        url = input;
+      } else if (input instanceof URL) {
+        url = input.toString();
+      } else {
+        url = input.url;
+      }
+      if (url.includes("/api/orchestrator/agents")) {
+        return Promise.resolve({
+          ok: true,
+          json: () => Promise.resolve([]),
+        } as unknown as Response);
+      }
+      if (url.includes("/api/orchestrator/queue/stats")) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              pending: 0,
+              active: 0,
+              completed: 0,
+              failed: 0,
+              delayed: 0,
+            }),
+        } as unknown as Response);
+      }
+      if (url.includes("/api/orchestrator/events/recent")) {
+        return Promise.resolve({
+          ok: true,
+          json: () =>
+            Promise.resolve({
+              events: [
+                {
+                  type: "task.executing",
+                  timestamp: new Date().toISOString(),
+                  taskId: "TASK-123",
+                },
+              ],
+            }),
+        } as unknown as Response);
+      }
+      return Promise.reject(new Error("Unknown endpoint"));
+    });
+
+    render(<TaskProgressWidget id="task-progress-1" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Latest: task.executing · TASK-123/i)).toBeInTheDocument();
+    });
+  });
 });
diff --git a/apps/web/src/components/widgets/__tests__/TasksWidget.test.tsx b/apps/web/src/components/widgets/__tests__/TasksWidget.test.tsx
index fade486..50091e4 100644
--- a/apps/web/src/components/widgets/__tests__/TasksWidget.test.tsx
+++ b/apps/web/src/components/widgets/__tests__/TasksWidget.test.tsx
@@ -1,138 +1,54 @@
-/**
- * TasksWidget Component Tests
- * Following TDD principles
- */
-
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, waitFor } from "@testing-library/react";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { act, render, screen } from "@testing-library/react";
 import { TasksWidget } from "../TasksWidget";
 
-// Mock fetch for API calls
-global.fetch = vi.fn() as typeof global.fetch;
+async function finishWidgetLoad(): Promise<void> {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(500);
+  });
+}
 
 describe("TasksWidget", (): void => {
   beforeEach((): void => {
-    vi.clearAllMocks();
+    vi.useFakeTimers();
   });
 
-  it("should render loading state initially", (): void => {
-    vi.mocked(global.fetch).mockImplementation(
-      () =>
-        new Promise(() => {
-          // Intentionally empty - creates a never-resolving promise for loading state
-        })
-    );
-
-    render(<TasksWidget id="tasks-1" />);
-
-    expect(screen.getByText(/loading/i)).toBeInTheDocument();
+  afterEach((): void => {
+    vi.useRealTimers();
   });
 
-  // TODO: Re-enable when TasksWidget uses fetch API instead of setTimeout mock data
-  it.skip("should render task statistics", async (): Promise<void> => {
-    const mockTasks = [
-      { id: "1", title: "Task 1", status: "IN_PROGRESS", priority: "HIGH" },
-      { id: "2", title: "Task 2", status: "COMPLETED", priority: "MEDIUM" },
-      { id: "3", title: "Task 3", status: "NOT_STARTED", priority: "LOW" },
-    ];
-
-    vi.mocked(global.fetch).mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(mockTasks),
-    } as unknown as Response);
-
+  it("renders loading state initially", (): void => {
     render(<TasksWidget id="tasks-1" />);
 
-    await waitFor(() => {
-      expect(screen.getByText("3")).toBeInTheDocument(); // Total
-      expect(screen.getByText("1")).toBeInTheDocument(); // In Progress
-      expect(screen.getByText("1")).toBeInTheDocument(); // Completed
-    });
+    expect(screen.getByText("Loading tasks...")).toBeInTheDocument();
   });
 
-  // TODO: Re-enable when TasksWidget uses fetch API instead of setTimeout mock data
-  it.skip("should render task list", async (): Promise<void> => {
-    const mockTasks = [
-      { id: "1", title: "Complete documentation", status: "IN_PROGRESS", priority: "HIGH" },
-      { id: "2", title: "Review PRs", status: "NOT_STARTED", priority: "MEDIUM" },
-    ];
-
-    vi.mocked(global.fetch).mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(mockTasks),
-    } as unknown as Response);
-
+  it("renders default summary stats", async (): Promise<void> => {
     render(<TasksWidget id="tasks-1" />);
 
-    await waitFor(() => {
-      expect(screen.getByText("Complete documentation")).toBeInTheDocument();
-      expect(screen.getByText("Review PRs")).toBeInTheDocument();
-    });
+    await finishWidgetLoad();
+
+    expect(screen.getByText("Total")).toBeInTheDocument();
+    expect(screen.getByText("In Progress")).toBeInTheDocument();
+    expect(screen.getByText("Done")).toBeInTheDocument();
+    expect(screen.getByText("3")).toBeInTheDocument();
   });
 
-  // TODO: Re-enable when TasksWidget uses fetch API instead of setTimeout mock data
-  it.skip("should handle empty task list", async (): Promise<void> => {
-    vi.mocked(global.fetch).mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve([]),
-    } as unknown as Response);
-
+  it("renders default task rows", async (): Promise<void> => {
     render(<TasksWidget id="tasks-1" />);
 
-    await waitFor(() => {
-      expect(screen.getByText(/no tasks/i)).toBeInTheDocument();
-    });
+    await finishWidgetLoad();
+
+    expect(screen.getByText("Complete project documentation")).toBeInTheDocument();
+    expect(screen.getByText("Review pull requests")).toBeInTheDocument();
+    expect(screen.getByText("Update dependencies")).toBeInTheDocument();
   });
 
-  // TODO: Re-enable when TasksWidget uses fetch API instead of setTimeout mock data
-  it.skip("should handle API errors gracefully", async (): Promise<void> => {
-    vi.mocked(global.fetch).mockRejectedValueOnce(new Error("API Error"));
-
+  it("shows due date labels for each task", async (): Promise<void> => {
     render(<TasksWidget id="tasks-1" />);
 
-    await waitFor(() => {
-      expect(screen.getByText(/error/i)).toBeInTheDocument();
-    });
-  });
+    await finishWidgetLoad();
 
-  // TODO: Re-enable when TasksWidget uses fetch API instead of setTimeout mock data
-  it.skip("should display priority indicators", async (): Promise<void> => {
-    const mockTasks = [
-      { id: "1", title: "High priority task", status: "IN_PROGRESS", priority: "HIGH" },
-    ];
-
-    vi.mocked(global.fetch).mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(mockTasks),
-    } as unknown as Response);
-
-    render(<TasksWidget id="tasks-1" />);
-
-    await waitFor(() => {
-      expect(screen.getByText("High priority task")).toBeInTheDocument();
-      // Priority icon should be rendered (high priority = red)
-    });
-  });
-
-  // TODO: Re-enable when TasksWidget uses fetch API instead of setTimeout mock data
-  it.skip("should limit displayed tasks to 5", async (): Promise<void> => {
-    const mockTasks = Array.from({ length: 10 }, (_, i) => ({
-      id: String(i + 1),
-      title: `Task ${String(i + 1)}`,
-      status: "NOT_STARTED",
-      priority: "MEDIUM",
-    }));
-
-    vi.mocked(global.fetch).mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(mockTasks),
-    } as unknown as Response);
-
-    render(<TasksWidget id="tasks-1" />);
-
-    await waitFor(() => {
-      const taskElements = screen.getAllByText(/Task \d+/);
-      expect(taskElements.length).toBeLessThanOrEqual(5);
-    });
+    expect(screen.getAllByText(/Due:/).length).toBe(3);
   });
 });
diff --git a/apps/web/src/components/widgets/__tests__/WidgetRegistry.test.tsx b/apps/web/src/components/widgets/__tests__/WidgetRegistry.test.tsx
index c02728d..2fe000a 100644
--- a/apps/web/src/components/widgets/__tests__/WidgetRegistry.test.tsx
+++ b/apps/web/src/components/widgets/__tests__/WidgetRegistry.test.tsx
@@ -10,6 +10,7 @@ import { widgetRegistry } from "../WidgetRegistry";
 import { TasksWidget } from "../TasksWidget";
 import { CalendarWidget } from "../CalendarWidget";
 import { QuickCaptureWidget } from "../QuickCaptureWidget";
+import { OrchestratorEventsWidget } from "../OrchestratorEventsWidget";
 
 describe("WidgetRegistry", (): void => {
   it("should have a registry of widgets", (): void => {
@@ -32,6 +33,11 @@ describe("WidgetRegistry", (): void => {
     expect(widgetRegistry.QuickCaptureWidget!.component).toBe(QuickCaptureWidget);
   });
 
+  it("should include OrchestratorEventsWidget in registry", (): void => {
+    expect(widgetRegistry.OrchestratorEventsWidget).toBeDefined();
+    expect(widgetRegistry.OrchestratorEventsWidget!.component).toBe(OrchestratorEventsWidget);
+  });
+
   it("should have correct metadata for TasksWidget", (): void => {
     const tasksWidget = widgetRegistry.TasksWidget!;
     expect(tasksWidget.name).toBe("TasksWidget");
diff --git a/apps/web/src/components/widgets/index.ts b/apps/web/src/components/widgets/index.ts
index 63aa792..971d8ee 100644
--- a/apps/web/src/components/widgets/index.ts
+++ b/apps/web/src/components/widgets/index.ts
@@ -6,3 +6,4 @@ export { TasksWidget } from "./TasksWidget";
 export { CalendarWidget } from "./CalendarWidget";
 export { QuickCaptureWidget } from "./QuickCaptureWidget";
 export { AgentStatusWidget } from "./AgentStatusWidget";
+export { OrchestratorEventsWidget } from "./OrchestratorEventsWidget";
diff --git a/apps/web/src/lib/api/client.mock-mode.test.ts b/apps/web/src/lib/api/client.mock-mode.test.ts
new file mode 100644
index 0000000..98f167c
--- /dev/null
+++ b/apps/web/src/lib/api/client.mock-mode.test.ts
@@ -0,0 +1,55 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+const originalEnv = { ...process.env };
+const mockFetch = vi.fn();
+
+describe("API Client (mock auth mode)", (): void => {
+  beforeEach((): void => {
+    process.env = {
+      ...originalEnv,
+      NODE_ENV: "development",
+      NEXT_PUBLIC_AUTH_MODE: "mock",
+    };
+    vi.resetModules();
+    mockFetch.mockReset();
+    global.fetch = mockFetch;
+  });
+
+  afterEach((): void => {
+    process.env = originalEnv;
+    vi.restoreAllMocks();
+  });
+
+  it("should return local mock data for active projects widget without network calls", async (): Promise<void> => {
+    const { apiPost } = await import("./client");
+    interface ProjectResponse {
+      id: string;
+      status: string;
+    }
+
+    const response = await apiPost<ProjectResponse[]>("/api/widgets/data/active-projects");
+
+    expect(response.length).toBeGreaterThan(0);
+    const firstProject = response[0];
+    expect(firstProject).toBeDefined();
+    if (firstProject) {
+      expect(typeof firstProject.id).toBe("string");
+      expect(typeof firstProject.status).toBe("string");
+    }
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("should return local mock data for agent chains widget without network calls", async (): Promise<void> => {
+    const { apiPost } = await import("./client");
+    interface AgentChainResponse {
+      id: string;
+      status: string;
+    }
+
+    const response = await apiPost<AgentChainResponse[]>("/api/widgets/data/agent-chains");
+
+    expect(response.length).toBeGreaterThan(0);
+    expect(response.some((session) => session.status === "active")).toBe(true);
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/web/src/lib/api/client.ts b/apps/web/src/lib/api/client.ts
index cefe350..7bdd8fc 100644
--- a/apps/web/src/lib/api/client.ts
+++ b/apps/web/src/lib/api/client.ts
@@ -5,7 +5,7 @@
 
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 
-import { API_BASE_URL } from "../config";
+import { API_BASE_URL, IS_MOCK_AUTH_MODE } from "../config";
 
 /**
  * In-memory CSRF token storage
@@ -41,6 +41,74 @@ export interface ApiRequestOptions extends RequestInit {
   _isRetry?: boolean; // Internal flag to prevent infinite retry loops
 }
 
+const MOCK_ACTIVE_PROJECTS_RESPONSE = [
+  {
+    id: "project-dev-1",
+    name: "Mosaic Stack FE Go-Live",
+    status: "active",
+    lastActivity: new Date().toISOString(),
+    taskCount: 7,
+    eventCount: 2,
+    color: "#3B82F6",
+  },
+  {
+    id: "project-dev-2",
+    name: "Auth Flow Remediation",
+    status: "in-progress",
+    lastActivity: new Date(Date.now() - 12 * 60_000).toISOString(),
+    taskCount: 4,
+    eventCount: 0,
+    color: "#F59E0B",
+  },
+] as const;
+
+const MOCK_AGENT_CHAINS_RESPONSE = [
+  {
+    id: "agent-session-dev-1",
+    sessionKey: "dev-session-1",
+    label: "UI Validator Agent",
+    channel: "codex",
+    agentName: "jarvis-agent",
+    agentStatus: "WORKING",
+    status: "active",
+    startedAt: new Date(Date.now() - 42 * 60_000).toISOString(),
+    lastMessageAt: new Date(Date.now() - 20_000).toISOString(),
+    runtimeMs: 42 * 60_000,
+    messageCount: 27,
+    contextSummary: "Validating dashboard, tasks, and auth-bypass UX for local development flow.",
+  },
+  {
+    id: "agent-session-dev-2",
+    sessionKey: "dev-session-2",
+    label: "Telemetry Stub Agent",
+    channel: "codex",
+    agentName: "jarvis-agent",
+    agentStatus: "TERMINATED",
+    status: "ended",
+    startedAt: new Date(Date.now() - 3 * 60 * 60_000).toISOString(),
+    lastMessageAt: new Date(Date.now() - 2 * 60 * 60_000).toISOString(),
+    runtimeMs: 63 * 60_000,
+    messageCount: 41,
+    contextSummary: "Generated telemetry mock payloads for usage and widget rendering.",
+  },
+] as const;
+
+function getMockApiResponse(endpoint: string, method: string): unknown {
+  if (!IS_MOCK_AUTH_MODE || process.env.NODE_ENV !== "development") {
+    return undefined;
+  }
+
+  if (method === "POST" && endpoint === "/api/widgets/data/active-projects") {
+    return [...MOCK_ACTIVE_PROJECTS_RESPONSE];
+  }
+
+  if (method === "POST" && endpoint === "/api/widgets/data/agent-chains") {
+    return [...MOCK_AGENT_CHAINS_RESPONSE];
+  }
+
+  return undefined;
+}
+
 /**
  * Fetch CSRF token from the API
  * Token is stored in an httpOnly cookie and returned in response body
@@ -100,6 +168,12 @@ async function ensureCsrfToken(): Promise<string> {
 export async function apiRequest<T>(endpoint: string, options: ApiRequestOptions = {}): Promise<T> {
   const url = `${API_BASE_URL}${endpoint}`;
   const { workspaceId, timeoutMs, _isRetry, ...fetchOptions } = options;
+  const method = (fetchOptions.method ?? "GET").toUpperCase();
+
+  const mockResponse = getMockApiResponse(endpoint, method);
+  if (mockResponse !== undefined) {
+    return mockResponse as T;
+  }
 
   // Set up abort controller for timeout
   const timeout = timeoutMs ?? DEFAULT_API_TIMEOUT_MS;
@@ -134,7 +208,6 @@ export async function apiRequest<T>(endpoint: string, options: ApiRequestOptions
     }
 
     // Add CSRF token for state-changing requests (POST, PUT, PATCH, DELETE)
-    const method = (fetchOptions.method ?? "GET").toUpperCase();
     const isStateChanging = ["POST", "PUT", "PATCH", "DELETE"].includes(method);
 
     if (isStateChanging) {
diff --git a/apps/web/src/lib/auth/auth-context.tsx b/apps/web/src/lib/auth/auth-context.tsx
index 1b25acc..1282b0f 100644
--- a/apps/web/src/lib/auth/auth-context.tsx
+++ b/apps/web/src/lib/auth/auth-context.tsx
@@ -11,6 +11,7 @@ import {
 } from "react";
 import type { AuthUser, AuthSession } from "@mosaic/shared";
 import { apiGet, apiPost } from "../api/client";
+import { IS_MOCK_AUTH_MODE } from "../config";
 import { parseAuthError } from "./auth-errors";
 
 /**
@@ -23,6 +24,11 @@ const SESSION_EXPIRY_WARNING_MINUTES = 5;
 
 /** Interval in milliseconds to check session expiry */
 const SESSION_CHECK_INTERVAL_MS = 60_000;
+const MOCK_AUTH_USER: AuthUser = {
+  id: "dev-user-local",
+  email: "dev@localhost",
+  name: "Local Dev User",
+};
 
 interface AuthContextValue {
   user: AuthUser | null;
@@ -70,6 +76,14 @@ function logAuthError(message: string, error: unknown): void {
 }
 
 export function AuthProvider({ children }: { children: ReactNode }): React.JSX.Element {
+  if (IS_MOCK_AUTH_MODE) {
+    return <MockAuthProvider>{children}</MockAuthProvider>;
+  }
+
+  return <RealAuthProvider>{children}</RealAuthProvider>;
+}
+
+function RealAuthProvider({ children }: { children: ReactNode }): React.JSX.Element {
   const [user, setUser] = useState<AuthUser | null>(null);
   const [isLoading, setIsLoading] = useState(true);
   const [authError, setAuthError] = useState<AuthErrorType>(null);
@@ -176,6 +190,33 @@ export function AuthProvider({ children }: { children: ReactNode }): React.JSX.E
   return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
 }
 
+function MockAuthProvider({ children }: { children: ReactNode }): React.JSX.Element {
+  const [user, setUser] = useState<AuthUser | null>(MOCK_AUTH_USER);
+
+  const signOut = useCallback((): Promise<void> => {
+    setUser(null);
+    return Promise.resolve();
+  }, []);
+
+  const refreshSession = useCallback((): Promise<void> => {
+    setUser(MOCK_AUTH_USER);
+    return Promise.resolve();
+  }, []);
+
+  const value: AuthContextValue = {
+    user,
+    isLoading: false,
+    isAuthenticated: user !== null,
+    authError: null,
+    sessionExpiring: false,
+    sessionMinutesRemaining: 0,
+    signOut,
+    refreshSession,
+  };
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
 export function useAuth(): AuthContextValue {
   const context = useContext(AuthContext);
   if (context === undefined) {
diff --git a/apps/web/src/lib/config.test.ts b/apps/web/src/lib/config.test.ts
index f4bf828..f14c288 100644
--- a/apps/web/src/lib/config.test.ts
+++ b/apps/web/src/lib/config.test.ts
@@ -22,11 +22,16 @@ describe("API Configuration", () => {
     it("should use default API URL when NEXT_PUBLIC_API_URL is not set", async () => {
       delete process.env.NEXT_PUBLIC_API_URL;
       delete process.env.NEXT_PUBLIC_ORCHESTRATOR_URL;
+      delete process.env.NEXT_PUBLIC_AUTH_MODE;
+      process.env = { ...process.env, NODE_ENV: "development" };
 
-      const { API_BASE_URL, ORCHESTRATOR_URL } = await import("./config");
+      const { API_BASE_URL, ORCHESTRATOR_URL, AUTH_MODE, IS_MOCK_AUTH_MODE } =
+        await import("./config");
 
       expect(API_BASE_URL).toBe("http://localhost:3001");
       expect(ORCHESTRATOR_URL).toBe("http://localhost:3001");
+      expect(AUTH_MODE).toBe("mock");
+      expect(IS_MOCK_AUTH_MODE).toBe(true);
     });
   });
 
@@ -34,17 +39,22 @@ describe("API Configuration", () => {
     it("should use NEXT_PUBLIC_API_URL when set", async () => {
       process.env.NEXT_PUBLIC_API_URL = "https://api.example.com";
       delete process.env.NEXT_PUBLIC_ORCHESTRATOR_URL;
+      delete process.env.NEXT_PUBLIC_AUTH_MODE;
+      process.env = { ...process.env, NODE_ENV: "development" };
 
-      const { API_BASE_URL, ORCHESTRATOR_URL } = await import("./config");
+      const { API_BASE_URL, ORCHESTRATOR_URL, AUTH_MODE } = await import("./config");
 
       expect(API_BASE_URL).toBe("https://api.example.com");
       // ORCHESTRATOR_URL should fall back to API_BASE_URL
       expect(ORCHESTRATOR_URL).toBe("https://api.example.com");
+      expect(AUTH_MODE).toBe("mock");
     });
 
     it("should use separate NEXT_PUBLIC_ORCHESTRATOR_URL when set", async () => {
       process.env.NEXT_PUBLIC_API_URL = "https://api.example.com";
       process.env.NEXT_PUBLIC_ORCHESTRATOR_URL = "https://orchestrator.example.com";
+      process.env = { ...process.env, NODE_ENV: "development" };
+      delete process.env.NEXT_PUBLIC_AUTH_MODE;
 
       const { API_BASE_URL, ORCHESTRATOR_URL } = await import("./config");
 
@@ -57,6 +67,8 @@ describe("API Configuration", () => {
     it("should build API URLs correctly", async () => {
       process.env.NEXT_PUBLIC_API_URL = "https://api.example.com";
       delete process.env.NEXT_PUBLIC_ORCHESTRATOR_URL;
+      process.env = { ...process.env, NODE_ENV: "development" };
+      delete process.env.NEXT_PUBLIC_AUTH_MODE;
 
       const { buildApiUrl } = await import("./config");
 
@@ -67,6 +79,8 @@ describe("API Configuration", () => {
     it("should build orchestrator URLs correctly", async () => {
       process.env.NEXT_PUBLIC_API_URL = "https://api.example.com";
       process.env.NEXT_PUBLIC_ORCHESTRATOR_URL = "https://orch.example.com";
+      process.env = { ...process.env, NODE_ENV: "development" };
+      delete process.env.NEXT_PUBLIC_AUTH_MODE;
 
       const { buildOrchestratorUrl } = await import("./config");
 
@@ -79,13 +93,44 @@ describe("API Configuration", () => {
     it("should expose all configuration through apiConfig", async () => {
       process.env.NEXT_PUBLIC_API_URL = "https://api.example.com";
       process.env.NEXT_PUBLIC_ORCHESTRATOR_URL = "https://orch.example.com";
+      process.env = { ...process.env, NODE_ENV: "development" };
+      process.env.NEXT_PUBLIC_AUTH_MODE = "real";
 
       const { apiConfig } = await import("./config");
 
       expect(apiConfig.baseUrl).toBe("https://api.example.com");
       expect(apiConfig.orchestratorUrl).toBe("https://orch.example.com");
+      expect(apiConfig.authMode).toBe("real");
       expect(apiConfig.buildUrl("/test")).toBe("https://api.example.com/test");
       expect(apiConfig.buildOrchestratorUrl("/test")).toBe("https://orch.example.com/test");
     });
   });
+
+  describe("auth mode", () => {
+    it("should enable mock mode only in development", async () => {
+      process.env = { ...process.env, NODE_ENV: "development" };
+      process.env.NEXT_PUBLIC_AUTH_MODE = "mock";
+
+      const { AUTH_MODE, IS_MOCK_AUTH_MODE } = await import("./config");
+
+      expect(AUTH_MODE).toBe("mock");
+      expect(IS_MOCK_AUTH_MODE).toBe(true);
+    });
+
+    it("should throw on invalid auth mode", async () => {
+      process.env = { ...process.env, NODE_ENV: "development" };
+      process.env.NEXT_PUBLIC_AUTH_MODE = "invalid";
+
+      await expect(import("./config")).rejects.toThrow("Invalid NEXT_PUBLIC_AUTH_MODE");
+    });
+
+    it("should throw when mock mode is set outside development", async () => {
+      process.env = { ...process.env, NODE_ENV: "production" };
+      process.env.NEXT_PUBLIC_AUTH_MODE = "mock";
+
+      await expect(import("./config")).rejects.toThrow(
+        "NEXT_PUBLIC_AUTH_MODE=mock is only allowed when NODE_ENV=development."
+      );
+    });
+  });
 });
diff --git a/apps/web/src/lib/config.ts b/apps/web/src/lib/config.ts
index cdb8bfd..9974e3b 100644
--- a/apps/web/src/lib/config.ts
+++ b/apps/web/src/lib/config.ts
@@ -7,12 +7,19 @@
  * Environment Variables:
  * - NEXT_PUBLIC_API_URL: The main API server URL (default: http://localhost:3001)
  * - NEXT_PUBLIC_ORCHESTRATOR_URL: The orchestrator service URL (default: same as API URL)
+ * - NEXT_PUBLIC_AUTH_MODE: Auth mode for web app (`real` or `mock`)
+ *   - If unset: development defaults to `mock`, production defaults to `real`
  */
 
 /**
  * Default API server URL for local development
  */
 const DEFAULT_API_URL = "http://localhost:3001";
+const DEFAULT_AUTH_MODE = process.env.NODE_ENV === "development" ? "mock" : "real";
+
+const VALID_AUTH_MODES = ["real", "mock"] as const;
+
+export type AuthMode = (typeof VALID_AUTH_MODES)[number];
 
 /**
  * Main API server URL
@@ -20,6 +27,34 @@ const DEFAULT_API_URL = "http://localhost:3001";
  */
 export const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL ?? DEFAULT_API_URL;
 
+function resolveAuthMode(): AuthMode {
+  const rawMode = (process.env.NEXT_PUBLIC_AUTH_MODE ?? DEFAULT_AUTH_MODE).toLowerCase();
+
+  if (!VALID_AUTH_MODES.includes(rawMode as AuthMode)) {
+    throw new Error(
+      `Invalid NEXT_PUBLIC_AUTH_MODE "${rawMode}". Expected one of: ${VALID_AUTH_MODES.join(", ")}.`
+    );
+  }
+
+  if (rawMode === "mock" && process.env.NODE_ENV !== "development") {
+    throw new Error("NEXT_PUBLIC_AUTH_MODE=mock is only allowed when NODE_ENV=development.");
+  }
+
+  return rawMode as AuthMode;
+}
+
+/**
+ * Authentication mode for frontend runtime.
+ * - real: uses normal BetterAuth/Backend session flow
+ * - mock: local-only seeded mock user for FE development
+ */
+export const AUTH_MODE: AuthMode = resolveAuthMode();
+
+/**
+ * Whether local mock auth mode is enabled.
+ */
+export const IS_MOCK_AUTH_MODE = AUTH_MODE === "mock";
+
 /**
  * Orchestrator service URL
  * Used for agent management, task progress, and orchestration features
@@ -53,6 +88,8 @@ export const apiConfig = {
   baseUrl: API_BASE_URL,
   /** Orchestrator service URL */
   orchestratorUrl: ORCHESTRATOR_URL,
+  /** Authentication mode (`real` or `mock`) */
+  authMode: AUTH_MODE,
   /** Build full API URL for an endpoint */
   buildUrl: buildApiUrl,
   /** Build full orchestrator URL for an endpoint */
diff --git a/apps/web/src/lib/hooks/useLayout.ts b/apps/web/src/lib/hooks/useLayout.ts
index ef1d903..da5de87 100644
--- a/apps/web/src/lib/hooks/useLayout.ts
+++ b/apps/web/src/lib/hooks/useLayout.ts
@@ -14,6 +14,70 @@ const DEFAULT_LAYOUT_NAME = "default";
  */
 const WORKSPACE_KEY = "mosaic-workspace-id";
 
+function createDefaultLayout(): LayoutConfig {
+  return {
+    id: DEFAULT_LAYOUT_NAME,
+    name: "Default Layout",
+    layout: [
+      {
+        i: "tasks-1",
+        x: 0,
+        y: 0,
+        w: 2,
+        h: 3,
+        minW: 1,
+        minH: 2,
+        isDraggable: true,
+        isResizable: true,
+      },
+      {
+        i: "calendar-1",
+        x: 2,
+        y: 0,
+        w: 2,
+        h: 2,
+        minW: 1,
+        minH: 2,
+        isDraggable: true,
+        isResizable: true,
+      },
+      {
+        i: "agent-status-1",
+        x: 2,
+        y: 2,
+        w: 2,
+        h: 2,
+        minW: 1,
+        minH: 1,
+        isDraggable: true,
+        isResizable: true,
+      },
+      {
+        i: "orchestrator-events-1",
+        x: 0,
+        y: 3,
+        w: 2,
+        h: 2,
+        minW: 1,
+        minH: 1,
+        isDraggable: true,
+        isResizable: true,
+      },
+      {
+        i: "quick-capture-1",
+        x: 2,
+        y: 4,
+        w: 2,
+        h: 1,
+        minW: 1,
+        minH: 1,
+        isDraggable: true,
+        isResizable: true,
+      },
+    ],
+  };
+}
+
 interface UseLayoutReturn {
   layouts: Record<string, LayoutConfig>;
   currentLayout: LayoutConfig | undefined;
@@ -45,7 +109,18 @@ export function useLayout(): UseLayoutReturn {
       if (stored) {
         const emptyFallback: Record<string, LayoutConfig> = {};
         const parsed = safeJsonParse(stored, isLayoutConfigRecord, emptyFallback);
-        setLayouts(parsed as Record<string, LayoutConfig>);
+        const parsedLayouts = parsed as Record<string, LayoutConfig>;
+        if (Object.keys(parsedLayouts).length > 0) {
+          setLayouts(parsedLayouts);
+        } else {
+          setLayouts({
+            [DEFAULT_LAYOUT_NAME]: createDefaultLayout(),
+          });
+        }
+      } else {
+        setLayouts({
+          [DEFAULT_LAYOUT_NAME]: createDefaultLayout(),
+        });
       }
 
       // Load current layout ID preference
@@ -195,11 +270,7 @@ export function useLayout(): UseLayoutReturn {
 
   const resetLayout = useCallback(() => {
     setLayouts({
-      [DEFAULT_LAYOUT_NAME]: {
-        id: DEFAULT_LAYOUT_NAME,
-        name: "Default Layout",
-        layout: [],
-      },
+      [DEFAULT_LAYOUT_NAME]: createDefaultLayout(),
     });
     setCurrentLayoutId(DEFAULT_LAYOUT_NAME);
   }, []);
diff --git a/docker-compose.portainer.yml b/docker-compose.portainer.yml
deleted file mode 100644
index 54430b4..0000000
--- a/docker-compose.portainer.yml
+++ /dev/null
@@ -1,95 +0,0 @@
-# ==============================================
-# OpenBao Standalone Deployment - Portainer Version
-# ==============================================
-#
-# This file is optimized for Portainer deployment:
-# - No env_file directive (define variables in Portainer's environment editor)
-# - Port exposed on all interfaces (Portainer limitation)
-# - All environment variables explicitly defined
-#
-# Usage in Portainer:
-#   1. Stacks -> Add Stack
-#   2. Name: mosaic-openbao
-#   3. Paste this file content
-#   4. Add environment variables in "Environment variables" section:
-#      - IMAGE_TAG=dev
-#      - OPENBAO_PORT=8200
-#   5. Deploy
-#
-# SECURITY NOTE: Port 8200 will be exposed on 0.0.0.0 (all interfaces)
-# Use firewall rules to restrict access if needed.
-# ==============================================
-
-services:
-  # ======================
-  # OpenBao Secrets Vault
-  # ======================
-  openbao:
-    image: git.mosaicstack.dev/mosaic/stack-openbao:${IMAGE_TAG:-dev}
-    container_name: mosaic-openbao
-    entrypoint: ["dumb-init", "--"]
-    command: ["bao", "server", "-config=/openbao/config/config.hcl"]
-    environment:
-      OPENBAO_ADDR: http://0.0.0.0:8200
-    ports:
-      - "${OPENBAO_PORT:-8200}:8200"
-    volumes:
-      - openbao_data:/openbao/data
-      - openbao_logs:/openbao/logs
-      - openbao_init:/openbao/init
-    cap_add:
-      - IPC_LOCK
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          "wget --spider --quiet 'http://localhost:8200/v1/sys/health?standbyok=true&uninitcode=200&sealedcode=200'",
-        ]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-    restart: unless-stopped
-    networks:
-      - mosaic_internal
-
-  # ======================
-  # OpenBao Init Sidecar
-  # ======================
-  # Auto-initializes and unseals OpenBao on first run
-  openbao-init:
-    image: git.mosaicstack.dev/mosaic/stack-openbao:${IMAGE_TAG:-dev}
-    container_name: mosaic-openbao-init
-    command: /openbao/init.sh
-    environment:
-      OPENBAO_ADDR: http://openbao:8200
-    volumes:
-      - openbao_init:/openbao/init
-    depends_on:
-      - openbao
-    restart: "no"
-    networks:
-      - mosaic_internal
-
-# ======================
-# Volumes
-# ======================
-volumes:
-  openbao_data:
-    name: mosaic-openbao-data
-    driver: local
-  openbao_logs:
-    name: mosaic-openbao-logs
-    driver: local
-  openbao_init:
-    name: mosaic-openbao-init
-    driver: local
-
-# ======================
-# Networks
-# ======================
-# Connect to the swarm stack's internal network
-networks:
-  mosaic_internal:
-    external: true
-    name: mosaic_internal
diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml
deleted file mode 100644
index d248237..0000000
--- a/docker-compose.prod.yml
+++ /dev/null
@@ -1,180 +0,0 @@
-# Production Docker Compose - Uses pre-built images from Gitea Packages
-#
-# Prerequisites:
-#   - Images built and pushed to git.mosaicstack.dev/mosaic/*
-#   - .env file configured with production values
-#
-# Usage:
-#   docker compose -f docker-compose.prod.yml up -d
-#
-# For Portainer:
-#   - Stack → Add Stack → Repository
-#   - Compose file: docker-compose.prod.yml
-
-services:
-  # ======================
-  # PostgreSQL Database
-  # ======================
-  postgres:
-    image: git.mosaicstack.dev/mosaic/stack-postgres:${IMAGE_TAG:-latest}
-    container_name: mosaic-postgres
-    restart: unless-stopped
-    environment:
-      POSTGRES_USER: ${POSTGRES_USER:-mosaic}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-      POSTGRES_DB: ${POSTGRES_DB:-mosaic}
-      POSTGRES_SHARED_BUFFERS: ${POSTGRES_SHARED_BUFFERS:-256MB}
-      POSTGRES_EFFECTIVE_CACHE_SIZE: ${POSTGRES_EFFECTIVE_CACHE_SIZE:-1GB}
-      POSTGRES_MAX_CONNECTIONS: ${POSTGRES_MAX_CONNECTIONS:-100}
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-mosaic} -d ${POSTGRES_DB:-mosaic}"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-    networks:
-      - mosaic-internal
-    labels:
-      - "com.mosaic.service=database"
-      - "com.mosaic.description=PostgreSQL 17 with pgvector"
-
-  # ======================
-  # Valkey Cache
-  # ======================
-  valkey:
-    image: valkey/valkey:8-alpine
-    container_name: mosaic-valkey
-    restart: unless-stopped
-    command:
-      - valkey-server
-      - --maxmemory ${VALKEY_MAXMEMORY:-256mb}
-      - --maxmemory-policy noeviction
-      - --appendonly yes
-    volumes:
-      - valkey_data:/data
-    healthcheck:
-      test: ["CMD", "valkey-cli", "ping"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 10s
-    networks:
-      - mosaic-internal
-    labels:
-      - "com.mosaic.service=cache"
-      - "com.mosaic.description=Valkey Redis-compatible cache"
-
-  # ======================
-  # Mosaic API
-  # ======================
-  api:
-    image: git.mosaicstack.dev/mosaic/stack-api:${IMAGE_TAG:-latest}
-    container_name: mosaic-api
-    restart: unless-stopped
-    environment:
-      NODE_ENV: production
-      PORT: ${API_PORT:-3001}
-      API_HOST: ${API_HOST:-0.0.0.0}
-      DATABASE_URL: postgresql://${POSTGRES_USER:-mosaic}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-mosaic}
-      VALKEY_URL: redis://valkey:6379
-      OIDC_ISSUER: ${OIDC_ISSUER}
-      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
-      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
-      OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI}
-      JWT_SECRET: ${JWT_SECRET}
-      JWT_EXPIRATION: ${JWT_EXPIRATION:-24h}
-      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
-      OLLAMA_ENDPOINT: ${OLLAMA_ENDPOINT:-http://ollama:11434}
-    ports:
-      - "${API_PORT:-3001}:${API_PORT:-3001}"
-    depends_on:
-      postgres:
-        condition: service_healthy
-      valkey:
-        condition: service_healthy
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          'node -e "require(''http'').get(''http://localhost:${API_PORT:-3001}/health'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
-        ]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    networks:
-      - mosaic-internal
-      - mosaic-public
-    labels:
-      - "com.mosaic.service=api"
-      - "com.mosaic.description=Mosaic NestJS API"
-      - "traefik.enable=${TRAEFIK_ENABLE:-false}"
-      - "traefik.http.routers.mosaic-api.rule=Host(`${MOSAIC_API_DOMAIN:-api.mosaicstack.dev}`)"
-      - "traefik.http.routers.mosaic-api.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
-      - "traefik.http.routers.mosaic-api.tls=${TRAEFIK_TLS_ENABLED:-true}"
-      - "traefik.http.services.mosaic-api.loadbalancer.server.port=${API_PORT:-3001}"
-      - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-mosaic-public}"
-      - "traefik.http.routers.mosaic-api.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
-
-  # ======================
-  # Mosaic Web
-  # ======================
-  web:
-    image: git.mosaicstack.dev/mosaic/stack-web:${IMAGE_TAG:-latest}
-    container_name: mosaic-web
-    restart: unless-stopped
-    environment:
-      NODE_ENV: production
-      PORT: ${WEB_PORT:-3000}
-      NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-https://api.mosaicstack.dev}
-    ports:
-      - "${WEB_PORT:-3000}:${WEB_PORT:-3000}"
-    depends_on:
-      api:
-        condition: service_healthy
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          'node -e "require(''http'').get(''http://localhost:${WEB_PORT:-3000}'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
-        ]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    networks:
-      - mosaic-public
-    labels:
-      - "com.mosaic.service=web"
-      - "com.mosaic.description=Mosaic Next.js Web App"
-      - "traefik.enable=${TRAEFIK_ENABLE:-false}"
-      - "traefik.http.routers.mosaic-web.rule=Host(`${MOSAIC_WEB_DOMAIN:-app.mosaicstack.dev}`)"
-      - "traefik.http.routers.mosaic-web.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
-      - "traefik.http.routers.mosaic-web.tls=${TRAEFIK_TLS_ENABLED:-true}"
-      - "traefik.http.services.mosaic-web.loadbalancer.server.port=${WEB_PORT:-3000}"
-      - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-mosaic-public}"
-      - "traefik.http.routers.mosaic-web.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
-
-# ======================
-# Volumes
-# ======================
-volumes:
-  postgres_data:
-    name: mosaic-postgres-data
-    driver: local
-  valkey_data:
-    name: mosaic-valkey-data
-    driver: local
-
-# ======================
-# Networks
-# ======================
-networks:
-  mosaic-internal:
-    name: mosaic-internal
-    driver: bridge
-  mosaic-public:
-    name: mosaic-public
-    driver: bridge
diff --git a/docker-compose.speech.yml b/docker-compose.speech.yml
deleted file mode 100644
index 855a947..0000000
--- a/docker-compose.speech.yml
+++ /dev/null
@@ -1,113 +0,0 @@
-# ==============================================
-# Speech Services - Docker Compose Dev Overlay
-# ==============================================
-#
-# Adds STT and TTS services for local development.
-#
-# Usage:
-#   Basic (STT + default TTS):
-#     docker compose -f docker-compose.yml -f docker-compose.speech.yml up -d
-#
-#   With premium TTS (requires GPU):
-#     docker compose -f docker-compose.yml -f docker-compose.speech.yml --profile premium-tts up -d
-#
-#   Or use Makefile targets:
-#     make speech-up              # Basic speech services
-#     make speech-down            # Stop speech services
-#     make speech-logs            # View speech service logs
-# ==============================================
-
-services:
-  # ======================
-  # Speaches (STT + basic TTS)
-  # ======================
-  speaches:
-    image: ghcr.io/speaches-ai/speaches:latest
-    container_name: mosaic-speaches
-    restart: unless-stopped
-    environment:
-      WHISPER__MODEL: ${SPEACHES_WHISPER_MODEL:-Systran/faster-whisper-large-v3-turbo}
-    ports:
-      - "${SPEACHES_PORT:-8090}:8000"
-    volumes:
-      - speaches_models:/root/.cache/huggingface
-    healthcheck:
-      test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
-      interval: 30s
-      timeout: 10s
-      retries: 5
-      start_period: 120s
-    networks:
-      - mosaic-internal
-    labels:
-      - "com.mosaic.service=speech-stt"
-      - "com.mosaic.description=Speaches STT (Whisper) and basic TTS"
-
-  # ======================
-  # Kokoro TTS (Default TTS)
-  # ======================
-  kokoro-tts:
-    image: ghcr.io/remsky/kokoro-fastapi:latest-cpu
-    container_name: mosaic-kokoro-tts
-    restart: unless-stopped
-    ports:
-      - "${KOKORO_TTS_PORT:-8880}:8880"
-    healthcheck:
-      test: ["CMD-SHELL", "curl -f http://localhost:8880/health || exit 1"]
-      interval: 30s
-      timeout: 10s
-      retries: 5
-      start_period: 120s
-    networks:
-      - mosaic-internal
-    labels:
-      - "com.mosaic.service=speech-tts"
-      - "com.mosaic.description=Kokoro FastAPI TTS engine"
-
-  # ======================
-  # Chatterbox TTS (Premium TTS - Optional)
-  # ======================
-  # Only starts with: --profile premium-tts
-  # Requires NVIDIA GPU with docker nvidia runtime
-  chatterbox-tts:
-    image: devnen/chatterbox-tts-server:latest
-    container_name: mosaic-chatterbox-tts
-    restart: unless-stopped
-    ports:
-      - "${CHATTERBOX_TTS_PORT:-8881}:8000"
-    profiles:
-      - premium-tts
-    deploy:
-      resources:
-        reservations:
-          devices:
-            - driver: nvidia
-              count: 1
-              capabilities: [gpu]
-    healthcheck:
-      test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
-      interval: 30s
-      timeout: 10s
-      retries: 5
-      start_period: 180s
-    networks:
-      - mosaic-internal
-    labels:
-      - "com.mosaic.service=speech-tts-premium"
-      - "com.mosaic.description=Chatterbox premium TTS with voice cloning (GPU)"
-
-# ======================
-# Volumes
-# ======================
-volumes:
-  speaches_models:
-    name: mosaic-speaches-models
-    driver: local
-
-# ======================
-# Networks
-# ======================
-networks:
-  mosaic-internal:
-    external: true
-    name: mosaic-internal
diff --git a/docker-compose.swarm.portainer.yml b/docker-compose.swarm.portainer.yml
index a544963..3f90de0 100644
--- a/docker-compose.swarm.portainer.yml
+++ b/docker-compose.swarm.portainer.yml
@@ -1,48 +1,63 @@
 # ==============================================
-# Mosaic Stack - Docker Swarm Deployment
+# Mosaic Stack — Docker Swarm / Portainer
 # ==============================================
 #
-# IMPORTANT: Docker Swarm does NOT support docker-compose profiles
-# To disable services (e.g., for external alternatives), manually comment them out
+# The canonical deployment file for Mosaic Stack on Docker Swarm.
+# Includes all services except OpenBao (standalone) and external services.
 #
-# Current Configuration:
-#   - PostgreSQL: ENABLED (internal)
-#   - Valkey: ENABLED (internal)
-#   - Coordinator: ENABLED (internal)
-#   - OpenBao: DISABLED (must use standalone - see docker-compose.openbao.yml)
-#   - Authentik: DISABLED (commented out - using external OIDC)
-#   - Ollama: DISABLED (commented out - using external Ollama)
+# External services (not in this file):
+#   - OpenBao: Standalone container (see docker-compose.openbao.yml)
+#   - Authentik: External OIDC provider
+#   - Ollama: External AI inference
 #
-# For detailed deployment instructions, see:
-#   docs/SWARM-DEPLOYMENT.md
+# Usage (Portainer):
+#   1. Stacks -> Add Stack -> Upload or paste
+#   2. Set environment variables (see .env.example for full reference)
+#   3. Deploy
 #
-# Quick Start:
-#   1. cp .env.swarm.example .env
-#   2. nano .env  # Configure environment
-#   3. ./scripts/deploy-swarm.sh mosaic
-#   4. Initialize OpenBao manually (see docs/SWARM-DEPLOYMENT.md)
+# Usage (CLI):
+#   docker stack deploy -c docker-compose.swarm.portainer.yml mosaic
+#
+# Host paths required for Matrix:
+#   /opt/mosaic/synapse/homeserver.yaml
+#   /opt/mosaic/synapse/element-config.json
+#   /opt/mosaic/synapse/media_store/    (auto-populated)
+#   /opt/mosaic/synapse/keys/           (auto-populated)
+#
+# ==============================================
+# ENVIRONMENT VARIABLE CONVENTION
+# ==============================================
+#
+#   ${VAR}           — REQUIRED. Must be set in Portainer env vars.
+#   ${VAR:-default}  — OPTIONAL. Falls back to a sensible default.
+#   ${VAR:-}         — OPTIONAL. Empty string is acceptable.
+#
+# NOTE: Portainer does not support ${VAR:?msg} syntax.
+# Required vars use plain ${VAR} — the app validates at startup.
 #
 # ==============================================
 
 services:
+  # ============================================
+  #  CORE INFRASTRUCTURE
+  # ============================================
+
   # ======================
   # PostgreSQL Database
   # ======================
   postgres:
     image: git.mosaicstack.dev/mosaic/stack-postgres:${IMAGE_TAG:-latest}
     environment:
-      POSTGRES_USER: ${POSTGRES_USER:-mosaic}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-mosaic_dev_password}
-      POSTGRES_DB: ${POSTGRES_DB:-mosaic}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
       POSTGRES_SHARED_BUFFERS: ${POSTGRES_SHARED_BUFFERS:-256MB}
       POSTGRES_EFFECTIVE_CACHE_SIZE: ${POSTGRES_EFFECTIVE_CACHE_SIZE:-1GB}
       POSTGRES_MAX_CONNECTIONS: ${POSTGRES_MAX_CONNECTIONS:-100}
     volumes:
       - postgres_data:/var/lib/postgresql/data
-      # Note: init-scripts bind mount removed for Portainer compatibility
-      # Init scripts are baked into the postgres image at build time
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-mosaic} -d ${POSTGRES_DB:-mosaic}"]
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
       interval: 10s
       timeout: 5s
       retries: 5
@@ -77,168 +92,113 @@ services:
       restart_policy:
         condition: on-failure
 
-  # ======================
-  # OpenBao Secrets Vault - COMMENTED OUT
-  # ======================
-  # IMPORTANT: OpenBao CANNOT run in swarm mode due to port binding conflicts.
-  # Deploy OpenBao as a standalone container instead:
-  #   docker compose -f docker-compose.openbao.yml up -d
-  #
-  # Alternative: Use external HashiCorp Vault or managed secrets service
-  #
-  # openbao:
-  #   image: git.mosaicstack.dev/mosaic/stack-openbao:${IMAGE_TAG:-latest}
-  #   environment:
-  #     OPENBAO_ADDR: ${OPENBAO_ADDR:-http://0.0.0.0:8200}
-  #     OPENBAO_DEV_ROOT_TOKEN_ID: ${OPENBAO_DEV_ROOT_TOKEN_ID:-root}
-  #   volumes:
-  #     - openbao_data:/openbao/data
-  #     - openbao_logs:/openbao/logs
-  #     - openbao_init:/openbao/init
-  #   cap_add:
-  #     - IPC_LOCK
-  #   healthcheck:
-  #     test:
-  #       ["CMD", "wget", "--spider", "--quiet", "http://localhost:8200/v1/sys/health?standbyok=true"]
-  #     interval: 10s
-  #     timeout: 5s
-  #     retries: 5
-  #     start_period: 30s
-  #   networks:
-  #     - internal
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
+  # ============================================
+  #  MOSAIC APPLICATION
+  # ============================================
 
   # ======================
-  # Authentik - COMMENTED OUT (Using External Authentik)
+  # Mosaic API
   # ======================
-  # Uncomment these services if you want to run Authentik internally
-  # For external Authentik, configure OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET in .env
-  #
-  # authentik-postgres:
-  #   image: postgres:17.7-alpine3.22
-  #   environment:
-  #     POSTGRES_USER: ${AUTHENTIK_POSTGRES_USER:-authentik}
-  #     POSTGRES_PASSWORD: ${AUTHENTIK_POSTGRES_PASSWORD:-authentik_password}
-  #     POSTGRES_DB: ${AUTHENTIK_POSTGRES_DB:-authentik}
-  #   volumes:
-  #     - authentik_postgres_data:/var/lib/postgresql/data
-  #   healthcheck:
-  #     test: ["CMD-SHELL", "pg_isready -U ${AUTHENTIK_POSTGRES_USER:-authentik}"]
-  #     interval: 10s
-  #     timeout: 5s
-  #     retries: 5
-  #     start_period: 20s
-  #   networks:
-  #     - internal
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
-  #
-  # authentik-redis:
-  #   image: valkey/valkey:8-alpine
-  #   command: valkey-server --save 60 1 --loglevel warning
-  #   volumes:
-  #     - authentik_redis_data:/data
-  #   healthcheck:
-  #     test: ["CMD", "valkey-cli", "ping"]
-  #     interval: 10s
-  #     timeout: 5s
-  #     retries: 5
-  #     start_period: 10s
-  #   networks:
-  #     - internal
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
-  #
-  # authentik-server:
-  #   image: ghcr.io/goauthentik/server:2024.12.1
-  #   command: server
-  #   environment:
-  #     AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:-change-this-to-a-random-secret}
-  #     AUTHENTIK_ERROR_REPORTING__ENABLED: ${AUTHENTIK_ERROR_REPORTING:-false}
-  #     AUTHENTIK_POSTGRESQL__HOST: authentik-postgres
-  #     AUTHENTIK_POSTGRESQL__PORT: 5432
-  #     AUTHENTIK_POSTGRESQL__NAME: ${AUTHENTIK_POSTGRES_DB:-authentik}
-  #     AUTHENTIK_POSTGRESQL__USER: ${AUTHENTIK_POSTGRES_USER:-authentik}
-  #     AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_POSTGRES_PASSWORD:-authentik_password}
-  #     AUTHENTIK_REDIS__HOST: authentik-redis
-  #     AUTHENTIK_REDIS__PORT: 6379
-  #     AUTHENTIK_BOOTSTRAP_PASSWORD: ${AUTHENTIK_BOOTSTRAP_PASSWORD:-admin}
-  #     AUTHENTIK_BOOTSTRAP_EMAIL: ${AUTHENTIK_BOOTSTRAP_EMAIL:-admin@localhost}
-  #     AUTHENTIK_COOKIE_DOMAIN: ${AUTHENTIK_COOKIE_DOMAIN:-.mosaicstack.dev}
-  #   volumes:
-  #     - authentik_media:/media
-  #     - authentik_templates:/templates
-  #   healthcheck:
-  #     test:
-  #       [
-  #         "CMD",
-  #         "wget",
-  #         "--no-verbose",
-  #         "--tries=1",
-  #         "--spider",
-  #         "http://localhost:9000/-/health/live/",
-  #       ]
-  #     interval: 30s
-  #     timeout: 10s
-  #     retries: 3
-  #     start_period: 90s
-  #   networks:
-  #     - internal
-  #     - traefik-public
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
-  #     labels:
-  #       - "traefik.enable=true"
-  #       - "traefik.http.routers.mosaic-auth.rule=Host(`${MOSAIC_AUTH_DOMAIN:-auth.mosaicstack.dev}`)"
-  #       - "traefik.http.routers.mosaic-auth.entrypoints=web"
-  #       - "traefik.http.services.mosaic-auth.loadbalancer.server.port=9000"
-  #
-  # authentik-worker:
-  #   image: ghcr.io/goauthentik/server:2024.12.1
-  #   command: worker
-  #   environment:
-  #     AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:-change-this-to-a-random-secret}
-  #     AUTHENTIK_ERROR_REPORTING__ENABLED: ${AUTHENTIK_ERROR_REPORTING:-false}
-  #     AUTHENTIK_POSTGRESQL__HOST: authentik-postgres
-  #     AUTHENTIK_POSTGRESQL__PORT: 5432
-  #     AUTHENTIK_POSTGRESQL__NAME: ${AUTHENTIK_POSTGRES_DB:-authentik}
-  #     AUTHENTIK_POSTGRESQL__USER: ${AUTHENTIK_POSTGRES_USER:-authentik}
-  #     AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_POSTGRES_PASSWORD:-authentik_password}
-  #     AUTHENTIK_REDIS__HOST: authentik-redis
-  #     AUTHENTIK_REDIS__PORT: 6379
-  #   volumes:
-  #     - authentik_media:/media
-  #     - authentik_certs:/certs
-  #     - authentik_templates:/templates
-  #   networks:
-  #     - internal
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
+  api:
+    image: git.mosaicstack.dev/mosaic/stack-api:${IMAGE_TAG:-latest}
+    environment:
+      NODE_ENV: production
+      PORT: ${API_PORT:-3001}
+      API_HOST: ${API_HOST:-0.0.0.0}
+      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+      VALKEY_URL: redis://valkey:6379
+      # Auth (external Authentik)
+      OIDC_ENABLED: ${OIDC_ENABLED:-false}
+      OIDC_ISSUER: ${OIDC_ISSUER}
+      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
+      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
+      OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI:-}
+      JWT_SECRET: ${JWT_SECRET:-change-this-to-a-random-secret}
+      JWT_EXPIRATION: ${JWT_EXPIRATION:-24h}
+      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      CSRF_SECRET: ${CSRF_SECRET}
+      # External services
+      OLLAMA_ENDPOINT: ${OLLAMA_ENDPOINT}
+      OPENBAO_ADDR: ${OPENBAO_ADDR}
+      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
+      # Matrix bridge (optional — configure after Synapse is running)
+      MATRIX_HOMESERVER_URL: ${MATRIX_HOMESERVER_URL:-http://synapse:8008}
+      MATRIX_ACCESS_TOKEN: ${MATRIX_ACCESS_TOKEN:-}
+      MATRIX_BOT_USER_ID: ${MATRIX_BOT_USER_ID:-}
+      MATRIX_CONTROL_ROOM_ID: ${MATRIX_CONTROL_ROOM_ID:-}
+      MATRIX_WORKSPACE_ID: ${MATRIX_WORKSPACE_ID:-}
+      MATRIX_SERVER_NAME: ${MATRIX_SERVER_NAME:-}
+      # Speech
+      SPEECH_MAX_UPLOAD_SIZE: ${SPEECH_MAX_UPLOAD_SIZE:-25000000}
+      SPEECH_MAX_DURATION_SECONDS: ${SPEECH_MAX_DURATION_SECONDS:-600}
+      SPEECH_MAX_TEXT_LENGTH: ${SPEECH_MAX_TEXT_LENGTH:-4096}
+      # Telemetry (disabled by default)
+      MOSAIC_TELEMETRY_ENABLED: ${MOSAIC_TELEMETRY_ENABLED:-false}
+      MOSAIC_TELEMETRY_SERVER_URL: ${MOSAIC_TELEMETRY_SERVER_URL:-}
+      MOSAIC_TELEMETRY_API_KEY: ${MOSAIC_TELEMETRY_API_KEY:-}
+      MOSAIC_TELEMETRY_INSTANCE_ID: ${MOSAIC_TELEMETRY_INSTANCE_ID:-}
+      MOSAIC_TELEMETRY_DRY_RUN: ${MOSAIC_TELEMETRY_DRY_RUN:-false}
+      # Frontend URLs (for CORS and auth redirects)
+      NEXT_PUBLIC_APP_URL: ${NEXT_PUBLIC_APP_URL}
+      NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL}
+      TRUSTED_ORIGINS: ${TRUSTED_ORIGINS:-}
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          'node -e "require(''http'').get(''http://localhost:${API_PORT:-3001}/health'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
+        ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    networks:
+      - internal
+      - traefik-public
+    deploy:
+      restart_policy:
+        condition: on-failure
+      labels:
+        - "traefik.enable=true"
+        - "traefik.http.routers.mosaic-api.rule=Host(`${MOSAIC_API_DOMAIN}`)"
+        - "traefik.http.routers.mosaic-api.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
+        - "traefik.http.routers.mosaic-api.tls=${TRAEFIK_TLS_ENABLED:-true}"
+        - "traefik.http.routers.mosaic-api.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
+        - "traefik.http.services.mosaic-api.loadbalancer.server.port=${API_PORT:-3001}"
+        - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-traefik-public}"
 
   # ======================
-  # Ollama (Optional AI Service)
+  # Mosaic Web
   # ======================
-  # ollama:
-  #   image: ollama/ollama:latest
-  #   volumes:
-  #     - ollama_data:/root/.ollama
-  #   healthcheck:
-  #     test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
-  #     interval: 30s
-  #     timeout: 10s
-  #     retries: 3
-  #     start_period: 60s
-  #   networks:
-  #     - internal
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
+  web:
+    image: git.mosaicstack.dev/mosaic/stack-web:${IMAGE_TAG:-latest}
+    environment:
+      NODE_ENV: production
+      PORT: ${WEB_PORT:-3000}
+      NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL}
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          'node -e "require(''http'').get(''http://localhost:${WEB_PORT:-3000}'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
+        ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    networks:
+      - traefik-public
+    deploy:
+      restart_policy:
+        condition: on-failure
+      labels:
+        - "traefik.enable=true"
+        - "traefik.http.routers.mosaic-web.rule=Host(`${MOSAIC_WEB_DOMAIN}`)"
+        - "traefik.http.routers.mosaic-web.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
+        - "traefik.http.routers.mosaic-web.tls=${TRAEFIK_TLS_ENABLED:-true}"
+        - "traefik.http.routers.mosaic-web.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
+        - "traefik.http.services.mosaic-web.loadbalancer.server.port=${WEB_PORT:-3000}"
+        - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-traefik-public}"
 
   # ======================
   # Mosaic Coordinator
@@ -247,7 +207,7 @@ services:
     image: git.mosaicstack.dev/mosaic/stack-coordinator:${IMAGE_TAG:-latest}
     environment:
       GITEA_WEBHOOK_SECRET: ${GITEA_WEBHOOK_SECRET}
-      GITEA_URL: ${GITEA_URL:-https://git.mosaicstack.dev}
+      GITEA_URL: ${GITEA_URL}
       ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
       LOG_LEVEL: ${LOG_LEVEL:-info}
       HOST: 0.0.0.0
@@ -255,9 +215,9 @@ services:
       COORDINATOR_POLL_INTERVAL: ${COORDINATOR_POLL_INTERVAL:-5.0}
       COORDINATOR_MAX_CONCURRENT_AGENTS: ${COORDINATOR_MAX_CONCURRENT_AGENTS:-10}
       COORDINATOR_ENABLED: ${COORDINATOR_ENABLED:-true}
-      # Telemetry (task completion tracking & predictions)
+      # Telemetry (disabled by default)
       MOSAIC_TELEMETRY_ENABLED: ${MOSAIC_TELEMETRY_ENABLED:-false}
-      MOSAIC_TELEMETRY_SERVER_URL: ${MOSAIC_TELEMETRY_SERVER_URL:-https://tel-api.mosaicstack.dev}
+      MOSAIC_TELEMETRY_SERVER_URL: ${MOSAIC_TELEMETRY_SERVER_URL:-}
       MOSAIC_TELEMETRY_API_KEY: ${MOSAIC_TELEMETRY_API_KEY:-}
       MOSAIC_TELEMETRY_INSTANCE_ID: ${MOSAIC_TELEMETRY_INSTANCE_ID:-}
       MOSAIC_TELEMETRY_DRY_RUN: ${MOSAIC_TELEMETRY_DRY_RUN:-false}
@@ -279,56 +239,6 @@ services:
       restart_policy:
         condition: on-failure
 
-  # ======================
-  # Mosaic API
-  # ======================
-  api:
-    image: git.mosaicstack.dev/mosaic/stack-api:${IMAGE_TAG:-latest}
-    environment:
-      NODE_ENV: production
-      PORT: ${API_PORT:-3001}
-      API_HOST: ${API_HOST:-0.0.0.0}
-      DATABASE_URL: postgresql://${POSTGRES_USER:-mosaic}:${POSTGRES_PASSWORD:-mosaic_dev_password}@postgres:5432/${POSTGRES_DB:-mosaic}
-      VALKEY_URL: redis://valkey:6379
-      OIDC_ISSUER: ${OIDC_ISSUER}
-      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
-      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
-      OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI:-}
-      JWT_SECRET: ${JWT_SECRET:-change-this-to-a-random-secret}
-      JWT_EXPIRATION: ${JWT_EXPIRATION:-24h}
-      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
-      CSRF_SECRET: ${CSRF_SECRET}
-      OLLAMA_ENDPOINT: ${OLLAMA_ENDPOINT:-http://ollama:11434}
-      OPENBAO_ADDR: ${OPENBAO_ADDR:-http://openbao:8200}
-      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
-      # Telemetry (task completion tracking & predictions)
-      MOSAIC_TELEMETRY_ENABLED: ${MOSAIC_TELEMETRY_ENABLED:-false}
-      MOSAIC_TELEMETRY_SERVER_URL: ${MOSAIC_TELEMETRY_SERVER_URL:-https://tel-api.mosaicstack.dev}
-      MOSAIC_TELEMETRY_API_KEY: ${MOSAIC_TELEMETRY_API_KEY:-}
-      MOSAIC_TELEMETRY_INSTANCE_ID: ${MOSAIC_TELEMETRY_INSTANCE_ID:-}
-      MOSAIC_TELEMETRY_DRY_RUN: ${MOSAIC_TELEMETRY_DRY_RUN:-false}
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          'node -e "require(''http'').get(''http://localhost:${API_PORT:-3001}/health'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
-        ]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    networks:
-      - internal
-      - traefik-public
-    deploy:
-      restart_policy:
-        condition: on-failure
-      labels:
-        - "traefik.enable=true"
-        - "traefik.http.routers.mosaic-api.rule=Host(`${MOSAIC_API_DOMAIN:-api.mosaicstack.dev}`)"
-        - "traefik.http.routers.mosaic-api.entrypoints=web"
-        - "traefik.http.services.mosaic-api.loadbalancer.server.port=${API_PORT:-3001}"
-
   # ======================
   # Mosaic Orchestrator
   # ======================
@@ -338,7 +248,11 @@ services:
     environment:
       NODE_ENV: production
       ORCHESTRATOR_PORT: 3001
+      AI_PROVIDER: ${AI_PROVIDER:-ollama}
       VALKEY_URL: redis://valkey:6379
+      VALKEY_HOST: valkey
+      VALKEY_PORT: 6379
+      # Claude API (required only when AI_PROVIDER=claude)
       CLAUDE_API_KEY: ${CLAUDE_API_KEY}
       DOCKER_SOCKET: /var/run/docker.sock
       GIT_USER_NAME: "Mosaic Orchestrator"
@@ -350,15 +264,16 @@ services:
       - orchestrator_workspace:/workspace
     healthcheck:
       test:
-        ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3001/health || exit 1"]
+        [
+          "CMD-SHELL",
+          'node -e "require(''http'').get(''http://localhost:3001/health'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
+        ]
       interval: 30s
       timeout: 10s
       retries: 3
       start_period: 40s
     networks:
       - internal
-    # Note: security_opt not supported in swarm mode
-    # Security hardening done via cap_drop/cap_add
     cap_drop:
       - ALL
     cap_add:
@@ -369,35 +284,152 @@ services:
       restart_policy:
         condition: on-failure
 
+  # ============================================
+  #  MATRIX (Synapse + Element Web)
+  # ============================================
+
   # ======================
-  # Mosaic Web
+  # Synapse Database Init
   # ======================
-  web:
-    image: git.mosaicstack.dev/mosaic/stack-web:${IMAGE_TAG:-latest}
+  # Creates the 'synapse' database in the shared PostgreSQL instance.
+  # Runs once and exits. Idempotent — safe to run on every deploy.
+  synapse-db-init:
+    image: postgres:17-alpine
     environment:
-      NODE_ENV: production
-      PORT: ${WEB_PORT:-3000}
-      NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-http://localhost:3001}
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          'node -e "require(''http'').get(''http://localhost:${WEB_PORT:-3000}'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
-        ]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
+      PGHOST: postgres
+      PGPORT: 5432
+      PGUSER: ${POSTGRES_USER}
+      PGPASSWORD: ${POSTGRES_PASSWORD}
+      SYNAPSE_DB: ${SYNAPSE_POSTGRES_DB}
+      SYNAPSE_USER: ${SYNAPSE_POSTGRES_USER}
+      SYNAPSE_PASSWORD: ${SYNAPSE_POSTGRES_PASSWORD}
+    entrypoint: ["sh", "-c"]
+    command:
+      - |
+        until pg_isready -h postgres -p 5432 -U $${PGUSER}; do
+          echo "Waiting for PostgreSQL..."
+          sleep 2
+        done
+        echo "PostgreSQL is ready. Creating Synapse database and user..."
+
+        psql -h postgres -U $${PGUSER} -tc "SELECT 1 FROM pg_roles WHERE rolname='$${SYNAPSE_USER}'" | grep -q 1 || \
+          psql -h postgres -U $${PGUSER} -c "CREATE USER $${SYNAPSE_USER} WITH PASSWORD '$${SYNAPSE_PASSWORD}';"
+
+        psql -h postgres -U $${PGUSER} -tc "SELECT 1 FROM pg_database WHERE datname='$${SYNAPSE_DB}'" | grep -q 1 || \
+          psql -h postgres -U $${PGUSER} -c "CREATE DATABASE $${SYNAPSE_DB} OWNER $${SYNAPSE_USER} ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE template0;"
+
+        echo "Synapse database ready: $${SYNAPSE_DB}"
     networks:
+      - internal
+    deploy:
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+        max_attempts: 5
+
+  # ======================
+  # Synapse (Matrix Homeserver)
+  # ======================
+  synapse:
+    image: matrixdotorg/synapse:${SYNAPSE_IMAGE_TAG:-latest}
+    environment:
+      SYNAPSE_CONFIG_DIR: /data
+      SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
+    volumes:
+      - /opt/mosaic/synapse:/data
+    healthcheck:
+      test: ["CMD-SHELL", "curl -fSs http://localhost:8008/health || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    networks:
+      - internal
       - traefik-public
     deploy:
       restart_policy:
         condition: on-failure
+        delay: 10s
+        max_attempts: 10
       labels:
         - "traefik.enable=true"
-        - "traefik.http.routers.mosaic-web.rule=Host(`${MOSAIC_WEB_DOMAIN:-mosaic.mosaicstack.dev}`)"
-        - "traefik.http.routers.mosaic-web.entrypoints=web"
-        - "traefik.http.services.mosaic-web.loadbalancer.server.port=${WEB_PORT:-3000}"
+        - "traefik.http.routers.matrix.rule=Host(`${MATRIX_DOMAIN}`)"
+        - "traefik.http.routers.matrix.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
+        - "traefik.http.routers.matrix.tls=${TRAEFIK_TLS_ENABLED:-true}"
+        - "traefik.http.routers.matrix.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
+        - "traefik.http.services.matrix.loadbalancer.server.port=8008"
+        - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-traefik-public}"
+
+  # ======================
+  # Element Web (Matrix Client)
+  # ======================
+  element-web:
+    image: vectorim/element-web:${ELEMENT_IMAGE_TAG:-latest}
+    volumes:
+      - /opt/mosaic/synapse/element-config.json:/app/config.json:ro
+    healthcheck:
+      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:80 || exit 1"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    networks:
+      - internal
+      - traefik-public
+    deploy:
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+      labels:
+        - "traefik.enable=true"
+        - "traefik.http.routers.element.rule=Host(`${ELEMENT_DOMAIN}`)"
+        - "traefik.http.routers.element.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
+        - "traefik.http.routers.element.tls=${TRAEFIK_TLS_ENABLED:-true}"
+        - "traefik.http.routers.element.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
+        - "traefik.http.services.element.loadbalancer.server.port=80"
+        - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-traefik-public}"
+
+  # ============================================
+  #  SPEECH SERVICES
+  # ============================================
+
+  # ======================
+  # Speaches (STT + basic TTS)
+  # ======================
+  speaches:
+    image: ghcr.io/speaches-ai/speaches:latest-cpu
+    environment:
+      WHISPER__MODEL: ${SPEACHES_WHISPER_MODEL:-Systran/faster-whisper-large-v3-turbo}
+    volumes:
+      - speaches_models:/root/.cache/huggingface
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
+    networks:
+      - internal
+    deploy:
+      restart_policy:
+        condition: on-failure
+
+  # ======================
+  # Kokoro TTS
+  # ======================
+  kokoro-tts:
+    image: ghcr.io/remsky/kokoro-fastapi-cpu:latest
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:8880/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
+    networks:
+      - internal
+    deploy:
+      restart_policy:
+        condition: on-failure
 
 # ======================
 # Volumes
@@ -405,19 +437,8 @@ services:
 volumes:
   postgres_data:
   valkey_data:
-  # OpenBao volumes - commented out (using standalone deployment)
-  # openbao_data:
-  # openbao_logs:
-  # openbao_init:
-  # Authentik volumes - commented out (using external Authentik)
-  # authentik_postgres_data:
-  # authentik_redis_data:
-  # authentik_media:
-  # authentik_certs:
-  # authentik_templates:
-  # Ollama volume - commented out (using external Ollama)
-  # ollama_data:
   orchestrator_workspace:
+  speaches_models:
 
 # ======================
 # Networks
diff --git a/docker-compose.swarm.yml b/docker-compose.swarm.yml
deleted file mode 100644
index 1d3b1af..0000000
--- a/docker-compose.swarm.yml
+++ /dev/null
@@ -1,459 +0,0 @@
-# ==============================================
-# Mosaic Stack - Docker Swarm Deployment
-# ==============================================
-#
-# IMPORTANT: Docker Swarm does NOT support docker-compose profiles
-# To disable services (e.g., for external alternatives), manually comment them out
-#
-# Current Configuration:
-#   - PostgreSQL: ENABLED (internal)
-#   - Valkey: ENABLED (internal)
-#   - Coordinator: ENABLED (internal)
-#   - OpenBao: DISABLED (must use standalone - see docker-compose.openbao.yml)
-#   - Authentik: DISABLED (commented out - using external OIDC)
-#   - Ollama: DISABLED (commented out - using external Ollama)
-#
-# For detailed deployment instructions, see:
-#   docs/SWARM-DEPLOYMENT.md
-#
-# Quick Start:
-#   1. cp .env.swarm.example .env
-#   2. nano .env  # Configure environment
-#   3. ./scripts/deploy-swarm.sh mosaic
-#   4. Initialize OpenBao manually (see docs/SWARM-DEPLOYMENT.md)
-#
-# ==============================================
-
-services:
-  # ======================
-  # PostgreSQL Database
-  # ======================
-  postgres:
-    image: git.mosaicstack.dev/mosaic/stack-postgres:${IMAGE_TAG:-latest}
-    env_file: .env
-    environment:
-      POSTGRES_USER: ${POSTGRES_USER:-mosaic}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-mosaic_dev_password}
-      POSTGRES_DB: ${POSTGRES_DB:-mosaic}
-      POSTGRES_SHARED_BUFFERS: ${POSTGRES_SHARED_BUFFERS:-256MB}
-      POSTGRES_EFFECTIVE_CACHE_SIZE: ${POSTGRES_EFFECTIVE_CACHE_SIZE:-1GB}
-      POSTGRES_MAX_CONNECTIONS: ${POSTGRES_MAX_CONNECTIONS:-100}
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-      # Note: init-scripts bind mount removed for Portainer compatibility
-      # Init scripts are baked into the postgres image at build time
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-mosaic} -d ${POSTGRES_DB:-mosaic}"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-    networks:
-      - internal
-    deploy:
-      restart_policy:
-        condition: on-failure
-
-  # ======================
-  # Valkey Cache
-  # ======================
-  valkey:
-    image: valkey/valkey:8-alpine
-    env_file: .env
-    command:
-      - valkey-server
-      - --maxmemory ${VALKEY_MAXMEMORY:-256mb}
-      - --maxmemory-policy noeviction
-      - --appendonly yes
-    volumes:
-      - valkey_data:/data
-    healthcheck:
-      test: ["CMD", "valkey-cli", "ping"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 10s
-    networks:
-      - internal
-    deploy:
-      restart_policy:
-        condition: on-failure
-
-  # ======================
-  # OpenBao Secrets Vault
-  # ======================
-  openbao:
-    image: git.mosaicstack.dev/mosaic/stack-openbao:${IMAGE_TAG:-latest}
-    entrypoint: ["dumb-init", "--"]
-    command: ["bao", "server", "-config=/openbao/config/config.hcl"]
-    env_file: .env
-    environment:
-      OPENBAO_ADDR: http://0.0.0.0:8200
-    volumes:
-      - openbao_data:/openbao/data
-      - openbao_logs:/openbao/logs
-      - openbao_init:/openbao/init
-    cap_add:
-      - IPC_LOCK
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          "wget --spider --quiet 'http://localhost:8200/v1/sys/health?standbyok=true&uninitcode=200&sealedcode=200'",
-        ]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-    networks:
-      - internal
-    deploy:
-      restart_policy:
-        condition: on-failure
-
-  # ======================
-  # OpenBao Init Sidecar
-  # ======================
-  # Auto-initializes and unseals OpenBao on first run.
-  # The init script has built-in retry logic (waits for OpenBao API).
-  openbao-init:
-    image: git.mosaicstack.dev/mosaic/stack-openbao:${IMAGE_TAG:-latest}
-    command: /openbao/init.sh
-    env_file: .env
-    environment:
-      VAULT_ADDR: http://openbao:8200
-    volumes:
-      - openbao_init:/openbao/init
-    networks:
-      - internal
-    deploy:
-      restart_policy:
-        condition: on-failure
-        max_attempts: 5
-        delay: 10s
-
-  # ======================
-  # Authentik - COMMENTED OUT (Using External Authentik)
-  # ======================
-  # Uncomment these services if you want to run Authentik internally
-  # For external Authentik, configure OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET in .env
-  #
-  # authentik-postgres:
-  #   image: postgres:17.7-alpine3.22
-  #   env_file: .env
-  #   environment:
-  #     POSTGRES_USER: ${AUTHENTIK_POSTGRES_USER:-authentik}
-  #     POSTGRES_PASSWORD: ${AUTHENTIK_POSTGRES_PASSWORD:-authentik_password}
-  #     POSTGRES_DB: ${AUTHENTIK_POSTGRES_DB:-authentik}
-  #   volumes:
-  #     - authentik_postgres_data:/var/lib/postgresql/data
-  #   healthcheck:
-  #     test: ["CMD-SHELL", "pg_isready -U ${AUTHENTIK_POSTGRES_USER:-authentik}"]
-  #     interval: 10s
-  #     timeout: 5s
-  #     retries: 5
-  #     start_period: 20s
-  #   networks:
-  #     - internal
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
-  #
-  # authentik-redis:
-  #   image: valkey/valkey:8-alpine
-  #   env_file: .env
-  #   command: valkey-server --save 60 1 --loglevel warning
-  #   volumes:
-  #     - authentik_redis_data:/data
-  #   healthcheck:
-  #     test: ["CMD", "valkey-cli", "ping"]
-  #     interval: 10s
-  #     timeout: 5s
-  #     retries: 5
-  #     start_period: 10s
-  #   networks:
-  #     - internal
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
-  #
-  # authentik-server:
-  #   image: ghcr.io/goauthentik/server:2024.12.1
-  #   env_file: .env
-  #   command: server
-  #   environment:
-  #     AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:-change-this-to-a-random-secret}
-  #     AUTHENTIK_ERROR_REPORTING__ENABLED: ${AUTHENTIK_ERROR_REPORTING:-false}
-  #     AUTHENTIK_POSTGRESQL__HOST: authentik-postgres
-  #     AUTHENTIK_POSTGRESQL__PORT: 5432
-  #     AUTHENTIK_POSTGRESQL__NAME: ${AUTHENTIK_POSTGRES_DB:-authentik}
-  #     AUTHENTIK_POSTGRESQL__USER: ${AUTHENTIK_POSTGRES_USER:-authentik}
-  #     AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_POSTGRES_PASSWORD:-authentik_password}
-  #     AUTHENTIK_REDIS__HOST: authentik-redis
-  #     AUTHENTIK_REDIS__PORT: 6379
-  #     AUTHENTIK_BOOTSTRAP_PASSWORD: ${AUTHENTIK_BOOTSTRAP_PASSWORD:-admin}
-  #     AUTHENTIK_BOOTSTRAP_EMAIL: ${AUTHENTIK_BOOTSTRAP_EMAIL:-admin@localhost}
-  #     AUTHENTIK_COOKIE_DOMAIN: ${AUTHENTIK_COOKIE_DOMAIN:-.mosaicstack.dev}
-  #   volumes:
-  #     - authentik_media:/media
-  #     - authentik_templates:/templates
-  #   healthcheck:
-  #     test:
-  #       [
-  #         "CMD",
-  #         "wget",
-  #         "--no-verbose",
-  #         "--tries=1",
-  #         "--spider",
-  #         "http://localhost:9000/-/health/live/",
-  #       ]
-  #     interval: 30s
-  #     timeout: 10s
-  #     retries: 3
-  #     start_period: 90s
-  #   networks:
-  #     - internal
-  #     - traefik-public
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
-  #     labels:
-  #       - "traefik.enable=true"
-  #       - "traefik.http.routers.mosaic-auth.rule=Host(`${MOSAIC_AUTH_DOMAIN:-auth.mosaicstack.dev}`)"
-  #       - "traefik.http.routers.mosaic-auth.entrypoints=web"
-  #       - "traefik.http.services.mosaic-auth.loadbalancer.server.port=9000"
-  #
-  # authentik-worker:
-  #   image: ghcr.io/goauthentik/server:2024.12.1
-  #   env_file: .env
-  #   command: worker
-  #   environment:
-  #     AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:-change-this-to-a-random-secret}
-  #     AUTHENTIK_ERROR_REPORTING__ENABLED: ${AUTHENTIK_ERROR_REPORTING:-false}
-  #     AUTHENTIK_POSTGRESQL__HOST: authentik-postgres
-  #     AUTHENTIK_POSTGRESQL__PORT: 5432
-  #     AUTHENTIK_POSTGRESQL__NAME: ${AUTHENTIK_POSTGRES_DB:-authentik}
-  #     AUTHENTIK_POSTGRESQL__USER: ${AUTHENTIK_POSTGRES_USER:-authentik}
-  #     AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_POSTGRES_PASSWORD:-authentik_password}
-  #     AUTHENTIK_REDIS__HOST: authentik-redis
-  #     AUTHENTIK_REDIS__PORT: 6379
-  #   volumes:
-  #     - authentik_media:/media
-  #     - authentik_certs:/certs
-  #     - authentik_templates:/templates
-  #   networks:
-  #     - internal
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
-
-  # ======================
-  # Ollama (Optional AI Service)
-  # ======================
-  # ollama:
-  #   image: ollama/ollama:latest
-  #   env_file: .env
-  #   volumes:
-  #     - ollama_data:/root/.ollama
-  #   healthcheck:
-  #     test: ["CMD", "curl", "-f", "http://localhost:11434/api/tags"]
-  #     interval: 30s
-  #     timeout: 10s
-  #     retries: 3
-  #     start_period: 60s
-  #   networks:
-  #     - internal
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
-
-  # ======================
-  # Mosaic Coordinator
-  # ======================
-  coordinator:
-    image: git.mosaicstack.dev/mosaic/stack-coordinator:${IMAGE_TAG:-latest}
-    env_file: .env
-    environment:
-      GITEA_WEBHOOK_SECRET: ${GITEA_WEBHOOK_SECRET}
-      GITEA_URL: ${GITEA_URL:-https://git.mosaicstack.dev}
-      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
-      LOG_LEVEL: ${LOG_LEVEL:-info}
-      HOST: 0.0.0.0
-      PORT: 8000
-      COORDINATOR_POLL_INTERVAL: ${COORDINATOR_POLL_INTERVAL:-5.0}
-      COORDINATOR_MAX_CONCURRENT_AGENTS: ${COORDINATOR_MAX_CONCURRENT_AGENTS:-10}
-      COORDINATOR_ENABLED: ${COORDINATOR_ENABLED:-true}
-      # Telemetry (task completion tracking & predictions)
-      MOSAIC_TELEMETRY_ENABLED: ${MOSAIC_TELEMETRY_ENABLED:-false}
-      MOSAIC_TELEMETRY_SERVER_URL: ${MOSAIC_TELEMETRY_SERVER_URL:-https://tel-api.mosaicstack.dev}
-      MOSAIC_TELEMETRY_API_KEY: ${MOSAIC_TELEMETRY_API_KEY:-}
-      MOSAIC_TELEMETRY_INSTANCE_ID: ${MOSAIC_TELEMETRY_INSTANCE_ID:-}
-      MOSAIC_TELEMETRY_DRY_RUN: ${MOSAIC_TELEMETRY_DRY_RUN:-false}
-    healthcheck:
-      test:
-        [
-          "CMD",
-          "python",
-          "-c",
-          "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')",
-        ]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 5s
-    networks:
-      - internal
-    deploy:
-      restart_policy:
-        condition: on-failure
-
-  # ======================
-  # Mosaic API
-  # ======================
-  api:
-    image: git.mosaicstack.dev/mosaic/stack-api:${IMAGE_TAG:-latest}
-    env_file: .env
-    environment:
-      NODE_ENV: production
-      PORT: ${API_PORT:-3001}
-      API_HOST: ${API_HOST:-0.0.0.0}
-      DATABASE_URL: postgresql://${POSTGRES_USER:-mosaic}:${POSTGRES_PASSWORD:-mosaic_dev_password}@postgres:5432/${POSTGRES_DB:-mosaic}
-      VALKEY_URL: redis://valkey:6379
-      OIDC_ISSUER: ${OIDC_ISSUER}
-      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
-      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
-      OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI:-http://localhost:3001/auth/callback}
-      JWT_SECRET: ${JWT_SECRET:-change-this-to-a-random-secret}
-      JWT_EXPIRATION: ${JWT_EXPIRATION:-24h}
-      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
-      OLLAMA_ENDPOINT: ${OLLAMA_ENDPOINT:-http://ollama:11434}
-      OPENBAO_ADDR: ${OPENBAO_ADDR:-http://openbao:8200}
-      ORCHESTRATOR_URL: ${ORCHESTRATOR_URL:-http://orchestrator:3001}
-      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
-      # Telemetry (task completion tracking & predictions)
-      MOSAIC_TELEMETRY_ENABLED: ${MOSAIC_TELEMETRY_ENABLED:-false}
-      MOSAIC_TELEMETRY_SERVER_URL: ${MOSAIC_TELEMETRY_SERVER_URL:-https://tel-api.mosaicstack.dev}
-      MOSAIC_TELEMETRY_API_KEY: ${MOSAIC_TELEMETRY_API_KEY:-}
-      MOSAIC_TELEMETRY_INSTANCE_ID: ${MOSAIC_TELEMETRY_INSTANCE_ID:-}
-      MOSAIC_TELEMETRY_DRY_RUN: ${MOSAIC_TELEMETRY_DRY_RUN:-false}
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          'node -e "require(''http'').get(''http://localhost:${API_PORT:-3001}/health'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
-        ]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    networks:
-      - internal
-      - traefik-public
-    deploy:
-      restart_policy:
-        condition: on-failure
-      labels:
-        - "traefik.enable=true"
-        - "traefik.http.routers.mosaic-api.rule=Host(`${MOSAIC_API_DOMAIN:-api.mosaicstack.dev}`)"
-        - "traefik.http.routers.mosaic-api.entrypoints=web"
-        - "traefik.http.services.mosaic-api.loadbalancer.server.port=${API_PORT:-3001}"
-
-  # ======================
-  # Mosaic Orchestrator
-  # ======================
-  orchestrator:
-    image: git.mosaicstack.dev/mosaic/stack-orchestrator:${IMAGE_TAG:-latest}
-    env_file: .env
-    user: "1000:1000"
-    environment:
-      NODE_ENV: production
-      ORCHESTRATOR_PORT: 3001
-      VALKEY_URL: redis://valkey:6379
-      CLAUDE_API_KEY: ${CLAUDE_API_KEY}
-      DOCKER_SOCKET: /var/run/docker.sock
-      GIT_USER_NAME: "Mosaic Orchestrator"
-      GIT_USER_EMAIL: "orchestrator@mosaicstack.dev"
-      KILLSWITCH_ENABLED: "true"
-      SANDBOX_ENABLED: "true"
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
-      - orchestrator_workspace:/workspace
-    healthcheck:
-      test:
-        ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3001/health || exit 1"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    networks:
-      - internal
-    # Note: security_opt not supported in swarm mode
-    # Security hardening done via cap_drop/cap_add
-    cap_drop:
-      - ALL
-    cap_add:
-      - NET_BIND_SERVICE
-    tmpfs:
-      - /tmp:noexec,nosuid,size=100m
-    deploy:
-      restart_policy:
-        condition: on-failure
-
-  # ======================
-  # Mosaic Web
-  # ======================
-  web:
-    image: git.mosaicstack.dev/mosaic/stack-web:${IMAGE_TAG:-latest}
-    env_file: .env
-    environment:
-      NODE_ENV: production
-      PORT: ${WEB_PORT:-3000}
-      NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-http://localhost:3001}
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          'node -e "require(''http'').get(''http://localhost:${WEB_PORT:-3000}'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
-        ]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    networks:
-      - traefik-public
-    deploy:
-      restart_policy:
-        condition: on-failure
-      labels:
-        - "traefik.enable=true"
-        - "traefik.http.routers.mosaic-web.rule=Host(`${MOSAIC_WEB_DOMAIN:-mosaic.mosaicstack.dev}`)"
-        - "traefik.http.routers.mosaic-web.entrypoints=web"
-        - "traefik.http.services.mosaic-web.loadbalancer.server.port=${WEB_PORT:-3000}"
-
-# ======================
-# Volumes
-# ======================
-volumes:
-  postgres_data:
-  valkey_data:
-  openbao_data:
-  openbao_logs:
-  openbao_init:
-  # Authentik volumes - commented out (using external Authentik)
-  # authentik_postgres_data:
-  # authentik_redis_data:
-  # authentik_media:
-  # authentik_certs:
-  # authentik_templates:
-  # Ollama volume - commented out (using external Ollama)
-  # ollama_data:
-  orchestrator_workspace:
-
-# ======================
-# Networks
-# ======================
-networks:
-  internal:
-    driver: overlay
-  traefik-public:
-    external: true
diff --git a/docker-compose.yml b/docker-compose.yml
index 6858318..275e8fb 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -27,9 +27,6 @@ services:
       start_period: 30s
     networks:
       - mosaic-internal
-    profiles:
-      - database
-      - full
     labels:
       - "com.mosaic.service=database"
       - "com.mosaic.description=PostgreSQL 17 with pgvector"
@@ -58,9 +55,6 @@ services:
       start_period: 10s
     networks:
       - mosaic-internal
-    profiles:
-      - cache
-      - full
     labels:
       - "com.mosaic.service=cache"
       - "com.mosaic.description=Valkey Redis-compatible cache"
@@ -368,12 +362,15 @@ services:
       OIDC_ISSUER: ${OIDC_ISSUER}
       OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
       OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
-      OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI:-http://localhost:3001/auth/callback}
+      OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI:-http://localhost:3001/auth/oauth2/callback/authentik}
       # JWT
       JWT_SECRET: ${JWT_SECRET:-change-this-to-a-random-secret}
       JWT_EXPIRATION: ${JWT_EXPIRATION:-24h}
       # Better Auth
       BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      BETTER_AUTH_URL: ${BETTER_AUTH_URL:-}
+      # Encryption (required for federation credentials/private keys)
+      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
       # Ollama (optional)
       OLLAMA_ENDPOINT: ${OLLAMA_ENDPOINT:-http://ollama:11434}
       # OpenBao (optional)
@@ -384,6 +381,10 @@ services:
       MOSAIC_TELEMETRY_API_KEY: ${MOSAIC_TELEMETRY_API_KEY:-}
       MOSAIC_TELEMETRY_INSTANCE_ID: ${MOSAIC_TELEMETRY_INSTANCE_ID:-}
       MOSAIC_TELEMETRY_DRY_RUN: ${MOSAIC_TELEMETRY_DRY_RUN:-false}
+      # Frontend URLs (for CORS and auth redirects)
+      NEXT_PUBLIC_APP_URL: ${NEXT_PUBLIC_APP_URL:-http://localhost:3000}
+      NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-http://localhost:3001}
+      TRUSTED_ORIGINS: ${TRUSTED_ORIGINS:-}
     volumes:
       - openbao_init:/openbao/init:ro
     ports:
@@ -432,9 +433,12 @@ services:
       NODE_ENV: production
       # Orchestrator Configuration
       ORCHESTRATOR_PORT: 3001
+      AI_PROVIDER: ${AI_PROVIDER:-ollama}
       # Valkey
       VALKEY_URL: redis://valkey:6379
-      # Claude API
+      VALKEY_HOST: valkey
+      VALKEY_PORT: 6379
+      # Claude API (required only when AI_PROVIDER=claude)
       CLAUDE_API_KEY: ${CLAUDE_API_KEY}
       # Docker
       DOCKER_SOCKET: /var/run/docker.sock
@@ -456,7 +460,10 @@ services:
         condition: service_healthy
     healthcheck:
       test:
-        ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3001/health || exit 1"]
+        [
+          "CMD-SHELL",
+          'node -e "require(''http'').get(''http://localhost:3001/health'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
+        ]
       interval: 30s
       timeout: 10s
       retries: 3
@@ -491,6 +498,7 @@ services:
       NODE_ENV: production
       PORT: ${WEB_PORT:-3000}
       NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-http://localhost:3001}
+      ORCHESTRATOR_API_KEY: ${ORCHESTRATOR_API_KEY}
     ports:
       - "${WEB_PORT:-3000}:${WEB_PORT:-3000}"
     depends_on:
diff --git a/docker/docker-compose.build.yml b/docker/docker-compose.build.yml
index 66a5e00..c8c387d 100644
--- a/docker/docker-compose.build.yml
+++ b/docker/docker-compose.build.yml
@@ -378,12 +378,13 @@ services:
       OIDC_ISSUER: ${OIDC_ISSUER}
       OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
       OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
-      OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI:-http://localhost:3001/auth/callback}
+      OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI:-http://localhost:3001/auth/oauth2/callback/authentik}
       # JWT
       JWT_SECRET: ${JWT_SECRET:-change-this-to-a-random-secret}
       JWT_EXPIRATION: ${JWT_EXPIRATION:-24h}
       # Better Auth
       BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      BETTER_AUTH_URL: ${BETTER_AUTH_URL:-}
       # Security
       CSRF_SECRET: ${CSRF_SECRET}
       ENCRYPTION_KEY: ${ENCRYPTION_KEY}
@@ -441,9 +442,12 @@ services:
       NODE_ENV: production
       # Orchestrator Configuration
       ORCHESTRATOR_PORT: 3001
+      AI_PROVIDER: ${AI_PROVIDER:-ollama}
       # Valkey
       VALKEY_URL: redis://valkey:6379
-      # Claude API
+      VALKEY_HOST: valkey
+      VALKEY_PORT: 6379
+      # Claude API (required only when AI_PROVIDER=claude)
       CLAUDE_API_KEY: ${CLAUDE_API_KEY}
       # Docker
       DOCKER_SOCKET: /var/run/docker.sock
@@ -465,7 +469,10 @@ services:
         condition: service_healthy
     healthcheck:
       test:
-        ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3001/health || exit 1"]
+        [
+          "CMD-SHELL",
+          'node -e "require(''http'').get(''http://localhost:3001/health'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
+        ]
       interval: 30s
       timeout: 10s
       retries: 3
diff --git a/docker/docker-compose.dev.yml b/docker/docker-compose.dev.yml
deleted file mode 100644
index af6dde7..0000000
--- a/docker/docker-compose.dev.yml
+++ /dev/null
@@ -1,22 +0,0 @@
-# Development overrides for docker-compose.yml
-# Usage: docker compose -f docker-compose.yml -f docker-compose.dev.yml up
-
-services:
-  postgres:
-    environment:
-      POSTGRES_USER: mosaic
-      POSTGRES_PASSWORD: mosaic_dev_password
-      POSTGRES_DB: mosaic
-    ports:
-      - "5432:5432"
-    # Enable query logging for development
-    command:
-      - "postgres"
-      - "-c"
-      - "log_statement=all"
-      - "-c"
-      - "log_duration=on"
-
-  valkey:
-    ports:
-      - "6379:6379"
diff --git a/docker/docker-compose.example.external.yml b/docker/docker-compose.example.external.yml
deleted file mode 100644
index bbbb9e4..0000000
--- a/docker/docker-compose.example.external.yml
+++ /dev/null
@@ -1,126 +0,0 @@
-# ==============================================
-# Mosaic Stack - External Services Deployment Example
-# ==============================================
-# This example shows a production deployment using external managed services.
-# All infrastructure (database, cache, secrets, auth, AI) is managed externally.
-#
-# Usage:
-#   1. Copy this file to docker-compose.override.yml
-#   2. Set COMPOSE_PROFILES= (empty) in .env
-#   3. Configure external service URLs in .env (see below)
-#   4. Run: docker compose up -d
-#
-# Or run directly:
-#   docker compose -f docker-compose.yml -f docker-compose.example.external.yml up -d
-#
-# Services Included:
-#   - API (NestJS) - configured to use external services
-#   - Web (Next.js)
-#   - Orchestrator (Agent management)
-#
-# External Services (configured via .env):
-#   - PostgreSQL (e.g., AWS RDS, Google Cloud SQL, Azure Database)
-#   - Redis/Valkey (e.g., AWS ElastiCache, Google Memorystore, Azure Cache)
-#   - OpenBao/Vault (e.g., HashiCorp Vault Cloud, self-hosted)
-#   - OIDC Provider (e.g., Auth0, Okta, Google, Azure AD)
-#   - LLM Service (e.g., hosted Ollama, OpenAI, Anthropic)
-#
-# Required Environment Variables (.env):
-#   COMPOSE_PROFILES=  # Empty - no bundled services
-#   IMAGE_TAG=latest
-#
-#   # External Database
-#   DATABASE_URL=postgresql://user:password@rds.example.com:5432/mosaic
-#
-#   # External Cache
-#   VALKEY_URL=redis://elasticache.example.com:6379
-#
-#   # External Secrets (OpenBao/Vault)
-#   OPENBAO_ADDR=https://vault.example.com:8200
-#   OPENBAO_ROLE_ID=your-role-id
-#   OPENBAO_SECRET_ID=your-secret-id
-#
-#   # External OIDC Authentication
-#   OIDC_ENABLED=true
-#   OIDC_ISSUER=https://auth.example.com/
-#   OIDC_CLIENT_ID=your-client-id
-#   OIDC_CLIENT_SECRET=your-client-secret
-#
-#   # External LLM Service
-#   OLLAMA_ENDPOINT=https://ollama.example.com:11434
-#   # Or use OpenAI:
-#   # AI_PROVIDER=openai
-#   # OPENAI_API_KEY=sk-...
-#
-# ==============================================
-
-services:
-  # Disable all bundled infrastructure services
-  postgres:
-    profiles:
-      - disabled
-
-  valkey:
-    profiles:
-      - disabled
-
-  openbao:
-    profiles:
-      - disabled
-
-  openbao-init:
-    profiles:
-      - disabled
-
-  authentik-postgres:
-    profiles:
-      - disabled
-
-  authentik-redis:
-    profiles:
-      - disabled
-
-  authentik-server:
-    profiles:
-      - disabled
-
-  authentik-worker:
-    profiles:
-      - disabled
-
-  ollama:
-    profiles:
-      - disabled
-
-  # Configure API to use external services
-  api:
-    environment:
-      # External database (e.g., AWS RDS)
-      DATABASE_URL: ${DATABASE_URL}
-
-      # External cache (e.g., AWS ElastiCache)
-      VALKEY_URL: ${VALKEY_URL}
-
-      # External secrets (e.g., HashiCorp Vault Cloud)
-      OPENBAO_ADDR: ${OPENBAO_ADDR}
-      OPENBAO_ROLE_ID: ${OPENBAO_ROLE_ID}
-      OPENBAO_SECRET_ID: ${OPENBAO_SECRET_ID}
-
-      # External LLM (e.g., hosted Ollama or OpenAI)
-      OLLAMA_ENDPOINT: ${OLLAMA_ENDPOINT}
-
-      # External OIDC (e.g., Auth0, Okta, Google)
-      OIDC_ENABLED: ${OIDC_ENABLED}
-      OIDC_ISSUER: ${OIDC_ISSUER}
-      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
-      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
-
-      # Security
-      CSRF_SECRET: ${CSRF_SECRET}
-      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
-
-  # Web app remains unchanged
-  # web: (uses defaults from docker-compose.yml)
-
-  # Orchestrator remains unchanged
-  # orchestrator: (uses defaults from docker-compose.yml)
diff --git a/docker/docker-compose.example.hybrid.yml b/docker/docker-compose.example.hybrid.yml
deleted file mode 100644
index 93de773..0000000
--- a/docker/docker-compose.example.hybrid.yml
+++ /dev/null
@@ -1,114 +0,0 @@
-# ==============================================
-# Mosaic Stack - Hybrid Deployment Example
-# ==============================================
-# This example shows a hybrid deployment mixing bundled and external services.
-# Common for staging environments: bundled database/cache, external auth/secrets.
-#
-# Usage:
-#   1. Copy this file to docker-compose.override.yml
-#   2. Set COMPOSE_PROFILES=database,cache,ollama in .env
-#   3. Configure external service URLs in .env (see below)
-#   4. Run: docker compose up -d
-#
-# Or run directly:
-#   docker compose -f docker-compose.yml -f docker-compose.example.hybrid.yml up -d
-#
-# Services Included (Bundled):
-#   - PostgreSQL 17 with pgvector
-#   - Valkey (Redis-compatible cache)
-#   - Ollama (local LLM)
-#   - API (NestJS)
-#   - Web (Next.js)
-#   - Orchestrator (Agent management)
-#
-# Services Included (External):
-#   - OpenBao/Vault (managed secrets)
-#   - Authentik/OIDC (managed authentication)
-#
-# Environment Variables (.env):
-#   COMPOSE_PROFILES=database,cache,ollama  # Enable only these bundled services
-#   IMAGE_TAG=dev
-#
-#   # Bundled Database (default from docker-compose.yml)
-#   DATABASE_URL=postgresql://mosaic:${POSTGRES_PASSWORD}@postgres:5432/mosaic
-#
-#   # Bundled Cache (default from docker-compose.yml)
-#   VALKEY_URL=redis://valkey:6379
-#
-#   # Bundled Ollama (default from docker-compose.yml)
-#   OLLAMA_ENDPOINT=http://ollama:11434
-#
-#   # External Secrets (OpenBao/Vault)
-#   OPENBAO_ADDR=https://vault.example.com:8200
-#   OPENBAO_ROLE_ID=your-role-id
-#   OPENBAO_SECRET_ID=your-secret-id
-#
-#   # External OIDC Authentication
-#   OIDC_ENABLED=true
-#   OIDC_ISSUER=https://auth.example.com/
-#   OIDC_CLIENT_ID=your-client-id
-#   OIDC_CLIENT_SECRET=your-client-secret
-#
-# ==============================================
-
-services:
-  # Use bundled PostgreSQL and Valkey (enabled via database,cache profiles)
-  # No overrides needed - profiles handle this
-
-  # Disable bundled Authentik - use external OIDC
-  authentik-postgres:
-    profiles:
-      - disabled
-
-  authentik-redis:
-    profiles:
-      - disabled
-
-  authentik-server:
-    profiles:
-      - disabled
-
-  authentik-worker:
-    profiles:
-      - disabled
-
-  # Disable bundled OpenBao - use external vault
-  openbao:
-    profiles:
-      - disabled
-
-  openbao-init:
-    profiles:
-      - disabled
-
-  # Use bundled Ollama (enabled via ollama profile)
-  # No override needed
-
-  # Configure API for hybrid deployment
-  api:
-    environment:
-      # Bundled database (default)
-      DATABASE_URL: postgresql://${POSTGRES_USER:-mosaic}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-mosaic}
-
-      # Bundled cache (default)
-      VALKEY_URL: redis://valkey:6379
-
-      # External secrets
-      OPENBAO_ADDR: ${OPENBAO_ADDR}
-      OPENBAO_ROLE_ID: ${OPENBAO_ROLE_ID}
-      OPENBAO_SECRET_ID: ${OPENBAO_SECRET_ID}
-
-      # Bundled Ollama (default)
-      OLLAMA_ENDPOINT: http://ollama:11434
-
-      # External OIDC
-      OIDC_ENABLED: ${OIDC_ENABLED}
-      OIDC_ISSUER: ${OIDC_ISSUER}
-      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
-      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
-
-      # Security
-      CSRF_SECRET: ${CSRF_SECRET}
-      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
-
-  # Web and Orchestrator use defaults from docker-compose.yml
diff --git a/docker/docker-compose.example.turnkey.yml b/docker/docker-compose.example.turnkey.yml
deleted file mode 100644
index 9443c01..0000000
--- a/docker/docker-compose.example.turnkey.yml
+++ /dev/null
@@ -1,43 +0,0 @@
-# ==============================================
-# Mosaic Stack - Turnkey Deployment Example
-# ==============================================
-# This example shows a complete all-in-one deployment with all services bundled.
-# Ideal for local development, testing, and demo environments.
-#
-# Usage:
-#   1. Copy this file to docker-compose.override.yml (optional)
-#   2. Set COMPOSE_PROFILES=full in .env
-#   3. Run: docker compose up -d
-#
-# Or run directly:
-#   docker compose -f docker-compose.yml -f docker-compose.example.turnkey.yml up -d
-#
-# Services Included:
-#   - PostgreSQL 17 with pgvector
-#   - Valkey (Redis-compatible cache)
-#   - OpenBao (secrets management)
-#   - Authentik (OIDC authentication)
-#   - Ollama (local LLM)
-#   - Traefik (reverse proxy) - optional, requires traefik-bundled profile
-#   - API (NestJS)
-#   - Web (Next.js)
-#   - Orchestrator (Agent management)
-#
-# Environment Variables (.env):
-#   COMPOSE_PROFILES=full
-#   IMAGE_TAG=dev  # or latest
-#
-# All services run in Docker containers with no external dependencies.
-# ==============================================
-
-services:
-  # No service overrides needed - the main docker-compose.yml handles everything
-  # This file serves as documentation for turnkey deployment
-  # Set COMPOSE_PROFILES=full in your .env file to enable all services
-
-  # Placeholder to make the file valid YAML
-  # (Docker Compose requires at least one service definition)
-  _placeholder:
-    image: alpine:latest
-    profiles:
-      - never-used
diff --git a/docker/docker-compose.matrix.yml b/docker/docker-compose.matrix.yml
deleted file mode 100644
index 1062111..0000000
--- a/docker/docker-compose.matrix.yml
+++ /dev/null
@@ -1,123 +0,0 @@
-# ==============================================
-# Matrix Dev Environment (Synapse + Element Web)
-# ==============================================
-#
-# Development-only overlay for testing the Matrix bridge locally.
-# NOT for production — use docker-compose.sample.matrix.yml for production.
-#
-# Usage:
-#   docker compose -f docker/docker-compose.yml -f docker/docker-compose.matrix.yml up -d
-#
-# Or with Makefile:
-#   make matrix-up
-#
-# This overlay:
-#   - Adds Synapse homeserver (localhost:8008) using shared PostgreSQL
-#   - Adds Element Web client (localhost:8501)
-#   - Creates a separate 'synapse' database in the shared PostgreSQL instance
-#   - Enables open registration for easy dev testing
-#
-# After first startup, create the bot account:
-#   docker/matrix/scripts/setup-bot.sh
-#
-# ==============================================
-
-services:
-  # ======================
-  # Synapse Database Init
-  # ======================
-  # Creates the 'synapse' database and user in the shared PostgreSQL instance.
-  # Runs once and exits — idempotent, safe to run repeatedly.
-  synapse-db-init:
-    image: postgres:17-alpine
-    container_name: mosaic-synapse-db-init
-    restart: "no"
-    environment:
-      PGHOST: postgres
-      PGPORT: 5432
-      PGUSER: ${POSTGRES_USER:-mosaic}
-      PGPASSWORD: ${POSTGRES_PASSWORD:-mosaic_dev_password}
-      SYNAPSE_DB: ${SYNAPSE_POSTGRES_DB:-synapse}
-      SYNAPSE_USER: ${SYNAPSE_POSTGRES_USER:-synapse}
-      SYNAPSE_PASSWORD: ${SYNAPSE_POSTGRES_PASSWORD:-synapse_dev_password}
-    entrypoint: ["sh", "-c"]
-    command:
-      - |
-        until pg_isready -h postgres -p 5432 -U $${PGUSER}; do
-          echo "Waiting for PostgreSQL..."
-          sleep 2
-        done
-        echo "PostgreSQL is ready. Creating Synapse database and user..."
-
-        psql -h postgres -U $${PGUSER} -tc "SELECT 1 FROM pg_roles WHERE rolname='$${SYNAPSE_USER}'" | grep -q 1 || \
-          psql -h postgres -U $${PGUSER} -c "CREATE USER $${SYNAPSE_USER} WITH PASSWORD '$${SYNAPSE_PASSWORD}';"
-
-        psql -h postgres -U $${PGUSER} -tc "SELECT 1 FROM pg_database WHERE datname='$${SYNAPSE_DB}'" | grep -q 1 || \
-          psql -h postgres -U $${PGUSER} -c "CREATE DATABASE $${SYNAPSE_DB} OWNER $${SYNAPSE_USER} ENCODING 'UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE template0;"
-
-        echo "Synapse database ready: $${SYNAPSE_DB}"
-    depends_on:
-      postgres:
-        condition: service_healthy
-    networks:
-      - mosaic-internal
-
-  # ======================
-  # Synapse (Matrix Homeserver)
-  # ======================
-  synapse:
-    image: matrixdotorg/synapse:latest
-    container_name: mosaic-synapse
-    restart: unless-stopped
-    environment:
-      SYNAPSE_CONFIG_DIR: /data
-      SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
-    ports:
-      - "${SYNAPSE_CLIENT_PORT:-8008}:8008"
-      - "${SYNAPSE_FEDERATION_PORT:-8448}:8448"
-    volumes:
-      - /opt/mosaic/synapse/homeserver.yaml:/data/homeserver.yaml:ro
-      - /opt/mosaic/synapse/media_store:/data/media_store
-      - /opt/mosaic/synapse/keys:/data/keys
-    depends_on:
-      postgres:
-        condition: service_healthy
-      synapse-db-init:
-        condition: service_completed_successfully
-    healthcheck:
-      test: ["CMD-SHELL", "curl -fSs http://localhost:8008/health || exit 1"]
-      interval: 15s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-    networks:
-      - mosaic-internal
-    labels:
-      com.mosaic.service: "matrix-synapse"
-      com.mosaic.description: "Matrix homeserver (dev)"
-
-  # ======================
-  # Element Web (Matrix Client)
-  # ======================
-  element-web:
-    image: vectorim/element-web:latest
-    container_name: mosaic-element-web
-    restart: unless-stopped
-    ports:
-      - "${ELEMENT_PORT:-8501}:80"
-    volumes:
-      - /opt/mosaic/synapse/element-config.json:/app/config.json:ro
-    depends_on:
-      synapse:
-        condition: service_healthy
-    healthcheck:
-      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:80 || exit 1"]
-      interval: 30s
-      timeout: 5s
-      retries: 3
-      start_period: 10s
-    networks:
-      - mosaic-internal
-    labels:
-      com.mosaic.service: "matrix-element"
-      com.mosaic.description: "Element Web client (dev)"
diff --git a/docker/docker-compose.prod.yml b/docker/docker-compose.prod.yml
deleted file mode 100644
index 01b637d..0000000
--- a/docker/docker-compose.prod.yml
+++ /dev/null
@@ -1,182 +0,0 @@
-# Production Docker Compose - Uses pre-built images from Gitea Packages
-#
-# Prerequisites:
-#   - Images built and pushed to git.mosaicstack.dev/mosaic/*
-#   - .env file configured with production values
-#
-# Usage:
-#   docker compose -f docker-compose.prod.yml up -d
-#
-# For Portainer:
-#   - Stack → Add Stack → Repository
-#   - Compose file: docker-compose.prod.yml
-
-services:
-  # ======================
-  # PostgreSQL Database
-  # ======================
-  postgres:
-    image: git.mosaicstack.dev/mosaic/postgres:latest
-    container_name: mosaic-postgres
-    restart: unless-stopped
-    environment:
-      POSTGRES_USER: ${POSTGRES_USER:-mosaic}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-      POSTGRES_DB: ${POSTGRES_DB:-mosaic}
-      POSTGRES_SHARED_BUFFERS: ${POSTGRES_SHARED_BUFFERS:-256MB}
-      POSTGRES_EFFECTIVE_CACHE_SIZE: ${POSTGRES_EFFECTIVE_CACHE_SIZE:-1GB}
-      POSTGRES_MAX_CONNECTIONS: ${POSTGRES_MAX_CONNECTIONS:-100}
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-mosaic} -d ${POSTGRES_DB:-mosaic}"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
-    networks:
-      - mosaic-internal
-    labels:
-      - "com.mosaic.service=database"
-      - "com.mosaic.description=PostgreSQL 17 with pgvector"
-
-  # ======================
-  # Valkey Cache
-  # ======================
-  valkey:
-    image: valkey/valkey:8-alpine
-    container_name: mosaic-valkey
-    restart: unless-stopped
-    command:
-      - valkey-server
-      - --maxmemory ${VALKEY_MAXMEMORY:-256mb}
-      - --maxmemory-policy noeviction
-      - --appendonly yes
-    volumes:
-      - valkey_data:/data
-    healthcheck:
-      test: ["CMD", "valkey-cli", "ping"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 10s
-    networks:
-      - mosaic-internal
-    labels:
-      - "com.mosaic.service=cache"
-      - "com.mosaic.description=Valkey Redis-compatible cache"
-
-  # ======================
-  # Mosaic API
-  # ======================
-  api:
-    image: git.mosaicstack.dev/mosaic/api:latest
-    container_name: mosaic-api
-    restart: unless-stopped
-    environment:
-      NODE_ENV: production
-      PORT: ${API_PORT:-3001}
-      API_HOST: ${API_HOST:-0.0.0.0}
-      DATABASE_URL: postgresql://${POSTGRES_USER:-mosaic}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-mosaic}
-      VALKEY_URL: redis://valkey:6379
-      OIDC_ISSUER: ${OIDC_ISSUER}
-      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
-      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
-      OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI}
-      JWT_SECRET: ${JWT_SECRET}
-      JWT_EXPIRATION: ${JWT_EXPIRATION:-24h}
-      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
-      CSRF_SECRET: ${CSRF_SECRET}
-      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
-      OLLAMA_ENDPOINT: ${OLLAMA_ENDPOINT:-http://ollama:11434}
-    ports:
-      - "${API_PORT:-3001}:${API_PORT:-3001}"
-    depends_on:
-      postgres:
-        condition: service_healthy
-      valkey:
-        condition: service_healthy
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          'node -e "require(''http'').get(''http://localhost:${API_PORT:-3001}/health'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
-        ]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    networks:
-      - mosaic-internal
-      - mosaic-public
-    labels:
-      - "com.mosaic.service=api"
-      - "com.mosaic.description=Mosaic NestJS API"
-      - "traefik.enable=${TRAEFIK_ENABLE:-false}"
-      - "traefik.http.routers.mosaic-api.rule=Host(`${MOSAIC_API_DOMAIN:-api.mosaicstack.dev}`)"
-      - "traefik.http.routers.mosaic-api.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
-      - "traefik.http.routers.mosaic-api.tls=${TRAEFIK_TLS_ENABLED:-true}"
-      - "traefik.http.services.mosaic-api.loadbalancer.server.port=${API_PORT:-3001}"
-      - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-mosaic-public}"
-      - "traefik.http.routers.mosaic-api.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
-
-  # ======================
-  # Mosaic Web
-  # ======================
-  web:
-    image: git.mosaicstack.dev/mosaic/web:latest
-    container_name: mosaic-web
-    restart: unless-stopped
-    environment:
-      NODE_ENV: production
-      PORT: ${WEB_PORT:-3000}
-      NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL:-https://api.mosaicstack.dev}
-    ports:
-      - "${WEB_PORT:-3000}:${WEB_PORT:-3000}"
-    depends_on:
-      api:
-        condition: service_healthy
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          'node -e "require(''http'').get(''http://localhost:${WEB_PORT:-3000}'', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"',
-        ]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-    networks:
-      - mosaic-public
-    labels:
-      - "com.mosaic.service=web"
-      - "com.mosaic.description=Mosaic Next.js Web App"
-      - "traefik.enable=${TRAEFIK_ENABLE:-false}"
-      - "traefik.http.routers.mosaic-web.rule=Host(`${MOSAIC_WEB_DOMAIN:-app.mosaicstack.dev}`)"
-      - "traefik.http.routers.mosaic-web.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
-      - "traefik.http.routers.mosaic-web.tls=${TRAEFIK_TLS_ENABLED:-true}"
-      - "traefik.http.services.mosaic-web.loadbalancer.server.port=${WEB_PORT:-3000}"
-      - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-mosaic-public}"
-      - "traefik.http.routers.mosaic-web.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
-
-# ======================
-# Volumes
-# ======================
-volumes:
-  postgres_data:
-    name: mosaic-postgres-data
-    driver: local
-  valkey_data:
-    name: mosaic-valkey-data
-    driver: local
-
-# ======================
-# Networks
-# ======================
-networks:
-  mosaic-internal:
-    name: mosaic-internal
-    driver: bridge
-  mosaic-public:
-    name: mosaic-public
-    driver: bridge
diff --git a/docker/docker-compose.sample.matrix.yml b/docker/docker-compose.sample.matrix.yml
deleted file mode 100644
index 5f71d48..0000000
--- a/docker/docker-compose.sample.matrix.yml
+++ /dev/null
@@ -1,206 +0,0 @@
-# ==============================================
-# Matrix (Synapse + Element) - Sample Swarm Deployment
-# ==============================================
-#
-# Standalone Matrix homeserver deployment for use with Mosaic Stack.
-# This is SEPARATE infrastructure — not part of the Mosaic Stack itself.
-# Mosaic connects to it via MATRIX_HOMESERVER_URL environment variable.
-#
-# Also serves: personal communications, GoToSocial bridges, other projects.
-#
-# Usage (Docker Swarm via Portainer):
-#   1. Create a new stack in Portainer
-#   2. Paste this file or point to the repo
-#   3. Set environment variables in Portainer's env var section
-#   4. Deploy the stack
-#
-# Usage (Docker Swarm CLI):
-#   1. cp docker-compose.sample.matrix.env .env
-#   2. nano .env  # Configure
-#   3. docker stack deploy -c docker-compose.sample.matrix.yml matrix
-#
-# Post-Deploy Setup:
-#   1. Generate Synapse config (first run only):
-#      docker exec <synapse_container> python -m synapse.app.homeserver \
-#        --server-name ${MATRIX_DOMAIN} --report-stats no \
-#        --generate-config --config-path /data/homeserver.yaml
-#
-#   2. Create admin account:
-#      docker exec -it <synapse_container> register_new_matrix_user \
-#        -u admin -a -c /data/homeserver.yaml http://localhost:8008
-#
-#   3. Create Mosaic bot account:
-#      docker exec -it <synapse_container> register_new_matrix_user \
-#        -u mosaic-bot -c /data/homeserver.yaml http://localhost:8008
-#
-#   4. Generate bot access token:
-#      curl -X POST http://localhost:8008/_matrix/client/v3/login \
-#        -d '{"type":"m.login.password","user":"mosaic-bot","password":"<password>"}'
-#
-#   5. Set MATRIX_ACCESS_TOKEN in Mosaic Stack .env
-#
-# Required Environment Variables:
-#   MATRIX_DOMAIN=matrix.example.com        # Synapse server name (permanent!)
-#   ELEMENT_DOMAIN=chat.example.com         # Element Web domain
-#   POSTGRES_PASSWORD=<strong-password>     # Synapse database password
-#
-# Optional Environment Variables:
-#   SYNAPSE_IMAGE_TAG=latest                # Synapse version
-#   ELEMENT_IMAGE_TAG=latest                # Element Web version
-#   POSTGRES_IMAGE_TAG=16-alpine            # PostgreSQL version
-#   TRAEFIK_ENTRYPOINT=websecure            # Traefik entrypoint name
-#   TRAEFIK_CERTRESOLVER=letsencrypt        # Traefik cert resolver
-#   TRAEFIK_DOCKER_NETWORK=traefik-public   # Traefik network name
-#   SYNAPSE_ENABLE_REGISTRATION=false       # Public registration
-#   SYNAPSE_REPORT_STATS=no                 # Anonymous stats reporting
-#   SYNAPSE_MAX_UPLOAD_SIZE=50M             # Max file upload size
-#
-# Connecting to Mosaic Stack:
-#   Add to your Mosaic Stack .env:
-#     MATRIX_HOMESERVER_URL=http://synapse:8008  (if same Docker network)
-#     MATRIX_HOMESERVER_URL=https://matrix.example.com  (if external)
-#     MATRIX_ACCESS_TOKEN=<bot access token from step 4>
-#     MATRIX_BOT_USER_ID=@mosaic-bot:matrix.example.com
-#
-# ==============================================
-
-services:
-  # ======================
-  # Synapse (Matrix Homeserver)
-  # ======================
-  synapse:
-    image: matrixdotorg/synapse:${SYNAPSE_IMAGE_TAG:-latest}
-    environment:
-      SYNAPSE_SERVER_NAME: ${MATRIX_DOMAIN}
-      SYNAPSE_REPORT_STATS: ${SYNAPSE_REPORT_STATS:-no}
-      SYNAPSE_CONFIG_DIR: /data
-      SYNAPSE_DATA_DIR: /data
-      SYNAPSE_LOG_LEVEL: ${SYNAPSE_LOG_LEVEL:-WARNING}
-      # Database connection (external PostgreSQL or bundled)
-      POSTGRES_HOST: synapse-postgres
-      POSTGRES_PORT: 5432
-      POSTGRES_DB: ${SYNAPSE_POSTGRES_DB:-synapse}
-      POSTGRES_USER: ${SYNAPSE_POSTGRES_USER:-synapse}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-    volumes:
-      - synapse-data:/data
-      - synapse-media:/data/media_store
-    depends_on:
-      synapse-postgres:
-        condition: service_healthy
-    healthcheck:
-      test: ["CMD-SHELL", "curl -fSs http://localhost:8008/health || exit 1"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 30s
-    networks:
-      - internal
-      - traefik-public
-    deploy:
-      restart_policy:
-        condition: on-failure
-        delay: 10s
-      labels:
-        - "traefik.enable=true"
-        - "traefik.http.routers.matrix.rule=Host(`${MATRIX_DOMAIN}`)"
-        - "traefik.http.routers.matrix.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
-        - "traefik.http.routers.matrix.tls=${TRAEFIK_TLS_ENABLED:-true}"
-        - "traefik.http.routers.matrix.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
-        - "traefik.http.services.matrix.loadbalancer.server.port=8008"
-        - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-traefik-public}"
-        # Well-known delegation (optional — for .well-known/matrix/server)
-        # - "traefik.http.routers.matrix-wellknown.rule=Host(`${MATRIX_DOMAIN}`) && PathPrefix(`/.well-known/matrix`)"
-
-  # ======================
-  # Element Web (Matrix Client)
-  # ======================
-  element-web:
-    image: vectorim/element-web:${ELEMENT_IMAGE_TAG:-latest}
-    volumes:
-      - element-config:/app/config
-    healthcheck:
-      test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:80 || exit 1"]
-      interval: 30s
-      timeout: 5s
-      retries: 3
-    networks:
-      - internal
-      - traefik-public
-    deploy:
-      restart_policy:
-        condition: on-failure
-      labels:
-        - "traefik.enable=true"
-        - "traefik.http.routers.element.rule=Host(`${ELEMENT_DOMAIN}`)"
-        - "traefik.http.routers.element.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
-        - "traefik.http.routers.element.tls=${TRAEFIK_TLS_ENABLED:-true}"
-        - "traefik.http.routers.element.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
-        - "traefik.http.services.element.loadbalancer.server.port=80"
-        - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-traefik-public}"
-
-  # ======================
-  # PostgreSQL (Synapse Database)
-  # ======================
-  # Separate from Mosaic's PostgreSQL — Synapse manages its own schema.
-  # If you prefer a shared PostgreSQL instance, remove this service and
-  # point POSTGRES_HOST to your existing PostgreSQL with a separate database.
-  synapse-postgres:
-    image: postgres:${POSTGRES_IMAGE_TAG:-16-alpine}
-    environment:
-      POSTGRES_DB: ${SYNAPSE_POSTGRES_DB:-synapse}
-      POSTGRES_USER: ${SYNAPSE_POSTGRES_USER:-synapse}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-      POSTGRES_INITDB_ARGS: "--encoding=UTF-8 --lc-collate=C --lc-ctype=C"
-    volumes:
-      - synapse-postgres-data:/var/lib/postgresql/data
-    healthcheck:
-      test:
-        [
-          "CMD-SHELL",
-          "pg_isready -U ${SYNAPSE_POSTGRES_USER:-synapse} -d ${SYNAPSE_POSTGRES_DB:-synapse}",
-        ]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    networks:
-      - internal
-    deploy:
-      restart_policy:
-        condition: on-failure
-
-  # ======================
-  # coturn (TURN/STUN for VoIP) - Optional
-  # ======================
-  # Uncomment if you need voice/video calls through NAT.
-  # Requires additional DNS and port configuration.
-  #
-  # coturn:
-  #   image: coturn/coturn:latest
-  #   environment:
-  #     TURN_REALM: ${MATRIX_DOMAIN}
-  #     TURN_SECRET: ${COTURN_SECRET}
-  #   ports:
-  #     - "3478:3478/tcp"
-  #     - "3478:3478/udp"
-  #     - "5349:5349/tcp"
-  #     - "5349:5349/udp"
-  #     - "49152-49200:49152-49200/udp"
-  #   networks:
-  #     - internal
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
-
-volumes:
-  synapse-data:
-  synapse-media:
-  synapse-postgres-data:
-  element-config:
-
-networks:
-  internal:
-    driver: overlay
-  traefik-public:
-    external: true
-    name: ${TRAEFIK_DOCKER_NETWORK:-traefik-public}
diff --git a/docker/docker-compose.sample.speech.yml b/docker/docker-compose.sample.speech.yml
deleted file mode 100644
index 983fb37..0000000
--- a/docker/docker-compose.sample.speech.yml
+++ /dev/null
@@ -1,164 +0,0 @@
-# ==============================================
-# Speech Services - Sample Swarm Deployment
-# ==============================================
-#
-# Standalone speech services deployment for use with Mosaic Stack.
-# This is SEPARATE infrastructure — not part of the Mosaic Stack itself.
-# Mosaic connects to it via SPEACHES_URL and TTS_URL environment variables.
-#
-# Provides:
-#   - Speaches: Speech-to-Text (Whisper) + basic TTS fallback
-#   - Kokoro TTS: Default high-quality text-to-speech
-#   - Chatterbox TTS: Premium TTS with voice cloning (optional, requires GPU)
-#
-# Usage (Docker Swarm via Portainer):
-#   1. Create a new stack in Portainer
-#   2. Paste this file or point to the repo
-#   3. Set environment variables in Portainer's env var section
-#   4. Deploy the stack
-#
-# Usage (Docker Swarm CLI):
-#   1. Create .env file with variables below
-#   2. docker stack deploy -c docker-compose.sample.speech.yml speech
-#
-# Required Environment Variables:
-#   STT_DOMAIN=stt.example.com              # Domain for Speaches (STT + basic TTS)
-#   TTS_DOMAIN=tts.example.com              # Domain for Kokoro TTS (default TTS)
-#
-# Optional Environment Variables:
-#   WHISPER_MODEL=Systran/faster-whisper-large-v3-turbo  # Whisper model for STT
-#   CHATTERBOX_TTS_DOMAIN=tts-premium.example.com       # Domain for Chatterbox (premium TTS)
-#   TRAEFIK_ENTRYPOINT=websecure            # Traefik entrypoint name
-#   TRAEFIK_CERTRESOLVER=letsencrypt        # Traefik cert resolver
-#   TRAEFIK_DOCKER_NETWORK=traefik-public   # Traefik network name
-#   TRAEFIK_TLS_ENABLED=true                # Enable TLS on Traefik routers
-#
-# Connecting to Mosaic Stack:
-#   Add to your Mosaic Stack .env:
-#     SPEACHES_URL=http://speaches:8000      (if same Docker network)
-#     SPEACHES_URL=https://stt.example.com   (if external)
-#     TTS_URL=http://kokoro-tts:8880         (if same Docker network)
-#     TTS_URL=https://tts.example.com        (if external)
-#
-# GPU Requirements (Chatterbox only):
-#   - NVIDIA GPU with CUDA support
-#   - nvidia-container-toolkit installed on Docker host
-#   - Docker runtime configured for GPU access
-#   - Note: Docker Swarm requires "generic resources" for GPU scheduling.
-#     See: https://docs.docker.com/engine/daemon/nvidia-gpu/#configure-gpus-for-docker-swarm
-#
-# ==============================================
-
-services:
-  # ======================
-  # Speaches (STT + basic TTS)
-  # ======================
-  # Primary speech-to-text service using Whisper.
-  # Also provides basic TTS as a fallback.
-  speaches:
-    image: ghcr.io/speaches-ai/speaches:latest
-    environment:
-      WHISPER__MODEL: ${WHISPER_MODEL:-Systran/faster-whisper-large-v3-turbo}
-    volumes:
-      - speaches-models:/root/.cache/huggingface
-    healthcheck:
-      test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
-      interval: 30s
-      timeout: 10s
-      retries: 5
-      start_period: 120s
-    networks:
-      - internal
-      - traefik-public
-    deploy:
-      restart_policy:
-        condition: on-failure
-        delay: 10s
-      labels:
-        - "traefik.enable=true"
-        - "traefik.http.routers.speech-stt.rule=Host(`${STT_DOMAIN}`)"
-        - "traefik.http.routers.speech-stt.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
-        - "traefik.http.routers.speech-stt.tls=${TRAEFIK_TLS_ENABLED:-true}"
-        - "traefik.http.routers.speech-stt.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
-        - "traefik.http.services.speech-stt.loadbalancer.server.port=8000"
-        - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-traefik-public}"
-
-  # ======================
-  # Kokoro TTS (Default TTS)
-  # ======================
-  # High-quality text-to-speech engine. Always deployed alongside Speaches.
-  kokoro-tts:
-    image: ghcr.io/remsky/kokoro-fastapi:latest-cpu
-    healthcheck:
-      test: ["CMD-SHELL", "curl -f http://localhost:8880/health || exit 1"]
-      interval: 30s
-      timeout: 10s
-      retries: 5
-      start_period: 120s
-    networks:
-      - internal
-      - traefik-public
-    deploy:
-      restart_policy:
-        condition: on-failure
-        delay: 10s
-      labels:
-        - "traefik.enable=true"
-        - "traefik.http.routers.speech-tts.rule=Host(`${TTS_DOMAIN}`)"
-        - "traefik.http.routers.speech-tts.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
-        - "traefik.http.routers.speech-tts.tls=${TRAEFIK_TLS_ENABLED:-true}"
-        - "traefik.http.routers.speech-tts.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
-        - "traefik.http.services.speech-tts.loadbalancer.server.port=8880"
-        - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-traefik-public}"
-
-  # ======================
-  # Chatterbox TTS (Premium TTS - Optional)
-  # ======================
-  # Premium TTS with voice cloning capabilities. Requires NVIDIA GPU.
-  #
-  # To enable: Uncomment this service and set CHATTERBOX_TTS_DOMAIN.
-  #
-  # For Docker Swarm GPU scheduling, configure generic resources on the node:
-  #   /etc/docker/daemon.json:
-  #     { "runtimes": { "nvidia": { ... } },
-  #       "node-generic-resources": ["NVIDIA-GPU=0"] }
-  #
-  # chatterbox-tts:
-  #   image: devnen/chatterbox-tts-server:latest
-  #   healthcheck:
-  #     test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
-  #     interval: 30s
-  #     timeout: 10s
-  #     retries: 5
-  #     start_period: 180s
-  #   networks:
-  #     - internal
-  #     - traefik-public
-  #   deploy:
-  #     restart_policy:
-  #       condition: on-failure
-  #       delay: 10s
-  #     resources:
-  #       reservations:
-  #         generic_resources:
-  #           - discrete_resource_spec:
-  #               kind: "NVIDIA-GPU"
-  #               value: 1
-  #     labels:
-  #       - "traefik.enable=true"
-  #       - "traefik.http.routers.speech-tts-premium.rule=Host(`${CHATTERBOX_TTS_DOMAIN}`)"
-  #       - "traefik.http.routers.speech-tts-premium.entrypoints=${TRAEFIK_ENTRYPOINT:-websecure}"
-  #       - "traefik.http.routers.speech-tts-premium.tls=${TRAEFIK_TLS_ENABLED:-true}"
-  #       - "traefik.http.routers.speech-tts-premium.tls.certresolver=${TRAEFIK_CERTRESOLVER:-}"
-  #       - "traefik.http.services.speech-tts-premium.loadbalancer.server.port=8000"
-  #       - "traefik.docker.network=${TRAEFIK_DOCKER_NETWORK:-traefik-public}"
-
-volumes:
-  speaches-models:
-
-networks:
-  internal:
-    driver: overlay
-  traefik-public:
-    external: true
-    name: ${TRAEFIK_DOCKER_NETWORK:-traefik-public}
diff --git a/docker/matrix/element/config.json b/docker/matrix/element/config.json
index 509f013..1cdbfbe 100644
--- a/docker/matrix/element/config.json
+++ b/docker/matrix/element/config.json
@@ -1,30 +1,34 @@
 {
   "default_server_config": {
     "m.homeserver": {
-      "base_url": "http://localhost:8008",
-      "server_name": "localhost"
+      "base_url": "https://matrix.mosaicstack.dev",
+      "server_name": "matrix.mosaicstack.dev"
+    },
+    "m.identity_server": {
+      "base_url": "https://vector.im"
     }
   },
-  "brand": "Mosaic Stack Dev",
+  "brand": "Mosaic Chat",
+  "integrations_ui_url": "https://scalar.vector.im/",
+  "integrations_rest_url": "https://scalar.vector.im/api",
+  "integrations_widgets_urls": [
+    "https://scalar.vector.im/_matrix/integrations/v1",
+    "https://scalar.vector.im/api",
+    "https://scalar-staging.vector.im/_matrix/integrations/v1",
+    "https://scalar-staging.vector.im/api",
+    "https://scalar-staging.riot.im/scalar/api"
+  ],
+  "disable_custom_urls": false,
+  "disable_guests": true,
+  "disable_login_language_selector": false,
+  "disable_3pid_login": false,
+  "default_country_code": "US",
+  "show_labs_settings": false,
   "default_theme": "dark",
   "room_directory": {
-    "servers": ["localhost"]
+    "servers": ["matrix.mosaicstack.dev"]
   },
-  "features": {
-    "feature_video_rooms": false,
-    "feature_group_calls": false
-  },
-  "show_labs_settings": true,
-  "piwik": false,
-  "posthog": {
-    "enabled": false
-  },
-  "privacy_policy_url": null,
-  "terms_and_conditions_links": [],
   "setting_defaults": {
-    "breadcrumbs": true,
-    "custom_themes": []
-  },
-  "disable_guests": true,
-  "disable_3pid_login": true
+    "breadcrumbs": true
+  }
 }
diff --git a/docker/matrix/synapse/homeserver.yaml b/docker/matrix/synapse/homeserver.yaml
index 304387c..35e09e5 100644
--- a/docker/matrix/synapse/homeserver.yaml
+++ b/docker/matrix/synapse/homeserver.yaml
@@ -1,27 +1,31 @@
 # ==============================================
-# Synapse Homeserver Configuration — Development Only
+# Synapse Homeserver Configuration — Production
 # ==============================================
 #
-# This config is for LOCAL DEVELOPMENT with the Mosaic Stack docker-compose overlay.
-# Do NOT use this in production. See docker-compose.sample.matrix.yml for production.
+# Deploy to /opt/mosaic/synapse/homeserver.yaml on the Docker host.
 #
-# Server name is set to 'localhost' — this is permanent and cannot be changed
-# after the database has been initialized.
+# IMPORTANT: server_name is PERMANENT. It becomes part of every user ID
+# (@user:server_name) and room alias. It cannot be changed after the
+# database has been initialized without losing all data.
+#
+# Before first deploy, replace ALL placeholders marked REPLACE_*.
 #
 # ==============================================
 
-server_name: "localhost"
+# REPLACE with your Matrix domain (e.g. matrix.mosaicstack.dev)
+# This is permanent — cannot be changed after first startup.
+server_name: "REPLACE_MATRIX_DOMAIN"
 pid_file: /data/homeserver.pid
-public_baseurl: "http://localhost:8008/"
+public_baseurl: "https://REPLACE_MATRIX_DOMAIN/"
 
 # ======================
 # Network Listeners
 # ======================
 listeners:
-  # Client API (used by Element Web, Mosaic bridge, etc.)
   - port: 8008
     tls: false
     type: http
+    # Traefik terminates TLS and forwards via X-Forwarded-For
     x_forwarded: true
     bind_addresses: ["0.0.0.0"]
     resources:
@@ -35,9 +39,11 @@ database:
   name: psycopg2
   txn_limit: 10000
   args:
-    user: "synapse"
-    password: "synapse_dev_password"
-    database: "synapse"
+    # Must match SYNAPSE_POSTGRES_USER / SYNAPSE_POSTGRES_PASSWORD
+    # from your Portainer environment variables
+    user: "REPLACE_SYNAPSE_DB_USER"
+    password: "REPLACE_SYNAPSE_DB_PASSWORD"
+    database: "REPLACE_SYNAPSE_DB_NAME"
     host: "postgres"
     port: 5432
     cp_min: 5
@@ -66,20 +72,25 @@ url_preview_ip_range_blacklist:
   - "fec0::/10"
 
 # ======================
-# Registration (Dev Only)
+# Registration
 # ======================
-enable_registration: true
-enable_registration_without_verification: true
+# Public registration disabled. Create accounts via the admin API or CLI:
+#   docker exec -it <container> register_new_matrix_user \
+#     -u username -c /data/homeserver.yaml http://localhost:8008
+enable_registration: false
 
 # ======================
 # Signing Keys
 # ======================
-# Auto-generated on first startup and persisted in the signing_key volume
-signing_key_path: "/data/keys/localhost.signing.key"
+# Auto-generated on first startup and persisted in /opt/mosaic/synapse/keys/
+signing_key_path: "/data/keys/signing.key"
 
-# Suppress warning about trusted key servers in dev
-suppress_key_server_warning: true
-trusted_key_servers: []
+# ======================
+# Trusted Key Servers
+# ======================
+# matrix.org is the default. Set to [] to disable federation key trust.
+trusted_key_servers:
+  - server_name: "matrix.org"
 
 # ======================
 # Room Configuration
@@ -88,44 +99,46 @@ enable_room_list_search: true
 allow_public_rooms_over_federation: false
 
 # ======================
-# Rate Limiting (Relaxed for Dev)
+# Rate Limiting
 # ======================
 rc_message:
-  per_second: 100
-  burst_count: 200
-
-rc_registration:
   per_second: 10
   burst_count: 50
 
+rc_registration:
+  per_second: 1
+  burst_count: 5
+
 rc_login:
   address:
-    per_second: 10
-    burst_count: 50
+    per_second: 3
+    burst_count: 10
   account:
-    per_second: 10
-    burst_count: 50
+    per_second: 3
+    burst_count: 10
 
 # ======================
 # Logging
 # ======================
-log_config: "/data/localhost.log.config"
-
-# Inline log config — write to stdout for docker logs
-# Synapse falls back to a basic console logger if the log_config file is missing,
-# so we leave log_config pointing to a non-existent file intentionally.
-# Override: mount a custom log config file at /data/localhost.log.config
+# Synapse falls back to a basic console logger (stdout) when this file
+# does not exist, which is ideal for Docker log collection.
+log_config: "/data/log.config"
 
 # ======================
-# Miscellaneous
+# Secrets
 # ======================
+# Generate with: python3 -c 'import secrets; print(secrets.token_hex(32))'
 report_stats: false
-macaroon_secret_key: "dev-macaroon-secret-change-in-production"
-form_secret: "dev-form-secret-change-in-production"
+macaroon_secret_key: "REPLACE_MACAROON_SECRET"
+form_secret: "REPLACE_FORM_SECRET"
 
-# Enable presence for dev
+# ======================
+# Presence & Retention
+# ======================
 use_presence: true
 
-# Retention policy (optional, keep messages for 180 days in dev)
 retention:
-  enabled: false
+  enabled: true
+  default_policy:
+    min_lifetime: 1d
+    max_lifetime: 365d
diff --git a/docker/openbao/config.hcl b/docker/openbao/config.hcl
index d9f578c..ea42bbe 100644
--- a/docker/openbao/config.hcl
+++ b/docker/openbao/config.hcl
@@ -11,9 +11,6 @@ listener "tcp" {
   tls_disable = 1
 }
 
-# Disable memory locking for Docker compatibility
-disable_mlock = true
-
 # API address for cluster communication
 api_addr = "http://0.0.0.0:8200"
 
diff --git a/docs/1-getting-started/2-installation/3-docker-setup.md b/docs/1-getting-started/2-installation/3-docker-setup.md
index c5a03f7..0d2c666 100644
--- a/docs/1-getting-started/2-installation/3-docker-setup.md
+++ b/docs/1-getting-started/2-installation/3-docker-setup.md
@@ -219,7 +219,7 @@ JWT_EXPIRATION=24h
 OIDC_ISSUER=https://auth.example.com/application/o/mosaic/
 OIDC_CLIENT_ID=prod-client-id
 OIDC_CLIENT_SECRET=prod-client-secret
-OIDC_REDIRECT_URI=https://mosaic.example.com/auth/callback
+OIDC_REDIRECT_URI=https://mosaic.example.com/auth/oauth2/callback/authentik
 ```
 
 ### Compose Override for Production
diff --git a/docs/1-getting-started/3-configuration/1-environment.md b/docs/1-getting-started/3-configuration/1-environment.md
index 1cd827b..28b4505 100644
--- a/docs/1-getting-started/3-configuration/1-environment.md
+++ b/docs/1-getting-started/3-configuration/1-environment.md
@@ -89,7 +89,7 @@ OIDC_CLIENT_ID=your-client-id
 OIDC_CLIENT_SECRET=your-client-secret
 
 # Callback URL (must match Authentik configuration)
-OIDC_REDIRECT_URI=http://localhost:3001/auth/callback
+OIDC_REDIRECT_URI=http://localhost:3001/auth/oauth2/callback/authentik
 ```
 
 See [Authentik Setup](2-authentik.md) for complete OIDC configuration.
@@ -229,7 +229,7 @@ JWT_EXPIRATION=24h
 OIDC_ISSUER=https://auth.example.com/application/o/mosaic-stack/
 OIDC_CLIENT_ID=your-client-id
 OIDC_CLIENT_SECRET=your-client-secret
-OIDC_REDIRECT_URI=http://localhost:3001/auth/callback
+OIDC_REDIRECT_URI=http://localhost:3001/auth/oauth2/callback/authentik
 
 # ======================
 # Cache
diff --git a/docs/1-getting-started/3-configuration/2-authentik.md b/docs/1-getting-started/3-configuration/2-authentik.md
index dceee03..15a4bbe 100644
--- a/docs/1-getting-started/3-configuration/2-authentik.md
+++ b/docs/1-getting-started/3-configuration/2-authentik.md
@@ -54,17 +54,17 @@ Sign up at [goauthentik.io](https://goauthentik.io) for managed Authentik.
 
 4. **Configure Provider:**
 
-   | Field                          | Value                                           |
-   | ------------------------------ | ----------------------------------------------- |
-   | **Name**                       | Mosaic Stack                                    |
-   | **Authorization flow**         | default-provider-authorization-implicit-consent |
-   | **Client type**                | Confidential                                    |
-   | **Client ID**                  | (auto-generated, save this)                     |
-   | **Client Secret**              | (auto-generated, save this)                     |
-   | **Redirect URIs**              | `http://localhost:3001/auth/callback`           |
-   | **Scopes**                     | `openid`, `email`, `profile`                    |
-   | **Subject mode**               | Based on User's UUID                            |
-   | **Include claims in id_token** | ✅ Enabled                                      |
+   | Field                          | Value                                                  |
+   | ------------------------------ | ------------------------------------------------------ |
+   | **Name**                       | Mosaic Stack                                           |
+   | **Authorization flow**         | default-provider-authorization-implicit-consent        |
+   | **Client type**                | Confidential                                           |
+   | **Client ID**                  | (auto-generated, save this)                            |
+   | **Client Secret**              | (auto-generated, save this)                            |
+   | **Redirect URIs**              | `http://localhost:3001/auth/oauth2/callback/authentik` |
+   | **Scopes**                     | `openid`, `email`, `profile`                           |
+   | **Subject mode**               | Based on User's UUID                                   |
+   | **Include claims in id_token** | ✅ Enabled                                             |
 
 5. **Click "Create"**
 
@@ -96,7 +96,7 @@ Update your `.env` file:
 OIDC_ISSUER=http://localhost:9000/application/o/mosaic-stack/
 OIDC_CLIENT_ID=<your-client-id-from-step-2>
 OIDC_CLIENT_SECRET=<your-client-secret-from-step-2>
-OIDC_REDIRECT_URI=http://localhost:3001/auth/callback
+OIDC_REDIRECT_URI=http://localhost:3001/auth/oauth2/callback/authentik
 ```
 
 **Important Notes:**
@@ -113,7 +113,7 @@ For production deployments:
 OIDC_ISSUER=https://auth.example.com/application/o/mosaic-stack/
 OIDC_CLIENT_ID=prod-client-id
 OIDC_CLIENT_SECRET=prod-client-secret
-OIDC_REDIRECT_URI=https://mosaic.example.com/auth/callback
+OIDC_REDIRECT_URI=https://mosaic.example.com/auth/oauth2/callback/authentik
 ```
 
 Update Authentik redirect URIs to match your production URL.
@@ -143,7 +143,7 @@ docker compose restart api
 
 ```bash
 # Initiate OIDC flow
-curl http://localhost:3001/auth/callback/authentik
+curl http://localhost:3001/auth/oauth2/callback/authentik
 
 # This will return a redirect URL to Authentik
 ```
@@ -223,8 +223,8 @@ Customize Authentik's login page:
 
 ```bash
 # Ensure exact match (including http vs https)
-# In Authentik: http://localhost:3001/auth/callback
-# In .env: OIDC_REDIRECT_URI=http://localhost:3001/auth/callback
+# In Authentik: http://localhost:3001/auth/oauth2/callback/authentik
+# In .env: OIDC_REDIRECT_URI=http://localhost:3001/auth/oauth2/callback/authentik
 ```
 
 ### Error: "Invalid client credentials"
diff --git a/docs/1-getting-started/3-configuration/3-docker.md b/docs/1-getting-started/3-configuration/3-docker.md
index 767b90d..4cfc6b4 100644
--- a/docs/1-getting-started/3-configuration/3-docker.md
+++ b/docs/1-getting-started/3-configuration/3-docker.md
@@ -89,7 +89,7 @@ AUTHENTIK_PORT_HTTPS=9443
 OIDC_ISSUER=http://localhost:9000/application/o/mosaic-stack/
 OIDC_CLIENT_ID=your-client-id-here
 OIDC_CLIENT_SECRET=your-client-secret-here
-OIDC_REDIRECT_URI=http://localhost:3001/auth/callback
+OIDC_REDIRECT_URI=http://localhost:3001/auth/oauth2/callback/authentik
 ```
 
 **Bootstrap Credentials:**
diff --git a/docs/4-api/2-authentication/1-endpoints.md b/docs/4-api/2-authentication/1-endpoints.md
index 754dd01..e8a13de 100644
--- a/docs/4-api/2-authentication/1-endpoints.md
+++ b/docs/4-api/2-authentication/1-endpoints.md
@@ -191,7 +191,7 @@ Authorization: Bearer {session_token}
 OAuth callback handler for Authentik (and other OIDC providers).
 
 ```http
-GET /auth/callback/authentik
+GET /auth/oauth2/callback/authentik
 ```
 
 **Query Parameters:**
@@ -226,7 +226,7 @@ This endpoint is called by the OIDC provider after successful authentication.
 1. User clicks "Sign in with Authentik"
 2. Frontend redirects to Authentik
 3. User authenticates with Authentik
-4. Authentik redirects to /auth/callback/authentik
+4. Authentik redirects to /auth/oauth2/callback/authentik
 5. Server exchanges code for tokens
 6. Server creates/updates user
 7. Server creates session
diff --git a/docs/DOCKER-SWARM.md b/docs/DOCKER-SWARM.md
index 77c69ee..30bc3fe 100644
--- a/docs/DOCKER-SWARM.md
+++ b/docs/DOCKER-SWARM.md
@@ -43,7 +43,10 @@ ENCRYPTION_KEY=$(openssl rand -hex 32)
 ORCHESTRATOR_API_KEY=$(openssl rand -base64 32)
 COORDINATOR_API_KEY=$(openssl rand -base64 32)
 
-# Claude API Key
+# AI Provider for Orchestrator
+AI_PROVIDER=ollama
+
+# Claude API Key (only required when AI_PROVIDER=claude)
 CLAUDE_API_KEY=your-claude-api-key
 
 # Authentik Bootstrap
diff --git a/docs/PORTAINER-DEPLOYMENT.md b/docs/PORTAINER-DEPLOYMENT.md
index 3015964..e331ee7 100644
--- a/docs/PORTAINER-DEPLOYMENT.md
+++ b/docs/PORTAINER-DEPLOYMENT.md
@@ -111,7 +111,7 @@ If using private registry images from `git.mosaicstack.dev`:
    OIDC_CLIENT_ID=<your-oidc-client-id>
    OIDC_CLIENT_SECRET=<your-oidc-client-secret>
    OIDC_ISSUER=https://auth.diversecanvas.com/application/o/mosaic-stack/
-   OIDC_REDIRECT_URI=https://api.mosaicstack.dev/auth/callback/authentik
+   OIDC_REDIRECT_URI=https://api.mosaicstack.dev/auth/oauth2/callback/authentik
    OLLAMA_ENDPOINT=http://10.1.1.42:11434
    ```
 
@@ -163,7 +163,7 @@ ENCRYPTION_KEY=<64-char-hex>     # openssl rand -hex 32
 OIDC_CLIENT_ID=<from-authentik>
 OIDC_CLIENT_SECRET=<from-authentik>
 OIDC_ISSUER=https://auth.diversecanvas.com/application/o/mosaic-stack/
-OIDC_REDIRECT_URI=https://api.mosaicstack.dev/auth/callback/authentik
+OIDC_REDIRECT_URI=https://api.mosaicstack.dev/auth/oauth2/callback/authentik
 
 # External Ollama
 OLLAMA_ENDPOINT=http://10.1.1.42:11434
@@ -352,7 +352,7 @@ Update environment variables:
 ```bash
 NEXT_PUBLIC_APP_URL=https://mosaic.example.com
 NEXT_PUBLIC_API_URL=https://api.example.com
-OIDC_REDIRECT_URI=https://api.example.com/auth/callback/authentik
+OIDC_REDIRECT_URI=https://api.example.com/auth/oauth2/callback/authentik
 ```
 
 ### Resource Limits
diff --git a/docs/SWARM-DEPLOYMENT.md b/docs/SWARM-DEPLOYMENT.md
index 86ba0dc..e389f24 100644
--- a/docs/SWARM-DEPLOYMENT.md
+++ b/docs/SWARM-DEPLOYMENT.md
@@ -369,7 +369,7 @@ sleep 30
    OIDC_ISSUER=https://auth.diversecanvas.com/application/o/mosaic-stack/
    OIDC_CLIENT_ID=your-client-id
    OIDC_CLIENT_SECRET=your-client-secret
-   OIDC_REDIRECT_URI=https://api.mosaicstack.dev/auth/callback/authentik
+   OIDC_REDIRECT_URI=https://api.mosaicstack.dev/auth/oauth2/callback/authentik
    ```
 
 ### Using External PostgreSQL
diff --git a/docs/plans/auth-frontend-remediation.md b/docs/plans/auth-frontend-remediation.md
index ae98b61..3e457a8 100644
--- a/docs/plans/auth-frontend-remediation.md
+++ b/docs/plans/auth-frontend-remediation.md
@@ -152,7 +152,7 @@ States:
 Add `OIDC_REDIRECT_URI` to `REQUIRED_OIDC_ENV_VARS`. Add URL format validation:
 
 - Must be a valid URL
-- Path must start with `/auth/callback`
+- Path must start with `/auth/oauth2/callback`
 - Warn if using `localhost` in production
 
 **Tests to add:** Missing var, invalid URL, invalid path, valid URL.
@@ -716,9 +716,9 @@ Browser                    NestJS API               Authentik
   ├────────────────────────────────────────────────────►│
   │                            │      User authenticates│
   │◄────────────────────────────────────────────────────┤
-  │ 302 → /auth/callback/authentik?code=X               │
+  │ 302 → /auth/oauth2/callback/authentik?code=X               │
   │                            │                        │
-  │ 5. GET /auth/callback/authentik?code=X              │
+  │ 5. GET /auth/oauth2/callback/authentik?code=X              │
   ├───────────────────────────►│                        │
   │                   BetterAuth exchanges code         │
   │                            ├───────────────────────►│
diff --git a/docs/scratchpads/362-auth-session-chain-debug.md b/docs/scratchpads/362-auth-session-chain-debug.md
new file mode 100644
index 0000000..3751e5c
--- /dev/null
+++ b/docs/scratchpads/362-auth-session-chain-debug.md
@@ -0,0 +1,240 @@
+# 362 - Auth Session Chain Debug (Authentik -> BetterAuth -> API Guard)
+
+## Context
+
+- Date (UTC): 2026-02-19
+- Environment under test: production domains
+  - Web: `https://app.mosaicstack.dev/login`
+  - API: `https://api.mosaicstack.dev`
+  - IdP: `https://auth.diversecanvas.com`
+- Tooling: Playwright MCP + Chromium
+
+## Problem Statement
+
+Users can complete Authentik login and consent, but Mosaic web app returns to login and remains unauthenticated.
+
+## Timeline and Evidence
+
+1. Initial reproduction from web login:
+   - `POST /auth/sign-in/oauth2` returned `200` with Authentik authorize URL.
+   - Authentik login flow and consent screen loaded correctly.
+
+2. First callback failure mode (before `jarvis` email fix):
+   - Callback ended at API error redirect with `error=email_is_missing`.
+   - Result URL: `https://api.mosaicstack.dev/?error=email_is_missing`.
+
+3. User updated Authentik account:
+   - `jarvis` account email set to `jarvis@mosaic.local`.
+   - `email_is_missing` failure no longer occurs.
+
+4. Current callback behavior (after email fix):
+   - `GET /auth/oauth2/callback/authentik?code=...&state=...` returns `302` to `https://app.mosaicstack.dev/`.
+   - Callback sets BetterAuth cookies:
+     - `__Secure-better-auth.state=...; Max-Age=0; ...`
+     - `__Secure-better-auth.session_token=...; Max-Age=604800; Path=/; HttpOnly; Secure; SameSite=Lax`
+   - Browser cookie jar confirms session cookie present for `api.mosaicstack.dev`.
+
+5. Session validation mismatch (critical):
+   - BetterAuth direct session endpoint succeeds:
+     - `GET /auth/get-session` -> `200` with session payload.
+   - Guarded API session endpoint fails:
+     - `GET /auth/session` -> `401` with
+       `{"message":"Invalid or expired session", ...}`
+   - Reproduced repeatedly in same browser context immediately after callback.
+
+## Config Sync Notes
+
+User synced local files with deployed Portainer stack:
+
+- `.env` updated with deployed values.
+- `docker-compose.swarm.portainer.yml` changed:
+  - Removed `BETTER_AUTH_URL` env mapping from API service.
+
+Observed auth behavior after sync:
+
+- Improvement: removed `email_is_missing` callback error.
+- Remaining failure: `/auth/session` still returns 401 despite valid BetterAuth cookie and successful `/auth/get-session`.
+
+## Root Cause Hypothesis (Strong)
+
+`AuthGuard` extracts BetterAuth session cookie token correctly, but `AuthService.verifySession()` validates it using `Authorization: Bearer <token>` instead of a BetterAuth cookie/header context.
+
+Relevant code paths:
+
+- `apps/api/src/auth/guards/auth.guard.ts`
+  - extracts `__Secure-better-auth.session_token` / `better-auth.session_token`
+- `apps/api/src/auth/auth.service.ts`
+  - `verifySession()` calls `auth.api.getSession({ headers: { authorization: "Bearer ..." } })`
+
+Why this matches evidence:
+
+- `/auth/get-session` (native BetterAuth endpoint reading request cookie) succeeds.
+- `/auth/session` (custom guard + verify path) fails for same browser session.
+
+## Next Actions
+
+1. Fix `verifySession()` to validate using BetterAuth-compatible cookie header candidates first, with bearer fallback for API clients.
+2. Add/update unit tests in `auth.service.spec.ts` to cover cookie-first validation and bearer fallback.
+3. Re-run targeted API auth tests.
+4. Re-run Playwright auth chain to confirm:
+   - callback sets cookie
+   - `/auth/session` returns `200`
+   - web app transitions out of `/login`.
+
+## Implementation Update (2026-02-19)
+
+Completed items:
+
+1. Updated backend session verification logic:
+   - File: `apps/api/src/auth/auth.service.ts`
+   - `verifySession()` now tries session resolution in this order:
+     - `cookie: __Secure-better-auth.session_token=<token>`
+     - `cookie: better-auth.session_token=<token>`
+     - `cookie: __Host-better-auth.session_token=<token>`
+     - `authorization: Bearer <token>` (fallback)
+   - Added helper methods:
+     - `buildSessionHeaderCandidates()`
+     - `isExpectedAuthError()`
+
+2. Added/updated tests:
+   - File: `apps/api/src/auth/auth.service.spec.ts`
+   - Added RED->GREEN test:
+     - `should validate session token using secure BetterAuth cookie header`
+   - Updated fallback coverage test:
+     - `should fall back to Authorization header when cookie-based lookups miss`
+
+3. Verification:
+   - Command: `pnpm --filter @mosaic/api test -- src/auth/auth.service.spec.ts`
+   - Result: pass (all tests green).
+   - Command: `pnpm --filter @mosaic/api lint`
+   - Result: pass.
+
+Remaining step (requires deploy):
+
+- Redeploy API with this patch and rerun live Playwright flow on `app.mosaicstack.dev` to confirm `/auth/session` returns `200` after callback.
+
+## Playwright Re-Check (2026-02-19, later run)
+
+Live flow evidence after previous deploy attempt:
+
+1. OAuth callback succeeds:
+   - `GET https://api.mosaicstack.dev/auth/oauth2/callback/authentik?code=...&state=...` -> `302`
+   - Redirect target observed: `https://app.mosaicstack.dev/`
+   - Browser cookie jar includes:
+     - `__Secure-better-auth.session_token` on `api.mosaicstack.dev` (HttpOnly, Secure, SameSite=Lax)
+
+2. Session bootstrap still fails immediately:
+   - `GET https://api.mosaicstack.dev/auth/session` -> `500`
+   - Response body shape:
+     - `{"success":false,"message":"An unexpected error occurred","errorId":"...","path":"/auth/session","statusCode":500}`
+   - Web app returns to login because session fetch fails.
+
+3. Frontend version mismatch observed:
+   - Live `POST /auth/sign-in/oauth2` response from login flow still shows callback URL pointing to `/dashboard`.
+   - Current repository login page uses callback URL `/`.
+   - This indicates deployed web image is older than current `develop` code (or stale image tag in runtime).
+
+## Additional Code Fix Applied Locally (pending push/deploy)
+
+Refined cookie candidate construction in API session verification:
+
+- File: `apps/api/src/auth/auth.service.ts`
+  - Removed URL-encoding of session token when constructing cookie headers.
+  - Cookie candidates now pass raw token value exactly as extracted from incoming cookie.
+
+Why:
+
+- BetterAuth cookie tokens can contain characters like `/`, `+`, and `=`.
+- Re-encoding these values can mutate token bytes and cause lookup/parse failures.
+
+Regression test added:
+
+- File: `apps/api/src/auth/auth.service.spec.ts`
+  - `should preserve raw cookie token value without URL re-encoding`
+
+## Deploy + Live Repro (after auth cookie fix deploy)
+
+Deployment actions executed:
+
+1. Pushed auth cookie fix commit to `develop`.
+2. Waited for Woodpecker pipeline success (`mosaic/stack`, build `#514`).
+3. On `10.1.1.90`:
+   - Ran `/home/localadmin/mosaic/pull_all.sh`.
+   - Updated swarm services to `:dev` images:
+     - `stack_api`
+     - `stack_web`
+     - `stack_coordinator`
+     - `stack_orchestrator`
+   - Verified service convergence.
+
+Post-deploy behavior:
+
+- Initial `/auth/session` without cookies now returns `401` (expected).
+- OAuth callback succeeds and sets BetterAuth session cookie.
+- `/auth/session` still fails after callback, now due to a new backend `500`.
+
+## New Root Cause Discovered (RLS interceptor SQL)
+
+Live `stack_api` logs showed:
+
+- Auth guard successfully finds session cookie:
+  - `Session cookie found: __Secure-better-auth.session_token`
+- Then failure inside RLS setup:
+  - PostgreSQL `42601` syntax error at or near `$1`
+  - Source: `RlsContextInterceptor` raw SQL while setting context vars
+  - Request ends as `500 Request processing failed` on `/auth/session`
+
+Cause:
+
+- `SET LOCAL app.current_user_id = ${userId}` became `SET LOCAL ... = $1` under parameterization.
+- PostgreSQL does not accept bind placeholders in `SET` assignment syntax.
+
+## RLS Fix Applied Locally (pending commit/deploy)
+
+Files updated:
+
+- `apps/api/src/common/interceptors/rls-context.interceptor.ts`
+  - Replaced `SET LOCAL` statements with parameter-safe, transaction-local calls:
+    - `SELECT set_config('app.current_user_id', ${userId}, true)`
+    - `SELECT set_config('app.current_workspace_id', ${workspaceId}, true)`
+  - Keeps transaction scoping (`true` => local to transaction).
+
+- `apps/api/src/common/interceptors/rls-context.interceptor.spec.ts`
+  - Updated expected SQL template fragments to `set_config(...)`.
+
+- `apps/api/src/common/interceptors/rls-context.integration.spec.ts`
+  - Updated integration expectations to `set_config(...)`.
+
+## Deploy + Verify (RLS fix commit `8424a28`)
+
+Pipeline and deploy sequence:
+
+1. Commit `8424a28` pushed to `develop`.
+2. Woodpecker pipeline `mosaic/stack#515` completed successfully.
+3. Host deploy actions on `10.1.1.90`:
+   - Ran `/home/localadmin/mosaic/pull_all.sh`
+   - Updated swarm services (`stack_api`, `stack_web`, `stack_coordinator`, `stack_orchestrator`) to `:dev`
+
+Observed issue after first restart:
+
+- Playwright still reproduced `/auth/session` `500` after Authentik callback.
+- `stack_api` logs still showed old RLS SQL failure (`SET LOCAL ... $1`), indicating runtime image drift/stale task.
+
+Resolution:
+
+1. Checked host image digest for API:
+   - `git.mosaicstack.dev/mosaic/stack-api:dev` -> `sha256:fd0cbfe053ed27945577553d67da5cbda0bf71610006e5ccc197d5761e29a220`
+2. Forced swarm API service to exact digest:
+   - `docker service update --with-registry-auth --image git.mosaicstack.dev/mosaic/stack-api@sha256:fd0cbfe053ed27945577553d67da5cbda0bf71610006e5ccc197d5761e29a220 stack_api`
+3. Verified new running task uses digest-pinned image.
+
+Final verification (Playwright MCP):
+
+- Login flow: `https://app.mosaicstack.dev/login` -> Authentik (`jarvis` / `jarvis`) -> redirect back to app.
+- Session endpoint: `GET https://api.mosaicstack.dev/auth/session` -> `200`.
+- App landed authenticated on `https://app.mosaicstack.dev/tasks` (not bounced to login).
+
+Status:
+
+- Auth chain is functioning end-to-end after digest-forced API rollout.
+- Remaining console noise observed: missing `favicon.ico` (`404`) on app domain (non-blocking for auth).
diff --git a/docs/scratchpads/4-authentik-oidc-final-status.md b/docs/scratchpads/4-authentik-oidc-final-status.md
index 8c00233..6330847 100644
--- a/docs/scratchpads/4-authentik-oidc-final-status.md
+++ b/docs/scratchpads/4-authentik-oidc-final-status.md
@@ -166,7 +166,7 @@ To use the authentication system, configure these environment variables:
 OIDC_ISSUER=https://auth.example.com/application/o/mosaic-stack/
 OIDC_CLIENT_ID=your-client-id
 OIDC_CLIENT_SECRET=your-client-secret
-OIDC_REDIRECT_URI=http://localhost:3001/auth/callback
+OIDC_REDIRECT_URI=http://localhost:3001/auth/oauth2/callback/authentik
 
 # JWT Session Management
 JWT_SECRET=change-this-to-a-random-secret-in-production
@@ -186,7 +186,7 @@ BetterAuth provides these endpoints automatically:
 - `POST /auth/sign-up` - User registration
 - `POST /auth/sign-out` - Logout
 - `GET /auth/session` - Get current session
-- `GET /auth/callback/authentik` - OAuth callback handler
+- `GET /auth/oauth2/callback/authentik` - OAuth callback handler
 - `GET /auth/profile` - Get authenticated user profile (custom)
 
 ---
diff --git a/docs/scratchpads/6-basic-web-ui.md b/docs/scratchpads/6-basic-web-ui.md
index cc25219..1e8b664 100644
--- a/docs/scratchpads/6-basic-web-ui.md
+++ b/docs/scratchpads/6-basic-web-ui.md
@@ -188,7 +188,7 @@ All components must follow TDD (tests first), achieve 85%+ coverage, and use PDA
 ### Existing Auth Implementation (from Issue #4)
 
 - BetterAuth is configured in the API (`apps/api/src/auth/`)
-- Endpoints: `/auth/callback/authentik`, `/auth/session`, `/auth/profile`
+- Endpoints: `/auth/oauth2/callback/authentik`, `/auth/session`, `/auth/profile`
 - Shared types available in `@mosaic/shared` package
 - Session-based auth with JWT tokens
 
@@ -313,7 +313,7 @@ Based on existing backend (from Issue #4):
 - `GET /auth/session` - Get current session
 - `GET /auth/profile` - Get user profile
 - `POST /auth/sign-out` - Logout
-- `GET /auth/callback/authentik` - OIDC callback (redirect from Authentik)
+- `GET /auth/oauth2/callback/authentik` - OIDC callback (redirect from Authentik)
 
 ### Tasks (to be implemented in future issue)
 
diff --git a/docs/scratchpads/86-authentik-oidc-integration.md b/docs/scratchpads/86-authentik-oidc-integration.md
index 1152fde..87866a0 100644
--- a/docs/scratchpads/86-authentik-oidc-integration.md
+++ b/docs/scratchpads/86-authentik-oidc-integration.md
@@ -161,7 +161,7 @@ Enhance `ConnectionService` to handle OIDC-based authentication:
 **Integration Tests**:
 
 - POST /auth/initiate starts OIDC flow with correct params
-- GET /auth/callback handles OIDC response and creates identity
+- GET /auth/oauth2/callback/:providerId handles OIDC response and creates identity
 - POST /auth/validate validates tokens from federated instances
 - GET /auth/identities returns user's federated identities
 - Federated requests with valid tokens are authenticated
diff --git a/docs/tasks.md b/docs/tasks.md
index f6a3083..3026d4f 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -314,3 +314,92 @@
 | 12 - QA: Test Coverage          | #411  | 4      | 35K            |
 | 13 - QA R2: Hardening + Tests   | #411  | 7      | 57K            |
 | **Total**                       |       | **64** | **605K**       |
+
+---
+
+## 2026-02-17 Full Code/Security/QA Review
+
+**Reviewer:** Jarvis (Codex runtime)
+**Scope:** Monorepo code review + security review + QA verification
+**Branch:** `fix/auth-frontend-remediation`
+
+### Verification Snapshot
+
+- `pnpm lint`: pass
+- `pnpm typecheck`: pass
+- `pnpm --filter @mosaic/api test -- src/mosaic-telemetry/mosaic-telemetry.module.spec.ts src/auth/auth-rls.integration.spec.ts src/credentials/user-credential.model.spec.ts src/job-events/job-events.performance.spec.ts src/knowledge/services/fulltext-search.spec.ts`: pass (DB-bound suites intentionally skipped unless `RUN_DB_TESTS=true`)
+- `pnpm audit --prod`: pass (0 vulnerabilities after overrides + lock refresh)
+
+### Remediation Tasks
+
+| id           | status | severity | category            | description                                                                                                                                                                                                                                                                                                                        | evidence                                                                                                                                                                                                                                    |
+| ------------ | ------ | -------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| REV-2026-001 | done   | high     | security+functional | Web dashboard widgets call orchestrator `GET /agents` directly without `X-API-Key`, but orchestrator protects all `/agents` routes with `OrchestratorApiKeyGuard`. This creates a broken production path or pressures exposing a sensitive API key client-side. Add a server-side proxy/BFF route and remove direct browser calls. | `apps/web/src/app/api/orchestrator/agents/route.ts:1`, `apps/web/src/components/widgets/AgentStatusWidget.tsx:32`, `apps/web/src/components/widgets/TaskProgressWidget.tsx:103`                                                             |
+| REV-2026-002 | done   | high     | security            | RLS context helpers are now applied in `TasksService` service boundaries (`create`, `findAll`, `findOne`, `update`, `remove`) with safe fallback behavior for test doubles; controller now passes user context for list/detail paths, and regression tests assert context usage.                                                   | `apps/api/src/tasks/tasks.service.ts:27`, `apps/api/src/tasks/tasks.controller.ts:54`, `apps/api/src/tasks/tasks.service.spec.ts:15`                                                                                                        |
+| REV-2026-003 | done   | medium   | security            | Docker sandbox defaults still use `bridge` networking; isolation hardening is incomplete by default. Move default to `none` and explicitly opt in to egress where required.                                                                                                                                                        | `apps/orchestrator/src/config/orchestrator.config.ts:32`, `apps/orchestrator/src/spawner/docker-sandbox.service.ts:115`, `apps/orchestrator/src/spawner/docker-sandbox.service.ts:265`                                                      |
+| REV-2026-004 | done   | high     | security            | Production dependency chain hardened via root overrides: replaced legacy `request` with `@cypress/request`, pinned `tough-cookie` and `qs` to patched ranges, and forced patched `ajv`; lockfile updated and production audit now reports zero vulnerabilities.                                                                    | `package.json:68`, `pnpm-lock.yaml:1`, `pnpm audit --prod --json` (0 vulnerabilities)                                                                                                                                                       |
+| REV-2026-005 | done   | high     | qa                  | API test suite is not hermetic for default `pnpm test`: database-backed tests run when `DATABASE_URL` exists but credentials are invalid, causing hard failures. Gate integration/perf suites behind explicit integration flag and connectivity preflight, or split commands in turbo pipeline.                                    | `apps/api/src/credentials/user-credential.model.spec.ts:18`, `apps/api/src/knowledge/services/fulltext-search.spec.ts:30`, `apps/api/src/job-events/job-events.performance.spec.ts:19`, `apps/api/src/auth/auth-rls.integration.spec.ts:10` |
+| REV-2026-006 | done   | medium   | qa+architecture     | `MosaicTelemetryModule` imports `AuthModule`, causing telemetry module tests to fail on unrelated `ENCRYPTION_KEY` auth config requirements. Decouple telemetry module dependencies or provide test-safe module overrides.                                                                                                         | `apps/api/src/mosaic-telemetry/mosaic-telemetry.module.ts:36`, `apps/api/src/mosaic-telemetry/mosaic-telemetry.module.spec.ts:1`                                                                                                            |
+| REV-2026-007 | done   | medium   | qa                  | Frontend skip cleanup completed for scoped findings: `TasksWidget`, `CalendarWidget`, and `LinkAutocomplete` coverage now runs with deterministic assertions and no stale `it.skip` markers in those suites.                                                                                                                       | `apps/web/src/components/widgets/__tests__/TasksWidget.test.tsx:1`, `apps/web/src/components/widgets/__tests__/CalendarWidget.test.tsx:1`, `apps/web/src/components/knowledge/__tests__/LinkAutocomplete.test.tsx:1`                        |
+| REV-2026-008 | done   | low      | tooling             | Repo session bootstrap reliability issue: `scripts/agent/session-start.sh` fails due stale branch tracking ref, which can silently block required lifecycle checks. Update script to tolerate missing remote branch or self-heal branch config.                                                                                    | `scripts/agent/session-start.sh:10`, `scripts/agent/session-start.sh:16`, `scripts/agent/session-start.sh:34`                                                                                                                               |
+
+---
+
+## 2026-02-17 Orchestrator Streaming + Queue Control Follow-up
+
+**Orchestrator:** Jarvis (Codex runtime)
+**Branch:** `fix/auth-frontend-remediation`
+
+### Tasks
+
+| id          | status | description                                                                                                         | issue | repo             | branch                        | depends_on   | blocks | agent | started_at        | completed_at      | estimate | used |
+| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------- | ----- | ---------------- | ----------------------------- | ------------ | ------ | ----- | ----------------- | ----------------- | -------- | ---- |
+| ORCH-FU-001 | done   | Add orchestrator SSE event stream endpoint and service fan-out (`/agents/events`) with initial snapshot + heartbeat | #411  | orchestrator,web | fix/auth-frontend-remediation | REV-2026-001 |        | orch  | 2026-02-17T15:00Z | 2026-02-17T15:18Z | 20K      | 24K  |
+| ORCH-FU-002 | done   | Add queue control API (`/queue/stats`, `/queue/pause`, `/queue/resume`) and web proxy routes                        | #411  | orchestrator,web | fix/auth-frontend-remediation | ORCH-FU-001  |        | orch  | 2026-02-17T15:18Z | 2026-02-17T15:24Z | 12K      | 15K  |
+| ORCH-FU-003 | done   | Wire `TaskProgressWidget` and `AgentStatusWidget` to live SSE updates with polling fallback                         | #411  | web              | fix/auth-frontend-remediation | ORCH-FU-001  |        | orch  | 2026-02-17T15:24Z | 2026-02-17T15:33Z | 15K      | 18K  |
+| ORCH-FU-004 | done   | Persist spawned state in lifecycle + align queue state transitions/events for spawned/non-spawned paths             | #411  | orchestrator     | fix/auth-frontend-remediation | ORCH-FU-001  |        | orch  | 2026-02-17T15:33Z | 2026-02-17T15:40Z | 15K      | 18K  |
+| ORCH-FU-005 | done   | Harden repo-local Mosaic linkage paths (`~/.config/mosaic`) and ignore orchestrator runtime artifacts               | #411  | docs,tooling     | fix/auth-frontend-remediation | ORCH-FU-004  |        | orch  | 2026-02-17T15:40Z | 2026-02-17T15:45Z | 8K       | 6K   |
+| ORCH-FU-V01 | done   | Verification: orchestrator and web targeted test suites pass after follow-up changes                                | #411  | all              | fix/auth-frontend-remediation | ORCH-FU-001  |        | orch  | 2026-02-17T15:45Z | 2026-02-17T15:48Z | 5K       | 3K   |
+
+### Verification Snapshot
+
+- `pnpm --filter @mosaic/orchestrator test -- src/api/queue/queue.controller.spec.ts src/api/agents/agents.controller.spec.ts src/api/agents/agents-killswitch.controller.spec.ts src/queue/queue.service.spec.ts src/config/orchestrator.config.spec.ts`: pass (`26` files, `737` tests)
+- `pnpm --filter @mosaic/web test -- src/components/widgets/__tests__/TaskProgressWidget.test.tsx src/components/widgets/__tests__/AgentStatusWidget.test.tsx`: pass (`89` files, `1117` tests, `3` skipped)
+
+---
+
+## 2026-02-17 Orchestrator Observability Follow-up
+
+**Orchestrator:** Jarvis (Codex runtime)
+**Branch:** `feature/mosaic-stack-finalization`
+
+### Tasks
+
+| id           | status | description                                                                                         | issue | repo              | branch                            | depends_on   | blocks | agent | started_at        | completed_at      | estimate | used |
+| ------------ | ------ | --------------------------------------------------------------------------------------------------- | ----- | ----------------- | --------------------------------- | ------------ | ------ | ----- | ----------------- | ----------------- | -------- | ---- |
+| ORCH-OBS-001 | done   | Add recent event buffer + endpoint (`GET /agents/events/recent?limit=`) for non-SSE polling clients | #411  | orchestrator      | feature/mosaic-stack-finalization | ORCH-FU-001  |        | orch  | 2026-02-17T16:20Z | 2026-02-17T16:28Z | 10K      | 8K   |
+| ORCH-OBS-002 | done   | Add web proxy route for recent orchestrator events (`/api/orchestrator/events/recent`)              | #411  | web               | feature/mosaic-stack-finalization | ORCH-OBS-001 |        | orch  | 2026-02-17T16:28Z | 2026-02-17T16:31Z | 5K       | 4K   |
+| ORCH-OBS-003 | done   | Add repo-level monitor script (`scripts/agent/orchestrator-events.sh`) for recent/watch modes       | #411  | tooling           | feature/mosaic-stack-finalization | ORCH-OBS-001 |        | orch  | 2026-02-17T16:31Z | 2026-02-17T16:36Z | 8K       | 5K   |
+| ORCH-OBS-004 | done   | Add tests/docs updates for recent events and operator command usage                                 | #411  | orchestrator,docs | feature/mosaic-stack-finalization | ORCH-OBS-001 |        | orch  | 2026-02-17T16:36Z | 2026-02-17T16:40Z | 8K       | 6K   |
+| ORCH-OBS-005 | done   | Fix HUD widget ID generation/parsing for hyphenated widget types (`quick-capture`, `agent-status`)  | #411  | web               | feature/mosaic-stack-finalization | ORCH-OBS-004 |        | orch  | 2026-02-17T16:42Z | 2026-02-17T16:48Z | 8K       | 6K   |
+| ORCH-OBS-006 | done   | Add `WidgetRenderer` regression tests for hyphenated widget IDs                                     | #411  | web               | feature/mosaic-stack-finalization | ORCH-OBS-005 |        | orch  | 2026-02-17T16:48Z | 2026-02-17T16:50Z | 5K       | 3K   |
+| ORCH-OBS-007 | done   | Add `OrchestratorEventsWidget` for live/recent orchestration visibility with Matrix signal hints    | #411  | web               | feature/mosaic-stack-finalization | ORCH-OBS-002 |        | orch  | 2026-02-17T16:55Z | 2026-02-17T17:03Z | 12K      | 9K   |
+| ORCH-OBS-008 | done   | Integrate new widget into HUD/WidgetRegistry and extend widget regression coverage                  | #411  | web               | feature/mosaic-stack-finalization | ORCH-OBS-007 |        | orch  | 2026-02-17T17:03Z | 2026-02-17T17:08Z | 10K      | 7K   |
+| ORCH-OBS-009 | done   | Seed default/reset local HUD layout with orchestration widgets so visibility works out-of-box       | #411  | web               | feature/mosaic-stack-finalization | ORCH-OBS-008 |        | orch  | 2026-02-17T17:10Z | 2026-02-17T17:14Z | 8K       | 6K   |
+| ORCH-OBS-010 | done   | Enrich `TaskProgressWidget` with latest recent-event context from `/api/orchestrator/events/recent` | #411  | web               | feature/mosaic-stack-finalization | ORCH-OBS-009 |        | orch  | 2026-02-17T17:15Z | 2026-02-17T17:20Z | 8K       | 6K   |
+| ORCH-OBS-011 | done   | Add orchestrator health proxy and readiness badge (`ready/degraded`) in events widget               | #411  | web               | feature/mosaic-stack-finalization | ORCH-OBS-010 |        | orch  | 2026-02-17T17:22Z | 2026-02-17T17:27Z | 8K       | 6K   |
+
+## 2026-02-17 Issue 424 — Orchestrator Provider-Aware Startup
+
+**Orchestrator:** Jarvis (Codex runtime)
+**Issue:** #424
+**Branch:** `fix/orchestrator-runtime-provider-config`
+
+### Tasks
+
+| id           | status | description                                                                                           | issue | repo              | branch                                   | depends_on                             | blocks       | agent | started_at | completed_at              | estimate | used |
+| ------------ | ------ | ----------------------------------------------------------------------------------------------------- | ----- | ----------------- | ---------------------------------------- | -------------------------------------- | ------------ | ----- | ---------- | ------------------------- | -------- | ---- |
+| ORCH-424-001 | done   | Remove hard startup dependency on `CLAUDE_API_KEY` unless provider explicitly requires it             | #424  | orchestrator      | fix/orchestrator-runtime-provider-config |                                        | ORCH-424-002 |       |            | 2026-02-17T17:15:18-06:00 | 12K      |      |
+| ORCH-424-002 | done   | Add provider/runtime-aware validation and startup diagnostics for required key availability           | #424  | orchestrator      | fix/orchestrator-runtime-provider-config | ORCH-424-001                           | ORCH-424-003 |       |            | 2026-02-17T17:15:18-06:00 | 10K      |      |
+| ORCH-424-003 | done   | Update env example docs for Codex/OpenCode/Claude multi-provider startup behavior                     | #424  | orchestrator,docs | fix/orchestrator-runtime-provider-config | ORCH-424-002                           | ORCH-424-V01 |       |            | 2026-02-17T17:15:18-06:00 | 8K       |      |
+| ORCH-424-V01 | done   | Verification: `pnpm lint && pnpm typecheck && pnpm test` healthy for non-Claude startup/runtime paths | #424  | all               | fix/orchestrator-runtime-provider-config | ORCH-424-001,ORCH-424-002,ORCH-424-003 |              |       |            | 2026-02-17T17:15:18-06:00 | 5K       |      |
diff --git a/docs/web-ui-implementation.md b/docs/web-ui-implementation.md
index 3adf33a..a325d7a 100644
--- a/docs/web-ui-implementation.md
+++ b/docs/web-ui-implementation.md
@@ -100,7 +100,7 @@ apps/web/src/
 
 - `GET /auth/session` - Get current session
 - `POST /auth/sign-out` - Logout
-- `GET /auth/callback/authentik` - OIDC callback
+- `GET /auth/oauth2/callback/authentik` - OIDC callback
 
 ### Future Endpoints (Mock Data Ready)
 
diff --git a/package.json b/package.json
index e34e135..04bc29f 100644
--- a/package.json
+++ b/package.json
@@ -68,7 +68,9 @@
       "form-data": ">=2.5.4",
       "lodash": ">=4.17.23",
       "lodash-es": ">=4.17.23",
-      "qs": ">=6.14.1",
+      "request": "npm:@cypress/request@3.0.10",
+      "qs": ">=6.15.0",
+      "tough-cookie": ">=4.1.3",
       "undici": ">=6.23.0"
     }
   }
diff --git a/packages/config/package.json b/packages/config/package.json
index 98de936..8338697 100644
--- a/packages/config/package.json
+++ b/packages/config/package.json
@@ -13,7 +13,7 @@
     "./eslint/nestjs": "./eslint/nestjs.js",
     "./prettier": "./prettier/index.js"
   },
-  "dependencies": {
+  "devDependencies": {
     "@eslint/js": "^9.21.0",
     "@typescript-eslint/eslint-plugin": "^8.26.0",
     "@typescript-eslint/parser": "^8.26.0",
@@ -22,9 +22,7 @@
     "eslint-plugin-prettier": "^5.2.3",
     "eslint-plugin-security": "^3.0.1",
     "prettier": "^3.5.3",
+    "typescript": "^5.8.2",
     "typescript-eslint": "^8.26.0"
-  },
-  "devDependencies": {
-    "typescript": "^5.8.2"
   }
 }
diff --git a/plans/mosaic-installer-plan.md b/plans/mosaic-installer-plan.md
new file mode 100644
index 0000000..3595691
--- /dev/null
+++ b/plans/mosaic-installer-plan.md
@@ -0,0 +1,657 @@
+# Mosaic Stack Comprehensive Installer Plan
+
+## Executive Summary
+
+This document outlines the plan for creating a comprehensive installation script for Mosaic Stack that "just works" across platforms, automatically installs all dependencies, detects the platform, and configures the system. The design is inspired by the OpenClaw installer pattern while addressing Mosaic Stack's unique requirements as a multi-tenant personal assistant platform with optional Docker deployment.
+
+---
+
+## 1. Current State Analysis
+
+### 1.1 Existing Setup Script ([`scripts/setup.sh`](scripts/setup.sh))
+
+**Strengths:**
+
+- Interactive configuration wizard
+- Platform detection (Debian, Arch, Fedora, macOS)
+- Docker and native deployment modes
+- Port conflict detection and resolution
+- .env file management with value preservation
+- Secret generation
+- SSO/Authentik configuration
+- Ollama integration options
+- Traefik reverse proxy support
+
+**Gaps:**
+
+- No curl-able one-liner installation
+- Missing automatic dependency installation for some platforms
+- No WSL detection/handling
+- No dry-run validation of full configuration
+- Limited post-install validation
+- No upgrade/migration path handling
+- Missing verbose/debug mode
+- No cleanup on failure
+- PATH management not comprehensive
+
+### 1.2 OpenClaw Installer Features to Adopt
+
+| Feature                  | Description                                              | Priority |
+| ------------------------ | -------------------------------------------------------- | -------- |
+| curl-able one-liner      | `curl -fsSL URL \| bash` pattern                         | High     |
+| Color output             | Consistent colored output with ACCENT/SUCCESS/WARN/ERROR | High     |
+| Platform detection       | macOS, Linux, WSL detection                              | High     |
+| Auto Homebrew            | Automatic Homebrew installation on macOS                 | Medium   |
+| Node.js management       | NodeSource integration for Linux, Homebrew for macOS     | High     |
+| npm permissions fix      | User-local npm global installs on Linux                  | Medium   |
+| pnpm via corepack        | Corepack-first pnpm installation                         | High     |
+| Git installation         | Automatic Git installation                               | Medium   |
+| Multiple install methods | npm vs git checkout options                              | Low      |
+| Dry-run mode             | Preview changes without execution                        | High     |
+| Verbose mode             | Debug output with `set -x`                               | Medium   |
+| Non-interactive mode     | CI/CD friendly automation                                | High     |
+| TTY detection            | Graceful handling of piped input                         | High     |
+| Temp file cleanup        | Trap-based cleanup on exit                               | High     |
+| Downloader detection     | curl/wget abstraction                                    | Medium   |
+| PATH warnings            | Alert user about PATH issues                             | Medium   |
+| Post-install doctor      | Validation and migration                                 | High     |
+| Fun taglines             | User-friendly messaging                                  | Low      |
+
+---
+
+## 2. Proposed Architecture
+
+### 2.1 File Structure
+
+```
+scripts/
+├── install.sh              # Main entry point (curl-able)
+├── setup.sh                # Interactive configuration wizard (enhanced)
+├── lib/
+│   ├── common.sh           # Shared utilities (enhanced)
+│   ├── platform.sh         # Platform detection functions
+│   ├── dependencies.sh     # Dependency installation functions
+│   ├── docker.sh           # Docker-specific functions
+│   ├── native.sh           # Native deployment functions
+│   └── validation.sh       # Post-install validation
+└── commands/
+    ├── doctor.sh           # Diagnostic and repair tool
+    └── upgrade.sh          # Upgrade/migration handler
+```
+
+### 2.2 Installer Flow Diagram
+
+```mermaid
+flowchart TD
+    A[curl/install.sh] --> B{Parse Arguments}
+    B --> C{Help?}
+    C -->|Yes| D[Show Usage]
+    C -->|No| E{Dry Run?}
+
+    E --> F[Detect Platform]
+    F --> G[Detect Package Manager]
+
+    G --> H{Install Method}
+    H -->|docker| I[Check Docker]
+    H -->|native| J[Check Node.js/pnpm]
+
+    I --> K{Docker OK?}
+    K -->|No| L[Install Docker]
+    K -->|Yes| M[Check Docker Compose]
+    L --> M
+
+    J --> N{Node.js OK?}
+    N -->|No| O[Install Node.js]
+    N -->|Yes| P{pnpm OK?}
+    O --> P
+    P -->|No| Q[Install pnpm]
+    P -->|Yes| R[Check PostgreSQL]
+    Q --> R
+
+    M --> S[Check Existing Config]
+    R --> S
+
+    S --> T{Has .env?}
+    T -->|Yes| U[Load Existing Values]
+    T -->|No| V[Interactive Config]
+    U --> V
+
+    V --> W[Generate Secrets]
+    W --> X[Resolve Port Conflicts]
+    X --> Y[Write .env]
+
+    Y --> Z{Deployment Mode}
+    Z -->|docker| AA[Docker Compose Up]
+    Z -->|native| AB[Run Migrations]
+
+    AA --> AC[Run Doctor]
+    AB --> AC
+
+    AC --> AD{All Checks Pass?}
+    AD -->|Yes| AE[Show Success]
+    AD -->|No| AF[Show Warnings]
+
+    AE --> AG[Print Next Steps]
+    AF --> AG
+```
+
+---
+
+## 3. Detailed Component Design
+
+### 3.1 Entry Point: `install.sh`
+
+The main installer should support both quick-start and advanced usage:
+
+```bash
+# Usage patterns:
+# Quick start (interactive):
+curl -fsSL https://get.mosaicstack.dev | bash
+
+# Non-interactive Docker deployment:
+curl -fsSL https://get.mosaicstack.dev | bash -s -- --non-interactive --mode docker
+
+# Dry run to preview:
+curl -fsSL https://get.mosaicstack.dev | bash -s -- --dry-run --mode docker
+
+# With all options:
+curl -fsSL https://get.mosaicstack.dev | bash -s -- \
+  --mode docker \
+  --enable-sso \
+  --bundled-authentik \
+  --ollama-mode local \
+  --base-url https://mosaic.example.com
+```
+
+**Command-line Options:**
+
+| Option                     | Description                     | Default               |
+| -------------------------- | ------------------------------- | --------------------- |
+| `--mode`                   | Deployment mode: docker, native | interactive           |
+| `--non-interactive`        | Skip all prompts                | false                 |
+| `--dry-run`                | Preview without changes         | false                 |
+| `--verbose`                | Enable debug output             | false                 |
+| `--enable-sso`             | Enable Authentik SSO            | false                 |
+| `--bundled-authentik`      | Use bundled Authentik           | false                 |
+| `--external-authentik URL` | External Authentik URL          | -                     |
+| `--ollama-mode`            | Ollama: local, remote, disabled | disabled              |
+| `--ollama-url URL`         | Remote Ollama URL               | -                     |
+| `--base-url URL`           | Mosaic base URL                 | http://localhost:3000 |
+| `--profiles`               | Compose profiles to enable      | full                  |
+| `--no-port-check`          | Skip port conflict detection    | false                 |
+| `--skip-deps`              | Skip dependency installation    | false                 |
+| `--help`                   | Show usage                      | -                     |
+
+### 3.2 Platform Detection: `lib/platform.sh`
+
+```bash
+# Functions to implement:
+
+detect_os()           # Returns: macos, debian, arch, fedora, linux, unknown
+detect_package_manager()  # Returns: brew, apt, pacman, dnf, unknown
+detect_wsl()          # Returns: WSL_DISTRO_NAME or empty
+detect_init_system()  # Returns: systemd, openrc, launchd, unknown
+get_os_name()         # Human-readable OS name
+get_arch()            # Returns: x86_64, aarch64, armv7l
+is_root()             # Check if running as root
+maybe_sudo()          # Run with sudo only if needed
+```
+
+**Platform Support Matrix:**
+
+| Platform      | Package Manager  | Init System | Node.js Source   |
+| ------------- | ---------------- | ----------- | ---------------- |
+| macOS         | Homebrew         | launchd     | Homebrew         |
+| Ubuntu/Debian | apt              | systemd     | NodeSource       |
+| Arch/Manjaro  | pacman           | systemd     | pacman           |
+| Fedora/RHEL   | dnf              | systemd     | NodeSource       |
+| WSL           | (host-dependent) | systemd\*   | (host-dependent) |
+
+### 3.3 Dependency Management: `lib/dependencies.sh`
+
+**Dependencies by Mode:**
+
+**Docker Mode:**
+
+- Docker Engine 24+
+- Docker Compose (plugin or standalone)
+- Git (for cloning if needed)
+
+**Native Mode:**
+
+- Node.js 22+
+- pnpm 10+
+- PostgreSQL 17+ (with pgvector)
+- Valkey/Redis (optional)
+- Git
+
+**Optional Dependencies:**
+
+- Ollama (for local LLM)
+- OpenSSL (for secret generation)
+
+**Installation Strategy:**
+
+```bash
+# macOS
+install_homebrew()      # Auto-install Homebrew if missing
+install_docker_macos()  # via Homebrew
+install_node_macos()    # via Homebrew
+install_pnpm()          # via corepack or npm
+
+# Debian/Ubuntu
+install_docker_debian() # via docker.com apt repo
+install_node_debian()   # via NodeSource
+install_postgres_debian() # via apt with pgvector
+
+# Arch Linux
+install_docker_arch()   # via pacman
+install_node_arch()     # via pacman
+install_postgres_arch() # via pacman with pgvector
+
+# Fedora/RHEL
+install_docker_fedora() # via dnf
+install_node_fedora()   # via NodeSource
+install_postgres_fedora() # via dnf
+```
+
+### 3.4 Docker Functions: `lib/docker.sh`
+
+```bash
+check_docker()           # Verify Docker is installed and accessible
+check_docker_compose()   # Verify Docker Compose is available
+check_docker_buildx()    # Verify buildx is available
+fix_docker_permissions() # Add user to docker group
+start_docker()           # Start Docker daemon if not running
+docker_pull_images()     # Pre-pull all required images
+docker_compose_up()      # Start services with health checks
+docker_compose_down()    # Stop services
+docker_logs()            # Tail logs for debugging
+```
+
+### 3.5 Configuration Generation
+
+**Environment File Structure:**
+
+The installer should generate a complete `.env` file based on:
+
+1. **Existing values** (if `.env` exists)
+2. **Command-line arguments**
+3. **Interactive prompts** (if TTY available)
+4. **Auto-detected defaults**
+
+**Secret Generation:**
+
+| Secret                       | Length | Method               |
+| ---------------------------- | ------ | -------------------- |
+| POSTGRES_PASSWORD            | 32     | openssl rand -base64 |
+| JWT_SECRET                   | 32     | openssl rand -base64 |
+| BETTER_AUTH_SECRET           | 32     | openssl rand -base64 |
+| ENCRYPTION_KEY               | 32     | openssl rand -hex 32 |
+| AUTHENTIK_SECRET_KEY         | 50     | openssl rand -base64 |
+| AUTHENTIK_BOOTSTRAP_PASSWORD | 16     | openssl rand -base64 |
+| COORDINATOR_API_KEY          | 32     | openssl rand -base64 |
+| ORCHESTRATOR_API_KEY         | 32     | openssl rand -base64 |
+| GITEA_WEBHOOK_SECRET         | 32     | openssl rand -hex 32 |
+
+**URL Derivation:**
+
+```bash
+# Localhost mode
+MOSAIC_BASE_URL=http://localhost:${WEB_PORT}
+NEXT_PUBLIC_API_URL=http://localhost:${API_PORT}
+
+# Domain mode (with Traefik)
+MOSAIC_BASE_URL=https://${MOSAIC_WEB_DOMAIN}
+NEXT_PUBLIC_API_URL=https://${MOSAIC_API_DOMAIN}
+
+# IP mode (local network)
+MOSAIC_BASE_URL=http://${LOCAL_IP}:${WEB_PORT}
+NEXT_PUBLIC_API_URL=http://${LOCAL_IP}:${API_PORT}
+```
+
+### 3.6 Port Conflict Resolution
+
+```bash
+# Default ports
+declare -A DEFAULT_PORTS=(
+    [WEB_PORT]=3000
+    [API_PORT]=3001
+    [POSTGRES_PORT]=5432
+    [VALKEY_PORT]=6379
+    [AUTHENTIK_PORT_HTTP]=9000
+    [AUTHENTIK_PORT_HTTPS]=9443
+    [OLLAMA_PORT]=11434
+    [TRAEFIK_HTTP_PORT]=80
+    [TRAEFIK_HTTPS_PORT]=443
+    [TRAEFIK_DASHBOARD_PORT]=8080
+)
+
+# Check if port is in use
+check_port_in_use() {
+    local port=$1
+    # Try ss first, fall back to netstat, then lsof
+}
+
+# Suggest alternative port
+suggest_alternative_port() {
+    local base_port=$1
+    # Try base_port+1, base_port+100, etc.
+}
+```
+
+### 3.7 Post-Install Validation: `lib/validation.sh`
+
+**Doctor Checks:**
+
+```bash
+# Docker mode checks
+doctor_docker_running()      # Docker daemon is running
+doctor_containers_healthy()  # All containers are healthy
+doctor_database_connected()  # PostgreSQL is accessible
+doctor_cache_connected()     # Valkey is accessible
+doctor_api_responding()      # API health check passes
+doctor_web_responding()      # Web frontend is accessible
+
+# Native mode checks
+doctor_node_version()        # Node.js version is sufficient
+doctor_pnpm_version()        # pnpm is installed
+doctor_postgres_running()    # PostgreSQL is running
+doctor_migrations_applied()  # Database migrations are up to date
+doctor_dependencies_installed()  # node_modules is complete
+
+# General checks
+doctor_env_complete()        # All required env vars are set
+doctor_secrets_valid()       # Secrets are not placeholders
+doctor_ports_available()     # Configured ports are available
+doctor_disk_space()          # Sufficient disk space
+```
+
+### 3.8 Doctor Command: `scripts/commands/doctor.sh`
+
+A standalone diagnostic tool that can be run after installation:
+
+```bash
+# Usage
+./scripts/commands/doctor.sh              # Run all checks
+./scripts/commands/doctor.sh --fix        # Attempt automatic fixes
+./scripts/commands/doctor.sh --verbose    # Detailed output
+./scripts/commands/doctor.sh --json       # JSON output for CI
+
+# Exit codes
+# 0: All checks passed
+# 1: Some checks failed
+# 2: Critical failure
+```
+
+---
+
+## 4. User Experience Design
+
+### 4.1 Banner and Branding
+
+```
+  __  __                 _       ____ _             _
+ |  \/  | ___  ___  __ _(_) ___ / ___| |_ __ _  ___| | __
+ | |\/| |/ _ \/ __|/ _` | |/ __|\___ | __/ _` |/ __| |/ /
+ | |  | | (_) \__ \ (_| | | (__ ___/ | || (_| | (__|   <
+ |_|  |_|\___/|___/\__,_|_|\___|____/ \__\__,_|\___|_|\_\
+
+  Multi-Tenant Personal Assistant Platform
+
+  Claws out, configs in — let's ship a calm, clean stack.
+```
+
+### 4.2 Progress Indicators
+
+```
+✓ Detected: macOS (brew)
+✓ Docker: OK (version 27.0.0)
+✓ Docker Compose: OK (version 2.28.0)
+✓ Node.js: OK (v22.5.0)
+⚠ Port 3000 is in use, using 3001
+→ Generating secrets...
+→ Writing .env file...
+→ Starting services...
+✓ All services healthy
+```
+
+### 4.3 Error Messages
+
+```
+✗ Docker is not running
+  Start with: open -a Docker (macOS)
+  Start with: sudo systemctl start docker (Linux)
+
+✗ Port conflicts detected:
+  - Web UI (3000): In use by process 12345 (node)
+  - API (3001): In use by process 12346 (python)
+  Run with --auto-ports to use alternative ports
+```
+
+### 4.4 Success Message
+
+```
+════════════════════════════════════════════════════════════
+  Mosaic Stack is ready!
+════════════════════════════════════════════════════════════
+
+  Web UI:     http://localhost:3000
+  API:        http://localhost:3001
+  Database:   localhost:5432
+
+  Next steps:
+    1. Open http://localhost:3000 in your browser
+    2. Create your first workspace
+    3. Configure AI providers in Settings
+
+  To stop:    docker compose down
+  To restart: docker compose restart
+  To view logs: docker compose logs -f
+
+  Documentation: https://docs.mosaicstack.dev
+  Support:       https://github.com/mosaicstack/stack/issues
+```
+
+---
+
+## 5. Implementation Phases
+
+### Phase 1: Core Infrastructure
+
+- [ ] Create `install.sh` entry point with argument parsing
+- [ ] Implement platform detection in `lib/platform.sh`
+- [ ] Create dependency checking functions
+- [ ] Add temp file cleanup and error handling
+- [ ] Implement colored output system
+
+### Phase 2: Dependency Installation
+
+- [ ] Implement Homebrew auto-installation for macOS
+- [ ] Implement Docker installation for all platforms
+- [ ] Implement Node.js installation via NodeSource (Debian/Fedora)
+- [ ] Implement pnpm installation via corepack
+- [ ] Implement PostgreSQL installation with pgvector
+
+### Phase 3: Configuration
+
+- [ ] Enhance .env file generation
+- [ ] Implement secret generation with proper entropy
+- [ ] Add URL derivation logic for all access modes
+- [ ] Implement port conflict detection and resolution
+- [ ] Add configuration validation
+
+### Phase 4: Service Management
+
+- [ ] Implement Docker Compose service orchestration
+- [ ] Add health check polling
+- [ ] Implement database migration running
+- [ ] Add service status reporting
+
+### Phase 5: Validation and Doctor
+
+- [ ] Create `scripts/commands/doctor.sh`
+- [ ] Implement all diagnostic checks
+- [ ] Add automatic fix capabilities
+- [ ] Create JSON output mode for CI
+
+### Phase 6: Polish and Testing
+
+- [ ] Add comprehensive logging
+- [ ] Test on all supported platforms
+- [ ] Test upgrade scenarios
+- [ ] Write documentation
+- [ ] Create CI/CD integration examples
+
+---
+
+## 6. Testing Strategy
+
+### 6.1 Platform Testing Matrix
+
+| Platform | Version       | Docker | Native | CI             |
+| -------- | ------------- | ------ | ------ | -------------- |
+| macOS    | 14 (Sonoma)   | ✓      | ✓      | Manual         |
+| macOS    | 13 (Ventura)  | ✓      | ✓      | Manual         |
+| Ubuntu   | 24.04 LTS     | ✓      | ✓      | GitHub Actions |
+| Ubuntu   | 22.04 LTS     | ✓      | ✓      | GitHub Actions |
+| Debian   | 12 (Bookworm) | ✓      | ✓      | GitHub Actions |
+| Arch     | Rolling       | ✓      | ✓      | Manual         |
+| Fedora   | 40            | ✓      | ✓      | Manual         |
+| WSL2     | Ubuntu        | ✓      | ✓      | Manual         |
+
+### 6.2 Test Scenarios
+
+1. **Fresh Installation**
+   - No dependencies installed
+   - Clean system
+
+2. **Partial Dependencies**
+   - Some dependencies already installed
+   - Different versions
+
+3. **Upgrade Scenario**
+   - Existing .env file
+   - Running containers
+
+4. **Port Conflicts**
+   - Common ports in use
+   - All ports in use
+
+5. **Error Recovery**
+   - Network failures
+   - Permission issues
+   - Disk space issues
+
+---
+
+## 7. Security Considerations
+
+### 7.1 Secret Handling
+
+- Never log secrets to console or file
+- Generate secrets with cryptographically secure random
+- Validate secrets are not placeholders before starting
+- Warn if default/weak secrets are detected
+
+### 7.2 Network Security
+
+- Download scripts over HTTPS only
+- Verify TLS certificates
+- Use specific version tags for Docker images
+- Pin NodeSource repository version
+
+### 7.3 File Permissions
+
+- Set restrictive permissions on .env (600)
+- Ensure secrets are not world-readable
+- Validate file ownership
+
+---
+
+## 8. Documentation Requirements
+
+### 8.1 README Updates
+
+- Add installation section with curl command
+- Document all command-line options
+- Add troubleshooting section
+- Include platform-specific notes
+
+### 8.2 Inline Documentation
+
+- Comment all functions with usage examples
+- Document expected return values
+- Include error codes
+
+### 8.3 User Guide
+
+- Step-by-step installation guide
+- Configuration options explained
+- Common issues and solutions
+- Upgrade procedures
+
+---
+
+## 9. Open Questions
+
+1. **Should we support Windows native installation?**
+   - Current recommendation: WSL2 only
+   - PowerShell version could be a future addition
+
+2. **Should we support ARM platforms (Raspberry Pi)?**
+   - Docker images would need ARM builds
+   - Could be community-supported
+
+3. **What is the upgrade strategy?**
+   - In-place upgrade vs. migrate data
+   - Database migration handling
+   - Configuration file changes
+
+4. **Should we provide an uninstaller?**
+   - Clean up Docker volumes
+   - Remove configuration files
+   - Uninstall dependencies (optional)
+
+---
+
+## 10. Success Criteria
+
+The installer is considered successful when:
+
+1. ✅ A user can run `curl -fsSL https://get.mosaicstack.dev | bash` and have a working installation
+2. ✅ All dependencies are automatically installed on supported platforms
+3. ✅ Port conflicts are automatically detected and resolved
+4. ✅ Secrets are automatically generated with proper entropy
+5. ✅ The installation completes in under 5 minutes on a fresh system
+6. ✅ Post-install validation confirms all services are healthy
+7. ✅ Clear next steps are provided to the user
+8. ✅ Non-interactive mode works for CI/CD pipelines
+9. ✅ The doctor command can diagnose and fix common issues
+10. ✅ Upgrade from previous versions preserves data and configuration
+
+---
+
+## Appendix A: Environment Variables Reference
+
+See [`.env.example`](.env.example) for the complete list of configuration options.
+
+## Appendix B: Docker Compose Profiles
+
+| Profile           | Services     | Use Case            |
+| ----------------- | ------------ | ------------------- |
+| `full`            | All services | Development/Trial   |
+| `database`        | PostgreSQL   | External cache/auth |
+| `cache`           | Valkey       | External database   |
+| `authentik`       | Authentik    | SSO enabled         |
+| `ollama`          | Ollama       | Local LLM           |
+| `traefik-bundled` | Traefik      | Reverse proxy       |
+| `openbao`         | OpenBao      | Secrets management  |
+
+## Appendix C: Related Files
+
+- Current setup script: [`scripts/setup.sh`](scripts/setup.sh)
+- Common utilities: [`scripts/lib/common.sh`](scripts/lib/common.sh)
+- Docker Compose: [`docker-compose.yml`](docker-compose.yml)
+- Environment example: [`.env.example`](.env.example)
+- OpenClaw installer reference: [`examples/openclaw/install.sh`](examples/openclaw/install.sh)
diff --git a/plans/prisma-middleware-migration-plan.md b/plans/prisma-middleware-migration-plan.md
new file mode 100644
index 0000000..8c947b4
--- /dev/null
+++ b/plans/prisma-middleware-migration-plan.md
@@ -0,0 +1,238 @@
+# Prisma Middleware Migration Plan: $use to $extends
+
+## Problem Summary
+
+The application fails to start with the following error:
+
+```
+TypeError: prisma.$use is not a function
+    at registerAccountEncryptionMiddleware (/app/apps/api/dist/prisma/account-encryption.middleware.js:45:12)
+```
+
+### Root Cause
+
+The project uses **Prisma 6.19.2**, which removed the deprecated `$use()` middleware API. The `$use()` method was deprecated in Prisma4.16.0 and removed in Prisma5.0.0. The replacement is **Prisma Client Extensions** using the `$extends()` API.
+
+### Affected Files
+
+| File                                                                                                 | Purpose                                                  |
+| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| [`account-encryption.middleware.ts`](apps/api/src/prisma/account-encryption.middleware.ts)           | Encrypts/decrypts OAuth tokens in Account table          |
+| [`llm-encryption.middleware.ts`](apps/api/src/prisma/llm-encryption.middleware.ts)                   | Encrypts/decrypts API keys in LlmProviderInstance.config |
+| [`prisma.service.ts`](apps/api/src/prisma/prisma.service.ts)                                         | Registers both middleware functions                      |
+| [`account-encryption.middleware.spec.ts`](apps/api/src/prisma/account-encryption.middleware.spec.ts) | Unit tests for account encryption                        |
+| [`llm-encryption.middleware.spec.ts`](apps/api/src/prisma/llm-encryption.middleware.spec.ts)         | Unit tests for LLM encryption                            |
+| [`prisma.service.spec.ts`](apps/api/src/prisma/prisma.service.spec.ts)                               | Unit tests for PrismaService                             |
+
+---
+
+## Migration Strategy
+
+### Current Architecture (Broken)
+
+```mermaid
+flowchart TD
+    A[PrismaService.onModuleInit] --> B[$connect to database]
+    B --> C[registerAccountEncryptionMiddleware]
+    B --> D[registerLlmEncryptionMiddleware]
+    C --> E[prisma.$use - REMOVED IN PRISMA5]
+    D --> F[prisma.$use - REMOVED IN PRISMA5]
+    E --> G[ERROR: $use is not a function]
+    F --> G
+```
+
+### Target Architecture (Client Extensions)
+
+```mermaid
+flowchart TD
+    A[PrismaService] --> B[Create Extended Client]
+    B --> C[prisma.$extends with Account query override]
+    B --> D[prisma.$extends with LlmProviderInstance query override]
+    C --> E[Extended Client with transparent encryption]
+    D --> E
+    E --> F[All queries use extended client automatically]
+```
+
+---
+
+## Implementation Tasks
+
+### Phase 1: Create Extension Functions
+
+#### Task 1.1: Create Account Encryption Extension
+
+Replace [`account-encryption.middleware.ts`](apps/api/src/prisma/account-encryption.middleware.ts) with a Client Extension:
+
+**Key changes:**
+
+- Remove `registerAccountEncryptionMiddleware` function
+- Create `createAccountEncryptionExtension` function that returns a Prisma extension
+- Use `prisma.$extends({ query: { account: { ... } } })` pattern
+- Override `$allOperations` or specific operations: `create`, `update`, `upsert`, `findUnique`, `findFirst`, `findMany`
+
+**Extension structure:**
+
+```typescript
+export function createAccountEncryptionExtension(prisma: PrismaClient, vaultService: VaultService) {
+  return prisma.$extends({
+    query: {
+      account: {
+        async $allOperations({ model, operation, args, query }) {
+          // Pre-operation: encrypt on writes
+          // Execute: call original query
+          // Post-operation: decrypt on reads
+        },
+      },
+    },
+  });
+}
+```
+
+#### Task 1.2: Create LLM Encryption Extension
+
+Replace [`llm-encryption.middleware.ts`](apps/api/src/prisma/llm-encryption.middleware.ts) with similar Client Extension pattern for `LlmProviderInstance` model.
+
+### Phase 2: Update PrismaService
+
+#### Task 2.1: Modify PrismaService to Use Extensions
+
+Update [`prisma.service.ts`](apps/api/src/prisma/prisma.service.ts:28-45):
+
+**Current code:**
+
+```typescript
+async onModuleInit() {
+  await this.$connect();
+  registerAccountEncryptionMiddleware(this, this.vaultService);
+  registerLlmEncryptionMiddleware(this, this.vaultService);
+}
+```
+
+**New approach:**
+
+- Create extended client in constructor or onModuleInit
+- Store extended client as property
+- Export extended client for use throughout application
+
+**Challenge:** PrismaService extends PrismaClient. We need to decide:
+
+- Option A: Return extended client from a getter method
+- Option B: Create a wrapper that delegates to extended client
+- Option C: Use composition instead of inheritance
+
+**Recommended: Option A with factory pattern**
+
+```typescript
+@Injectable()
+export class PrismaService {
+  private readonly baseClient: PrismaClient;
+  private readonly extendedClient: ExtendedPrismaClient;
+
+  constructor(vaultService: VaultService) {
+    this.baseClient = new PrismaClient({...});
+    this.extendedClient = createExtendedClient(this.baseClient, vaultService);
+  }
+
+  // Delegate all PrismaClient methods to extended client
+  get $queryRaw() { return this.extendedClient.$queryRaw; }
+  // ... other delegates
+}
+```
+
+### Phase 3: Update Unit Tests
+
+#### Task 3.1: Update account-encryption.middleware.spec.ts
+
+- Change mock from `$use` to `$extends`
+- Update test structure to work with extension pattern
+- Test that extension correctly intercepts queries
+
+#### Task 3.2: Update llm-encryption.middleware.spec.ts
+
+Same updates as Task 3.1 for LLM encryption.
+
+#### Task 3.3: Update prisma.service.spec.ts
+
+- Remove `$use` mock
+- Update to test extension registration
+
+### Phase 4: Integration Testing
+
+#### Task 4.1: Verify Encryption/Decryption Works
+
+- Run existing integration tests
+- Verify OAuth tokens are encrypted at rest
+- Verify LLM API keys are encrypted at rest
+- Verify transparent decryption on read
+
+#### Task 4.2: Test Backward Compatibility
+
+- Verify existing encrypted data can be decrypted
+- Verify plaintext data is encrypted on next write
+
+---
+
+## Detailed Implementation Checklist
+
+### Files to Modify
+
+- [ ] `apps/api/src/prisma/account-encryption.middleware.ts`
+  - Rename to `account-encryption.extension.ts` or keep name
+  - Replace `$use` with `$extends` pattern
+- [ ] `apps/api/src/prisma/llm-encryption.middleware.ts`
+  - Rename to `llm-encryption.extension.ts` or keep name
+  - Replace `$use` with `$extends` pattern
+
+- [ ] `apps/api/src/prisma/prisma.service.ts`
+  - Refactor to use extended client
+  - Maintain backward compatibility for existing code
+
+- [ ] `apps/api/src/prisma/account-encryption.middleware.spec.ts`
+  - Update mocks and test structure
+
+- [ ] `apps/api/src/prisma/llm-encryption.middleware.spec.ts`
+  - Update mocks and test structure
+
+- [ ] `apps/api/src/prisma/prisma.service.spec.ts`
+  - Update mocks and test structure
+
+- [ ] `apps/api/src/prisma/index.ts` (if exists)
+  - Update exports if file names change
+
+---
+
+## Risk Assessment
+
+| Risk                      | Impact   | Mitigation                                |
+| ------------------------- | -------- | ----------------------------------------- |
+| Breaking existing queries | High     | Comprehensive test coverage before/after  |
+| Type safety issues        | Medium   | Use Prisma generated types with extension |
+| Performance regression    | Low      | Extension overhead is minimal             |
+| Data corruption           | Critical | Test with real encryption/decryption      |
+
+---
+
+## References
+
+- [Prisma Client Extensions Documentation](https://www.prisma.io/docs/concepts/components/prisma-client/client-extensions)
+- [Migration Guide: Middleware to Extensions](https://www.prisma.io/docs/concepts/components/prisma-client/middleware)
+- Original TODO comments in code pointing to this migration
+
+---
+
+## Execution Order
+
+1. **Code Mode**: Implement extension functions (Phase 1)
+2. **Code Mode**: Update PrismaService (Phase 2)
+3. **Code Mode**: Update unit tests (Phase 3)
+4. **Debug Mode**: Integration testing and verification (Phase 4)
+
+---
+
+## User Decisions
+
+- **File naming**: Rename middleware files to `.extension.ts` for clarity
+  - `account-encryption.middleware.ts` → `account-encryption.extension.ts`
+  - `llm-encryption.middleware.ts` → `llm-encryption.extension.ts`
+  - `account-encryption.middleware.spec.ts` → `account-encryption.extension.spec.ts`
+  - `llm-encryption.middleware.spec.ts` → `llm-encryption.extension.spec.ts`
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f7d9192..ff4d621 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -11,7 +11,9 @@ overrides:
   form-data: '>=2.5.4'
   lodash: '>=4.17.23'
   lodash-es: '>=4.17.23'
-  qs: '>=6.14.1'
+  request: npm:@cypress/request@3.0.10
+  qs: '>=6.15.0'
+  tough-cookie: '>=4.1.3'
   undici: '>=6.23.0'
 
 importers:
@@ -479,7 +481,7 @@ importers:
   packages/cli-tools: {}
 
   packages/config:
-    dependencies:
+    devDependencies:
       '@eslint/js':
         specifier: ^9.21.0
         version: 9.39.2
@@ -504,13 +506,12 @@ importers:
       prettier:
         specifier: ^3.5.3
         version: 3.8.1
-      typescript-eslint:
-        specifier: ^8.26.0
-        version: 8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
-    devDependencies:
       typescript:
         specifier: ^5.8.2
         version: 5.9.3
+      typescript-eslint:
+        specifier: ^8.26.0
+        version: 8.54.0(eslint@9.39.2(jiti@2.6.1))(typescript@5.9.3)
 
   packages/shared:
     devDependencies:
@@ -893,6 +894,10 @@ packages:
     resolution: {integrity: sha512-Vd/9EVDiu6PPJt9yAh6roZP6El1xHrdvIVGjyBsHR0RYwNHgL7FJPyIIW4fANJNG6FtyZfvlRPpFI4ZM/lubvw==}
     engines: {node: '>=18'}
 
+  '@cypress/request@3.0.10':
+    resolution: {integrity: sha512-hauBrOdvu08vOsagkZ/Aju5XuiZx6ldsLfByg1htFeldhex+PeMrYauANzFsMJeAA0+dyPLbDoX2OYuvVoLDkQ==}
+    engines: {node: '>= 6'}
+
   '@discordjs/builders@1.13.1':
     resolution: {integrity: sha512-cOU0UDHc3lp/5nKByDxkmRiNZBpdp0kx55aarbiAfakfKJHlxv/yFW1zmIqCAmwH5CRlrH9iMFKJMpvW4DPB+w==}
     engines: {node: '>=16.11.0'}
@@ -3310,6 +3315,9 @@ packages:
   ajv@8.17.1:
     resolution: {integrity: sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==}
 
+  ajv@8.18.0:
+    resolution: {integrity: sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==}
+
   another-json@0.2.0:
     resolution: {integrity: sha512-/Ndrl68UQLhnCdsAzEXLMFuOR546o2qbYRqCglaNHbjXrwG1ayTcdwr3zkSGOGtGXDyR5X9nCFfnyG2AFJIsqg==}
 
@@ -4767,15 +4775,6 @@ packages:
   hachure-fill@0.5.2:
     resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==}
 
-  har-schema@2.0.0:
-    resolution: {integrity: sha512-Oqluz6zhGX8cyRaTQlFMPw80bSJVG2x/cFb8ZPhUILGgHka9SsokCCOQgpveePerqidZOrT14ipqfJb7ILcW5Q==}
-    engines: {node: '>=4'}
-
-  har-validator@5.1.5:
-    resolution: {integrity: sha512-nmT2T0lljbxdQZfspsno9hgrG3Uir6Ks5afism62poxqBM6sDnMEuPmzTq8XN0OEwqKLLdh1jQI3qyE66Nzb3w==}
-    engines: {node: '>=6'}
-    deprecated: this library is no longer supported
-
   has-flag@4.0.0:
     resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
     engines: {node: '>=8'}
@@ -4824,9 +4823,9 @@ packages:
     resolution: {integrity: sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==}
     engines: {node: '>= 14'}
 
-  http-signature@1.2.0:
-    resolution: {integrity: sha512-CAbnr6Rz4CYQkLYUtSNXxQPUH2gK8f3iWexVlsnMeD+GjlsQ0Xsy1cOX+mN3dtxYomRy21CiOzU8Uhw6OwncEQ==}
-    engines: {node: '>=0.8', npm: '>=1.3.7'}
+  http-signature@1.4.0:
+    resolution: {integrity: sha512-G5akfn7eKbpDN+8nPS/cb57YeA1jLTVxjpCj7tmm3QKPdyDy7T+qSC40e9ptydSWvkwjSXw1VbkpyEm39ukeAg==}
+    engines: {node: '>=0.10'}
 
   https-proxy-agent@7.0.6:
     resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
@@ -5088,9 +5087,9 @@ packages:
   jsonfile@6.2.0:
     resolution: {integrity: sha512-FGuPw30AdOIUTRMC2OMRtQV+jkVj2cfPqSeWXv1NEAJ1qZ5zb1X6z1mFhbfOB/iy3ssJCD+3KuZ8r8C3uVFlAg==}
 
-  jsprim@1.4.2:
-    resolution: {integrity: sha512-P2bSOMAc/ciLz6DzgjVlGJP9+BrJWu5UDGK70C2iweC5QBIeFf0ZXRvGjEj2uYgrY2MkAAhsSWHDWlFtEroZWw==}
-    engines: {node: '>=0.6.0'}
+  jsprim@2.0.2:
+    resolution: {integrity: sha512-gqXddjPqQ6G40VdnI6T6yObEC+pDNvyP95wdQhkWkg7crHH3km5qP1FsOXEkzEQwnz6gz5qGTn1c2Y52wP3OyQ==}
+    engines: {'0': node >=0.6.0}
 
   katex@0.16.28:
     resolution: {integrity: sha512-YHzO7721WbmAL6Ov1uzN/l5mY5WWWhJBSW+jq4tkfZfsxmo1hu6frS0EOswvjBUnWE6NtjEs48SFn5CQESRLZg==}
@@ -5364,9 +5363,9 @@ packages:
   minimalistic-assert@1.0.1:
     resolution: {integrity: sha512-UtJcAD4yEaGtjPezWuO9wC4nwUnVH/8/Im3yEHQP4b67cXlD/Qr9hdITCU1xDbSEXg2XKNaP8jsReV7vQd00/A==}
 
-  minimatch@10.2.2:
-    resolution: {integrity: sha512-+G4CpNBxa5MprY+04MbgOw1v7So6n5JY166pFi9KfYwT78fxScCeSNQSNzp6dpPSW2rONOps6Ocam1wFhCgoVw==}
-    engines: {node: 18 || 20 || >=22}
+  minimatch@10.2.1:
+    resolution: {integrity: sha512-MClCe8IL5nRRmawL6ib/eT4oLyeKMGCghibcDWK+J0hh0Q8kqSdia6BvbRMVk6mPa6WqUa5uR2oxt6C5jd533A==}
+    engines: {node: 20 || >=22}
 
   minimist@1.2.8:
     resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
@@ -5518,9 +5517,6 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
-  oauth-sign@0.9.0:
-    resolution: {integrity: sha512-fexhUFFPTGV8ybAtSIGbV6gOkSv8UtRbDBnAyLQw4QPKkgNlsH2ByPGtMUqdWkos6YCRmAqViwgZrJc/mRDzZQ==}
-
   object-assign@4.1.1:
     resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
     engines: {node: '>=0.10.0'}
@@ -5834,9 +5830,6 @@ packages:
   proxy-from-env@1.1.0:
     resolution: {integrity: sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==}
 
-  psl@1.15.0:
-    resolution: {integrity: sha512-JZd3gMVBAVQkSs6HdNZo9Sdo0LNcQeMNP3CozBJb3JYC/QUYZTnKxP+f8oWRX4rHP5EurWxqAHTSwUCjlNKa1w==}
-
   pump@3.0.3:
     resolution: {integrity: sha512-todwxLMY7/heScKmntwQG8CXVkWUOdYxIvY2s0VWAAMh/nd8SoYiRaKjlr7+iCs984f2P8zvrfWcDDYVb73NfA==}
 
@@ -5847,8 +5840,8 @@ packages:
   pure-rand@6.1.0:
     resolution: {integrity: sha512-bVWawvoZoBYpp6yIoQtQXHZjmz35RSVHnUOTefl8Vcjr8snTPY1wnpSPMWekcFwbxI6gtmT7rSYPFvz71ldiOA==}
 
-  qs@6.14.1:
-    resolution: {integrity: sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ==}
+  qs@6.15.0:
+    resolution: {integrity: sha512-mAZTtNCeetKMH+pSjrb76NAM8V9a05I9aBZOHztWy/UqcJdQYNsf59vrRKWnojAT9Y+GbIvoTBC++CPHqpDBhQ==}
     engines: {node: '>=0.6'}
 
   randombytes@2.1.0:
@@ -5995,11 +5988,6 @@ packages:
     peerDependencies:
       request: ^2.34
 
-  request@2.88.2:
-    resolution: {integrity: sha512-MsvtOrfG9ZcrOwAW+Qi+F6HbD0CWXEh9ou77uOb7FM2WPhwT7smM833PzanhJLsgXjN89Ir6V2PczXNnMpwKhw==}
-    engines: {node: '>= 6'}
-    deprecated: request has been deprecated, see https://github.com/request/request/issues/3142
-
   require-directory@2.1.1:
     resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
     engines: {node: '>=0.10.0'}
@@ -6485,10 +6473,6 @@ packages:
     resolution: {integrity: sha512-dRXchy+C0IgK8WPC6xvCHFRIWYUbqqdEIKPaKo/AcTUNzwLTK6AH7RjdLWsEZcAN/TBdtfUw3PYEgPr5VPr6ww==}
     engines: {node: '>=14.16'}
 
-  tough-cookie@2.5.0:
-    resolution: {integrity: sha512-nlLsUzgm1kfLXSXfRZMc1KLAugd4hqJHDTvc2hDIwS3mZAfMEuMbc03SujMF+GEcpaX/qboeycw6iO8JwVv2+g==}
-    engines: {node: '>=0.8'}
-
   tough-cookie@5.1.2:
     resolution: {integrity: sha512-FVDYdxtnj0G6Qm/DhNPSb8Ju59ULcup3tuJxkFb5K8Bv2pUXILbf0xZWU8PX8Ov19OXljbUyveOFwRMwkXzO+A==}
     engines: {node: '>=16'}
@@ -6680,9 +6664,8 @@ packages:
     resolution: {integrity: sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==}
     hasBin: true
 
-  uuid@3.4.0:
-    resolution: {integrity: sha512-HjSDRw6gZE5JMggctHBcjVak08+KEVhSIiDzFnT9S9aegmp85S/bReBVTb4QTFaRNptJ9kuYaNhnbNEOkbKb/A==}
-    deprecated: Please upgrade  to version 7 or higher.  Older versions may use Math.random() in certain circumstances, which is known to be problematic.  See https://v8.dev/blog/math-random for details.
+  uuid@8.3.2:
+    resolution: {integrity: sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==}
     hasBin: true
 
   uuid@9.0.1:
@@ -7537,6 +7520,27 @@ snapshots:
 
   '@csstools/css-tokenizer@3.0.4': {}
 
+  '@cypress/request@3.0.10':
+    dependencies:
+      aws-sign2: 0.7.0
+      aws4: 1.13.2
+      caseless: 0.12.0
+      combined-stream: 1.0.8
+      extend: 3.0.2
+      forever-agent: 0.6.1
+      form-data: 4.0.5
+      http-signature: 1.4.0
+      is-typedarray: 1.0.0
+      isstream: 0.1.2
+      json-stringify-safe: 5.0.1
+      mime-types: 2.1.35
+      performance-now: 2.1.0
+      qs: 6.15.0
+      safe-buffer: 5.2.1
+      tough-cookie: 5.1.2
+      tunnel-agent: 0.6.0
+      uuid: 8.3.2
+
   '@discordjs/builders@1.13.1':
     dependencies:
       '@discordjs/formatters': 0.6.2
@@ -7705,7 +7709,7 @@ snapshots:
     dependencies:
       '@eslint/object-schema': 2.1.7
       debug: 4.4.3
-      minimatch: 10.2.2
+      minimatch: 10.2.1
     transitivePeerDependencies:
       - supports-color
 
@@ -7726,7 +7730,7 @@ snapshots:
       ignore: 5.3.2
       import-fresh: 3.3.1
       js-yaml: 4.1.1
-      minimatch: 10.2.2
+      minimatch: 10.2.1
       strip-json-comments: 3.1.1
     transitivePeerDependencies:
       - supports-color
@@ -9912,7 +9916,7 @@ snapshots:
       '@typescript-eslint/types': 8.54.0
       '@typescript-eslint/visitor-keys': 8.54.0
       debug: 4.4.3
-      minimatch: 10.2.2
+      minimatch: 10.2.1
       semver: 7.7.3
       tinyglobby: 0.2.15
       ts-api-utils: 2.4.0(typescript@5.9.3)
@@ -10217,9 +10221,9 @@ snapshots:
 
   agent-base@7.1.4: {}
 
-  ajv-formats@2.1.1(ajv@8.17.1):
+  ajv-formats@2.1.1(ajv@8.18.0):
     optionalDependencies:
-      ajv: 8.17.1
+      ajv: 8.18.0
 
   ajv-formats@3.0.1(ajv@8.17.1):
     optionalDependencies:
@@ -10229,9 +10233,9 @@ snapshots:
     dependencies:
       ajv: 6.12.6
 
-  ajv-keywords@5.1.0(ajv@8.17.1):
+  ajv-keywords@5.1.0(ajv@8.18.0):
     dependencies:
-      ajv: 8.17.1
+      ajv: 8.18.0
       fast-deep-equal: 3.1.3
 
   ajv@6.12.6:
@@ -10248,6 +10252,13 @@ snapshots:
       json-schema-traverse: 1.0.0
       require-from-string: 2.0.2
 
+  ajv@8.18.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-uri: 3.1.0
+      json-schema-traverse: 1.0.0
+      require-from-string: 2.0.2
+
   another-json@0.2.0: {}
 
   ansi-colors@4.1.3: {}
@@ -10480,7 +10491,7 @@ snapshots:
       http-errors: 2.0.1
       iconv-lite: 0.4.24
       on-finished: 2.4.1
-      qs: 6.14.1
+      qs: 6.15.0
       raw-body: 2.5.3
       type-is: 1.6.18
       unpipe: 1.0.0
@@ -10495,7 +10506,7 @@ snapshots:
       http-errors: 2.0.1
       iconv-lite: 0.7.2
       on-finished: 2.4.1
-      qs: 6.14.1
+      qs: 6.15.0
       raw-body: 3.0.2
       type-is: 2.0.1
     transitivePeerDependencies:
@@ -11411,7 +11422,7 @@ snapshots:
       is-glob: 4.0.3
       json-stable-stringify-without-jsonify: 1.0.1
       lodash.merge: 4.6.2
-      minimatch: 10.2.2
+      minimatch: 10.2.1
       natural-compare: 1.4.0
       optionator: 0.9.4
     optionalDependencies:
@@ -11488,7 +11499,7 @@ snapshots:
       parseurl: 1.3.3
       path-to-regexp: 0.1.12
       proxy-addr: 2.0.7
-      qs: 6.14.1
+      qs: 6.15.0
       range-parser: 1.2.1
       safe-buffer: 5.2.1
       send: 0.19.2
@@ -11523,7 +11534,7 @@ snapshots:
       once: 1.4.0
       parseurl: 1.3.3
       proxy-addr: 2.0.7
-      qs: 6.14.1
+      qs: 6.15.0
       range-parser: 1.2.1
       router: 2.2.0
       send: 1.2.1
@@ -11640,7 +11651,7 @@ snapshots:
       deepmerge: 4.3.1
       fs-extra: 10.1.0
       memfs: 3.5.3
-      minimatch: 10.2.2
+      minimatch: 10.2.1
       node-abort-controller: 3.1.1
       schema-utils: 3.3.0
       semver: 7.7.3
@@ -11760,14 +11771,14 @@ snapshots:
     dependencies:
       foreground-child: 3.3.1
       jackspeak: 3.4.3
-      minimatch: 10.2.2
+      minimatch: 10.2.1
       minipass: 7.1.2
       package-json-from-dist: 1.0.1
       path-scurry: 1.11.1
 
   glob@13.0.0:
     dependencies:
-      minimatch: 10.2.2
+      minimatch: 10.2.1
       minipass: 7.1.2
       path-scurry: 2.0.1
 
@@ -11788,13 +11799,6 @@ snapshots:
 
   hachure-fill@0.5.2: {}
 
-  har-schema@2.0.0: {}
-
-  har-validator@5.1.5:
-    dependencies:
-      ajv: 6.12.6
-      har-schema: 2.0.0
-
   has-flag@4.0.0: {}
 
   has-symbols@1.1.0: {}
@@ -11852,10 +11856,10 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  http-signature@1.2.0:
+  http-signature@1.4.0:
     dependencies:
       assert-plus: 1.0.0
-      jsprim: 1.4.2
+      jsprim: 2.0.2
       sshpk: 1.18.0
 
   https-proxy-agent@7.0.6:
@@ -12099,7 +12103,7 @@ snapshots:
     optionalDependencies:
       graceful-fs: 4.2.11
 
-  jsprim@1.4.2:
+  jsprim@2.0.2:
     dependencies:
       assert-plus: 1.0.0
       extsprintf: 1.3.0
@@ -12299,8 +12303,8 @@ snapshots:
       mkdirp: 3.0.1
       morgan: 1.10.1
       postgres: 3.4.8
-      request: 2.88.2
-      request-promise: 4.2.6(request@2.88.2)
+      request: '@cypress/request@3.0.10'
+      request-promise: 4.2.6(@cypress/request@3.0.10)
       sanitize-html: 2.17.0
     transitivePeerDependencies:
       - supports-color
@@ -12375,7 +12379,7 @@ snapshots:
 
   minimalistic-assert@1.0.1: {}
 
-  minimatch@10.2.2:
+  minimatch@10.2.1:
     dependencies:
       brace-expansion: 5.0.2
 
@@ -12521,8 +12525,6 @@ snapshots:
       pathe: 2.0.3
       tinyexec: 1.0.2
 
-  oauth-sign@0.9.0: {}
-
   object-assign@4.1.1: {}
 
   object-hash@3.0.0: {}
@@ -12831,10 +12833,6 @@ snapshots:
 
   proxy-from-env@1.1.0: {}
 
-  psl@1.15.0:
-    dependencies:
-      punycode: 2.3.1
-
   pump@3.0.3:
     dependencies:
       end-of-stream: 1.4.5
@@ -12844,7 +12842,7 @@ snapshots:
 
   pure-rand@6.1.0: {}
 
-  qs@6.14.1:
+  qs@6.15.0:
     dependencies:
       side-channel: 1.1.0
 
@@ -12953,7 +12951,7 @@ snapshots:
 
   readdir-glob@1.1.3:
     dependencies:
-      minimatch: 10.2.2
+      minimatch: 10.2.1
 
   readdirp@4.1.2: {}
 
@@ -13002,41 +13000,18 @@ snapshots:
 
   regexp-tree@0.1.27: {}
 
-  request-promise-core@1.1.4(request@2.88.2):
+  request-promise-core@1.1.4(@cypress/request@3.0.10):
     dependencies:
       lodash: 4.17.23
-      request: 2.88.2
+      request: '@cypress/request@3.0.10'
 
-  request-promise@4.2.6(request@2.88.2):
+  request-promise@4.2.6(@cypress/request@3.0.10):
     dependencies:
       bluebird: 3.7.2
-      request: 2.88.2
-      request-promise-core: 1.1.4(request@2.88.2)
+      request: '@cypress/request@3.0.10'
+      request-promise-core: 1.1.4(@cypress/request@3.0.10)
       stealthy-require: 1.1.1
-      tough-cookie: 2.5.0
-
-  request@2.88.2:
-    dependencies:
-      aws-sign2: 0.7.0
-      aws4: 1.13.2
-      caseless: 0.12.0
-      combined-stream: 1.0.8
-      extend: 3.0.2
-      forever-agent: 0.6.1
-      form-data: 4.0.5
-      har-validator: 5.1.5
-      http-signature: 1.2.0
-      is-typedarray: 1.0.0
-      isstream: 0.1.2
-      json-stringify-safe: 5.0.1
-      mime-types: 2.1.35
-      oauth-sign: 0.9.0
-      performance-now: 2.1.0
-      qs: 6.14.1
-      safe-buffer: 5.2.1
-      tough-cookie: 2.5.0
-      tunnel-agent: 0.6.0
-      uuid: 3.4.0
+      tough-cookie: 5.1.2
 
   require-directory@2.1.1: {}
 
@@ -13176,9 +13151,9 @@ snapshots:
   schema-utils@4.3.3:
     dependencies:
       '@types/json-schema': 7.0.15
-      ajv: 8.17.1
-      ajv-formats: 2.1.1(ajv@8.17.1)
-      ajv-keywords: 5.1.0(ajv@8.17.1)
+      ajv: 8.18.0
+      ajv-formats: 2.1.1(ajv@8.18.0)
+      ajv-keywords: 5.1.0(ajv@8.18.0)
 
   section-matter@1.0.0:
     dependencies:
@@ -13535,7 +13510,7 @@ snapshots:
       formidable: 3.5.4
       methods: 1.1.2
       mime: 2.6.0
-      qs: 6.14.1
+      qs: 6.15.0
     transitivePeerDependencies:
       - supports-color
 
@@ -13613,7 +13588,7 @@ snapshots:
     dependencies:
       '@istanbuljs/schema': 0.1.3
       glob: 10.5.0
-      minimatch: 10.2.2
+      minimatch: 10.2.1
 
   text-decoder@1.2.3:
     dependencies:
@@ -13660,11 +13635,6 @@ snapshots:
       '@tokenizer/token': 0.3.0
       ieee754: 1.2.1
 
-  tough-cookie@2.5.0:
-    dependencies:
-      psl: 1.15.0
-      punycode: 2.3.1
-
   tough-cookie@5.1.2:
     dependencies:
       tldts: 6.1.86
@@ -13846,7 +13816,7 @@ snapshots:
 
   uuid@11.1.0: {}
 
-  uuid@3.4.0: {}
+  uuid@8.3.2: {}
 
   uuid@9.0.1: {}
 
diff --git a/scripts/agent/orchestrator-daemon.sh b/scripts/agent/orchestrator-daemon.sh
new file mode 100755
index 0000000..7700f98
--- /dev/null
+++ b/scripts/agent/orchestrator-daemon.sh
@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./common.sh
+source "$SCRIPT_DIR/common.sh"
+
+ensure_repo_root
+
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
+ORCH_DIR=".mosaic/orchestrator"
+PID_FILE="$ORCH_DIR/orchestrator.pid"
+LOG_FILE="$ORCH_DIR/logs/daemon.log"
+
+usage() {
+  cat <<USAGE
+Usage: $(basename "$0") <start|drain|stop|status> [--poll-sec N] [--no-sync]
+
+Commands:
+  start    Run orchestrator drain loop in background (detached)
+  drain    Run orchestrator drain loop in foreground (until queue drained)
+  stop     Stop background orchestrator if running
+  status   Show background orchestrator status
+
+Options:
+  --poll-sec N   Poll interval (default: 15)
+  --no-sync      Skip docs/tasks.md -> orchestrator queue sync before run
+USAGE
+}
+
+cmd="${1:-status}"
+if [[ $# -gt 0 ]]; then
+  shift
+fi
+
+poll_sec=15
+sync_arg=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --poll-sec)
+      poll_sec="${2:-15}"
+      shift 2
+      ;;
+    --no-sync)
+      sync_arg="--no-sync"
+      shift
+      ;;
+    *)
+      echo "[agent-framework] unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+mkdir -p "$ORCH_DIR/logs" "$ORCH_DIR/results"
+
+is_running() {
+  [[ -f "$PID_FILE" ]] || return 1
+  local pid
+  pid="$(cat "$PID_FILE" 2>/dev/null || true)"
+  [[ -n "$pid" ]] || return 1
+  kill -0 "$pid" 2>/dev/null
+}
+
+case "$cmd" in
+  start)
+    if is_running; then
+      echo "[agent-framework] orchestrator already running (pid=$(cat "$PID_FILE"))"
+      exit 0
+    fi
+    nohup "$MOSAIC_HOME/bin/mosaic-orchestrator-drain" --poll-sec "$poll_sec" $sync_arg >"$LOG_FILE" 2>&1 &
+    echo "$!" > "$PID_FILE"
+    echo "[agent-framework] orchestrator started (pid=$!, log=$LOG_FILE)"
+    ;;
+  drain)
+    exec "$MOSAIC_HOME/bin/mosaic-orchestrator-drain" --poll-sec "$poll_sec" $sync_arg
+    ;;
+  stop)
+    if ! is_running; then
+      echo "[agent-framework] orchestrator not running"
+      rm -f "$PID_FILE"
+      exit 0
+    fi
+    pid="$(cat "$PID_FILE")"
+    kill "$pid" || true
+    rm -f "$PID_FILE"
+    echo "[agent-framework] orchestrator stopped (pid=$pid)"
+    ;;
+  status)
+    if is_running; then
+      echo "[agent-framework] orchestrator running (pid=$(cat "$PID_FILE"), log=$LOG_FILE)"
+    else
+      echo "[agent-framework] orchestrator not running"
+      rm -f "$PID_FILE"
+    fi
+    ;;
+  *)
+    usage
+    exit 1
+    ;;
+esac
diff --git a/scripts/agent/orchestrator-events.sh b/scripts/agent/orchestrator-events.sh
new file mode 100755
index 0000000..ca806c2
--- /dev/null
+++ b/scripts/agent/orchestrator-events.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./common.sh
+source "$SCRIPT_DIR/common.sh"
+
+ensure_repo_root
+
+ORCH_URL="${ORCHESTRATOR_URL:-http://localhost:3001}"
+API_KEY="${ORCHESTRATOR_API_KEY:-}"
+
+usage() {
+  cat <<USAGE
+Usage: $(basename "$0") <recent|watch> [--limit N]
+
+Commands:
+  recent   Fetch recent orchestrator events (JSON)
+  watch    Stream live orchestrator events (SSE)
+
+Options:
+  --limit N   Number of recent events to return (default: 50)
+
+Environment:
+  ORCHESTRATOR_URL      Orchestrator base URL (default: http://localhost:3001)
+  ORCHESTRATOR_API_KEY  Required API key for orchestrator requests
+USAGE
+}
+
+cmd="${1:-recent}"
+if [[ $# -gt 0 ]]; then
+  shift
+fi
+
+limit=50
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --limit)
+      limit="${2:-50}"
+      shift 2
+      ;;
+    *)
+      echo "[agent-framework] unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$API_KEY" ]]; then
+  echo "[agent-framework] ORCHESTRATOR_API_KEY is required" >&2
+  exit 1
+fi
+
+case "$cmd" in
+  recent)
+    curl -fsSL \
+      -H "X-API-Key: $API_KEY" \
+      -H "Content-Type: application/json" \
+      "$ORCH_URL/agents/events/recent?limit=$limit"
+    ;;
+  watch)
+    curl -NfsSL \
+      -H "X-API-Key: $API_KEY" \
+      -H "Accept: text/event-stream" \
+      "$ORCH_URL/agents/events"
+    ;;
+  *)
+    usage
+    exit 1
+    ;;
+esac
diff --git a/scripts/agent/orchestrator-worker.sh b/scripts/agent/orchestrator-worker.sh
new file mode 100755
index 0000000..5e384da
--- /dev/null
+++ b/scripts/agent/orchestrator-worker.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+task_file="${1:-}"
+if [[ -z "$task_file" || ! -f "$task_file" ]]; then
+  echo "[orchestrator-worker] missing task file argument" >&2
+  exit 1
+fi
+
+worker_exec="${MOSAIC_WORKER_EXEC:-}"
+if [[ -z "$worker_exec" ]]; then
+  if command -v codex >/dev/null 2>&1; then
+    worker_exec="codex -p"
+  elif command -v opencode >/dev/null 2>&1; then
+    worker_exec="opencode -p"
+  else
+    echo "[orchestrator-worker] set MOSAIC_WORKER_EXEC to your worker command (example: 'codex -p' or 'opencode -p')" >&2
+    exit 1
+  fi
+fi
+
+prompt="$(python3 - "$task_file" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+task = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+task_id = str(task.get("id", "TASK"))
+title = str(task.get("title", ""))
+description = str(task.get("description", ""))
+meta = task.get("metadata", {}) or {}
+issue = str(meta.get("issue", ""))
+repo = str(meta.get("repo", ""))
+branch = str(meta.get("branch", ""))
+depends = task.get("depends_on", [])
+if isinstance(depends, list):
+    depends_str = ", ".join(str(x) for x in depends)
+else:
+    depends_str = str(depends)
+
+print(
+    f"""Read ~/.config/mosaic/STANDARDS.md, then AGENTS.md and SOUL.md (if present).
+Complete this queued task fully.
+
+Task ID: {task_id}
+Title: {title}
+Description: {description}
+Issue: {issue}
+Repo hint: {repo}
+Branch hint: {branch}
+Depends on: {depends_str}
+
+Requirements:
+- Implement and verify the task end-to-end.
+- Keep changes scoped to this task.
+- Run project checks and tests relevant to touched code.
+- Return with a concise summary of what changed and verification results.
+"""
+)
+PY
+)"
+
+PROMPT="$prompt" bash -lc "$worker_exec \"\$PROMPT\""
diff --git a/scripts/agent/session-start.sh b/scripts/agent/session-start.sh
index 89e8cd1..4e2f77d 100755
--- a/scripts/agent/session-start.sh
+++ b/scripts/agent/session-start.sh
@@ -9,8 +9,35 @@ ensure_repo_root
 load_repo_hooks
 
 if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && has_remote; then
+  current_branch="$(git rev-parse --abbrev-ref HEAD)"
+  upstream_ref="$(git rev-parse --abbrev-ref --symbolic-full-name "@{upstream}" 2>/dev/null || true)"
+
+  if [[ -n "$upstream_ref" ]] && ! git show-ref --verify --quiet "refs/remotes/$upstream_ref"; then
+    echo "[agent-framework] Upstream ref '$upstream_ref' is missing; attempting to self-heal branch tracking"
+
+    fallback_upstream=""
+    if git show-ref --verify --quiet "refs/remotes/origin/develop"; then
+      fallback_upstream="origin/develop"
+    elif git show-ref --verify --quiet "refs/remotes/origin/main"; then
+      fallback_upstream="origin/main"
+    fi
+
+    if [[ -n "$fallback_upstream" ]] && [[ "$current_branch" != "HEAD" ]]; then
+      git branch --set-upstream-to="$fallback_upstream" "$current_branch" >/dev/null
+      upstream_ref="$fallback_upstream"
+      echo "[agent-framework] Set upstream for '$current_branch' to '$fallback_upstream'"
+    else
+      echo "[agent-framework] No fallback upstream found; skipping pull"
+      upstream_ref=""
+    fi
+  fi
+
   if git diff --quiet && git diff --cached --quiet; then
-    run_step "Pull latest changes" git pull --rebase
+    if [[ -n "$upstream_ref" ]]; then
+      run_step "Pull latest changes" git pull --rebase
+    else
+      echo "[agent-framework] Skip pull: no valid upstream configured"
+    fi
   else
     echo "[agent-framework] Skip pull: working tree has local changes"
   fi