WilliamAGH · WilliamAGH · Jan 25, 2026 · Jan 25, 2026 · Jan 25, 2026 · Jan 25, 2026
diff --git a/.env.example b/.env.example
@@ -1,41 +1,49 @@
-# Java Chat Application Environment Variables
+# Java Chat environment variables
+#
+# Copy to .env:
+#   cp .env.example .env
 
 # Environment Configuration
 # Set to 'prod' for production (hides API key details in logs)
 # Set to 'dev' for development (shows last 4 chars of API keys in logs)
 SPRING_PROFILE=dev
 
-# API Keys (Choose one of the following)
-# Option 1: GitHub Models (Free tier available)
-GITHUB_TOKEN=your_github_personal_access_token
-
-# Option 2: OpenAI API
-OPENAI_API_KEY=your_openai_api_key
-
-# Optional: Override default model
-OPENAI_MODEL=gpt-4o-mini
-
-# Optional: Override base URL for API
-# For GitHub Models: https://models.github.ai/inference
-# For OpenAI: https://api.openai.com
-OPENAI_BASE_URL=https://models.github.ai/inference
-
 # Server Configuration
 PORT=8085
 
+# LLM providers (set one or both)
+#
+# GitHub Models (free tier available)
+GITHUB_TOKEN=
+# Optional overrides (used by Makefile + streaming SDK)
+GITHUB_MODELS_BASE_URL=https://models.github.ai/inference
+GITHUB_MODELS_CHAT_MODEL=gpt-5
+#
+# OpenAI (optional: can be used as primary or fallback)
+OPENAI_API_KEY=
+# For OpenAI: https://api.openai.com
+OPENAI_BASE_URL=https://api.openai.com
+OPENAI_MODEL=gpt-5.2
+# OPENAI_REASONING_EFFORT=high
+
 # Local Embedding Server (if you have one running)
 APP_LOCAL_EMBEDDING_ENABLED=false
 LOCAL_EMBEDDING_SERVER_URL=http://127.0.0.1:8088
 APP_LOCAL_EMBEDDING_MODEL=text-embedding-qwen3-embedding-8b
+APP_LOCAL_EMBEDDING_DIMENSIONS=4096
+APP_LOCAL_EMBEDDING_USE_HASH_WHEN_DISABLED=true
 
-# Qdrant Vector Database (if using)
+# Qdrant Vector Database (local docker-compose defaults)
 QDRANT_HOST=localhost
-QDRANT_PORT=8086
+QDRANT_SSL=false
+QDRANT_PORT=8086       # gRPC (app)
+QDRANT_REST_PORT=8087  # REST (scripts/monitors)
 QDRANT_COLLECTION=java-chat
+QDRANT_API_KEY=
 
 # RAG Configuration
 RAG_CHUNK_MAX_TOKENS=900
 RAG_CHUNK_OVERLAP_TOKENS=150
 RAG_TOP_K=12
 RAG_RETURN_K=6
-RAG_CITATIONS_K=3
+RAG_CITATIONS_K=3
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -0,0 +1,70 @@
+name: Build & Test
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+  pull_request:
+    branches:
+      - main
+      - dev
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Temurin JDK
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: 25
+          cache: gradle
+
+      - name: Log system & Java info (drift detection)
+        run: |
+          echo "=== Environment Info ==="
+          uname -a
+          echo "=== Java Version ==="
+          java -version
+          echo "=== Gradle Version ==="
+          ./gradlew --version
+
+      - name: Run tests
+        run: ./gradlew test --no-daemon
+
+      - name: Build application
+        run: ./gradlew build -x test --no-daemon
+
+      - name: Run static analysis
+        run: ./gradlew spotbugsMain pmdMain --no-daemon
+
+      - name: Upload test reports on failure
+        if: failure()
+        uses: actions/upload-artifact@v6
+        with:
+          name: test-results
+          path: build/test-results/
+          retention-days: 7
+
+      - name: Upload SpotBugs report on failure
+        if: failure()
+        uses: actions/upload-artifact@v6
+        with:
+          name: spotbugs-report
+          path: build/reports/spotbugs/
+          retention-days: 7
+
+      - name: Upload PMD report on failure
+        if: failure()
+        uses: actions/upload-artifact@v6
+        with:
+          name: pmd-report
+          path: build/reports/pmd/
+          retention-days: 7
diff --git a/.gitignore b/.gitignore
@@ -52,6 +52,9 @@ build/
 frontend/node_modules/
 frontend/.svelte-kit/
 
+# Local scratchpad (non-source artifacts)
+tmp/
+
 # Built frontend assets (generated by npm run build)
 # Favicons in static/ are source files and should be committed
 src/main/resources/static/index.html

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,13 @@
+repos:
+  - repo: local
+    hooks:
+      - id: spotless-java
+        name: Spotless Java (Gradle, auto-format)
+        entry: ./gradlew spotlessApply --no-daemon
+        language: system
+        pass_filenames: false
+      - id: frontend-check
+        name: Frontend check (Vite/Svelte)
+        entry: bash -lc "cd frontend && npm run check"
+        language: system
+        pass_filenames: false
diff --git a/.tool-versions b/.tool-versions
@@ -0,0 +1 @@
+java = temurin 25
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,41 @@
+# Contributing to Java Chat
+
+Feedback and contributions are welcome. If you find a bug or want a feature, please open an issue in this repository.
+
+## Getting started
+
+1) Fork the repository
+2) Clone your fork
+3) Create a feature branch
+4) Make your changes
+5) Run checks locally:
+
+```bash
+make test
+make build
+make lint
+```
+
+6) Commit with a descriptive message
+7) Push your branch and open a Pull Request
+
+## Guidelines
+
+- Use the deterministic toolchain: Gradle Wrapper + Gradle Toolchains + Temurin.
+- Local Java is managed by mise/asdf via `.tool-versions` (see below). The CI uses the same vendor.
+- We pin major Java version in Gradle toolchain and CI; patch is logged in CI and bumped intentionally.
+
+- Keep PRs focused (one change per PR when possible).
+- Add tests for new behavior.
+- Update docs when you change workflows or endpoints.
+- Don’t commit secrets (use `.env`, and keep `.env.example` up to date).
+
+## Reporting issues
+
+When reporting an issue, please include:
+
+- Clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- OS, Java version, and how you’re running the app (`make dev`, `make run`, etc.)
+
diff --git a/Dockerfile b/Dockerfile
@@ -25,7 +25,7 @@ RUN npm run build
 # ================================
 # BACKEND BUILD STAGE
 # ================================
-FROM public.ecr.aws/docker/library/eclipse-temurin:21-jdk AS builder
+FROM public.ecr.aws/docker/library/eclipse-temurin:25-jdk AS builder
 WORKDIR /app
 
 # Copy Gradle wrapper, build files, and static analysis configs
@@ -51,7 +51,7 @@ RUN ./gradlew clean build -x test --no-daemon && \
 # ================================
 # RUNTIME STAGE
 # ================================
-FROM public.ecr.aws/docker/library/eclipse-temurin:21-jre AS runtime
+FROM public.ecr.aws/docker/library/eclipse-temurin:25-jre AS runtime
 
 # Install curl for health check
 RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,9 @@
+Copyright © 2026, William Callahan.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+No licensee or downstream recipient may use the Software (including any modified or derivative versions) to directly compete with the original Licensor by offering it to third parties as a hosted, managed, or Software-as-a-Service (SaaS) product or cloud service where the primary value of the service is the functionality of the Software itself.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
diff --git a/Makefile b/Makefile
@@ -21,19 +21,9 @@ export RED GREEN YELLOW CYAN NC
 export PROJECT_ROOT := $(shell pwd)
 export JAR_PATH = $(call get_jar)
 
+.PHONY: all help clean build test lint format hooks run dev dev-backend compose-up compose-down compose-logs compose-ps health ingest citations fetch-all process-all full-pipeline frontend-install frontend-build
 
-# Runtime arguments mapped from GitHub Models env vars
-# - Requires GITHUB_TOKEN (PAT with models:read)
-# - Base URL and model names have sensible defaults
-# - CRITICAL: GitHub Models endpoint is https://models.github.ai/inference (NOT azure.com)
-# - Model names differ by provider: GitHub Models uses gpt-5, OpenAI uses gpt-5.2
-RUN_ARGS := \
-  --spring.ai.openai.api-key="$$GITHUB_TOKEN" \
-  --spring.ai.openai.base-url="$${GITHUB_MODELS_BASE_URL:-https://models.github.ai/inference}" \
-  --spring.ai.openai.chat.options.model="$${GITHUB_MODELS_CHAT_MODEL:-gpt-5}" \
-  --spring.ai.openai.embedding.options.model="$${GITHUB_MODELS_EMBED_MODEL:-text-embedding-3-small}"
-
-.PHONY: help clean build test lint run dev dev-backend compose-up compose-down compose-logs compose-ps health ingest citations fetch-all process-all full-pipeline frontend-install frontend-build
+all: help ## Default target (alias)
 
 help: ## Show available targets
 	@grep -E '^[a-zA-Z0-9_.-]+:.*?## ' Makefile | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'
@@ -52,38 +42,80 @@ lint: ## Run static analysis (Java: SpotBugs + PMD, Frontend: svelte-check)
 	$(GRADLEW) spotbugsMain pmdMain
 	cd frontend && npm run check
 
+format: ## Apply Java formatting (Palantir via Spotless)
+	$(GRADLEW) spotlessApply
+
+hooks: ## Install git hooks via prek
+	@command -v prek >/dev/null 2>&1 || { echo "Error: 'prek' not found. Install it first: https://prek.j178.dev/" >&2; exit 1; }
+	prek install --install-hooks
+
 run: build ## Run the packaged jar (loads .env if present)
 	@if [ -f .env ]; then set -a; source .env; set +a; fi; \
-	  [ -n "$$GITHUB_TOKEN" ] || (echo "ERROR: GITHUB_TOKEN is not set. See README for setup." >&2; exit 1); \
+	  if [ -z "$$GITHUB_TOKEN" ] && [ -z "$$OPENAI_API_KEY" ]; then \
+	    echo "ERROR: Set GITHUB_TOKEN or OPENAI_API_KEY. See README and docs/configuration.md." >&2; \
+	    exit 1; \
+	  fi; \
 	  SERVER_PORT=$${PORT:-$${port:-8085}}; \
 	  if [ $$SERVER_PORT -lt 8085 ] || [ $$SERVER_PORT -gt 8090 ]; then echo "Requested port $$SERVER_PORT is outside allowed range 8085-8090; using 8085" >&2; SERVER_PORT=8085; fi; \
 	  echo "Ensuring port $$SERVER_PORT is free..." >&2; \
 	  PIDS=$$(lsof -ti tcp:$$SERVER_PORT 2>/dev/null || true); echo "Found PIDs on port $$SERVER_PORT: '$$PIDS'" >&2; if [ -n "$$PIDS" ]; then echo "Killing process(es) on port $$SERVER_PORT: $$PIDS" >&2; kill -9 $$PIDS 2>/dev/null || true; sleep 2; fi; \
 	  echo "Binding app to port $$SERVER_PORT" >&2; \
+	  APP_ARGS=(--server.port=$$SERVER_PORT); \
+	  if [ -n "$$GITHUB_TOKEN" ]; then \
+	    APP_ARGS+=( \
+	      --spring.ai.openai.api-key="$$GITHUB_TOKEN" \
+	      --spring.ai.openai.base-url="$${GITHUB_MODELS_BASE_URL:-https://models.github.ai/inference}" \
+	      --spring.ai.openai.chat.options.model="$${GITHUB_MODELS_CHAT_MODEL:-gpt-5}" \
+	      --spring.ai.openai.embedding.options.model="$${GITHUB_MODELS_EMBED_MODEL:-text-embedding-3-small}" \
+	    ); \
+	  elif [ -n "$$OPENAI_API_KEY" ]; then \
+	    APP_ARGS+=( \
+	      --spring.ai.openai.api-key="$$OPENAI_API_KEY" \
+	    ); \
+	  fi; \
 	  # Add conservative JVM memory limits to prevent OS-level SIGKILL (exit 137) under memory pressure
 	  # Tuned for local dev: override via JAVA_OPTS env if needed
 	  JAVA_OPTS="$${JAVA_OPTS:- -XX:+IgnoreUnrecognizedVMOptions -Xms512m -Xmx1g -XX:+UseG1GC -XX:MaxRAMPercentage=70 -XX:MaxDirectMemorySize=256m -Dio.netty.handler.ssl.noOpenSsl=true -Dio.grpc.netty.shaded.io.netty.handler.ssl.noOpenSsl=true}"; \
-	  java $$JAVA_OPTS -Djava.net.preferIPv4Stack=true -jar $(call get_jar) --server.port=$$SERVER_PORT $(RUN_ARGS) & disown
+	  java $$JAVA_OPTS -Djava.net.preferIPv4Stack=true -jar $(call get_jar) "$${APP_ARGS[@]}" & disown
 
 dev: frontend-build ## Start both Spring Boot and Vite dev servers (Ctrl+C stops both)
 	@echo "$(YELLOW)Starting full-stack development environment...$(NC)"
 	@echo "$(CYAN)Frontend: http://localhost:5173/$(NC)"
 	@echo "$(YELLOW)Backend API: http://localhost:8085/api/$(NC)"
 	@echo ""
 	@if [ -f .env ]; then set -a; source .env; set +a; fi; \
-	  [ -n "$$GITHUB_TOKEN" ] || (echo "ERROR: GITHUB_TOKEN is not set. See README for setup." >&2; exit 1); \
+	  if [ -z "$$GITHUB_TOKEN" ] && [ -z "$$OPENAI_API_KEY" ]; then \
+	    echo "ERROR: Set GITHUB_TOKEN or OPENAI_API_KEY. See README and docs/configuration.md." >&2; \
+	    exit 1; \
+	  fi; \
 	  trap 'kill 0' INT TERM; \
 	  (cd frontend && npm run dev 2>&1 | awk '{print "\033[36m[vite]\033[0m " $$0; fflush()}') & \
 	  (if [ -f .env ]; then set -a; source .env; set +a; fi; \
+	   APP_ARGS=(--server.port=8085); \
+	   if [ -n "$$GITHUB_TOKEN" ]; then \
+	     APP_ARGS+=( \
+	       --spring.ai.openai.api-key="$$GITHUB_TOKEN" \
+	       --spring.ai.openai.base-url="$${GITHUB_MODELS_BASE_URL:-https://models.github.ai/inference}" \
+	       --spring.ai.openai.chat.options.model="$${GITHUB_MODELS_CHAT_MODEL:-gpt-5}" \
+	       --spring.ai.openai.embedding.options.model="$${GITHUB_MODELS_EMBED_MODEL:-text-embedding-3-small}" \
+	     ); \
+	   elif [ -n "$$OPENAI_API_KEY" ]; then \
+	     APP_ARGS+=( \
+	       --spring.ai.openai.api-key="$$OPENAI_API_KEY" \
+	     ); \
+	   fi; \
 	   SPRING_PROFILES_ACTIVE=dev $(GRADLEW) bootRun \
-	   --args="--server.port=8085 $(RUN_ARGS)" \
+	   --args="$${APP_ARGS[*]}" \
 	   -Dorg.gradle.jvmargs="-Xmx2g -Dspring.devtools.restart.enabled=true -Djava.net.preferIPv4Stack=true -Dio.netty.handler.ssl.noOpenSsl=true -Dio.grpc.netty.shaded.io.netty.handler.ssl.noOpenSsl=true" 2>&1 \
 	   | awk '{print "\033[33m[java]\033[0m " $$0; fflush()}') & \
 	  wait
 
 dev-backend: ## Run only Spring Boot backend (dev profile)
 	@if [ -f .env ]; then set -a; source .env; set +a; fi; \
-	  [ -n "$$GITHUB_TOKEN" ] || (echo "ERROR: GITHUB_TOKEN is not set. See README for setup." >&2; exit 1); \
+	  if [ -z "$$GITHUB_TOKEN" ] && [ -z "$$OPENAI_API_KEY" ]; then \
+	    echo "ERROR: Set GITHUB_TOKEN or OPENAI_API_KEY. See README and docs/configuration.md." >&2; \
+	    exit 1; \
+	  fi; \
 	  SERVER_PORT=$${PORT:-$${port:-8085}}; \
 	  LIVERELOAD_PORT=$${LIVERELOAD_PORT:-35730}; \
 	  if [ $$SERVER_PORT -lt 8085 ] || [ $$SERVER_PORT -gt 8090 ]; then echo "Requested port $$SERVER_PORT is outside allowed range 8085-8090; using 8085" >&2; SERVER_PORT=8085; fi; \
@@ -93,8 +125,21 @@ dev-backend: ## Run only Spring Boot backend (dev profile)
 	    if [ -n "$$PIDS" ]; then echo "Killing process(es) on port $$port: $$PIDS" >&2; kill -9 $$PIDS 2>/dev/null || true; sleep 1; fi; \
 	  done; \
 	  echo "Binding app (dev) to port $$SERVER_PORT, LiveReload on $$LIVERELOAD_PORT" >&2; \
+	  APP_ARGS=(--server.port=$$SERVER_PORT --spring.devtools.livereload.port=$$LIVERELOAD_PORT); \
+	  if [ -n "$$GITHUB_TOKEN" ]; then \
+	    APP_ARGS+=( \
+	      --spring.ai.openai.api-key="$$GITHUB_TOKEN" \
+	      --spring.ai.openai.base-url="$${GITHUB_MODELS_BASE_URL:-https://models.github.ai/inference}" \
+	      --spring.ai.openai.chat.options.model="$${GITHUB_MODELS_CHAT_MODEL:-gpt-5}" \
+	      --spring.ai.openai.embedding.options.model="$${GITHUB_MODELS_EMBED_MODEL:-text-embedding-3-small}" \
+	    ); \
+	  elif [ -n "$$OPENAI_API_KEY" ]; then \
+	    APP_ARGS+=( \
+	      --spring.ai.openai.api-key="$$OPENAI_API_KEY" \
+	    ); \
+	  fi; \
 	  SPRING_PROFILES_ACTIVE=dev $(GRADLEW) bootRun \
-	    --args="--server.port=$$SERVER_PORT --spring.devtools.livereload.port=$$LIVERELOAD_PORT $(RUN_ARGS)" \
+	    --args="$${APP_ARGS[*]}" \
 	    -Dorg.gradle.jvmargs="-Xmx2g -Dspring.devtools.restart.enabled=true -Djava.net.preferIPv4Stack=true -Dio.netty.handler.ssl.noOpenSsl=true -Dio.grpc.netty.shaded.io.netty.handler.ssl.noOpenSsl=true"
 
 frontend-install: ## Install frontend dependencies