From 3fcc07d07f10b21d1329761852d81c571576d363 Mon Sep 17 00:00:00 2001
From: Marc Parisi <phrocker@apache.org>
Date: Fri, 11 Sep 2026 10:23:53 -0400
Subject: [PATCH 1/6] Port remaining private features into public repo

Brings the public tree to parity with Sentrius-private. All changes are
additive or supersede existing stubs; no public-only code was lost.

Features:
- Deployment Environments: model, repository, service, REST controller and
  V49 migration for cross-cloud enclave tracking. Agent heartbeats now carry
  environmentName and refresh the environment last-contact timestamp.
- Agent Forensics: AgentForensicsService plus four /forensics/* endpoints
  (trace, by-agent, by-user, timeline) on AuditApiController.
- Behavioral pattern mining: BehavioralPatternAgent, AutomationAdoptionTracker,
  DriLifecycleService and four /dri/* endpoints on KnowledgeGraphController.
- Topology view: TopologyViewController, topology.html and sidebar entry.
- LLM analytics cost controls: ~15 new SystemOptions flags including an
  enableLLMAnalytics master kill switch and pattern-mining thresholds.
- Trust scoring: AgentContext.getProvenanceScore() now scores the real
  provenance trail instead of returning a hardcoded 80.0.

Not ported:
- ops-scripts/gcp/rendered-demo.yaml (rendered Helm output containing resolved
  Secret values); added a .gitignore rule so it cannot be committed here.
- test-node-properties-update.sh (empty file).

Verified with mvn clean install on JDK 17: all 18 modules build, tests pass
with 0 failures and 0 errors.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLVutpMbp3msuhvxA46cU3
---
 .gcp.env                                      |    4 +-
 .gitignore                                    |    4 +
 CLAUDE.md                                     |  173 +++
 .../automation/AutomationAdoptionTracker.java |  314 +++++
 .../behavioral/BehavioralPatternAgent.java    | 1128 +++++++++++++++++
 .../DocumentRelationshipAnalyzer.java         |   12 +
 .../RdpSessionSummarizationAgent.java         |   13 +
 .../SshSessionSummarizationAgent.java         |  243 +++-
 .../agents/trust/TrustEvaluationService.java  |  164 ++-
 .../src/main/resources/application.properties |    2 +
 .../controllers/api/AuditApiController.java   |  104 ++
 .../api/DeploymentEnvironmentController.java  |  112 ++
 .../documents/KnowledgeGraphController.java   |  130 +-
 .../view/TopologyViewController.java          |   34 +
 .../V49__create_deployment_environments.sql   |   25 +
 .../templates/fragments/sidebar.html          |    5 +
 .../resources/templates/sso/topology.html     |  598 +++++++++
 .../sso/core/dto/AgentHeartbeatDTO.java       |    1 +
 .../sentrius/sso/core/trust/AgentContext.java |   35 +-
 .../core/trust/TrustScoreCalculatorTest.java  |   43 +-
 .../sso/core/config/SystemOptions.java        |   60 +-
 .../sso/core/model/AgentHeartbeat.java        |    3 +
 .../sso/core/model/DeploymentEnvironment.java |  110 ++
 .../model/agents/AgentExecutionAudit.java     |    5 +
 .../sso/core/model/hostgroup/HostGroup.java   |    6 +
 .../AgentExecutionAuditRepository.java        |    6 +
 .../repository/AgentMemoryRepository.java     |    3 +
 .../DeploymentEnvironmentRepository.java      |   27 +
 .../DeploymentEnvironmentService.java         |  304 +++++
 .../agents/AgentForensicsService.java         |  436 +++++++
 .../core/services/agents/AgentService.java    |   16 +-
 .../documents/DriLifecycleService.java        |  296 +++++
 .../KnowledgeGraphIngestionService.java       |   21 +-
 .../services/agents/AgentServiceTest.java     |    4 +
 34 files changed, 4332 insertions(+), 109 deletions(-)
 create mode 100644 CLAUDE.md
 create mode 100644 analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java
 create mode 100644 analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java
 create mode 100644 api/src/main/java/io/sentrius/sso/controllers/api/DeploymentEnvironmentController.java
 create mode 100644 api/src/main/java/io/sentrius/sso/controllers/view/TopologyViewController.java
 create mode 100644 api/src/main/resources/db/migration/V49__create_deployment_environments.sql
 create mode 100644 api/src/main/resources/templates/sso/topology.html
 create mode 100644 dataplane/src/main/java/io/sentrius/sso/core/model/DeploymentEnvironment.java
 create mode 100644 dataplane/src/main/java/io/sentrius/sso/core/repository/DeploymentEnvironmentRepository.java
 create mode 100644 dataplane/src/main/java/io/sentrius/sso/core/services/DeploymentEnvironmentService.java
 create mode 100644 dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java
 create mode 100644 dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java

diff --git a/.gcp.env b/.gcp.env
index 3543fc4b..3c8d7265 100644
--- a/.gcp.env
+++ b/.gcp.env
@@ -1,7 +1,7 @@
-SENTRIUS_VERSION=1.1.161
+SENTRIUS_VERSION=1.1.162
 SENTRIUS_SSH_VERSION=1.1.13
 SENTRIUS_KEYCLOAK_VERSION=1.1.16
-SENTRIUS_AGENT_VERSION=1.1.76
+SENTRIUS_AGENT_VERSION=1.1.82
 SENTRIUS_AI_AGENT_VERSION=1.1.65
 LLMPROXY_VERSION=1.1.22
 LAUNCHER_VERSION=1.1.12
diff --git a/.gitignore b/.gitignore
index d3ebd5d4..80fdcd6d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -69,3 +69,7 @@ docker/prompt-advisor/prompt-advisor
 # Python
 *.pyc
 __pycache__/
+
+# Rendered Helm output - may contain resolved Secret values
+rendered*.yaml
+ops-scripts/**/rendered-*.yaml
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..52770c21
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,173 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Sentrius is a zero trust security platform for protecting infrastructure — SSH sessions, APIs, and RDP connections — with AI-powered monitoring, dynamic policy enforcement, and self-healing capabilities. It is a Java 17 / Spring Boot 3.4.x multi-module Maven project with a secondary Python agent framework.
+
+## Build Commands
+
+**CRITICAL: Builds take ~7 minutes, tests ~1 minute. NEVER cancel builds or tests. Use 60+ minute timeouts.**
+
+```bash
+# Full build (7m24s first time, 3-5min cached)
+mvn clean install
+
+# Build without tests (faster for dev)
+mvn clean install -DskipTests
+
+# Build specific module with dependencies
+mvn clean install -pl api -am
+mvn clean install -pl core,api,dataplane -am
+
+# Run all tests (~1m3s)
+mvn test
+
+# Run tests for a single module
+mvn test -pl api
+mvn test -pl core
+
+# Run a single test class
+mvn test -pl api -Dtest=DocumentControllerTest
+
+# CI equivalent
+mvn -B package --file pom.xml
+```
+
+### Helm Chart Validation
+```bash
+helm lint sentrius-chart
+helm lint sentrius-chart-launcher
+helm template test-launcher sentrius-chart-launcher --set tenant=test-tenant --dry-run
+```
+
+### Python Agent
+```bash
+cd python-agent
+pip3 install -r requirements.txt
+TEST_MODE=true python3 main.py chat-helper --task-data '{"test": "message"}'
+```
+
+### Docker Images
+```bash
+./ops-scripts/base/build-images.sh --all --no-cache          # Sequential
+./ops-scripts/base/build-all-images-concurrent.sh --all --no-cache  # Parallel (faster)
+```
+
+## Architecture
+
+### Module Dependency Graph
+
+```
+provenance-core          (standalone: event tracking/audit)
+    ↑
+core (sentrius-core)     (business logic, JPA entities, repositories, services)
+    ↑
+dataplane                (data processing, depends on core + sag)
+    ↑
+llm-core → llm-dataplane (LLM integration layers, depend on core)
+    ↑
+api                      (REST API + web UI, depends on core/dataplane/llm-*)
+integration-proxy        (external service proxy, adds Kubernetes client)
+agent-proxy              (agent communication proxy)
+agent-launcher           (K8s pod lifecycle management)
+analytics                (AI-powered monitoring/analysis agent)
+enterprise-agent         (AI enterprise agent)
+monitoring               (system monitoring agent)
+ssh-proxy / ssh-agent    (SSH proxy and agent)
+rdp-proxy                (RDP proxy)
+provenance-ingestor      (Kafka event ingestion)
+sag                      (ANTLR4 grammar for agent rules/guardrails, standalone)
+```
+
+### Spring Boot Applications (12 runnable services)
+- **api** (port 8080) — Main REST API and web UI
+- **integration-proxy** — External service integrations (LLM, GitHub, JIRA)
+- **agent-proxy** — WebSocket-based agent communication
+- **agent-launcher** — Dynamic agent lifecycle via Kubernetes
+- **analytics** — Java AI analysis agent (document relationships, session summarization, trust evaluation)
+- **enterprise-agent** — AI-powered enterprise agent
+- **monitoring** — System monitoring agent
+- **ssh-agent** / **ssh-proxy** — SSH session handling
+- **rdp-proxy** — RDP session handling
+- **provenance-ingestor** — Event ingestion from Kafka
+
+### Library Modules (not runnable)
+- **provenance-core** — Event/audit model
+- **core** — JPA entities, repositories, services, DTOs, security config
+- **dataplane** — Data processing services (knowledge graph ingestion, system options)
+- **llm-core** / **llm-dataplane** — LLM message models, categorization, response handling
+- **sag** — Sentrius Agent Grammar (ANTLR4 DSL for guardrails/rules)
+
+### Key Package Structure
+Base package: `io.sentrius.sso`
+- `core.model` — JPA entities (hosts, sessions, agents, documents, trust)
+- `core.repository` — Spring Data JPA repositories
+- `core.services` — Business logic services
+- `core.dto` — Data transfer objects
+- `core.config` — Configuration classes (SystemOptions for feature flags)
+- `core.security` — Security configuration
+- `controllers.api` — REST API controllers
+- `automation` — Rule automation and auditing
+- `genai` — Generative AI / LLM models
+- `io.sentrius.agent.analysis` — Analytics agent implementations
+
+### Data Stores
+- **PostgreSQL** (required) — Primary relational store with pgvector for embeddings
+- **Keycloak** (required) — OAuth2/OIDC authentication
+- **SurrealDB** (optional) — Knowledge graph
+- **Neo4j** (optional) — Graph analysis
+- **Kafka** (optional) — Event streaming for provenance
+- **Qdrant** (optional) — Vector search
+
+### Database Migrations
+Flyway migrations in `api/src/main/resources/db/migration/` (V1 through V36+). H2 in-memory database is used for tests.
+
+### Key Architecture Patterns
+- **ZTAT (Zero Trust Access Tokens)** — Custom token-based zero trust architecture
+- **ABAC** — Attribute-Based Access Control
+- **SAG** — ANTLR4-based DSL for agent guardrails (parsed in `sag` module, used by `dataplane`)
+- **Self-healing** — Automatic error detection and code repair via coding agents
+- **Knowledge graph** — Document ingestion into SurrealDB with concept extraction for Q&A
+- **MCP (Model Context Protocol)** — Integration with external tools (GitHub, coding)
+- **Provenance** — Full audit trail via Kafka event streaming
+- **WebSocket** — Real-time communication for terminals, agent status, monitoring
+
+## Local Development Environment
+
+Default service endpoints:
+- PostgreSQL: `home.guard.local:5432` (database: `sentrius`, user: `postgres`)
+- Keycloak: `http://localhost:8180`
+- OpenTelemetry: `http://localhost:4317`
+
+Key environment variables: `KEYCLOAK_BASE_URL`, `KEYCLOAK_SECRET`, `DATABASE_PASSWORD`, `KEYSTORE_PASSWORD`, `BASE_URL`, `SURREALDB_PASSWORD`
+
+Running locally:
+```bash
+./ops-scripts/local/run-sentrius.sh --build   # convenience script
+# OR
+cd api && mvn spring-boot:run                  # direct (needs PostgreSQL + Keycloak)
+```
+
+## Build Warnings (Safe to Ignore)
+
+```
+'dependencyManagement.dependencies.dependency' must be unique: org.projectlombok:lombok:jar
+'dependencyManagement.dependencies.dependency' must be unique: org.springframework.boot:spring-boot-starter-web:jar
+'dependencies.dependency' must be unique: org.springframework.boot:spring-boot-starter-actuator:jar
+```
+
+## Non-Maven Components
+
+- **python-agent/** — Python 3.12+ agent framework (chat-helper, mcp, coding, knowledge-graph agents)
+- **sentrius-chart/** — Helm chart for full Kubernetes deployment (70+ templates)
+- **sentrius-chart-launcher/** — Lightweight Helm chart for agent launcher only
+- **ops-scripts/** — Deployment scripts organized by environment (local, gcp, azure)
+- **docker/** — 17 Dockerfiles for all services (base image: eclipse-temurin:17-jdk-noble)
+
+## CI/CD
+
+GitHub Actions workflows in `.github/workflows/`:
+- **maven.yml** — Java build + tests on push/PR to main (JDK 17 temurin)
+- **helm-ci.yml** — Helm linting, template rendering, schema validation, integration tests with kind cluster
diff --git a/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java b/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java
new file mode 100644
index 00000000..a4fe6663
--- /dev/null
+++ b/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java
@@ -0,0 +1,314 @@
+package io.sentrius.agent.analysis.agents.automation;
+
+import io.sentrius.sso.core.config.SystemOptions;
+import io.sentrius.sso.core.model.automation.AutomationSuggestion;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphNode;
+import io.sentrius.sso.core.model.metadata.TerminalCommand;
+import io.sentrius.sso.core.model.metadata.TerminalSessionMetadata;
+import io.sentrius.sso.core.repository.automation.AutomationSuggestionRepository;
+import io.sentrius.sso.core.services.agents.AgentExecutionAuditService;
+import io.sentrius.sso.core.services.documents.KnowledgeGraphService;
+import io.sentrius.sso.core.services.metadata.TerminalCommandService;
+import io.sentrius.sso.core.services.metadata.TerminalSessionMetadataService;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.nio.charset.StandardCharsets;
+import java.time.LocalDateTime;
+import java.util.*;
+import java.util.stream.Collectors;
+
+/**
+ * Tracks adoption of generated automation suggestions and runbooks.
+ * When a user executes commands that match a generated automation script or runbook,
+ * creates an ADOPTED relationship in the knowledge graph to close the feedback loop.
+ *
+ * This data feeds back into:
+ * - Confidence scoring for future automation suggestions
+ * - "Life of a DRI" to show which automations are actually being used
+ * - Prioritization of runbook/TSG generation
+ */
+@Slf4j
+@Component
+@ConditionalOnProperty(
+    name = "agents.automation-suggestion.enabled",
+    havingValue = "true",
+    matchIfMissing = false
+)
+public class AutomationAdoptionTracker {
+
+    @Autowired(required = false)
+    private KnowledgeGraphService knowledgeGraphService;
+
+    private final AutomationSuggestionRepository suggestionRepository;
+    private final TerminalSessionMetadataService sessionMetadataService;
+    private final TerminalCommandService commandService;
+    private final AgentExecutionAuditService auditService;
+    private final SystemOptions systemOptions;
+
+    @Autowired
+    public AutomationAdoptionTracker(
+            AutomationSuggestionRepository suggestionRepository,
+            TerminalSessionMetadataService sessionMetadataService,
+            TerminalCommandService commandService,
+            AgentExecutionAuditService auditService,
+            SystemOptions systemOptions) {
+        this.suggestionRepository = suggestionRepository;
+        this.sessionMetadataService = sessionMetadataService;
+        this.commandService = commandService;
+        this.auditService = auditService;
+        this.systemOptions = systemOptions;
+    }
+
+    /**
+     * Check for adoption of automation suggestions every 8 hours.
+     * Compares APPROVED/PENDING automation scripts against recent session commands
+     * to detect if users are manually executing the suggested automation steps.
+     */
+    @Scheduled(fixedDelay = 28800000, initialDelay = 600000) // 8 hours, 10 min initial
+    @Transactional
+    public void trackAdoption() {
+        if (knowledgeGraphService == null) {
+            log.debug("Knowledge graph not available, skipping adoption tracking");
+            return;
+        }
+
+        String taskExecutionId = UUID.randomUUID().toString();
+        createTaskAudit(taskExecutionId, "automation-adoption-tracker");
+        String taskStatus = "COMPLETED";
+
+        try {
+            log.info("Starting automation adoption tracking...");
+
+            // Get all automation suggestions that could be adopted
+            List<AutomationSuggestion> suggestions = suggestionRepository.findByStatus("PENDING");
+            suggestions.addAll(suggestionRepository.findByStatus("APPROVED"));
+
+            if (suggestions.isEmpty()) {
+                log.debug("No automation suggestions to track adoption for");
+                return;
+            }
+
+            // Get recent processed sessions
+            List<TerminalSessionMetadata> recentSessions = sessionMetadataService.getSessionsByState("PROCESSED");
+            if (recentSessions.isEmpty()) {
+                log.debug("No processed sessions to check for adoption");
+                return;
+            }
+
+            int adoptionsDetected = 0;
+
+            for (AutomationSuggestion suggestion : suggestions) {
+                // Extract key commands from the suggestion script
+                List<String> scriptCommands = extractCommandsFromScript(suggestion.getSuggestedScript());
+                if (scriptCommands.isEmpty()) continue;
+
+                // Check if any recent sessions contain these commands
+                for (TerminalSessionMetadata session : recentSessions) {
+                    try {
+                        List<TerminalCommand> sessionCommands = commandService.getCommandsBySessionId(session.getId());
+                        if (sessionCommands == null || sessionCommands.isEmpty()) continue;
+
+                        List<String> decodedCommands = sessionCommands.stream()
+                            .map(cmd -> decodeCommand(cmd.getCommand()))
+                            .filter(s -> !s.isEmpty())
+                            .collect(Collectors.toList());
+
+                        // Calculate overlap between script commands and session commands
+                        double overlapScore = calculateCommandOverlap(scriptCommands, decodedCommands);
+
+                        if (overlapScore >= 0.5) { // At least 50% of script commands were executed
+                            // Detected adoption!
+                            createAdoptionRelationship(suggestion, session, overlapScore);
+                            adoptionsDetected++;
+
+                            log.info("Adoption detected: suggestion #{} ({}%) matched session {} by {}",
+                                suggestion.getId(), (int)(overlapScore * 100),
+                                session.getId(),
+                                session.getUser() != null ? session.getUser().getUsername() : "unknown");
+                        }
+
+                    } catch (Exception e) {
+                        log.debug("Error checking session {} for adoption: {}", session.getId(), e.getMessage());
+                    }
+                }
+            }
+
+            log.info("Automation adoption tracking complete: {} adoptions detected from {} suggestions",
+                adoptionsDetected, suggestions.size());
+
+        } catch (Exception e) {
+            log.error("Error in automation adoption tracking", e);
+            taskStatus = "ERROR";
+        } finally {
+            closeTaskAudit(taskExecutionId, taskStatus);
+        }
+    }
+
+    /**
+     * Extract meaningful commands from a script (bash or python).
+     * Filters out comments, empty lines, and script structure.
+     */
+    private List<String> extractCommandsFromScript(String script) {
+        if (script == null || script.isEmpty()) return Collections.emptyList();
+
+        return Arrays.stream(script.split("\n"))
+            .map(String::trim)
+            .filter(line -> !line.isEmpty())
+            .filter(line -> !line.startsWith("#"))     // Skip bash comments
+            .filter(line -> !line.startsWith("//"))    // Skip other comments
+            .filter(line -> !line.startsWith("echo"))  // Skip echo statements
+            .filter(line -> !line.startsWith("set"))   // Skip shell options
+            .filter(line -> !line.equals("#!/bin/bash"))
+            .filter(line -> !line.startsWith("if ") && !line.startsWith("then") &&
+                           !line.startsWith("fi") && !line.startsWith("else") &&
+                           !line.startsWith("done") && !line.startsWith("do"))
+            .filter(line -> line.length() > 3 && line.length() < 500)
+            .collect(Collectors.toList());
+    }
+
+    /**
+     * Calculate overlap between script commands and session commands.
+     * Uses fuzzy matching — a session command matches a script command if it
+     * contains the key executable and arguments.
+     */
+    private double calculateCommandOverlap(List<String> scriptCommands, List<String> sessionCommands) {
+        if (scriptCommands.isEmpty()) return 0.0;
+
+        int matched = 0;
+        for (String scriptCmd : scriptCommands) {
+            // Extract the core command (first word/executable)
+            String coreCmd = scriptCmd.split("\\s+")[0];
+            if (coreCmd.isEmpty()) continue;
+
+            for (String sessionCmd : sessionCommands) {
+                // Fuzzy match: session command starts with or contains the script command's core
+                if (sessionCmd.contains(coreCmd) && fuzzyMatch(scriptCmd, sessionCmd)) {
+                    matched++;
+                    break;
+                }
+            }
+        }
+
+        return (double) matched / scriptCommands.size();
+    }
+
+    /**
+     * Fuzzy match: check if a session command is similar enough to a script command.
+     * Compares the first N tokens of each command.
+     */
+    private boolean fuzzyMatch(String scriptCmd, String sessionCmd) {
+        String[] scriptTokens = scriptCmd.split("\\s+");
+        String[] sessionTokens = sessionCmd.split("\\s+");
+
+        // Must match the command name (first token)
+        if (scriptTokens.length == 0 || sessionTokens.length == 0) return false;
+        if (!scriptTokens[0].equals(sessionTokens[0])) return false;
+
+        // If just a single-word command, that's a match
+        if (scriptTokens.length == 1) return true;
+
+        // Check how many subsequent tokens match
+        int matchedTokens = 1; // Already matched first token
+        for (int i = 1; i < Math.min(scriptTokens.length, sessionTokens.length); i++) {
+            // Skip variable substitutions in scripts ($VAR, ${VAR})
+            if (scriptTokens[i].startsWith("$")) {
+                matchedTokens++;
+                continue;
+            }
+            if (scriptTokens[i].equals(sessionTokens[i])) {
+                matchedTokens++;
+            }
+        }
+
+        // At least half the tokens should match
+        return matchedTokens >= scriptTokens.length * 0.5;
+    }
+
+    /**
+     * Create an ADOPTED relationship in the knowledge graph between a session and a runbook/suggestion.
+     */
+    private void createAdoptionRelationship(AutomationSuggestion suggestion, TerminalSessionMetadata session,
+                                            double overlapScore) {
+        try {
+            String sessionNodeId = "session:" + session.getSessionLog().getId();
+
+            // Create or find the runbook node for this suggestion
+            String runbookId = "runbook:suggestion-" + suggestion.getId();
+
+            // Ensure the runbook node exists
+            Map<String, Object> properties = new HashMap<>();
+            properties.put("suggestionId", suggestion.getId());
+            properties.put("description", suggestion.getDescription());
+            properties.put("scriptType", suggestion.getScriptType());
+            properties.put("confidenceScore", suggestion.getConfidenceScore());
+
+            KnowledgeGraphNode runbookNode = KnowledgeGraphNode.builder()
+                .id(runbookId)
+                .nodeType("runbook")
+                .name("Automation: " + (suggestion.getDescription() != null ?
+                    suggestion.getDescription().substring(0, Math.min(80, suggestion.getDescription().length())) :
+                    "Suggestion #" + suggestion.getId()))
+                .description(suggestion.getDescription())
+                .properties(properties)
+                .markings("SESSION_DATA")
+                .createdBy("automation-adoption-tracker")
+                .createdAt(LocalDateTime.now())
+                .updatedAt(LocalDateTime.now())
+                .tags(Arrays.asList("runbook", "automation-suggestion", suggestion.getScriptType()))
+                .build();
+
+            knowledgeGraphService.createNode(runbookNode, "automation-adoption-tracker");
+
+            // Create ADOPTED relationship: session -> runbook
+            knowledgeGraphService.createRelationship(sessionNodeId, runbookId,
+                "ADOPTED", overlapScore, "automation-adoption-tracker");
+
+            // Also link the user to the runbook
+            if (session.getUser() != null) {
+                String userNodeId = "user:" + sanitizeId(session.getUser().getUsername());
+                knowledgeGraphService.createRelationship(userNodeId, runbookId,
+                    "ADOPTED", overlapScore, "automation-adoption-tracker");
+            }
+
+        } catch (Exception e) {
+            log.warn("Failed to create adoption relationship: {}", e.getMessage());
+        }
+    }
+
+    private String decodeCommand(String encoded) {
+        try {
+            return new String(Base64.getDecoder().decode(encoded), StandardCharsets.UTF_8);
+        } catch (Exception e) {
+            return "";
+        }
+    }
+
+    private String sanitizeId(String input) {
+        if (input == null) return "unknown";
+        return input.toLowerCase()
+            .replaceAll("[^a-z0-9-]", "-")
+            .replaceAll("-+", "-")
+            .replaceAll("^-|-$", "");
+    }
+
+    private void createTaskAudit(String taskExecutionId, String agentType) {
+        try {
+            auditService.createAudit("analytics-agent", taskExecutionId, agentType, "system");
+        } catch (Exception e) {
+            log.debug("Could not create audit for {} task: {}", agentType, e.getMessage());
+        }
+    }
+
+    private void closeTaskAudit(String taskExecutionId, String status) {
+        try {
+            auditService.closeAudit(taskExecutionId, status);
+        } catch (Exception e) {
+            log.debug("Could not close audit for task: {}", e.getMessage());
+        }
+    }
+}
diff --git a/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java b/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java
new file mode 100644
index 00000000..a99aab5d
--- /dev/null
+++ b/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java
@@ -0,0 +1,1128 @@
+package io.sentrius.agent.analysis.agents.behavioral;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import io.sentrius.sso.core.config.SystemOptions;
+import io.sentrius.sso.core.dto.ztat.TokenDTO;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphNode;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryRequest;
+import io.sentrius.sso.core.model.metadata.TerminalCommand;
+import io.sentrius.sso.core.model.metadata.TerminalSessionMetadata;
+import io.sentrius.sso.core.model.sessions.SessionLog;
+import io.sentrius.sso.core.model.sessions.SshSessionSummary;
+import io.sentrius.sso.core.repository.SessionLogRepository;
+import io.sentrius.sso.core.repository.SshSessionSummaryRepository;
+import io.sentrius.sso.core.services.agents.AgentExecutionAuditService;
+import io.sentrius.sso.core.services.agents.LLMService;
+import io.sentrius.sso.core.services.documents.KnowledgeGraphService;
+import io.sentrius.sso.core.services.metadata.TerminalCommandService;
+import io.sentrius.sso.core.services.metadata.TerminalSessionMetadataService;
+import io.sentrius.sso.core.services.security.IntegrationSecurityTokenService;
+import io.sentrius.sso.core.utils.JsonUtil;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.nio.charset.StandardCharsets;
+import java.sql.Timestamp;
+import java.time.*;
+import java.util.*;
+import java.util.stream.Collectors;
+
+/**
+ * Analytics agent that mines behavioral patterns from session data to discover:
+ * - Routines: Recurring access patterns (e.g., "user connects to host every morning")
+ * - Workflows: Common command sequences across sessions
+ * - Incidents: Correlated multi-user/multi-session events
+ * - Runbooks/TSGs: Auto-generated from discovered workflows
+ *
+ * Creates knowledge graph nodes and relationships for the "Life of a DRI" feature.
+ */
+@Slf4j
+@Component
+@ConditionalOnProperty(
+    name = "agents.behavioral-pattern.enabled",
+    havingValue = "true",
+    matchIfMissing = false
+)
+public class BehavioralPatternAgent {
+
+    @Autowired(required = false)
+    private KnowledgeGraphService knowledgeGraphService;
+
+    private final TerminalSessionMetadataService sessionMetadataService;
+    private final TerminalCommandService commandService;
+    private final SessionLogRepository sessionLogRepository;
+    private final SshSessionSummaryRepository sshSummaryRepository;
+    private final IntegrationSecurityTokenService integrationSecurityTokenService;
+    private final LLMService llmService;
+    private final AgentExecutionAuditService auditService;
+    private final SystemOptions systemOptions;
+
+    @Autowired
+    public BehavioralPatternAgent(
+            TerminalSessionMetadataService sessionMetadataService,
+            TerminalCommandService commandService,
+            SessionLogRepository sessionLogRepository,
+            SshSessionSummaryRepository sshSummaryRepository,
+            IntegrationSecurityTokenService integrationSecurityTokenService,
+            @Autowired(required = false) LLMService llmService,
+            AgentExecutionAuditService auditService,
+            SystemOptions systemOptions) {
+        this.sessionMetadataService = sessionMetadataService;
+        this.commandService = commandService;
+        this.sessionLogRepository = sessionLogRepository;
+        this.sshSummaryRepository = sshSummaryRepository;
+        this.integrationSecurityTokenService = integrationSecurityTokenService;
+        this.llmService = llmService;
+        this.auditService = auditService;
+        this.systemOptions = systemOptions;
+    }
+
+    // ========================================================================
+    // Scheduler - runs every 4 hours
+    // ========================================================================
+
+    @Scheduled(fixedDelay = 14400000, initialDelay = 300000) // 4 hours, 5 min initial delay
+    @Transactional
+    public void analyzePatterns() {
+        if (!isEnabled()) {
+            log.debug("Behavioral pattern mining disabled");
+            return;
+        }
+
+        if (knowledgeGraphService == null) {
+            log.debug("Knowledge graph service not available, skipping behavioral pattern analysis");
+            return;
+        }
+
+        String taskExecutionId = UUID.randomUUID().toString();
+        createTaskAudit(taskExecutionId, "behavioral-pattern-miner");
+        String taskStatus = "COMPLETED";
+
+        try {
+            log.info("Starting behavioral pattern analysis...");
+
+            // Phase 1: Discover routines from session access patterns
+            int routinesFound = discoverRoutines();
+            log.info("Phase 1 complete: {} routines discovered", routinesFound);
+
+            // Phase 2: Discover workflows from command sequences
+            int workflowsFound = discoverWorkflows();
+            log.info("Phase 2 complete: {} workflows discovered", workflowsFound);
+
+            // Phase 3: Correlate sessions into incidents
+            int incidentsFound = correlateIncidents();
+            log.info("Phase 3 complete: {} incidents correlated", incidentsFound);
+
+            // Phase 4: Generate runbooks from workflows (LLM-powered)
+            int runbooksGenerated = 0;
+            if (systemOptions.autoGenerateRunbooks != null && systemOptions.autoGenerateRunbooks) {
+                runbooksGenerated = generateRunbooks();
+                log.info("Phase 4 complete: {} runbooks generated", runbooksGenerated);
+            }
+
+            // Phase 5: Detect anomalies from baselines
+            int anomaliesDetected = 0;
+            if (systemOptions.baselineAnomalyDetectionEnabled != null && systemOptions.baselineAnomalyDetectionEnabled) {
+                anomaliesDetected = detectBaselineAnomalies();
+                log.info("Phase 5 complete: {} anomalies detected", anomaliesDetected);
+            }
+
+            // Phase 6: Build DRI role profiles
+            int profilesUpdated = 0;
+            if (systemOptions.driLifecycleTrackingEnabled != null && systemOptions.driLifecycleTrackingEnabled) {
+                profilesUpdated = buildRoleProfiles();
+                log.info("Phase 6 complete: {} DRI profiles updated", profilesUpdated);
+            }
+
+            log.info("Behavioral pattern analysis complete: {} routines, {} workflows, {} incidents, {} runbooks, {} anomalies, {} profiles",
+                routinesFound, workflowsFound, incidentsFound, runbooksGenerated, anomaliesDetected, profilesUpdated);
+
+        } catch (Exception e) {
+            log.error("Error in behavioral pattern analysis", e);
+            taskStatus = "ERROR";
+        } finally {
+            closeTaskAudit(taskExecutionId, taskStatus);
+        }
+    }
+
+    // ========================================================================
+    // Phase 1: Routine Discovery
+    // ========================================================================
+
+    private int discoverRoutines() {
+        int minOccurrences = systemOptions.routineMinOccurrences != null
+            ? systemOptions.routineMinOccurrences : 3;
+
+        // Group all sessions by user+host pair
+        List<TerminalSessionMetadata> allSessions = sessionMetadataService.getSessionsByState("PROCESSED");
+        if (allSessions.isEmpty()) return 0;
+
+        Map<String, List<TerminalSessionMetadata>> grouped = allSessions.stream()
+            .filter(s -> s.getUser() != null && s.getHostSystem() != null)
+            .collect(Collectors.groupingBy(
+                s -> s.getUser().getUsername() + "@" + s.getHostSystem().getHost()
+            ));
+
+        int routinesFound = 0;
+
+        for (Map.Entry<String, List<TerminalSessionMetadata>> entry : grouped.entrySet()) {
+            List<TerminalSessionMetadata> sessions = entry.getValue();
+            if (sessions.size() < minOccurrences) continue;
+
+            String userHost = entry.getKey();
+            String[] parts = userHost.split("@", 2);
+            String username = parts[0];
+            String host = parts.length > 1 ? parts[1] : "unknown";
+
+            // Analyze temporal patterns
+            TemporalPattern pattern = analyzeTemporalPattern(sessions);
+            if (pattern == null) continue;
+
+            // Create routine node in knowledge graph
+            try {
+                String routineId = "routine:" + sanitizeId(userHost + "-" + pattern.description);
+                Map<String, Object> properties = new HashMap<>();
+                properties.put("username", username);
+                properties.put("host", host);
+                properties.put("frequency", pattern.frequency);
+                properties.put("schedule", pattern.schedule);
+                properties.put("avgDurationSeconds", pattern.avgDurationSeconds);
+                properties.put("sessionCount", sessions.size());
+                properties.put("firstSeen", sessions.stream()
+                    .map(s -> s.getStartTime())
+                    .filter(Objects::nonNull)
+                    .min(Timestamp::compareTo)
+                    .map(Timestamp::toString).orElse("unknown"));
+                properties.put("lastSeen", sessions.stream()
+                    .map(s -> s.getStartTime())
+                    .filter(Objects::nonNull)
+                    .max(Timestamp::compareTo)
+                    .map(Timestamp::toString).orElse("unknown"));
+                properties.put("confidence", pattern.confidence);
+
+                // Extract common commands across these sessions
+                List<String> commonCommands = findCommonCommands(sessions);
+                properties.put("commonCommands", commonCommands.stream().limit(20).collect(Collectors.toList()));
+
+                KnowledgeGraphNode routineNode = KnowledgeGraphNode.builder()
+                    .id(routineId)
+                    .nodeType("routine")
+                    .name(username + "'s " + pattern.description + " on " + host)
+                    .description(String.format("Routine: %s connects to %s %s (%d occurrences, %.0f%% confidence)",
+                        username, host, pattern.schedule, sessions.size(), pattern.confidence * 100))
+                    .properties(properties)
+                    .markings("SESSION_DATA")
+                    .createdBy("behavioral-pattern-agent")
+                    .createdAt(LocalDateTime.now())
+                    .updatedAt(LocalDateTime.now())
+                    .tags(Arrays.asList("routine", "behavioral-pattern", pattern.frequency))
+                    .build();
+
+                knowledgeGraphService.createNode(routineNode, "behavioral-pattern-agent");
+
+                // Create PERFORMS_ROUTINELY relationship: user -> routine
+                String userNodeId = "user:" + sanitizeId(username);
+                knowledgeGraphService.createRelationship(userNodeId, routineId, "PERFORMS_ROUTINELY",
+                    pattern.confidence, "behavioral-pattern-agent");
+
+                // Create CONNECTED_TO relationship: routine -> system
+                String systemNodeId = "system:" + sanitizeId(host);
+                knowledgeGraphService.createRelationship(routineId, systemNodeId, "CONNECTED_TO",
+                    1.0, "behavioral-pattern-agent");
+
+                routinesFound++;
+
+            } catch (Exception e) {
+                log.warn("Failed to create routine node for {}: {}", userHost, e.getMessage());
+            }
+        }
+
+        return routinesFound;
+    }
+
+    /**
+     * Analyze sessions to find temporal patterns (daily, weekly, etc.)
+     */
+    private TemporalPattern analyzeTemporalPattern(List<TerminalSessionMetadata> sessions) {
+        if (sessions.size() < 2) return null;
+
+        // Extract hours of day from session start times
+        Map<Integer, Integer> hourCounts = new HashMap<>();
+        Map<Integer, Integer> dayOfWeekCounts = new HashMap<>();
+        List<Long> durationsSeconds = new ArrayList<>();
+
+        for (TerminalSessionMetadata s : sessions) {
+            if (s.getStartTime() == null) continue;
+
+            LocalDateTime startTime = s.getStartTime().toLocalDateTime();
+            hourCounts.merge(startTime.getHour(), 1, Integer::sum);
+            dayOfWeekCounts.merge(startTime.getDayOfWeek().getValue(), 1, Integer::sum);
+
+            if (s.getEndTime() != null) {
+                long dur = (s.getEndTime().getTime() - s.getStartTime().getTime()) / 1000;
+                if (dur > 0) durationsSeconds.add(dur);
+            }
+        }
+
+        // Find peak hour
+        int peakHour = hourCounts.entrySet().stream()
+            .max(Map.Entry.comparingByValue())
+            .map(Map.Entry::getKey).orElse(9);
+
+        int peakHourCount = hourCounts.getOrDefault(peakHour, 0);
+        double hourConcentration = (double) peakHourCount / sessions.size();
+
+        // Find peak day of week
+        int peakDay = dayOfWeekCounts.entrySet().stream()
+            .max(Map.Entry.comparingByValue())
+            .map(Map.Entry::getKey).orElse(1);
+
+        // Determine if it's a weekday pattern
+        int weekdayCount = dayOfWeekCounts.entrySet().stream()
+            .filter(e -> e.getKey() >= 1 && e.getKey() <= 5)
+            .mapToInt(Map.Entry::getValue).sum();
+        boolean weekdayPattern = weekdayCount > sessions.size() * 0.7;
+
+        long avgDuration = durationsSeconds.isEmpty() ? 0 :
+            durationsSeconds.stream().mapToLong(Long::longValue).sum() / durationsSeconds.size();
+
+        // Determine pattern type and confidence
+        String schedule;
+        String frequency;
+        String description;
+        double confidence;
+
+        if (hourConcentration > 0.5 && weekdayPattern) {
+            // Strong daily weekday pattern at a specific time
+            String timeLabel = peakHour < 12 ? "morning" : peakHour < 17 ? "afternoon" : "evening";
+            schedule = String.format("weekdays around %d:00", peakHour);
+            frequency = "daily";
+            description = timeLabel + " routine";
+            confidence = Math.min(0.95, hourConcentration * 0.8 + 0.2);
+        } else if (hourConcentration > 0.4) {
+            // Regular pattern at a specific time
+            String timeLabel = peakHour < 12 ? "morning" : peakHour < 17 ? "afternoon" : "evening";
+            schedule = String.format("regularly around %d:00", peakHour);
+            frequency = "regular";
+            description = timeLabel + " access pattern";
+            confidence = hourConcentration * 0.7;
+        } else {
+            // Irregular but frequent
+            schedule = "irregular schedule";
+            frequency = "frequent";
+            description = "frequent access pattern";
+            confidence = 0.3;
+        }
+
+        // Don't create very low confidence patterns
+        if (confidence < 0.3) return null;
+
+        TemporalPattern pattern = new TemporalPattern();
+        pattern.schedule = schedule;
+        pattern.frequency = frequency;
+        pattern.description = description;
+        pattern.confidence = confidence;
+        pattern.peakHour = peakHour;
+        pattern.avgDurationSeconds = avgDuration;
+        return pattern;
+    }
+
+    /**
+     * Find commands that appear in most sessions for a user+host pair.
+     */
+    private List<String> findCommonCommands(List<TerminalSessionMetadata> sessions) {
+        Map<String, Integer> commandFrequency = new HashMap<>();
+        int sessionCount = 0;
+
+        for (TerminalSessionMetadata session : sessions) {
+            try {
+                List<TerminalCommand> commands = commandService.getCommandsBySessionId(session.getId());
+                if (commands == null || commands.isEmpty()) continue;
+
+                sessionCount++;
+                Set<String> uniqueInSession = commands.stream()
+                    .map(cmd -> decodeCommand(cmd.getCommand()))
+                    .filter(s -> !s.isEmpty())
+                    .collect(Collectors.toSet());
+
+                uniqueInSession.forEach(cmd -> commandFrequency.merge(cmd, 1, Integer::sum));
+            } catch (Exception e) {
+                log.debug("Error reading commands for session {}: {}", session.getId(), e.getMessage());
+            }
+        }
+
+        if (sessionCount == 0) return Collections.emptyList();
+
+        // Return commands that appear in at least 40% of sessions
+        int threshold = Math.max(2, (int)(sessionCount * 0.4));
+        final int finalCount = sessionCount;
+        return commandFrequency.entrySet().stream()
+            .filter(e -> e.getValue() >= threshold)
+            .sorted((a, b) -> b.getValue().compareTo(a.getValue()))
+            .map(Map.Entry::getKey)
+            .collect(Collectors.toList());
+    }
+
+    // ========================================================================
+    // Phase 2: Workflow Discovery
+    // ========================================================================
+
+    private int discoverWorkflows() {
+        List<TerminalSessionMetadata> sessions = sessionMetadataService.getSessionsByState("PROCESSED");
+        if (sessions.isEmpty()) return 0;
+
+        // Group by host to find workflows specific to a system
+        Map<String, List<TerminalSessionMetadata>> byHost = sessions.stream()
+            .filter(s -> s.getHostSystem() != null)
+            .collect(Collectors.groupingBy(s -> s.getHostSystem().getHost()));
+
+        int workflowsFound = 0;
+
+        for (Map.Entry<String, List<TerminalSessionMetadata>> entry : byHost.entrySet()) {
+            String host = entry.getKey();
+            List<TerminalSessionMetadata> hostSessions = entry.getValue();
+            if (hostSessions.size() < 3) continue;
+
+            // Extract command sequences from each session
+            List<List<String>> allSequences = new ArrayList<>();
+            for (TerminalSessionMetadata session : hostSessions) {
+                try {
+                    List<TerminalCommand> commands = commandService.getCommandsBySessionId(session.getId());
+                    if (commands == null || commands.size() < 2) continue;
+
+                    List<String> decoded = commands.stream()
+                        .map(cmd -> decodeCommand(cmd.getCommand()))
+                        .filter(s -> !s.isEmpty())
+                        .collect(Collectors.toList());
+
+                    if (decoded.size() >= 2) {
+                        allSequences.add(decoded);
+                    }
+                } catch (Exception e) {
+                    log.debug("Error reading commands for session {}", session.getId());
+                }
+            }
+
+            // Find common subsequences across sessions
+            List<List<String>> workflows = findCommonSubsequences(allSequences);
+
+            for (List<String> workflow : workflows) {
+                try {
+                    String workflowName = workflow.stream().limit(3).collect(Collectors.joining(" → "));
+                    String workflowId = "workflow:" + sanitizeId(host + "-" + workflowName.hashCode());
+
+                    Map<String, Object> properties = new HashMap<>();
+                    properties.put("host", host);
+                    properties.put("steps", workflow);
+                    properties.put("stepCount", workflow.size());
+                    properties.put("occurrences", countSequenceOccurrences(allSequences, workflow));
+
+                    KnowledgeGraphNode workflowNode = KnowledgeGraphNode.builder()
+                        .id(workflowId)
+                        .nodeType("workflow")
+                        .name("Workflow: " + workflowName + (workflow.size() > 3 ? " ..." : ""))
+                        .description(String.format("Common workflow on %s: %s (%d steps)",
+                            host, String.join(" → ", workflow), workflow.size()))
+                        .properties(properties)
+                        .markings("SESSION_DATA")
+                        .createdBy("behavioral-pattern-agent")
+                        .createdAt(LocalDateTime.now())
+                        .updatedAt(LocalDateTime.now())
+                        .tags(Arrays.asList("workflow", "behavioral-pattern", host))
+                        .build();
+
+                    knowledgeGraphService.createNode(workflowNode, "behavioral-pattern-agent");
+
+                    // Create PART_OF_WORKFLOW relationships for each command
+                    for (int i = 0; i < workflow.size(); i++) {
+                        String cmdNodeId = "command:" + sanitizeId(workflow.get(i));
+                        Map<String, Object> cmdProps = new HashMap<>();
+                        cmdProps.put("command", workflow.get(i));
+                        cmdProps.put("stepIndex", i);
+
+                        KnowledgeGraphNode cmdNode = KnowledgeGraphNode.builder()
+                            .id(cmdNodeId)
+                            .nodeType("command")
+                            .name(workflow.get(i))
+                            .description("Command: " + workflow.get(i))
+                            .properties(cmdProps)
+                            .markings("SESSION_DATA")
+                            .createdBy("behavioral-pattern-agent")
+                            .build();
+
+                        knowledgeGraphService.createNode(cmdNode, "behavioral-pattern-agent");
+                        knowledgeGraphService.createRelationship(cmdNodeId, workflowId, "PART_OF_WORKFLOW",
+                            1.0, "behavioral-pattern-agent");
+                    }
+
+                    workflowsFound++;
+                } catch (Exception e) {
+                    log.warn("Failed to create workflow node: {}", e.getMessage());
+                }
+            }
+        }
+
+        return workflowsFound;
+    }
+
+    /**
+     * Find common subsequences (ordered) that appear across multiple session command lists.
+     */
+    private List<List<String>> findCommonSubsequences(List<List<String>> allSequences) {
+        if (allSequences.size() < 2) return Collections.emptyList();
+
+        // Find command pairs that frequently appear in order
+        Map<String, Integer> pairFrequency = new HashMap<>();
+        for (List<String> seq : allSequences) {
+            Set<String> seenPairs = new HashSet<>();
+            for (int i = 0; i < seq.size() - 1; i++) {
+                String pair = seq.get(i) + "|||" + seq.get(i + 1);
+                if (seenPairs.add(pair)) {
+                    pairFrequency.merge(pair, 1, Integer::sum);
+                }
+            }
+        }
+
+        // Keep pairs that appear in at least 40% of sequences
+        int threshold = Math.max(2, (int)(allSequences.size() * 0.4));
+        Set<String> commonPairs = pairFrequency.entrySet().stream()
+            .filter(e -> e.getValue() >= threshold)
+            .map(Map.Entry::getKey)
+            .collect(Collectors.toSet());
+
+        if (commonPairs.isEmpty()) return Collections.emptyList();
+
+        // Build chains from common pairs
+        List<List<String>> workflows = new ArrayList<>();
+        Set<String> usedPairs = new HashSet<>();
+
+        for (String pair : commonPairs) {
+            if (usedPairs.contains(pair)) continue;
+
+            String[] parts = pair.split("\\|\\|\\|", 2);
+            List<String> chain = new ArrayList<>();
+            chain.add(parts[0]);
+            chain.add(parts[1]);
+            usedPairs.add(pair);
+
+            // Try to extend the chain
+            boolean extended = true;
+            while (extended) {
+                extended = false;
+                String lastCmd = chain.get(chain.size() - 1);
+                for (String nextPair : commonPairs) {
+                    if (usedPairs.contains(nextPair)) continue;
+                    String[] nextParts = nextPair.split("\\|\\|\\|", 2);
+                    if (nextParts[0].equals(lastCmd)) {
+                        chain.add(nextParts[1]);
+                        usedPairs.add(nextPair);
+                        extended = true;
+                        break;
+                    }
+                }
+            }
+
+            if (chain.size() >= 2) {
+                workflows.add(chain);
+            }
+        }
+
+        return workflows;
+    }
+
+    private int countSequenceOccurrences(List<List<String>> allSequences, List<String> workflow) {
+        int count = 0;
+        for (List<String> seq : allSequences) {
+            if (containsSubsequence(seq, workflow)) count++;
+        }
+        return count;
+    }
+
+    private boolean containsSubsequence(List<String> sequence, List<String> subsequence) {
+        int j = 0;
+        for (int i = 0; i < sequence.size() && j < subsequence.size(); i++) {
+            if (sequence.get(i).equals(subsequence.get(j))) {
+                j++;
+            }
+        }
+        return j == subsequence.size();
+    }
+
+    // ========================================================================
+    // Phase 3: Incident Correlation
+    // ========================================================================
+
+    private int correlateIncidents() {
+        int windowMinutes = systemOptions.incidentCorrelationWindowMinutes != null
+            ? systemOptions.incidentCorrelationWindowMinutes : 30;
+
+        // Find sessions that overlap or are close in time on the same host
+        List<TerminalSessionMetadata> sessions = sessionMetadataService.getSessionsByState("PROCESSED");
+        if (sessions.size() < 2) return 0;
+
+        // Group by host
+        Map<String, List<TerminalSessionMetadata>> byHost = sessions.stream()
+            .filter(s -> s.getHostSystem() != null && s.getStartTime() != null)
+            .collect(Collectors.groupingBy(s -> s.getHostSystem().getHost()));
+
+        int incidentsFound = 0;
+
+        for (Map.Entry<String, List<TerminalSessionMetadata>> entry : byHost.entrySet()) {
+            String host = entry.getKey();
+            List<TerminalSessionMetadata> hostSessions = entry.getValue();
+
+            // Sort by start time
+            hostSessions.sort(Comparator.comparing(TerminalSessionMetadata::getStartTime));
+
+            // Find clusters of sessions within the correlation window
+            List<List<TerminalSessionMetadata>> clusters = new ArrayList<>();
+            List<TerminalSessionMetadata> currentCluster = new ArrayList<>();
+
+            for (TerminalSessionMetadata session : hostSessions) {
+                if (currentCluster.isEmpty()) {
+                    currentCluster.add(session);
+                } else {
+                    TerminalSessionMetadata last = currentCluster.get(currentCluster.size() - 1);
+                    long gapMinutes = (session.getStartTime().getTime() - last.getStartTime().getTime()) / 60000;
+                    if (gapMinutes <= windowMinutes) {
+                        currentCluster.add(session);
+                    } else {
+                        if (currentCluster.size() >= 2) {
+                            // Multiple users/sessions in a window = potential incident
+                            Set<String> users = currentCluster.stream()
+                                .filter(s -> s.getUser() != null)
+                                .map(s -> s.getUser().getUsername())
+                                .collect(Collectors.toSet());
+                            if (users.size() >= 2) {
+                                clusters.add(new ArrayList<>(currentCluster));
+                            }
+                        }
+                        currentCluster = new ArrayList<>();
+                        currentCluster.add(session);
+                    }
+                }
+            }
+            // Don't forget the last cluster
+            if (currentCluster.size() >= 2) {
+                Set<String> users = currentCluster.stream()
+                    .filter(s -> s.getUser() != null)
+                    .map(s -> s.getUser().getUsername())
+                    .collect(Collectors.toSet());
+                if (users.size() >= 2) {
+                    clusters.add(currentCluster);
+                }
+            }
+
+            // Create incident nodes for each cluster
+            for (List<TerminalSessionMetadata> cluster : clusters) {
+                try {
+                    Timestamp earliest = cluster.stream()
+                        .map(TerminalSessionMetadata::getStartTime)
+                        .min(Timestamp::compareTo).orElse(new Timestamp(System.currentTimeMillis()));
+
+                    String incidentId = "incident:" + sanitizeId(host + "-" + earliest.getTime());
+                    Set<String> involvedUsers = cluster.stream()
+                        .filter(s -> s.getUser() != null)
+                        .map(s -> s.getUser().getUsername())
+                        .collect(Collectors.toSet());
+
+                    Map<String, Object> properties = new HashMap<>();
+                    properties.put("host", host);
+                    properties.put("sessionCount", cluster.size());
+                    properties.put("involvedUsers", new ArrayList<>(involvedUsers));
+                    properties.put("startTime", earliest.toString());
+                    properties.put("durationMinutes", cluster.size() > 1 ?
+                        (cluster.get(cluster.size() - 1).getStartTime().getTime() - earliest.getTime()) / 60000 : 0);
+
+                    KnowledgeGraphNode incidentNode = KnowledgeGraphNode.builder()
+                        .id(incidentId)
+                        .nodeType("incident")
+                        .name(String.format("Incident on %s (%s)", host, earliest.toLocalDateTime().toLocalDate()))
+                        .description(String.format("Correlated incident: %d sessions by %d users on %s within %d-minute window",
+                            cluster.size(), involvedUsers.size(), host, windowMinutes))
+                        .properties(properties)
+                        .markings("SESSION_DATA")
+                        .createdBy("behavioral-pattern-agent")
+                        .createdAt(LocalDateTime.now())
+                        .updatedAt(LocalDateTime.now())
+                        .tags(Arrays.asList("incident", "behavioral-pattern", host))
+                        .build();
+
+                    knowledgeGraphService.createNode(incidentNode, "behavioral-pattern-agent");
+
+                    // Link sessions to incident
+                    for (TerminalSessionMetadata session : cluster) {
+                        String sessionNodeId = "session:" + session.getSessionLog().getId();
+                        knowledgeGraphService.createRelationship(sessionNodeId, incidentId,
+                            "TRIGGERED_BY_INCIDENT", 0.8, "behavioral-pattern-agent");
+                    }
+
+                    // Create COLLABORATES_WITH relationships between involved users
+                    List<String> userList = new ArrayList<>(involvedUsers);
+                    for (int i = 0; i < userList.size() - 1; i++) {
+                        for (int j = i + 1; j < userList.size(); j++) {
+                            String user1NodeId = "user:" + sanitizeId(userList.get(i));
+                            String user2NodeId = "user:" + sanitizeId(userList.get(j));
+                            knowledgeGraphService.createRelationship(user1NodeId, user2NodeId,
+                                "COLLABORATES_WITH", 0.7, "behavioral-pattern-agent");
+                        }
+                    }
+
+                    incidentsFound++;
+                } catch (Exception e) {
+                    log.warn("Failed to create incident node: {}", e.getMessage());
+                }
+            }
+        }
+
+        return incidentsFound;
+    }
+
+    // ========================================================================
+    // Phase 4: Runbook/TSG Generation
+    // ========================================================================
+
+    private int generateRunbooks() {
+        if (knowledgeGraphService == null || !isLLMAvailable()) return 0;
+
+        // Find workflow nodes that don't have associated runbooks yet
+        // Query the knowledge graph for workflow nodes
+        try {
+            // Get all workflow nodes
+            var queryRequest = KnowledgeGraphQueryRequest.builder()
+                .queryType(KnowledgeGraphQueryRequest.QueryType.SEARCH)
+                .searchText("workflow")
+                .nodeTypes(List.of("workflow"))
+                .limit(20)
+                .build();
+
+            var response = knowledgeGraphService.executeQuery(queryRequest, "behavioral-pattern-agent");
+            if (response == null || response.getNodes() == null) return 0;
+
+            int runbooksGenerated = 0;
+
+            for (KnowledgeGraphNode workflowNode : response.getNodes()) {
+                if (!"workflow".equals(workflowNode.getNodeType())) continue;
+
+                // Check if a runbook already exists for this workflow
+                String runbookId = "runbook:" + sanitizeId(workflowNode.getId().replace("workflow:", ""));
+
+                try {
+                    @SuppressWarnings("unchecked")
+                    List<String> steps = workflowNode.getProperties() != null
+                        ? (List<String>) workflowNode.getProperties().get("steps")
+                        : null;
+
+                    if (steps == null || steps.isEmpty()) continue;
+
+                    String host = workflowNode.getProperties() != null
+                        ? (String) workflowNode.getProperties().get("host")
+                        : "unknown";
+
+                    String runbookContent = generateRunbookFromWorkflow(steps, host, workflowNode.getName());
+                    if (runbookContent == null || runbookContent.isEmpty()) continue;
+
+                    Map<String, Object> properties = new HashMap<>();
+                    properties.put("sourceWorkflowId", workflowNode.getId());
+                    properties.put("host", host);
+                    properties.put("generatedBy", "behavioral-pattern-agent");
+                    properties.put("content", runbookContent);
+                    properties.put("steps", steps);
+
+                    KnowledgeGraphNode runbookNode = KnowledgeGraphNode.builder()
+                        .id(runbookId)
+                        .nodeType("runbook")
+                        .name("TSG: " + workflowNode.getName())
+                        .description("Auto-generated runbook from observed workflow: " + workflowNode.getName())
+                        .properties(properties)
+                        .markings("SESSION_DATA")
+                        .createdBy("behavioral-pattern-agent")
+                        .createdAt(LocalDateTime.now())
+                        .updatedAt(LocalDateTime.now())
+                        .tags(Arrays.asList("runbook", "tsg", "auto-generated", host))
+                        .build();
+
+                    knowledgeGraphService.createNode(runbookNode, "behavioral-pattern-agent");
+
+                    // Link runbook to source workflow
+                    knowledgeGraphService.createRelationship(runbookId, workflowNode.getId(),
+                        "GENERATED_FROM", 1.0, "behavioral-pattern-agent");
+
+                    runbooksGenerated++;
+
+                } catch (Exception e) {
+                    log.warn("Failed to generate runbook for workflow {}: {}", workflowNode.getId(), e.getMessage());
+                }
+            }
+
+            return runbooksGenerated;
+
+        } catch (Exception e) {
+            log.warn("Failed to query workflows for runbook generation: {}", e.getMessage());
+            return 0;
+        }
+    }
+
+    private String generateRunbookFromWorkflow(List<String> steps, String host, String workflowName) {
+        try {
+            var token = integrationSecurityTokenService.selectToken(systemOptions.getDefaultLlmProvider())
+                .orElse(null);
+            if (token == null) return null;
+
+            TokenDTO tokenDTO = TokenDTO.builder()
+                .communicationId(UUID.randomUUID().toString())
+                .ztatToken("")
+                .build();
+
+            String stepsText = String.join("\n", steps.stream()
+                .map(s -> "- " + s)
+                .collect(Collectors.toList()));
+
+            String prompt = String.format(
+                "Generate a concise operational runbook/TSG (Troubleshooting Guide) based on this observed workflow on host '%s'.\n\n" +
+                "Workflow: %s\nObserved steps:\n%s\n\n" +
+                "Generate a structured runbook with:\n" +
+                "1. Purpose (1-2 sentences)\n" +
+                "2. Prerequisites\n" +
+                "3. Step-by-step procedure (use the observed commands, add context)\n" +
+                "4. Verification steps\n" +
+                "5. Rollback procedure if applicable\n\n" +
+                "Keep it practical and concise. Use the actual commands observed.",
+                host, workflowName, stepsText
+            );
+
+            Map<String, Object> payload = Map.of(
+                "model", "gpt-4o-mini",
+                "input", List.of(
+                    Map.of("role", "system", "content", List.of(
+                        Map.of("type", "text", "text",
+                            "You are an SRE writing operational runbooks from observed terminal session patterns. " +
+                            "Be concise and practical. Focus on the actual commands observed.")
+                    )),
+                    Map.of("role", "user", "content", List.of(
+                        Map.of("type", "text", "text", prompt)
+                    ))
+                ),
+                "temperature", 0.3
+            );
+
+            String raw = llmService.askQuestion(tokenDTO, payload);
+            JsonNode response = JsonUtil.MAPPER.readTree(raw);
+            return extractResponseText(response);
+
+        } catch (io.sentrius.sso.core.exceptions.ZtatException | com.fasterxml.jackson.core.JsonProcessingException e) {
+            log.debug("LLM runbook generation failed: {}", e.getMessage());
+            return null;
+        } catch (Exception e) {
+            log.debug("LLM runbook generation failed: {}", e.getMessage());
+            return null;
+        }
+    }
+
+    // ========================================================================
+    // Phase 5: Baseline Anomaly Detection
+    // ========================================================================
+
+    private int detectBaselineAnomalies() {
+        double deviationThreshold = systemOptions.anomalyDeviationThreshold != null
+            ? systemOptions.anomalyDeviationThreshold : 2.0;
+
+        List<TerminalSessionMetadata> recentSessions = sessionMetadataService.getSessionsByState("PROCESSED");
+        if (recentSessions.isEmpty()) return 0;
+
+        // Group by user
+        Map<String, List<TerminalSessionMetadata>> byUser = recentSessions.stream()
+            .filter(s -> s.getUser() != null)
+            .collect(Collectors.groupingBy(s -> s.getUser().getUsername()));
+
+        int anomaliesDetected = 0;
+
+        for (Map.Entry<String, List<TerminalSessionMetadata>> entry : byUser.entrySet()) {
+            String username = entry.getKey();
+            List<TerminalSessionMetadata> userSessions = entry.getValue();
+            if (userSessions.size() < 5) continue; // Need enough history for a baseline
+
+            // Calculate baseline metrics
+            DoubleSummaryStatistics commandCountStats = userSessions.stream()
+                .map(s -> {
+                    try {
+                        var cmds = commandService.getCommandsBySessionId(s.getId());
+                        return cmds != null ? (double) cmds.size() : 0.0;
+                    } catch (Exception e) {
+                        return 0.0;
+                    }
+                })
+                .collect(Collectors.summarizingDouble(Double::doubleValue));
+
+            double meanCommands = commandCountStats.getAverage();
+            double stdDevCommands = calculateStdDev(userSessions.stream()
+                .map(s -> {
+                    try {
+                        var cmds = commandService.getCommandsBySessionId(s.getId());
+                        return cmds != null ? (double) cmds.size() : 0.0;
+                    } catch (Exception e) {
+                        return 0.0;
+                    }
+                })
+                .collect(Collectors.toList()), meanCommands);
+
+            // Calculate baseline for session time of day
+            DoubleSummaryStatistics hourStats = userSessions.stream()
+                .filter(s -> s.getStartTime() != null)
+                .map(s -> (double) s.getStartTime().toLocalDateTime().getHour())
+                .collect(Collectors.summarizingDouble(Double::doubleValue));
+
+            double meanHour = hourStats.getAverage();
+            double stdDevHour = calculateStdDev(userSessions.stream()
+                .filter(s -> s.getStartTime() != null)
+                .map(s -> (double) s.getStartTime().toLocalDateTime().getHour())
+                .collect(Collectors.toList()), meanHour);
+
+            // Check the most recent sessions for anomalies
+            List<TerminalSessionMetadata> recent = userSessions.stream()
+                .sorted((a, b) -> {
+                    if (a.getStartTime() == null) return 1;
+                    if (b.getStartTime() == null) return -1;
+                    return b.getStartTime().compareTo(a.getStartTime());
+                })
+                .limit(3) // Check last 3 sessions
+                .collect(Collectors.toList());
+
+            for (TerminalSessionMetadata session : recent) {
+                List<String> anomalyReasons = new ArrayList<>();
+
+                // Check command count anomaly
+                try {
+                    var cmds = commandService.getCommandsBySessionId(session.getId());
+                    int cmdCount = cmds != null ? cmds.size() : 0;
+                    if (stdDevCommands > 0 && Math.abs(cmdCount - meanCommands) > deviationThreshold * stdDevCommands) {
+                        anomalyReasons.add(String.format("Unusual command count: %d (baseline: %.0f ± %.0f)",
+                            cmdCount, meanCommands, stdDevCommands));
+                    }
+                } catch (Exception e) {
+                    // skip
+                }
+
+                // Check time of day anomaly
+                if (session.getStartTime() != null && stdDevHour > 0) {
+                    double hour = session.getStartTime().toLocalDateTime().getHour();
+                    if (Math.abs(hour - meanHour) > deviationThreshold * stdDevHour) {
+                        anomalyReasons.add(String.format("Unusual access time: %d:00 (baseline: %.0f:00 ± %.0f hours)",
+                            (int) hour, meanHour, stdDevHour));
+                    }
+                }
+
+                // Check host anomaly - is this a host the user rarely connects to?
+                if (session.getHostSystem() != null) {
+                    String host = session.getHostSystem().getHost();
+                    long hostCount = userSessions.stream()
+                        .filter(s -> s.getHostSystem() != null && s.getHostSystem().getHost().equals(host))
+                        .count();
+                    if (hostCount == 1 && userSessions.size() > 10) {
+                        anomalyReasons.add(String.format("First-time access to host: %s", host));
+                    }
+                }
+
+                if (!anomalyReasons.isEmpty()) {
+                    try {
+                        String sessionNodeId = "session:" + session.getSessionLog().getId();
+
+                        // Find the user's routine for this host (if any)
+                        String host = session.getHostSystem() != null ? session.getHostSystem().getHost() : "unknown";
+                        String routineId = "routine:" + sanitizeId(username + "-" + host);
+
+                        // Create DEVIATES_FROM relationship
+                        knowledgeGraphService.createRelationship(sessionNodeId, routineId,
+                            "DEVIATES_FROM", 0.8, "behavioral-pattern-agent");
+
+                        anomaliesDetected++;
+                        log.info("Anomaly detected for user {} in session {}: {}",
+                            username, session.getId(), String.join("; ", anomalyReasons));
+
+                    } catch (Exception e) {
+                        log.debug("Failed to create anomaly relationship: {}", e.getMessage());
+                    }
+                }
+            }
+        }
+
+        return anomaliesDetected;
+    }
+
+    // ========================================================================
+    // Phase 6: DRI Role Profile Building
+    // ========================================================================
+
+    private int buildRoleProfiles() {
+        List<TerminalSessionMetadata> sessions = sessionMetadataService.getSessionsByState("PROCESSED");
+        if (sessions.isEmpty()) return 0;
+
+        // Group by user to build profiles
+        Map<String, List<TerminalSessionMetadata>> byUser = sessions.stream()
+            .filter(s -> s.getUser() != null)
+            .collect(Collectors.groupingBy(s -> s.getUser().getUsername()));
+
+        int profilesUpdated = 0;
+
+        for (Map.Entry<String, List<TerminalSessionMetadata>> entry : byUser.entrySet()) {
+            String username = entry.getKey();
+            List<TerminalSessionMetadata> userSessions = entry.getValue();
+            if (userSessions.size() < 3) continue; // Need enough history
+
+            try {
+                // Determine systems this user operates
+                Set<String> systems = userSessions.stream()
+                    .filter(s -> s.getHostSystem() != null)
+                    .map(s -> s.getHostSystem().getHost())
+                    .collect(Collectors.toSet());
+
+                // Determine typical working hours
+                DoubleSummaryStatistics hourStats = userSessions.stream()
+                    .filter(s -> s.getStartTime() != null)
+                    .map(s -> (double) s.getStartTime().toLocalDateTime().getHour())
+                    .collect(Collectors.summarizingDouble(Double::doubleValue));
+
+                // Count sessions per system for ownership weight
+                Map<String, Long> systemCounts = userSessions.stream()
+                    .filter(s -> s.getHostSystem() != null)
+                    .collect(Collectors.groupingBy(
+                        s -> s.getHostSystem().getHost(), Collectors.counting()));
+
+                String profileId = "role_profile:" + sanitizeId(username);
+                Map<String, Object> properties = new HashMap<>();
+                properties.put("username", username);
+                properties.put("systems", new ArrayList<>(systems));
+                properties.put("totalSessions", userSessions.size());
+                properties.put("typicalStartHour", (int) hourStats.getAverage());
+                properties.put("systemSessionCounts", systemCounts);
+
+                KnowledgeGraphNode profileNode = KnowledgeGraphNode.builder()
+                    .id(profileId)
+                    .nodeType("role_profile")
+                    .name("DRI Profile: " + username)
+                    .description(String.format("DRI profile for %s: operates %d systems, %d total sessions",
+                        username, systems.size(), userSessions.size()))
+                    .properties(properties)
+                    .markings("SESSION_DATA")
+                    .createdBy("behavioral-pattern-agent")
+                    .createdAt(LocalDateTime.now())
+                    .updatedAt(LocalDateTime.now())
+                    .tags(Arrays.asList("role_profile", "dri", username))
+                    .build();
+
+                knowledgeGraphService.createNode(profileNode, "behavioral-pattern-agent");
+
+                // Create OWNS relationships to systems (weighted by session count)
+                for (Map.Entry<String, Long> systemEntry : systemCounts.entrySet()) {
+                    String systemNodeId = "system:" + sanitizeId(systemEntry.getKey());
+                    double weight = Math.min(1.0, systemEntry.getValue() / 10.0);
+                    knowledgeGraphService.createRelationship(profileId, systemNodeId,
+                        "OWNS", weight, "behavioral-pattern-agent");
+                }
+
+                // Link profile to user
+                String userNodeId = "user:" + sanitizeId(username);
+                knowledgeGraphService.createRelationship(userNodeId, profileId,
+                    "HAS_PROFILE", 1.0, "behavioral-pattern-agent");
+
+                profilesUpdated++;
+
+            } catch (Exception e) {
+                log.warn("Failed to build role profile for {}: {}", username, e.getMessage());
+            }
+        }
+
+        return profilesUpdated;
+    }
+
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+
+    private boolean isEnabled() {
+        return systemOptions.behavioralPatternMiningEnabled != null
+            && systemOptions.behavioralPatternMiningEnabled;
+    }
+
+    private boolean isLLMAvailable() {
+        try {
+            return integrationSecurityTokenService
+                .selectToken(systemOptions.getDefaultLlmProvider())
+                .isPresent();
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
+    private String decodeCommand(String encoded) {
+        try {
+            return new String(Base64.getDecoder().decode(encoded), StandardCharsets.UTF_8);
+        } catch (Exception e) {
+            return "";
+        }
+    }
+
+    private String sanitizeId(String input) {
+        if (input == null) return "unknown";
+        return input.toLowerCase()
+            .replaceAll("[^a-z0-9-]", "-")
+            .replaceAll("-+", "-")
+            .replaceAll("^-|-$", "");
+    }
+
+    private double calculateStdDev(List<Double> values, double mean) {
+        if (values.size() < 2) return 0;
+        double variance = values.stream()
+            .mapToDouble(v -> Math.pow(v - mean, 2))
+            .sum() / (values.size() - 1);
+        return Math.sqrt(variance);
+    }
+
+    private String extractResponseText(JsonNode response) {
+        JsonNode output = response.get("output");
+        if (output != null && output.isArray()) {
+            StringBuilder sb = new StringBuilder();
+            for (JsonNode item : output) {
+                if ("message".equals(item.path("type").asText())) {
+                    for (JsonNode content : item.path("content")) {
+                        if ("output_text".equals(content.path("type").asText())) {
+                            sb.append(content.path("text").asText()).append("\n");
+                        }
+                    }
+                }
+            }
+            return sb.toString().trim();
+        }
+        return "";
+    }
+
+    private void createTaskAudit(String taskExecutionId, String agentType) {
+        try {
+            auditService.createAudit("analytics-agent", taskExecutionId, agentType, "system");
+        } catch (Exception e) {
+            log.debug("Could not create audit for {} task: {}", agentType, e.getMessage());
+        }
+    }
+
+    private void closeTaskAudit(String taskExecutionId, String status) {
+        try {
+            auditService.closeAudit(taskExecutionId, status);
+        } catch (Exception e) {
+            log.debug("Could not close audit for task: {}", e.getMessage());
+        }
+    }
+
+    // Inner class for temporal pattern results
+    private static class TemporalPattern {
+        String schedule;
+        String frequency;
+        String description;
+        double confidence;
+        int peakHour;
+        long avgDurationSeconds;
+    }
+}
diff --git a/analytics/src/main/java/io/sentrius/agent/analysis/agents/documents/DocumentRelationshipAnalyzer.java b/analytics/src/main/java/io/sentrius/agent/analysis/agents/documents/DocumentRelationshipAnalyzer.java
index 45fba17d..c089f1dc 100644
--- a/analytics/src/main/java/io/sentrius/agent/analysis/agents/documents/DocumentRelationshipAnalyzer.java
+++ b/analytics/src/main/java/io/sentrius/agent/analysis/agents/documents/DocumentRelationshipAnalyzer.java
@@ -207,6 +207,18 @@ public DocumentRelationshipAnalyzer(
 
     public void analyzeDocumentRelationships() {
 
+        // Check if LLM analytics is enabled globally
+        if (systemOptions.enableLLMAnalytics != null && !systemOptions.enableLLMAnalytics) {
+            log.debug("LLM analytics disabled globally via enableLLMAnalytics, skipping document relationship analysis");
+            return;
+        }
+
+        // Check if document relationship analysis is enabled specifically
+        if (systemOptions.documentRelationshipAnalysisEnabled != null && !systemOptions.documentRelationshipAnalysisEnabled) {
+            log.debug("Document relationship analysis disabled via documentRelationshipAnalysisEnabled, skipping");
+            return;
+        }
+
         log.info("Starting scheduled document relationship analysis");
 
 
diff --git a/analytics/src/main/java/io/sentrius/agent/analysis/agents/sessions/RdpSessionSummarizationAgent.java b/analytics/src/main/java/io/sentrius/agent/analysis/agents/sessions/RdpSessionSummarizationAgent.java
index 43a661ab..7c0eec5b 100644
--- a/analytics/src/main/java/io/sentrius/agent/analysis/agents/sessions/RdpSessionSummarizationAgent.java
+++ b/analytics/src/main/java/io/sentrius/agent/analysis/agents/sessions/RdpSessionSummarizationAgent.java
@@ -39,6 +39,7 @@ public class RdpSessionSummarizationAgent {
     private final IntegrationSecurityTokenService integrationSecurityTokenService;
     private final LLMService llmService;
     private final AgentExecutionAuditService auditService;
+    private final io.sentrius.sso.core.config.SystemOptions systemOptions;
 
     /**
      * Process RDP sessions with unprocessed screenshots every 2 minutes
@@ -46,6 +47,18 @@ public class RdpSessionSummarizationAgent {
     @Scheduled(fixedDelay = 120000) // 2 minutes
     @Transactional
     public void processRdpSessions() {
+        // Check if LLM analytics is enabled globally
+        if (systemOptions.enableLLMAnalytics != null && !systemOptions.enableLLMAnalytics) {
+            log.debug("LLM analytics disabled globally, skipping RDP session summarization");
+            return;
+        }
+
+        // Check if RDP session summarization is enabled specifically
+        if (systemOptions.rdpSessionSummarizationEnabled != null && !systemOptions.rdpSessionSummarizationEnabled) {
+            log.debug("RDP session summarization disabled via rdpSessionSummarizationEnabled, skipping");
+            return;
+        }
+
         // Check if OpenAI integration is available
         if (!isLLMAvailable()) {
             log.debug("LLM integration not available, skipping RDP session summarization");
diff --git a/analytics/src/main/java/io/sentrius/agent/analysis/agents/sessions/SshSessionSummarizationAgent.java b/analytics/src/main/java/io/sentrius/agent/analysis/agents/sessions/SshSessionSummarizationAgent.java
index 1c4e9962..7b6188d7 100644
--- a/analytics/src/main/java/io/sentrius/agent/analysis/agents/sessions/SshSessionSummarizationAgent.java
+++ b/analytics/src/main/java/io/sentrius/agent/analysis/agents/sessions/SshSessionSummarizationAgent.java
@@ -1,13 +1,17 @@
 package io.sentrius.agent.analysis.agents.sessions;
 
+import com.fasterxml.jackson.databind.JsonNode;
+import io.sentrius.sso.core.dto.ztat.TokenDTO;
 import io.sentrius.sso.core.model.sessions.SessionLog;
 import io.sentrius.sso.core.model.sessions.SshSessionSummary;
 import io.sentrius.sso.core.model.sessions.TerminalLogs;
 import io.sentrius.sso.core.repository.SessionLogRepository;
 import io.sentrius.sso.core.repository.SshSessionSummaryRepository;
 import io.sentrius.sso.core.repository.TerminalLogsRepository;
+import io.sentrius.sso.core.services.agents.LLMService;
 import io.sentrius.sso.core.services.security.IntegrationSecurityTokenService;
 import io.sentrius.sso.core.services.agents.AgentExecutionAuditService;
+import io.sentrius.sso.core.utils.JsonUtil;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
@@ -16,7 +20,7 @@
 import org.springframework.transaction.annotation.Transactional;
 
 import java.time.Instant;
-import java.util.List;
+import java.util.*;
 import java.util.stream.Collectors;
 
 /**
@@ -33,7 +37,9 @@ public class SshSessionSummarizationAgent {
     private final TerminalLogsRepository terminalLogsRepository;
     private final SshSessionSummaryRepository summaryRepository;
     private final IntegrationSecurityTokenService integrationSecurityTokenService;
+    private final LLMService llmService;
     private final AgentExecutionAuditService auditService;
+    private final io.sentrius.sso.core.config.SystemOptions systemOptions;
 
     /**
      * Process SSH sessions that have closed and don't have summaries yet - runs every 2 minutes
@@ -41,6 +47,18 @@ public class SshSessionSummarizationAgent {
     @Scheduled(fixedDelay = 120000) // 2 minutes
     @Transactional
     public void processSshSessions() {
+        // Check if LLM analytics is enabled globally
+        if (systemOptions.enableLLMAnalytics != null && !systemOptions.enableLLMAnalytics) {
+            log.debug("LLM analytics disabled globally, skipping SSH session summarization");
+            return;
+        }
+
+        // Check if SSH session summarization is enabled specifically
+        if (systemOptions.sshSessionSummarizationEnabled != null && !systemOptions.sshSessionSummarizationEnabled) {
+            log.debug("SSH session summarization disabled via sshSessionSummarizationEnabled, skipping");
+            return;
+        }
+
         // Check if LLM integration is available
         if (!isLLMAvailable()) {
             log.debug("LLM integration not available, skipping SSH session summarization");
@@ -117,7 +135,12 @@ private void processSession(Long sessionId) {
         
         // Analyze terminal logs
         String sessionAnalysis = analyzeTerminalLogs(sessionId, sessionLog, terminalLogs);
-        
+
+        // Extract commands and key activities for structured fields
+        List<String> commands = extractCommands(terminalLogs);
+        String commandsExecuted = commands.stream().limit(50).collect(Collectors.joining("\n"));
+        String keyActivities = commands.stream().limit(10).collect(Collectors.joining(", "));
+
         // Create summary
         SshSessionSummary summary = SshSessionSummary.builder()
             .sessionId(sessionId)
@@ -126,6 +149,8 @@ private void processSession(Long sessionId) {
             .sessionStart(sessionLog.getSessionTm().toInstant())
             .sessionEnd(Instant.now())
             .summary(sessionAnalysis)
+            .commandsExecuted(commandsExecuted)
+            .keyActivities(keyActivities)
             .terminalLogCount(terminalLogs.size())
             .build();
         
@@ -137,74 +162,176 @@ private void processSession(Long sessionId) {
     }
     
     /**
-     * Analyze terminal logs to generate session summary
+     * Analyze terminal logs to generate session summary.
+     * Uses LLM for rich narrative analysis when available, falls back to structured template.
      */
     private String analyzeTerminalLogs(Long sessionId, SessionLog sessionLog, List<TerminalLogs> terminalLogs) {
         try {
-            // Build analysis summary from terminal logs
-            StringBuilder analysisBuilder = new StringBuilder();
-            analysisBuilder.append("SSH/Terminal Session Analysis Summary\n");
-            analysisBuilder.append("======================================\n\n");
-            analysisBuilder.append("Session ID: ").append(sessionId).append("\n");
-            analysisBuilder.append("User: ").append(sessionLog.getUsername()).append("\n");
-            analysisBuilder.append("Target: ").append(sessionLog.getIpAddress()).append("\n\n");
-            
-            analysisBuilder.append("Session Timeline:\n");
-            analysisBuilder.append("-----------------\n");
-            
+            List<String> commands = extractCommands(terminalLogs);
             Instant sessionStart = sessionLog.getSessionTm().toInstant();
-            Instant sessionEnd = terminalLogs.isEmpty() ? Instant.now() : 
+            Instant sessionEnd = terminalLogs.isEmpty() ? Instant.now() :
                 terminalLogs.get(terminalLogs.size() - 1).getLogTm().toInstant();
             long durationSeconds = sessionEnd.getEpochSecond() - sessionStart.getEpochSecond();
-            
-            analysisBuilder.append(String.format("Start: %s\n", sessionStart));
-            analysisBuilder.append(String.format("End: %s\n", sessionEnd));
-            analysisBuilder.append(String.format("Duration: %d seconds (%.2f minutes)\n\n", 
-                durationSeconds, durationSeconds / 60.0));
-            
-            // Extract and analyze commands
-            analysisBuilder.append("Command Activity:\n");
-            analysisBuilder.append("------------------\n");
-            
-            List<String> commands = extractCommands(terminalLogs);
-            analysisBuilder.append("Total command outputs captured: ").append(terminalLogs.size()).append("\n");
-            analysisBuilder.append("Distinct commands detected: ").append(commands.size()).append("\n\n");
-            
-            if (!commands.isEmpty()) {
-                analysisBuilder.append("Key commands executed:\n");
-                int commandCount = 0;
-                for (String command : commands) {
-                    if (commandCount++ >= 20) { // Limit to first 20 commands
-                        analysisBuilder.append("... (").append(commands.size() - 20).append(" more commands)\n");
-                        break;
-                    }
-                    analysisBuilder.append("  - ").append(command).append("\n");
-                }
-            }
-            
-            // Add summary section
-            analysisBuilder.append("\nSession Summary:\n");
-            analysisBuilder.append("----------------\n");
-            analysisBuilder.append(String.format("This SSH session lasted %.2f minutes with %d terminal log entries.\n",
-                durationSeconds / 60.0, terminalLogs.size()));
-            
-            if (commands.isEmpty()) {
-                analysisBuilder.append("Note: No distinct commands extracted from terminal output.\n");
-            } else {
-                analysisBuilder.append(String.format("User executed approximately %d commands during this session.\n", 
-                    commands.size()));
+
+            // Build structured context for both LLM and fallback
+            String sessionContext = buildSessionContext(sessionId, sessionLog, commands, sessionStart, sessionEnd, durationSeconds);
+
+            // Try LLM-powered analysis first
+            String llmAnalysis = getLLMSessionAnalysis(sessionLog, commands, durationSeconds);
+            if (llmAnalysis != null && !llmAnalysis.isEmpty()) {
+                StringBuilder result = new StringBuilder();
+                result.append("SSH/Terminal Session Analysis Summary\n");
+                result.append("======================================\n\n");
+                result.append(sessionContext);
+                result.append("\nAI-Generated Analysis:\n");
+                result.append("----------------------\n");
+                result.append(llmAnalysis).append("\n");
+                return result.toString();
             }
-            
-            // Future enhancement: Call LLM API here when vision capabilities are fully integrated
-            analysisBuilder.append("\nNote: Full LLM-based analysis will be available when integrated with OpenAI API.\n");
-            
-            return analysisBuilder.toString();
-            
+
+            // Graceful fallback to structured template when LLM is unavailable
+            return buildTemplateSummary(sessionId, sessionLog, commands, sessionStart, sessionEnd, durationSeconds, terminalLogs.size());
+
         } catch (Exception e) {
             log.error("Error analyzing terminal logs for session: {}", sessionId, e);
             return "Error during analysis: " + e.getMessage();
         }
     }
+
+    /**
+     * Get LLM-based analysis of SSH session commands and activity.
+     */
+    private String getLLMSessionAnalysis(SessionLog sessionLog, List<String> commands, long durationSeconds) {
+        try {
+            var token = integrationSecurityTokenService.selectToken(systemOptions.getDefaultLlmProvider())
+                .orElse(null);
+            if (token == null) {
+                log.debug("No LLM token available for SSH session analysis");
+                return null;
+            }
+
+            if (commands.isEmpty()) {
+                return null;
+            }
+
+            TokenDTO tokenDTO = TokenDTO.builder()
+                .ztatToken("")
+                .communicationId(UUID.randomUUID().toString())
+                .build();
+
+            // Limit commands sent to LLM for token efficiency
+            List<String> commandsForAnalysis = commands.stream().limit(50).collect(Collectors.toList());
+
+            String prompt = String.format(
+                "Analyze this SSH session and provide a concise security-focused summary.\n\n" +
+                "User: %s\nTarget: %s\nDuration: %d seconds\n\n" +
+                "Commands executed:\n%s\n\n" +
+                "Provide:\n" +
+                "1. A brief description of what the user was doing (1-2 sentences)\n" +
+                "2. Key activities observed\n" +
+                "3. Any security-relevant observations (risky commands, privilege escalation, unusual patterns)\n" +
+                "4. Risk assessment (LOW/MEDIUM/HIGH with brief justification)\n\n" +
+                "Be concise and focus on actionable insights.",
+                sessionLog.getUsername(),
+                sessionLog.getIpAddress(),
+                durationSeconds,
+                String.join("\n", commandsForAnalysis)
+            );
+
+            Map<String, Object> payload = Map.of(
+                "model", "gpt-4o-mini",
+                "input", List.of(
+                    Map.of("role", "system", "content", List.of(
+                        Map.of("type", "text", "text",
+                            "You are a security analyst reviewing SSH terminal sessions. " +
+                            "Provide concise, actionable summaries focused on what the user accomplished and any security concerns.")
+                    )),
+                    Map.of("role", "user", "content", List.of(
+                        Map.of("type", "text", "text", prompt)
+                    ))
+                ),
+                "temperature", 0.3
+            );
+
+            String raw = llmService.askQuestion(tokenDTO, payload);
+            JsonNode response = JsonUtil.MAPPER.readTree(raw);
+            return extractResponseText(response);
+
+        } catch (io.sentrius.sso.core.exceptions.ZtatException | com.fasterxml.jackson.core.JsonProcessingException e) {
+            log.debug("LLM analysis unavailable for SSH session, using template fallback: {}", e.getMessage());
+            return null;
+        } catch (Exception e) {
+            log.debug("LLM analysis unavailable for SSH session, using template fallback: {}", e.getMessage());
+            return null;
+        }
+    }
+
+    private String extractResponseText(JsonNode response) {
+        JsonNode output = response.get("output");
+        if (output != null && output.isArray()) {
+            StringBuilder sb = new StringBuilder();
+            for (JsonNode item : output) {
+                if ("message".equals(item.path("type").asText())) {
+                    for (JsonNode content : item.path("content")) {
+                        if ("output_text".equals(content.path("type").asText())) {
+                            sb.append(content.path("text").asText()).append("\n");
+                        }
+                    }
+                }
+            }
+            return sb.toString().trim();
+        }
+        return "";
+    }
+
+    private String buildSessionContext(Long sessionId, SessionLog sessionLog, List<String> commands,
+                                       Instant sessionStart, Instant sessionEnd, long durationSeconds) {
+        StringBuilder ctx = new StringBuilder();
+        ctx.append("Session ID: ").append(sessionId).append("\n");
+        ctx.append("User: ").append(sessionLog.getUsername()).append("\n");
+        ctx.append("Target: ").append(sessionLog.getIpAddress()).append("\n");
+        ctx.append(String.format("Duration: %d seconds (%.2f minutes)\n", durationSeconds, durationSeconds / 60.0));
+        ctx.append("Commands detected: ").append(commands.size()).append("\n");
+        return ctx.toString();
+    }
+
+    /**
+     * Fallback structured template when LLM is unavailable.
+     */
+    private String buildTemplateSummary(Long sessionId, SessionLog sessionLog, List<String> commands,
+                                        Instant sessionStart, Instant sessionEnd, long durationSeconds, int logCount) {
+        StringBuilder sb = new StringBuilder();
+        sb.append("SSH/Terminal Session Analysis Summary\n");
+        sb.append("======================================\n\n");
+        sb.append("Session ID: ").append(sessionId).append("\n");
+        sb.append("User: ").append(sessionLog.getUsername()).append("\n");
+        sb.append("Target: ").append(sessionLog.getIpAddress()).append("\n\n");
+
+        sb.append("Session Timeline:\n-----------------\n");
+        sb.append(String.format("Start: %s\nEnd: %s\n", sessionStart, sessionEnd));
+        sb.append(String.format("Duration: %d seconds (%.2f minutes)\n\n", durationSeconds, durationSeconds / 60.0));
+
+        sb.append("Command Activity:\n------------------\n");
+        sb.append("Total command outputs captured: ").append(logCount).append("\n");
+        sb.append("Distinct commands detected: ").append(commands.size()).append("\n\n");
+
+        if (!commands.isEmpty()) {
+            sb.append("Key commands executed:\n");
+            int count = 0;
+            for (String command : commands) {
+                if (count++ >= 20) {
+                    sb.append("... (").append(commands.size() - 20).append(" more commands)\n");
+                    break;
+                }
+                sb.append("  - ").append(command).append("\n");
+            }
+        }
+
+        sb.append(String.format("\nThis SSH session lasted %.2f minutes with %d terminal log entries.\n",
+            durationSeconds / 60.0, logCount));
+
+        return sb.toString();
+    }
     
     /**
      * Extract commands from terminal logs
diff --git a/analytics/src/main/java/io/sentrius/agent/analysis/agents/trust/TrustEvaluationService.java b/analytics/src/main/java/io/sentrius/agent/analysis/agents/trust/TrustEvaluationService.java
index eb639467..1c16d9f2 100644
--- a/analytics/src/main/java/io/sentrius/agent/analysis/agents/trust/TrustEvaluationService.java
+++ b/analytics/src/main/java/io/sentrius/agent/analysis/agents/trust/TrustEvaluationService.java
@@ -9,8 +9,11 @@
 import io.sentrius.sso.core.repository.AgentCommunicationRepository;
 import io.sentrius.sso.core.repository.AgentHeartbeatRepository;
 import io.sentrius.sso.core.repository.SessionLogRepository;
+import io.sentrius.sso.core.repository.SshSessionSummaryRepository;
 import io.sentrius.sso.core.services.ATPLPolicyService;
 import io.sentrius.sso.core.services.UserService;
+import io.sentrius.sso.core.services.metadata.TerminalCommandService;
+import io.sentrius.sso.core.services.agents.AgentExecutionAuditService;
 import io.sentrius.sso.core.services.trust.AgentTrustScoreService;
 import io.sentrius.sso.core.services.trust.PolicyViolationEventService;
 import io.sentrius.sso.core.trust.*;
@@ -18,11 +21,14 @@
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.data.domain.PageRequest;
 import org.springframework.scheduling.annotation.Scheduled;
 import org.springframework.stereotype.Service;
 
 import java.sql.Timestamp;
+import java.time.Instant;
 import java.time.LocalDateTime;
+import java.time.temporal.ChronoUnit;
 import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.stream.Collectors;
@@ -41,10 +47,14 @@ public class TrustEvaluationService {
     private final LLMGuidedSchedulerService llmScheduler;
     private final io.sentrius.sso.core.services.feedback.RLHFFeedbackService rlhfFeedbackService;
     private final PolicyViolationEventService policyViolationEventService;
-    
+    private final io.sentrius.sso.core.config.SystemOptions systemOptions;
+    private final SshSessionSummaryRepository sshSessionSummaryRepository;
+    private final TerminalCommandService terminalCommandService;
+    private final AgentExecutionAuditService agentAuditService;
+
     private final Map<String, List<ProvenanceEvent>> provenanceCache = new ConcurrentHashMap<>();
     private final Map<String, Integer> incidentTracker = new ConcurrentHashMap<>();
-    
+
     @Autowired
     public TrustEvaluationService(
             AgentHeartbeatRepository heartbeatRepository,
@@ -55,7 +65,11 @@ public TrustEvaluationService(
             UserService userService,
             @Autowired(required = false) LLMGuidedSchedulerService llmScheduler,
             @Autowired(required = false) io.sentrius.sso.core.services.feedback.RLHFFeedbackService rlhfFeedbackService,
-            @Autowired(required = false) PolicyViolationEventService policyViolationEventService) {
+            @Autowired(required = false) PolicyViolationEventService policyViolationEventService,
+            io.sentrius.sso.core.config.SystemOptions systemOptions,
+            @Autowired(required = false) SshSessionSummaryRepository sshSessionSummaryRepository,
+            @Autowired(required = false) TerminalCommandService terminalCommandService,
+            @Autowired(required = false) AgentExecutionAuditService agentAuditService) {
         this.heartbeatRepository = heartbeatRepository;
         this.communicationRepository = communicationRepository;
         this.sessionLogRepository = sessionLogRepository;
@@ -65,12 +79,16 @@ public TrustEvaluationService(
         this.llmScheduler = llmScheduler;
         this.rlhfFeedbackService = rlhfFeedbackService;
         this.policyViolationEventService = policyViolationEventService;
+        this.systemOptions = systemOptions;
+        this.sshSessionSummaryRepository = sshSessionSummaryRepository;
+        this.terminalCommandService = terminalCommandService;
+        this.agentAuditService = agentAuditService;
     }
     
     @Scheduled(fixedRate = 300000, initialDelay = 60000)
     public void evaluateAllAgentsAndUsers() {
-        // Check with LLM if evaluation should run now
-        if (llmScheduler != null && llmScheduler.isEnabled()) {
+        // Check with LLM if evaluation should run now (only if LLM guidance is enabled)
+        if (llmScheduler != null && llmScheduler.isEnabled() && isLLMGuidanceEnabled()) {
             llmScheduler.shouldRunTrustEvaluation().thenAccept(shouldRun -> {
                 if (shouldRun) {
                     log.info("LLM recommended running trust evaluation");
@@ -84,11 +102,29 @@ public void evaluateAllAgentsAndUsers() {
                 return null;
             });
         } else {
-            // No LLM guidance available, run as normal
+            // No LLM guidance available or disabled, run as normal
             performEvaluation();
         }
     }
-    
+
+    /**
+     * Check if LLM guidance for trust evaluation is enabled via SystemOptions.
+     * This allows disabling LLM token consumption for trust evaluation while still running evaluations.
+     */
+    private boolean isLLMGuidanceEnabled() {
+        // Check master LLM analytics flag first
+        if (systemOptions.enableLLMAnalytics != null && !systemOptions.enableLLMAnalytics) {
+            log.debug("LLM analytics disabled globally");
+            return false;
+        }
+        // Check trust evaluation specific flag
+        if (systemOptions.trustEvaluationLLMGuidanceEnabled != null && !systemOptions.trustEvaluationLLMGuidanceEnabled) {
+            log.debug("Trust evaluation LLM guidance disabled");
+            return false;
+        }
+        return true;
+    }
+
     private void performEvaluation() {
         log.info("Starting scheduled trust evaluation for all agents and users");
         
@@ -193,18 +229,44 @@ private AgentContext buildEntityContext(String entityId, String entityName, Iden
     private AgentContext buildHumanUserContext(String userId, String username) {
         // For human users, we track sessions instead of heartbeats
         List<SessionLog> userSessions = sessionLogRepository.findByUsername(username);
-        
+
         int priorRuns = calculatePriorSessions(userSessions);
         int incidentCount = getIncidentCount(userId);
-        
+
         // Human users are verified through Keycloak authentication
         List<ProvenanceEvent> events = provenanceCache.getOrDefault(userId, Collections.emptyList());
         String identityIssuer = "keycloak"; // Always verified for authenticated users
-        
+
         // Enclave verification doesn't apply to human users, but we can consider
         // if they're accessing from a secure/verified location
         boolean enclaveVerified = false; // Could be enhanced with IP/location verification
-        
+
+        // Evaluate provenance trail completeness
+        boolean hasAuditTrail = !userSessions.isEmpty();
+        boolean hasCommandsCaptured = false;
+        boolean hasSessionSummary = false;
+
+        if (!userSessions.isEmpty() && terminalCommandService != null) {
+            // Check if recent sessions have captured commands
+            hasCommandsCaptured = userSessions.stream()
+                .limit(5) // Check last 5 sessions for efficiency
+                .anyMatch(s -> {
+                    try {
+                        var commands = terminalCommandService.getCommandsBySessionId(s.getId());
+                        return commands != null && !commands.isEmpty();
+                    } catch (Exception e) {
+                        return false;
+                    }
+                });
+        }
+
+        if (!userSessions.isEmpty() && sshSessionSummaryRepository != null) {
+            // Check if any sessions have been summarized
+            hasSessionSummary = userSessions.stream()
+                .limit(5)
+                .anyMatch(s -> sshSessionSummaryRepository.findBySessionId(s.getId()).isPresent());
+        }
+
         return AgentContext.builder()
             .agentId(userId)
             .tags(extractUserTags(username))
@@ -212,6 +274,10 @@ private AgentContext buildHumanUserContext(String userId, String username) {
             .enclaveVerified(enclaveVerified)
             .priorRuns(priorRuns)
             .incidentCount(incidentCount)
+            .hasAuditTrail(hasAuditTrail)
+            .hasCommandsCaptured(hasCommandsCaptured)
+            .hasSessionSummary(hasSessionSummary)
+            .provenanceEventCount(events.size())
             .build();
     }
     
@@ -237,23 +303,31 @@ private Set<String> extractUserTags(String username) {
     
     private AgentContext buildAgentContext(String agentId, String agentName) {
         Optional<AgentHeartbeat> heartbeatOpt = heartbeatRepository.findByAgentId(agentId);
-        int priorRuns = calculatePriorRuns(agentId);
         int incidentCount = getIncidentCount(agentId);
-        
+
         boolean enclaveVerified = heartbeatOpt
             .map(hb -> hb.getStatus() != null && hb.getStatus().contains("verified"))
             .orElse(false);
-        
-        List<ProvenanceEvent> events = provenanceCache.getOrDefault(agentId, Collections.emptyList());
-        String identityIssuer = events.isEmpty() ? null : "keycloak";
-        
+
+        // Agents with active heartbeats have been authenticated through the platform
+        String identityIssuer = heartbeatOpt.isPresent() ? "keycloak" : null;
+
+        // Count actual agent communications in the last 30 days (not heartbeat rows)
+        int priorRuns = countRecentAgentActivity(agentId);
+
         // Calculate RLHF feedback score if service is available
         Double feedbackScore = null;
         if (rlhfFeedbackService != null) {
             feedbackScore = rlhfFeedbackService.calculateFeedbackScore(agentId);
             log.debug("RLHF feedback score for agent {}: {}", agentId, feedbackScore);
         }
-        
+
+        // Build provenance from actual persistent data instead of ephemeral in-memory cache
+        boolean hasAuditTrail = heartbeatOpt.isPresent();
+        boolean hasCommandsCaptured = priorRuns > 0;
+        boolean hasSessionSummary = hasCompletedAuditsWithSummaries(agentId);
+        int provenanceEventCount = priorRuns;
+
         return AgentContext.builder()
             .agentId(agentId)
             .tags(extractTags(agentName))
@@ -262,6 +336,10 @@ private AgentContext buildAgentContext(String agentId, String agentName) {
             .priorRuns(priorRuns)
             .incidentCount(incidentCount)
             .feedbackScore(feedbackScore)
+            .hasAuditTrail(hasAuditTrail)
+            .hasCommandsCaptured(hasCommandsCaptured)
+            .hasSessionSummary(hasSessionSummary)
+            .provenanceEventCount(provenanceEventCount)
             .build();
     }
     
@@ -278,12 +356,50 @@ private int getIncidentCount(String entityId) {
         return incidentTracker.getOrDefault(entityId, 0);
     }
     
-    private int calculatePriorRuns(String agentId) {
-        LocalDateTime thirtyDaysAgo = LocalDateTime.now().minusDays(30);
-        return (int) heartbeatRepository.findAll().stream()
-            .filter(hb -> hb.getAgentId().equals(agentId))
-            .filter(hb -> hb.getLastHeartbeat() != null && hb.getLastHeartbeat().isAfter(thirtyDaysAgo))
-            .count();
+    /**
+     * Count actual agent activity (communications) in the last 30 days.
+     * Falls back to heartbeat-based count if communication data is unavailable.
+     */
+    private int countRecentAgentActivity(String agentId) {
+        try {
+            Instant thirtyDaysAgo = Instant.now().minus(30, ChronoUnit.DAYS);
+            var recentComms = communicationRepository.findBySourceAgentAndCreatedAtBetween(
+                agentId, thirtyDaysAgo, Instant.now(), PageRequest.of(0, 1));
+            int commCount = (int) recentComms.getTotalElements();
+            if (commCount > 0) {
+                return commCount;
+            }
+        } catch (Exception e) {
+            log.debug("Could not count agent communications for {}: {}", agentId, e.getMessage());
+        }
+        // Fall back: count execution audits if available
+        if (agentAuditService != null) {
+            try {
+                var audits = agentAuditService.getAuditsByAgentId(agentId);
+                if (audits != null && !audits.isEmpty()) {
+                    return audits.size();
+                }
+            } catch (Exception e) {
+                log.debug("Could not count agent audits for {}: {}", agentId, e.getMessage());
+            }
+        }
+        return 0;
+    }
+
+    /**
+     * Check if an agent has completed execution audits with summaries.
+     * This indicates the full processing pipeline has run for this agent.
+     */
+    private boolean hasCompletedAuditsWithSummaries(String agentId) {
+        if (agentAuditService == null) return false;
+        try {
+            var audits = agentAuditService.getAuditsByAgentId(agentId);
+            return audits != null && audits.stream()
+                .anyMatch(a -> "COMPLETED".equals(a.getStatus()) && a.getSummary() != null);
+        } catch (Exception e) {
+            log.debug("Could not check agent audits for {}: {}", agentId, e.getMessage());
+            return false;
+        }
     }
     
     private Set<String> extractTags(String agentName) {
diff --git a/analytics/src/main/resources/application.properties b/analytics/src/main/resources/application.properties
index b005f23f..c757b6be 100644
--- a/analytics/src/main/resources/application.properties
+++ b/analytics/src/main/resources/application.properties
@@ -65,6 +65,8 @@ agents.session-analytics.enabled=true
 agents.ssh-session-analytics.enabled=true
 agents.rdp-session-analytics.enabled=true
 agents.agent-execution-analytics.enabled=true
+agents.behavioral-pattern.enabled=true
+agents.automation-suggestion.enabled=true
 
 management.endpoints.web.exposure.include=health
 management.endpoint.health.show-details=always
diff --git a/api/src/main/java/io/sentrius/sso/controllers/api/AuditApiController.java b/api/src/main/java/io/sentrius/sso/controllers/api/AuditApiController.java
index 3d792a81..ee237b35 100644
--- a/api/src/main/java/io/sentrius/sso/controllers/api/AuditApiController.java
+++ b/api/src/main/java/io/sentrius/sso/controllers/api/AuditApiController.java
@@ -29,11 +29,14 @@
 import io.sentrius.sso.core.services.security.KeycloakService;
 import io.sentrius.sso.core.services.terminal.SessionTrackingService;
 import io.sentrius.sso.core.services.agents.AgentExecutionAuditService;
+import io.sentrius.sso.core.services.agents.AgentForensicsService;
 import io.sentrius.sso.core.dto.agents.AgentExecutionAuditDTO;
 import io.sentrius.sso.core.model.agents.AgentExecutionAudit;
+import java.time.Instant;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpEntity;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpMethod;
@@ -58,6 +61,9 @@ public class AuditApiController extends BaseController {
     private final SshSessionSummaryRepository sshSessionSummaryRepository;
     private final AgentExecutionAuditService agentExecutionAuditService;
 
+    @Autowired(required = false)
+    private AgentForensicsService agentForensicsService;
+
     private WebClient webClient;
 
     public AuditApiController(
@@ -402,6 +408,104 @@ public ResponseEntity<Map<String, Object>> consolidateAgentExecutionAudits(
         ));
     }
 
+    // ========================================================================
+    // Agent Forensics endpoints
+    // ========================================================================
+
+    /**
+     * Get full forensics trace for a single agent execution.
+     * Assembles execution metadata, communications, ABAC-filtered memories,
+     * knowledge graph context, and a unified timeline.
+     */
+    @GetMapping("/agents/audit/forensics/trace")
+    @LimitAccess(applicationAccess = {ApplicationAccessEnum.CAN_LOG_IN})
+    public ResponseEntity<AgentForensicsService.ForensicsTrace> getForensicsTrace(
+        @RequestParam String executionId,
+        @RequestParam(defaultValue = "false") boolean includePodLogs,
+        @RequestParam(defaultValue = "200") int maxCommunications,
+        @RequestParam(defaultValue = "500") int maxPodLogLines,
+        HttpServletRequest request
+    ) {
+        if (agentForensicsService == null) {
+            return ResponseEntity.status(503).build();
+        }
+        String userId = getCurrentUsername(request);
+        AgentForensicsService.ForensicsTrace trace = agentForensicsService.getForensicsTrace(
+                executionId, userId, includePodLogs, maxCommunications, maxPodLogLines);
+        if (trace == null) {
+            return ResponseEntity.notFound().build();
+        }
+        return ResponseEntity.ok(trace);
+    }
+
+    /**
+     * List forensic summaries for an agent within a time range.
+     */
+    @GetMapping("/agents/audit/forensics/by-agent")
+    @LimitAccess(applicationAccess = {ApplicationAccessEnum.CAN_LOG_IN})
+    public ResponseEntity<List<AgentForensicsService.ForensicsSummary>> getForensicsByAgent(
+        @RequestParam String agentId,
+        @RequestParam String startTime,
+        @RequestParam String endTime,
+        HttpServletRequest request
+    ) {
+        if (agentForensicsService == null) {
+            return ResponseEntity.status(503).build();
+        }
+        String userId = getCurrentUsername(request);
+        List<AgentForensicsService.ForensicsSummary> summaries = agentForensicsService.getForensicsByAgentAndTimeRange(
+                agentId, Instant.parse(startTime), Instant.parse(endTime), userId);
+        return ResponseEntity.ok(summaries);
+    }
+
+    /**
+     * List forensic summaries for executions triggered by a given user.
+     */
+    @GetMapping("/agents/audit/forensics/by-user")
+    @LimitAccess(applicationAccess = {ApplicationAccessEnum.CAN_LOG_IN})
+    public ResponseEntity<List<AgentForensicsService.ForensicsSummary>> getForensicsByUser(
+        @RequestParam String username,
+        @RequestParam(defaultValue = "50") int limit,
+        HttpServletRequest request
+    ) {
+        if (agentForensicsService == null) {
+            return ResponseEntity.status(503).build();
+        }
+        String userId = getCurrentUsername(request);
+        List<AgentForensicsService.ForensicsSummary> summaries = agentForensicsService.getForensicsByUser(
+                username, userId, limit);
+        return ResponseEntity.ok(summaries);
+    }
+
+    /**
+     * Get the flat chronological timeline for an agent execution.
+     */
+    @GetMapping("/agents/audit/forensics/timeline")
+    @LimitAccess(applicationAccess = {ApplicationAccessEnum.CAN_LOG_IN})
+    public ResponseEntity<List<AgentForensicsService.TimelineEvent>> getForensicsTimeline(
+        @RequestParam String executionId,
+        HttpServletRequest request
+    ) {
+        if (agentForensicsService == null) {
+            return ResponseEntity.status(503).build();
+        }
+        String userId = getCurrentUsername(request);
+        List<AgentForensicsService.TimelineEvent> timeline = agentForensicsService.getTimeline(executionId, userId);
+        if (timeline.isEmpty()) {
+            // Distinguish "execution not found" from "empty timeline"
+            var auditOpt = agentForensicsService.getForensicsTrace(executionId, userId, false, 0, 0);
+            if (auditOpt == null) {
+                return ResponseEntity.notFound().build();
+            }
+        }
+        return ResponseEntity.ok(timeline);
+    }
+
+    private String getCurrentUsername(HttpServletRequest request) {
+        var principal = request.getUserPrincipal();
+        return principal != null ? principal.getName() : null;
+    }
+
     /**
      * Convert AgentExecutionAudit entity to DTO
      */
diff --git a/api/src/main/java/io/sentrius/sso/controllers/api/DeploymentEnvironmentController.java b/api/src/main/java/io/sentrius/sso/controllers/api/DeploymentEnvironmentController.java
new file mode 100644
index 00000000..035fd8af
--- /dev/null
+++ b/api/src/main/java/io/sentrius/sso/controllers/api/DeploymentEnvironmentController.java
@@ -0,0 +1,112 @@
+package io.sentrius.sso.controllers.api;
+
+import io.sentrius.sso.core.annotations.LimitAccess;
+import io.sentrius.sso.core.model.DeploymentEnvironment;
+import io.sentrius.sso.core.model.security.enums.ApplicationAccessEnum;
+import io.sentrius.sso.core.services.DeploymentEnvironmentService;
+import io.sentrius.sso.core.services.DeploymentEnvironmentService.TopologyGraph;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.List;
+import java.util.NoSuchElementException;
+
+/**
+ * REST API controller for managing deployment environments and topology visualization.
+ */
+@Slf4j
+@RestController
+@RequestMapping("/api/v1/environments")
+public class DeploymentEnvironmentController {
+
+    private final DeploymentEnvironmentService environmentService;
+
+    public DeploymentEnvironmentController(DeploymentEnvironmentService environmentService) {
+        this.environmentService = environmentService;
+    }
+
+    /**
+     * List all deployment environments.
+     */
+    @GetMapping
+    public ResponseEntity<List<DeploymentEnvironment>> listAll() {
+        return ResponseEntity.ok(environmentService.listAll());
+    }
+
+    /**
+     * Get a single deployment environment by name.
+     */
+    @GetMapping("/{name}")
+    public ResponseEntity<DeploymentEnvironment> getByName(@PathVariable String name) {
+        return environmentService.getByName(name)
+                .map(ResponseEntity::ok)
+                .orElse(ResponseEntity.notFound().build());
+    }
+
+    /**
+     * Create a new deployment environment.
+     */
+    @PostMapping
+    @LimitAccess(applicationAccess = {ApplicationAccessEnum.CAN_MANAGE_APPLICATION})
+    public ResponseEntity<DeploymentEnvironment> create(@RequestBody DeploymentEnvironment env) {
+        try {
+            DeploymentEnvironment created = environmentService.getOrCreateEnvironment(
+                    env.getName(), env.getProvider(), env.getRegion(),
+                    env.getZone(), env.getClusterName());
+            // Set additional fields not covered by getOrCreate
+            if (env.getDisplayName() != null) created.setDisplayName(env.getDisplayName());
+            if (env.getEndpoint() != null) created.setEndpoint(env.getEndpoint());
+            if (env.getMetadata() != null) created.setMetadata(env.getMetadata());
+            created = environmentService.update(created.getName(), created);
+            return ResponseEntity.status(HttpStatus.CREATED).body(created);
+        } catch (Exception e) {
+            log.error("Failed to create environment: {}", e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
+        }
+    }
+
+    /**
+     * Update an existing deployment environment (partial update).
+     */
+    @PutMapping("/{name}")
+    @LimitAccess(applicationAccess = {ApplicationAccessEnum.CAN_MANAGE_APPLICATION})
+    public ResponseEntity<DeploymentEnvironment> update(
+            @PathVariable String name,
+            @RequestBody DeploymentEnvironment partial) {
+        try {
+            DeploymentEnvironment updated = environmentService.update(name, partial);
+            return ResponseEntity.ok(updated);
+        } catch (NoSuchElementException e) {
+            return ResponseEntity.notFound().build();
+        } catch (Exception e) {
+            log.error("Failed to update environment '{}': {}", name, e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
+        }
+    }
+
+    /**
+     * Delete a deployment environment by name.
+     */
+    @DeleteMapping("/{name}")
+    @LimitAccess(applicationAccess = {ApplicationAccessEnum.CAN_MANAGE_APPLICATION})
+    public ResponseEntity<Void> delete(@PathVariable String name) {
+        environmentService.delete(name);
+        return ResponseEntity.noContent().build();
+    }
+
+    /**
+     * Get the full topology graph for visualization (environments, host groups, hosts, agents).
+     */
+    @GetMapping("/topology")
+    public ResponseEntity<TopologyGraph> getTopology() {
+        try {
+            TopologyGraph graph = environmentService.getTopologyData();
+            return ResponseEntity.ok(graph);
+        } catch (Exception e) {
+            log.error("Failed to build topology graph: {}", e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
+        }
+    }
+}
diff --git a/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java b/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java
index 0e9cedf9..6d4ae3fa 100644
--- a/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java
+++ b/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java
@@ -1,6 +1,7 @@
 package io.sentrius.sso.controllers.api.documents;
 
 import io.sentrius.sso.core.model.documents.*;
+import io.sentrius.sso.core.services.documents.DriLifecycleService;
 import io.sentrius.sso.core.services.documents.KnowledgeGraphService;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -24,10 +25,14 @@
 public class KnowledgeGraphController {
     
     private final KnowledgeGraphService knowledgeGraphService;
-    
+    private final DriLifecycleService driLifecycleService;
+
     @Autowired
-    public KnowledgeGraphController(@Autowired(required = false) KnowledgeGraphService knowledgeGraphService) {
+    public KnowledgeGraphController(
+            @Autowired(required = false) KnowledgeGraphService knowledgeGraphService,
+            @Autowired(required = false) DriLifecycleService driLifecycleService) {
         this.knowledgeGraphService = knowledgeGraphService;
+        this.driLifecycleService = driLifecycleService;
         if (knowledgeGraphService == null) {
             log.warn("KnowledgeGraphController initialized without KnowledgeGraphService - SurrealDB may not be configured");
         } else {
@@ -448,4 +453,125 @@ public ResponseEntity<Map<String, Object>> getRelationshipsForNodes(
             return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
         }
     }
+
+    // ========================================================================
+    // DRI Lifecycle Endpoints
+    // ========================================================================
+
+    /**
+     * Get the "Life of a DRI" view for a user.
+     * Returns routines, workflows, incidents, systems, collaborators, and runbooks.
+     */
+    @GetMapping("/dri/{username}")
+    public ResponseEntity<?> getDriLifecycle(
+            @PathVariable String username,
+            Authentication authentication) {
+
+        log.info("GET /api/v1/knowledge-graph/dri/{} - DRI lifecycle request", username);
+
+        if (driLifecycleService == null) {
+            return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
+                .body(Map.of("error", "DRI lifecycle service not available"));
+        }
+
+        try {
+            DriLifecycleService.DriLifecycleView view = driLifecycleService.getDriLifecycle(username);
+            if (view == null) {
+                return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
+                    .body(Map.of("error", "Knowledge graph not available"));
+            }
+            return ResponseEntity.ok(view);
+        } catch (Exception e) {
+            log.error("Failed to get DRI lifecycle for {}: {}", username, e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(Map.of("error", "Failed to get DRI lifecycle: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Transfer patterns from a previous DRI to a new DRI.
+     * Used for onboarding when responsibility for systems changes hands.
+     */
+    @PostMapping("/dri/transfer")
+    public ResponseEntity<?> transferDriPatterns(
+            @RequestBody Map<String, Object> request,
+            Authentication authentication) {
+
+        String previousDri = (String) request.get("previousDri");
+        String newDri = (String) request.get("newDri");
+        @SuppressWarnings("unchecked")
+        List<String> systems = (List<String>) request.get("systems");
+
+        log.info("POST /api/v1/knowledge-graph/dri/transfer - Transfer from {} to {}", previousDri, newDri);
+
+        if (driLifecycleService == null) {
+            return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
+                .body(Map.of("error", "DRI lifecycle service not available"));
+        }
+
+        if (previousDri == null || newDri == null) {
+            return ResponseEntity.badRequest()
+                .body(Map.of("error", "previousDri and newDri are required"));
+        }
+
+        try {
+            DriLifecycleService.OnboardingPackage pkg =
+                driLifecycleService.transferPatterns(previousDri, newDri, systems);
+            return ResponseEntity.ok(pkg);
+        } catch (Exception e) {
+            log.error("Failed to transfer patterns from {} to {}: {}", previousDri, newDri, e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(Map.of("error", "Failed to transfer patterns: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Find DRIs/owners responsible for a given system.
+     */
+    @GetMapping("/dri/system/{systemHost}/owners")
+    public ResponseEntity<?> findSystemOwners(
+            @PathVariable String systemHost,
+            Authentication authentication) {
+
+        log.info("GET /api/v1/knowledge-graph/dri/system/{}/owners", systemHost);
+
+        if (driLifecycleService == null) {
+            return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
+                .body(Map.of("error", "DRI lifecycle service not available"));
+        }
+
+        try {
+            List<KnowledgeGraphNode> owners = driLifecycleService.findSystemOwners(systemHost);
+            return ResponseEntity.ok(owners);
+        } catch (Exception e) {
+            log.error("Failed to find owners for system {}: {}", systemHost, e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(Map.of("error", "Failed to find system owners: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Get all runbooks relevant to a specific system.
+     */
+    @GetMapping("/dri/system/{systemHost}/runbooks")
+    public ResponseEntity<?> getSystemRunbooks(
+            @PathVariable String systemHost,
+            Authentication authentication) {
+
+        log.info("GET /api/v1/knowledge-graph/dri/system/{}/runbooks", systemHost);
+
+        if (driLifecycleService == null) {
+            return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
+                .body(Map.of("error", "DRI lifecycle service not available"));
+        }
+
+        try {
+            List<KnowledgeGraphNode> runbooks = driLifecycleService.getSystemRunbooks(systemHost);
+            return ResponseEntity.ok(runbooks);
+        } catch (Exception e) {
+            log.error("Failed to get runbooks for system {}: {}", systemHost, e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(Map.of("error", "Failed to get runbooks: " + e.getMessage()));
+        }
+    }
 }
diff --git a/api/src/main/java/io/sentrius/sso/controllers/view/TopologyViewController.java b/api/src/main/java/io/sentrius/sso/controllers/view/TopologyViewController.java
new file mode 100644
index 00000000..940d75dc
--- /dev/null
+++ b/api/src/main/java/io/sentrius/sso/controllers/view/TopologyViewController.java
@@ -0,0 +1,34 @@
+package io.sentrius.sso.controllers.view;
+
+import io.sentrius.sso.core.config.SystemOptions;
+import io.sentrius.sso.core.controllers.BaseController;
+import io.sentrius.sso.core.services.ErrorOutputService;
+import io.sentrius.sso.core.services.UserService;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Controller;
+import org.springframework.ui.Model;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+
+/**
+ * View controller for the infrastructure topology visualization page.
+ */
+@Slf4j
+@Controller
+@RequestMapping("/sso/v1/topology")
+public class TopologyViewController extends BaseController {
+
+    public TopologyViewController(
+        UserService userService,
+        SystemOptions systemOptions,
+        ErrorOutputService errorOutputService
+    ) {
+        super(userService, systemOptions, errorOutputService);
+    }
+
+    @GetMapping
+    public String topology(Model model) {
+        log.info("Rendering infrastructure topology page");
+        return "sso/topology";
+    }
+}
diff --git a/api/src/main/resources/db/migration/V49__create_deployment_environments.sql b/api/src/main/resources/db/migration/V49__create_deployment_environments.sql
new file mode 100644
index 00000000..c207fa89
--- /dev/null
+++ b/api/src/main/resources/db/migration/V49__create_deployment_environments.sql
@@ -0,0 +1,25 @@
+-- Create deployment_environments table for cross-cloud enclave tracking
+CREATE TABLE IF NOT EXISTS deployment_environments (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    name VARCHAR(255) NOT NULL UNIQUE,
+    display_name VARCHAR(255),
+    provider VARCHAR(50),
+    region VARCHAR(100),
+    zone VARCHAR(100),
+    cluster_name VARCHAR(255),
+    endpoint VARCHAR(500),
+    status VARCHAR(50) NOT NULL DEFAULT 'ACTIVE',
+    last_contact_at TIMESTAMP WITH TIME ZONE,
+    metadata TEXT,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_deployment_env_name ON deployment_environments(name);
+CREATE INDEX idx_deployment_env_provider ON deployment_environments(provider);
+CREATE INDEX idx_deployment_env_status ON deployment_environments(status);
+
+-- Add environment_name to existing tables for cross-environment tracking
+ALTER TABLE agent_execution_audits ADD COLUMN IF NOT EXISTS environment_name VARCHAR(255);
+ALTER TABLE agent_heartbeats ADD COLUMN IF NOT EXISTS environment_name VARCHAR(255);
+ALTER TABLE host_groups ADD COLUMN IF NOT EXISTS environment_name VARCHAR(255);
diff --git a/api/src/main/resources/templates/fragments/sidebar.html b/api/src/main/resources/templates/fragments/sidebar.html
index de592327..a146c0b5 100755
--- a/api/src/main/resources/templates/fragments/sidebar.html
+++ b/api/src/main/resources/templates/fragments/sidebar.html
@@ -35,6 +35,11 @@
                             <i class="fas fa-server"></i> <span class="ms-1 d-none d-sm-inline">Host Enclaves</span>
                         </a>
                     </li>
+                    <li data-ui-resource="infrastructure.topology">
+                        <a href="/sso/v1/topology" class="nav-link px-0 align-middle">
+                            <i class="fas fa-globe"></i> <span class="ms-1 d-none d-sm-inline">Topology</span>
+                        </a>
+                    </li>
                     <li th:if="${uiAccessHelper.check(operatingUser, 'CAN_MANAGE_APPLICATION', '/ui/infrastructure/integrations')}"
                         data-ui-resource="infrastructure.integrations">
                         <a href="/sso/v1/integrations" class="nav-link px-0 align-middle">
diff --git a/api/src/main/resources/templates/sso/topology.html b/api/src/main/resources/templates/sso/topology.html
new file mode 100644
index 00000000..016d9a7f
--- /dev/null
+++ b/api/src/main/resources/templates/sso/topology.html
@@ -0,0 +1,598 @@
+<!DOCTYPE html>
+<html xmlns:th="http://www.thymeleaf.org" class="dark" data-bs-theme="dark">
+<head>
+    <meta th:replace="~{fragments/header}">
+    <title>[[${systemOptions.systemLogoName}]] - Infrastructure Topology</title>
+    <style>
+        .topology-container {
+            max-width: 1600px;
+            margin: 20px auto;
+            background: #1e1e1e;
+            border-radius: 15px;
+            padding: 0;
+            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.8);
+            overflow: hidden;
+        }
+
+        .topo-header {
+            background: linear-gradient(135deg, #2a2a2a 0%, #3a3a3a 100%);
+            padding: 20px;
+            border-bottom: 1px solid #444;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+        }
+
+        .topo-header h2 {
+            color: #ffffff;
+            margin: 0;
+            font-size: 1.8rem;
+            font-weight: 600;
+        }
+
+        .topo-header p {
+            color: #aaa;
+            margin: 4px 0 0 0;
+            font-size: 0.95rem;
+        }
+
+        .topo-stats {
+            display: flex;
+            gap: 20px;
+            align-items: center;
+        }
+
+        .topo-stat {
+            text-align: center;
+            color: #ccc;
+        }
+
+        .topo-stat .stat-value {
+            font-size: 1.4rem;
+            font-weight: 700;
+            color: #4fc3f7;
+        }
+
+        .topo-stat .stat-label {
+            font-size: 0.75rem;
+            text-transform: uppercase;
+            color: #888;
+        }
+
+        .topo-content {
+            display: grid;
+            grid-template-columns: 260px 1fr;
+            gap: 0;
+            height: calc(100vh - 220px);
+        }
+
+        .topo-sidebar {
+            background: #1a1a1a;
+            border-right: 1px solid #444;
+            padding: 20px;
+            overflow-y: auto;
+        }
+
+        .topo-main {
+            background: #252525;
+            position: relative;
+        }
+
+        #topology-canvas {
+            width: 100%;
+            height: 100%;
+        }
+
+        .filter-section {
+            background: #2a2a2a;
+            border-radius: 8px;
+            padding: 15px;
+            margin-bottom: 15px;
+        }
+
+        .filter-section h4 {
+            color: #ccc;
+            font-size: 0.9rem;
+            font-weight: 600;
+            margin-bottom: 10px;
+            text-transform: uppercase;
+            letter-spacing: 0.5px;
+        }
+
+        .filter-checkbox {
+            display: flex;
+            align-items: center;
+            gap: 8px;
+            margin-bottom: 6px;
+            color: #bbb;
+            font-size: 0.85rem;
+            cursor: pointer;
+        }
+
+        .filter-checkbox input[type="checkbox"] {
+            accent-color: #4fc3f7;
+        }
+
+        .legend-item {
+            display: flex;
+            align-items: center;
+            gap: 8px;
+            margin-bottom: 8px;
+            font-size: 0.85rem;
+            color: #bbb;
+        }
+
+        .legend-dot {
+            width: 12px;
+            height: 12px;
+            border-radius: 50%;
+            flex-shrink: 0;
+        }
+
+        .detail-panel {
+            background: #2a2a2a;
+            border-radius: 8px;
+            padding: 15px;
+            margin-top: 15px;
+            display: none;
+        }
+
+        .detail-panel.active {
+            display: block;
+        }
+
+        .detail-panel h4 {
+            color: #4fc3f7;
+            font-size: 0.95rem;
+            margin-bottom: 10px;
+        }
+
+        .detail-row {
+            display: flex;
+            justify-content: space-between;
+            padding: 4px 0;
+            font-size: 0.8rem;
+            border-bottom: 1px solid #333;
+        }
+
+        .detail-row .detail-key {
+            color: #888;
+        }
+
+        .detail-row .detail-value {
+            color: #ddd;
+            text-align: right;
+            max-width: 150px;
+            overflow: hidden;
+            text-overflow: ellipsis;
+            white-space: nowrap;
+        }
+
+        .status-badge {
+            display: inline-block;
+            padding: 2px 8px;
+            border-radius: 10px;
+            font-size: 0.7rem;
+            font-weight: 600;
+            text-transform: uppercase;
+        }
+
+        .status-active { background: #1b5e20; color: #a5d6a7; }
+        .status-degraded { background: #e65100; color: #ffcc80; }
+        .status-unreachable { background: #b71c1c; color: #ef9a9a; }
+        .status-decommissioned { background: #37474f; color: #90a4ae; }
+
+        .refresh-indicator {
+            font-size: 0.75rem;
+            color: #666;
+        }
+
+        .btn-refresh {
+            background: #333;
+            color: #ccc;
+            border: 1px solid #555;
+            padding: 6px 14px;
+            border-radius: 6px;
+            cursor: pointer;
+            font-size: 0.85rem;
+        }
+
+        .btn-refresh:hover {
+            background: #444;
+            color: #fff;
+        }
+    </style>
+</head>
+<body>
+<div class="container-fluid">
+    <div class="row flex-nowrap">
+        <div th:replace="~{fragments/sidebar}" class="col-auto sidebar" style="width: 180px;"></div>
+        <div class="col py-4">
+            <div class="main-content">
+
+<div class="topology-container">
+    <div class="topo-header">
+        <div>
+            <h2>Infrastructure Topology</h2>
+            <p>Cross-cloud view of deployment environments, enclaves, hosts, and agents</p>
+        </div>
+        <div class="topo-stats">
+            <div class="topo-stat">
+                <div class="stat-value" id="env-count">0</div>
+                <div class="stat-label">Environments</div>
+            </div>
+            <div class="topo-stat">
+                <div class="stat-value" id="agent-count">0</div>
+                <div class="stat-label">Agents</div>
+            </div>
+            <div class="topo-stat">
+                <div class="stat-value" id="host-count">0</div>
+                <div class="stat-label">Hosts</div>
+            </div>
+            <div style="text-align: right;">
+                <button class="btn-refresh" onclick="refreshTopology()">Refresh</button>
+                <div class="refresh-indicator" id="last-refresh">--</div>
+            </div>
+        </div>
+    </div>
+
+    <div class="topo-content">
+        <!-- Sidebar: Filters + Legend + Detail -->
+        <div class="topo-sidebar">
+            <div class="filter-section">
+                <h4>Provider Filter</h4>
+                <label class="filter-checkbox">
+                    <input type="checkbox" checked value="GCP" onchange="applyFilters()"> GCP
+                </label>
+                <label class="filter-checkbox">
+                    <input type="checkbox" checked value="AWS" onchange="applyFilters()"> AWS
+                </label>
+                <label class="filter-checkbox">
+                    <input type="checkbox" checked value="AZURE" onchange="applyFilters()"> Azure
+                </label>
+                <label class="filter-checkbox">
+                    <input type="checkbox" checked value="BARE_METAL" onchange="applyFilters()"> Bare Metal
+                </label>
+                <label class="filter-checkbox">
+                    <input type="checkbox" checked value="ON_PREM" onchange="applyFilters()"> On-Prem
+                </label>
+                <label class="filter-checkbox">
+                    <input type="checkbox" checked value="OTHER" onchange="applyFilters()"> Other
+                </label>
+            </div>
+
+            <div class="filter-section">
+                <h4>Status Filter</h4>
+                <label class="filter-checkbox">
+                    <input type="checkbox" checked value="ACTIVE" onchange="applyFilters()"> Active
+                </label>
+                <label class="filter-checkbox">
+                    <input type="checkbox" checked value="DEGRADED" onchange="applyFilters()"> Degraded
+                </label>
+                <label class="filter-checkbox">
+                    <input type="checkbox" checked value="UNREACHABLE" onchange="applyFilters()"> Unreachable
+                </label>
+            </div>
+
+            <div class="filter-section">
+                <h4>Legend</h4>
+                <div class="legend-item">
+                    <div class="legend-dot" style="background: #42a5f5;"></div> Environment (GCP)
+                </div>
+                <div class="legend-item">
+                    <div class="legend-dot" style="background: #ff9800;"></div> Environment (AWS)
+                </div>
+                <div class="legend-item">
+                    <div class="legend-dot" style="background: #26c6da;"></div> Environment (Azure)
+                </div>
+                <div class="legend-item">
+                    <div class="legend-dot" style="background: #78909c;"></div> Environment (Other)
+                </div>
+                <div class="legend-item">
+                    <div class="legend-dot" style="background: #7e57c2;"></div> Host Group (Enclave)
+                </div>
+                <div class="legend-item">
+                    <div class="legend-dot" style="background: #66bb6a;"></div> Host (Connected)
+                </div>
+                <div class="legend-item">
+                    <div class="legend-dot" style="background: #ef5350;"></div> Host (Disconnected)
+                </div>
+                <div class="legend-item">
+                    <div class="legend-dot" style="background: #29b6f6;"></div> Agent
+                </div>
+            </div>
+
+            <div class="detail-panel" id="detail-panel">
+                <h4 id="detail-title">Node Details</h4>
+                <div id="detail-content"></div>
+            </div>
+        </div>
+
+        <!-- Main canvas -->
+        <div class="topo-main">
+            <div id="topology-canvas"></div>
+        </div>
+    </div>
+</div>
+
+            </div>
+        </div>
+    </div>
+</div>
+
+<script src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>
+<script>
+    const csrfToken = document.querySelector('meta[name="_csrf"]')?.content || '';
+    const csrfHeader = document.querySelector('meta[name="_csrf_header"]')?.content || 'X-CSRF-TOKEN';
+
+    let network = null;
+    let allNodes = [];
+    let allEdges = [];
+    let rawData = { nodes: [], edges: [] };
+    let autoRefreshInterval = null;
+
+    // Color mappings
+    const providerColors = {
+        'GCP': '#42a5f5',
+        'AWS': '#ff9800',
+        'AZURE': '#26c6da',
+        'BARE_METAL': '#78909c',
+        'ON_PREM': '#8d6e63',
+        'OTHER': '#78909c'
+    };
+
+    const nodeShapes = {
+        'ENVIRONMENT': 'diamond',
+        'HOST_GROUP': 'triangle',
+        'HOST': 'square',
+        'AGENT': 'dot'
+    };
+
+    function getNodeColor(node) {
+        switch (node.type) {
+            case 'ENVIRONMENT':
+                return providerColors[node.metadata?.provider] || providerColors['OTHER'];
+            case 'HOST_GROUP':
+                return '#7e57c2';
+            case 'HOST':
+                if (node.status === 'CONNECTED') return '#66bb6a';
+                if (node.status === 'AUTHFAIL' || node.status === 'DISCONNECTED') return '#ef5350';
+                return '#ffa726';
+            case 'AGENT': {
+                const lastHb = node.metadata?.lastHeartbeat;
+                if (!lastHb) return '#ef5350';
+                const diff = (Date.now() - new Date(lastHb).getTime()) / 60000;
+                if (diff < 2) return '#66bb6a';
+                if (diff < 5) return '#ffa726';
+                return '#ef5350';
+            }
+            default:
+                return '#888';
+        }
+    }
+
+    function getNodeSize(node) {
+        switch (node.type) {
+            case 'ENVIRONMENT': return 30;
+            case 'HOST_GROUP': return 22;
+            case 'HOST': return 16;
+            case 'AGENT': return 14;
+            default: return 14;
+        }
+    }
+
+    function buildVisData(topoData) {
+        rawData = topoData;
+        const visNodes = topoData.nodes.map(n => ({
+            id: n.id,
+            label: n.label,
+            color: {
+                background: getNodeColor(n),
+                border: getNodeColor(n),
+                highlight: { background: '#fff', border: getNodeColor(n) }
+            },
+            shape: nodeShapes[n.type] || 'dot',
+            size: getNodeSize(n),
+            font: { color: '#ddd', size: 11 },
+            borderWidth: 2,
+            _raw: n
+        }));
+
+        const visEdges = topoData.edges.map((e, i) => ({
+            id: 'edge-' + i,
+            from: e.from,
+            to: e.to,
+            label: '',
+            color: { color: '#555', highlight: '#888' },
+            arrows: { to: { enabled: true, scaleFactor: 0.5 } },
+            smooth: { type: 'cubicBezier', roundness: 0.4 }
+        }));
+
+        return { nodes: visNodes, edges: visEdges };
+    }
+
+    function initNetwork(visData) {
+        const container = document.getElementById('topology-canvas');
+        const options = {
+            physics: {
+                solver: 'forceAtlas2Based',
+                forceAtlas2Based: {
+                    gravitationalConstant: -80,
+                    centralGravity: 0.01,
+                    springLength: 120,
+                    springConstant: 0.04,
+                    damping: 0.4
+                },
+                stabilization: { iterations: 150 }
+            },
+            interaction: {
+                hover: true,
+                tooltipDelay: 200,
+                zoomView: true,
+                dragView: true
+            },
+            layout: {
+                improvedLayout: true
+            }
+        };
+
+        const data = {
+            nodes: new vis.DataSet(visData.nodes),
+            edges: new vis.DataSet(visData.edges)
+        };
+
+        allNodes = data.nodes;
+        allEdges = data.edges;
+
+        network = new vis.Network(container, data, options);
+
+        network.on('click', function (params) {
+            if (params.nodes.length > 0) {
+                const nodeId = params.nodes[0];
+                const node = allNodes.get(nodeId);
+                if (node && node._raw) {
+                    showDetail(node._raw);
+                }
+            } else {
+                hideDetail();
+            }
+        });
+    }
+
+    function showDetail(node) {
+        const panel = document.getElementById('detail-panel');
+        const title = document.getElementById('detail-title');
+        const content = document.getElementById('detail-content');
+
+        title.textContent = node.label;
+
+        let html = '';
+        html += '<div class="detail-row"><span class="detail-key">Type</span><span class="detail-value">' + escapeHtml(node.type) + '</span></div>';
+        html += '<div class="detail-row"><span class="detail-key">Status</span><span class="detail-value"><span class="status-badge status-' + node.status.toLowerCase() + '">' + escapeHtml(node.status) + '</span></span></div>';
+
+        if (node.metadata) {
+            for (const [key, value] of Object.entries(node.metadata)) {
+                html += '<div class="detail-row"><span class="detail-key">' + escapeHtml(key) + '</span><span class="detail-value" title="' + escapeHtml(value) + '">' + escapeHtml(value) + '</span></div>';
+            }
+        }
+
+        content.innerHTML = html;
+        panel.classList.add('active');
+    }
+
+    function hideDetail() {
+        document.getElementById('detail-panel').classList.remove('active');
+    }
+
+    function updateStats(topoData) {
+        const envCount = topoData.nodes.filter(n => n.type === 'ENVIRONMENT').length;
+        const agentCount = topoData.nodes.filter(n => n.type === 'AGENT').length;
+        const hostCount = topoData.nodes.filter(n => n.type === 'HOST').length;
+
+        document.getElementById('env-count').textContent = envCount;
+        document.getElementById('agent-count').textContent = agentCount;
+        document.getElementById('host-count').textContent = hostCount;
+        document.getElementById('last-refresh').textContent = 'Updated ' + new Date().toLocaleTimeString();
+    }
+
+    function applyFilters() {
+        const providerCheckboxes = document.querySelectorAll('.filter-section:first-child .filter-checkbox input');
+        const statusCheckboxes = document.querySelectorAll('.filter-section:nth-child(2) .filter-checkbox input');
+
+        const activeProviders = new Set();
+        providerCheckboxes.forEach(cb => { if (cb.checked) activeProviders.add(cb.value); });
+
+        const activeStatuses = new Set();
+        statusCheckboxes.forEach(cb => { if (cb.checked) activeStatuses.add(cb.value); });
+
+        // Determine which environment node IDs pass the filter
+        const visibleEnvIds = new Set();
+        rawData.nodes.forEach(n => {
+            if (n.type === 'ENVIRONMENT') {
+                const provider = n.metadata?.provider || 'OTHER';
+                if (activeProviders.has(provider) && activeStatuses.has(n.status)) {
+                    visibleEnvIds.add(n.id);
+                }
+            }
+        });
+
+        // Build set of all connected node IDs via edges
+        const visibleNodeIds = new Set(visibleEnvIds);
+        // Iteratively resolve children
+        let changed = true;
+        while (changed) {
+            changed = false;
+            rawData.edges.forEach(e => {
+                if (visibleNodeIds.has(e.from) && !visibleNodeIds.has(e.to)) {
+                    visibleNodeIds.add(e.to);
+                    changed = true;
+                }
+            });
+        }
+
+        // Also include nodes with no environment connection (orphans)
+        const connectedNodes = new Set();
+        rawData.edges.forEach(e => { connectedNodes.add(e.to); });
+        rawData.nodes.forEach(n => {
+            if (n.type !== 'ENVIRONMENT' && !connectedNodes.has(n.id)) {
+                visibleNodeIds.add(n.id);
+            }
+        });
+
+        // Update visibility
+        const updates = [];
+        allNodes.forEach(visNode => {
+            const shouldBeHidden = !visibleNodeIds.has(visNode.id);
+            if (visNode.hidden !== shouldBeHidden) {
+                updates.push({ id: visNode.id, hidden: shouldBeHidden });
+            }
+        });
+        if (updates.length > 0) {
+            allNodes.update(updates);
+        }
+    }
+
+    async function refreshTopology() {
+        try {
+            const headers = { 'Content-Type': 'application/json' };
+            if (csrfToken) headers[csrfHeader] = csrfToken;
+
+            const response = await fetch('/api/v1/environments/topology', { headers });
+            if (!response.ok) throw new Error('HTTP ' + response.status);
+            const topoData = await response.json();
+
+            if (!network) {
+                const visData = buildVisData(topoData);
+                initNetwork(visData);
+            } else {
+                // Update existing network
+                const visData = buildVisData(topoData);
+                allNodes.clear();
+                allNodes.add(visData.nodes);
+                allEdges.clear();
+                allEdges.add(visData.edges);
+            }
+
+            updateStats(topoData);
+            applyFilters();
+        } catch (error) {
+            console.error('Failed to load topology:', error);
+        }
+    }
+
+    function escapeHtml(text) {
+        if (!text) return '';
+        const div = document.createElement('div');
+        div.textContent = text;
+        return div.innerHTML;
+    }
+
+    // Initial load
+    refreshTopology();
+
+    // Auto-refresh every 30 seconds
+    autoRefreshInterval = setInterval(refreshTopology, 30000);
+</script>
+
+</body>
+</html>
diff --git a/core/src/main/java/io/sentrius/sso/core/dto/AgentHeartbeatDTO.java b/core/src/main/java/io/sentrius/sso/core/dto/AgentHeartbeatDTO.java
index 27562e63..e357714a 100644
--- a/core/src/main/java/io/sentrius/sso/core/dto/AgentHeartbeatDTO.java
+++ b/core/src/main/java/io/sentrius/sso/core/dto/AgentHeartbeatDTO.java
@@ -12,5 +12,6 @@ public class AgentHeartbeatDTO {
     private final String agentId;
     private final String name;
     private final String agentUrl;
+    private final String environmentName;
 
 }
diff --git a/core/src/main/java/io/sentrius/sso/core/trust/AgentContext.java b/core/src/main/java/io/sentrius/sso/core/trust/AgentContext.java
index 5fb7f9e8..38c9aa08 100644
--- a/core/src/main/java/io/sentrius/sso/core/trust/AgentContext.java
+++ b/core/src/main/java/io/sentrius/sso/core/trust/AgentContext.java
@@ -17,15 +17,44 @@ public class AgentContext {
     private int incidentCount;
     private Double feedbackScore; // RLHF feedback score (0-100)
 
+    // Provenance trail indicators
+    private boolean hasAuditTrail;
+    private boolean hasCommandsCaptured;
+    private boolean hasSessionSummary;
+    private int provenanceEventCount;
+
 
     public double evaluateIdentity() {
         return identityIssuer != null ? 100.0 : 0.0;
     }
 
     public double evaluateProvenance() {
-        // Score based on presence and quality of provenance data
-        // This is enhanced in TrustEvaluationService with cached events
-        return 80.0;
+        // Score based on actual provenance trail completeness
+        double score = 0.0;
+
+        // Base: has any provenance events at all
+        if (provenanceEventCount > 0) {
+            score += 30.0;
+            // Bonus for richer event trails (up to 20 more points)
+            score += Math.min(20.0, provenanceEventCount * 2.0);
+        }
+
+        // Audit trail exists for this entity
+        if (hasAuditTrail) {
+            score += 20.0;
+        }
+
+        // Commands were captured and stored
+        if (hasCommandsCaptured) {
+            score += 15.0;
+        }
+
+        // Session has been summarized (indicates full processing pipeline ran)
+        if (hasSessionSummary) {
+            score += 15.0;
+        }
+
+        return Math.min(100.0, score);
     }
 
     public double evaluateRuntime() {
diff --git a/core/src/test/java/io/sentrius/sso/core/trust/TrustScoreCalculatorTest.java b/core/src/test/java/io/sentrius/sso/core/trust/TrustScoreCalculatorTest.java
index c0ac9728..14af2933 100644
--- a/core/src/test/java/io/sentrius/sso/core/trust/TrustScoreCalculatorTest.java
+++ b/core/src/test/java/io/sentrius/sso/core/trust/TrustScoreCalculatorTest.java
@@ -37,10 +37,13 @@ void testCalculateWithCorrectWeightings() {
             .priorRuns(0)                // 50 score (new agent)
             .incidentCount(0)
             .feedbackScore(null)         // 50 score (default)
+            .provenanceEventCount(10)    // provenance: 50+15+15 = 80
+            .hasCommandsCaptured(true)
+            .hasSessionSummary(true)
             .build();
-        
+
         int score = calculator.calculate(context, policy);
-        
+
         // Expected: (100 * 0.3) + (80 * 0.2) + (30 * 0.3) + (50 * 0.2) + (50 * 0.0)
         //         = 30 + 16 + 9 + 10 + 0 = 65
         assertEquals(65, score, "Trust score should be correctly calculated");
@@ -59,10 +62,13 @@ void testCalculateWithEnclaveVerified() {
             .priorRuns(50)               // 85 score (good, > 10 but not > 50)
             .incidentCount(0)
             .feedbackScore(null)         // 50 score
+            .provenanceEventCount(10)    // provenance: 50+15+15 = 80
+            .hasCommandsCaptured(true)
+            .hasSessionSummary(true)
             .build();
-        
+
         int score = calculator.calculate(context, policy);
-        
+
         // Expected: (100 * 0.3) + (80 * 0.2) + (100 * 0.3) + (85 * 0.2) + (50 * 0.0)
         //         = 30 + 16 + 30 + 17 + 0 = 93
         assertEquals(93, score, "High trust agent should have high score");
@@ -81,10 +87,13 @@ void testCalculateWithIncidents() {
             .priorRuns(10)               // 85 score (good)
             .incidentCount(3)            // 60 - (3*5) = 45 score
             .feedbackScore(null)         // 50 score
+            .provenanceEventCount(10)    // provenance: 50+15+15 = 80
+            .hasCommandsCaptured(true)
+            .hasSessionSummary(true)
             .build();
-        
+
         int score = calculator.calculate(context, policy);
-        
+
         // Expected: (100 * 0.3) + (80 * 0.2) + (100 * 0.3) + (45 * 0.2) + (50 * 0.0)
         //         = 30 + 16 + 30 + 9 + 0 = 85
         assertEquals(85, score, "Agent with incidents should have reduced behavior score");
@@ -103,10 +112,13 @@ void testCalculateWithNoIdentity() {
             .priorRuns(10)               // 70 score (some history, > 0 but not > 10)
             .incidentCount(0)
             .feedbackScore(null)         // 50 score
+            .provenanceEventCount(10)    // provenance: 50+15+15 = 80
+            .hasCommandsCaptured(true)
+            .hasSessionSummary(true)
             .build();
-        
+
         int score = calculator.calculate(context, policy);
-        
+
         // Expected: (0 * 0.3) + (80 * 0.2) + (30 * 0.3) + (70 * 0.2) + (50 * 0.0)
         //         = 0 + 16 + 9 + 14 + 0 = 39
         assertEquals(39, score, "Agent with no identity should have low score");
@@ -116,7 +128,7 @@ void testCalculateWithNoIdentity() {
     void testCalculateWithFeedbackScore() {
         TrustScore trustScore = createTrustScore(0.3, 0.2, 0.2, 0.2, 0.1);
         policy = createPolicy(trustScore);
-        
+
         AgentContext context = AgentContext.builder()
             .agentId("test-agent")
             .tags(new HashSet<>())
@@ -125,6 +137,9 @@ void testCalculateWithFeedbackScore() {
             .priorRuns(20)               // 85 score
             .incidentCount(0)
             .feedbackScore(90.0)         // 90 score
+            .provenanceEventCount(10)    // provenance: 50+15+15 = 80
+            .hasCommandsCaptured(true)
+            .hasSessionSummary(true)
             .build();
         
         int score = calculator.calculate(context, policy);
@@ -161,10 +176,13 @@ void testIncorrectWeightingsSumTooHigh() {
             .priorRuns(0)                // 50 score
             .incidentCount(0)
             .feedbackScore(null)         // 50 score
+            .provenanceEventCount(10)    // provenance: 50+15+15 = 80
+            .hasCommandsCaptured(true)
+            .hasSessionSummary(true)
             .build();
-        
+
         int score = calculator.calculate(context, policy);
-        
+
         // With incorrect weightings (sum=1.2):
         // (100 * 0.5) + (80 * 0.2) + (30 * 0.3) + (50 * 0.2) + (50 * 0.0)
         // = 50 + 16 + 9 + 10 + 0 = 85 (inflated by 20%)
@@ -186,6 +204,9 @@ void testCommonLowTrustScenarioGives39() {
             .priorRuns(10)               // 70 score - some history
             .incidentCount(0)            // no incidents
             .feedbackScore(null)         // 50 score - neutral
+            .provenanceEventCount(10)    // provenance: 50+15+15 = 80
+            .hasCommandsCaptured(true)
+            .hasSessionSummary(true)
             .build();
         
         int score = calculator.calculate(context, policy);
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/config/SystemOptions.java b/dataplane/src/main/java/io/sentrius/sso/core/config/SystemOptions.java
index 5ba35e60..a759f1cb 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/config/SystemOptions.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/config/SystemOptions.java
@@ -210,18 +210,39 @@ public class SystemOptions {
     @Builder.Default
     public String githubAgentTokenName = "";
 
-    @Updatable(description = "Sleep time for the document relationship analyzer", group = "AI/LLM")
+    // LLM Analytics Controls - Control token consumption by enabling/disabling LLM-based analytics
+    @Updatable(description = "Master switch for all LLM-based analytics. When disabled, all scheduled LLM analytics jobs are skipped to save tokens.", group = "AI/LLM")
+    @Builder.Default
+    public Boolean enableLLMAnalytics = true;
+
+    @Updatable(description = "Enable document relationship analysis using LLM. Discovers semantic relationships between documents.", group = "AI/LLM")
+    @Builder.Default
+    public Boolean documentRelationshipAnalysisEnabled = true;
+
+    @Updatable(description = "Sleep time for the document relationship analyzer (in milliseconds)", group = "AI/LLM")
     @Builder.Default
     public Long documentRelationshipsSleep = 30000L;
 
+    @Updatable(description = "Enable SSH session summarization using LLM. Generates human-readable summaries of terminal sessions.", group = "AI/LLM")
+    @Builder.Default
+    public Boolean sshSessionSummarizationEnabled = true;
+
+    @Updatable(description = "Enable RDP session summarization using LLM. Generates human-readable summaries of RDP sessions.", group = "AI/LLM")
+    @Builder.Default
+    public Boolean rdpSessionSummarizationEnabled = true;
+
+    @Updatable(description = "Enable trust evaluation using LLM guidance. Uses LLM to optimize trust evaluation timing.", group = "AI/LLM")
+    @Builder.Default
+    public Boolean trustEvaluationLLMGuidanceEnabled = true;
+
     // Knowledge Graph Session/Agent Integration Options
     @Updatable(description = "Enable storing terminal/SSH session data in the knowledge graph", group = "Knowledge Graph")
     @Builder.Default
-    public Boolean knowledgeGraphSessionsEnabled = false;
+    public Boolean knowledgeGraphSessionsEnabled = true;
 
     @Updatable(description = "Enable storing agent execution data in the knowledge graph", group = "Knowledge Graph")
     @Builder.Default
-    public Boolean knowledgeGraphAgentExecutionsEnabled = false;
+    public Boolean knowledgeGraphAgentExecutionsEnabled = true;
 
     @Updatable(description = "Default markings for session data in knowledge graph (e.g., 'SESSION_DATA', 'SENSITIVE&AUDIT'). Users need these authorizations to query session nodes.", group = "Knowledge Graph")
     @Builder.Default
@@ -519,4 +540,37 @@ public String getSurrealdbDatabase() {
     return dynamicPropertiesService.getProperty("sentrius-sentrius", "surrealdbDatabase",
         surrealdbDatabase != null ? surrealdbDatabase : "knowledge_graph");
   }
+
+  // Behavioral Pattern Mining Configuration
+  @Updatable(description = "Enable behavioral pattern mining agent that discovers routines, workflows, and incidents from session data", group = "Knowledge Graph")
+  @Builder.Default
+  public Boolean behavioralPatternMiningEnabled = true;
+
+  @Updatable(description = "Minimum number of sessions with same user+host pattern to qualify as a routine", group = "Knowledge Graph")
+  @Builder.Default
+  public Integer routineMinOccurrences = 3;
+
+  @Updatable(description = "Minimum command sequence similarity (0.0-1.0) to cluster sessions into workflows", group = "Knowledge Graph")
+  @Builder.Default
+  public Double workflowSimilarityThreshold = 0.6;
+
+  @Updatable(description = "Time window in minutes to correlate multiple sessions into a single incident", group = "Knowledge Graph")
+  @Builder.Default
+  public Integer incidentCorrelationWindowMinutes = 30;
+
+  @Updatable(description = "Enable automatic TSG/runbook generation from discovered workflows", group = "Knowledge Graph")
+  @Builder.Default
+  public Boolean autoGenerateRunbooks = true;
+
+  @Updatable(description = "Enable baseline anomaly detection that flags deviations from established behavioral patterns", group = "Knowledge Graph")
+  @Builder.Default
+  public Boolean baselineAnomalyDetectionEnabled = true;
+
+  @Updatable(description = "Standard deviations from baseline before flagging as anomalous (higher = less sensitive)", group = "Knowledge Graph")
+  @Builder.Default
+  public Double anomalyDeviationThreshold = 2.0;
+
+  @Updatable(description = "Enable DRI lifecycle tracking and cross-user pattern transfer", group = "Knowledge Graph")
+  @Builder.Default
+  public Boolean driLifecycleTrackingEnabled = true;
 }
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/model/AgentHeartbeat.java b/dataplane/src/main/java/io/sentrius/sso/core/model/AgentHeartbeat.java
index 28a0da33..76c52c0a 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/model/AgentHeartbeat.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/model/AgentHeartbeat.java
@@ -34,4 +34,7 @@ public class AgentHeartbeat {
 
     @Column(name = "agent_url")
     private String agentUrl;
+
+    @Column(name = "environment_name")
+    private String environmentName;
 }
\ No newline at end of file
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/model/DeploymentEnvironment.java b/dataplane/src/main/java/io/sentrius/sso/core/model/DeploymentEnvironment.java
new file mode 100644
index 00000000..e0dc17bd
--- /dev/null
+++ b/dataplane/src/main/java/io/sentrius/sso/core/model/DeploymentEnvironment.java
@@ -0,0 +1,110 @@
+package io.sentrius.sso.core.model;
+
+import jakarta.persistence.*;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import java.time.Instant;
+import java.util.UUID;
+
+/**
+ * Represents a deployment environment — a cloud region, data center, or bare-metal site
+ * where Sentrius agents and host groups operate.
+ */
+@Entity
+@Getter
+@Setter
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@Table(name = "deployment_environments")
+public class DeploymentEnvironment {
+
+    @Id
+    @GeneratedValue
+    private UUID id;
+
+    /**
+     * Unique machine-friendly name, e.g. "gcp-us-east1-prod", "dc1-bare-metal".
+     */
+    @Column(nullable = false, unique = true)
+    private String name;
+
+    /**
+     * Human-friendly display label.
+     */
+    private String displayName;
+
+    /**
+     * Cloud provider: GCP, AWS, AZURE, BARE_METAL, ON_PREM, OTHER.
+     */
+    @Column(length = 50)
+    private String provider;
+
+    /**
+     * Cloud region, e.g. "us-east1", "eastus". Null for bare metal.
+     */
+    @Column(length = 100)
+    private String region;
+
+    /**
+     * Cloud zone, e.g. "us-east1-b". Null for bare metal.
+     */
+    @Column(length = 100)
+    private String zone;
+
+    /**
+     * Kubernetes cluster name, null for non-K8s deployments.
+     */
+    private String clusterName;
+
+    /**
+     * API endpoint URL for the central Sentrius API this environment reports to.
+     */
+    @Column(length = 500)
+    private String endpoint;
+
+    /**
+     * Environment status: ACTIVE, DEGRADED, UNREACHABLE, DECOMMISSIONED.
+     */
+    @Column(nullable = false, length = 50)
+    @Builder.Default
+    private String status = "ACTIVE";
+
+    /**
+     * Updated on each heartbeat from this environment.
+     */
+    private Instant lastContactAt;
+
+    /**
+     * JSON blob for provider-specific configuration.
+     */
+    @Lob
+    @Column(columnDefinition = "TEXT")
+    private String metadata;
+
+    @Column(nullable = false, updatable = false)
+    private Instant createdAt;
+
+    @Column(nullable = false)
+    private Instant updatedAt;
+
+    @PrePersist
+    protected void onCreate() {
+        Instant now = Instant.now();
+        if (createdAt == null) {
+            createdAt = now;
+        }
+        if (updatedAt == null) {
+            updatedAt = now;
+        }
+    }
+
+    @PreUpdate
+    protected void onUpdate() {
+        updatedAt = Instant.now();
+    }
+}
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/model/agents/AgentExecutionAudit.java b/dataplane/src/main/java/io/sentrius/sso/core/model/agents/AgentExecutionAudit.java
index 3616cd35..f16a080b 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/model/agents/AgentExecutionAudit.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/model/agents/AgentExecutionAudit.java
@@ -91,6 +91,11 @@ public class AgentExecutionAudit {
      */
     private Long durationMs;
 
+    /**
+     * The deployment environment this execution ran in (e.g. "gcp-us-east1-prod").
+     */
+    private String environmentName;
+
     /**
      * Number of times this type of execution has occurred.
      * Used for consolidating duplicate audit entries.
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/model/hostgroup/HostGroup.java b/dataplane/src/main/java/io/sentrius/sso/core/model/hostgroup/HostGroup.java
index 2f17c113..846cd766 100755
--- a/dataplane/src/main/java/io/sentrius/sso/core/model/hostgroup/HostGroup.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/model/hostgroup/HostGroup.java
@@ -109,6 +109,12 @@ public class HostGroup {
   @JoinColumn(name = "application_key_id", referencedColumnName = "id", unique = true)
   private ApplicationKey applicationKey;
 
+  /**
+   * The deployment environment this host group belongs to (e.g. "gcp-us-east1-prod").
+   */
+  @Column(name = "environment_name")
+  private String environmentName;
+
 
   public ProfileConfiguration getConfiguration() {
     ObjectMapper objectMapper = new ObjectMapper();
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/repository/AgentExecutionAuditRepository.java b/dataplane/src/main/java/io/sentrius/sso/core/repository/AgentExecutionAuditRepository.java
index b7dbe8d8..fd2a00eb 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/repository/AgentExecutionAuditRepository.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/repository/AgentExecutionAuditRepository.java
@@ -51,6 +51,12 @@ public interface AgentExecutionAuditRepository extends JpaRepository<AgentExecut
     @Query("SELECT aea FROM AgentExecutionAudit aea WHERE aea.startTime >= :startTime AND aea.startTime <= :endTime ORDER BY aea.startTime DESC")
     List<AgentExecutionAudit> findByStartTimeBetween(@Param("startTime") Instant startTime, @Param("endTime") Instant endTime);
 
+    /**
+     * Find agent execution audits by agent ID within a time range.
+     */
+    @Query("SELECT aea FROM AgentExecutionAudit aea WHERE aea.agentId = :agentId AND aea.startTime >= :startTime AND aea.startTime <= :endTime ORDER BY aea.startTime DESC")
+    List<AgentExecutionAudit> findByAgentIdAndStartTimeBetween(@Param("agentId") String agentId, @Param("startTime") Instant startTime, @Param("endTime") Instant endTime);
+
     /**
      * Find completed agent executions without summaries (summary is null or empty).
      * This is used by the AgentExecutionSummarizationAgent to process executions.
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/repository/AgentMemoryRepository.java b/dataplane/src/main/java/io/sentrius/sso/core/repository/AgentMemoryRepository.java
index c6bd8591..6c6a9b56 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/repository/AgentMemoryRepository.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/repository/AgentMemoryRepository.java
@@ -31,6 +31,9 @@ public interface AgentMemoryRepository extends JpaRepository<AgentMemory, Long>
 
     List<AgentMemory> findByCreatorUserIdOrderByCreatedAtDesc(String creatorUserId);
 
+    @Query("SELECT m FROM AgentMemory m WHERE m.agentId = :agentId AND m.createdAt >= :startTime AND m.createdAt <= :endTime ORDER BY m.createdAt ASC")
+    List<AgentMemory> findByAgentIdAndCreatedAtBetween(@Param("agentId") String agentId, @Param("startTime") Instant startTime, @Param("endTime") Instant endTime);
+
     // === Sharing ===
 
     @Query("""
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/repository/DeploymentEnvironmentRepository.java b/dataplane/src/main/java/io/sentrius/sso/core/repository/DeploymentEnvironmentRepository.java
new file mode 100644
index 00000000..a82fdd56
--- /dev/null
+++ b/dataplane/src/main/java/io/sentrius/sso/core/repository/DeploymentEnvironmentRepository.java
@@ -0,0 +1,27 @@
+package io.sentrius.sso.core.repository;
+
+import io.sentrius.sso.core.model.DeploymentEnvironment;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+@Repository
+public interface DeploymentEnvironmentRepository extends JpaRepository<DeploymentEnvironment, UUID> {
+
+    Optional<DeploymentEnvironment> findByName(String name);
+
+    List<DeploymentEnvironment> findByProvider(String provider);
+
+    List<DeploymentEnvironment> findByStatus(String status);
+
+    List<DeploymentEnvironment> findAllByOrderByNameAsc();
+
+    /**
+     * Find environments that have not reported in since the given cutoff time.
+     */
+    List<DeploymentEnvironment> findByLastContactAtBefore(Instant cutoff);
+}
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/DeploymentEnvironmentService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/DeploymentEnvironmentService.java
new file mode 100644
index 00000000..32cacb92
--- /dev/null
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/DeploymentEnvironmentService.java
@@ -0,0 +1,304 @@
+package io.sentrius.sso.core.services;
+
+import io.sentrius.sso.core.model.AgentHeartbeat;
+import io.sentrius.sso.core.model.DeploymentEnvironment;
+import io.sentrius.sso.core.model.HostSystem;
+import io.sentrius.sso.core.model.hostgroup.HostGroup;
+import io.sentrius.sso.core.repository.AgentHeartbeatRepository;
+import io.sentrius.sso.core.repository.DeploymentEnvironmentRepository;
+import io.sentrius.sso.core.repository.HostGroupRepository;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Duration;
+import java.time.Instant;
+import java.util.*;
+
+/**
+ * Service for managing deployment environments and building topology graphs.
+ */
+@Slf4j
+@Service
+@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
+public class DeploymentEnvironmentService {
+
+    private final DeploymentEnvironmentRepository repository;
+    private final HostGroupRepository hostGroupRepository;
+    private final AgentHeartbeatRepository agentHeartbeatRepository;
+
+    public DeploymentEnvironmentService(
+            DeploymentEnvironmentRepository repository,
+            HostGroupRepository hostGroupRepository,
+            AgentHeartbeatRepository agentHeartbeatRepository) {
+        this.repository = repository;
+        this.hostGroupRepository = hostGroupRepository;
+        this.agentHeartbeatRepository = agentHeartbeatRepository;
+    }
+
+    /**
+     * Idempotent upsert — creates the environment if it doesn't exist, updates it if it does.
+     */
+    @Transactional
+    public DeploymentEnvironment getOrCreateEnvironment(String name, String provider, String region,
+                                                         String zone, String clusterName) {
+        Optional<DeploymentEnvironment> existing = repository.findByName(name);
+        if (existing.isPresent()) {
+            DeploymentEnvironment env = existing.get();
+            if (provider != null) env.setProvider(provider);
+            if (region != null) env.setRegion(region);
+            if (zone != null) env.setZone(zone);
+            if (clusterName != null) env.setClusterName(clusterName);
+            env.setLastContactAt(Instant.now());
+            return repository.save(env);
+        }
+
+        DeploymentEnvironment env = DeploymentEnvironment.builder()
+                .name(name)
+                .displayName(name)
+                .provider(provider)
+                .region(region)
+                .zone(zone)
+                .clusterName(clusterName)
+                .status("ACTIVE")
+                .lastContactAt(Instant.now())
+                .build();
+        return repository.save(env);
+    }
+
+    /**
+     * Updates lastContactAt to now and sets status to ACTIVE.
+     */
+    @Transactional
+    public void touchEnvironment(String name) {
+        if (name == null || name.isBlank()) return;
+        Optional<DeploymentEnvironment> existing = repository.findByName(name);
+        if (existing.isPresent()) {
+            DeploymentEnvironment env = existing.get();
+            env.setLastContactAt(Instant.now());
+            env.setStatus("ACTIVE");
+            repository.save(env);
+        } else {
+            log.debug("touchEnvironment called for unknown environment '{}' — auto-creating", name);
+            getOrCreateEnvironment(name, null, null, null, null);
+        }
+    }
+
+    public List<DeploymentEnvironment> listAll() {
+        return repository.findAllByOrderByNameAsc();
+    }
+
+    public Optional<DeploymentEnvironment> getByName(String name) {
+        return repository.findByName(name);
+    }
+
+    public Optional<DeploymentEnvironment> getById(UUID id) {
+        return repository.findById(id);
+    }
+
+    @Transactional
+    public DeploymentEnvironment updateStatus(String name, String status) {
+        DeploymentEnvironment env = repository.findByName(name)
+                .orElseThrow(() -> new NoSuchElementException("Environment not found: " + name));
+        env.setStatus(status);
+        return repository.save(env);
+    }
+
+    @Transactional
+    public DeploymentEnvironment update(String name, DeploymentEnvironment partial) {
+        DeploymentEnvironment env = repository.findByName(name)
+                .orElseThrow(() -> new NoSuchElementException("Environment not found: " + name));
+        if (partial.getDisplayName() != null) env.setDisplayName(partial.getDisplayName());
+        if (partial.getProvider() != null) env.setProvider(partial.getProvider());
+        if (partial.getRegion() != null) env.setRegion(partial.getRegion());
+        if (partial.getZone() != null) env.setZone(partial.getZone());
+        if (partial.getClusterName() != null) env.setClusterName(partial.getClusterName());
+        if (partial.getEndpoint() != null) env.setEndpoint(partial.getEndpoint());
+        if (partial.getStatus() != null) env.setStatus(partial.getStatus());
+        if (partial.getMetadata() != null) env.setMetadata(partial.getMetadata());
+        return repository.save(env);
+    }
+
+    @Transactional
+    public void delete(String name) {
+        repository.findByName(name).ifPresent(repository::delete);
+    }
+
+    /**
+     * Mark environments as UNREACHABLE if they haven't reported in beyond the threshold.
+     */
+    @Transactional
+    public int markStaleEnvironments(Duration threshold) {
+        Instant cutoff = Instant.now().minus(threshold);
+        List<DeploymentEnvironment> stale = repository.findByLastContactAtBefore(cutoff);
+        int count = 0;
+        for (DeploymentEnvironment env : stale) {
+            if (!"DECOMMISSIONED".equals(env.getStatus()) && !"UNREACHABLE".equals(env.getStatus())) {
+                env.setStatus("UNREACHABLE");
+                repository.save(env);
+                count++;
+            }
+        }
+        return count;
+    }
+
+    /**
+     * Build a topology graph combining environments, host groups, hosts, and agents.
+     */
+    public TopologyGraph getTopologyData() {
+        List<TopologyNode> nodes = new ArrayList<>();
+        List<TopologyEdge> edges = new ArrayList<>();
+
+        // 1. Environment nodes
+        List<DeploymentEnvironment> environments = repository.findAllByOrderByNameAsc();
+        for (DeploymentEnvironment env : environments) {
+            Map<String, String> meta = new LinkedHashMap<>();
+            if (env.getProvider() != null) meta.put("provider", env.getProvider());
+            if (env.getRegion() != null) meta.put("region", env.getRegion());
+            if (env.getZone() != null) meta.put("zone", env.getZone());
+            if (env.getClusterName() != null) meta.put("clusterName", env.getClusterName());
+            if (env.getLastContactAt() != null) meta.put("lastContact", env.getLastContactAt().toString());
+
+            nodes.add(new TopologyNode(
+                    "env:" + env.getName(),
+                    env.getDisplayName() != null ? env.getDisplayName() : env.getName(),
+                    "ENVIRONMENT",
+                    env.getStatus(),
+                    meta));
+        }
+
+        // Build a lookup of environmentName → env node id
+        Map<String, String> envNameToNodeId = new HashMap<>();
+        for (DeploymentEnvironment env : environments) {
+            envNameToNodeId.put(env.getName(), "env:" + env.getName());
+        }
+
+        // 2. Host group nodes
+        List<HostGroup> hostGroups = hostGroupRepository.findAll();
+        for (HostGroup hg : hostGroups) {
+            Map<String, String> meta = new LinkedHashMap<>();
+            if (hg.getEnvironmentName() != null) meta.put("environmentName", hg.getEnvironmentName());
+
+            nodes.add(new TopologyNode(
+                    "hg:" + hg.getId(),
+                    hg.getName(),
+                    "HOST_GROUP",
+                    "ACTIVE",
+                    meta));
+
+            // Edge: environment → host group
+            if (hg.getEnvironmentName() != null && envNameToNodeId.containsKey(hg.getEnvironmentName())) {
+                edges.add(new TopologyEdge(
+                        envNameToNodeId.get(hg.getEnvironmentName()),
+                        "hg:" + hg.getId(),
+                        "contains",
+                        "CONTAINS"));
+            }
+
+            // 3. Host nodes within this group
+            try {
+                List<HostSystem> hosts = hg.getHostSystems();
+                if (hosts != null) {
+                    for (HostSystem host : hosts) {
+                        String hostNodeId = "host:" + host.getId();
+                        Map<String, String> hostMeta = new LinkedHashMap<>();
+                        if (host.getHost() != null) hostMeta.put("hostname", host.getHost());
+                        if (host.getDisplayName() != null) hostMeta.put("displayName", host.getDisplayName());
+                        if (host.getStatusCd() != null) hostMeta.put("statusCode", host.getStatusCd());
+
+                        String label = host.getDisplayName() != null ? host.getDisplayName()
+                                : host.getHost() != null ? host.getHost()
+                                : "host-" + host.getId();
+
+                        nodes.add(new TopologyNode(
+                                hostNodeId,
+                                label,
+                                "HOST",
+                                host.getStatusCd() != null ? host.getStatusCd() : "UNKNOWN",
+                                hostMeta));
+
+                        edges.add(new TopologyEdge(
+                                "hg:" + hg.getId(),
+                                hostNodeId,
+                                "contains",
+                                "CONTAINS"));
+                    }
+                }
+            } catch (Exception e) {
+                log.debug("Could not load hosts for group {}: {}", hg.getId(), e.getMessage());
+            }
+        }
+
+        // 4. Agent nodes from heartbeats
+        List<AgentHeartbeat> heartbeats = agentHeartbeatRepository.findAll();
+        for (AgentHeartbeat hb : heartbeats) {
+            Map<String, String> agentMeta = new LinkedHashMap<>();
+            agentMeta.put("agentId", hb.getAgentId());
+            if (hb.getStatus() != null) agentMeta.put("status", hb.getStatus());
+            if (hb.getLastHeartbeat() != null) agentMeta.put("lastHeartbeat", hb.getLastHeartbeat().toString());
+            if (hb.getEnvironmentName() != null) agentMeta.put("environmentName", hb.getEnvironmentName());
+
+            String agentNodeId = "agent:" + hb.getAgentId();
+            nodes.add(new TopologyNode(
+                    agentNodeId,
+                    hb.getAgentName() != null ? hb.getAgentName() : hb.getAgentId(),
+                    "AGENT",
+                    hb.getStatus() != null ? hb.getStatus() : "UNKNOWN",
+                    agentMeta));
+
+            // Edge: environment → agent
+            if (hb.getEnvironmentName() != null && envNameToNodeId.containsKey(hb.getEnvironmentName())) {
+                edges.add(new TopologyEdge(
+                        envNameToNodeId.get(hb.getEnvironmentName()),
+                        agentNodeId,
+                        "runs in",
+                        "RUNS_IN"));
+            }
+        }
+
+        TopologyGraph graph = new TopologyGraph();
+        graph.nodes = nodes;
+        graph.edges = edges;
+        return graph;
+    }
+
+    // ========================================================================
+    // Data classes
+    // ========================================================================
+
+    public static class TopologyGraph {
+        public List<TopologyNode> nodes;
+        public List<TopologyEdge> edges;
+    }
+
+    public static class TopologyNode {
+        public String id;
+        public String label;
+        public String type;
+        public String status;
+        public Map<String, String> metadata;
+
+        public TopologyNode(String id, String label, String type, String status, Map<String, String> metadata) {
+            this.id = id;
+            this.label = label;
+            this.type = type;
+            this.status = status;
+            this.metadata = metadata;
+        }
+    }
+
+    public static class TopologyEdge {
+        public String from;
+        public String to;
+        public String label;
+        public String type;
+
+        public TopologyEdge(String from, String to, String label, String type) {
+            this.from = from;
+            this.to = to;
+            this.label = label;
+            this.type = type;
+        }
+    }
+}
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java
new file mode 100644
index 00000000..87d28b87
--- /dev/null
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java
@@ -0,0 +1,436 @@
+package io.sentrius.sso.core.services.agents;
+
+import io.sentrius.sso.core.model.agents.AgentExecutionAudit;
+import io.sentrius.sso.core.model.agents.AgentMemory;
+import io.sentrius.sso.core.model.chat.AgentCommunication;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphNode;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryRequest;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryResponse;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphRelationship;
+import io.sentrius.sso.core.repository.AgentCommunicationRepository;
+import io.sentrius.sso.core.repository.AgentExecutionAuditRepository;
+import io.sentrius.sso.core.repository.AgentMemoryRepository;
+import io.sentrius.sso.core.services.documents.KnowledgeGraphService;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.data.domain.Sort;
+import org.springframework.stereotype.Service;
+
+import java.time.Instant;
+import java.util.*;
+import java.util.stream.Collectors;
+
+/**
+ * Agent Forensics Service — assembles the full reasoning chain for an agent execution.
+ * Stitches together data from execution audits, communications, agent memory, and the
+ * knowledge graph into a single unified forensics trace.
+ */
+@Slf4j
+@Service
+@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
+public class AgentForensicsService {
+
+    private static final int MAX_PAYLOAD_LENGTH = 10_000;
+    private static final int MEMORY_WINDOW_SECONDS = 60;
+
+    private final AgentExecutionAuditRepository auditRepository;
+    private final AgentCommunicationRepository communicationRepository;
+    private final AgentMemoryRepository memoryRepository;
+    private final MemoryAccessControlService memoryAccessControlService;
+
+    @Autowired(required = false)
+    private KnowledgeGraphService knowledgeGraphService;
+
+    @Autowired
+    public AgentForensicsService(
+            AgentExecutionAuditRepository auditRepository,
+            AgentCommunicationRepository communicationRepository,
+            AgentMemoryRepository memoryRepository,
+            MemoryAccessControlService memoryAccessControlService) {
+        this.auditRepository = auditRepository;
+        this.communicationRepository = communicationRepository;
+        this.memoryRepository = memoryRepository;
+        this.memoryAccessControlService = memoryAccessControlService;
+    }
+
+    // ========================================================================
+    // Public API
+    // ========================================================================
+
+    /**
+     * Build the full forensics trace for a single agent execution.
+     *
+     * @param executionId       the execution audit ID
+     * @param requestingUserId  user requesting the trace (for ABAC filtering)
+     * @param includePodLogs    whether to include pod logs in the response
+     * @param maxCommunications maximum number of communication entries to return
+     * @param maxPodLogLines    when pod logs are included, tail-truncate to this many lines
+     * @return the assembled trace, or null if the execution ID is not found
+     */
+    public ForensicsTrace getForensicsTrace(String executionId, String requestingUserId,
+                                            boolean includePodLogs, int maxCommunications,
+                                            int maxPodLogLines) {
+        // 1. Fetch the audit record
+        Optional<AgentExecutionAudit> auditOpt = auditRepository.findByExecutionId(executionId);
+        if (auditOpt.isEmpty()) {
+            log.debug("No execution audit found for executionId={}", executionId);
+            return null;
+        }
+        AgentExecutionAudit audit = auditOpt.get();
+        ExecutionMetadata metadata = toExecutionMetadata(audit);
+
+        // 2. Fetch communications
+        List<CommunicationEntry> communications = fetchCommunications(
+                executionId, audit.getAgentId(), audit.getStartTime(), audit.getEndTime(), maxCommunications);
+
+        // 3. Fetch ABAC-filtered memories
+        List<MemoryEntry> memories = fetchMemories(
+                audit.getAgentId(), audit.getStartTime(), audit.getEndTime(), requestingUserId);
+
+        // 4. Fetch KG context (optional)
+        KnowledgeGraphContext kgContext = fetchKnowledgeGraphContext(executionId);
+
+        // 5. Pod logs (opt-in)
+        String podLogs = null;
+        if (includePodLogs && audit.getPodLogs() != null) {
+            podLogs = tailTruncate(audit.getPodLogs(), maxPodLogLines);
+        }
+
+        // 6. Build unified timeline
+        List<TimelineEvent> timeline = buildTimeline(audit, communications, memories, kgContext);
+
+        ForensicsTrace trace = new ForensicsTrace();
+        trace.executionId = executionId;
+        trace.metadata = metadata;
+        trace.summary = audit.getSummary();
+        trace.communications = communications;
+        trace.memories = memories;
+        trace.knowledgeGraphContext = kgContext;
+        trace.podLogs = podLogs;
+        trace.timeline = timeline;
+        return trace;
+    }
+
+    /**
+     * List forensic summaries for an agent within a time range.
+     */
+    public List<ForensicsSummary> getForensicsByAgentAndTimeRange(String agentId, Instant startTime,
+                                                                   Instant endTime, String requestingUserId) {
+        List<AgentExecutionAudit> audits = auditRepository.findByAgentIdAndStartTimeBetween(agentId, startTime, endTime);
+        return audits.stream().map(this::toForensicsSummary).collect(Collectors.toList());
+    }
+
+    /**
+     * List forensic summaries for executions triggered by a given user.
+     */
+    public List<ForensicsSummary> getForensicsByUser(String username, String requestingUserId, int limit) {
+        List<AgentExecutionAudit> audits = auditRepository.findByExecutedByOrderByStartTimeDesc(username);
+        return audits.stream()
+                .limit(limit)
+                .map(this::toForensicsSummary)
+                .collect(Collectors.toList());
+    }
+
+    /**
+     * Return only the flat chronological timeline for an execution.
+     */
+    public List<TimelineEvent> getTimeline(String executionId, String requestingUserId) {
+        ForensicsTrace trace = getForensicsTrace(executionId, requestingUserId, false, 200, 0);
+        return trace != null ? trace.timeline : Collections.emptyList();
+    }
+
+    // ========================================================================
+    // Internal helpers
+    // ========================================================================
+
+    private ExecutionMetadata toExecutionMetadata(AgentExecutionAudit audit) {
+        ExecutionMetadata m = new ExecutionMetadata();
+        m.executionId = audit.getExecutionId();
+        m.agentId = audit.getAgentId();
+        m.agentType = audit.getAgentType();
+        m.executedBy = audit.getExecutedBy();
+        m.status = audit.getStatus();
+        m.environmentName = audit.getEnvironmentName();
+        m.startTime = audit.getStartTime();
+        m.endTime = audit.getEndTime();
+        m.durationMs = audit.getDurationMs();
+        return m;
+    }
+
+    private ForensicsSummary toForensicsSummary(AgentExecutionAudit audit) {
+        ForensicsSummary s = new ForensicsSummary();
+        s.executionId = audit.getExecutionId();
+        s.agentId = audit.getAgentId();
+        s.agentType = audit.getAgentType();
+        s.executedBy = audit.getExecutedBy();
+        s.status = audit.getStatus();
+        s.environmentName = audit.getEnvironmentName();
+        s.summary = audit.getSummary();
+        s.startTime = audit.getStartTime();
+        s.endTime = audit.getEndTime();
+        s.durationMs = audit.getDurationMs();
+        return s;
+    }
+
+    private List<CommunicationEntry> fetchCommunications(String executionId, String agentId,
+                                                          Instant startTime, Instant endTime,
+                                                          int maxCommunications) {
+        List<AgentCommunication> comms;
+        try {
+            UUID commUuid = UUID.fromString(executionId);
+            comms = communicationRepository.findByCommunicationId(commUuid);
+        } catch (IllegalArgumentException e) {
+            // executionId is not a valid UUID — fall back to agent + time window
+            comms = Collections.emptyList();
+        }
+
+        // Fallback: query by agent and time window
+        if (comms.isEmpty() && startTime != null) {
+            Instant end = endTime != null ? endTime : Instant.now();
+            var page = communicationRepository.findBySourceAgentAndCreatedAtBetween(
+                    agentId, startTime, end,
+                    PageRequest.of(0, maxCommunications, Sort.by(Sort.Direction.ASC, "createdAt")));
+            comms = page.getContent();
+        }
+
+        return comms.stream()
+                .limit(maxCommunications)
+                .sorted(Comparator.comparing(c -> c.getCreatedAt() != null ? c.getCreatedAt() : Instant.EPOCH))
+                .map(this::toCommunicationEntry)
+                .collect(Collectors.toList());
+    }
+
+    private CommunicationEntry toCommunicationEntry(AgentCommunication comm) {
+        CommunicationEntry entry = new CommunicationEntry();
+        entry.id = comm.getId();
+        entry.sourceAgent = comm.getSourceAgent();
+        entry.targetAgent = comm.getTargetAgent();
+        entry.messageType = comm.getMessageType();
+        entry.payload = truncate(comm.getPayload(), MAX_PAYLOAD_LENGTH);
+        entry.payloadTruncated = comm.getPayload() != null && comm.getPayload().length() > MAX_PAYLOAD_LENGTH;
+        entry.createdAt = comm.getCreatedAt();
+        return entry;
+    }
+
+    private List<MemoryEntry> fetchMemories(String agentId, Instant startTime, Instant endTime,
+                                             String requestingUserId) {
+        if (startTime == null) return Collections.emptyList();
+
+        Instant windowStart = startTime.minusSeconds(MEMORY_WINDOW_SECONDS);
+        Instant windowEnd = (endTime != null ? endTime : Instant.now()).plusSeconds(MEMORY_WINDOW_SECONDS);
+
+        List<AgentMemory> memories = memoryRepository.findByAgentIdAndCreatedAtBetween(agentId, windowStart, windowEnd);
+
+        return memories.stream()
+                .filter(m -> memoryAccessControlService.canAccessMemory(m, requestingUserId, agentId, "READ"))
+                .map(this::toMemoryEntry)
+                .collect(Collectors.toList());
+    }
+
+    private MemoryEntry toMemoryEntry(AgentMemory memory) {
+        MemoryEntry entry = new MemoryEntry();
+        entry.id = memory.getId();
+        entry.memoryKey = memory.getMemoryKey();
+        entry.memoryValue = memory.getMemoryValue();
+        entry.memoryType = memory.getMemoryType();
+        entry.classification = memory.getClassification();
+        entry.markings = memory.getMarkings();
+        entry.createdAt = memory.getCreatedAt();
+        return entry;
+    }
+
+    private KnowledgeGraphContext fetchKnowledgeGraphContext(String executionId) {
+        KnowledgeGraphContext ctx = new KnowledgeGraphContext();
+        if (knowledgeGraphService == null) {
+            ctx.available = false;
+            ctx.nodes = Collections.emptyList();
+            ctx.relationships = Collections.emptyList();
+            return ctx;
+        }
+
+        try {
+            var queryRequest = KnowledgeGraphQueryRequest.builder()
+                    .queryType(KnowledgeGraphQueryRequest.QueryType.NEIGHBORS)
+                    .startNodeId("agent_execution:" + executionId)
+                    .limit(50)
+                    .build();
+
+            KnowledgeGraphQueryResponse response = knowledgeGraphService.executeQuery(queryRequest, "system", true);
+            ctx.available = true;
+            ctx.nodes = response.getNodes() != null ? response.getNodes() : Collections.emptyList();
+            ctx.relationships = response.getRelationships() != null ? response.getRelationships() : Collections.emptyList();
+        } catch (Exception e) {
+            log.debug("Knowledge graph query failed for execution {}: {}", executionId, e.getMessage());
+            ctx.available = false;
+            ctx.nodes = Collections.emptyList();
+            ctx.relationships = Collections.emptyList();
+        }
+        return ctx;
+    }
+
+    private List<TimelineEvent> buildTimeline(AgentExecutionAudit audit,
+                                               List<CommunicationEntry> communications,
+                                               List<MemoryEntry> memories,
+                                               KnowledgeGraphContext kgContext) {
+        List<TimelineEvent> events = new ArrayList<>();
+
+        // Execution start
+        if (audit.getStartTime() != null) {
+            events.add(timelineEvent("EXECUTION_START", audit.getStartTime(),
+                    "Execution started: " + audit.getAgentType() + " agent " + audit.getAgentId(),
+                    Map.of("status", audit.getStatus(), "executedBy", Objects.toString(audit.getExecutedBy(), ""))));
+        }
+
+        // Communications
+        for (CommunicationEntry comm : communications) {
+            if (comm.createdAt != null) {
+                events.add(timelineEvent("COMMUNICATION", comm.createdAt,
+                        comm.sourceAgent + " → " + comm.targetAgent + " [" + comm.messageType + "]",
+                        Map.of("communicationId", Objects.toString(comm.id, ""),
+                                "messageType", Objects.toString(comm.messageType, ""))));
+            }
+        }
+
+        // Memories
+        for (MemoryEntry mem : memories) {
+            if (mem.createdAt != null) {
+                events.add(timelineEvent("MEMORY_WRITE", mem.createdAt,
+                        "Memory written: " + mem.memoryKey,
+                        Map.of("memoryType", Objects.toString(mem.memoryType, ""),
+                                "classification", Objects.toString(mem.classification, ""))));
+            }
+        }
+
+        // KG nodes
+        if (kgContext != null && kgContext.available && kgContext.nodes != null) {
+            for (KnowledgeGraphNode node : kgContext.nodes) {
+                Instant nodeTime = audit.getStartTime(); // approximate — KG nodes don't have timestamps
+                events.add(timelineEvent("KG_NODE_CREATED", nodeTime,
+                        "KG node: " + node.getName() + " [" + node.getNodeType() + "]",
+                        Map.of("nodeType", Objects.toString(node.getNodeType(), ""),
+                                "nodeName", Objects.toString(node.getName(), ""))));
+            }
+        }
+
+        // Execution end
+        if (audit.getEndTime() != null) {
+            Map<String, String> details = new HashMap<>();
+            details.put("status", audit.getStatus());
+            if (audit.getDurationMs() != null) {
+                details.put("durationMs", audit.getDurationMs().toString());
+            }
+            if (audit.getExitCode() != null) {
+                details.put("exitCode", audit.getExitCode().toString());
+            }
+            events.add(timelineEvent("EXECUTION_END", audit.getEndTime(),
+                    "Execution ended: " + audit.getStatus(), details));
+        }
+
+        // Sort chronologically
+        events.sort(Comparator.comparing(e -> e.timestamp));
+        return events;
+    }
+
+    private TimelineEvent timelineEvent(String type, Instant timestamp, String description,
+                                         Map<String, String> details) {
+        TimelineEvent event = new TimelineEvent();
+        event.type = type;
+        event.timestamp = timestamp;
+        event.description = description;
+        event.details = details;
+        return event;
+    }
+
+    private static String truncate(String value, int maxLength) {
+        if (value == null) return null;
+        return value.length() <= maxLength ? value : value.substring(0, maxLength) + "…";
+    }
+
+    private static String tailTruncate(String text, int maxLines) {
+        if (text == null || maxLines <= 0) return text;
+        String[] lines = text.split("\n");
+        if (lines.length <= maxLines) return text;
+        int start = lines.length - maxLines;
+        StringBuilder sb = new StringBuilder();
+        for (int i = start; i < lines.length; i++) {
+            if (i > start) sb.append('\n');
+            sb.append(lines[i]);
+        }
+        return sb.toString();
+    }
+
+    // ========================================================================
+    // Data classes
+    // ========================================================================
+
+    public static class ForensicsTrace {
+        public String executionId;
+        public ExecutionMetadata metadata;
+        public String summary;
+        public List<CommunicationEntry> communications;
+        public List<MemoryEntry> memories;
+        public KnowledgeGraphContext knowledgeGraphContext;
+        public String podLogs;
+        public List<TimelineEvent> timeline;
+    }
+
+    public static class ExecutionMetadata {
+        public String executionId;
+        public String agentId;
+        public String agentType;
+        public String executedBy;
+        public String status;
+        public String environmentName;
+        public Instant startTime;
+        public Instant endTime;
+        public Long durationMs;
+    }
+
+    public static class CommunicationEntry {
+        public Long id;
+        public String sourceAgent;
+        public String targetAgent;
+        public String messageType;
+        public String payload;
+        public boolean payloadTruncated;
+        public Instant createdAt;
+    }
+
+    public static class MemoryEntry {
+        public Long id;
+        public String memoryKey;
+        public String memoryValue;
+        public String memoryType;
+        public String classification;
+        public String markings;
+        public Instant createdAt;
+    }
+
+    public static class KnowledgeGraphContext {
+        public boolean available;
+        public List<KnowledgeGraphNode> nodes;
+        public List<KnowledgeGraphRelationship> relationships;
+    }
+
+    public static class TimelineEvent {
+        public String type;
+        public Instant timestamp;
+        public String description;
+        public Map<String, String> details;
+    }
+
+    public static class ForensicsSummary {
+        public String executionId;
+        public String agentId;
+        public String agentType;
+        public String executedBy;
+        public String status;
+        public String environmentName;
+        public String summary;
+        public Instant startTime;
+        public Instant endTime;
+        public Long durationMs;
+    }
+}
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentService.java
index 36dc2097..92145478 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentService.java
@@ -27,6 +27,7 @@
 import io.sentrius.sso.core.repository.AgentCommunicationRepository;
 import io.sentrius.sso.core.repository.AgentHeartbeatRepository;
 import io.sentrius.sso.core.services.ATPLPolicyService;
+import io.sentrius.sso.core.services.DeploymentEnvironmentService;
 import io.sentrius.sso.core.services.UserService;
 import io.sentrius.sso.core.services.security.CryptoService;
 import io.sentrius.sso.core.services.security.KeycloakService;
@@ -57,6 +58,7 @@ public class AgentService {
     private final UserService userService;
     private final ATPLPolicyService policyService;
     private final CryptoService cryptoService;
+    private final DeploymentEnvironmentService deploymentEnvironmentService;
 
     private ConcurrentMap<String, String> callbackUrls = new ConcurrentHashMap<>();
 
@@ -74,7 +76,8 @@ public class AgentService {
     public AgentService(
         AgentCommunicationRepository agentCommunicationRepository, AgentHeartbeatRepository repository, UserService userService, ATPLPolicyService policyService,
         CryptoService cryptoService,
-        KeycloakService keycloakService, ProvenanceKafkaProducer provenanceKafkaProducer
+        KeycloakService keycloakService, ProvenanceKafkaProducer provenanceKafkaProducer,
+        DeploymentEnvironmentService deploymentEnvironmentService
     ) {
         this.agentCommunicationRepository = agentCommunicationRepository;
         this.repository = repository;
@@ -83,6 +86,7 @@ public AgentService(
         this.cryptoService = cryptoService;
         this.keycloakService = keycloakService;
         this.provenanceKafkaProducer = provenanceKafkaProducer;
+        this.deploymentEnvironmentService = deploymentEnvironmentService;
     }
 
     @Transactional
@@ -94,7 +98,17 @@ public void recordHeartbeat(String agentId, String name, AgentHeartbeatDTO heart
         heartbeat.setAgentName(name);
         heartbeat.setAgentUrl(heartbeatDTO.getAgentUrl());
         heartbeat.setStatus(heartbeatDTO.getStatus());
+        heartbeat.setEnvironmentName(heartbeatDTO.getEnvironmentName());
         repository.save(heartbeat);
+
+        // Update deployment environment last-contact timestamp
+        if (heartbeatDTO.getEnvironmentName() != null && !heartbeatDTO.getEnvironmentName().isBlank()) {
+            try {
+                deploymentEnvironmentService.touchEnvironment(heartbeatDTO.getEnvironmentName());
+            } catch (Exception e) {
+                log.debug("Could not touch environment '{}': {}", heartbeatDTO.getEnvironmentName(), e.getMessage());
+            }
+        }
     }
 
     public AgentHeartbeat getHeartbeat(String agentId) {
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java
new file mode 100644
index 00000000..551659e3
--- /dev/null
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java
@@ -0,0 +1,296 @@
+package io.sentrius.sso.core.services.documents;
+
+import io.sentrius.sso.core.config.SystemOptions;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphNode;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryRequest;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryResponse;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphRelationship;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
+import org.springframework.stereotype.Service;
+
+import java.util.*;
+import java.util.stream.Collectors;
+
+/**
+ * Service for DRI (Directly Responsible Individual) lifecycle management.
+ * Provides graph-based queries for:
+ * - "Life of a DRI" view: routines, workflows, incidents, systems
+ * - Cross-user pattern transfer for onboarding
+ * - System ownership and responsibility mapping
+ */
+@Slf4j
+@Service
+@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
+public class DriLifecycleService {
+
+    @Autowired(required = false)
+    private KnowledgeGraphService knowledgeGraphService;
+
+    private final SystemOptions systemOptions;
+
+    @Autowired
+    public DriLifecycleService(SystemOptions systemOptions) {
+        this.systemOptions = systemOptions;
+    }
+
+    /**
+     * Get the complete "Life of a DRI" view for a user.
+     * Traverses the knowledge graph to find all associated entities:
+     * routines, workflows, incidents, systems, collaborators, runbooks.
+     *
+     * @param username The DRI's username
+     * @return DRI lifecycle data or null if graph unavailable
+     */
+    public DriLifecycleView getDriLifecycle(String username) {
+        if (knowledgeGraphService == null) {
+            log.debug("Knowledge graph not available for DRI lifecycle query");
+            return null;
+        }
+
+        try {
+            String userNodeId = "user:" + sanitizeId(username);
+
+            // Get all entities connected to this user
+            var queryRequest = KnowledgeGraphQueryRequest.builder()
+                .queryType(KnowledgeGraphQueryRequest.QueryType.SUBGRAPH)
+                .startNodeId(userNodeId)
+                .maxDepth(2)
+                .limit(200)
+                .build();
+
+            var response = knowledgeGraphService.executeQuery(queryRequest, username, true);
+            if (response == null) return null;
+
+            DriLifecycleView view = new DriLifecycleView();
+            view.username = username;
+            view.routines = new ArrayList<>();
+            view.workflows = new ArrayList<>();
+            view.incidents = new ArrayList<>();
+            view.systems = new ArrayList<>();
+            view.collaborators = new ArrayList<>();
+            view.runbooks = new ArrayList<>();
+            view.roleProfile = null;
+
+            if (response.getNodes() != null) {
+                for (KnowledgeGraphNode node : response.getNodes()) {
+                    switch (node.getNodeType()) {
+                        case "routine":
+                            view.routines.add(node);
+                            break;
+                        case "workflow":
+                            view.workflows.add(node);
+                            break;
+                        case "incident":
+                            view.incidents.add(node);
+                            break;
+                        case "system":
+                            view.systems.add(node);
+                            break;
+                        case "user":
+                            if (!node.getName().equals(username)) {
+                                view.collaborators.add(node);
+                            }
+                            break;
+                        case "runbook":
+                            view.runbooks.add(node);
+                            break;
+                        case "role_profile":
+                            view.roleProfile = node;
+                            break;
+                    }
+                }
+            }
+
+            if (response.getRelationships() != null) {
+                view.relationships = response.getRelationships();
+            }
+
+            log.info("DRI lifecycle for {}: {} routines, {} workflows, {} incidents, {} systems, {} collaborators, {} runbooks",
+                username, view.routines.size(), view.workflows.size(), view.incidents.size(),
+                view.systems.size(), view.collaborators.size(), view.runbooks.size());
+
+            return view;
+
+        } catch (Exception e) {
+            log.error("Error fetching DRI lifecycle for {}: {}", username, e.getMessage(), e);
+            return null;
+        }
+    }
+
+    /**
+     * Transfer patterns from a previous DRI to a new DRI for the same system(s).
+     * Returns the routines, workflows, and runbooks that the previous DRI used
+     * on the specified systems.
+     *
+     * @param previousDri The username of the outgoing DRI
+     * @param newDri The username of the incoming DRI
+     * @param systems The systems being transferred (null = all)
+     * @return Onboarding package with transferred patterns
+     */
+    public OnboardingPackage transferPatterns(String previousDri, String newDri, List<String> systems) {
+        if (knowledgeGraphService == null) return null;
+
+        try {
+            // Get the previous DRI's lifecycle
+            DriLifecycleView previousLifecycle = getDriLifecycle(previousDri);
+            if (previousLifecycle == null) {
+                return OnboardingPackage.empty(previousDri, newDri);
+            }
+
+            OnboardingPackage pkg = new OnboardingPackage();
+            pkg.previousDri = previousDri;
+            pkg.newDri = newDri;
+
+            // Filter by systems if specified
+            Set<String> targetSystems = systems != null ? new HashSet<>(systems) : null;
+
+            // Transfer routines for the target systems
+            pkg.routines = previousLifecycle.routines.stream()
+                .filter(r -> {
+                    if (targetSystems == null) return true;
+                    String host = r.getProperties() != null ? (String) r.getProperties().get("host") : null;
+                    return host != null && targetSystems.contains(host);
+                })
+                .collect(Collectors.toList());
+
+            // Transfer workflows for the target systems
+            pkg.workflows = previousLifecycle.workflows.stream()
+                .filter(w -> {
+                    if (targetSystems == null) return true;
+                    String host = w.getProperties() != null ? (String) w.getProperties().get("host") : null;
+                    return host != null && targetSystems.contains(host);
+                })
+                .collect(Collectors.toList());
+
+            // Transfer all runbooks
+            pkg.runbooks = previousLifecycle.runbooks;
+
+            // Transfer system info
+            pkg.systems = previousLifecycle.systems.stream()
+                .filter(s -> targetSystems == null || targetSystems.contains(s.getName()))
+                .collect(Collectors.toList());
+
+            // Transfer incident history for context
+            pkg.recentIncidents = previousLifecycle.incidents.stream()
+                .limit(10) // Only recent incidents
+                .collect(Collectors.toList());
+
+            log.info("Onboarding package for {} from {}: {} routines, {} workflows, {} runbooks, {} systems",
+                newDri, previousDri, pkg.routines.size(), pkg.workflows.size(),
+                pkg.runbooks.size(), pkg.systems.size());
+
+            return pkg;
+
+        } catch (Exception e) {
+            log.error("Error transferring patterns from {} to {}: {}", previousDri, newDri, e.getMessage(), e);
+            return OnboardingPackage.empty(previousDri, newDri);
+        }
+    }
+
+    /**
+     * Find all DRIs responsible for a given system.
+     *
+     * @param systemHost The system hostname
+     * @return List of user nodes that own/operate this system
+     */
+    public List<KnowledgeGraphNode> findSystemOwners(String systemHost) {
+        if (knowledgeGraphService == null) return Collections.emptyList();
+
+        try {
+            String systemNodeId = "system:" + sanitizeId(systemHost);
+
+            var queryRequest = KnowledgeGraphQueryRequest.builder()
+                .queryType(KnowledgeGraphQueryRequest.QueryType.NEIGHBORS)
+                .startNodeId(systemNodeId)
+                .relationshipTypes(List.of("OWNS", "CONNECTED_TO"))
+                .limit(50)
+                .build();
+
+            var response = knowledgeGraphService.executeQuery(queryRequest, "system");
+            if (response == null || response.getNodes() == null) return Collections.emptyList();
+
+            return response.getNodes().stream()
+                .filter(n -> "user".equals(n.getNodeType()) || "role_profile".equals(n.getNodeType()))
+                .collect(Collectors.toList());
+
+        } catch (Exception e) {
+            log.error("Error finding system owners for {}: {}", systemHost, e.getMessage());
+            return Collections.emptyList();
+        }
+    }
+
+    /**
+     * Get all runbooks relevant to a specific system.
+     */
+    public List<KnowledgeGraphNode> getSystemRunbooks(String systemHost) {
+        if (knowledgeGraphService == null) return Collections.emptyList();
+
+        try {
+            var queryRequest = KnowledgeGraphQueryRequest.builder()
+                .queryType(KnowledgeGraphQueryRequest.QueryType.SEARCH)
+                .searchText(systemHost)
+                .nodeTypes(List.of("runbook"))
+                .limit(50)
+                .build();
+
+            var response = knowledgeGraphService.executeQuery(queryRequest, "system");
+            if (response == null || response.getNodes() == null) return Collections.emptyList();
+
+            return response.getNodes().stream()
+                .filter(n -> "runbook".equals(n.getNodeType()))
+                .collect(Collectors.toList());
+
+        } catch (Exception e) {
+            log.error("Error fetching runbooks for {}: {}", systemHost, e.getMessage());
+            return Collections.emptyList();
+        }
+    }
+
+    private String sanitizeId(String input) {
+        if (input == null) return "unknown";
+        return input.toLowerCase()
+            .replaceAll("[^a-z0-9-]", "-")
+            .replaceAll("-+", "-")
+            .replaceAll("^-|-$", "");
+    }
+
+    // ========================================================================
+    // Data classes
+    // ========================================================================
+
+    public static class DriLifecycleView {
+        public String username;
+        public KnowledgeGraphNode roleProfile;
+        public List<KnowledgeGraphNode> routines;
+        public List<KnowledgeGraphNode> workflows;
+        public List<KnowledgeGraphNode> incidents;
+        public List<KnowledgeGraphNode> systems;
+        public List<KnowledgeGraphNode> collaborators;
+        public List<KnowledgeGraphNode> runbooks;
+        public List<KnowledgeGraphRelationship> relationships;
+    }
+
+    public static class OnboardingPackage {
+        public String previousDri;
+        public String newDri;
+        public List<KnowledgeGraphNode> routines;
+        public List<KnowledgeGraphNode> workflows;
+        public List<KnowledgeGraphNode> runbooks;
+        public List<KnowledgeGraphNode> systems;
+        public List<KnowledgeGraphNode> recentIncidents;
+
+        public static OnboardingPackage empty(String previousDri, String newDri) {
+            OnboardingPackage pkg = new OnboardingPackage();
+            pkg.previousDri = previousDri;
+            pkg.newDri = newDri;
+            pkg.routines = Collections.emptyList();
+            pkg.workflows = Collections.emptyList();
+            pkg.runbooks = Collections.emptyList();
+            pkg.systems = Collections.emptyList();
+            pkg.recentIncidents = Collections.emptyList();
+            return pkg;
+        }
+    }
+}
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java
index dbfc17d5..877b3627 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java
@@ -11,6 +11,7 @@
 import io.sentrius.sso.core.repository.TerminalLogsRepository;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
 import org.springframework.stereotype.Service;
 
 import java.time.LocalDateTime;
@@ -42,9 +43,12 @@
  */
 @Slf4j
 @Service
+@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
 public class KnowledgeGraphIngestionService {
 
-    private final KnowledgeGraphService knowledgeGraphService;
+    @Autowired(required = false)
+    private KnowledgeGraphService knowledgeGraphService;
+
     private final SystemOptions systemOptions;
     private final ObjectMapper objectMapper;
 
@@ -59,19 +63,25 @@ public class KnowledgeGraphIngestionService {
 
     @Autowired
     public KnowledgeGraphIngestionService(
-            KnowledgeGraphService knowledgeGraphService,
             SystemOptions systemOptions,
             ObjectMapper objectMapper) {
-        this.knowledgeGraphService = knowledgeGraphService;
         this.systemOptions = systemOptions;
         this.objectMapper = objectMapper;
     }
 
+    /**
+     * Check if knowledge graph service is available
+     */
+    private boolean isKnowledgeGraphAvailable() {
+        return knowledgeGraphService != null;
+    }
+
     /**
      * Check if session ingestion is enabled
      */
     public boolean isSessionIngestionEnabled() {
-        return systemOptions.knowledgeGraphSessionsEnabled != null
+        return isKnowledgeGraphAvailable()
+            && systemOptions.knowledgeGraphSessionsEnabled != null
             && systemOptions.knowledgeGraphSessionsEnabled;
     }
 
@@ -79,7 +89,8 @@ public boolean isSessionIngestionEnabled() {
      * Check if agent execution ingestion is enabled
      */
     public boolean isAgentIngestionEnabled() {
-        return systemOptions.knowledgeGraphAgentExecutionsEnabled != null
+        return isKnowledgeGraphAvailable()
+            && systemOptions.knowledgeGraphAgentExecutionsEnabled != null
             && systemOptions.knowledgeGraphAgentExecutionsEnabled;
     }
 
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/agents/AgentServiceTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/agents/AgentServiceTest.java
index ab71e4aa..b9e933e1 100644
--- a/dataplane/src/test/java/io/sentrius/sso/core/services/agents/AgentServiceTest.java
+++ b/dataplane/src/test/java/io/sentrius/sso/core/services/agents/AgentServiceTest.java
@@ -7,6 +7,7 @@
 import io.sentrius.sso.core.repository.AgentCommunicationRepository;
 import io.sentrius.sso.core.repository.AgentHeartbeatRepository;
 import io.sentrius.sso.core.services.ATPLPolicyService;
+import io.sentrius.sso.core.services.DeploymentEnvironmentService;
 import io.sentrius.sso.core.services.UserService;
 import io.sentrius.sso.core.services.security.CryptoService;
 import io.sentrius.sso.core.services.security.KeycloakService;
@@ -51,6 +52,9 @@ class AgentServiceTest {
     @Mock
     private ProvenanceKafkaProducer provenanceKafkaProducer;
 
+    @Mock
+    private DeploymentEnvironmentService deploymentEnvironmentService;
+
     @InjectMocks
     private AgentService agentService;
 

From 4339dd0ed92af0dff7b445b11f744c968e5b61cc Mon Sep 17 00:00:00 2001
From: Marc Parisi <phrocker@apache.org>
Date: Fri, 11 Sep 2026 12:15:06 -0400
Subject: [PATCH 2/6] Make ZTAT use accounting atomic and stop audit
 consolidation losing executions

Two independent correctness fixes in access enforcement and audit retention.

ZTAT use counting was a read-check-increment-save sequence guarded by neither
@Version nor a row lock. Under READ_COMMITTED two concurrent callers could both
observe the same pre-increment value, both pass the maxJitUses check, and both
be granted access while the counter advanced only once. The limit check and the
increment now happen in a single conditional UPDATE via claimUse(), and callers
treat a return of 0 as "limit exceeded". The stale-entity save() calls are gone;
leaving them would have clobbered the atomic update. Policy semantics are
unchanged - the bound is still uses < maxJitUses.

The ops branch of incrementAccessTokenUses also advanced the counter without
writing an OpsUse row, so the counter and the use log diverged by construction
and nothing reconciled them. Both branches now record the use only after the
claim succeeds.

Audit consolidation grouped rows by agentType + agentId + status + executedBy,
with no executionId and no time component, then deleted every row in the group
but the most recent. Two distinct runs by the same user of the same agent with
the same outcome were merged, permanently losing one execution's executionId,
summary, podLogs, resourceLinks and exitCode. Forensics traces by executionId,
so that loss was not recoverable elsewhere, and the job runs on a schedule from
AgentExecutionSummarizationAgent. The key is now anchored on executionId, and a
row without one keys on its own id so it consolidates with nothing.

Tests were confirmed to fail against the previous behaviour before being kept.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLVutpMbp3msuhvxA46cU3
---
 .../repository/OpsApprovalRepository.java     |  17 ++
 ...eroTrustAccessTokenApprovalRepository.java |  19 +++
 .../agents/AgentExecutionAuditService.java    |  18 +++
 .../security/ZeroTrustRequestService.java     |  30 ++--
 .../AgentExecutionAuditServiceTest.java       |  57 +++++++
 .../ZeroTrustRequestServiceUsesTest.java      | 150 ++++++++++++++++++
 6 files changed, 271 insertions(+), 20 deletions(-)
 create mode 100644 dataplane/src/test/java/io/sentrius/sso/core/services/security/ZeroTrustRequestServiceUsesTest.java

diff --git a/dataplane/src/main/java/io/sentrius/sso/core/repository/OpsApprovalRepository.java b/dataplane/src/main/java/io/sentrius/sso/core/repository/OpsApprovalRepository.java
index ea39f62c..7b050c35 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/repository/OpsApprovalRepository.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/repository/OpsApprovalRepository.java
@@ -4,6 +4,7 @@
 import java.util.UUID;
 import io.sentrius.sso.core.model.zt.OpsApproval;
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
 import org.springframework.data.jpa.repository.Query;
 import org.springframework.data.repository.query.Param;
 
@@ -12,6 +13,22 @@ public interface OpsApprovalRepository extends JpaRepository<OpsApproval, Long>
 
     Optional<OpsApproval> findByZtatRequestId(Long id);
 
+    /**
+     * Atomically consume one use of an ops approval, refusing to exceed the limit.
+     *
+     * <p>The limit check and the increment happen in a single statement so that
+     * concurrent callers cannot both observe the same pre-increment value and
+     * each be granted a use. Callers MUST treat a return of 0 as "limit
+     * exceeded" and MUST NOT fall back to reading, incrementing, and saving the
+     * entity, which would reintroduce the race and clobber this update.
+     *
+     * @return 1 when a use was consumed, 0 when the approval was already at its limit
+     */
+    @Modifying(clearAutomatically = true, flushAutomatically = true)
+    @Query("UPDATE OpsApproval a SET a.uses = a.uses + 1 "
+        + "WHERE a.id = :id AND a.uses < :maxUses")
+    int claimUse(@Param("id") Long id, @Param("maxUses") int maxUses);
+
     @Query("SELECT oa FROM OpsApproval oa LEFT JOIN FETCH oa.ztatRequest WHERE oa.token = :token")
     Optional<OpsApproval> findByToken(@Param("token") UUID token);
 }
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/repository/ZeroTrustAccessTokenApprovalRepository.java b/dataplane/src/main/java/io/sentrius/sso/core/repository/ZeroTrustAccessTokenApprovalRepository.java
index a4cc4702..edc2a7f4 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/repository/ZeroTrustAccessTokenApprovalRepository.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/repository/ZeroTrustAccessTokenApprovalRepository.java
@@ -3,10 +3,29 @@
 import java.util.Optional;
 import io.sentrius.sso.core.model.zt.ZeroTrustAccessTokenApproval;
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 
 public interface ZeroTrustAccessTokenApprovalRepository extends JpaRepository<ZeroTrustAccessTokenApproval, Long> {
     void deleteByztatRequestId(Long ztatRequestId);
 
     Optional<ZeroTrustAccessTokenApproval> findByZtatRequestId(Long ztatRequestId);
+
+    /**
+     * Atomically consume one use of an approval, refusing to exceed the limit.
+     *
+     * <p>The limit check and the increment happen in a single statement so that
+     * concurrent callers cannot both observe the same pre-increment value and
+     * each be granted a use. Callers MUST treat a return of 0 as "limit
+     * exceeded" and MUST NOT fall back to reading, incrementing, and saving the
+     * entity, which would reintroduce the race and clobber this update.
+     *
+     * @return 1 when a use was consumed, 0 when the approval was already at its limit
+     */
+    @Modifying(clearAutomatically = true, flushAutomatically = true)
+    @Query("UPDATE ZeroTrustAccessTokenApproval a SET a.uses = a.uses + 1 "
+        + "WHERE a.id = :id AND a.uses < :maxUses")
+    int claimUse(@Param("id") Long id, @Param("maxUses") int maxUses);
 }
 
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentExecutionAuditService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentExecutionAuditService.java
index 4ff0a4f9..04b02d61 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentExecutionAuditService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentExecutionAuditService.java
@@ -320,8 +320,26 @@ public long consolidateDuplicates() {
      * Build a key for grouping duplicate audits.
      * Audits with the same key are considered duplicates.
      */
+    /**
+     * Build the key identifying rows that describe the SAME execution.
+     *
+     * <p>The key is anchored on {@code executionId}, which is the identity of an
+     * execution. Without it, two genuinely distinct runs that happen to share an
+     * agent, status, and operator would group together and all but the most
+     * recent would be deleted, permanently losing their executionId, summary,
+     * podLogs, resourceLinks, and exitCode. Forensics traces by executionId, so
+     * that loss is not recoverable from anywhere else.
+     *
+     * <p>When executionId is absent the row cannot be shown to duplicate any
+     * other, so it is keyed on its own primary key and consolidates with nothing.
+     */
     private String buildConsolidationKey(AgentExecutionAudit audit) {
+        String executionId = audit.getExecutionId();
+        if (executionId == null || executionId.isBlank()) {
+            return "unidentified|" + audit.getId();
+        }
         return String.join("|",
+            executionId,
             audit.getAgentType() != null ? audit.getAgentType() : "",
             audit.getAgentId() != null ? audit.getAgentId() : "",
             audit.getStatus() != null ? audit.getStatus() : "",
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/security/ZeroTrustRequestService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/security/ZeroTrustRequestService.java
index 5f5321c7..8f262e67 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/security/ZeroTrustRequestService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/security/ZeroTrustRequestService.java
@@ -239,28 +239,22 @@ public void getAccessTokenStatus(ZeroTrustAccessTokenRequest request, User user,
     @Transactional
     public void incrementAccessTokenUses(ZeroTrustAccessTokenRequest request) {
         if (request.getSystem().getId().equals(-1L)) {
-            log.info("Incrementing uses for JITRequest: {}", ztatApprovalRepository.findByZtatRequestId(request.getId()).isPresent());
             opsApprovalRepository.findByZtatRequestId(request.getId()).ifPresent(approval -> {
-                if (approval.getUses() >= systemOptions.maxJitUses) {
+                if (opsApprovalRepository.claimUse(approval.getId(), systemOptions.maxJitUses) == 0) {
                     throw new RuntimeException("JIT uses exceeded");
                 }
-                approval.setUses(approval.getUses() + 1);
-                log.info("Incrementing uses for JITRequest: {}", request.getId());
-                opsApprovalRepository.save(approval);
+                // Record the use only once the claim succeeded, so the counter and
+                // the use log can never disagree about how much access was granted.
+                opsUseRepository.save(OpsUse.builder().opsApproval(approval).user(request.getUser()).build());
+                log.info("Incremented uses for JITRequest: {}", request.getId());
             });
         } else {
-            log.info("Incrementing uses for JITRequest: {}", ztatApprovalRepository.findByZtatRequestId(request.getId()).isPresent());
             ztatApprovalRepository.findByZtatRequestId(request.getId()).ifPresent(approval -> {
-                if (approval.getUses() >= systemOptions.maxJitUses) {
+                if (ztatApprovalRepository.claimUse(approval.getId(), systemOptions.maxJitUses) == 0) {
                     throw new RuntimeException("JIT uses exceeded");
                 }
-
                 ztatUseRepository.save(ZtatUse.builder().ztatApproval(approval).user(request.getUser()).build());
-                log.info("Incrementing uses for JITRequest: {}", request.getId());
-                ztatApprovalRepository.save(approval);
-
-                approval.setUses(approval.getUses() + 1);
-                ztatApprovalRepository.save(approval);
+                log.info("Incremented uses for JITRequest: {}", request.getId());
             });
         }
     }
@@ -438,18 +432,14 @@ public void addCommunicationLink(RequestCommunicationLink link) {
         requestCommunicationLinkRepository.save(link);
     }
 
+    @Transactional
     public void incrementAccessTokenUses(OpsApproval request) {
-        log.info("Incrementing uses for JITRequest: {}",
-            opsApprovalRepository.findByZtatRequestId(request.getZtatRequest().getId()).isPresent());
         opsApprovalRepository.findByZtatRequestId(request.getZtatRequest().getId()).ifPresent(approval -> {
-            if (approval.getUses() >= systemOptions.maxJitUses) {
+            if (opsApprovalRepository.claimUse(approval.getId(), systemOptions.maxJitUses) == 0) {
                 throw new RuntimeException("JIT uses exceeded");
             }
-            log.info("Incrementing uses for JITRequest: {}", request.getId());
             opsUseRepository.save(OpsUse.builder().opsApproval(approval).user(request.getApprover()).build());
-            log.info("Incrementing uses for JITRequest: {}", request.getId());
-            approval.setUses( approval.getUses() + 1 );
-            opsApprovalRepository.save(approval);
+            log.info("Incremented uses for JITRequest: {}", request.getId());
         });
     }
 }
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/agents/AgentExecutionAuditServiceTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/agents/AgentExecutionAuditServiceTest.java
index 309e2242..5b09966b 100644
--- a/dataplane/src/test/java/io/sentrius/sso/core/services/agents/AgentExecutionAuditServiceTest.java
+++ b/dataplane/src/test/java/io/sentrius/sso/core/services/agents/AgentExecutionAuditServiceTest.java
@@ -208,4 +208,61 @@ void testCalculateDuration() {
         assertNotNull(testAudit.getDurationMs());
         assertEquals(330000L, testAudit.getDurationMs()); // 5 minutes 30 seconds = 330000 ms
     }
+
+    private AgentExecutionAudit completedAudit(String executionId, Instant startTime) {
+        AgentExecutionAudit audit = new AgentExecutionAudit();
+        audit.setId(UUID.randomUUID());
+        audit.setExecutionId(executionId);
+        audit.setAgentId("test-agent-pod-123");
+        audit.setAgentType("chat-helper");
+        audit.setExecutedBy("test@example.com");
+        audit.setStatus("COMPLETED");
+        audit.setStartTime(startTime);
+        return audit;
+    }
+
+    @Test
+    void testConsolidationKeepsDistinctExecutions() {
+        // Two genuinely different runs that share agent, type, status and operator.
+        // Only the executionId distinguishes them, and forensics traces by it, so
+        // neither may be deleted.
+        AgentExecutionAudit first = completedAudit("exec-aaa", Instant.parse("2026-01-22T10:00:00Z"));
+        AgentExecutionAudit second = completedAudit("exec-bbb", Instant.parse("2026-01-22T11:00:00Z"));
+
+        when(repository.findAllOrderByStartTimeDesc()).thenReturn(Arrays.asList(second, first));
+
+        long consolidated = service.consolidateDuplicates();
+
+        assertEquals(0, consolidated);
+        verify(repository, never()).delete(any(AgentExecutionAudit.class));
+    }
+
+    @Test
+    void testConsolidationMergesTrueDuplicatesOfOneExecution() {
+        // The same execution recorded twice is a genuine duplicate and may merge.
+        AgentExecutionAudit first = completedAudit("exec-aaa", Instant.parse("2026-01-22T10:00:00Z"));
+        AgentExecutionAudit duplicate = completedAudit("exec-aaa", Instant.parse("2026-01-22T10:00:05Z"));
+
+        when(repository.findAllOrderByStartTimeDesc()).thenReturn(Arrays.asList(duplicate, first));
+
+        long consolidated = service.consolidateDuplicates();
+
+        assertEquals(1, consolidated);
+        verify(repository, times(1)).delete(any(AgentExecutionAudit.class));
+    }
+
+    @Test
+    void testConsolidationNeverMergesRowsWithNoExecutionId() {
+        // A row with no executionId cannot be shown to duplicate anything, so it
+        // must consolidate with nothing rather than be silently collapsed.
+        AgentExecutionAudit first = completedAudit(null, Instant.parse("2026-01-22T10:00:00Z"));
+        AgentExecutionAudit second = completedAudit(null, Instant.parse("2026-01-22T11:00:00Z"));
+
+        when(repository.findAllOrderByStartTimeDesc()).thenReturn(Arrays.asList(second, first));
+
+        long consolidated = service.consolidateDuplicates();
+
+        assertEquals(0, consolidated);
+        verify(repository, never()).delete(any(AgentExecutionAudit.class));
+    }
 }
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/security/ZeroTrustRequestServiceUsesTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/security/ZeroTrustRequestServiceUsesTest.java
new file mode 100644
index 00000000..9b79d2fe
--- /dev/null
+++ b/dataplane/src/test/java/io/sentrius/sso/core/services/security/ZeroTrustRequestServiceUsesTest.java
@@ -0,0 +1,150 @@
+package io.sentrius.sso.core.services.security;
+
+import io.sentrius.sso.core.config.SystemOptions;
+import io.sentrius.sso.core.model.HostSystem;
+import io.sentrius.sso.core.model.users.User;
+import io.sentrius.sso.core.model.zt.OpsApproval;
+import io.sentrius.sso.core.model.zt.OpsUse;
+import io.sentrius.sso.core.model.zt.ZeroTrustAccessTokenApproval;
+import io.sentrius.sso.core.model.zt.ZeroTrustAccessTokenRequest;
+import io.sentrius.sso.core.model.zt.ZtatUse;
+import io.sentrius.sso.core.repository.OpsApprovalRepository;
+import io.sentrius.sso.core.repository.OpsUseRepository;
+import io.sentrius.sso.core.repository.ZeroTrustAccessTokenApprovalRepository;
+import io.sentrius.sso.core.repository.ZtatUseRepository;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.util.Optional;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * Pins the use-accounting contract for zero trust access tokens.
+ *
+ * <p>Consuming a use must be a single atomic claim against the database, not a
+ * read-check-increment-save sequence. Two concurrent callers that each read the
+ * same pre-increment value would otherwise both pass the limit check and both
+ * be granted access, consuming two uses while advancing the counter by one.
+ * These tests assert the service delegates the decision to the atomic claim and
+ * only records a use once that claim has succeeded.
+ */
+@ExtendWith(MockitoExtension.class)
+class ZeroTrustRequestServiceUsesTest {
+
+    private static final long OPS_SYSTEM_ID = -1L;
+    private static final long REGULAR_SYSTEM_ID = 42L;
+    private static final int MAX_USES = 3;
+
+    @Mock
+    private ZeroTrustAccessTokenApprovalRepository ztatApprovalRepository;
+
+    @Mock
+    private OpsApprovalRepository opsApprovalRepository;
+
+    @Mock
+    private ZtatUseRepository ztatUseRepository;
+
+    @Mock
+    private OpsUseRepository opsUseRepository;
+
+    @Mock
+    private SystemOptions systemOptions;
+
+    @InjectMocks
+    private ZeroTrustRequestService service;
+
+    private User user;
+
+    @BeforeEach
+    void setUp() {
+        systemOptions.maxJitUses = MAX_USES;
+        user = new User();
+        user.setId(7L);
+    }
+
+    private ZeroTrustAccessTokenRequest requestFor(long systemId) {
+        HostSystem system = new HostSystem();
+        system.setId(systemId);
+
+        ZeroTrustAccessTokenRequest request = new ZeroTrustAccessTokenRequest();
+        request.setId(100L);
+        request.setSystem(system);
+        request.setUser(user);
+        return request;
+    }
+
+    @Test
+    void consumingAUseClaimsAtomicallyAndRecordsTheUse() {
+        ZeroTrustAccessTokenApproval approval = new ZeroTrustAccessTokenApproval();
+        approval.setId(555L);
+
+        when(ztatApprovalRepository.findByZtatRequestId(100L)).thenReturn(Optional.of(approval));
+        when(ztatApprovalRepository.claimUse(555L, MAX_USES)).thenReturn(1);
+
+        service.incrementAccessTokenUses(requestFor(REGULAR_SYSTEM_ID));
+
+        verify(ztatApprovalRepository).claimUse(555L, MAX_USES);
+        verify(ztatUseRepository).save(any(ZtatUse.class));
+        // The counter must never be advanced by writing back a stale entity; that
+        // would both reintroduce the race and clobber the atomic claim.
+        verify(ztatApprovalRepository, never()).save(any(ZeroTrustAccessTokenApproval.class));
+    }
+
+    @Test
+    void exhaustedApprovalIsRefusedAndRecordsNoUse() {
+        ZeroTrustAccessTokenApproval approval = new ZeroTrustAccessTokenApproval();
+        approval.setId(555L);
+
+        when(ztatApprovalRepository.findByZtatRequestId(100L)).thenReturn(Optional.of(approval));
+        when(ztatApprovalRepository.claimUse(555L, MAX_USES)).thenReturn(0);
+
+        RuntimeException thrown = assertThrows(RuntimeException.class,
+            () -> service.incrementAccessTokenUses(requestFor(REGULAR_SYSTEM_ID)));
+
+        assertEquals("JIT uses exceeded", thrown.getMessage());
+        // A refused claim must leave no trace of a use having been granted.
+        verify(ztatUseRepository, never()).save(any(ZtatUse.class));
+    }
+
+    @Test
+    void opsApprovalAlsoRecordsItsUseSoTheCounterAndLogAgree() {
+        OpsApproval approval = new OpsApproval();
+        approval.setId(888L);
+
+        when(opsApprovalRepository.findByZtatRequestId(100L)).thenReturn(Optional.of(approval));
+        when(opsApprovalRepository.claimUse(888L, MAX_USES)).thenReturn(1);
+
+        service.incrementAccessTokenUses(requestFor(OPS_SYSTEM_ID));
+
+        verify(opsApprovalRepository).claimUse(888L, MAX_USES);
+        // Previously this branch advanced the counter without writing an OpsUse,
+        // leaving the counter and the use log permanently unreconcilable.
+        verify(opsUseRepository).save(any(OpsUse.class));
+        verify(opsApprovalRepository, never()).save(any(OpsApproval.class));
+    }
+
+    @Test
+    void exhaustedOpsApprovalIsRefusedAndRecordsNoUse() {
+        OpsApproval approval = new OpsApproval();
+        approval.setId(888L);
+
+        when(opsApprovalRepository.findByZtatRequestId(100L)).thenReturn(Optional.of(approval));
+        when(opsApprovalRepository.claimUse(eq(888L), eq(MAX_USES))).thenReturn(0);
+
+        assertThrows(RuntimeException.class,
+            () -> service.incrementAccessTokenUses(requestFor(OPS_SYSTEM_ID)));
+
+        verify(opsUseRepository, never()).save(any(OpsUse.class));
+    }
+}

From a968eb66713dc0f6dccf35aa1dc04da455aed223 Mon Sep 17 00:00:00 2001
From: Marc Parisi <phrocker@apache.org>
Date: Fri, 11 Sep 2026 12:15:12 -0400
Subject: [PATCH 3/6] Remove SurrealDB and put a storage-neutral
 KnowledgeGraphPort in its place

No deployment ever ran SurrealDB, so the knowledge graph has only ever exhibited
its degraded path. The backend is removed; the features built on it are not.

BehavioralPatternAgent, AutomationAdoptionTracker, DriLifecycleService,
AgentForensicsService and DocumentService all read and write the graph. Deleting
the store outright would have taken roughly 1,700 lines of recently ported code
with it, so the vendor implementation is replaced by a seam instead:

- KnowledgeGraphPort - the 11 methods consumers actually call, storage-neutral.
- UnavailableKnowledgeGraph - inert fallback reproducing exactly the degraded
  behaviour the SurrealDB implementation showed with its provider disabled:
  writes dropped, queries empty, statistics reporting a disconnected store.
- KnowledgeGraphConfiguration - supplies the fallback only when nothing else
  provides the port. The condition sits on a @Bean method rather than the class,
  because @ConditionalOnMissingBean is only evaluated reliably against already
  registered definitions and not between two scanned components.

Removed: KnowledgeGraphService (2,391 lines), SurrealDBConfig and its test, the
com.surrealdb dependency from api and dataplane, five Helm templates and their
values block, the SystemOptions configuration, configmap properties, the
SURREALDB_PASSWORD plumbing, and the secret generation and deploy script wiring.
No surreal reference remains in the tree and helm lint passes.

Dropping the 212 MB driver takes the api boot jar from roughly 352 MB to 140 MB.

Note: no working Spring context-load test exists for the api module - one is
@Disabled and one has its @Test commented out, both predating this change - so
the bean graph is verified in isolation rather than through a full context boot.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLVutpMbp3msuhvxA46cU3
---
 CLAUDE.md                                     |    6 +-
 .../automation/AutomationAdoptionTracker.java |    4 +-
 .../behavioral/BehavioralPatternAgent.java    |    4 +-
 api/pom.xml                                   |    7 -
 .../sentrius/sso/config/SurrealDBConfig.java  |  157 --
 .../documents/KnowledgeGraphController.java   |   30 +-
 api/src/main/resources/application.properties |    3 -
 dataplane/pom.xml                             |    7 -
 .../sso/core/config/SystemOptions.java        |   99 -
 .../model/documents/KnowledgeGraphNode.java   |    4 +-
 .../documents/KnowledgeGraphQueryRequest.java |    2 +-
 .../documents/KnowledgeGraphRelationship.java |    4 +-
 .../agents/AgentForensicsService.java         |    4 +-
 .../services/documents/DocumentService.java   |    4 +-
 .../documents/DriLifecycleService.java        |    2 +-
 .../KnowledgeGraphConfiguration.java          |   30 +
 .../KnowledgeGraphIngestionService.java       |    2 +-
 .../documents/KnowledgeGraphPort.java         |   60 +
 .../documents/KnowledgeGraphService.java      | 2391 -----------------
 .../documents/UnavailableKnowledgeGraph.java  |  120 +
 .../DocumentSearchEmptyResultsTest.java       |    2 +-
 .../documents/DocumentServiceTest.java        |    2 +-
 .../documents/KeywordExtractionTest.java      |    2 +-
 .../KnowledgeGraphConfigurationTest.java      |  101 +
 .../documents/KnowledgeGraphServiceTest.java  |  402 ---
 docker/sentrius/Dockerfile                    |    2 +-
 ops-scripts/azure/deploy-helm.sh              |    1 -
 ops-scripts/base/generate-secrets.sh          |    4 -
 ops-scripts/gcp/deploy-helm.sh                |    1 -
 ops-scripts/local/deploy-helm.sh              |    1 -
 python-agent/knowledge-graph.yaml             |    2 +-
 sentrius-chart/templates/configmap.yaml       |    7 -
 sentrius-chart/templates/deployment.yaml      |    8 -
 .../templates/surrealdb-deployment.yaml       |   84 -
 .../templates/surrealdb-networkpolicy.yaml    |   25 -
 sentrius-chart/templates/surrealdb-pvc.yaml   |   18 -
 .../templates/surrealdb-secret.yaml           |   13 -
 .../templates/surrealdb-service.yaml          |   19 -
 sentrius-chart/values.yaml                    |   16 -
 39 files changed, 349 insertions(+), 3301 deletions(-)
 delete mode 100644 api/src/main/java/io/sentrius/sso/config/SurrealDBConfig.java
 create mode 100644 dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfiguration.java
 create mode 100644 dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphPort.java
 delete mode 100644 dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphService.java
 create mode 100644 dataplane/src/main/java/io/sentrius/sso/core/services/documents/UnavailableKnowledgeGraph.java
 create mode 100644 dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfigurationTest.java
 delete mode 100644 dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphServiceTest.java
 delete mode 100644 sentrius-chart/templates/surrealdb-deployment.yaml
 delete mode 100644 sentrius-chart/templates/surrealdb-networkpolicy.yaml
 delete mode 100644 sentrius-chart/templates/surrealdb-pvc.yaml
 delete mode 100644 sentrius-chart/templates/surrealdb-secret.yaml
 delete mode 100644 sentrius-chart/templates/surrealdb-service.yaml

diff --git a/CLAUDE.md b/CLAUDE.md
index 52770c21..f24835de 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -116,7 +116,7 @@ Base package: `io.sentrius.sso`
 ### Data Stores
 - **PostgreSQL** (required) — Primary relational store with pgvector for embeddings
 - **Keycloak** (required) — OAuth2/OIDC authentication
-- **SurrealDB** (optional) — Knowledge graph
+- **Knowledge graph** (optional) — pluggable via `KnowledgeGraphPort`; no backend ships by default
 - **Neo4j** (optional) — Graph analysis
 - **Kafka** (optional) — Event streaming for provenance
 - **Qdrant** (optional) — Vector search
@@ -129,7 +129,7 @@ Flyway migrations in `api/src/main/resources/db/migration/` (V1 through V36+). H
 - **ABAC** — Attribute-Based Access Control
 - **SAG** — ANTLR4-based DSL for agent guardrails (parsed in `sag` module, used by `dataplane`)
 - **Self-healing** — Automatic error detection and code repair via coding agents
-- **Knowledge graph** — Document ingestion into SurrealDB with concept extraction for Q&A
+- **Knowledge graph** — Document ingestion behind `KnowledgeGraphPort` with concept extraction for Q&A
 - **MCP (Model Context Protocol)** — Integration with external tools (GitHub, coding)
 - **Provenance** — Full audit trail via Kafka event streaming
 - **WebSocket** — Real-time communication for terminals, agent status, monitoring
@@ -141,7 +141,7 @@ Default service endpoints:
 - Keycloak: `http://localhost:8180`
 - OpenTelemetry: `http://localhost:4317`
 
-Key environment variables: `KEYCLOAK_BASE_URL`, `KEYCLOAK_SECRET`, `DATABASE_PASSWORD`, `KEYSTORE_PASSWORD`, `BASE_URL`, `SURREALDB_PASSWORD`
+Key environment variables: `KEYCLOAK_BASE_URL`, `KEYCLOAK_SECRET`, `DATABASE_PASSWORD`, `KEYSTORE_PASSWORD`, `BASE_URL`
 
 Running locally:
 ```bash
diff --git a/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java b/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java
index a4fe6663..3d301b74 100644
--- a/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java
+++ b/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java
@@ -7,7 +7,7 @@
 import io.sentrius.sso.core.model.metadata.TerminalSessionMetadata;
 import io.sentrius.sso.core.repository.automation.AutomationSuggestionRepository;
 import io.sentrius.sso.core.services.agents.AgentExecutionAuditService;
-import io.sentrius.sso.core.services.documents.KnowledgeGraphService;
+import io.sentrius.sso.core.services.documents.KnowledgeGraphPort;
 import io.sentrius.sso.core.services.metadata.TerminalCommandService;
 import io.sentrius.sso.core.services.metadata.TerminalSessionMetadataService;
 import lombok.extern.slf4j.Slf4j;
@@ -42,7 +42,7 @@
 public class AutomationAdoptionTracker {
 
     @Autowired(required = false)
-    private KnowledgeGraphService knowledgeGraphService;
+    private KnowledgeGraphPort knowledgeGraphService;
 
     private final AutomationSuggestionRepository suggestionRepository;
     private final TerminalSessionMetadataService sessionMetadataService;
diff --git a/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java b/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java
index a99aab5d..6d5cc9df 100644
--- a/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java
+++ b/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java
@@ -13,7 +13,7 @@
 import io.sentrius.sso.core.repository.SshSessionSummaryRepository;
 import io.sentrius.sso.core.services.agents.AgentExecutionAuditService;
 import io.sentrius.sso.core.services.agents.LLMService;
-import io.sentrius.sso.core.services.documents.KnowledgeGraphService;
+import io.sentrius.sso.core.services.documents.KnowledgeGraphPort;
 import io.sentrius.sso.core.services.metadata.TerminalCommandService;
 import io.sentrius.sso.core.services.metadata.TerminalSessionMetadataService;
 import io.sentrius.sso.core.services.security.IntegrationSecurityTokenService;
@@ -50,7 +50,7 @@
 public class BehavioralPatternAgent {
 
     @Autowired(required = false)
-    private KnowledgeGraphService knowledgeGraphService;
+    private KnowledgeGraphPort knowledgeGraphService;
 
     private final TerminalSessionMetadataService sessionMetadataService;
     private final TerminalCommandService commandService;
diff --git a/api/pom.xml b/api/pom.xml
index 511e1423..61e7a672 100644
--- a/api/pom.xml
+++ b/api/pom.xml
@@ -111,13 +111,6 @@
             <artifactId>spring-boot-starter-security</artifactId>
         </dependency>
 
-        <!-- SurrealDB Java SDK for knowledge graph -->
-        <dependency>
-            <groupId>com.surrealdb</groupId>
-            <artifactId>surrealdb</artifactId>
-            <version>1.0.0-beta.1</version>
-            <optional>true</optional>
-        </dependency>
 
         <dependency>
             <groupId>org.springframework.security</groupId>
diff --git a/api/src/main/java/io/sentrius/sso/config/SurrealDBConfig.java b/api/src/main/java/io/sentrius/sso/config/SurrealDBConfig.java
deleted file mode 100644
index 0fb0cb81..00000000
--- a/api/src/main/java/io/sentrius/sso/config/SurrealDBConfig.java
+++ /dev/null
@@ -1,157 +0,0 @@
-package io.sentrius.sso.config;
-
-import com.surrealdb.Surreal;
-import com.surrealdb.signin.Root;
-import io.sentrius.sso.core.config.SystemOptions;
-import io.sentrius.sso.core.services.documents.KnowledgeGraphService;
-import lombok.extern.slf4j.Slf4j;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-import org.springframework.beans.factory.annotation.Value;
-import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
-import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-
-/**
- * Configuration for SurrealDB knowledge graph database connection.
- * SurrealDB is used for storing and querying document relationships and knowledge graphs.
- *
- * This provides a SurrealDBConnectionFactory that creates fresh connections on demand,
- * allowing dynamic configuration changes via SystemOptions to take effect without restart.
- *
- * This configuration is only loaded when:
- * 1. surrealdb.enabled=true property is set (or not set, defaults to true)
- * 2. The SurrealDB classes are available on the classpath
- */
-@Configuration
-@ConditionalOnProperty(name = "surrealdb.enabled", havingValue = "true", matchIfMissing = true)
-@ConditionalOnClass(name = "com.surrealdb.Surreal")
-@Slf4j
-public class SurrealDBConfig {
-    
-    
-    @Value("${surrealdb.password:${SURREALDB_PASSWORD:}}")
-    private String surrealdbPassword;
-    
-    /**
-     * Creates a SurrealDBConnectionFactory bean that provides fresh connections.
-     * This allows SystemOptions changes to take effect without requiring a restart.
-     */
-    @Bean
-    public SurrealDBConnectionFactory surrealDBConnectionFactory(SystemOptions systemOptions) {
-        return new SurrealDBConnectionFactory(systemOptions, surrealdbPassword);
-    }
-
-    /**
-     * Factory class for creating SurrealDB connections.
-     * Implements SurrealDBConnectionProvider for use by KnowledgeGraphService.
-     * Each call to getConnection() creates a fresh connection using current SystemOptions values.
-     */
-    public static class SurrealDBConnectionFactory implements KnowledgeGraphService.SurrealDBConnectionProvider {
-
-        private final SystemOptions systemOptions;
-        private final String password;
-
-        public SurrealDBConnectionFactory(SystemOptions systemOptions, String password) {
-            this.systemOptions = systemOptions;
-            this.password = password;
-            log.info("SurrealDBConnectionFactory initialized");
-        }
-
-        /**
-         * Check if SurrealDB is enabled and properly configured.
-         */
-        @Override
-        public boolean isEnabled() {
-            return systemOptions.getSurrealdbEnabled() &&
-                   password != null &&
-                   !password.trim().isEmpty();
-        }
-
-        /**
-         * Creates a new SurrealDB connection using current SystemOptions values.
-         * Caller is responsible for closing the connection when done.
-         *
-         * @return A new connected Surreal instance, or null if connection fails
-         */
-        @Override
-        public Surreal getConnection() {
-            if (!systemOptions.getSurrealdbEnabled()) {
-                log.debug("SurrealDB is disabled via SystemOptions");
-                return null;
-            }
-
-            if (password == null || password.trim().isEmpty()) {
-                log.error("SurrealDB password not set. Please set SURREALDB_PASSWORD environment variable.");
-                return null;
-            }
-
-            String host = systemOptions.getSurrealdbHost();
-            Integer port = systemOptions.getSurrealdbPort();
-            String username = systemOptions.getSurrealdbUsername();
-            String namespace = systemOptions.getSurrealdbNamespace();
-            String database = systemOptions.getSurrealdbDatabase();
-            
-            try {
-                log.debug("Creating new SurrealDB connection to {}:{}", host, port);
-
-                Surreal db = new Surreal();
-                String connectionString = String.format("ws://%s:%d", host, port);
-                db.connect(connectionString);
-
-                // Sign in with root credentials
-                db.signin(new Root(username, password));
-
-                // Use specific namespace and database
-                db.useNs(namespace);
-                db.useDb(database);
-
-                log.debug("Successfully connected to SurrealDB namespace: {}, database: {}",
-                    namespace, database);
-
-                return db;
-            } catch (Exception e) {
-                log.error("Failed to connect to SurrealDB at {}:{}: {}", host, port, e.getMessage());
-                return null;
-            }
-        }
-
-        /**
-         * Execute a query with automatic connection management.
-         * Creates a connection, executes the query, and ensures cleanup.
-         *
-         * @param queryExecutor Function that takes a Surreal connection and returns a result
-         * @return The result of the query, or null if connection failed
-         */
-        public <T> T executeWithConnection(SurrealQueryExecutor<T> queryExecutor) {
-            Surreal db = null;
-            try {
-                db = getConnection();
-                if (db == null) {
-                    return null;
-                }
-                return queryExecutor.execute(db);
-            } catch (Exception e) {
-                log.error("Error executing SurrealDB query: {}", e.getMessage(), e);
-                return null;
-            } finally {
-                if (db != null) {
-                    try {
-                        db.close();
-                    } catch (Exception e) {
-                        log.warn("Error closing SurrealDB connection: {}", e.getMessage());
-                    }
-                }
-            }
-        }
-    }
-
-    /**
-     * Functional interface for executing queries with a Surreal connection.
-     */
-    @FunctionalInterface
-    public interface SurrealQueryExecutor<T> {
-        T execute(Surreal db) throws Exception;
-    }
-}
diff --git a/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java b/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java
index 6d4ae3fa..34d46d93 100644
--- a/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java
+++ b/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java
@@ -2,7 +2,7 @@
 
 import io.sentrius.sso.core.model.documents.*;
 import io.sentrius.sso.core.services.documents.DriLifecycleService;
-import io.sentrius.sso.core.services.documents.KnowledgeGraphService;
+import io.sentrius.sso.core.services.documents.KnowledgeGraphPort;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.http.HttpStatus;
@@ -24,19 +24,19 @@
 @RequestMapping("/api/v1/knowledge-graph")
 public class KnowledgeGraphController {
     
-    private final KnowledgeGraphService knowledgeGraphService;
+    private final KnowledgeGraphPort knowledgeGraphService;
     private final DriLifecycleService driLifecycleService;
 
     @Autowired
     public KnowledgeGraphController(
-            @Autowired(required = false) KnowledgeGraphService knowledgeGraphService,
+            @Autowired(required = false) KnowledgeGraphPort knowledgeGraphService,
             @Autowired(required = false) DriLifecycleService driLifecycleService) {
         this.knowledgeGraphService = knowledgeGraphService;
         this.driLifecycleService = driLifecycleService;
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphController initialized without KnowledgeGraphService - SurrealDB may not be configured");
+            log.warn("KnowledgeGraphController initialized without a KnowledgeGraphPort");
         } else {
-            log.info("KnowledgeGraphController initialized with KnowledgeGraphService");
+            log.info("KnowledgeGraphController initialized with KnowledgeGraphPort");
         }
     }
     
@@ -51,7 +51,7 @@ public ResponseEntity<KnowledgeGraphNode> createNode(
         log.info("POST /api/v1/knowledge-graph/nodes - Create node request received");
 
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphService not available - SurrealDB is not configured");
+            log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                     .body(null);
         }
@@ -111,7 +111,7 @@ public ResponseEntity<KnowledgeGraphRelationship> createRelationship(
         }
 
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphService not available - SurrealDB is not configured");
+            log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
         
@@ -150,7 +150,7 @@ public ResponseEntity<KnowledgeGraphQueryResponse> findSimilarDocuments(
             documentId, limit);
 
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphService not available - SurrealDB is not configured");
+            log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
         
@@ -185,7 +185,7 @@ public ResponseEntity<KnowledgeGraphQueryResponse> executeQuery(
             request.getQueryType(), request.getSearchText());
 
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphService not available - SurrealDB is not configured");
+            log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
         
@@ -222,7 +222,7 @@ public ResponseEntity<Map<String, Object>> updateNodeProperties(
         log.info("PATCH /api/v1/knowledge-graph/nodes/{}/properties - Update node properties request", nodeId);
 
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphService not available - SurrealDB is not configured");
+            log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
 
@@ -262,7 +262,7 @@ public ResponseEntity<Void> deleteNode(
         log.info("DELETE /api/v1/knowledge-graph/nodes/{} - Delete node request", nodeId);
 
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphService not available - SurrealDB is not configured");
+            log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
         
@@ -293,7 +293,7 @@ public ResponseEntity<Map<String, Object>> getStatistics(Authentication authenti
         log.info("GET /api/v1/knowledge-graph/statistics - Get statistics request");
 
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphService not available - SurrealDB is not configured");
+            log.warn("No knowledge graph backend is configured");
             Map<String, Object> stats = new HashMap<>();
             stats.put("enabled", false);
             stats.put("status", "service_unavailable");
@@ -324,7 +324,7 @@ public ResponseEntity<KnowledgeGraphQueryResponse> listNodes(
         log.info("GET /api/v1/knowledge-graph/nodes - List all nodes (limit: {})", limit);
 
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphService not available - SurrealDB is not configured");
+            log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
 
@@ -365,7 +365,7 @@ public ResponseEntity<Map<String, Object>> askQuestion(
         log.info("POST /api/v1/knowledge-graph/ask - Question: {}", question);
 
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphService not available - SurrealDB is not configured");
+            log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
 
@@ -409,7 +409,7 @@ public ResponseEntity<Map<String, Object>> getRelationshipsForNodes(
             nodeIds != null ? nodeIds.size() : 0);
 
         if (knowledgeGraphService == null) {
-            log.warn("KnowledgeGraphService not available - SurrealDB is not configured");
+            log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
 
diff --git a/api/src/main/resources/application.properties b/api/src/main/resources/application.properties
index 77572e9f..7e094e3e 100644
--- a/api/src/main/resources/application.properties
+++ b/api/src/main/resources/application.properties
@@ -110,8 +110,5 @@ spring.kafka.producer.acks=1
 spring.kafka.producer.request-timeout-ms=500
 spring.kafka.producer.delivery-timeout-ms=1000
 
-# SurrealDB Knowledge Graph Configuration
-# Note: Most SurrealDB settings are now in SystemOptions (configurable via UI/ConfigMap)
-# Password MUST be set via SURREALDB_PASSWORD environment variable for security
 
 spring.kafka.properties.max.block.ms=500
\ No newline at end of file
diff --git a/dataplane/pom.xml b/dataplane/pom.xml
index 01b2df7f..4838c901 100644
--- a/dataplane/pom.xml
+++ b/dataplane/pom.xml
@@ -93,13 +93,6 @@
             <artifactId>spring-boot-starter-security</artifactId>
         </dependency>
 
-        <!-- SurrealDB Java SDK for knowledge graph -->
-        <dependency>
-            <groupId>com.surrealdb</groupId>
-            <artifactId>surrealdb</artifactId>
-            <version>1.0.0-beta.1</version>
-            <optional>true</optional>
-        </dependency>
 
         <dependency>
             <groupId>org.springframework.boot</groupId>
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/config/SystemOptions.java b/dataplane/src/main/java/io/sentrius/sso/core/config/SystemOptions.java
index a759f1cb..75bb46b2 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/config/SystemOptions.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/config/SystemOptions.java
@@ -442,105 +442,6 @@ public Boolean getLockdownEnabled() {
     return Boolean.parseBoolean(value);
   }
 
-  // SurrealDB Knowledge Graph Configuration
-  @Updatable(description = "Enable SurrealDB knowledge graph integration", group = "Knowledge Graph")
-  @Builder.Default
-  public Boolean surrealdbEnabled = false;
-
-  @Updatable(description = "SurrealDB host address", group = "Knowledge Graph")
-  @Builder.Default
-  public String surrealdbHost = "sentrius-surrealdb";
-
-  @Updatable(description = "SurrealDB port", group = "Knowledge Graph")
-  @Builder.Default
-  public Integer surrealdbPort = 8000;
-
-  @Updatable(description = "SurrealDB username", group = "Knowledge Graph")
-  @Builder.Default
-  public String surrealdbUsername = "root";
-
-  @Updatable(description = "SurrealDB namespace", group = "Knowledge Graph")
-  @Builder.Default
-  public String surrealdbNamespace = "sentrius";
-
-  @Updatable(description = "SurrealDB database name", group = "Knowledge Graph")
-  @Builder.Default
-  public String surrealdbDatabase = "knowledge_graph";
-
-  /**
-   * Get SurrealDB enabled state from dynamic properties.
-   * @return the current SurrealDB enabled state
-   */
-  public Boolean getSurrealdbEnabled() {
-    if (dynamicPropertiesService == null) {
-      return surrealdbEnabled;
-    }
-    String value = dynamicPropertiesService.getProperty("sentrius-sentrius", "surrealdbEnabled",
-        surrealdbEnabled != null ? surrealdbEnabled.toString() : "false");
-    return Boolean.parseBoolean(value);
-  }
-
-  /**
-   * Get SurrealDB host from dynamic properties.
-   * @return the current SurrealDB host
-   */
-  public String getSurrealdbHost() {
-    if (dynamicPropertiesService == null) {
-      return surrealdbHost;
-    }
-    return dynamicPropertiesService.getProperty("sentrius-sentrius", "surrealdbHost",
-        surrealdbHost != null ? surrealdbHost : "sentrius-surrealdb");
-  }
-
-  /**
-   * Get SurrealDB port from dynamic properties.
-   * @return the current SurrealDB port
-   */
-  public Integer getSurrealdbPort() {
-    if (dynamicPropertiesService == null) {
-      return surrealdbPort;
-    }
-    String value = dynamicPropertiesService.getProperty("sentrius-sentrius", "surrealdbPort",
-        surrealdbPort != null ? surrealdbPort.toString() : "8000");
-    return Integer.parseInt(value);
-  }
-
-  /**
-   * Get SurrealDB username from dynamic properties.
-   * @return the current SurrealDB username
-   */
-  public String getSurrealdbUsername() {
-    if (dynamicPropertiesService == null) {
-      return surrealdbUsername;
-    }
-    return dynamicPropertiesService.getProperty("sentrius-sentrius", "surrealdbUsername",
-        surrealdbUsername != null ? surrealdbUsername : "root");
-  }
-
-  /**
-   * Get SurrealDB namespace from dynamic properties.
-   * @return the current SurrealDB namespace
-   */
-  public String getSurrealdbNamespace() {
-    if (dynamicPropertiesService == null) {
-      return surrealdbNamespace;
-    }
-    return dynamicPropertiesService.getProperty("sentrius-sentrius", "surrealdbNamespace",
-        surrealdbNamespace != null ? surrealdbNamespace : "sentrius");
-  }
-
-  /**
-   * Get SurrealDB database name from dynamic properties.
-   * @return the current SurrealDB database name
-   */
-  public String getSurrealdbDatabase() {
-    if (dynamicPropertiesService == null) {
-      return surrealdbDatabase;
-    }
-    return dynamicPropertiesService.getProperty("sentrius-sentrius", "surrealdbDatabase",
-        surrealdbDatabase != null ? surrealdbDatabase : "knowledge_graph");
-  }
-
   // Behavioral Pattern Mining Configuration
   @Updatable(description = "Enable behavioral pattern mining agent that discovers routines, workflows, and incidents from session data", group = "Knowledge Graph")
   @Builder.Default
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphNode.java b/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphNode.java
index 8dcdcfd0..966820ab 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphNode.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphNode.java
@@ -11,7 +11,7 @@
 import java.util.Map;
 
 /**
- * Represents a node in the knowledge graph stored in SurrealDB.
+ * Represents a node in the knowledge graph in the knowledge graph store.
  * Nodes are entities (documents, concepts, users, systems) with properties and relationships.
  */
 @Data
@@ -22,7 +22,7 @@
 public class KnowledgeGraphNode {
     
     /**
-     * Unique identifier in SurrealDB (e.g., "document:123" or "concept:ai")
+     * Unique identifier in the knowledge graph store (e.g., "document:123" or "concept:ai")
      */
     private String id;
     
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphQueryRequest.java b/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphQueryRequest.java
index 7076de85..f9f71136 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphQueryRequest.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphQueryRequest.java
@@ -60,7 +60,7 @@ public class KnowledgeGraphQueryRequest {
     private Integer limit;
     
     /**
-     * Custom SurrealQL query (for advanced users)
+     * Custom backend-native query (for advanced users)
      */
     private String customQuery;
     
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphRelationship.java b/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphRelationship.java
index 09f7e6df..f051d5d8 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphRelationship.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/model/documents/KnowledgeGraphRelationship.java
@@ -10,7 +10,7 @@
 import java.util.Map;
 
 /**
- * Represents a relationship (edge) in the knowledge graph stored in SurrealDB.
+ * Represents a relationship (edge) in the knowledge graph in the knowledge graph store.
  * Relationships connect nodes with typed edges and optional properties.
  */
 @Data
@@ -21,7 +21,7 @@
 public class KnowledgeGraphRelationship {
     
     /**
-     * Unique identifier in SurrealDB
+     * Unique identifier in the knowledge graph store
      */
     private String id;
     
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java
index 87d28b87..fcb214c1 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java
@@ -10,7 +10,7 @@
 import io.sentrius.sso.core.repository.AgentCommunicationRepository;
 import io.sentrius.sso.core.repository.AgentExecutionAuditRepository;
 import io.sentrius.sso.core.repository.AgentMemoryRepository;
-import io.sentrius.sso.core.services.documents.KnowledgeGraphService;
+import io.sentrius.sso.core.services.documents.KnowledgeGraphPort;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
@@ -41,7 +41,7 @@ public class AgentForensicsService {
     private final MemoryAccessControlService memoryAccessControlService;
 
     @Autowired(required = false)
-    private KnowledgeGraphService knowledgeGraphService;
+    private KnowledgeGraphPort knowledgeGraphService;
 
     @Autowired
     public AgentForensicsService(
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DocumentService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DocumentService.java
index a6be0c2e..7f97efe6 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DocumentService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DocumentService.java
@@ -51,14 +51,14 @@ public class DocumentService {
 
     private final SystemOptions  systemOptions;
     
-    private final KnowledgeGraphService knowledgeGraphService;
+    private final KnowledgeGraphPort knowledgeGraphService;
 
     public DocumentService(DocumentRepository documentRepository,
                            @Autowired(required = false) EmbeddingService embeddingService,
                            KeycloakService keycloakService, 
                            SystemOptions systemOptions,
                            DocumentAccessControlService accessControlService,
-                           @Autowired(required = false) KnowledgeGraphService knowledgeGraphService
+                           @Autowired(required = false) KnowledgeGraphPort knowledgeGraphService
     ) {
         this.documentRepository = documentRepository;
         this.embeddingService = embeddingService;
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java
index 551659e3..4b79b694 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java
@@ -26,7 +26,7 @@
 public class DriLifecycleService {
 
     @Autowired(required = false)
-    private KnowledgeGraphService knowledgeGraphService;
+    private KnowledgeGraphPort knowledgeGraphService;
 
     private final SystemOptions systemOptions;
 
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfiguration.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfiguration.java
new file mode 100644
index 00000000..fcda751c
--- /dev/null
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfiguration.java
@@ -0,0 +1,30 @@
+package io.sentrius.sso.core.services.documents;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Selects the knowledge graph backend.
+ *
+ * <p>Sentrius ships no graph backend. When an adapter is on the classpath as a
+ * component it is discovered during scanning, this condition sees it, and the
+ * inert fallback is not registered. Otherwise {@link UnavailableKnowledgeGraph}
+ * is supplied so that every consumer still has a {@link KnowledgeGraphPort} to
+ * inject and graph-derived features degrade instead of failing to start.
+ *
+ * <p>The condition lives on a {@code @Bean} method rather than on the fallback
+ * class itself: {@code @ConditionalOnMissingBean} is only evaluated reliably
+ * against bean definitions that are already registered, which is true for
+ * component-scanned adapters by the time configuration-class bean methods are
+ * processed, and is not guaranteed between two scanned components.
+ */
+@Configuration
+public class KnowledgeGraphConfiguration {
+
+    @Bean
+    @ConditionalOnMissingBean(KnowledgeGraphPort.class)
+    public KnowledgeGraphPort unavailableKnowledgeGraph() {
+        return new UnavailableKnowledgeGraph();
+    }
+}
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java
index 877b3627..66bb756b 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java
@@ -47,7 +47,7 @@
 public class KnowledgeGraphIngestionService {
 
     @Autowired(required = false)
-    private KnowledgeGraphService knowledgeGraphService;
+    private KnowledgeGraphPort knowledgeGraphService;
 
     private final SystemOptions systemOptions;
     private final ObjectMapper objectMapper;
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphPort.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphPort.java
new file mode 100644
index 00000000..481023cd
--- /dev/null
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphPort.java
@@ -0,0 +1,60 @@
+package io.sentrius.sso.core.services.documents;
+
+import java.util.List;
+import java.util.Map;
+
+import io.sentrius.sso.core.model.documents.Document;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphNode;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryRequest;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryResponse;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphRelationship;
+
+/**
+ * Storage-neutral contract for the knowledge graph.
+ *
+ * <p>This is the single seam between Sentrius and whatever backs the graph.
+ * Callers depend on this interface only; no caller should reference a concrete
+ * store, so that the backing implementation can be replaced without touching
+ * the behavioural, DRI, forensics, or document features built on top of it.
+ *
+ * <p>Implementations that cannot reach their backing store must degrade rather
+ * than throw: return {@code null} for single-node writes, an empty response for
+ * queries, and {@code false} for mutations. Every consumer in the codebase is
+ * written against that contract, so a graph-less deployment stays functional
+ * with graph-derived features simply absent.
+ */
+public interface KnowledgeGraphPort {
+
+    /** @return true when the backing store is reachable and configured. */
+    boolean isAvailable();
+
+    KnowledgeGraphNode storeDocumentAsNode(Document document, String username);
+
+    KnowledgeGraphNode createNode(KnowledgeGraphNode node, String username);
+
+    KnowledgeGraphRelationship createRelationship(
+        String fromNodeId,
+        String toNodeId,
+        String relationshipType,
+        Double weight,
+        String username);
+
+    KnowledgeGraphQueryResponse findSimilarDocuments(Long documentId, String username, int limit);
+
+    KnowledgeGraphQueryResponse executeQuery(KnowledgeGraphQueryRequest request, String username);
+
+    KnowledgeGraphQueryResponse executeQuery(
+        KnowledgeGraphQueryRequest request, String username, boolean includeRelationships);
+
+    Map<String, Object> getRelationshipsForNodeIds(List<String> nodeIds, String username);
+
+    boolean deleteNode(String nodeId, String username);
+
+    boolean updateNodeProperties(String nodeId, Map<String, Object> properties, String username);
+
+    List<KnowledgeGraphNode> getAllNodes(int limit);
+
+    Map<String, Object> getStatistics();
+
+    Map<String, Object> answerQuestion(String question, String username);
+}
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphService.java
deleted file mode 100644
index d82bb7cb..00000000
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphService.java
+++ /dev/null
@@ -1,2391 +0,0 @@
-package io.sentrius.sso.core.services.documents;
-
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.surrealdb.Surreal;
-import com.surrealdb.SurrealException;
-import com.surrealdb.Response;
-import com.surrealdb.Value;
-import io.sentrius.sso.core.config.SystemOptions;
-import io.sentrius.sso.core.dto.ztat.TokenDTO;
-import io.sentrius.sso.core.exceptions.ZtatException;
-import io.sentrius.sso.core.model.documents.*;
-import io.sentrius.sso.core.model.documents.*;
-import io.sentrius.sso.provenance.ProvenanceEvent;
-import io.sentrius.sso.provenance.ProvenanceLogger;
-import lombok.extern.slf4j.Slf4j;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
-import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
-import org.springframework.stereotype.Service;
-
-import java.time.LocalDateTime;
-import java.util.*;
-import java.util.stream.Collectors;
-
-/**
- * Service for managing knowledge graph operations using SurrealDB.
- * Provides functionality for storing documents as graph nodes, creating relationships,
- * and querying the knowledge graph for document discovery and investigation.
- *
- * Note: This service uses SurrealDBConnectionFactory to get fresh connections for each operation,
- * allowing dynamic configuration changes to take effect without restart.
- * ProvenanceLogger is optional. When not available, provenance events are skipped.
- */
-@Slf4j
-@Service
-@ConditionalOnClass(name = "com.surrealdb.Surreal")
-@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
-public class KnowledgeGraphService {
-    
-    /** Maximum content length to include in full before using excerpts only */
-    private static final int MAX_FULL_CONTENT_LENGTH = 3000;
-    
-    /** Length of excerpt to extract around search terms */
-    private static final int EXCERPT_LENGTH = 500;
-    
-    private final SurrealDBConnectionProvider connectionProvider;
-    private final ProvenanceLogger provenanceLogger;
-    private final DocumentAccessControlService accessControlService;
-    private final ObjectMapper objectMapper;
-    private final io.sentrius.sso.core.services.agents.LLMService llmService;
-    private final SystemOptions systemOptions;
-    private final io.sentrius.sso.core.repository.documents.DocumentRepository documentRepository;
-
-    /**
-     * Interface for providing SurrealDB connections.
-     * This allows the service to work with different connection strategies.
-     */
-    public interface SurrealDBConnectionProvider {
-        boolean isEnabled();
-        Surreal getConnection();
-    }
-
-    @Autowired
-    public KnowledgeGraphService(
-        @Autowired(required = false) SurrealDBConnectionProvider connectionProvider,
-        @Autowired(required = false) ProvenanceLogger provenanceLogger,
-        DocumentAccessControlService accessControlService,
-        ObjectMapper objectMapper,
-        @Autowired(required = false) io.sentrius.sso.core.services.agents.LLMService llmService,
-        SystemOptions systemOptions,
-        @Autowired(required = false) io.sentrius.sso.core.repository.documents.DocumentRepository documentRepository
-    ) {
-        this.connectionProvider = connectionProvider;
-        this.provenanceLogger = provenanceLogger;
-        this.accessControlService = accessControlService;
-        this.objectMapper = objectMapper;
-        this.llmService = llmService;
-        this.systemOptions = systemOptions;
-        this.documentRepository = documentRepository;
-
-        if (connectionProvider == null) {
-            log.info("SurrealDB connection provider not configured. Knowledge graph features will be disabled.");
-        } else if (!connectionProvider.isEnabled()) {
-            log.info("SurrealDB is disabled. Knowledge graph features will be disabled.");
-        } else {
-            log.info("KnowledgeGraphService initialized with SurrealDB connection provider.");
-        }
-        if (provenanceLogger == null) {
-            log.info("ProvenanceLogger not configured. Provenance logging will be disabled for knowledge graph operations.");
-        }
-        if (llmService == null) {
-            log.info("LLMService not configured. Using fallback keyword extraction for search queries.");
-        } else {
-            log.info("LLMService available. Will use AI-powered keyword extraction for search queries.");
-        }
-
-        if (null != llmService){
-            log.info("LLM Service detected in KnowledgeGraphService");
-            llmService.setLLMEndpoint( systemOptions.getIntegrationProxyUrl());
-        }
-        if (documentRepository == null) {
-            log.info("DocumentRepository not configured. Knowledge graph answers will use only node metadata.");
-        } else {
-            log.info("DocumentRepository available. Knowledge graph will use full document content.");
-        }
-    }
-    
-    /**
-     * Check if SurrealDB is available and enabled.
-     */
-    private boolean isSurrealDBAvailable() {
-        return connectionProvider != null && connectionProvider.isEnabled();
-    }
-
-    /**
-     * Creates or updates a node in the knowledge graph from a Document entity.
-     * Also creates automatic relationships with existing documents based on:
-     * - Shared tags
-     * - Same author/creator
-     */
-    public KnowledgeGraphNode storeDocumentAsNode(Document document, String username) {
-        if (!isSurrealDBAvailable()) {
-            log.warn("SurrealDB not configured, skipping knowledge graph storage");
-            return null;
-        }
-        
-        try {
-            // Create node representation
-            KnowledgeGraphNode node = KnowledgeGraphNode.builder()
-                    .id("document:" + document.getId())
-                    .nodeType("document")
-                    .name(document.getDocumentName())
-                    .description(document.getSummary())
-                    .entityId(document.getId())
-                    .properties(buildDocumentProperties(document))
-                    .markings(document.getMarkings())
-                    .createdBy(username)
-                    .createdAt(LocalDateTime.now())
-                    .updatedAt(LocalDateTime.now())
-                    .tags(parseTags(document.getTags()))
-                    .build();
-            
-            // Store in SurrealDB using UPSERT to handle existing records
-            // UPSERT will create if not exists, or update if exists
-            String escapedId = escapeRecordIdForRelate(node.getId());
-            String query = "UPSERT " + escapedId + " CONTENT " + objectMapper.writeValueAsString(nodeToMap(node));
-            invokeSurrealQuery(query);
-            
-            // Log provenance
-            logProvenance("KNOWLEDGE_GRAPH_NODE_CREATED", username, 
-                    "Created/updated knowledge graph node for document: " + document.getDocumentName());
-
-            log.info("Stored document {} as knowledge graph node", document.getId());
-
-            // Create automatic relationships with existing documents
-            createAutomaticRelationships(node, document, username);
-
-            return node;
-        } catch (Exception e) {
-            log.error("Failed to store document as knowledge graph node: {}", e.getMessage(), e);
-            return null;
-        }
-    }
-    
-    /**
-     * Creates a node in the knowledge graph.
-     * If the node is a concept/procedure derived from a document, it inherits the document's markings.
-     *
-     * @param node The node to create
-     * @param username The user creating the node
-     * @return The created node, or null if creation failed
-     */
-    public KnowledgeGraphNode createNode(KnowledgeGraphNode node, String username) {
-        if (!isSurrealDBAvailable()) {
-            log.warn("SurrealDB not configured, skipping node creation");
-            return null;
-        }
-
-        try {
-            // Set created metadata if not already set
-            if (node.getCreatedBy() == null) {
-                node.setCreatedBy(username);
-            }
-            if (node.getCreatedAt() == null) {
-                node.setCreatedAt(LocalDateTime.now());
-            }
-            node.setUpdatedAt(LocalDateTime.now());
-
-            // If node has a sourceDocumentId, inherit markings from the source document
-            if (node.getMarkings() == null && node.getProperties() != null) {
-                Object sourceDocId = node.getProperties().get("sourceDocumentId");
-                if (sourceDocId != null) {
-                    String inheritedMarkings = getMarkingsFromSourceDocument(sourceDocId);
-                    if (inheritedMarkings != null) {
-                        node.setMarkings(inheritedMarkings);
-                        log.debug("Inherited markings '{}' from source document {} for node {}",
-                            inheritedMarkings, sourceDocId, node.getId());
-                    }
-                }
-            }
-
-            // Default to PUBLIC if no markings specified
-            if (node.getMarkings() == null || node.getMarkings().trim().isEmpty()) {
-                node.setMarkings("PUBLIC");
-            }
-
-            // Store in SurrealDB
-            String escapedId = escapeRecordIdForRelate(node.getId());
-            String query = "CREATE " + escapedId + " CONTENT " + objectMapper.writeValueAsString(nodeToMap(node));
-            invokeSurrealQuery(query);
-
-            // Log provenance
-            logProvenance("KNOWLEDGE_GRAPH_NODE_CREATED", username,
-                    "Created knowledge graph node: " + node.getName() + " (type: " + node.getNodeType() + ")");
-
-            log.info("Created knowledge graph node: {} (type: {}, markings: {})",
-                node.getId(), node.getNodeType(), node.getMarkings());
-
-            return node;
-        } catch (Exception e) {
-            log.error("Failed to create knowledge graph node: {}", e.getMessage(), e);
-            return null;
-        }
-    }
-
-    /**
-     * Get the markings from a source document node by its ID.
-     * Used to inherit markings for concept/procedure nodes derived from documents.
-     */
-    private String getMarkingsFromSourceDocument(Object sourceDocId) {
-        try {
-            String docNodeId = "document:" + sourceDocId;
-            String query = "SELECT markings FROM " + escapeRecordIdForRelate(docNodeId);
-            List<Object> results = invokeSurrealQuery(query);
-
-            if (results != null && !results.isEmpty()) {
-                Object result = results.get(0);
-                if (result instanceof Map) {
-                    Map<String, Object> map = (Map<String, Object>) result;
-                    Object markings = map.get("markings");
-                    if (markings != null) {
-                        return markings.toString();
-                    }
-                }
-            }
-        } catch (Exception e) {
-            log.debug("Could not get markings from source document {}: {}", sourceDocId, e.getMessage());
-        }
-        return null;
-    }
-
-    /**
-     * Creates automatic relationships between a new document node and existing documents.
-     * Relationships are created based on:
-     * - SHARES_TAG: Documents that share one or more tags
-     * - SAME_AUTHOR: Documents created by the same user
-     * - SAME_MARKINGS: Documents with the same marking level
-     * - SAME_TYPE: Documents of the same type (e.g., both are TSG, README, etc.)
-     */
-    private void createAutomaticRelationships(KnowledgeGraphNode newNode, Document document, String username) {
-        try {
-            String nodeId = newNode.getId();
-            List<String> tags = newNode.getTags();
-            String markings = document.getMarkings();
-            String documentType = document.getDocumentType();
-            String createdBy = document.getCreatedBy();
-
-            log.info("Creating automatic relationships for document node: {}", nodeId);
-
-            // Find and link documents with shared tags
-            if (tags != null && !tags.isEmpty()) {
-                for (String tag : tags) {
-                    String tagQuery = String.format(
-                        "SELECT * FROM document WHERE '%s' IN tags AND id != '%s' LIMIT 10",
-                        escapeString(tag), nodeId
-                    );
-                    List<Object> relatedByTag = invokeSurrealQuery(tagQuery);
-                    List<KnowledgeGraphNode> tagNodes = parseNodesToList(relatedByTag);
-
-                    for (KnowledgeGraphNode relatedNode : tagNodes) {
-                        createRelationship(nodeId, relatedNode.getId(), "SHARES_TAG", 0.7, username);
-                        log.debug("Created SHARES_TAG relationship: {} -> {} (tag: {})",
-                            nodeId, relatedNode.getId(), tag);
-                    }
-                }
-            }
-
-            // Find and link documents by same author
-            if (createdBy != null && !createdBy.isEmpty()) {
-                String authorQuery = String.format(
-                    "SELECT * FROM document WHERE createdBy = '%s' AND id != '%s' LIMIT 20",
-                    escapeString(createdBy), nodeId
-                );
-                List<Object> relatedByAuthor = invokeSurrealQuery(authorQuery);
-                List<KnowledgeGraphNode> authorNodes = parseNodesToList(relatedByAuthor);
-
-                for (KnowledgeGraphNode relatedNode : authorNodes) {
-                    createRelationship(nodeId, relatedNode.getId(), "SAME_AUTHOR", 0.5, username);
-                    log.debug("Created SAME_AUTHOR relationship: {} -> {}", nodeId, relatedNode.getId());
-                }
-            }
-
-            // Find and link documents with same markings
-            if (markings != null && !markings.isEmpty()) {
-                String classQuery = String.format(
-                    "SELECT * FROM document WHERE markings = '%s' AND id != '%s' LIMIT 20",
-                    escapeString(markings), nodeId
-                );
-                List<Object> relatedByClass = invokeSurrealQuery(classQuery);
-                List<KnowledgeGraphNode> classNodes = parseNodesToList(relatedByClass);
-
-                for (KnowledgeGraphNode relatedNode : classNodes) {
-                    createRelationship(nodeId, relatedNode.getId(), "SAME_MARKINGS", 0.3, username);
-                    log.debug("Created SAME_MARKINGSSAME_MARKINGS relationship: {} -> {}", nodeId, relatedNode.getId());
-                }
-            }
-
-            // Find and link documents of same type
-            if (documentType != null && !documentType.isEmpty()) {
-                String typeQuery = String.format(
-                    "SELECT * FROM document WHERE properties.document_type = '%s' AND id != '%s' LIMIT 20",
-                    escapeString(documentType), nodeId
-                );
-                List<Object> relatedByType = invokeSurrealQuery(typeQuery);
-                List<KnowledgeGraphNode> typeNodes = parseNodesToList(relatedByType);
-
-                for (KnowledgeGraphNode relatedNode : typeNodes) {
-                    createRelationship(nodeId, relatedNode.getId(), "SAME_TYPE", 0.4, username);
-                    log.debug("Created SAME_TYPE relationship: {} -> {}", nodeId, relatedNode.getId());
-                }
-            }
-
-            log.info("Completed automatic relationship creation for document: {}", nodeId);
-
-        } catch (Exception e) {
-            log.error("Failed to create automatic relationships for document: {}", e.getMessage(), e);
-        }
-    }
-
-    /**
-     * Escape string for SurrealDB query to prevent injection
-     */
-    private String escapeString(String input) {
-        if (input == null) return "";
-        return input.replace("'", "\\'").replace("\"", "\\\"");
-    }
-
-    /**
-     * Escape a record ID for use in SurrealDB RELATE statements.
-     * Format: table:id or table:⟨complex-id⟩ for IDs with special characters.
-     *
-     * @param recordId The record ID like "document:5" or "concept:my-concept-name"
-     * @return Properly escaped record ID for RELATE statement
-     */
-    private String escapeRecordIdForRelate(String recordId) {
-        if (recordId == null) return "";
-
-        int colonIndex = recordId.indexOf(':');
-        if (colonIndex == -1) {
-            // No colon, return as-is
-            return recordId;
-        }
-
-        String table = recordId.substring(0, colonIndex);
-        String id = recordId.substring(colonIndex + 1);
-
-        // Check if already escaped with angle brackets - don't double-escape
-        if (id.startsWith("⟨") && id.endsWith("⟩")) {
-            return recordId;
-        }
-
-        // Check if ID contains special characters that need escaping
-        // Special chars: hyphens, spaces, dots, etc.
-        boolean needsEscaping = id.contains("-") || id.contains(" ") ||
-                                id.contains(".") || id.contains("/") ||
-                                !id.matches("[a-zA-Z0-9_]+");
-
-        if (needsEscaping) {
-            // Use SurrealDB's angle bracket syntax for complex IDs
-            return table + ":⟨" + id + "⟩";
-        }
-
-        return recordId;
-    }
-
-    /**
-     * Creates a relationship between two nodes in the knowledge graph.
-     */
-    public KnowledgeGraphRelationship createRelationship(
-            String fromNodeId, 
-            String toNodeId, 
-            String relationshipType,
-            Double weight,
-            String username) {
-        
-        if (!isSurrealDBAvailable()) {
-            log.warn("SurrealDB not configured, skipping relationship creation");
-            return null;
-        }
-        
-        try {
-            KnowledgeGraphRelationship relationship = KnowledgeGraphRelationship.builder()
-                    .id(fromNodeId + "->" + relationshipType + "->" + toNodeId)
-                    .relationshipType(relationshipType)
-                    .fromNode(fromNodeId)
-                    .toNode(toNodeId)
-                    .weight(weight != null ? weight : 1.0)
-                    .createdBy(username)
-                    .createdAt(LocalDateTime.now())
-                    .build();
-            
-            // Use RELATE statement in SurrealDB
-            // For RELATE, record IDs should not be wrapped in backticks
-            // Format: RELATE table:id->RELATION_TYPE->table:id
-            // For IDs with special chars, use the ⟨id⟩ syntax: table:⟨my-special-id⟩
-            String escapedFromId = escapeRecordIdForRelate(fromNodeId);
-            String escapedToId = escapeRecordIdForRelate(toNodeId);
-
-            String query = String.format(
-                    "RELATE %s->%s->%s CONTENT %s",
-                    escapedFromId,
-                    relationshipType,
-                    escapedToId,
-                    objectMapper.writeValueAsString(relationshipToMap(relationship))
-            );
-            invokeSurrealQuery(query);
-            
-            // Log provenance
-            logProvenance("KNOWLEDGE_GRAPH_RELATIONSHIP_CREATED", username,
-                    String.format("Created %s relationship from %s to %s", relationshipType, fromNodeId, toNodeId));
-            
-            log.debug("Created relationship: {} -> {} -> {}", fromNodeId, relationshipType, toNodeId);
-            return relationship;
-        } catch (Exception e) {
-            log.error("Failed to create relationship: {}", e.getMessage(), e);
-            return null;
-        }
-    }
-    
-    /**
-     * Finds similar documents in the knowledge graph based on relationships.
-     */
-    public KnowledgeGraphQueryResponse findSimilarDocuments(Long documentId, String username, int limit) {
-        if (!isSurrealDBAvailable()) {
-            return KnowledgeGraphQueryResponse.builder()
-                    .nodes(Collections.emptyList())
-                    .relationships(Collections.emptyList())
-                    .totalCount(0)
-                    .build();
-        }
-        
-        try {
-            long startTime = System.currentTimeMillis();
-            
-            String nodeId = "document:" + documentId;
-            
-            // Query for similar documents using relationships
-            String query = String.format(
-                    "SELECT * FROM %s<-similar_to | similar_to->* LIMIT %d",
-                    nodeId, limit
-            );
-            
-            // Execute query
-            List<Object> results = invokeSurrealQuery(query);
-            
-            // Parse results (simplified - actual parsing depends on SDK)
-            List<KnowledgeGraphNode> nodes = parseNodesToList(results);
-            
-            // Filter by access control
-            nodes = filterNodesByAccess(nodes, username);
-            
-            long executionTime = System.currentTimeMillis() - startTime;
-            
-            // Log provenance
-            logProvenance("KNOWLEDGE_GRAPH_QUERY", username,
-                    "Queried similar documents for document ID: " + documentId);
-            
-            return KnowledgeGraphQueryResponse.builder()
-                    .nodes(nodes)
-                    .relationships(Collections.emptyList())
-                    .totalCount(nodes.size())
-                    .executionTimeMs(executionTime)
-                    .build();
-        } catch (Exception e) {
-            log.error("Failed to find similar documents: {}", e.getMessage(), e);
-            return KnowledgeGraphQueryResponse.builder()
-                    .nodes(Collections.emptyList())
-                    .relationships(Collections.emptyList())
-                    .totalCount(0)
-                    .build();
-        }
-    }
-    
-    /**
-     * Executes a custom knowledge graph query.
-     * By default, does NOT fetch relationships to keep the query fast.
-     * Use executeQueryWithRelationships() or the includeRelationships parameter for full graph data.
-     */
-    public KnowledgeGraphQueryResponse executeQuery(KnowledgeGraphQueryRequest request, String username) {
-        return executeQuery(request, username, false);
-    }
-
-    /**
-     * Executes a custom knowledge graph query with optional relationship fetching.
-     * @param includeRelationships If true, also fetches relationships and connected nodes (slower)
-     */
-    public KnowledgeGraphQueryResponse executeQuery(KnowledgeGraphQueryRequest request, String username, boolean includeRelationships) {
-        if (!isSurrealDBAvailable()) {
-            return KnowledgeGraphQueryResponse.builder()
-                    .nodes(Collections.emptyList())
-                    .relationships(Collections.emptyList())
-                    .totalCount(0)
-                    .build();
-        }
-        
-        try {
-            long startTime = System.currentTimeMillis();
-            
-            String query = buildQuery(request);
-            log.debug("Executing knowledge graph query: {}", query);
-            
-            List<Object> results = invokeSurrealQuery(query);
-            
-            List<KnowledgeGraphNode> nodes = parseNodesToList(results);
-            nodes = filterNodesByAccess(nodes, username);
-            
-            List<KnowledgeGraphRelationship> relationships = Collections.emptyList();
-            List<KnowledgeGraphNode> allNodes = new ArrayList<>(nodes);
-
-            // Only fetch relationships if explicitly requested (to keep queries fast)
-            if (includeRelationships) {
-                relationships = fetchRelationshipsForNodes(nodes);
-
-                // Also fetch the connected nodes (concepts, procedures) so the UI can render the full graph
-                if (!relationships.isEmpty()) {
-                    List<KnowledgeGraphNode> connectedNodes = fetchConnectedNodes(relationships, nodes);
-                    allNodes.addAll(connectedNodes);
-                    log.debug("Added {} connected nodes to response", connectedNodes.size());
-                }
-            }
-
-            long executionTime = System.currentTimeMillis() - startTime;
-            
-            // Log provenance
-            logProvenance("KNOWLEDGE_GRAPH_QUERY", username,
-                    "Executed knowledge graph query: " + request.getQueryType());
-            
-            return KnowledgeGraphQueryResponse.builder()
-                    .nodes(allNodes)
-                    .relationships(relationships)
-                    .totalCount(allNodes.size())
-                    .executionTimeMs(executionTime)
-                    .metadata("Query type: " + request.getQueryType())
-                    .build();
-        } catch (Exception e) {
-            log.error("Failed to execute knowledge graph query: {}", e.getMessage(), e);
-            return KnowledgeGraphQueryResponse.builder()
-                    .nodes(Collections.emptyList())
-                    .relationships(Collections.emptyList())
-                    .totalCount(0)
-                    .build();
-        }
-    }
-    
-    /**
-     * Fetches relationships for a list of nodes.
-     * Queries SurrealDB for all relationships where any of the nodes is the source (out) or target (in).
-     */
-    private List<KnowledgeGraphRelationship> fetchRelationshipsForNodes(List<KnowledgeGraphNode> nodes) {
-        if (nodes == null || nodes.isEmpty()) {
-            return Collections.emptyList();
-        }
-
-        try {
-            // Build a list of node IDs
-            List<String> nodeIds = nodes.stream()
-                    .map(KnowledgeGraphNode::getId)
-                    .filter(id -> id != null && !id.isEmpty())
-                    .collect(Collectors.toList());
-
-            if (nodeIds.isEmpty()) {
-                return Collections.emptyList();
-            }
-
-            // Query for relationships where any node is source or target
-            // In SurrealDB, relationships are stored in tables named after the relationship type
-            // We query DISCUSSES, CONTAINS_PROCEDURE, RELATED_TO, etc.
-            List<KnowledgeGraphRelationship> allRelationships = new ArrayList<>();
-
-            String[] relationshipTypes = {"DISCUSSES", "CONTAINS_PROCEDURE", "RELATED_TO", "REFERENCES", "SUPERSEDES", "DEPENDS_ON"};
-
-            for (String relType : relationshipTypes) {
-                try {
-                    String query = "SELECT * FROM " + relType + " LIMIT 500";
-                    log.debug("Querying relationships of type {}: {}", relType, query);
-                    List<Object> results = invokeSurrealQuery(query);
-
-                    if (results != null && !results.isEmpty()) {
-                        log.debug("Found {} {} relationships", results.size(), relType);
-                        List<KnowledgeGraphRelationship> relationships = parseRelationshipsFromResults(results, relType);
-
-                        // Filter to only include relationships connected to our nodes
-                        for (KnowledgeGraphRelationship rel : relationships) {
-                            String fromNode = rel.getFromNode();
-                            String toNode = rel.getToNode();
-
-                            // Check if either endpoint is in our node list
-                            if ((fromNode != null && nodeIds.stream().anyMatch(id -> fromNode.contains(id) || id.contains(fromNode))) ||
-                                (toNode != null && nodeIds.stream().anyMatch(id -> toNode.contains(id) || id.contains(toNode)))) {
-                                allRelationships.add(rel);
-                                log.trace("Including relationship: {} -> {} -> {}", fromNode, relType, toNode);
-                            }
-                        }
-                    } else {
-                        log.trace("No {} relationships found", relType);
-                    }
-                } catch (Exception e) {
-                    // Relationship type table might not exist, skip it
-                    log.trace("Could not query relationship type {}: {}", relType, e.getMessage());
-                }
-            }
-
-            log.debug("Fetched {} relationships for {} nodes", allRelationships.size(), nodes.size());
-            return allRelationships;
-
-        } catch (Exception e) {
-            log.error("Failed to fetch relationships for nodes: {}", e.getMessage(), e);
-            return Collections.emptyList();
-        }
-    }
-
-    /**
-     * Parse relationship results from SurrealDB query response.
-     */
-    private List<KnowledgeGraphRelationship> parseRelationshipsFromResults(List<Object> results, String relType) {
-        List<KnowledgeGraphRelationship> relationships = new ArrayList<>();
-
-        try {
-            for (Object result : results) {
-                if (result instanceof Map) {
-                    Map<String, Object> map = (Map<String, Object>) result;
-
-                    // SurrealDB RELATE syntax: RELATE source->TYPE->target
-                    // Stored as: 'out' = source node, 'in' = target node
-                    String fromNode = map.get("out") != null ? map.get("out").toString() : null;
-                    String toNode = map.get("in") != null ? map.get("in").toString() : null;
-                    String id = map.get("id") != null ? map.get("id").toString() : null;
-
-                    Double weight = null;
-                    if (map.get("weight") != null) {
-                        try {
-                            weight = Double.valueOf(map.get("weight").toString());
-                        } catch (NumberFormatException e) {
-                            weight = 1.0;
-                        }
-                    }
-
-                    if (fromNode != null && toNode != null) {
-                        relationships.add(KnowledgeGraphRelationship.builder()
-                                .id(id)
-                                .fromNode(fromNode)
-                                .toNode(toNode)
-                                .relationshipType(relType)
-                                .weight(weight != null ? weight : 1.0)
-                                .build());
-                    }
-                }
-            }
-        } catch (Exception e) {
-            log.warn("Error parsing relationship results: {}", e.getMessage());
-        }
-
-        return relationships;
-    }
-
-    /**
-     * Fetches nodes that are connected via relationships but not in the original node list.
-     * This allows the UI to render the full graph including concept and procedure nodes.
-     */
-    private List<KnowledgeGraphNode> fetchConnectedNodes(List<KnowledgeGraphRelationship> relationships, List<KnowledgeGraphNode> existingNodes) {
-        if (relationships == null || relationships.isEmpty()) {
-            return Collections.emptyList();
-        }
-
-        try {
-            // Get existing node IDs
-            Set<String> existingNodeIds = existingNodes.stream()
-                    .map(KnowledgeGraphNode::getId)
-                    .filter(id -> id != null)
-                    .collect(Collectors.toSet());
-
-            // Find node IDs from relationships that we don't already have
-            Set<String> missingNodeIds = new HashSet<>();
-            for (KnowledgeGraphRelationship rel : relationships) {
-                if (rel.getFromNode() != null && !existingNodeIds.contains(rel.getFromNode())) {
-                    missingNodeIds.add(rel.getFromNode());
-                }
-                if (rel.getToNode() != null && !existingNodeIds.contains(rel.getToNode())) {
-                    missingNodeIds.add(rel.getToNode());
-                }
-            }
-
-            if (missingNodeIds.isEmpty()) {
-                return Collections.emptyList();
-            }
-
-            log.debug("Fetching {} connected nodes: {}", missingNodeIds.size(), missingNodeIds);
-
-            // Query for each missing node
-            List<KnowledgeGraphNode> connectedNodes = new ArrayList<>();
-            for (String nodeId : missingNodeIds) {
-                try {
-                    String escapedNodeId = escapeRecordIdForRelate(nodeId);
-                    String query = "SELECT * FROM " + escapedNodeId;
-                    List<Object> results = invokeSurrealQuery(query);
-
-                    if (results != null && !results.isEmpty()) {
-                        List<KnowledgeGraphNode> nodes = parseNodesToList(results);
-                        connectedNodes.addAll(nodes);
-                    }
-                } catch (Exception e) {
-                    log.trace("Could not fetch connected node {}: {}", nodeId, e.getMessage());
-                }
-            }
-
-            log.debug("Fetched {} connected nodes", connectedNodes.size());
-            return connectedNodes;
-
-        } catch (Exception e) {
-            log.error("Failed to fetch connected nodes: {}", e.getMessage(), e);
-            return Collections.emptyList();
-        }
-    }
-
-    /**
-     * Public method to fetch relationships for a list of node IDs.
-     * Designed to be called async from the UI after the main query returns.
-     * Returns relationships and connected nodes with resolved names.
-     */
-    public Map<String, Object> getRelationshipsForNodeIds(List<String> nodeIds, String username) {
-        Map<String, Object> result = new HashMap<>();
-
-        if (!isSurrealDBAvailable() || nodeIds == null || nodeIds.isEmpty()) {
-            result.put("relationships", Collections.emptyList());
-            result.put("connectedNodes", Collections.emptyList());
-            result.put("relationshipCount", 0);
-            return result;
-        }
-
-        try {
-            // Create minimal node objects for the fetch method
-            List<KnowledgeGraphNode> nodes = nodeIds.stream()
-                .map(id -> KnowledgeGraphNode.builder().id(id).build())
-                .collect(Collectors.toList());
-
-            // Fetch relationships
-            List<KnowledgeGraphRelationship> relationships = fetchRelationshipsForNodes(nodes);
-
-            // Fetch connected nodes
-            List<KnowledgeGraphNode> connectedNodes = Collections.emptyList();
-            if (!relationships.isEmpty()) {
-                connectedNodes = fetchConnectedNodes(relationships, nodes);
-            }
-
-            // Build a map of node ID -> name for the UI to resolve names
-            Map<String, String> nodeNames = new HashMap<>();
-            for (KnowledgeGraphNode node : connectedNodes) {
-                if (node.getId() != null && node.getName() != null) {
-                    nodeNames.put(node.getId(), node.getName());
-                }
-            }
-
-            // Enrich relationships with node names for easier UI display
-            List<Map<String, Object>> enrichedRelationships = new ArrayList<>();
-            for (KnowledgeGraphRelationship rel : relationships) {
-                Map<String, Object> enrichedRel = new HashMap<>();
-                enrichedRel.put("id", rel.getId());
-                enrichedRel.put("fromNode", rel.getFromNode());
-                enrichedRel.put("toNode", rel.getToNode());
-                enrichedRel.put("relationshipType", rel.getRelationshipType());
-                enrichedRel.put("weight", rel.getWeight());
-
-                // Add resolved names
-                String fromName = nodeNames.getOrDefault(rel.getFromNode(), extractNameFromId(rel.getFromNode()));
-                String toName = nodeNames.getOrDefault(rel.getToNode(), extractNameFromId(rel.getToNode()));
-                enrichedRel.put("fromNodeName", fromName);
-                enrichedRel.put("toNodeName", toName);
-
-                enrichedRelationships.add(enrichedRel);
-            }
-
-            result.put("relationships", enrichedRelationships);
-            result.put("connectedNodes", connectedNodes);
-            result.put("relationshipCount", relationships.size());
-            result.put("nodeNames", nodeNames);
-
-            log.info("Fetched {} relationships and {} connected nodes for {} input nodes",
-                relationships.size(), connectedNodes.size(), nodeIds.size());
-
-            return result;
-
-        } catch (Exception e) {
-            log.error("Failed to get relationships for node IDs: {}", e.getMessage(), e);
-            result.put("relationships", Collections.emptyList());
-            result.put("connectedNodes", Collections.emptyList());
-            result.put("relationshipCount", 0);
-            result.put("error", e.getMessage());
-            return result;
-        }
-    }
-
-    /**
-     * Extract a human-readable name from a node ID.
-     * e.g., "concept:⟨unit-testing⟩" -> "unit-testing"
-     */
-    private String extractNameFromId(String nodeId) {
-        if (nodeId == null) return "";
-
-        int colonIndex = nodeId.indexOf(':');
-        if (colonIndex == -1) return nodeId;
-
-        String id = nodeId.substring(colonIndex + 1);
-
-        // Remove angle brackets if present
-        if (id.startsWith("⟨") && id.endsWith("⟩")) {
-            id = id.substring(1, id.length() - 1);
-        }
-
-        // Convert hyphens to spaces and capitalize words
-        return id.replace("-", " ");
-    }
-
-    /**
-     * Deletes a node from the knowledge graph.
-     */
-    public boolean deleteNode(String nodeId, String username) {
-        if (!isSurrealDBAvailable()) {
-            return false;
-        }
-        
-        try {
-            String query = "DELETE " + nodeId;
-            invokeSurrealQuery(query);
-            
-            // Log provenance
-            logProvenance("KNOWLEDGE_GRAPH_NODE_DELETED", username,
-                    "Deleted knowledge graph node: " + nodeId);
-            
-            log.debug("Deleted knowledge graph node: {}", nodeId);
-            return true;
-        } catch (Exception e) {
-            log.error("Failed to delete node: {}", e.getMessage(), e);
-            return false;
-        }
-    }
-    
-    /**
-     * Updates properties of an existing node in the knowledge graph.
-     * Merges the provided properties with the existing node properties.
-     */
-    public boolean updateNodeProperties(String nodeId, Map<String, Object> properties, String username) {
-        if (!isSurrealDBAvailable()) {
-            return false;
-        }
-
-        try {
-            // Build the MERGE query to update properties
-            // This will merge the new properties with existing ones
-            // Use proper record ID escaping for special characters
-            String escapedNodeId = escapeRecordIdForRelate(nodeId);
-            String propertiesJson = objectMapper.writeValueAsString(properties);
-            String query = "UPDATE " + escapedNodeId + " MERGE " + propertiesJson;
-
-            log.info("Executing node properties update for {}: {}", nodeId, query);
-            log.debug("Properties JSON: {}", propertiesJson);
-
-            List<Object> updateResult = invokeSurrealQuery(query);
-            log.info("Update query returned {} results", updateResult.size());
-
-            // Verify the update by querying the node
-            String verifyQuery = "SELECT * FROM " + escapedNodeId;
-            List<Object> verifyResult = invokeSurrealQuery(verifyQuery);
-            log.info("Verification query returned {} results", verifyResult.size());
-
-            if (verifyResult.isEmpty()) {
-                log.error("Node {} not found after update! Update may have failed or corrupted the node", nodeId);
-                return false;
-            }
-
-            // Log provenance
-            logProvenance("KNOWLEDGE_GRAPH_NODE_UPDATED", username,
-                    "Updated knowledge graph node properties: " + nodeId + " with " + properties.size() + " properties");
-
-            log.info("Successfully updated knowledge graph node: {} with {} properties", nodeId, properties.size());
-            return true;
-        } catch (Exception e) {
-            log.error("Failed to update node properties for {}: {}", nodeId, e.getMessage(), e);
-            return false;
-        }
-    }
-
-    // Helper methods
-    
-    private Map<String, Object> buildDocumentProperties(Document document) {
-        Map<String, Object> properties = new HashMap<>();
-        properties.put("document_type", document.getDocumentType());
-        properties.put("file_size", document.getFileSize());
-        properties.put("checksum", document.getChecksum());
-        properties.put("created_at", document.getCreatedAt());
-        if (document.getMetadata() != null && !document.getMetadata().isNull()) {
-            try {
-                // Convert JsonNode to Map
-                Map<String, Object> metadataMap = objectMapper.convertValue(
-                        document.getMetadata(), 
-                        objectMapper.getTypeFactory().constructMapType(Map.class, String.class, Object.class));
-                properties.putAll(metadataMap);
-            } catch (Exception e) {
-                log.warn("Failed to convert metadata to map: {}", e.getMessage());
-            }
-        }
-        return properties;
-    }
-    
-    /**
-     * Get all nodes in the knowledge graph (for debugging/admin purposes).
-     */
-    public List<KnowledgeGraphNode> getAllNodes(int limit) {
-        if (!isSurrealDBAvailable()) {
-            log.warn("SurrealDB not configured");
-            return Collections.emptyList();
-        }
-
-        try {
-            String query = "SELECT * FROM document LIMIT " + limit;
-            log.info("Executing getAllNodes query: {}", query);
-            List<Object> results = invokeSurrealQuery(query);
-            List<KnowledgeGraphNode> nodes = parseNodesToList(results);
-            log.info("getAllNodes returned {} nodes", nodes.size());
-            return nodes;
-        } catch (Exception e) {
-            log.error("Failed to get all nodes: {}", e.getMessage(), e);
-            return Collections.emptyList();
-        }
-    }
-
-    /**
-     * Get knowledge graph statistics.
-     */
-    public Map<String, Object> getStatistics() {
-        Map<String, Object> stats = new HashMap<>();
-        stats.put("enabled", isSurrealDBAvailable());
-        stats.put("database", "surrealdb");
-
-        if (!isSurrealDBAvailable()) {
-            stats.put("nodeCount", 0);
-            stats.put("status", "disconnected");
-            return stats;
-        }
-
-        try {
-            // Count documents
-            String countQuery = "SELECT count() FROM document GROUP ALL";
-            log.debug("Executing count query: {}", countQuery);
-            List<Object> countResult = invokeSurrealQuery(countQuery);
-
-            int nodeCount = 0;
-            if (!countResult.isEmpty()) {
-                Object first = countResult.get(0);
-                if (first instanceof Map) {
-                    @SuppressWarnings("unchecked")
-                    Map<String, Object> countMap = (Map<String, Object>) first;
-                    Object count = countMap.get("count");
-                    if (count instanceof Number) {
-                        nodeCount = ((Number) count).intValue();
-                    }
-                }
-            }
-            stats.put("nodeCount", nodeCount);
-            stats.put("status", "connected");
-
-            // Also try a simple info query
-            String infoQuery = "INFO FOR DB";
-            log.debug("Executing info query: {}", infoQuery);
-            List<Object> infoResult = invokeSurrealQuery(infoQuery);
-            if (!infoResult.isEmpty()) {
-                stats.put("dbInfo", infoResult.get(0));
-            }
-
-        } catch (Exception e) {
-            log.error("Failed to get statistics: {}", e.getMessage(), e);
-            stats.put("status", "error");
-            stats.put("error", e.getMessage());
-        }
-
-        return stats;
-    }
-
-    private List<String> parseTags(String tags) {
-        if (tags == null || tags.isEmpty()) {
-            return Collections.emptyList();
-        }
-        return Arrays.stream(tags.split(","))
-                .map(String::trim)
-                .filter(s -> !s.isEmpty())
-                .collect(Collectors.toList());
-    }
-    
-    private Map<String, Object> nodeToMap(KnowledgeGraphNode node) {
-        Map<String, Object> map = new HashMap<>();
-        map.put("nodeType", node.getNodeType());
-        map.put("name", node.getName());
-        map.put("description", node.getDescription());
-        map.put("entityId", node.getEntityId());
-        map.put("properties", node.getProperties());
-        map.put("markings", node.getMarkings());
-        map.put("createdBy", node.getCreatedBy());
-        map.put("createdAt", node.getCreatedAt());
-        map.put("updatedAt", node.getUpdatedAt());
-        map.put("tags", node.getTags());
-        return map;
-    }
-    
-    private Map<String, Object> relationshipToMap(KnowledgeGraphRelationship relationship) {
-        Map<String, Object> map = new HashMap<>();
-        map.put("relationshipType", relationship.getRelationshipType());
-        map.put("weight", relationship.getWeight());
-        map.put("createdBy", relationship.getCreatedBy());
-        map.put("createdAt", relationship.getCreatedAt());
-        map.put("description", relationship.getDescription());
-        if (relationship.getProperties() != null) {
-            map.putAll(relationship.getProperties());
-        }
-        return map;
-    }
-    
-    private String buildQuery(KnowledgeGraphQueryRequest request) {
-        int limit = request.getLimit() != null ? request.getLimit() : 50;
-        
-        switch (request.getQueryType()) {
-            case SEARCH:
-                return buildSearchQuery(request.getSearchText(), request.getNodeTypes(), limit);
-            case NEIGHBORS:
-                return buildNeighborsQuery(request.getStartNodeId(), limit);
-            case TRAVERSE:
-                int maxDepth = request.getMaxDepth() != null ? request.getMaxDepth() : 2;
-                return buildTraversalQuery(request.getStartNodeId(), maxDepth, limit);
-            case PATH:
-                return buildPathQuery(request.getStartNodeId(), request.getTargetNodeId());
-            case SUBGRAPH:
-                maxDepth = request.getMaxDepth() != null ? request.getMaxDepth() : 2;
-                return buildSubgraphQuery(request.getStartNodeId(), maxDepth, limit);
-            default:
-                return "SELECT * FROM document LIMIT " + limit;
-        }
-    }
-    
-    private String buildSearchQuery(String searchText, List<String> nodeTypes, int limit) {
-        // Handle null or empty search text - return all documents
-        if (searchText == null || searchText.trim().isEmpty()) {
-            log.debug("Empty search text, returning all documents");
-            StringBuilder query = new StringBuilder("SELECT * FROM document");
-
-            if (nodeTypes != null && !nodeTypes.isEmpty()) {
-                query.append(" WHERE nodeType IN [");
-                query.append(nodeTypes.stream()
-                        .map(t -> "'" + t + "'")
-                        .collect(Collectors.joining(", ")));
-                query.append("]");
-            }
-
-            query.append(" LIMIT ").append(limit);
-            return query.toString();
-        }
-
-        // Extract keywords from search text using LLM if available, otherwise use fallback
-        List<String> keywords = extractKeywordsWithLLM(searchText);
-
-        if (keywords.isEmpty()) {
-            // If still no keywords, use the original text as a single keyword (but we know it's not empty)
-            keywords = List.of(searchText.trim());
-        }
-
-        log.debug("Extracted {} keywords from search text: {}", keywords.size(), keywords);
-
-        // Build OR query for each keyword
-        StringBuilder query = new StringBuilder("SELECT * FROM document WHERE (");
-
-        List<String> conditions = new ArrayList<>();
-        for (String keyword : keywords) {
-            if (keyword != null && !keyword.trim().isEmpty()) {
-                String escapedKeyword = escapeString(keyword).toLowerCase();
-                conditions.add("string::lowercase(name) CONTAINS '" + escapedKeyword + "'");
-                conditions.add("string::lowercase(description) CONTAINS '" + escapedKeyword + "'");
-            }
-        }
-
-        // If no valid conditions, return all documents
-        if (conditions.isEmpty()) {
-            log.debug("No valid keywords found, returning all documents");
-            query = new StringBuilder("SELECT * FROM document");
-
-            if (nodeTypes != null && !nodeTypes.isEmpty()) {
-                query.append(" WHERE nodeType IN [");
-                query.append(nodeTypes.stream()
-                        .map(t -> "'" + t + "'")
-                        .collect(Collectors.joining(", ")));
-                query.append("]");
-            }
-
-            query.append(" LIMIT ").append(limit);
-            return query.toString();
-        }
-
-        query.append(String.join(" OR ", conditions));
-        query.append(")");
-
-        if (nodeTypes != null && !nodeTypes.isEmpty()) {
-            query.append(" AND nodeType IN [");
-            query.append(nodeTypes.stream()
-                    .map(t -> "'" + t + "'")
-                    .collect(Collectors.joining(", ")));
-            query.append("]");
-        }
-        
-        query.append(" LIMIT ").append(limit);
-        log.debug("Built search query: {}", query);
-        return query.toString();
-    }
-    
-    private String buildNeighborsQuery(String startNodeId, int limit) {
-        if (startNodeId == null || startNodeId.trim().isEmpty()) {
-            log.warn("NEIGHBORS query requires startNodeId but it was null or empty");
-            return "SELECT * FROM document LIMIT " + limit;
-        }
-        return String.format(
-                "SELECT * FROM %s<-* | *->* LIMIT %d",
-                startNodeId, limit
-        );
-    }
-    
-    private String buildTraversalQuery(String startNodeId, int maxDepth, int limit) {
-        if (startNodeId == null || startNodeId.trim().isEmpty()) {
-            log.warn("TRAVERSE query requires startNodeId but it was null or empty");
-            return "SELECT * FROM document LIMIT " + limit;
-        }
-        return String.format(
-                "SELECT * FROM %s->*..%d LIMIT %d",
-                startNodeId, maxDepth, limit
-        );
-    }
-    
-    private String buildPathQuery(String startNodeId, String targetNodeId) {
-        if (startNodeId == null || startNodeId.trim().isEmpty() ||
-            targetNodeId == null || targetNodeId.trim().isEmpty()) {
-            log.warn("PATH query requires both startNodeId and targetNodeId but one or both were null or empty");
-            return "SELECT * FROM document LIMIT 50";
-        }
-        return String.format(
-                "SELECT * FROM %s<->*<->%s",
-                startNodeId, targetNodeId
-        );
-    }
-    
-    private String buildSubgraphQuery(String startNodeId, int maxDepth, int limit) {
-        if (startNodeId == null || startNodeId.trim().isEmpty()) {
-            log.warn("SUBGRAPH query requires startNodeId but it was null or empty");
-            return "SELECT * FROM document LIMIT " + limit;
-        }
-        return String.format(
-                "SELECT * FROM %s<->*..%d LIMIT %d",
-                startNodeId, maxDepth, limit
-        );
-    }
-    
-    /**
-     * Extract keywords using LLM if available, otherwise fall back to simple extraction.
-     * The LLM can understand the intent of natural language questions and extract relevant search terms.
-     * Only uses LLM for complex queries (questions, multiple words, etc.)
-     */
-    private List<String> extractKeywordsWithLLM(String searchText) {
-        if (llmService == null) {
-            log.debug("LLM service not available, using simple keyword extraction");
-            return extractKeywords(searchText);
-        }
-
-        if (!shouldUseLLMForKeywordExtraction(searchText)) {
-            log.debug("Query is simple, using basic keyword extraction without LLM");
-            return extractKeywords(searchText);
-        }
-
-        try {
-            log.debug("Using LLM to extract keywords from: {}", searchText);
-
-            String prompt = String.format(
-                "Extract 3-5 relevant search keywords from this question for searching a document database. " +
-                "Return ONLY the keywords as a comma-separated list, nothing else.\n\n" +
-                "Question: %s\n\n" +
-                "Keywords:",
-                searchText
-            );
-
-            TokenDTO tokenDTO = TokenDTO.builder().communicationId(UUID.randomUUID().toString()).build();
-            Map<String, Object> llmRequest = Map.of(
-                "model", "gpt-4.1",
-                "messages", List.of(Map.of("role", "user", "content", prompt)),
-                "temperature", 0.3,
-                "max_tokens", 500
-            );
-
-            String response = llmService.askQuestion(tokenDTO, llmRequest);
-
-            if (response != null && !response.trim().isEmpty()) {
-                try {
-                    com.fasterxml.jackson.databind.JsonNode jsonResponse = objectMapper.readTree(response);
-                    String extractedText = null;
-
-                    if (jsonResponse.isArray() && jsonResponse.size() > 0) {
-                        com.fasterxml.jackson.databind.JsonNode firstItem = jsonResponse.get(0);
-                        if (firstItem.has("output") && firstItem.get("output").isArray()) {
-                            com.fasterxml.jackson.databind.JsonNode output = firstItem.get("output").get(0);
-                            if (output.has("content") && output.get("content").isArray()) {
-                                com.fasterxml.jackson.databind.JsonNode content = output.get("content").get(0);
-                                if (content.has("text")) {
-                                    extractedText = content.get("text").asText();
-                                }
-                            }
-                        }
-                    } else if (jsonResponse.has("choices") && jsonResponse.get("choices").isArray()) {
-                        com.fasterxml.jackson.databind.JsonNode choices = jsonResponse.get("choices").get(0);
-                        if (choices.has("message") && choices.get("message").has("content")) {
-                            extractedText = choices.get("message").get("content").asText();
-                        }
-                    }
-
-                    if (extractedText != null && !extractedText.trim().isEmpty()) {
-                        String[] keywordsArray = extractedText.split(",");
-                        List<String> keywords = Arrays.stream(keywordsArray)
-                                .map(String::trim)
-                                .filter(s -> !s.isEmpty())
-                                .collect(Collectors.toList());
-                        log.debug("LLM extracted keywords: {}", keywords);
-                        return keywords;
-                    }
-                } catch (Exception parseEx) {
-                    log.warn("Failed to parse LLM response JSON: {}", parseEx.getMessage());
-                }
-
-                log.warn("Could not extract keywords from LLM response, falling back to simple extraction");
-                return extractKeywords(searchText);
-            } else {
-                log.warn("LLM returned empty response, falling back to simple extraction");
-                return extractKeywords(searchText);
-            }
-
-        } catch (Exception | ZtatException e) {
-            log.warn("Failed to extract keywords using LLM: {}, falling back to simple extraction", e.getMessage());
-            return extractKeywords(searchText);
-        }
-    }
-
-    /**
-     * Determine if we should use LLM for keyword extraction.
-     * Only use LLM for complex queries that would benefit from natural language understanding.
-     */
-    private boolean shouldUseLLMForKeywordExtraction(String searchText) {
-        if (searchText == null || searchText.trim().isEmpty()) {
-            return false;
-        }
-
-        String trimmed = searchText.trim();
-
-        // Don't use LLM for very short queries (1-3 characters)
-        if (trimmed.length() <= 3) {
-            return false;
-        }
-
-        // Don't use LLM for single word queries
-        if (!trimmed.contains(" ")) {
-            return false;
-        }
-
-        // Use LLM for questions (contains question words or ends with ?)
-        String lower = trimmed.toLowerCase();
-        if (lower.endsWith("?") ||
-            lower.startsWith("what ") || lower.startsWith("where ") ||
-            lower.startsWith("when ") || lower.startsWith("who ") ||
-            lower.startsWith("why ") || lower.startsWith("how ") ||
-            lower.startsWith("find ") || lower.startsWith("show ") ||
-            lower.startsWith("search ") || lower.startsWith("list ")) {
-            return true;
-        }
-
-        // Use LLM for longer queries (more than 5 words)
-        if (trimmed.split("\\s+").length > 5) {
-            return true;
-        }
-
-        // Default to simple extraction for everything else
-        return false;
-    }
-
-    /**
-     * Extract meaningful keywords from search text by removing common stop words.
-     * This allows natural language questions to be converted to effective search terms.
-     */
-    private List<String> extractKeywords(String searchText) {
-        if (searchText == null || searchText.trim().isEmpty()) {
-            return Collections.emptyList();
-        }
-
-        // Common stop words to exclude from search
-        Set<String> stopWords = Set.of(
-            "a", "an", "and", "are", "as", "at", "be", "by", "for", "from", "has", "he",
-            "in", "is", "it", "its", "of", "on", "that", "the", "to", "was", "will", "with",
-            "what", "when", "where", "who", "why", "how", "do", "does", "did", "we", "you",
-            "i", "me", "my", "have", "can", "could", "would", "should", "about", "kind", "type"
-        );
-
-        // Tokenize and filter
-        return Arrays.stream(searchText.toLowerCase().split("\\s+"))
-            .map(word -> word.replaceAll("[^a-z0-9-]", "")) // Remove punctuation but keep hyphens
-            .filter(word -> word.length() > 2) // Min 3 characters
-            .filter(word -> !stopWords.contains(word))
-            .distinct()
-            .limit(10) // Limit to 10 keywords to avoid overly complex queries
-            .collect(Collectors.toList());
-    }
-
-    @SuppressWarnings("unchecked")
-    private List<KnowledgeGraphNode> parseNodesToList(List<Object> results) {
-        List<KnowledgeGraphNode> nodes = new ArrayList<>();
-        if (results == null || results.isEmpty()) {
-            log.debug("No results to parse");
-            return nodes;
-        }
-
-        log.debug("Parsing {} results to KnowledgeGraphNode list", results.size());
-
-        for (Object result : results) {
-            try {
-                KnowledgeGraphNode node;
-
-                if (result instanceof Map) {
-                    // Handle Map response from SurrealDB
-                    Map<String, Object> map = (Map<String, Object>) result;
-                    log.debug("Parsing Map result with keys: {}", map.keySet());
-
-                    node = KnowledgeGraphNode.builder()
-                            .id(getStringValue(map, "id"))
-                            .nodeType(getStringValue(map, "nodeType"))
-                            .name(getStringValue(map, "name"))
-                            .description(getStringValue(map, "description"))
-                            .entityId(getLongValue(map, "entityId"))
-                            .markings(getStringValue(map, "markings"))
-                            .createdBy(getStringValue(map, "createdBy"))
-                            .properties((Map<String, Object>) map.get("properties"))
-                            .tags(getStringList(map, "tags"))
-                            .build();
-                } else if (result instanceof KnowledgeGraphNode) {
-                    // Already the correct type
-                    node = (KnowledgeGraphNode) result;
-                } else {
-                    // Try Jackson conversion as fallback
-                    log.debug("Attempting Jackson conversion for type: {}", result.getClass().getName());
-                    node = objectMapper.convertValue(result, KnowledgeGraphNode.class);
-                }
-
-                if (node != null && node.getId() != null) {
-                    nodes.add(node);
-                    log.debug("Successfully parsed node: id={}, name={}", node.getId(), node.getName());
-                }
-            } catch (Exception e) {
-                log.warn("Failed to parse node from result (type: {}): {}",
-                    result != null ? result.getClass().getName() : "null", e.getMessage());
-            }
-        }
-
-        log.info("Parsed {} nodes from {} results", nodes.size(), results.size());
-        return nodes;
-    }
-    
-    private String getStringValue(Map<String, Object> map, String key) {
-        Object value = map.get(key);
-        return value != null ? value.toString() : null;
-    }
-
-    private Long getLongValue(Map<String, Object> map, String key) {
-        Object value = map.get(key);
-        if (value == null) return null;
-        if (value instanceof Number) return ((Number) value).longValue();
-        try {
-            return Long.parseLong(value.toString());
-        } catch (NumberFormatException e) {
-            return null;
-        }
-    }
-
-    @SuppressWarnings("unchecked")
-    private List<String> getStringList(Map<String, Object> map, String key) {
-        Object value = map.get(key);
-        if (value == null) return new ArrayList<>();
-        if (value instanceof List) {
-            return ((List<?>) value).stream()
-                    .map(Object::toString)
-                    .collect(Collectors.toList());
-        }
-        return new ArrayList<>();
-    }
-
-    private List<KnowledgeGraphNode> filterNodesByAccess(List<KnowledgeGraphNode> nodes, String username) {
-        return nodes.stream()
-                .filter(node -> accessControlService.canAccessNode(node, username))
-                .collect(Collectors.toList());
-    }
-    
-    private void logProvenance(String eventType, String username, String description) {
-        if (provenanceLogger == null) {
-            log.debug("ProvenanceLogger not available, skipping knowledge graph event logging");
-            return;
-        }
-        try {
-            // Use UNKNOWN for custom event types not in the enum
-            ProvenanceEvent event = ProvenanceEvent.builder()
-                    .eventType(ProvenanceEvent.EventType.UNKNOWN)
-                    .actor(username)
-                    .timestamp(java.time.Instant.now())
-                    .outputSummary(eventType + ": " + description)
-                    .build();
-            provenanceLogger.log(event);
-        } catch (Exception e) {
-            log.error("Failed to log provenance event: {}", e.getMessage());
-        }
-    }
-    
-    /**
-     * Invoke a SurrealDB query using the SDK.
-     * Creates a fresh connection for each query to respect dynamic configuration.
-     * Returns results as a list for processing.
-     */
-    @SuppressWarnings("unchecked")
-    private List<Object> invokeSurrealQuery(String query) {
-        if (!isSurrealDBAvailable()) {
-            log.info("SurrealDB not configured, cannot execute query");
-            return Collections.emptyList();
-        }
-        
-        Surreal surrealDB = null;
-        try {
-            log.debug("Executing SurrealDB query: {}", query);
-
-            // Get a fresh connection for this query
-            surrealDB = connectionProvider.getConnection();
-            if (surrealDB == null) {
-                log.warn("Failed to get SurrealDB connection");
-                return Collections.emptyList();
-            }
-
-            // Use the SurrealDB SDK query method which returns a Response object
-            Response response = surrealDB.query(query);
-
-            log.debug("SurrealDB response size: {}", response.size());
-
-            // Parse the response - Response.take(index) gets result set at index
-            if (response.size() > 0) {
-                try {
-                    // Get the raw Value object first to see what we have
-                    Value value = response.take(0);
-                    String valueStr = value.toString();
-                    log.debug("SurrealDB raw value: {}", valueStr);
-
-                    // The Value.toString() returns the SurrealDB format like:
-                    // [{ field: 'value', ... }, { field: 'value', ... }]
-                    // We need to convert this to valid JSON and parse it
-
-                    if (valueStr == null || valueStr.equals("[]") || valueStr.equals("NONE")) {
-                        log.debug("SurrealDB returned empty or NONE result");
-                        return Collections.emptyList();
-                    }
-
-                    // Convert SurrealDB format to JSON and parse
-                    if (valueStr.startsWith("[")) {
-                        String jsonContent = convertSurrealResponseToJson(valueStr);
-                        log.debug("Converted to JSON: {}", jsonContent);
-
-                        List<Object> parsed = objectMapper.readValue(jsonContent,
-                            objectMapper.getTypeFactory().constructCollectionType(List.class, Object.class));
-
-                        if (parsed != null && !parsed.isEmpty()) {
-                            log.info("SurrealDB query returned {} results", parsed.size());
-                            return parsed;
-                        }
-                    } else if (valueStr.startsWith("{")) {
-                        // Single object result
-                        String jsonContent = convertSurrealResponseToJson(valueStr);
-                        Object parsed = objectMapper.readValue(jsonContent, Object.class);
-                        if (parsed != null) {
-                            log.info("SurrealDB query returned single result");
-                            return Collections.singletonList(parsed);
-                        }
-                    }
-
-                    log.debug("SurrealDB returned unrecognized format: {}", valueStr);
-                    return Collections.emptyList();
-
-                } catch (Exception e) {
-                    log.error("Failed to parse SurrealDB response: {}", e.getMessage(), e);
-                    return Collections.emptyList();
-                }
-            } else {
-                log.debug("SurrealDB response has no result sets");
-            }
-            
-            log.debug("Executed SurrealDB query successfully, no results returned");
-            return Collections.emptyList();
-        } catch (Exception e) {
-            log.error("Failed to execute SurrealDB query: {}", e.getMessage(), e);
-            return Collections.emptyList();
-        } finally {
-            // Always close the connection after use
-            if (surrealDB != null) {
-                try {
-                    surrealDB.close();
-                } catch (Exception e) {
-                    log.warn("Error closing SurrealDB connection: {}", e.getMessage());
-                }
-            }
-        }
-    }
-
-    /**
-     * Parse results from SurrealDB SDK error message.
-     * The SDK sometimes throws "Unexpected value: [data...]" when it can't deserialize,
-     * but the actual data is in the error message.
-     */
-    private List<Object> parseResultsFromErrorMessage(String errorMessage) {
-        try {
-            log.debug("Parsing SurrealDB results from error message");
-            String jsonContent = errorMessage.substring("Unexpected value: ".length());
-            jsonContent = convertSurrealResponseToJson(jsonContent);
-
-            List<Object> parsed = objectMapper.readValue(jsonContent,
-                objectMapper.getTypeFactory().constructCollectionType(List.class, Object.class));
-
-            if (parsed != null && !parsed.isEmpty()) {
-                log.info("SurrealDB query returned {} results (parsed from response)", parsed.size());
-                return parsed;
-            }
-        } catch (Exception parseEx) {
-            log.warn("Failed to parse SurrealDB response from error message: {}", parseEx.getMessage());
-        }
-        return Collections.emptyList();
-    }
-
-    /**
-     * Convert SurrealDB's Value.toString() format to valid JSON.
-     *
-     * SurrealDB returns data like:
-     *   [{ markings: 'PRIVATE', id: document:2, name: 'test' }]
-     *
-     * We need to convert to:
-     *   [{ "markings": "PRIVATE", "id": "document:2", "name": "test" }]
-     */
-    private String convertSurrealResponseToJson(String surrealResponse) {
-        if (surrealResponse == null || surrealResponse.isEmpty()) {
-            return "[]";
-        }
-
-        StringBuilder result = new StringBuilder();
-        int i = 0;
-        int len = surrealResponse.length();
-
-        while (i < len) {
-            char c = surrealResponse.charAt(i);
-
-            if (c == '"') {
-                // Already a double-quoted string - copy it as-is (it's already valid JSON)
-                result.append('"');
-                i++;
-                while (i < len) {
-                    char ch = surrealResponse.charAt(i);
-
-                    // Handle escaped characters
-                    if (ch == '\\' && i + 1 < len) {
-                        result.append(ch).append(surrealResponse.charAt(i + 1));
-                        i += 2;
-                        continue;
-                    }
-
-                    // End of string
-                    if (ch == '"') {
-                        result.append('"');
-                        i++;
-                        break;
-                    }
-
-                    result.append(ch);
-                    i++;
-                }
-            } else if (c == '\'') {
-                // Convert single-quoted string to double-quoted
-                result.append('"');
-                i++;
-                while (i < len) {
-                    char ch = surrealResponse.charAt(i);
-
-                    // Check for escaped single quote
-                    if (ch == '\\' && i + 1 < len && surrealResponse.charAt(i + 1) == '\'') {
-                        result.append("\\'");
-                        i += 2;
-                        continue;
-                    }
-
-                    // End of string - found unescaped single quote
-                    if (ch == '\'') {
-                        break;
-                    }
-
-                    // Escape special JSON characters
-                    if (ch == '"') {
-                        result.append('\\').append('"');
-                    } else if (ch == '\\') {
-                        result.append('\\').append('\\');
-                    } else if (ch == '\n') {
-                        result.append('\\').append('n');
-                    } else if (ch == '\r') {
-                        result.append('\\').append('r');
-                    } else if (ch == '\t') {
-                        result.append('\\').append('t');
-                    } else if (ch == '\b') {
-                        result.append('\\').append('b');
-                    } else if (ch == '\f') {
-                        result.append('\\').append('f');
-                    } else if (ch < 32 || ch == 127) {
-                        // Escape other control characters
-                        result.append(String.format("\\u%04x", (int) ch));
-                    } else {
-                        result.append(ch);
-                    }
-
-                    i++;
-                }
-                result.append('"');
-                i++; // skip closing quote
-            } else if (c == '{' || c == ',') {
-                result.append(c);
-                i++;
-                // Skip whitespace
-                while (i < len && Character.isWhitespace(surrealResponse.charAt(i))) {
-                    result.append(surrealResponse.charAt(i));
-                    i++;
-                }
-                // Check if next token is an unquoted property name
-                if (i < len && (Character.isLetter(surrealResponse.charAt(i)) || surrealResponse.charAt(i) == '_')) {
-                    // Find the property name (ends at ':')
-                    int start = i;
-                    while (i < len && surrealResponse.charAt(i) != ':' && surrealResponse.charAt(i) != '}') {
-                        i++;
-                    }
-                    String propName = surrealResponse.substring(start, i).trim();
-                    result.append('"').append(propName).append('"');
-                }
-            } else if (c == ':') {
-                result.append(c);
-                i++;
-                // Skip whitespace after colon
-                while (i < len && Character.isWhitespace(surrealResponse.charAt(i))) {
-                    result.append(surrealResponse.charAt(i));
-                    i++;
-                }
-                // Check if value is unquoted (not starting with ', ", [, {, or digit, or true/false/null)
-                if (i < len) {
-                    char nextChar = surrealResponse.charAt(i);
-
-                    // Handle numeric values (may have type suffix like 0.8f, 123i64, etc.)
-                    if (Character.isDigit(nextChar) || nextChar == '-') {
-                        int start = i;
-                        // Read the numeric part (digits, dots, minus, e/E for scientific notation)
-                        while (i < len && (Character.isDigit(surrealResponse.charAt(i)) ||
-                                          surrealResponse.charAt(i) == '.' ||
-                                          surrealResponse.charAt(i) == '-' ||
-                                          surrealResponse.charAt(i) == 'e' ||
-                                          surrealResponse.charAt(i) == 'E' ||
-                                          surrealResponse.charAt(i) == '+')) {
-                            i++;
-                        }
-                        // Skip any type suffix (f, d, i64, dec, etc.)
-                        while (i < len && (Character.isLetter(surrealResponse.charAt(i)) ||
-                                          Character.isDigit(surrealResponse.charAt(i)))) {
-                            i++;
-                        }
-                        // Extract just the numeric part (without suffix)
-                        String numStr = surrealResponse.substring(start, i).trim();
-                        // Remove any trailing type suffix
-                        numStr = numStr.replaceAll("[a-zA-Z]+[0-9]*$", "");
-                        result.append(numStr);
-                    } else if (nextChar != '\'' && nextChar != '"' && nextChar != '[' && nextChar != '{') {
-                        // Could be: true, false, null, NULL, or an unquoted value like document:2
-                        int start = i;
-                        while (i < len && !isValueTerminator(surrealResponse.charAt(i))) {
-                            i++;
-                        }
-                        String value = surrealResponse.substring(start, i).trim();
-                        // Check if it's a boolean or null (SurrealDB uses NULL uppercase)
-                        if (value.equals("true") || value.equals("false") ||
-                            value.equals("null") || value.equals("NULL")) {
-                            result.append(value.toLowerCase());
-                        } else {
-                            // It's an unquoted string value (like document:2)
-                            result.append('"').append(value).append('"');
-                        }
-                    }
-                }
-            } else {
-                result.append(c);
-                i++;
-            }
-        }
-
-        return result.toString();
-    }
-
-    /**
-     * Check if character terminates a value in SurrealDB format.
-     */
-    private boolean isValueTerminator(char c) {
-        return c == ',' || c == '}' || c == ']' || c == '\n';
-    }
-
-    /**
-     * Answer a natural language question about documents and the knowledge graph using LLM.
-     * This method:
-     * 1. Extracts key terms from the question
-     * 2. Searches for relevant documents by content (not just graph nodes)
-     * 3. Queries the knowledge graph for relationships
-     * 4. Retrieves actual document content for context
-     * 5. Uses LLM to synthesize a natural language answer
-     *
-     * @param question Natural language question (e.g., "What do the documents say about agents?" or "How are the contrib guide and agents related?")
-     * @param username User asking the question
-     * @return Map containing the answer, context documents, nodes, and metadata
-     */
-    public Map<String, Object> answerQuestion(String question, String username) {
-        log.info("Answering document question: {}", question);
-
-        Map<String, Object> result = new HashMap<>();
-        result.put("question", question);
-
-        if (llmService == null) {
-            log.warn("LLMService not available - cannot answer question");
-            result.put("answer", "I'm sorry, but the LLM service is not available to answer your question.");
-            result.put("error", "LLM service not configured");
-            return result;
-        }
-
-        try {
-            // Extract key terms from the question to search for in the graph
-            List<String> keyTerms = extractKeyTermsFromQuestion(question);
-            log.debug("Extracted key terms from question: {}", keyTerms);
-
-            // Search for relevant nodes in the knowledge graph
-            List<KnowledgeGraphNode> relevantNodes = new ArrayList<>();
-            List<KnowledgeGraphRelationship> relevantRelationships = new ArrayList<>();
-            List<Map<String, Object>> relevantDocuments = new ArrayList<>();
-
-            for (String term : keyTerms) {
-                // Search knowledge graph nodes - include relationships for LLM context
-                KnowledgeGraphQueryRequest searchRequest = KnowledgeGraphQueryRequest.builder()
-                        .queryType(KnowledgeGraphQueryRequest.QueryType.SEARCH)
-                        .searchText(term)
-                        .limit(5)
-                        .build();
-
-                // Use includeRelationships=true for LLM answering - the graph structure helps provide better context
-                KnowledgeGraphQueryResponse searchResponse = executeQuery(searchRequest, username, true);
-                if (searchResponse.getNodes() != null) {
-                    relevantNodes.addAll(searchResponse.getNodes());
-                }
-                if (searchResponse.getRelationships() != null) {
-                    relevantRelationships.addAll(searchResponse.getRelationships());
-                }
-
-                // Also search actual document content via document service
-                try {
-                    List<Map<String, Object>> docs = searchDocumentContent(term, username);
-                    relevantDocuments.addAll(docs);
-                } catch (Exception e) {
-                    log.warn("Failed to search document content for term '{}': {}", term, e.getMessage());
-                }
-            }
-
-            // Remove duplicates
-            relevantNodes = relevantNodes.stream()
-                    .distinct()
-                    .limit(10)
-                    .collect(java.util.stream.Collectors.toList());
-            relevantRelationships = relevantRelationships.stream()
-                    .distinct()
-                    .limit(20)
-                    .collect(java.util.stream.Collectors.toList());
-
-            // Deduplicate documents by ID
-            Map<Object, Map<String, Object>> uniqueDocs = new java.util.LinkedHashMap<>();
-            for (Map<String, Object> doc : relevantDocuments) {
-                Object docId = doc.get("id");
-                if (docId != null && !uniqueDocs.containsKey(docId)) {
-                    uniqueDocs.put(docId, doc);
-                    if (uniqueDocs.size() >= 5) break; // Limit to top 5 documents
-                }
-            }
-            relevantDocuments = new ArrayList<>(uniqueDocs.values());
-
-            log.info("Found {} relevant nodes, {} relationships, and {} documents for question",
-                    relevantNodes.size(), relevantRelationships.size(), relevantDocuments.size());
-
-            // Build comprehensive context for LLM including document content
-            String context = buildComprehensiveContext(relevantNodes, relevantRelationships, relevantDocuments);
-
-            // Use LLM to answer the question
-            String answer = askLLMToAnswerQuestion(question, context);
-
-            result.put("answer", answer);
-            result.put("contextNodes", relevantNodes);
-            result.put("contextRelationships", relevantRelationships);
-            result.put("contextDocuments", relevantDocuments);
-            result.put("contextNodeCount", relevantNodes.size());
-            result.put("contextRelationshipCount", relevantRelationships.size());
-            result.put("contextDocumentCount", relevantDocuments.size());
-
-        } catch (Exception e) {
-            log.error("Failed to answer question: {}", e.getMessage(), e);
-            result.put("answer", "I encountered an error while trying to answer your question: " + e.getMessage());
-            result.put("error", e.getMessage());
-        }
-
-        return result;
-    }
-
-    /**
-     * Search for documents by content using the document search API.
-     * Returns document summaries and excerpts relevant to the search term.
-     * This method now fetches the full document content from the database for richer context.
-     */
-    private List<Map<String, Object>> searchDocumentContent(String searchTerm, String username) {
-        List<Map<String, Object>> documents = new ArrayList<>();
-
-        // Early return if DocumentRepository is not available
-        if (documentRepository == null) {
-            log.debug("DocumentRepository not available, using node metadata only");
-            return documents;
-        }
-
-        try {
-            // First, search knowledge graph nodes to find relevant document IDs
-            KnowledgeGraphQueryRequest searchRequest = KnowledgeGraphQueryRequest.builder()
-                    .queryType(KnowledgeGraphQueryRequest.QueryType.SEARCH)
-                    .searchText(searchTerm)
-                    .nodeTypes(java.util.Arrays.asList("document"))
-                    .limit(5)
-                    .build();
-
-            KnowledgeGraphQueryResponse response = executeQuery(searchRequest, username);
-
-            if (response.getNodes() != null && !response.getNodes().isEmpty()) {
-                // Collect all document IDs to batch fetch (avoid N+1 query problem)
-                List<Long> documentIds = new ArrayList<>();
-                Map<Long, KnowledgeGraphNode> nodesByDocId = new HashMap<>();
-                
-                for (KnowledgeGraphNode node : response.getNodes()) {
-                    if ("document".equalsIgnoreCase(node.getNodeType()) && node.getEntityId() != null) {
-                        documentIds.add(node.getEntityId());
-                        nodesByDocId.put(node.getEntityId(), node);
-                    }
-                }
-
-                if (!documentIds.isEmpty()) {
-                    // Batch fetch all documents in a single query
-                    List<Document> fetchedDocuments = documentRepository.findAllById(documentIds);
-                    
-                    for (Document document : fetchedDocuments) {
-                        try {
-                            // Check access control with proper evaluator
-                            // Note: Passing null evaluator means complex markings won't be fully evaluated
-                            // This is acceptable for knowledge graph search but should be improved with proper AccessEvaluator
-                            if (!accessControlService.canAccessDocument(document, null, username)) {
-                                log.debug("User {} does not have access to document {}", username, document.getId());
-                                continue;
-                            }
-                            
-                            Map<String, Object> doc = new HashMap<>();
-                            doc.put("id", document.getId());
-                            doc.put("name", document.getDocumentName());
-                            doc.put("description", document.getSummary());
-                            doc.put("summary", document.getSummary());
-                            doc.put("type", document.getDocumentType());
-                            
-                            // Include the full content for richer context
-                            String content = document.getContent();
-                            if (content != null && !content.isEmpty()) {
-                                // Extract relevant excerpts from the content based on search term
-                                String excerpt = extractRelevantExcerpt(content, searchTerm);
-                                doc.put("content", content); // Full content for comprehensive answers
-                                doc.put("excerpt", excerpt); // Relevant excerpt for context summary
-                            } else {
-                                doc.put("content", "");
-                                doc.put("excerpt", "");
-                            }
-                            
-                            documents.add(doc);
-                        } catch (Exception e) {
-                            log.warn("Error processing document {}: {}", document.getId(), e.getMessage());
-                        }
-                    }
-                }
-            }
-        } catch (Exception e) {
-            log.warn("Error searching document content: {}", e.getMessage());
-        }
-
-        return documents;
-    }
-
-    /**
-     * Extract relevant excerpt from document content based on search term.
-     * Returns a snippet around the first occurrence of the search term, or the beginning if not found.
-     */
-    private String extractRelevantExcerpt(String content, String searchTerm) {
-        if (content == null || content.isEmpty()) {
-            return "";
-        }
-        
-        // Find the first occurrence of the search term (case-insensitive)
-        int index = content.toLowerCase().indexOf(searchTerm.toLowerCase());
-        
-        if (index >= 0) {
-            // Extract content around the search term
-            int start = Math.max(0, index - EXCERPT_LENGTH / 2);
-            int end = Math.min(content.length(), index + searchTerm.length() + EXCERPT_LENGTH / 2);
-            
-            // Adjust start to not break words if possible
-            if (start > 0 && start < content.length()) {
-                int spaceIndex = content.lastIndexOf(' ', start);
-                if (spaceIndex > 0 && start - spaceIndex < 20) {
-                    start = spaceIndex + 1;
-                }
-            }
-            
-            // Adjust end to not break words if possible
-            if (end < content.length()) {
-                int spaceIndex = content.indexOf(' ', end);
-                if (spaceIndex > 0 && spaceIndex - end < 20) {
-                    end = spaceIndex;
-                }
-            }
-            
-            String excerpt = content.substring(start, end);
-            
-            // Add ellipsis if we didn't start/end at document boundaries
-            if (start > 0) excerpt = "..." + excerpt;
-            if (end < content.length()) excerpt = excerpt + "...";
-            
-            return excerpt;
-        } else {
-            // If search term not found, return the beginning of the document
-            int end = Math.min(content.length(), EXCERPT_LENGTH);
-            
-            // Try to end at a word boundary
-            if (end < content.length()) {
-                int spaceIndex = content.indexOf(' ', end);
-                if (spaceIndex > 0 && spaceIndex - end < 20) {
-                    end = spaceIndex;
-                }
-            }
-            
-            String excerpt = content.substring(0, end);
-            if (end < content.length()) excerpt = excerpt + "...";
-            return excerpt;
-        }
-    }
-
-    /**
-     * Build comprehensive context including both graph structure and document content.
-     */
-    private String buildComprehensiveContext(List<KnowledgeGraphNode> nodes,
-                                            List<KnowledgeGraphRelationship> relationships,
-                                            List<Map<String, Object>> documents) {
-        StringBuilder context = new StringBuilder();
-
-        context.append("DOCUMENT KNOWLEDGE BASE:\n\n");
-
-        // Add document content first (most important for content questions)
-        if (!documents.isEmpty()) {
-            context.append("===== DOCUMENT CONTENT =====\n\n");
-            for (Map<String, Object> doc : documents) {
-                context.append("Document: ").append(doc.get("name")).append("\n");
-                context.append("Type: ").append(doc.get("type")).append("\n");
-                
-                if (doc.get("summary") != null && !doc.get("summary").toString().isEmpty()) {
-                    context.append("Summary: ").append(doc.get("summary")).append("\n");
-                }
-                
-                // Include the full content or relevant excerpt
-                if (doc.get("content") != null && !doc.get("content").toString().isEmpty()) {
-                    String content = doc.get("content").toString();
-                    // If content is very long, prefer the excerpt, otherwise use full content
-                    if (content.length() > MAX_FULL_CONTENT_LENGTH && doc.get("excerpt") != null) {
-                        context.append("\nRelevant Excerpt:\n").append(doc.get("excerpt")).append("\n");
-                    } else {
-                        context.append("\nFull Content:\n").append(content).append("\n");
-                    }
-                } else if (doc.get("description") != null && !doc.get("description").toString().isEmpty()) {
-                    context.append("Description: ").append(doc.get("description")).append("\n");
-                }
-                context.append("\n---\n\n");
-            }
-        }
-
-        // Add extracted knowledge from graph nodes (key facts, procedures, concepts)
-        boolean hasExtractedContent = false;
-        for (KnowledgeGraphNode node : nodes) {
-            if (node.getProperties() != null && 
-                (node.getProperties().containsKey("keyFacts") || 
-                 node.getProperties().containsKey("procedures") ||
-                 node.getProperties().containsKey("concepts"))) {
-                hasExtractedContent = true;
-                break;
-            }
-        }
-        
-        if (hasExtractedContent) {
-            context.append("===== EXTRACTED KNOWLEDGE =====\n\n");
-            for (KnowledgeGraphNode node : nodes) {
-                if (node.getProperties() == null) continue;
-                
-                boolean nodeHasContent = false;
-                StringBuilder nodeContent = new StringBuilder();
-                
-                // Add key facts
-                if (node.getProperties().containsKey("keyFacts")) {
-                    Object keyFacts = node.getProperties().get("keyFacts");
-                    if (keyFacts instanceof List) {
-                        @SuppressWarnings("unchecked")
-                        List<String> facts = (List<String>) keyFacts;
-                        if (!facts.isEmpty()) {
-                            nodeContent.append("Key Facts from ").append(node.getName()).append(":\n");
-                            for (String fact : facts) {
-                                nodeContent.append("  • ").append(fact).append("\n");
-                            }
-                            nodeHasContent = true;
-                        }
-                    }
-                }
-                
-                // Add procedures
-                if (node.getProperties().containsKey("procedures")) {
-                    Object procedures = node.getProperties().get("procedures");
-                    if (procedures instanceof List) {
-                        @SuppressWarnings("unchecked")
-                        List<Map<String, Object>> procs = (List<Map<String, Object>>) procedures;
-                        if (!procs.isEmpty()) {
-                            nodeContent.append("\nProcedures from ").append(node.getName()).append(":\n");
-                            for (Map<String, Object> proc : procs) {
-                                nodeContent.append("  ▶ ").append(proc.get("name")).append(":\n");
-                                if (proc.containsKey("steps") && proc.get("steps") instanceof List) {
-                                    @SuppressWarnings("unchecked")
-                                    List<String> steps = (List<String>) proc.get("steps");
-                                    for (int i = 0; i < steps.size(); i++) {
-                                        nodeContent.append("    ").append(i + 1).append(". ").append(steps.get(i)).append("\n");
-                                    }
-                                }
-                            }
-                            nodeHasContent = true;
-                        }
-                    }
-                }
-                
-                // Add concepts
-                if (node.getProperties().containsKey("concepts")) {
-                    Object concepts = node.getProperties().get("concepts");
-                    if (concepts instanceof List) {
-                        @SuppressWarnings("unchecked")
-                        List<String> conceptList = (List<String>) concepts;
-                        if (!conceptList.isEmpty()) {
-                            nodeContent.append("\nKey Concepts in ").append(node.getName()).append(": ");
-                            nodeContent.append(String.join(", ", conceptList)).append("\n");
-                            nodeHasContent = true;
-                        }
-                    }
-                }
-                
-                if (nodeHasContent) {
-                    context.append(nodeContent).append("\n");
-                }
-            }
-            context.append("\n");
-        }
-
-        // Add graph nodes
-        if (!nodes.isEmpty()) {
-            context.append("===== KNOWLEDGE GRAPH NODES =====\n");
-            for (KnowledgeGraphNode node : nodes) {
-                context.append("• ").append(node.getName())
-                       .append(" (").append(node.getNodeType()).append(")");
-                if (node.getDescription() != null && !node.getDescription().isEmpty()) {
-                    context.append(": ").append(node.getDescription());
-                }
-                context.append("\n");
-            }
-            context.append("\n");
-        }
-
-        // Add relationships with human-readable names
-        if (!relationships.isEmpty()) {
-            // Build a name lookup map from nodes
-            Map<String, String> nodeNames = new HashMap<>();
-            for (KnowledgeGraphNode node : nodes) {
-                if (node.getId() != null && node.getName() != null) {
-                    nodeNames.put(node.getId(), node.getName());
-                }
-            }
-
-            context.append("===== DOCUMENT RELATIONSHIPS =====\n");
-            context.append("(These relationships show how documents, concepts, and procedures are connected)\n\n");
-
-            for (KnowledgeGraphRelationship rel : relationships) {
-                // Get readable names, falling back to extracting from ID
-                String fromName = nodeNames.getOrDefault(rel.getFromNode(), extractNameFromId(rel.getFromNode()));
-                String toName = nodeNames.getOrDefault(rel.getToNode(), extractNameFromId(rel.getToNode()));
-
-                // Format relationship type for readability
-                String relType = rel.getRelationshipType();
-                String readableRelType = formatRelationshipType(relType);
-
-                context.append("• ").append(fromName)
-                       .append(" ").append(readableRelType).append(" ")
-                       .append(toName);
-                if (rel.getProperties() != null && rel.getProperties().containsKey("reason")) {
-                    context.append("\n  Reason: ").append(rel.getProperties().get("reason"));
-                }
-                context.append("\n");
-            }
-        }
-
-        if (documents.isEmpty() && nodes.isEmpty() && relationships.isEmpty()) {
-            context.append("No relevant information found in the document knowledge base.\n");
-        }
-
-        return context.toString();
-    }
-
-    /**
-     * Format a relationship type for human readability.
-     * e.g., "DISCUSSES" -> "discusses", "CONTAINS_PROCEDURE" -> "contains procedure"
-     */
-    private String formatRelationshipType(String relType) {
-        if (relType == null) return "relates to";
-
-        switch (relType.toUpperCase()) {
-            case "DISCUSSES": return "discusses";
-            case "CONTAINS_PROCEDURE": return "contains procedure";
-            case "RELATED_TO": return "is related to";
-            case "REFERENCES": return "references";
-            case "SUPERSEDES": return "supersedes";
-            case "DEPENDS_ON": return "depends on";
-            default: return relType.toLowerCase().replace("_", " ");
-        }
-    }
-
-    /**
-     * Extract key terms from a natural language question to search the graph.
-     */
-    private List<String> extractKeyTermsFromQuestion(String question) {
-        // Remove common question words and split into terms
-        String[] stopWords = {"how", "what", "why", "when", "where", "who", "are", "is", "the", "a", "an",
-                              "and", "or", "of", "to", "in", "for", "on", "with", "by", "from", "as", "at",
-                              "be", "been", "being", "was", "were", "can", "could", "would", "should", "do",
-                              "does", "did", "have", "has", "had", "related", "connected", "linked"};
-
-        String cleaned = question.toLowerCase()
-                .replaceAll("[^a-z0-9\\s-]", " ")
-                .trim();
-
-        List<String> terms = new ArrayList<>();
-        for (String word : cleaned.split("\\s+")) {
-            // Skip stop words and very short terms
-            if (word.length() > 2 && !java.util.Arrays.asList(stopWords).contains(word)) {
-                terms.add(word);
-            }
-        }
-
-        // Also extract potential compound terms (e.g., "contrib guide")
-        String[] bigrams = question.toLowerCase().split("\\s+");
-        for (int i = 0; i < bigrams.length - 1; i++) {
-            String bigram = bigrams[i] + " " + bigrams[i + 1];
-            if (bigram.length() > 5 && !bigram.matches(".*\\b(" + String.join("|", stopWords) + ")\\b.*")) {
-                terms.add(bigram);
-            }
-        }
-
-        return terms.stream().distinct().collect(java.util.stream.Collectors.toList());
-    }
-
-    /**
-     * Build a text context summary from nodes and relationships for the LLM.
-     */
-    private String buildGraphContext(List<KnowledgeGraphNode> nodes,
-                                     List<KnowledgeGraphRelationship> relationships) {
-        StringBuilder context = new StringBuilder();
-
-        context.append("KNOWLEDGE GRAPH CONTEXT:\n\n");
-
-        if (!nodes.isEmpty()) {
-            context.append("NODES:\n");
-            for (KnowledgeGraphNode node : nodes) {
-                context.append("- ").append(node.getName())
-                       .append(" (").append(node.getNodeType()).append(")");
-                if (node.getDescription() != null && !node.getDescription().isEmpty()) {
-                    context.append(": ").append(node.getDescription());
-                }
-                context.append("\n");
-            }
-            context.append("\n");
-        }
-
-        if (!relationships.isEmpty()) {
-            context.append("RELATIONSHIPS:\n");
-            for (KnowledgeGraphRelationship rel : relationships) {
-                context.append("- ").append(rel.getFromNode())
-                       .append(" -[").append(rel.getRelationshipType()).append("]-> ")
-                       .append(rel.getToNode());
-                if (rel.getProperties() != null && rel.getProperties().containsKey("reason")) {
-                    context.append(" (").append(rel.getProperties().get("reason")).append(")");
-                }
-                context.append("\n");
-            }
-        }
-
-        if (nodes.isEmpty() && relationships.isEmpty()) {
-            context.append("No relevant information found in the knowledge graph.\n");
-        }
-
-        return context.toString();
-    }
-
-    /**
-     * Use LLM to generate a natural language answer based on the question and graph context.
-     */
-    private String askLLMToAnswerQuestion(String question, String graphContext) {
-        try {
-            // Create agent execution for LLM service
-            io.sentrius.sso.core.dto.UserDTO systemUser = io.sentrius.sso.core.dto.UserDTO.builder()
-                    .username("knowledge-graph-assistant")
-                    .build();
-
-            // Use AgentExecutionService to create proper AgentExecution
-            io.sentrius.sso.core.services.agents.AgentExecutionService executionService =
-                    new io.sentrius.sso.core.services.agents.AgentExecutionService();
-            io.sentrius.sso.core.dto.agents.AgentExecution agentExecution =
-                    executionService.getAgentExecution(systemUser);
-            agentExecution.setCommunicationId(java.util.UUID.randomUUID().toString());
-
-            String systemPrompt = "You are a knowledge graph assistant that answers questions by EXTRACTING AND SYNTHESIZING information from the provided document content. " +
-                    "The knowledge base includes:\n" +
-                    "- Full document content\n" +
-                    "- Extracted key facts and procedures from documents\n" +
-                    "- Concepts and topics discovered through analysis\n" +
-                    "- Relationships between documents\n" +
-                    "\n" +
-                    "CRITICAL RULES:\n" +
-                    "1. NEVER tell users to 'refer to' or 'consult' a document - you must answer the question directly using the content provided\n" +
-                    "2. Extract specific steps, procedures, code examples, or instructions from the document content\n" +
-                    "3. Synthesize information from multiple sources (full content, extracted facts, procedures)\n" +
-                    "4. When you cite sources, use them to support your answer - not replace it\n" +
-                    "5. If the content is insufficient to answer fully, say what you CAN answer from the content, then explain what's missing\n" +
-                    "\n" +
-                    "CORRECT ANSWER PATTERN:\n" +
-                    "Q: How do I create a custom agent?\n" +
-                    "A: To create a custom agent, you need to:\n" +
-                    "   1. Create a new directory under python-agent/agents/ with your agent name\n" +
-                    "   2. Add an __init__.py file and your main agent implementation file\n" +
-                    "   3. Register the agent in main.py by importing it and adding to the registry\n" +
-                    "   (Source: CUSTOM_AGENTS.md)\n" +
-                    "\n" +
-                    "FORBIDDEN ANSWER PATTERN:\n" +
-                    "Q: How do I create a custom agent?\n" +
-                    "A: You should refer to the CUSTOM_AGENTS.md document for instructions.\n" +
-                    "A: Please consult the agents documentation.\n" +
-                    "A: See the CUSTOM_AGENTS.md file for details.\n" +
-                    "\n" +
-                    "Answer questions FROM the knowledge graph content, not ABOUT the knowledge graph content.";
-
-            String userPrompt = "Question: " + question + "\n\n" + graphContext +
-                    "\n\nProvide a direct, detailed answer to the question above by extracting and synthesizing information from the document content provided. " +
-                    "DO NOT tell me to refer to or consult any documents - answer the question directly using the content above.";
-
-            io.sentrius.sso.genai.model.LLMRequest request = io.sentrius.sso.genai.model.LLMRequest.builder()
-                    .model("gpt-4.1")
-                    .messages(java.util.Arrays.asList(
-                            io.sentrius.sso.genai.Message.builder().role("system").content(systemPrompt).build(),
-                            io.sentrius.sso.genai.Message.builder().role("user").content(userPrompt).build()
-                    ))
-                    .temperature(0.3F)
-                    .maxTokens(1000)
-                    .build();
-
-            String response;
-            try {
-                response = llmService.askQuestion(agentExecution, request);
-            } catch (io.sentrius.sso.core.exceptions.ZtatException e) {
-                log.error("ZtatException while calling LLM service: {}", e.getMessage(), e);
-                return "I encountered an error while calling the LLM service: " + e.getMessage();
-            }
-
-            // Extract text from the response (handling different formats)
-            try {
-                com.fasterxml.jackson.databind.JsonNode responseNode = objectMapper.readTree(response);
-
-                log.debug("LLM response structure: has 'output'={}, has 'choices'={}, has 'content'={}",
-                        responseNode.has("output"), responseNode.has("choices"), responseNode.has("content"));
-
-                // Try different response formats
-
-                // Format 1: Direct output array at top level (your current format)
-                if (responseNode.has("output") && responseNode.get("output").isArray()) {
-                    com.fasterxml.jackson.databind.JsonNode outputArray = responseNode.get("output");
-                    if (!outputArray.isEmpty()) {
-                        com.fasterxml.jackson.databind.JsonNode firstOutput = outputArray.get(0);
-                        if (firstOutput.has("content") && firstOutput.get("content").isArray()) {
-                            com.fasterxml.jackson.databind.JsonNode contentArray = firstOutput.get("content");
-                            if (!contentArray.isEmpty()) {
-                                com.fasterxml.jackson.databind.JsonNode firstContent = contentArray.get(0);
-                                if (firstContent.has("text")) {
-                                    String extractedText = firstContent.get("text").asText();
-                                    log.info("Successfully extracted text from LLM response (format: output.content.text)");
-                                    return extractedText;
-                                }
-                            }
-                        }
-                    }
-                }
-
-                // Format 2: OpenAI-style response
-                if (responseNode.has("choices")) {
-                    String extractedText = responseNode.get("choices").get(0).get("message").get("content").asText();
-                    log.info("Successfully extracted text from LLM response (format: choices.message.content)");
-                    return extractedText;
-                }
-
-                // Format 3: Array response with nested output field
-                else if (responseNode.isArray() && !responseNode.isEmpty()) {
-                    com.fasterxml.jackson.databind.JsonNode firstResponse = responseNode.get(0);
-                    if (firstResponse.has("output") && firstResponse.get("output").isArray()) {
-                        com.fasterxml.jackson.databind.JsonNode output = firstResponse.get("output").get(0);
-                        if (output.has("content") && output.get("content").isArray()) {
-                            com.fasterxml.jackson.databind.JsonNode contentNode = output.get("content").get(0);
-                            if (contentNode.has("text")) {
-                                String extractedText = contentNode.get("text").asText();
-                                log.info("Successfully extracted text from LLM response (format: array.output.content.text)");
-                                return extractedText;
-                            }
-                        }
-                    }
-                }
-
-                // Format 4: Direct content array
-                else if (responseNode.has("content") && responseNode.get("content").isArray()) {
-                    com.fasterxml.jackson.databind.JsonNode contentArray = responseNode.get("content");
-                    if (!contentArray.isEmpty() && contentArray.get(0).has("text")) {
-                        String extractedText = contentArray.get(0).get("text").asText();
-                        log.info("Successfully extracted text from LLM response (format: content.text)");
-                        return extractedText;
-                    }
-                }
-
-                // If we can't extract, log the structure and return error message
-                log.warn("Could not extract text from LLM response. Response structure: {}",
-                        response.length() > 500 ? response.substring(0, 500) + "..." : response);
-                return "I received a response from the LLM but couldn't extract the answer text. Please try again.";
-            } catch (Exception parseEx) {
-                // If parsing fails, log and return error
-                log.error("Failed to parse LLM response: {}", parseEx.getMessage(), parseEx);
-                log.debug("Raw response preview: {}", response.length() > 500 ? response.substring(0, 500) + "..." : response);
-                return "I encountered an error while parsing the LLM response. Please try again.";
-            }
-
-        } catch (Exception e) {
-            log.error("Failed to get LLM answer: {}", e.getMessage(), e);
-            return "I encountered an error while processing your question with the LLM: " + e.getMessage();
-        }
-    }
-}
-
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/UnavailableKnowledgeGraph.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/UnavailableKnowledgeGraph.java
new file mode 100644
index 00000000..06c3c4e6
--- /dev/null
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/UnavailableKnowledgeGraph.java
@@ -0,0 +1,120 @@
+package io.sentrius.sso.core.services.documents;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import io.sentrius.sso.core.model.documents.Document;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphNode;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryRequest;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryResponse;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphRelationship;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * Knowledge graph implementation used when no graph backend is configured.
+ *
+ * <p>It reproduces exactly the degraded behaviour the SurrealDB implementation
+ * exhibited when its connection provider was disabled, which was the only
+ * behaviour any deployment ever saw: writes are dropped, queries return empty
+ * responses, and statistics report a disconnected store. Features built on the
+ * graph therefore stay loadable and inert rather than failing at startup.
+ *
+ * <p>It is registered by {@link KnowledgeGraphConfiguration} only when no other
+ * {@link KnowledgeGraphPort} bean exists, so a real adapter takes over simply by
+ * being present on the classpath.
+ */
+@Slf4j
+public class UnavailableKnowledgeGraph implements KnowledgeGraphPort {
+
+    public UnavailableKnowledgeGraph() {
+        log.info("No knowledge graph backend configured; graph-derived features are inactive");
+    }
+
+    private static KnowledgeGraphQueryResponse emptyResponse() {
+        return KnowledgeGraphQueryResponse.builder()
+            .nodes(Collections.emptyList())
+            .relationships(Collections.emptyList())
+            .totalCount(0)
+            .build();
+    }
+
+    @Override
+    public boolean isAvailable() {
+        return false;
+    }
+
+    @Override
+    public KnowledgeGraphNode storeDocumentAsNode(Document document, String username) {
+        return null;
+    }
+
+    @Override
+    public KnowledgeGraphNode createNode(KnowledgeGraphNode node, String username) {
+        return null;
+    }
+
+    @Override
+    public KnowledgeGraphRelationship createRelationship(
+        String fromNodeId, String toNodeId, String relationshipType, Double weight, String username) {
+        return null;
+    }
+
+    @Override
+    public KnowledgeGraphQueryResponse findSimilarDocuments(Long documentId, String username, int limit) {
+        return emptyResponse();
+    }
+
+    @Override
+    public KnowledgeGraphQueryResponse executeQuery(KnowledgeGraphQueryRequest request, String username) {
+        return emptyResponse();
+    }
+
+    @Override
+    public KnowledgeGraphQueryResponse executeQuery(
+        KnowledgeGraphQueryRequest request, String username, boolean includeRelationships) {
+        return emptyResponse();
+    }
+
+    @Override
+    public Map<String, Object> getRelationshipsForNodeIds(List<String> nodeIds, String username) {
+        Map<String, Object> result = new HashMap<>();
+        result.put("relationships", Collections.emptyList());
+        result.put("connectedNodes", Collections.emptyList());
+        result.put("relationshipCount", 0);
+        return result;
+    }
+
+    @Override
+    public boolean deleteNode(String nodeId, String username) {
+        return false;
+    }
+
+    @Override
+    public boolean updateNodeProperties(String nodeId, Map<String, Object> properties, String username) {
+        return false;
+    }
+
+    @Override
+    public List<KnowledgeGraphNode> getAllNodes(int limit) {
+        return Collections.emptyList();
+    }
+
+    @Override
+    public Map<String, Object> getStatistics() {
+        Map<String, Object> stats = new HashMap<>();
+        stats.put("nodeCount", 0);
+        stats.put("status", "disconnected");
+        return stats;
+    }
+
+    @Override
+    public Map<String, Object> answerQuestion(String question, String username) {
+        Map<String, Object> result = new HashMap<>();
+        result.put("question", question);
+        result.put("answer", "The knowledge graph is not configured, so this question cannot be answered.");
+        result.put("error", "Knowledge graph not configured");
+        return result;
+    }
+}
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/DocumentSearchEmptyResultsTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/DocumentSearchEmptyResultsTest.java
index 263d5b36..1329f68d 100644
--- a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/DocumentSearchEmptyResultsTest.java
+++ b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/DocumentSearchEmptyResultsTest.java
@@ -43,7 +43,7 @@ class DocumentSearchEmptyResultsTest {
     private DocumentAccessControlService accessControlService;
 
     @Mock
-    private KnowledgeGraphService knowledgeGraphService;
+    private KnowledgeGraphPort knowledgeGraphService;
 
     private DocumentService documentService;
     private SystemOptions systemOptions = new SystemOptions();
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/DocumentServiceTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/DocumentServiceTest.java
index b5c3e802..b34ecf42 100644
--- a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/DocumentServiceTest.java
+++ b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/DocumentServiceTest.java
@@ -43,7 +43,7 @@ class DocumentServiceTest {
     private DocumentAccessControlService accessControlService;
 
     @Mock
-    private KnowledgeGraphService knowledgeGraphService;
+    private KnowledgeGraphPort knowledgeGraphService;
 
     @BeforeEach
     void setUp() {
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KeywordExtractionTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KeywordExtractionTest.java
index 46acb7f9..a90ba59d 100644
--- a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KeywordExtractionTest.java
+++ b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KeywordExtractionTest.java
@@ -10,7 +10,7 @@
 import static org.junit.jupiter.api.Assertions.*;
 
 /**
- * Tests for keyword extraction logic in KnowledgeGraphService.
+ * Tests for keyword extraction logic in KnowledgeGraphPort.
  * This demonstrates the improvement from literal string matching to keyword extraction.
  */
 @ExtendWith(MockitoExtension.class)
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfigurationTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfigurationTest.java
new file mode 100644
index 00000000..8b953a34
--- /dev/null
+++ b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfigurationTest.java
@@ -0,0 +1,101 @@
+package io.sentrius.sso.core.services.documents;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+import io.sentrius.sso.core.model.documents.Document;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphNode;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryRequest;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryResponse;
+import io.sentrius.sso.core.model.documents.KnowledgeGraphRelationship;
+import org.junit.jupiter.api.Test;
+import org.springframework.context.annotation.AnnotationConfigApplicationContext;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertInstanceOf;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Verifies knowledge graph backend selection.
+ *
+ * <p>Every consumer injects {@link KnowledgeGraphPort}, so a deployment with no
+ * graph backend must still get a bean or the application will not start. These
+ * tests cover both directions: the inert fallback is supplied when nothing else
+ * provides the port, and it steps aside the moment a real adapter exists.
+ */
+class KnowledgeGraphConfigurationTest {
+
+    @Test
+    void fallbackIsSuppliedWhenNoBackendIsPresent() {
+        try (AnnotationConfigApplicationContext context =
+                 new AnnotationConfigApplicationContext(KnowledgeGraphConfiguration.class)) {
+            assertEquals(1, context.getBeanNamesForType(KnowledgeGraphPort.class).length);
+            KnowledgeGraphPort port = context.getBean(KnowledgeGraphPort.class);
+            assertInstanceOf(UnavailableKnowledgeGraph.class, port);
+            assertFalse(port.isAvailable());
+        }
+    }
+
+    @Test
+    void fallbackDegradesInsteadOfThrowing() {
+        try (AnnotationConfigApplicationContext context =
+                 new AnnotationConfigApplicationContext(KnowledgeGraphConfiguration.class)) {
+            KnowledgeGraphPort port = context.getBean(KnowledgeGraphPort.class);
+
+            assertNull(port.createNode(null, "someone"));
+            assertFalse(port.deleteNode("node:1", "someone"));
+            assertTrue(port.getAllNodes(10).isEmpty());
+            assertEquals(0, port.executeQuery(null, "someone").getTotalCount());
+            assertEquals("disconnected", port.getStatistics().get("status"));
+        }
+    }
+
+    @Test
+    void aRealBackendReplacesTheFallback() {
+        try (AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext()) {
+            // Registered first, exactly as a component-scanned adapter would be,
+            // so the fallback's condition observes it and backs off.
+            context.register(StubBackendConfiguration.class, KnowledgeGraphConfiguration.class);
+            context.refresh();
+
+            assertEquals(1, context.getBeanNamesForType(KnowledgeGraphPort.class).length);
+            KnowledgeGraphPort port = context.getBean(KnowledgeGraphPort.class);
+            assertInstanceOf(StubBackend.class, port);
+            assertTrue(port.isAvailable());
+        }
+    }
+
+    @Configuration
+    static class StubBackendConfiguration {
+        @Bean
+        KnowledgeGraphPort stubBackend() {
+            return new StubBackend();
+        }
+    }
+
+    /** Stands in for a future adapter; only availability is meaningful here. */
+    static class StubBackend implements KnowledgeGraphPort {
+        @Override public boolean isAvailable() { return true; }
+        @Override public KnowledgeGraphNode storeDocumentAsNode(Document d, String u) { return null; }
+        @Override public KnowledgeGraphNode createNode(KnowledgeGraphNode n, String u) { return null; }
+        @Override public KnowledgeGraphRelationship createRelationship(
+            String f, String t, String type, Double w, String u) { return null; }
+        @Override public KnowledgeGraphQueryResponse findSimilarDocuments(Long id, String u, int l) { return null; }
+        @Override public KnowledgeGraphQueryResponse executeQuery(KnowledgeGraphQueryRequest r, String u) { return null; }
+        @Override public KnowledgeGraphQueryResponse executeQuery(
+            KnowledgeGraphQueryRequest r, String u, boolean rel) { return null; }
+        @Override public Map<String, Object> getRelationshipsForNodeIds(List<String> ids, String u) {
+            return Collections.emptyMap();
+        }
+        @Override public boolean deleteNode(String id, String u) { return false; }
+        @Override public boolean updateNodeProperties(String id, Map<String, Object> p, String u) { return false; }
+        @Override public List<KnowledgeGraphNode> getAllNodes(int limit) { return Collections.emptyList(); }
+        @Override public Map<String, Object> getStatistics() { return Collections.emptyMap(); }
+        @Override public Map<String, Object> answerQuestion(String q, String u) { return Collections.emptyMap(); }
+    }
+}
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphServiceTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphServiceTest.java
deleted file mode 100644
index 9cd12cef..00000000
--- a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphServiceTest.java
+++ /dev/null
@@ -1,402 +0,0 @@
-package io.sentrius.sso.core.services.documents;
-
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.surrealdb.Surreal;
-import com.surrealdb.Response;
-import com.surrealdb.Value;
-import io.sentrius.sso.core.config.SystemOptions;
-import io.sentrius.sso.core.model.documents.*;
-import io.sentrius.sso.provenance.ProvenanceLogger;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.extension.ExtendWith;
-import org.mockito.Mock;
-import org.mockito.junit.jupiter.MockitoExtension;
-
-import java.time.LocalDateTime;
-import java.util.*;
-
-import static org.junit.jupiter.api.Assertions.*;
-import static org.mockito.ArgumentMatchers.*;
-import static org.mockito.Mockito.*;
-
-/**
- * Unit tests for KnowledgeGraphService.
- */
-@ExtendWith(MockitoExtension.class)
-class KnowledgeGraphServiceTest {
-
-    @Mock
-    private KnowledgeGraphService.SurrealDBConnectionProvider connectionProvider;
-
-    @Mock
-    private Surreal surrealDB;
-
-    @Mock
-    private ProvenanceLogger provenanceLogger;
-
-    @Mock
-    private DocumentAccessControlService accessControlService;
-
-    @Mock
-    private io.sentrius.sso.core.services.agents.LLMService llmService;
-
-    @Mock
-    private SystemOptions systemOptions;
-
-    @Mock
-    private io.sentrius.sso.core.repository.documents.DocumentRepository documentRepository;
-
-    private ObjectMapper objectMapper;
-
-    private KnowledgeGraphService knowledgeGraphService;
-
-    @BeforeEach
-    void setUp() {
-        objectMapper = new ObjectMapper();
-        // Set up mock connection provider to return mock surreal connection
-        lenient().when(connectionProvider.isEnabled()).thenReturn(true);
-        lenient().when(connectionProvider.getConnection()).thenReturn(surrealDB);
-
-        knowledgeGraphService = new KnowledgeGraphService(
-                connectionProvider,
-                provenanceLogger,
-                accessControlService, 
-                objectMapper,
-                llmService,
-                systemOptions,
-                documentRepository);
-    }
-
-    @Test
-    void testStoreDocumentAsNode_WhenSurrealDBNull() {
-        // Arrange - use null connection provider
-        knowledgeGraphService = new KnowledgeGraphService(
-                null, 
-                provenanceLogger, 
-                accessControlService, 
-                objectMapper,
-                null,
-                systemOptions,
-                documentRepository);
-
-        Document document = Document.builder()
-                .id(1L)
-                .documentName("Test Document")
-                .documentType("TSG")
-                .content("Test content")
-                .summary("Test summary")
-                .classification("UNCLASSIFIED")
-                .markings("PUBLIC")
-                .tags("test,knowledge")
-                .build();
-
-        String username = "testuser";
-
-        // Act
-        KnowledgeGraphNode result = knowledgeGraphService.storeDocumentAsNode(document, username);
-
-        // Assert - Should return null when SurrealDB not configured
-        assertNull(result);
-    }
-
-    @Test
-    void testStoreDocumentAsNode_WhenConnectionProviderDisabled() {
-        // Arrange - mock connection provider as disabled
-        when(connectionProvider.isEnabled()).thenReturn(false);
-
-        knowledgeGraphService = new KnowledgeGraphService(
-                connectionProvider,
-                provenanceLogger,
-                accessControlService,
-                objectMapper,
-                llmService,
-                systemOptions,
-                documentRepository);
-
-        Document document = Document.builder()
-                .id(1L)
-                .documentName("Test Document")
-                .documentType("TSG")
-                .content("Test content")
-                .summary("Test summary")
-                .classification("UNCLASSIFIED")
-                .markings("PUBLIC")
-                .tags("test,knowledge")
-                .build();
-
-        String username = "testuser";
-
-        // Act
-        KnowledgeGraphNode result = knowledgeGraphService.storeDocumentAsNode(document, username);
-
-        // Assert - Should return null when connection provider is disabled
-        assertNull(result);
-    }
-
-    @Test
-    void testCreateRelationship_WhenSurrealDBNull() {
-        // Arrange
-        knowledgeGraphService = new KnowledgeGraphService(
-                null, 
-                provenanceLogger, 
-                accessControlService, 
-                objectMapper,
-                null,
-                systemOptions,
-                documentRepository);
-
-        String fromNodeId = "document:1";
-        String toNodeId = "document:2";
-        String relationshipType = "references";
-        Double weight = 0.8;
-        String username = "testuser";
-
-        // Act
-        KnowledgeGraphRelationship result = knowledgeGraphService.createRelationship(
-                fromNodeId, toNodeId, relationshipType, weight, username);
-
-        // Assert - Should return null when SurrealDB not configured
-        assertNull(result);
-    }
-
-    @Test
-    void testFindSimilarDocuments_WhenSurrealDBNull() {
-        // Arrange
-        knowledgeGraphService = new KnowledgeGraphService(
-                null, 
-                provenanceLogger, 
-                accessControlService, 
-                objectMapper,
-                null,
-                systemOptions,
-                documentRepository);
-
-        // Act
-        KnowledgeGraphQueryResponse result = knowledgeGraphService.findSimilarDocuments(
-                1L, "testuser", 10);
-
-        // Assert
-        assertNotNull(result);
-        assertTrue(result.getNodes().isEmpty());
-        assertTrue(result.getRelationships().isEmpty());
-        assertEquals(0, result.getTotalCount());
-    }
-
-    @Test
-    void testExecuteQuery_SearchType() {
-        // Arrange
-        // Mock the SurrealDB response
-        Response mockResponse = mock(Response.class);
-        Value mockValue = mock(Value.class);
-        when(mockValue.toString()).thenReturn("[]");
-        when(mockResponse.size()).thenReturn(1);
-        when(mockResponse.take(eq(0))).thenReturn(mockValue);
-        when(surrealDB.query(anyString())).thenReturn(mockResponse);
-
-        KnowledgeGraphQueryRequest request = KnowledgeGraphQueryRequest.builder()
-                .queryType(KnowledgeGraphQueryRequest.QueryType.SEARCH)
-                .searchText("test")
-                .limit(50)
-                .build();
-
-        // Act
-        KnowledgeGraphQueryResponse result = knowledgeGraphService.executeQuery(request, "testuser");
-
-        // Assert
-        assertNotNull(result);
-        assertTrue(result.getNodes().isEmpty());
-        assertEquals(0, result.getTotalCount());
-        assertNotNull(result.getExecutionTimeMs());
-
-        // Verify provenance logging
-        verify(provenanceLogger, times(1)).log(any());
-    }
-
-    @Test
-    void testExecuteQuery_NeighborsType() {
-        // Arrange
-        Response mockResponse = mock(Response.class);
-        Value mockValue = mock(Value.class);
-        when(mockValue.toString()).thenReturn("[]");
-        when(mockResponse.size()).thenReturn(1);
-        when(mockResponse.take(eq(0))).thenReturn(mockValue);
-        when(surrealDB.query(anyString())).thenReturn(mockResponse);
-
-        KnowledgeGraphQueryRequest request = KnowledgeGraphQueryRequest.builder()
-                .queryType(KnowledgeGraphQueryRequest.QueryType.NEIGHBORS)
-                .startNodeId("document:1")
-                .limit(20)
-                .build();
-
-        // Act
-        KnowledgeGraphQueryResponse result = knowledgeGraphService.executeQuery(request, "testuser");
-
-        // Assert
-        assertNotNull(result);
-        assertNotNull(result.getMetadata());
-        assertTrue(result.getMetadata().contains("NEIGHBORS"));
-    }
-
-    @Test
-    void testExecuteQuery_TraverseType() {
-        // Arrange
-        Response mockResponse = mock(Response.class);
-        Value mockValue = mock(Value.class);
-        when(mockValue.toString()).thenReturn("[]");
-        when(mockResponse.size()).thenReturn(1);
-        when(mockResponse.take(eq(0))).thenReturn(mockValue);
-        when(surrealDB.query(anyString())).thenReturn(mockResponse);
-
-        KnowledgeGraphQueryRequest request = KnowledgeGraphQueryRequest.builder()
-                .queryType(KnowledgeGraphQueryRequest.QueryType.TRAVERSE)
-                .startNodeId("document:1")
-                .maxDepth(2)
-                .limit(50)
-                .build();
-
-        // Act
-        KnowledgeGraphQueryResponse result = knowledgeGraphService.executeQuery(request, "testuser");
-
-        // Assert
-        assertNotNull(result);
-        assertNotNull(result.getMetadata());
-        assertTrue(result.getMetadata().contains("TRAVERSE"));
-    }
-
-    @Test
-    void testExecuteQuery_PathType() {
-        // Arrange
-        Response mockResponse = mock(Response.class);
-        Value mockValue = mock(Value.class);
-        when(mockValue.toString()).thenReturn("[]");
-        when(mockResponse.size()).thenReturn(1);
-        when(mockResponse.take(eq(0))).thenReturn(mockValue);
-        when(surrealDB.query(anyString())).thenReturn(mockResponse);
-
-        KnowledgeGraphQueryRequest request = KnowledgeGraphQueryRequest.builder()
-                .queryType(KnowledgeGraphQueryRequest.QueryType.PATH)
-                .startNodeId("document:1")
-                .targetNodeId("document:5")
-                .build();
-
-        // Act
-        KnowledgeGraphQueryResponse result = knowledgeGraphService.executeQuery(request, "testuser");
-
-        // Assert
-        assertNotNull(result);
-        assertNotNull(result.getMetadata());
-        assertTrue(result.getMetadata().contains("PATH"));
-    }
-
-    @Test
-    void testExecuteQuery_SubgraphType() {
-        // Arrange
-        Response mockResponse = mock(Response.class);
-        Value mockValue = mock(Value.class);
-        when(mockValue.toString()).thenReturn("[]");
-        when(mockResponse.size()).thenReturn(1);
-        when(mockResponse.take(eq(0))).thenReturn(mockValue);
-        when(surrealDB.query(anyString())).thenReturn(mockResponse);
-
-        KnowledgeGraphQueryRequest request = KnowledgeGraphQueryRequest.builder()
-                .queryType(KnowledgeGraphQueryRequest.QueryType.SUBGRAPH)
-                .startNodeId("document:1")
-                .maxDepth(2)
-                .limit(50)
-                .build();
-
-        // Act
-        KnowledgeGraphQueryResponse result = knowledgeGraphService.executeQuery(request, "testuser");
-
-        // Assert
-        assertNotNull(result);
-        assertNotNull(result.getMetadata());
-        assertTrue(result.getMetadata().contains("SUBGRAPH"));
-    }
-
-    @Test
-    void testDeleteNode_Success() {
-        // Arrange
-        Response mockResponse = mock(Response.class);
-        Value mockValue = mock(Value.class);
-        when(mockValue.toString()).thenReturn("[]");
-        when(mockResponse.size()).thenReturn(1);
-        when(mockResponse.take(eq(0))).thenReturn(mockValue);
-        when(surrealDB.query(anyString())).thenReturn(mockResponse);
-
-        String nodeId = "document:1";
-        String username = "testuser";
-
-        // Act
-        boolean result = knowledgeGraphService.deleteNode(nodeId, username);
-
-        // Assert
-        assertTrue(result);
-
-        // Verify provenance logging
-        verify(provenanceLogger, times(1)).log(any());
-    }
-
-    @Test
-    void testDeleteNode_WhenSurrealDBNull() {
-        // Arrange
-        knowledgeGraphService = new KnowledgeGraphService(
-                null, 
-                provenanceLogger, 
-                accessControlService, 
-                objectMapper,
-                null,
-                systemOptions,
-                documentRepository);
-
-        // Act
-        boolean result = knowledgeGraphService.deleteNode("document:1", "testuser");
-
-        // Assert
-        assertFalse(result);
-    }
-
-    @Test
-    void testGetStatistics_WhenEnabled() {
-        // Arrange
-        Response mockResponse = mock(Response.class);
-        Value mockValue = mock(Value.class);
-        Map<String, Object> countResult = new HashMap<>();
-        countResult.put("count", 5);
-        // The statistics query returns a result like "[{count: 5}]"
-        when(mockValue.toString()).thenReturn("[{count: 5}]");
-        when(mockResponse.size()).thenReturn(1);
-        when(mockResponse.take(eq(0))).thenReturn(mockValue);
-        when(surrealDB.query(anyString())).thenReturn(mockResponse);
-
-        // Act
-        Map<String, Object> stats = knowledgeGraphService.getStatistics();
-
-        // Assert
-        assertNotNull(stats);
-        assertEquals(true, stats.get("enabled"));
-        assertEquals("surrealdb", stats.get("database"));
-    }
-
-    @Test
-    void testGetStatistics_WhenDisabled() {
-        // Arrange
-        knowledgeGraphService = new KnowledgeGraphService(
-                null,
-                provenanceLogger,
-                accessControlService,
-                objectMapper,
-                null,
-                systemOptions,
-                documentRepository);
-
-        // Act
-        Map<String, Object> stats = knowledgeGraphService.getStatistics();
-
-        // Assert
-        assertNotNull(stats);
-        assertEquals(false, stats.get("enabled"));
-        assertEquals("disconnected", stats.get("status"));
-    }
-}
diff --git a/docker/sentrius/Dockerfile b/docker/sentrius/Dockerfile
index 016efc02..86f76592 100644
--- a/docker/sentrius/Dockerfile
+++ b/docker/sentrius/Dockerfile
@@ -1,5 +1,5 @@
 # Use an OpenJDK image as the base
-# Using Noble (Ubuntu 24.04) for GLIBC 2.39+ required by SurrealDB Java SDK
+# Using Noble (Ubuntu 24.04) for a modern GLIBC baseline
 FROM eclipse-temurin:17-jdk-noble
 
 # Declare the argument
diff --git a/ops-scripts/azure/deploy-helm.sh b/ops-scripts/azure/deploy-helm.sh
index a4a196ae..f9f93893 100755
--- a/ops-scripts/azure/deploy-helm.sh
+++ b/ops-scripts/azure/deploy-helm.sh
@@ -344,7 +344,6 @@ helm upgrade --install sentrius ./sentrius-chart --namespace ${TENANT} \
     --set keycloak.realm.clients.sshagent.client_secret="${SSH_AGENT_CLIENT_SECRET}" \
     --set keycloak.realm.clients.agentProxy.client_secret="${SENTRIUS_APROXY_CLIENT_SECRET}" \
     --set keycloak.realm.clients.promptAdvisor.client_secret="${PROMPT_ADVISOR_CLIENT_SECRET}" \
-    --set surrealdb.password="${SURREALDB_PASSWORD}" \
     --set keycloak.image.repository="${AZURE_REGISTRY}/sentrius-keycloak" \
     --set keycloak.image.pullPolicy="IfNotPresent" \
     --set keycloak.image.tag=${SENTRIUS_KEYCLOAK_VERSION} \
diff --git a/ops-scripts/base/generate-secrets.sh b/ops-scripts/base/generate-secrets.sh
index 585a99b6..377687ff 100755
--- a/ops-scripts/base/generate-secrets.sh
+++ b/ops-scripts/base/generate-secrets.sh
@@ -73,9 +73,6 @@ SSH_AGENT_CLIENT_SECRET=$(get_or_generate_secret "$KEYCLOAK_SECRET" "SSH_AGENT_C
 SENTRIUS_RDPPROXY_CLIENT_SECRET=$(get_or_generate_secret "$KEYCLOAK_SECRET" "SENTRIUS_RDPPROXY_CLIENT_SECRET" "SENTRIUS_RDPPROXY_CLIENT_SECRET" 32)
 PROMPT_ADVISOR_CLIENT_SECRET=$(get_or_generate_secret "$KEYCLOAK_SECRET" "PROMPT_ADVISOR_CLIENT_SECRET" "PROMPT_ADVISOR_CLIENT_SECRET" 32)
 
-# SurrealDB password
-SURREALDB_SECRET="${TENANT}-surrealdb-secret"
-SURREALDB_PASSWORD=$(get_or_generate_secret "$SURREALDB_SECRET" "SURREALDB_PASSWORD" "password" 24)
 
 # Output to .generated.env
 cat <<EOF > "$GENERATED_ENV_PATH"
@@ -92,7 +89,6 @@ MONITORING_AGENT_CLIENT_SECRET=${MONITORING_AGENT_CLIENT_SECRET}
 SSH_AGENT_CLIENT_SECRET=${SSH_AGENT_CLIENT_SECRET}
 SENTRIUS_RDPPROXY_CLIENT_SECRET=${SENTRIUS_RDPPROXY_CLIENT_SECRET}
 PROMPT_ADVISOR_CLIENT_SECRET=${PROMPT_ADVISOR_CLIENT_SECRET}
-SURREALDB_PASSWORD=${SURREALDB_PASSWORD}
 EOF
 
 echo "📦 Secrets written to $GENERATED_ENV_PATH"
diff --git a/ops-scripts/gcp/deploy-helm.sh b/ops-scripts/gcp/deploy-helm.sh
index 26a8d2d6..ee975fcf 100755
--- a/ops-scripts/gcp/deploy-helm.sh
+++ b/ops-scripts/gcp/deploy-helm.sh
@@ -270,7 +270,6 @@ helm upgrade --install sentrius ./sentrius-chart --namespace ${TENANT} \
     --set keycloak.realm.clients.sshagent.client_secret="${SSH_AGENT_CLIENT_SECRET}" \
     --set keycloak.realm.clients.agentProxy.client_secret="${SENTRIUS_APROXY_CLIENT_SECRET}" \
     --set keycloak.realm.clients.promptAdvisor.client_secret="${PROMPT_ADVISOR_CLIENT_SECRET}" \
-    --set surrealdb.password="${SURREALDB_PASSWORD}" \
     --set keycloak.image.repository="${GCP_REGISTRY}/sentrius-keycloak" \
     --set keycloak.image.pullPolicy="IfNotPresent" \
     --set keycloak.image.tag=${SENTRIUS_KEYCLOAK_VERSION} \
diff --git a/ops-scripts/local/deploy-helm.sh b/ops-scripts/local/deploy-helm.sh
index 598e3c97..b2789e20 100755
--- a/ops-scripts/local/deploy-helm.sh
+++ b/ops-scripts/local/deploy-helm.sh
@@ -303,7 +303,6 @@ helm upgrade --install sentrius ./sentrius-chart --namespace ${TENANT} \
     --set keycloak.realm.clients.sshagent.client_secret="${SSH_AGENT_CLIENT_SECRET}" \
     --set keycloak.realm.clients.agentProxy.client_secret="${SENTRIUS_APROXY_CLIENT_SECRET}" \
     --set keycloak.realm.clients.promptAdvisor.client_secret="${PROMPT_ADVISOR_CLIENT_SECRET}" \
-    --set surrealdb.password="${SURREALDB_PASSWORD}" \
     --set sentrius.image.pullPolicy="Never" \
     --set keycloak.image.pullPolicy="Never" \
     --set ssh.image.pullPolicy="Never" \
diff --git a/python-agent/knowledge-graph.yaml b/python-agent/knowledge-graph.yaml
index c9c7693e..3adeb655 100644
--- a/python-agent/knowledge-graph.yaml
+++ b/python-agent/knowledge-graph.yaml
@@ -2,7 +2,7 @@ description: "Agent that provides knowledge graph querying and investigation cap
 api_base_url: "http://localhost:8080"
 context: |
   You are a Knowledge Graph agent that provides semantic querying and investigation of documents.
-  You have access to a knowledge graph stored in SurrealDB that represents documents and their relationships.
+  You have access to a knowledge graph that represents documents and their relationships.
   All operations are authenticated and logged for compliance and provenance.
   
   Available operations:
diff --git a/sentrius-chart/templates/configmap.yaml b/sentrius-chart/templates/configmap.yaml
index 7c9ad91b..0f07a50e 100644
--- a/sentrius-chart/templates/configmap.yaml
+++ b/sentrius-chart/templates/configmap.yaml
@@ -484,13 +484,6 @@ data:
     integrationproxy.externalUrl=http://sentrius-integrationproxy:8080/
     sentrius.integration.proxyUrl=http://sentrius-integrationproxy:8080/
     sentrius.abac.keycloak-sync.enabled=true
-    # SurrealDB Knowledge Graph configuration
-    surrealdb.enabled=true
-    surrealdb.host={{ .Release.Name }}-surrealdb
-    surrealdb.port={{ .Values.surrealdb.port | default 8000 }}
-    surrealdb.username={{ .Values.surrealdb.username | default "root" }}
-    surrealdb.namespace={{ .Values.surrealdb.namespace | default "sentrius" }}
-    surrealdb.database={{ .Values.surrealdb.database | default "knowledge" }}
     # Self-Healing configuration
     self-healing.enabled={{ .Values.selfHealing.enabled }}
     self-healing.off-hours.start={{ .Values.selfHealing.offHours.start }}
diff --git a/sentrius-chart/templates/deployment.yaml b/sentrius-chart/templates/deployment.yaml
index 7713b4e6..482fa90f 100644
--- a/sentrius-chart/templates/deployment.yaml
+++ b/sentrius-chart/templates/deployment.yaml
@@ -80,14 +80,6 @@ spec:
                   name: {{ .Release.Name }}-db-secret
                   key: keystore-password
 
-            {{- if .Values.surrealdb.enabled }}
-            - name: SURREALDB_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: {{ .Release.Name }}-surrealdb-secret
-                  key: password
-            {{- end }}
-
             # Database URL switches based on Cloud SQL mode
             - name: SPRING_DATASOURCE_URL
               value: {{- if .Values.cloudsql.enabled }}
diff --git a/sentrius-chart/templates/surrealdb-deployment.yaml b/sentrius-chart/templates/surrealdb-deployment.yaml
deleted file mode 100644
index 13edd481..00000000
--- a/sentrius-chart/templates/surrealdb-deployment.yaml
+++ /dev/null
@@ -1,84 +0,0 @@
-{{- if .Values.surrealdb.enabled }}
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: {{ .Release.Name }}-surrealdb
-  labels:
-    app: surrealdb
-    release: {{ .Release.Name }}
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app: surrealdb
-      release: {{ .Release.Name }}
-  template:
-    metadata:
-      labels:
-        app: surrealdb
-        release: {{ .Release.Name }}
-    spec:
-      # Init container to fix permissions on the data directory
-      initContainers:
-        - name: fix-permissions
-          image: busybox:latest
-          command: ['sh', '-c', 'chown -R 1000:1000 /data && chmod -R 755 /data']
-          volumeMounts:
-            - name: surrealdb-data
-              mountPath: /data
-          securityContext:
-            runAsUser: 0
-      containers:
-        - name: surrealdb
-          image: "{{ .Values.surrealdb.image.repository }}:{{ .Values.surrealdb.image.tag }}"
-          imagePullPolicy: {{ .Values.surrealdb.image.pullPolicy }}
-          command: ["/surreal", "start"]
-          args:
-            - "--bind"
-            - "0.0.0.0:{{ .Values.surrealdb.port }}"
-            - "--user"
-            - "root"
-            - "--pass"
-            - "$(SURREAL_PASS)"
-            - "surrealkv:/data/sentrius.db"
-          securityContext:
-            runAsUser: 1000
-            runAsGroup: 1000
-          ports:
-            - containerPort: {{ .Values.surrealdb.port }}
-              name: http
-          env:
-            - name: SURREAL_USER
-              value: "root"
-            - name: SURREAL_PASS
-              valueFrom:
-                secretKeyRef:
-                  name: {{ .Release.Name }}-surrealdb-secret
-                  key: password
-            - name: SURREAL_LOG
-              value: {{ .Values.surrealdb.env.SURREAL_LOG | quote }}
-            - name: SURREAL_CAPS_ALLOW_ALL
-              value: {{ .Values.surrealdb.env.SURREAL_CAPS_ALLOW_ALL | quote }}
-            - name: SURREAL_CAPS_ALLOW_NET
-              value: {{ .Values.surrealdb.env.SURREAL_CAPS_ALLOW_NET | quote }}
-          volumeMounts:
-            - name: surrealdb-data
-              mountPath: /data
-          resources: {{- toYaml .Values.surrealdb.resources | nindent 12 }}
-          livenessProbe:
-            httpGet:
-              path: /health
-              port: http
-            initialDelaySeconds: 30
-            periodSeconds: 10
-          readinessProbe:
-            httpGet:
-              path: /health
-              port: http
-            initialDelaySeconds: 10
-            periodSeconds: 5
-      volumes:
-        - name: surrealdb-data
-          persistentVolumeClaim:
-            claimName: {{ .Release.Name }}-surrealdb-pvc
-{{- end }}
diff --git a/sentrius-chart/templates/surrealdb-networkpolicy.yaml b/sentrius-chart/templates/surrealdb-networkpolicy.yaml
deleted file mode 100644
index e8ed9d35..00000000
--- a/sentrius-chart/templates/surrealdb-networkpolicy.yaml
+++ /dev/null
@@ -1,25 +0,0 @@
-{{- if .Values.surrealdb.enabled }}
-apiVersion: networking.k8s.io/v1
-kind: NetworkPolicy
-metadata:
-  name: {{ .Release.Name }}-allow-surrealdb-from-api
-  labels:
-    app: surrealdb
-    release: {{ .Release.Name }}
-spec:
-  podSelector:
-    matchLabels:
-      app: surrealdb
-      release: {{ .Release.Name }}
-  ingress:
-    - from:
-        - podSelector:
-            matchLabels:
-              app: sentrius
-              release: {{ .Release.Name }}
-      ports:
-        - protocol: TCP
-          port: {{ .Values.surrealdb.port }}
-  policyTypes:
-    - Ingress
-{{- end }}
diff --git a/sentrius-chart/templates/surrealdb-pvc.yaml b/sentrius-chart/templates/surrealdb-pvc.yaml
deleted file mode 100644
index e8849d65..00000000
--- a/sentrius-chart/templates/surrealdb-pvc.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-{{- if .Values.surrealdb.enabled }}
-apiVersion: v1
-kind: PersistentVolumeClaim
-metadata:
-  name: {{ .Release.Name }}-surrealdb-pvc
-  labels:
-    app: surrealdb
-    release: {{ .Release.Name }}
-spec:
-  accessModes:
-    - ReadWriteOnce
-  {{- if .Values.config.storageClassName }}
-  storageClassName: {{ .Values.config.storageClassName }}
-  {{- end }}
-  resources:
-    requests:
-      storage: {{ .Values.surrealdb.storageSize | default "10Gi" }}
-{{- end }}
diff --git a/sentrius-chart/templates/surrealdb-secret.yaml b/sentrius-chart/templates/surrealdb-secret.yaml
deleted file mode 100644
index 8aa40ccb..00000000
--- a/sentrius-chart/templates/surrealdb-secret.yaml
+++ /dev/null
@@ -1,13 +0,0 @@
-{{- if .Values.surrealdb.enabled }}
-apiVersion: v1
-kind: Secret
-metadata:
-  name: {{ .Release.Name }}-surrealdb-secret
-  labels:
-    app: surrealdb
-    release: {{ .Release.Name }}
-type: Opaque
-data:
-  # SurrealDB root password
-  password: {{ .Values.surrealdb.password | default (randAlphaNum 24) | b64enc | quote }}
-{{- end }}
diff --git a/sentrius-chart/templates/surrealdb-service.yaml b/sentrius-chart/templates/surrealdb-service.yaml
deleted file mode 100644
index 947bf8d5..00000000
--- a/sentrius-chart/templates/surrealdb-service.yaml
+++ /dev/null
@@ -1,19 +0,0 @@
-{{- if .Values.surrealdb.enabled }}
-apiVersion: v1
-kind: Service
-metadata:
-  name: {{ .Release.Name }}-surrealdb
-  labels:
-    app: surrealdb
-    release: {{ .Release.Name }}
-spec:
-  type: ClusterIP
-  ports:
-    - port: {{ .Values.surrealdb.port }}
-      targetPort: http
-      protocol: TCP
-      name: http
-  selector:
-    app: surrealdb
-    release: {{ .Release.Name }}
-{{- end }}
diff --git a/sentrius-chart/values.yaml b/sentrius-chart/values.yaml
index c7729560..4649fb53 100644
--- a/sentrius-chart/values.yaml
+++ b/sentrius-chart/values.yaml
@@ -447,22 +447,6 @@ neo4j:
     NEO4J_AUTH: ""  # To be set via environment variable (e.g., neo4j/your-secure-password)
     NEO4J_server_config_strict__validation__enabled: "true"
 
-# SurrealDB configuration for knowledge graph
-surrealdb:
-  enabled: true
-  image:
-    repository: surrealdb/surrealdb
-    tag: v2.1.3
-    pullPolicy: IfNotPresent
-  port: 8000
-  storageSize: 10Gi
-  resources: {}
-  password: ""  # To be set via environment variable or external secret
-  env:
-    SURREAL_LOG: info
-    SURREAL_CAPS_ALLOW_ALL: "false"
-    SURREAL_CAPS_ALLOW_NET: "false"
-
 adminer:
   enabled: false
 

From 668e84ab94a74fcc318a1d33f3316b140f78b92b Mon Sep 17 00:00:00 2001
From: Marc Parisi <phrocker@apache.org>
Date: Fri, 11 Sep 2026 12:17:38 -0400
Subject: [PATCH 4/6] Resolve lazy associations before the ZTAT use claim
 detaches them

claimUse is annotated clearAutomatically = true, so the persistence context is
cleared as soon as it runs and every managed entity becomes detached. Both
increment paths then resolved a lazy @ManyToOne for the use record -
request.getUser() and request.getApprover() - which would have thrown
LazyInitializationException whenever the proxy had not already been initialized.

The use record is now built before the claim and saved after it, so every lazy
association is resolved while the context is still live, and the record is still
only persisted once the claim has succeeded. Added an ordering test so the two
cannot be reversed again.

Found while reviewing 4339dd0; clearAutomatically is retained deliberately, since
it is what prevents a stale in-memory counter being read after the claim.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLVutpMbp3msuhvxA46cU3
---
 .../security/ZeroTrustRequestService.java     | 13 ++++++---
 .../ZeroTrustRequestServiceUsesTest.java      | 27 +++++++++++++++++++
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/security/ZeroTrustRequestService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/security/ZeroTrustRequestService.java
index 8f262e67..3597c24a 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/security/ZeroTrustRequestService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/security/ZeroTrustRequestService.java
@@ -240,20 +240,25 @@ public void getAccessTokenStatus(ZeroTrustAccessTokenRequest request, User user,
     public void incrementAccessTokenUses(ZeroTrustAccessTokenRequest request) {
         if (request.getSystem().getId().equals(-1L)) {
             opsApprovalRepository.findByZtatRequestId(request.getId()).ifPresent(approval -> {
+                // Build the use record first: claimUse clears the persistence context,
+                // after which resolving a lazy association such as the requesting user
+                // would fail on a detached entity.
+                OpsUse use = OpsUse.builder().opsApproval(approval).user(request.getUser()).build();
                 if (opsApprovalRepository.claimUse(approval.getId(), systemOptions.maxJitUses) == 0) {
                     throw new RuntimeException("JIT uses exceeded");
                 }
                 // Record the use only once the claim succeeded, so the counter and
                 // the use log can never disagree about how much access was granted.
-                opsUseRepository.save(OpsUse.builder().opsApproval(approval).user(request.getUser()).build());
+                opsUseRepository.save(use);
                 log.info("Incremented uses for JITRequest: {}", request.getId());
             });
         } else {
             ztatApprovalRepository.findByZtatRequestId(request.getId()).ifPresent(approval -> {
+                ZtatUse use = ZtatUse.builder().ztatApproval(approval).user(request.getUser()).build();
                 if (ztatApprovalRepository.claimUse(approval.getId(), systemOptions.maxJitUses) == 0) {
                     throw new RuntimeException("JIT uses exceeded");
                 }
-                ztatUseRepository.save(ZtatUse.builder().ztatApproval(approval).user(request.getUser()).build());
+                ztatUseRepository.save(use);
                 log.info("Incremented uses for JITRequest: {}", request.getId());
             });
         }
@@ -435,10 +440,12 @@ public void addCommunicationLink(RequestCommunicationLink link) {
     @Transactional
     public void incrementAccessTokenUses(OpsApproval request) {
         opsApprovalRepository.findByZtatRequestId(request.getZtatRequest().getId()).ifPresent(approval -> {
+            // Resolve the lazy approver before claimUse clears the persistence context.
+            OpsUse use = OpsUse.builder().opsApproval(approval).user(request.getApprover()).build();
             if (opsApprovalRepository.claimUse(approval.getId(), systemOptions.maxJitUses) == 0) {
                 throw new RuntimeException("JIT uses exceeded");
             }
-            opsUseRepository.save(OpsUse.builder().opsApproval(approval).user(request.getApprover()).build());
+            opsUseRepository.save(use);
             log.info("Incremented uses for JITRequest: {}", request.getId());
         });
     }
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/security/ZeroTrustRequestServiceUsesTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/security/ZeroTrustRequestServiceUsesTest.java
index 9b79d2fe..c059bc05 100644
--- a/dataplane/src/test/java/io/sentrius/sso/core/services/security/ZeroTrustRequestServiceUsesTest.java
+++ b/dataplane/src/test/java/io/sentrius/sso/core/services/security/ZeroTrustRequestServiceUsesTest.java
@@ -134,6 +134,33 @@ void opsApprovalAlsoRecordsItsUseSoTheCounterAndLogAgree() {
         verify(opsApprovalRepository, never()).save(any(OpsApproval.class));
     }
 
+    @Test
+    void lazyAssociationsAreResolvedBeforeTheClaimClearsThePersistenceContext() {
+        // claimUse is a @Modifying query with clearAutomatically = true, so every
+        // managed entity is detached once it runs. Any lazy association needed for
+        // the use record must therefore be resolved first, or the save would fail
+        // with a LazyInitializationException on a detached request.
+        ZeroTrustAccessTokenApproval approval = new ZeroTrustAccessTokenApproval();
+        approval.setId(555L);
+
+        HostSystem system = new HostSystem();
+        system.setId(REGULAR_SYSTEM_ID);
+
+        ZeroTrustAccessTokenRequest request = org.mockito.Mockito.mock(ZeroTrustAccessTokenRequest.class);
+        when(request.getSystem()).thenReturn(system);
+        when(request.getId()).thenReturn(100L);
+        when(request.getUser()).thenReturn(user);
+
+        when(ztatApprovalRepository.findByZtatRequestId(100L)).thenReturn(Optional.of(approval));
+        when(ztatApprovalRepository.claimUse(555L, MAX_USES)).thenReturn(1);
+
+        service.incrementAccessTokenUses(request);
+
+        org.mockito.InOrder order = org.mockito.Mockito.inOrder(request, ztatApprovalRepository);
+        order.verify(request).getUser();
+        order.verify(ztatApprovalRepository).claimUse(555L, MAX_USES);
+    }
+
     @Test
     void exhaustedOpsApprovalIsRefusedAndRecordsNoUse() {
         OpsApproval approval = new OpsApproval();

From 5faece7777f85b28aafbae1a43e1202002454d11 Mon Sep 17 00:00:00 2001
From: Marc Parisi <phrocker@apache.org>
Date: Fri, 11 Sep 2026 12:20:58 -0400
Subject: [PATCH 5/6] Gate knowledge graph work on isAvailable, not on the bean
 existing

Adversarial review of a968eb6 found that replacing an optionally absent bean
with an always present inert one silently broke every consumer's guard.

com.surrealdb was <optional>true</optional> in dataplane, so it never reached
the classpath of analytics, ssh-proxy or rdp-proxy. KnowledgeGraphService was
@ConditionalOnClass, so in those applications the bean genuinely did not exist
and every "knowledgeGraphService == null" guard short-circuited. Supplying a
fallback made all of those guards dead, so the work they were guarding began to
run and its results were discarded:

- BehavioralPatternAgent.analyzePatterns is @Scheduled every four hours and
  scans the session tables, mines command sequences and generates runbooks via
  LLM; it counted routines, workflows and incidents as discovered while every
  write was dropped.
- KnowledgeGraphIngestionService gated only on the bean existing, so
  AuditService.closeSession loaded the full terminal log set and built a node
  graph synchronously on every SSH and RDP session teardown, into a no-op sink.
- AutomationAdoptionTracker ran the same way every eight hours.
- KnowledgeGraphController returned 500 rather than 503 for an unconfigured
  install, and DriLifecycleService returned an empty DRI view as a fact rather
  than reporting the graph as unavailable.

Every consumer now asks isAvailable(). That is also the check the eventual
adapter needs, since a bean will exist while its backing store is unreachable.

Also from the review: the fallback's statistics regained the enabled and
database keys that knowledge_graph.html renders, and selection moved to a real
@AutoConfiguration outside any component-scanned package. On a plain
@Configuration, @ConditionalOnMissingBean is evaluated in registration order, so
an adapter contributed by a later-processed configuration would have left two
beans and failed startup with NoUniqueBeanDefinitionException. The test now
drives it through AutoConfigurations so the ordering guarantee is actually
exercised; the previous version registered the stub first and could not fail.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLVutpMbp3msuhvxA46cU3
---
 .../automation/AutomationAdoptionTracker.java |  2 +-
 .../behavioral/BehavioralPatternAgent.java    |  4 +-
 .../documents/KnowledgeGraphController.java   | 22 +++---
 dataplane/pom.xml                             |  7 ++
 .../KnowledgeGraphAutoConfiguration.java      | 42 ++++++++++
 .../agents/AgentForensicsService.java         |  2 +-
 .../services/documents/DocumentService.java   |  2 +-
 .../documents/DriLifecycleService.java        |  8 +-
 .../KnowledgeGraphConfiguration.java          | 30 -------
 .../KnowledgeGraphIngestionService.java       |  2 +-
 .../documents/UnavailableKnowledgeGraph.java  |  5 ++
 ...ot.autoconfigure.AutoConfiguration.imports |  1 +
 .../documents/KeywordExtractionTest.java      |  8 +-
 ... KnowledgeGraphAutoConfigurationTest.java} | 78 ++++++++++---------
 14 files changed, 125 insertions(+), 88 deletions(-)
 create mode 100644 dataplane/src/main/java/io/sentrius/knowledgegraph/autoconfigure/KnowledgeGraphAutoConfiguration.java
 delete mode 100644 dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfiguration.java
 create mode 100644 dataplane/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
 rename dataplane/src/test/java/io/sentrius/sso/core/services/documents/{KnowledgeGraphConfigurationTest.java => KnowledgeGraphAutoConfigurationTest.java} (55%)

diff --git a/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java b/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java
index 3d301b74..7d5992e7 100644
--- a/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java
+++ b/analytics/src/main/java/io/sentrius/agent/analysis/agents/automation/AutomationAdoptionTracker.java
@@ -72,7 +72,7 @@ public AutomationAdoptionTracker(
     @Scheduled(fixedDelay = 28800000, initialDelay = 600000) // 8 hours, 10 min initial
     @Transactional
     public void trackAdoption() {
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.debug("Knowledge graph not available, skipping adoption tracking");
             return;
         }
diff --git a/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java b/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java
index 6d5cc9df..31440b47 100644
--- a/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java
+++ b/analytics/src/main/java/io/sentrius/agent/analysis/agents/behavioral/BehavioralPatternAgent.java
@@ -93,7 +93,7 @@ public void analyzePatterns() {
             return;
         }
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.debug("Knowledge graph service not available, skipping behavioral pattern analysis");
             return;
         }
@@ -687,7 +687,7 @@ private int correlateIncidents() {
     // ========================================================================
 
     private int generateRunbooks() {
-        if (knowledgeGraphService == null || !isLLMAvailable()) return 0;
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable() || !isLLMAvailable()) return 0;
 
         // Find workflow nodes that don't have associated runbooks yet
         // Query the knowledge graph for workflow nodes
diff --git a/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java b/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java
index 34d46d93..1a32bde0 100644
--- a/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java
+++ b/api/src/main/java/io/sentrius/sso/controllers/api/documents/KnowledgeGraphController.java
@@ -33,7 +33,7 @@ public KnowledgeGraphController(
             @Autowired(required = false) DriLifecycleService driLifecycleService) {
         this.knowledgeGraphService = knowledgeGraphService;
         this.driLifecycleService = driLifecycleService;
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("KnowledgeGraphController initialized without a KnowledgeGraphPort");
         } else {
             log.info("KnowledgeGraphController initialized with KnowledgeGraphPort");
@@ -50,7 +50,7 @@ public ResponseEntity<KnowledgeGraphNode> createNode(
         
         log.info("POST /api/v1/knowledge-graph/nodes - Create node request received");
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                     .body(null);
@@ -110,7 +110,7 @@ public ResponseEntity<KnowledgeGraphRelationship> createRelationship(
             return ResponseEntity.badRequest().build();
         }
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
@@ -149,7 +149,7 @@ public ResponseEntity<KnowledgeGraphQueryResponse> findSimilarDocuments(
         log.info("GET /api/v1/knowledge-graph/documents/{}/similar - Find similar documents request (limit: {})",
             documentId, limit);
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
@@ -184,7 +184,7 @@ public ResponseEntity<KnowledgeGraphQueryResponse> executeQuery(
         log.info("POST /api/v1/knowledge-graph/query - Execute query request: type={}, searchText={}",
             request.getQueryType(), request.getSearchText());
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
@@ -221,7 +221,7 @@ public ResponseEntity<Map<String, Object>> updateNodeProperties(
 
         log.info("PATCH /api/v1/knowledge-graph/nodes/{}/properties - Update node properties request", nodeId);
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
@@ -261,7 +261,7 @@ public ResponseEntity<Void> deleteNode(
         
         log.info("DELETE /api/v1/knowledge-graph/nodes/{} - Delete node request", nodeId);
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
@@ -292,7 +292,7 @@ public ResponseEntity<Void> deleteNode(
     public ResponseEntity<Map<String, Object>> getStatistics(Authentication authentication) {
         log.info("GET /api/v1/knowledge-graph/statistics - Get statistics request");
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("No knowledge graph backend is configured");
             Map<String, Object> stats = new HashMap<>();
             stats.put("enabled", false);
@@ -323,7 +323,7 @@ public ResponseEntity<KnowledgeGraphQueryResponse> listNodes(
 
         log.info("GET /api/v1/knowledge-graph/nodes - List all nodes (limit: {})", limit);
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
@@ -364,7 +364,7 @@ public ResponseEntity<Map<String, Object>> askQuestion(
         String question = request.get("question");
         log.info("POST /api/v1/knowledge-graph/ask - Question: {}", question);
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
@@ -408,7 +408,7 @@ public ResponseEntity<Map<String, Object>> getRelationshipsForNodes(
         log.info("POST /api/v1/knowledge-graph/relationships/for-nodes - Fetching relationships for {} nodes",
             nodeIds != null ? nodeIds.size() : 0);
 
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.warn("No knowledge graph backend is configured");
             return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).build();
         }
diff --git a/dataplane/pom.xml b/dataplane/pom.xml
index 4838c901..e4b3ce62 100644
--- a/dataplane/pom.xml
+++ b/dataplane/pom.xml
@@ -105,6 +105,13 @@
             <scope>test</scope>
         </dependency>
 
+        <!-- Required by ApplicationContextRunner, which is how auto-configuration
+             ordering is exercised in tests. -->
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-test-autoconfigure</artifactId>
diff --git a/dataplane/src/main/java/io/sentrius/knowledgegraph/autoconfigure/KnowledgeGraphAutoConfiguration.java b/dataplane/src/main/java/io/sentrius/knowledgegraph/autoconfigure/KnowledgeGraphAutoConfiguration.java
new file mode 100644
index 00000000..de8409f6
--- /dev/null
+++ b/dataplane/src/main/java/io/sentrius/knowledgegraph/autoconfigure/KnowledgeGraphAutoConfiguration.java
@@ -0,0 +1,42 @@
+package io.sentrius.knowledgegraph.autoconfigure;
+
+import io.sentrius.sso.core.services.documents.KnowledgeGraphPort;
+import io.sentrius.sso.core.services.documents.UnavailableKnowledgeGraph;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * Selects the knowledge graph backend.
+ *
+ * <p>Sentrius ships no graph backend. When an adapter supplies a
+ * {@link KnowledgeGraphPort} this configuration contributes nothing; otherwise
+ * it supplies {@link UnavailableKnowledgeGraph} so every consumer still has a
+ * bean to inject and graph-derived features degrade instead of the application
+ * failing to start.
+ *
+ * <p>This is an auto-configuration, and deliberately lives outside every
+ * component-scanned package ({@code io.sentrius.sso}, {@code io.sentrius.agent})
+ * so that it is applied once, and only after all user beans are registered.
+ * {@code @ConditionalOnMissingBean} is only dependable under that ordering: on
+ * an ordinary {@code @Configuration} it sees whatever happens to have been
+ * registered first, so an adapter contributed by a later-processed
+ * {@code @Configuration} would leave two {@code KnowledgeGraphPort} beans and
+ * every injection point would fail with {@code NoUniqueBeanDefinitionException}.
+ * Registered through {@code META-INF/spring/
+ * org.springframework.boot.autoconfigure.AutoConfiguration.imports}.
+ *
+ * <p>Consumers must still ask {@link KnowledgeGraphPort#isAvailable()} before
+ * doing work on the graph's behalf. A non-null bean no longer implies a usable
+ * backend, and it will not imply one later either: a real adapter is present as
+ * a bean even while the store it talks to is unreachable.
+ */
+@AutoConfiguration
+public class KnowledgeGraphAutoConfiguration {
+
+    @Bean
+    @ConditionalOnMissingBean(KnowledgeGraphPort.class)
+    public KnowledgeGraphPort unavailableKnowledgeGraph() {
+        return new UnavailableKnowledgeGraph();
+    }
+}
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java
index fcb214c1..cc7cb9f7 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/agents/AgentForensicsService.java
@@ -243,7 +243,7 @@ private MemoryEntry toMemoryEntry(AgentMemory memory) {
 
     private KnowledgeGraphContext fetchKnowledgeGraphContext(String executionId) {
         KnowledgeGraphContext ctx = new KnowledgeGraphContext();
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             ctx.available = false;
             ctx.nodes = Collections.emptyList();
             ctx.relationships = Collections.emptyList();
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DocumentService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DocumentService.java
index 7f97efe6..0c8e6f9f 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DocumentService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DocumentService.java
@@ -118,7 +118,7 @@ public Document storeDocument(String documentName, String documentType, String c
         }
 
         // Store in knowledge graph if service is available
-        if (knowledgeGraphService != null) {
+        if (knowledgeGraphService != null && knowledgeGraphService.isAvailable()) {
             try {
                 knowledgeGraphService.storeDocumentAsNode(saved, createdBy);
                 log.info("Stored document in knowledge graph: id={}", saved.getId());
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java
index 4b79b694..07a791af 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/DriLifecycleService.java
@@ -44,7 +44,7 @@ public DriLifecycleService(SystemOptions systemOptions) {
      * @return DRI lifecycle data or null if graph unavailable
      */
     public DriLifecycleView getDriLifecycle(String username) {
-        if (knowledgeGraphService == null) {
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) {
             log.debug("Knowledge graph not available for DRI lifecycle query");
             return null;
         }
@@ -130,7 +130,7 @@ public DriLifecycleView getDriLifecycle(String username) {
      * @return Onboarding package with transferred patterns
      */
     public OnboardingPackage transferPatterns(String previousDri, String newDri, List<String> systems) {
-        if (knowledgeGraphService == null) return null;
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) return null;
 
         try {
             // Get the previous DRI's lifecycle
@@ -196,7 +196,7 @@ public OnboardingPackage transferPatterns(String previousDri, String newDri, Lis
      * @return List of user nodes that own/operate this system
      */
     public List<KnowledgeGraphNode> findSystemOwners(String systemHost) {
-        if (knowledgeGraphService == null) return Collections.emptyList();
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) return Collections.emptyList();
 
         try {
             String systemNodeId = "system:" + sanitizeId(systemHost);
@@ -225,7 +225,7 @@ public List<KnowledgeGraphNode> findSystemOwners(String systemHost) {
      * Get all runbooks relevant to a specific system.
      */
     public List<KnowledgeGraphNode> getSystemRunbooks(String systemHost) {
-        if (knowledgeGraphService == null) return Collections.emptyList();
+        if (knowledgeGraphService == null || !knowledgeGraphService.isAvailable()) return Collections.emptyList();
 
         try {
             var queryRequest = KnowledgeGraphQueryRequest.builder()
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfiguration.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfiguration.java
deleted file mode 100644
index fcda751c..00000000
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfiguration.java
+++ /dev/null
@@ -1,30 +0,0 @@
-package io.sentrius.sso.core.services.documents;
-
-import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-
-/**
- * Selects the knowledge graph backend.
- *
- * <p>Sentrius ships no graph backend. When an adapter is on the classpath as a
- * component it is discovered during scanning, this condition sees it, and the
- * inert fallback is not registered. Otherwise {@link UnavailableKnowledgeGraph}
- * is supplied so that every consumer still has a {@link KnowledgeGraphPort} to
- * inject and graph-derived features degrade instead of failing to start.
- *
- * <p>The condition lives on a {@code @Bean} method rather than on the fallback
- * class itself: {@code @ConditionalOnMissingBean} is only evaluated reliably
- * against bean definitions that are already registered, which is true for
- * component-scanned adapters by the time configuration-class bean methods are
- * processed, and is not guaranteed between two scanned components.
- */
-@Configuration
-public class KnowledgeGraphConfiguration {
-
-    @Bean
-    @ConditionalOnMissingBean(KnowledgeGraphPort.class)
-    public KnowledgeGraphPort unavailableKnowledgeGraph() {
-        return new UnavailableKnowledgeGraph();
-    }
-}
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java
index 66bb756b..5bb6601f 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/KnowledgeGraphIngestionService.java
@@ -73,7 +73,7 @@ public KnowledgeGraphIngestionService(
      * Check if knowledge graph service is available
      */
     private boolean isKnowledgeGraphAvailable() {
-        return knowledgeGraphService != null;
+        return knowledgeGraphService != null && knowledgeGraphService.isAvailable();
     }
 
     /**
diff --git a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/UnavailableKnowledgeGraph.java b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/UnavailableKnowledgeGraph.java
index 06c3c4e6..665f00e3 100644
--- a/dataplane/src/main/java/io/sentrius/sso/core/services/documents/UnavailableKnowledgeGraph.java
+++ b/dataplane/src/main/java/io/sentrius/sso/core/services/documents/UnavailableKnowledgeGraph.java
@@ -103,9 +103,14 @@ public List<KnowledgeGraphNode> getAllNodes(int limit) {
 
     @Override
     public Map<String, Object> getStatistics() {
+        // Keys match what the previous implementation always returned and what
+        // the knowledge graph view renders; an absent "enabled" would be
+        // indistinguishable from a malformed response.
         Map<String, Object> stats = new HashMap<>();
+        stats.put("enabled", false);
         stats.put("nodeCount", 0);
         stats.put("status", "disconnected");
+        stats.put("database", "none");
         return stats;
     }
 
diff --git a/dataplane/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports b/dataplane/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
new file mode 100644
index 00000000..472ab5a6
--- /dev/null
+++ b/dataplane/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
@@ -0,0 +1 @@
+io.sentrius.knowledgegraph.autoconfigure.KnowledgeGraphAutoConfiguration
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KeywordExtractionTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KeywordExtractionTest.java
index a90ba59d..e828b2b2 100644
--- a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KeywordExtractionTest.java
+++ b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KeywordExtractionTest.java
@@ -10,8 +10,12 @@
 import static org.junit.jupiter.api.Assertions.*;
 
 /**
- * Tests for keyword extraction logic in KnowledgeGraphPort.
- * This demonstrates the improvement from literal string matching to keyword extraction.
+ * Characterises the keyword extraction approach used for graph search.
+ *
+ * <p>This exercises a copy of the algorithm held in this test, not shipping code:
+ * the original lived in KnowledgeGraphService and was removed with the SurrealDB
+ * backend. It is retained as the specification a future KnowledgeGraphPort
+ * adapter should satisfy, and should move onto that adapter once one exists.
  */
 @ExtendWith(MockitoExtension.class)
 class KeywordExtractionTest {
diff --git a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfigurationTest.java b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphAutoConfigurationTest.java
similarity index 55%
rename from dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfigurationTest.java
rename to dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphAutoConfigurationTest.java
index 8b953a34..a19bbb47 100644
--- a/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphConfigurationTest.java
+++ b/dataplane/src/test/java/io/sentrius/sso/core/services/documents/KnowledgeGraphAutoConfigurationTest.java
@@ -4,70 +4,78 @@
 import java.util.List;
 import java.util.Map;
 
+import io.sentrius.knowledgegraph.autoconfigure.KnowledgeGraphAutoConfiguration;
 import io.sentrius.sso.core.model.documents.Document;
 import io.sentrius.sso.core.model.documents.KnowledgeGraphNode;
 import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryRequest;
 import io.sentrius.sso.core.model.documents.KnowledgeGraphQueryResponse;
 import io.sentrius.sso.core.model.documents.KnowledgeGraphRelationship;
 import org.junit.jupiter.api.Test;
-import org.springframework.context.annotation.AnnotationConfigApplicationContext;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
-import static org.junit.jupiter.api.Assertions.assertEquals;
-import static org.junit.jupiter.api.Assertions.assertFalse;
-import static org.junit.jupiter.api.Assertions.assertInstanceOf;
-import static org.junit.jupiter.api.Assertions.assertNull;
-import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.assertj.core.api.Assertions.assertThat;
 
 /**
  * Verifies knowledge graph backend selection.
  *
  * <p>Every consumer injects {@link KnowledgeGraphPort}, so a deployment with no
  * graph backend must still get a bean or the application will not start. These
- * tests cover both directions: the inert fallback is supplied when nothing else
- * provides the port, and it steps aside the moment a real adapter exists.
+ * tests use {@link AutoConfigurations} rather than registering the configuration
+ * directly, because that is what applies Spring Boot's real ordering guarantee -
+ * auto-configuration last, after every user bean. Registering it as a plain
+ * configuration would evaluate {@code @ConditionalOnMissingBean} in declaration
+ * order and prove nothing about the case that matters.
  */
-class KnowledgeGraphConfigurationTest {
+class KnowledgeGraphAutoConfigurationTest {
+
+    private final ApplicationContextRunner runner = new ApplicationContextRunner()
+        .withConfiguration(AutoConfigurations.of(KnowledgeGraphAutoConfiguration.class));
 
     @Test
     void fallbackIsSuppliedWhenNoBackendIsPresent() {
-        try (AnnotationConfigApplicationContext context =
-                 new AnnotationConfigApplicationContext(KnowledgeGraphConfiguration.class)) {
-            assertEquals(1, context.getBeanNamesForType(KnowledgeGraphPort.class).length);
-            KnowledgeGraphPort port = context.getBean(KnowledgeGraphPort.class);
-            assertInstanceOf(UnavailableKnowledgeGraph.class, port);
-            assertFalse(port.isAvailable());
-        }
+        runner.run(context -> {
+            assertThat(context).hasSingleBean(KnowledgeGraphPort.class);
+            assertThat(context.getBean(KnowledgeGraphPort.class))
+                .isInstanceOf(UnavailableKnowledgeGraph.class);
+            assertThat(context.getBean(KnowledgeGraphPort.class).isAvailable()).isFalse();
+        });
     }
 
     @Test
     void fallbackDegradesInsteadOfThrowing() {
-        try (AnnotationConfigApplicationContext context =
-                 new AnnotationConfigApplicationContext(KnowledgeGraphConfiguration.class)) {
+        runner.run(context -> {
             KnowledgeGraphPort port = context.getBean(KnowledgeGraphPort.class);
 
-            assertNull(port.createNode(null, "someone"));
-            assertFalse(port.deleteNode("node:1", "someone"));
-            assertTrue(port.getAllNodes(10).isEmpty());
-            assertEquals(0, port.executeQuery(null, "someone").getTotalCount());
-            assertEquals("disconnected", port.getStatistics().get("status"));
-        }
+            assertThat(port.createNode(null, "someone")).isNull();
+            assertThat(port.deleteNode("node:1", "someone")).isFalse();
+            assertThat(port.getAllNodes(10)).isEmpty();
+            assertThat(port.executeQuery(null, "someone").getTotalCount()).isZero();
+        });
     }
 
     @Test
-    void aRealBackendReplacesTheFallback() {
-        try (AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext()) {
-            // Registered first, exactly as a component-scanned adapter would be,
-            // so the fallback's condition observes it and backs off.
-            context.register(StubBackendConfiguration.class, KnowledgeGraphConfiguration.class);
-            context.refresh();
+    void statisticsKeepTheShapeConsumersRender() {
+        runner.run(context -> {
+            Map<String, Object> stats = context.getBean(KnowledgeGraphPort.class).getStatistics();
 
-            assertEquals(1, context.getBeanNamesForType(KnowledgeGraphPort.class).length);
-            KnowledgeGraphPort port = context.getBean(KnowledgeGraphPort.class);
-            assertInstanceOf(StubBackend.class, port);
-            assertTrue(port.isAvailable());
-        }
+            // knowledge_graph.html renders enabled and database directly; an absent
+            // key is indistinguishable there from a malformed response.
+            assertThat(stats).containsEntry("enabled", false)
+                .containsEntry("status", "disconnected")
+                .containsKey("database")
+                .containsKey("nodeCount");
+        });
+    }
+
+    @Test
+    void aRealBackendReplacesTheFallback() {
+        runner.withUserConfiguration(StubBackendConfiguration.class).run(context -> {
+            assertThat(context).hasSingleBean(KnowledgeGraphPort.class);
+            assertThat(context.getBean(KnowledgeGraphPort.class)).isInstanceOf(StubBackend.class);
+        });
     }
 
     @Configuration

From 20e0514e339a1a138bb1d562c98f18fc458eaaf7 Mon Sep 17 00:00:00 2001
From: Marc Parisi <phrocker@apache.org>
Date: Fri, 11 Sep 2026 14:37:41 -0400
Subject: [PATCH 6/6] Fix deploy scripts: silent build failures, ssh-agent,
 prompt-advisor, cert ordering

Found while standing the full stack up on a clean cluster. Each of these only
shows on a cluster that is not already configured, which is why they survived.

build_image reported success for failed builds. The exit status was read after
an intervening if statement, so $? held that statement's result rather than
docker build's - and a false condition yields 0. A failed build printed
"Built locally" and the deploy continued to ImagePullBackOff. The status is now
captured immediately and checked before the Minikube sync.

ssh-agent never built at all: the jar copy read \/target/ssh-agent-*.jar, which
resolves to an absolute /target path rather than the module directory, so the
cp failed and the Docker COPY then failed on the missing jar. Masked entirely by
the bug above. Two assignments in the same block were written $VAR=value, which
expands the variable and tries to run the result as a command instead of
assigning; both corrected.

prompt-advisor pointed at Dockerfile-prompt-advisor in the repository root,
which does not exist - the Dockerfile is docker/prompt-advisor/Dockerfile. It
copies prompt-advisor/... from the root, so the context stays the root and only
the -f path changes. prepare_docker_context cannot serve it, since that resolves
dev-certs relative to the context's parent, which is outside the repository for
a root context, so the certs are staged inline instead.

deploy-helm.sh created the sentrius-dev-ca secret in the cert-manager namespace
before installing cert-manager, so on a cluster without it the secret always
failed to create and the Issuer had no CA to sign from. The namespace is now
ensured first; helm --create-namespace later adopts it.

Added a root .dockerignore so the prompt-advisor root-context build stops
shipping every module's target directory as build context.

Verified on a clean minikube cluster: all 17 pods in dev plus the launcher in
dev-agents reach Running, wildcard-cert-dev is issued, and the api serves.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YLVutpMbp3msuhvxA46cU3
---
 .dockerignore                    | 14 +++++++++++
 ops-scripts/base/build-images.sh | 40 ++++++++++++++++++++++----------
 ops-scripts/local/deploy-helm.sh | 12 ++++++++++
 3 files changed, 54 insertions(+), 12 deletions(-)
 create mode 100644 .dockerignore

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 00000000..bdf698f6
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,14 @@
+# Keep root-context builds (prompt-advisor) from shipping the whole repository.
+# Without this the build context includes every module's target/ directory,
+# which is several GB of jars.
+**/target/
+.git/
+**/node_modules/
+**/.venv/
+**/__pycache__/
+*.jar
+docker/
+ops-scripts/
+sentrius-chart/
+sentrius-chart-launcher/
+!prompt-advisor/**
diff --git a/ops-scripts/base/build-images.sh b/ops-scripts/base/build-images.sh
index 91738a67..50fd0bfe 100755
--- a/ops-scripts/base/build-images.sh
+++ b/ops-scripts/base/build-images.sh
@@ -101,14 +101,12 @@ build_image() {
     else
         docker build "${BUILD_ARGS[@]}" $dockerfile_flag -t "$name:$version" "$context_dir"
     fi
+    # Capture immediately. Any command in between - including an if statement
+    # whose condition is simply false - overwrites $? and made failed builds
+    # report success.
+    local build_status=$?
 
-    # Sync image into Minikube if running multi-node
-    if [[ "$ENV_TARGET" == "local" && "$USE_MINIKUBE_LOAD" == true ]]; then
-        echo "📦 Loading $name:$version into Minikube nodes..."
-        minikube image load "$name:$version"
-    fi
-
-    if [ $? -ne 0 ]; then
+    if [ $build_status -ne 0 ]; then
         echo "❌ Failed to build $name"
         if ! $skip_dev_certs; then
             cleanup_docker_context "$context_dir"
@@ -116,6 +114,12 @@ build_image() {
         exit 1
     fi
 
+    # Sync image into Minikube if running multi-node
+    if [[ "$ENV_TARGET" == "local" && "$USE_MINIKUBE_LOAD" == true ]]; then
+        echo "📦 Loading $name:$version into Minikube nodes..."
+        minikube image load "$name:$version"
+    fi
+
     if [[ "$ENV_TARGET" == "gcp" || "$ENV_TARGET" == "azure" ]]; then
         REGISTRY="us-central1-docker.pkg.dev/sentrius-project/sentrius-repo"
         docker tag "$name:$version" "$REGISTRY/$name:$version"
@@ -388,12 +392,12 @@ if $update_monitoring_agent; then
 fi
 
 if $update_ssh_agent; then
-    cp \/target/ssh-agent-*.jar docker/ssh-agent/ssh-agent.jar
+    cp ssh-agent/target/ssh-agent-*.jar docker/ssh-agent/ssh-agent.jar
     if [[ "$ENV_TARGET" == "gcp" || "$ENV_TARGET" == "azure" ]]; then
-        $SSH_AGENT_VERSION=$(increment_patch_version $SSH_AGENT_VERSION)
-        update_env_var "$SSH_AGENT_VERSION" "$SSH_AGENT_VERSION"
+        SSH_AGENT_VERSION=$(increment_patch_version $SSH_AGENT_VERSION)
+        update_env_var "SSH_AGENT_VERSION" "$SSH_AGENT_VERSION"
     else
-        $SSH_AGENT_VERSION="latest"
+        SSH_AGENT_VERSION="latest"
     fi
     build_image "sentrius-ssh-agent" "$SSH_AGENT_VERSION" "${SCRIPT_DIR}/../../docker/ssh-agent"
     rm docker/ssh-agent/ssh-agent.jar
@@ -416,5 +420,17 @@ if $update_prompt_advisor; then
     else
         PROMPT_ADVISOR_VERSION="latest"
     fi
-    build_image "sentrius-prompt-advisor" "$PROMPT_ADVISOR_VERSION" "${SCRIPT_DIR}/../../" -f Dockerfile-prompt-advisor --skip-dev-certs
+    # This Dockerfile copies prompt-advisor/... from the repository root, so the
+    # build context is the root while the Dockerfile itself lives under docker/.
+    # prepare_docker_context cannot be used here: it resolves dev-certs relative
+    # to the context's parent, which is outside the repository for a root context.
+    PA_ROOT="${SCRIPT_DIR}/../../"
+    mkdir -p "${PA_ROOT}/dev-certs"
+    if $INCLUDE_DEV_CERTS; then
+        cp "${PA_ROOT}/docker/dev-certs/sentrius-ca.crt" "${PA_ROOT}/dev-certs/sentrius-ca.crt"
+    else
+        cp "${PA_ROOT}/docker/dev-certs/empty-sentrius-ca.crt" "${PA_ROOT}/dev-certs/sentrius-ca.crt"
+    fi
+    build_image "sentrius-prompt-advisor" "$PROMPT_ADVISOR_VERSION" "${PA_ROOT}" -f docker/prompt-advisor/Dockerfile --skip-dev-certs
+    rm -rf "${PA_ROOT}/dev-certs"
 fi
\ No newline at end of file
diff --git a/ops-scripts/local/deploy-helm.sh b/ops-scripts/local/deploy-helm.sh
index b2789e20..54bad4aa 100755
--- a/ops-scripts/local/deploy-helm.sh
+++ b/ops-scripts/local/deploy-helm.sh
@@ -85,6 +85,12 @@ if [[ "$ENABLE_TLS" == "true"  ]]; then
 
 
       echo "Creating dev CA secret in cluster"
+      # The namespace must exist before the secret can be created. cert-manager
+      # itself is not installed until later in this script, so on a cluster that
+      # does not already have it this create would otherwise always fail and the
+      # Issuer would have no CA to sign from. helm --create-namespace later is
+      # idempotent and will adopt this namespace.
+      kubectl create namespace cert-manager --dry-run=client -o yaml | kubectl apply -f -
       kubectl -n cert-manager delete secret sentrius-dev-ca 2>/dev/null || true
       kubectl -n cert-manager create secret tls sentrius-dev-ca \
         --cert="$CERT_DIR/sentrius-ca.crt" \
@@ -99,6 +105,12 @@ if [[ "$ENABLE_TLS" == "true"  ]]; then
 
 
       echo "Creating dev CA secret in cluster"
+      # The namespace must exist before the secret can be created. cert-manager
+      # itself is not installed until later in this script, so on a cluster that
+      # does not already have it this create would otherwise always fail and the
+      # Issuer would have no CA to sign from. helm --create-namespace later is
+      # idempotent and will adopt this namespace.
+      kubectl create namespace cert-manager --dry-run=client -o yaml | kubectl apply -f -
       kubectl -n cert-manager delete secret sentrius-dev-ca 2>/dev/null || true
       kubectl -n cert-manager create secret tls sentrius-dev-ca \
         --cert="$CERT_DIR/sentrius-ca.crt" \