diff --git a/.github/actions/kind/action.yaml b/.github/actions/kind/action.yaml
new file mode 100644
index 0000000..17cbc40
--- /dev/null
+++ b/.github/actions/kind/action.yaml
@@ -0,0 +1,159 @@
+name: Kind cluster and Helm deploy
+description: Create a Kind cluster with a local registry and install the general-simulation Helm chart
+
+inputs:
+ namespace:
+ description: Kubernetes namespace for the release
+ required: false
+ default: general-simulation
+ helm_release:
+ description: Helm release name
+ required: false
+ default: general-simulation
+ registry:
+ description: Local registry host:port (Kind registry mirror)
+ required: false
+ default: localhost:5001
+ helm_extra_args:
+ description: Extra arguments passed to helm upgrade --install
+ required: false
+ default: ""
+ skip_image_build:
+ description: Skip building and pushing app images (use tags already in the local registry)
+ required: false
+ default: "false"
+ wait_for_rollout:
+ description: Wait for general-sim-api Deployment to become Available
+ required: false
+ default: "true"
+ run_builtin_smoke:
+ description: Run minimal /health check in this action (disable if the workflow runs kind-verify-deployment.sh)
+ required: false
+ default: "false"
+
+runs:
+ using: composite
+ steps:
+ - name: Install Go (Kind CLI)
+ uses: actions/setup-go@v5
+ with:
+ go-version: "1.22.x"
+
+ - name: Install Kind
+ shell: bash
+ run: |
+ go install sigs.k8s.io/kind@v0.30.0
+ echo "$(go env GOPATH)/bin" >> "${GITHUB_PATH}"
+
+ - name: Install Podman
+ shell: bash
+ run: |
+ sudo apt-get update -qq
+ sudo apt-get install -y podman
+ podman version
+ podman info
+
+ - name: Create Kind cluster with local registry
+ shell: bash
+ env:
+ USE_PODMAN: "1"
+ run: bash ./scripts/ci/kind-with-registry.sh
+
+ - name: Install Helm
+ uses: azure/setup-helm@v4
+ with:
+ version: v3.19.4
+
+ - name: Helm dependencies
+ shell: bash
+ run: make helm-deps
+
+ - name: Build app images
+ if: inputs.skip_image_build != 'true'
+ shell: bash
+ run: make kind-build-images REGISTRY=${{ inputs.registry }}
+
+ - name: Push app images to local registry
+ if: inputs.skip_image_build != 'true'
+ shell: bash
+ run: make kind-push-images REGISTRY=${{ inputs.registry }} PUSH_EXTRA_ARGS=--tls-verify=false
+
+ - name: Create namespace
+ shell: bash
+ run: make k8s-namespace NAMESPACE=${{ inputs.namespace }}
+
+ - name: Helm install (Kind values)
+ id: helm_install
+ shell: bash
+ run: |
+ set -euo pipefail
+ make helm-install-kind \
+ NAMESPACE=${{ inputs.namespace }} \
+ HELM_RELEASE_NAME=${{ inputs.helm_release }} \
+ REGISTRY=${{ inputs.registry }} \
+ HELM_EXTRA_ARGS="${{ inputs.helm_extra_args }}"
+
+ - name: Dump cluster state on Helm install failure
+ if: failure() && steps.helm_install.outcome == 'failure'
+ shell: bash
+ run: |
+ set +e
+ NS="${{ inputs.namespace }}"
+ REL="${{ inputs.helm_release }}"
+ echo "=== kubectl get deploy,sts,svc,pvc,job,sa,pods -n ${NS} ==="
+ kubectl get deploy,sts,svc,pvc,job,sa,pods -n "${NS}" -o wide
+ echo "=== kubectl get events -n ${NS} (last 50) ==="
+ kubectl get events -n "${NS}" --sort-by=.lastTimestamp | tail -50
+ echo "=== StorageClasses ==="
+ kubectl get storageclass
+ echo "=== helm status ==="
+ helm status "${REL}" -n "${NS}" || true
+ dump_pod() {
+ local pod="$1"
+ echo "=== describe ${pod} ==="
+ kubectl describe -n "${NS}" "${pod}" | tail -50
+ kubectl logs -n "${NS}" "${pod}" --all-containers --tail=80 2>/dev/null || true
+ }
+ for dep in general-sim-api neo4j postgres bootstrap; do
+ echo "=== candidates matching *${dep}* ==="
+ kubectl get pods -n "${NS}" -o name 2>/dev/null | grep -i "${dep}" | while read -r pod; do
+ dump_pod "${pod}"
+ done
+ done
+ if kubectl get pod -n "${NS}" "${REL}-0" >/dev/null 2>&1; then
+ dump_pod "pod/${REL}-0"
+ fi
+ kubectl get jobs -n "${NS}" -o name 2>/dev/null | while read -r job; do
+ echo "=== job describe ${job} ==="
+ kubectl describe -n "${NS}" "${job}" | tail -40
+ kubectl logs -n "${NS}" "job/$(basename "${job}")" --all-containers --tail=80 2>/dev/null || true
+ done
+
+ - name: Wait for API deployment
+ if: inputs.wait_for_rollout == 'true'
+ shell: bash
+ run: |
+ kubectl wait --namespace "${{ inputs.namespace }}" \
+ --for=condition=available \
+ deployment/general-sim-api \
+ --timeout=300s
+
+ - name: Smoke test API /health
+ if: inputs.wait_for_rollout == 'true' && inputs.run_builtin_smoke == 'true'
+ shell: bash
+ run: |
+ set -euo pipefail
+ kubectl port-forward -n "${{ inputs.namespace }}" \
+ svc/general-sim-api 18000:8000 >/tmp/pf.log 2>&1 &
+ PF_PID=$!
+ trap 'kill "${PF_PID}" 2>/dev/null || true' EXIT
+ for _ in $(seq 1 45); do
+ if curl -sf http://127.0.0.1:18000/health | grep -q '"status"'; then
+ echo "API /health OK"
+ exit 0
+ fi
+ sleep 2
+ done
+ echo "API /health did not become ready"
+ cat /tmp/pf.log || true
+ exit 1
diff --git a/.github/workflows/kind-helm-smoke.yml b/.github/workflows/kind-helm-smoke.yml
new file mode 100644
index 0000000..03837ed
--- /dev/null
+++ b/.github/workflows/kind-helm-smoke.yml
@@ -0,0 +1,71 @@
+name: Kind Helm smoke
+
+# Helm lint, Kind deploy, and API verification (health + seed + /query with fake LLM).
+on:
+ workflow_dispatch:
+ pull_request:
+ types: [opened, synchronize, reopened]
+ branches: [main, master, development]
+ paths:
+ - "apps/**"
+ - "lib/**"
+ - "domain/**"
+ - "deploy/**"
+ - "scripts/ci/**"
+ - "scripts/local-kind-smoke-test.sh"
+ - "scripts/seed_demo.py"
+ - "scripts/smoke-uk-closure.sh"
+ - "Makefile"
+ - ".github/actions/kind/**"
+ - ".github/workflows/kind-helm-smoke.yml"
+ push:
+ branches: [main, master, development]
+ paths:
+ - "apps/**"
+ - "lib/**"
+ - "domain/**"
+ - "deploy/**"
+ - "scripts/ci/**"
+ - "scripts/local-kind-smoke-test.sh"
+ - "scripts/seed_demo.py"
+ - "scripts/smoke-uk-closure.sh"
+ - "Makefile"
+ - ".github/actions/kind/**"
+ - ".github/workflows/kind-helm-smoke.yml"
+
+concurrency:
+ group: kind-helm-smoke-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+ cancel-in-progress: true
+
+env:
+ KIND_NAMESPACE: general-simulation
+ HELM_RELEASE: general-simulation
+
+jobs:
+ kind-helm-smoke:
+ name: Helm lint, Kind deploy, API verify
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: azure/setup-helm@v4
+ with:
+ version: v3.19.4
+
+ - name: Helm chart lint
+ run: make lint-charts
+
+ - name: Deploy chart on Kind
+ uses: ./.github/actions/kind
+ with:
+ namespace: ${{ env.KIND_NAMESPACE }}
+ helm_release: ${{ env.HELM_RELEASE }}
+ registry: localhost:5001
+ run_builtin_smoke: "false"
+
+ - name: Verify deployment (health, seed, /query)
+ shell: bash
+ run: make kind-verify
+ env:
+ NAMESPACE: ${{ env.KIND_NAMESPACE }}
+ HELM_RELEASE_NAME: ${{ env.HELM_RELEASE }}
diff --git a/Makefile b/Makefile
index 5f42886..4738b0b 100644
--- a/Makefile
+++ b/Makefile
@@ -37,11 +37,24 @@ IMG_NEO4J := $(REGISTRY)/$(NEO4J_IMAGE_NAME):$(TAG)
# ── Helm chart paths ──────────────────────────────────────────────────────────
CHART_UMBRELLA := deploy/helm
+CHART_VALUES := deploy/helm/values.yaml
+CHART_VALUES_KIND := deploy/helm/values-kind.yaml
CHART_VALUES_SECRETS := deploy/helm/values-secrets.yaml
# Common flags passed to every helm command
HELM_RELEASE_NAME ?= general-simulation
HELM_COMMON := --namespace $(NAMESPACE)
+HELM_EXTRA_ARGS ?=
+KIND_DEPLOY_TIMEOUT ?= 15m
+# Optional on push, e.g. PUSH_EXTRA_ARGS=--tls-verify=false for Kind (localhost:5001)
+PUSH_EXTRA_ARGS ?=
+LOCAL_KIND_SMOKE_ARGS ?=
+
+# Kind: pin images to the local registry via global.registry / neo4j.customImage.
+HELM_KIND_IMAGE_SETS = \
+ --set global.registry=$(REGISTRY) \
+ --set global.imageTag=$(TAG) \
+ --set neo4j.image.customImage=$(IMG_NEO4J)
# Neo4j subchart reads image.customImage directly (not global.registry helpers).
_helm_neo4j_image_set := --set neo4j.image.customImage=$(IMG_NEO4J)
@@ -75,10 +88,13 @@ LOCAL_COMPOSE := deploy/local/composefile.yml
build build-postgres build-neo4j build-app \
deploy deploy-umbrella neo4j-connect \
package-chart \
- undeploy status lint-charts test-unit smoke-test \
+ undeploy status lint-charts helm-deps test-unit smoke-test \
local-up local-down local-bootstrap \
+ kind-build-images kind-push-images k8s-namespace \
+ helm-install-kind kind-undeploy \
+ kind-preflight kind-verify local-kind-smoke-test \
_guard-values-secrets \
- _guard-oc _guard-helm _guard-podman _guard-namespace \
+ _guard-oc _guard-helm _guard-podman _guard-namespace _guard-kubectl \
_remove-orphan-neo4j-resources _remove-openshift-routes
# ── Default target ────────────────────────────────────────────────────────────
@@ -95,11 +111,21 @@ help:
@printf " %-40s %s\n" "undeploy" "Uninstall Helm releases"
@printf " %-40s %s\n" "status" "helm list + oc get pods"
@printf " %-40s %s\n" "lint-charts" "helm lint"
+ @printf " %-40s %s\n" "helm-deps" "Update Helm chart dependencies"
@printf " %-40s %s\n" "test-unit" "Run unit tests (uv run pytest)"
@printf " %-40s %s\n" "smoke-test" "Seed UK demo + POST /query (auto cluster when deployed)"
@printf " %-40s %s\n" "local-up" "Start local Postgres + Neo4j (compose --wait)"
@printf " %-40s %s\n" "local-down" "Stop local Postgres + Neo4j"
@printf " %-40s %s\n" "local-bootstrap" "local-up + schema bootstrap (Postgres + Neo4j)"
+ @printf "\nKind / local Kubernetes:\n"
+ @printf " %-40s %s\n" "kind-preflight" "Check Podman VM / Kind node RAM before local smoke"
+ @printf " %-40s %s\n" "kind-build-images" "Build images for REGISTRY (default quay; use localhost:5001)"
+ @printf " %-40s %s\n" "kind-push-images" "Push kind-build-images to REGISTRY"
+ @printf " %-40s %s\n" "k8s-namespace" "Create kubectl namespace (NAMESPACE)"
+ @printf " %-40s %s\n" "helm-install-kind" "Install on Kind (values-kind.yaml + local REGISTRY)"
+ @printf " %-40s %s\n" "kind-verify" "Post-deploy checks (port-forward + /health + seed + /query)"
+ @printf " %-40s %s\n" "local-kind-smoke-test" "Full local Kind smoke (cluster + images + install + verify)"
+ @printf " %-40s %s\n" "kind-undeploy" "helm uninstall Kind release (kubectl; no oc)"
@printf "\nVariables:\n"
@printf " %-18s %s\n" "REGISTRY" "$(REGISTRY)"
@printf " %-18s %s\n" "APP_IMAGE_NAME" "$(APP_IMAGE_NAME)"
@@ -140,6 +166,10 @@ _guard-podman:
@command -v podman >/dev/null 2>&1 || \
{ echo "ERROR: 'podman' not found. Install Podman or substitute 'docker' by setting PODMAN=docker."; exit 1; }
+_guard-kubectl:
+ @command -v kubectl >/dev/null 2>&1 || \
+ { echo "ERROR: 'kubectl' not found. Install kubectl for Kind targets."; exit 1; }
+
# ── Container image builds ────────────────────────────────────────────────────
build: _guard-podman build-postgres build-neo4j build-app
@echo "==> All images built and pushed to $(REGISTRY)."
@@ -308,12 +338,15 @@ status: _guard-helm _guard-oc
@echo "==> Pod status:"
@oc get pods -n $(NAMESPACE)
-lint-charts: _guard-helm
+helm-deps: _guard-helm
+ @echo "==> Updating umbrella chart dependencies..."
helm repo add neo4j https://helm.neo4j.com/neo4j 2>/dev/null || true
helm repo update neo4j
helm repo add ai-architecture-charts $(LLM_SERVICE_CHART_REPO) 2>/dev/null || true
helm repo update ai-architecture-charts
helm dependency update $(CHART_UMBRELLA)
+
+lint-charts: helm-deps
helm lint $(CHART_UMBRELLA)
@echo "==> Chart passed lint."
@@ -332,3 +365,65 @@ local-bootstrap: local-up
smoke-test:
@chmod +x scripts/smoke-uk-closure.sh
./scripts/smoke-uk-closure.sh
+
+# ── Kind / plain Kubernetes ───────────────────────────────────────────────────
+
+kind-build-images: _guard-podman
+ @echo "==> Building Neo4j image: $(IMG_NEO4J)"
+ podman build \
+ --platform=linux/amd64 \
+ -f deploy/container_files/neo4j/Containerfile \
+ -t $(IMG_NEO4J) \
+ deploy/container_files/neo4j
+ @echo "==> Building Postgres image: $(IMG_POSTGRES)"
+ podman build \
+ --platform=linux/amd64 \
+ -f deploy/container_files/postgres/Containerfile \
+ -t $(IMG_POSTGRES) \
+ deploy/container_files/postgres
+ @echo "==> Building FastAPI app image: $(IMG_APP)"
+ podman build \
+ --platform=linux/amd64 \
+ -f deploy/container_files/api/Containerfile \
+ -t $(IMG_APP) \
+ .
+
+kind-push-images: _guard-podman
+ @echo "==> Pushing images to $(REGISTRY) ($(PUSH_EXTRA_ARGS))"
+ podman push $(PUSH_EXTRA_ARGS) $(IMG_NEO4J)
+ podman push $(PUSH_EXTRA_ARGS) $(IMG_POSTGRES)
+ podman push $(PUSH_EXTRA_ARGS) $(IMG_APP)
+
+k8s-namespace: _guard-kubectl
+ @echo "==> Ensuring namespace $(NAMESPACE)"
+ kubectl create namespace $(NAMESPACE) --dry-run=client -o yaml | kubectl apply -f -
+ kubectl config set-context --current --namespace=$(NAMESPACE) >/dev/null 2>&1 || true
+
+helm-install-kind: helm-deps k8s-namespace
+ @echo "==> Installing $(HELM_RELEASE_NAME) on Kind/Kubernetes (namespace: $(NAMESPACE), registry: $(REGISTRY))"
+ helm upgrade --install $(HELM_RELEASE_NAME) $(CHART_UMBRELLA) \
+ --namespace $(NAMESPACE) \
+ -f $(CHART_VALUES) \
+ -f $(CHART_VALUES_KIND) \
+ $(HELM_KIND_IMAGE_SETS) \
+ $(HELM_EXTRA_ARGS) \
+ --wait \
+ --timeout $(KIND_DEPLOY_TIMEOUT)
+
+kind-undeploy: _guard-helm _guard-kubectl
+ @echo "==> Removing Helm release $(HELM_RELEASE_NAME) from namespace $(NAMESPACE)..."
+ helm uninstall $(HELM_RELEASE_NAME) --namespace $(NAMESPACE) 2>/dev/null || true
+
+kind-preflight:
+ @chmod +x scripts/ci/kind-preflight.sh
+ @bash ./scripts/ci/kind-preflight.sh
+
+kind-verify:
+ @chmod +x scripts/ci/kind-verify-deployment.sh
+ @NAMESPACE=$(NAMESPACE) HELM_RELEASE=$(HELM_RELEASE_NAME) \
+ bash ./scripts/ci/kind-verify-deployment.sh
+
+local-kind-smoke-test:
+ @chmod +x scripts/local-kind-smoke-test.sh scripts/ci/kind-with-registry.sh \
+ scripts/ci/kind-preflight.sh scripts/ci/kind-verify-deployment.sh
+ @bash ./scripts/local-kind-smoke-test.sh $(LOCAL_KIND_SMOKE_ARGS)
diff --git a/README.md b/README.md
index ec14466..03eb1f9 100644
--- a/README.md
+++ b/README.md
@@ -49,11 +49,11 @@ The whole platform is built to run on **OpenShift**, which is a hard constraint
## System at a glance
-The platform is a small number of cooperating layers running inside one OpenShift cluster. The diagram below shows how they stack: an API and an orchestrator at the top, the three reasoning stages beneath, the LLM client as the inference/vector backend, and separate Neo4j and Postgres instances for graph and geo/vector state. Two things are worth noticing immediately — the reasoning stages are colour-coded by whether they use the LLM, and both the graph (Neo4j) and geo (PostGIS) paths bypass the LLM client to be queried directly.
+The platform is a small number of cooperating layers running inside one OpenShift cluster. The diagram below shows how they stack: FastAPI at the top, an in-process ReAct agent loop that chooses tools, the LLM client as the inference/embedding path, and separate Neo4j and Postgres instances for graph and geo/vector state. Two things are worth noticing immediately — tools are colour-coded by whether they need the LLM, and both the graph (Neo4j) and geo (PostGIS) paths bypass Llama Stack to be queried directly. Vector search hits pgvector via the LLM client (asyncpg), not a Llama Stack vector provider.

-*Figure 1 — Layered system overview. Everything runs inside OpenShift. The LLM client fronts inference and vector/RAG; graph (Neo4j) and live/geo (PostGIS) are queried directly.*
+*Figure 1 — Layered system overview. Everything runs inside OpenShift. ReAct tools drive Neo4j / PostGIS / pgvector; Llama Stack is the inference gateway (optional in-cluster vLLM behind it).*
The remaining sections walk through each component: what it is, why it is there, and how it relates to its neighbours.
@@ -175,7 +175,7 @@ A `POST /query` request kicks off the ReAct agent loop. The diagram below captur

-*Figure 2 — The ReAct query lifecycle. The LLM decides which tools to call; every tool invocation and its result appear in the `tool_call_trace` field of the response.*
+*Figure 2 — The ReAct query lifecycle. After a spatial AFFECTED_BY refresh, the LLM decides which tools to call; every invocation appears in `tool_call_trace`.*
**Typical agent sequence for an impact question:**
@@ -208,7 +208,7 @@ This is what makes multiple concurrent what-if scenarios trivial — each is an

-*Figure 3 — The overlay mechanism. Ground truth (left) is read-only at query time. The event and its affected-entity references (right) are injected and removable, leaving the base graph intact.*
+*Figure 3 — The overlay mechanism. Ground truth (Neo4j entity graph + PostGIS live snapshot) is read-only at query time. The SimulationEvent, AFFECTED_BY edges, and pgvector narrative (right) are injected and removable.*
> **What kind of simulation this is (and isn’t):** This is a **dependency-and-impact reasoning** engine: it propagates effects through a known graph and applies solver logic on top. It is **not** a tick-by-tick discrete-event physics simulation (e.g. AnyLogic). That is an intentional trade: you gain explainability, speed, and concurrent what-if scenarios; you give up stochastic second-by-second temporal dynamics. Because the Stage 2 solver is pluggable, a full discrete-event engine can be dropped into that slot later without changing anything else.
@@ -226,7 +226,7 @@ solvers). Which packages load is controlled by **`ENABLED_DOMAINS`**

-*Figure 4 — The fixed core (left) versus the per-domain swap seams (right). Domain adaptation touches only the right-hand column.*
+*Figure 4 — The fixed core (left) versus per-domain swap seams under `domain/` (right), selected by `ENABLED_DOMAINS`. Domain adaptation touches only the right-hand column.*
The reason this works is that impact propagation is graph traversal in every domain. A port closure cascading through dependent routes and a stopped machine cascading through dependent cells are the **same** Cypher traversal over a **different** schema. The table below makes the mapping concrete.
diff --git a/deploy/helm/README.md b/deploy/helm/README.md
index 9b85fc1..486ee85 100644
--- a/deploy/helm/README.md
+++ b/deploy/helm/README.md
@@ -8,6 +8,7 @@ external subchart dependencies.
| File | Purpose |
|------|---------|
| [`values.yaml`](values.yaml) | **Default config** — component toggles, models, images |
+| [`values-kind.yaml`](values-kind.yaml) | Kind / plain Kubernetes CI overrides (no Routes, fake LLM, demo secrets) |
| [`values-secrets.yaml.example`](values-secrets.yaml.example) | Template for passwords/tokens (copy to `values-secrets.yaml`) |
## Template layout
@@ -65,3 +66,35 @@ enable the CronJob. Domain keys (`api.enabledDomains`, `ingestion.adapterId`, et
default via `templates/_helpers.tpl`.
**Values flow:** see [`VALUES_MAPPING.md`](../../docs/VALUES_MAPPING.md).
+
+## Kind / local Kubernetes smoke
+
+CI and local verification use Kind with a local registry (`localhost:5001`),
+`values-kind.yaml` (Routes off, Llama Stack off, `api.llm.backend: fake`), then
+API checks: `GET /health`, demo seed, `POST /query`.
+
+**RAM:** Neo4j’s chart requires at least 2Gi. Local Podman VMs should be ≥8Gi —
+run `make kind-preflight` first. GitHub `ubuntu-latest` is fine.
+
+**UIDs:** Kind has no OpenShift SCC, so `values-kind.yaml` pins Postgres to UID
+999 and Neo4j to UID 7474. Without that, pods stay in `CreateContainerConfigError`
+(`runAsNonRoot` with a root or non-numeric image USER).
+
+```bash
+# One-shot local path (Podman + Kind)
+make local-kind-smoke-test
+
+# Or step by step:
+bash scripts/ci/kind-with-registry.sh
+make kind-build-images REGISTRY=localhost:5001
+make kind-push-images REGISTRY=localhost:5001 PUSH_EXTRA_ARGS=--tls-verify=false
+make helm-install-kind REGISTRY=localhost:5001
+make kind-verify
+
+# Reuse an existing cluster / images:
+make local-kind-smoke-test LOCAL_KIND_SMOKE_ARGS='--skip-build'
+make local-kind-smoke-test LOCAL_KIND_SMOKE_ARGS='--recreate --cleanup'
+```
+
+GitHub Actions: [`.github/workflows/kind-helm-smoke.yml`](../../.github/workflows/kind-helm-smoke.yml)
+uses [`.github/actions/kind`](../../.github/actions/kind/action.yaml).
diff --git a/deploy/helm/templates/postgres/statefulset.yaml b/deploy/helm/templates/postgres/statefulset.yaml
index 0f910af..62c624d 100644
--- a/deploy/helm/templates/postgres/statefulset.yaml
+++ b/deploy/helm/templates/postgres/statefulset.yaml
@@ -17,13 +17,16 @@ spec:
labels:
{{- include "postgres.selectorLabels" . | nindent 8 }}
spec:
- # OpenShift restricted SCC: leave podSecurityContext empty so the platform
- # assigns UID/fsGroup. Kind sets postgres.podSecurityContext.runAsUser=999.
+ # OpenShift restricted SCC: no fixed runAsUser/fsGroup — the platform assigns
+ # a namespace UID and fsGroup; the postgres image supports arbitrary UID.
+ # Kind has no SCC: set postgres.podSecurityContext.runAsUser (999) in values-kind.yaml.
+ {{- if .Values.postgres.podSecurityContext }}
+ securityContext:
+ {{- toYaml .Values.postgres.podSecurityContext | nindent 8 }}
+ {{- else }}
securityContext:
runAsNonRoot: true
- {{- with .Values.postgres.podSecurityContext }}
- {{- toYaml . | nindent 8 }}
- {{- end }}
+ {{- end }}
containers:
- name: postgres
image: {{ include "postgres.containerImage" . }}
@@ -59,13 +62,15 @@ spec:
resources:
{{- toYaml . | nindent 12 }}
{{- end }}
+ {{- if .Values.postgres.containerSecurityContext }}
+ securityContext:
+ {{- toYaml .Values.postgres.containerSecurityContext | nindent 12 }}
+ {{- else }}
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop: ["ALL"]
- {{- with .Values.postgres.containerSecurityContext }}
- {{- toYaml . | nindent 12 }}
- {{- end }}
+ {{- end }}
livenessProbe:
exec:
command:
diff --git a/deploy/helm/values-kind.yaml b/deploy/helm/values-kind.yaml
new file mode 100644
index 0000000..d773893
--- /dev/null
+++ b/deploy/helm/values-kind.yaml
@@ -0,0 +1,130 @@
+# Kind / plain Kubernetes CI overrides (use with: make helm-install-kind)
+#
+# Availability contract for helm --wait (must become Ready/Complete):
+# postgres, neo4j (Service name neo4j), general-sim-api, then
+# general-sim-bootstrap post-install hook.
+#
+# Kept off so they cannot block --wait or pull heavy images:
+# llama-stack, llm-service, OpenSky ingestion CronJob.
+# OpenShift Routes disabled (no router on Kind).
+#
+# Demo passwords so Postgres/Neo4j secret templates render without
+# values-secrets.yaml. Local Podman + Kind needs an 8Gi Podman VM
+# (Neo4j chart minimum is 2Gi). Run `make kind-preflight` before local smoke.
+
+openshift:
+ neo4j:
+ scc:
+ enabled: false
+
+global:
+ registry: localhost:5001
+ imageTag: latest
+ postgres:
+ password: kind-demo-password
+ neo4j:
+ password: kind-demo-password
+ models:
+ openai:
+ enabled: false
+ deepseek-r1-distill-qwen-1-5b:
+ enabled: false
+ external-model:
+ enabled: false
+
+postgres:
+ enabled: true
+ postgres:
+ password: kind-demo-password
+ # Kind has no OpenShift SCC to assign a UID. The image USER is empty (root),
+ # so runAsNonRoot alone fails with CreateContainerConfigError — pin UID 999.
+ podSecurityContext:
+ runAsNonRoot: true
+ runAsUser: 999
+ runAsGroup: 999
+ fsGroup: 999
+ containerSecurityContext:
+ allowPrivilegeEscalation: false
+ runAsNonRoot: true
+ runAsUser: 999
+ capabilities:
+ drop: ["ALL"]
+
+pgvector:
+ enabled: false
+
+neo4j:
+ enabled: true
+ fullnameOverride: neo4j
+ disableLookups: true
+ # SCC off skips ServiceAccount/neo4j-sa; clear the chart default SA.
+ podSpec:
+ serviceAccountName: default
+ # Image USER is the string "neo4j"; Kind cannot verify non-root without a
+ # numeric runAsUser (UID 7474 matches the image passwd entry).
+ securityContext:
+ runAsNonRoot: true
+ runAsUser: 7474
+ runAsGroup: 7474
+ fsGroup: 7474
+ fsGroupChangePolicy: OnRootMismatch
+ containerSecurityContext:
+ runAsNonRoot: true
+ runAsUser: 7474
+ runAsGroup: 7474
+ allowPrivilegeEscalation: false
+ capabilities:
+ drop: ["ALL"]
+ neo4j:
+ resources:
+ # Official neo4j chart fails helm template below 2Gi — this is the floor.
+ cpu: "500m"
+ memory: 2Gi
+ volumes:
+ data:
+ mode: dynamic
+ dynamic:
+ accessModes:
+ - ReadWriteOnce
+ requests:
+ storage: 2Gi
+ # Kind local-path provisioner (default StorageClass name).
+ storageClassName: standard
+
+llama-stack:
+ enabled: false
+
+llm-service:
+ enabled: false
+
+api:
+ enabled: true
+ route:
+ enabled: false
+ llm:
+ backend: fake
+ # Not used by FakeLLMClient; keeps Secret non-empty for Kind.
+ apiKey: kind-unused
+ baseUrl: http://127.0.0.1:9/v1
+ postgres:
+ password: kind-demo-password
+ neo4j:
+ password: kind-demo-password
+ # Fake backend ignores the model id; keep a stable placeholder.
+ models:
+ generation: fake/canned
+ embedding: sentence-transformers/nomic-ai/nomic-embed-text-v1.5
+
+bootstrap:
+ enabled: true
+ postgres:
+ password: kind-demo-password
+ neo4j:
+ password: kind-demo-password
+
+ingestion:
+ enabled: false
+ postgres:
+ password: kind-demo-password
+ neo4j:
+ password: kind-demo-password
diff --git a/docs/images/architecture-overview.mmd b/docs/images/architecture-overview.mmd
new file mode 100644
index 0000000..3898b78
--- /dev/null
+++ b/docs/images/architecture-overview.mmd
@@ -0,0 +1,54 @@
+%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Inter, Helvetica, Arial, sans-serif", "fontSize": "14px", "primaryColor": "#e8f0fe", "primaryBorderColor": "#1a73e8", "primaryTextColor": "#202124", "lineColor": "#5f6368", "secondaryColor": "#e6f4ea", "tertiaryColor": "#fce8e6"}}}%%
+flowchart TB
+ subgraph OCP["OpenShift cluster — hard platform constraint"]
+ direction TB
+
+ API["FastAPI — POST /query · /admin/*"]
+ REACT["ReAct agent loop — lib/reasoning/pipeline.py
LLM chooses tools · max 6 rounds · tool_call_trace"]
+
+ API --> REACT
+
+ subgraph TOOLS["Agent tools — called in any order"]
+ direction LR
+ T1["get_affected_subgraph
NO LLM · Neo4j Cypher"]
+ T2["solve_impact
NO LLM · PostGIS + Solver"]
+ T3["search_scenario_context
via LLM client · pgvector"]
+ T4["run_ingestion_pull
on-demand adapter"]
+ end
+
+ REACT --> TOOLS
+
+ LLM["LLM client — OpenAI-compatible
inference + embed · pgvector via asyncpg"]
+ LS["Llama Stack — inference gateway
maas · openai · local vLLM"]
+ VLLM["vLLM optional — llm-service
OpenShift AI / KServe"]
+
+ T3 --> LLM
+ REACT --> LLM
+ LLM --> LS
+ LS -.-> VLLM
+
+ subgraph DIRECT["Queried directly — not via Llama Stack"]
+ direction LR
+ NJ["Neo4j — dependency graph
+ SimulationEvent overlays"]
+ PG["PostgreSQL StatefulSet
pgvector + PostGIS
no AGE"]
+ end
+
+ T1 --> NJ
+ T2 --> PG
+ LLM --> PG
+ T4 --> PG
+ end
+
+ classDef entry fill:#1a73e8,stroke:#174ea6,color:#fff
+ classDef agent fill:#9334e6,stroke:#681da8,color:#fff
+ classDef nollm fill:#e6f4ea,stroke:#137333,color:#137333
+ classDef llm fill:#f3e8fd,stroke:#9334e6,color:#5b2d8e
+ classDef infra fill:#fff3e0,stroke:#e37400,color:#b06000
+ classDef store fill:#e8f0fe,stroke:#1a73e8,color:#174ea6
+
+ class API entry
+ class REACT agent
+ class T1,T2 nollm
+ class T3,T4,LLM llm
+ class LS,VLLM infra
+ class NJ,PG store
diff --git a/docs/images/architecture-overview.png b/docs/images/architecture-overview.png
index 9fad429..bb431a5 100644
Binary files a/docs/images/architecture-overview.png and b/docs/images/architecture-overview.png differ
diff --git a/docs/images/domain-seams.mmd b/docs/images/domain-seams.mmd
new file mode 100644
index 0000000..7032a51
--- /dev/null
+++ b/docs/images/domain-seams.mmd
@@ -0,0 +1,35 @@
+%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Inter, Helvetica, Arial, sans-serif", "fontSize": "14px"}}}%%
+flowchart LR
+ subgraph CORE["FIXED CORE — identical across domains"]
+ direction TB
+ C1["OpenShift + Helm umbrella"]
+ C2["Llama Stack inference gateway"]
+ C3["LLM client · OpenAI-compatible"]
+ C4["Neo4j graph + overlays"]
+ C5["Postgres: pgvector + PostGIS"]
+ C6["ReAct agent pipeline + tools"]
+ C7["Simulation overlay mechanism"]
+ C8["Canonical entity schema"]
+ C1 --- C2 --- C3 --- C4 --- C5 --- C6 --- C7 --- C8
+ end
+
+ PLUG["plug into
ENABLED_DOMAINS"]
+
+ subgraph SEAMS["SWAP SEAMS — per domain package under domain/"]
+ direction TB
+ S1["1. Ingestion adapters
aviation: OpenSky · shipping: fixture/API
mfg: OPC-UA / MQTT / SCADA"]
+ S2["2. Graph schema / seed wiring
Port·Route·Region vs ISA-95 plant"]
+ S3["3. Solver optional Stage 2
pathfinding vs rescheduling
default: StubSolver"]
+ S4["4. Domain RAG context
logistics precedent vs SOPs / playbooks"]
+ S1 --- S2 --- S3 --- S4
+ end
+
+ CORE --> PLUG --> SEAMS
+
+ classDef core fill:#e8f0fe,stroke:#1a73e8,color:#174ea6
+ classDef seam fill:#fef7e0,stroke:#e37400,color:#b06000
+ classDef link fill:#fff,stroke:#5f6368,color:#5f6368
+
+ class C1,C2,C3,C4,C5,C6,C7,C8 core
+ class S1,S2,S3,S4 seam
+ class PLUG link
diff --git a/docs/images/domain-seams.png b/docs/images/domain-seams.png
index 054568d..cca4a5b 100644
Binary files a/docs/images/domain-seams.png and b/docs/images/domain-seams.png differ
diff --git a/docs/images/query-flow.mmd b/docs/images/query-flow.mmd
new file mode 100644
index 0000000..19ba9d3
--- /dev/null
+++ b/docs/images/query-flow.mmd
@@ -0,0 +1,40 @@
+%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Inter, Helvetica, Arial, sans-serif", "fontSize": "14px"}}}%%
+flowchart TB
+ START["POST /query
{ question, scenario_id }"]
+ PRE["Pre-step: refresh AFFECTED_BY
from PostGIS bbox → Neo4j"]
+ LOOP["ReAct loop — LLM orchestrates
up to 6 rounds · tool_choice required then auto"]
+
+ START --> PRE --> LOOP
+
+ LOOP --> T1
+ LOOP --> T2
+ LOOP --> T3
+ LOOP --> T4
+
+ T1["① get_affected_subgraph
Neo4j: AFFECTED_BY seeds + DEPENDS_ON / FEEDS / CARRIES expand"]
+ T2["② solve_impact
PostGIS live state + StubSolver / domain solver"]
+ T3["③ search_scenario_context
pgvector narrative chunks via LLM client"]
+ T4["④ run_ingestion_pull optional
refresh live entities from adapter"]
+
+ T1 --> ANS
+ T2 --> ANS
+ T3 --> ANS
+ T4 --> ANS
+
+ ANS["LLM final answer grounded in tool outputs"]
+ OUT["QueryResponse
answer · affected_entities · solver · tool_call_trace"]
+
+ ANS --> OUT
+
+ classDef entry fill:#1a73e8,stroke:#174ea6,color:#fff
+ classDef pre fill:#e8f0fe,stroke:#1a73e8,color:#174ea6
+ classDef agent fill:#9334e6,stroke:#681da8,color:#fff
+ classDef tool fill:#e6f4ea,stroke:#137333,color:#137333
+ classDef opt fill:#fef7e0,stroke:#f9ab00,color:#7a5c00
+ classDef out fill:#1a73e8,stroke:#174ea6,color:#fff
+
+ class START,OUT entry
+ class PRE pre
+ class LOOP,ANS agent
+ class T1,T2,T3 tool
+ class T4 opt
diff --git a/docs/images/query-flow.png b/docs/images/query-flow.png
index 20457bb..f5b978f 100644
Binary files a/docs/images/query-flow.png and b/docs/images/query-flow.png differ
diff --git a/docs/images/simulation-overlay.mmd b/docs/images/simulation-overlay.mmd
new file mode 100644
index 0000000..588b300
--- /dev/null
+++ b/docs/images/simulation-overlay.mmd
@@ -0,0 +1,31 @@
+%%{init: {"theme": "base", "themeVariables": {"fontFamily": "Inter, Helvetica, Arial, sans-serif", "fontSize": "14px"}}}%%
+flowchart LR
+ subgraph GT["GROUND TRUTH — read-only at query time"]
+ direction TB
+ NJG["Neo4j Entity graph
A → B ← C · B → D
FEEDS / DEPENDS_ON / CARRIES"]
+ PGS["PostGIS live snapshot
positions · states · geometry"]
+ NJG --- PGS
+ end
+
+ REF[["references — never edits"]]
+
+ subgraph OV["OVERLAY — injected, removable in one op"]
+ direction TB
+ EV["SimulationEvent
scenario_id = S1"]
+ AB["AFFECTED_BY → Entity B, D
Neo4j overlay edges"]
+ VEC["Event narrative in pgvector
tagged scenario_id = S1"]
+ NOTE["Multiple scenarios coexist
S1, S2, S3… independent what-ifs"]
+ EV --> AB
+ EV --> VEC
+ EV --- NOTE
+ end
+
+ GT --> REF --> OV
+
+ classDef truth fill:#e8f0fe,stroke:#1a73e8,color:#174ea6
+ classDef overlay fill:#fce8e6,stroke:#c5221f,color:#a50e0e
+ classDef link fill:#fff,stroke:#c5221f,color:#c5221f
+
+ class NJG,PGS truth
+ class EV,AB,VEC,NOTE overlay
+ class REF link
diff --git a/docs/images/simulation-overlay.png b/docs/images/simulation-overlay.png
index c3a33c1..b144e63 100644
Binary files a/docs/images/simulation-overlay.png and b/docs/images/simulation-overlay.png differ
diff --git a/scripts/ci/kind-preflight.sh b/scripts/ci/kind-preflight.sh
new file mode 100755
index 0000000..746d49f
--- /dev/null
+++ b/scripts/ci/kind-preflight.sh
@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Read-only checks before local Kind full-stack smoke (Podman VM + Kind node RAM).
+# Neo4j's official Helm chart requires 2Gi memory minimum; a 2Gi Podman VM cannot
+# schedule it. GHA ubuntu-latest runners have enough RAM — skip this in CI.
+set -euo pipefail
+
+USE_PODMAN="${USE_PODMAN:-1}"
+MIN_PODMAN_MEMORY_MIB="${MIN_PODMAN_MEMORY_MIB:-8192}"
+MIN_KIND_NODE_MIB="${MIN_KIND_NODE_MIB:-3584}"
+
+log() { echo ">>> $*"; }
+fail() { echo "ERROR: $*" >&2; exit 1; }
+
+podman_machine_memory_mib() {
+ podman machine inspect --format '{{.Resources.Memory}}' 2>/dev/null | head -1 | tr -d '[:space:]'
+}
+
+kind_node_allocatable_mib() {
+ if ! command -v kubectl >/dev/null 2>&1; then
+ echo 0
+ return 0
+ fi
+ local raw
+ raw="$(kubectl get nodes -o jsonpath='{.items[0].status.allocatable.memory}' 2>/dev/null || true)"
+ case "${raw}" in
+ *Ki) echo $(( ${raw%Ki} / 1024 )) ;;
+ *Mi) echo "${raw%Mi}" ;;
+ *Gi) echo $(( ${raw%Gi} * 1024 )) ;;
+ *) echo 0 ;;
+ esac
+}
+
+if [[ "${USE_PODMAN}" == "1" ]] && command -v podman >/dev/null 2>&1; then
+ mem="$(podman_machine_memory_mib)"
+ if [[ -n "${mem}" && "${mem}" =~ ^[0-9]+$ && "${mem}" -lt "${MIN_PODMAN_MEMORY_MIB}" ]]; then
+ fail "Podman machine has ${mem} MiB RAM; full-stack Kind needs >= ${MIN_PODMAN_MEMORY_MIB} MiB
+(Neo4j requests 2Gi — official chart minimum).
+
+Resize the VM, then recreate the Kind cluster:
+ podman machine stop
+ podman machine set --memory ${MIN_PODMAN_MEMORY_MIB}
+ podman machine start
+ make local-kind-smoke-test LOCAL_KIND_SMOKE_ARGS='--recreate --skip-build'"
+ fi
+ if [[ -n "${mem}" && "${mem}" =~ ^[0-9]+$ ]]; then
+ log "Podman machine memory: ${mem} MiB (minimum ${MIN_PODMAN_MEMORY_MIB} MiB)"
+ fi
+fi
+
+alloc_mib="$(kind_node_allocatable_mib)"
+if [[ "${alloc_mib}" =~ ^[0-9]+$ && "${alloc_mib}" -gt 0 && "${alloc_mib}" -lt "${MIN_KIND_NODE_MIB}" ]]; then
+ fail "Kind node allocatable memory is ${alloc_mib} MiB; Neo4j's 2Gi request will stay Pending.
+
+After resizing the Podman VM, recreate the cluster so kubelet sees the new RAM:
+ make local-kind-smoke-test LOCAL_KIND_SMOKE_ARGS='--recreate --skip-build'"
+fi
+if [[ "${alloc_mib}" =~ ^[0-9]+$ && "${alloc_mib}" -gt 0 ]]; then
+ log "Kind node allocatable memory: ${alloc_mib} MiB (minimum ${MIN_KIND_NODE_MIB} MiB)"
+fi
+
+log "Kind preflight passed"
diff --git a/scripts/ci/kind-verify-deployment.sh b/scripts/ci/kind-verify-deployment.sh
new file mode 100755
index 0000000..aa4e580
--- /dev/null
+++ b/scripts/ci/kind-verify-deployment.sh
@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# Post-deploy checks for Kind + Helm install (used by kind-helm-smoke workflow).
+# API-only: /health, seed demo scenarios, POST /query (expects LLM_BACKEND=fake).
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+NAMESPACE="${NAMESPACE:-general-simulation}"
+HELM_RELEASE="${HELM_RELEASE:-general-simulation}"
+API_PF_PORT="${API_PF_PORT:-18000}"
+CURL_MAX_TIME="${CURL_MAX_TIME:-120}"
+QUERY_TIMEOUT="${QUERY_TIMEOUT:-120}"
+SCENARIO_ID="${SCENARIO_ID:-opensky-uk-closure-001}"
+QUESTION="${QUESTION:-UK airspace is closed due to a NATS GPS failure. Which aircraft are affected?}"
+
+log() { echo ">>> $*"; }
+fail() { echo "ERROR: $*" >&2; exit 1; }
+
+body_contains() {
+ local needle="$1"
+ local body="$2"
+ [[ "${body}" == *"${needle}"* ]]
+}
+
+cleanup() {
+ if [ -n "${API_PF_PID:-}" ] && kill -0 "${API_PF_PID}" 2>/dev/null; then
+ kill "${API_PF_PID}" 2>/dev/null || true
+ fi
+}
+trap cleanup EXIT
+
+wait_for_url() {
+ local url="$1"
+ local attempts="${2:-30}"
+ local i
+ for i in $(seq 1 "${attempts}"); do
+ if curl -sf --max-time "${CURL_MAX_TIME}" "${url}" >/dev/null 2>&1; then
+ return 0
+ fi
+ sleep 2
+ done
+ return 1
+}
+
+curl_body() {
+ local url="$1"
+ curl -sf --max-time "${CURL_MAX_TIME}" "${url}"
+}
+
+seed_demo() {
+ log "Seeding demo scenarios via kubectl exec (seed-demo)"
+ kubectl wait -n "${NAMESPACE}" --for=condition=available \
+ deployment/general-sim-api --timeout=180s
+
+ if kubectl exec -n "${NAMESPACE}" deploy/general-sim-api -c api -- \
+ test -x /app/.venv/bin/seed-demo 2>/dev/null; then
+ kubectl exec -n "${NAMESPACE}" deploy/general-sim-api -c api -- seed-demo
+ return
+ fi
+ if kubectl exec -n "${NAMESPACE}" deploy/general-sim-api -c api -- \
+ test -f /app/scripts/seed_demo.py 2>/dev/null; then
+ kubectl exec -n "${NAMESPACE}" deploy/general-sim-api -c api -- \
+ /app/.venv/bin/python /app/scripts/seed_demo.py
+ return
+ fi
+
+ local seed_script="${ROOT_DIR}/scripts/seed_demo.py"
+ [[ -f "${seed_script}" ]] || fail "missing seed script: ${seed_script}"
+ local pod
+ pod="$(kubectl get pod -n "${NAMESPACE}" -l app.kubernetes.io/name=general-sim-api \
+ -o jsonpath='{.items[0].metadata.name}')"
+ [[ -n "${pod}" ]] || fail "no general-sim-api pod in namespace ${NAMESPACE}"
+ log "API image has no bundled seed script; copying from repo"
+ kubectl cp "${seed_script}" "${NAMESPACE}/${pod}:/tmp/seed_demo.py" -c api
+ kubectl exec -n "${NAMESPACE}" deploy/general-sim-api -c api -- \
+ /app/.venv/bin/python /tmp/seed_demo.py
+}
+
+log "Helm release status"
+helm status "${HELM_RELEASE}" --namespace "${NAMESPACE}"
+
+log "Workloads in namespace ${NAMESPACE}"
+kubectl get deploy,sts,svc,pods -n "${NAMESPACE}"
+
+log "Expect general-sim-api Deployment Available"
+kubectl wait -n "${NAMESPACE}" --for=condition=available \
+ deployment/general-sim-api --timeout=180s
+
+log "Port-forward API Service"
+kubectl port-forward -n "${NAMESPACE}" svc/general-sim-api \
+ "${API_PF_PORT}:8000" >/tmp/kind-pf-api.log 2>&1 &
+API_PF_PID=$!
+wait_for_url "http://127.0.0.1:${API_PF_PORT}/health" 45 \
+ || fail "API /health not ready (see /tmp/kind-pf-api.log)"
+
+HEALTH=$(curl_body "http://127.0.0.1:${API_PF_PORT}/health")
+body_contains '"status": "ok"' "${HEALTH}" || body_contains '"status":"ok"' "${HEALTH}" \
+ || fail "unexpected /health body: ${HEALTH}"
+body_contains 'reachable' "${HEALTH}" || fail "/health db not reachable: ${HEALTH}"
+body_contains 'agent_tool_choice' "${HEALTH}" || fail "/health missing agent_tool_choice marker: ${HEALTH}"
+log "PASS GET /health"
+
+seed_demo
+log "PASS demo seed"
+
+QUERY_JSON="$(SCENARIO_ID="${SCENARIO_ID}" QUESTION="${QUESTION}" python3 - <<'PY'
+import json, os
+print(json.dumps({
+ "scenario_id": os.environ["SCENARIO_ID"],
+ "question": os.environ["QUESTION"],
+ "allow_live_ingestion": False,
+}))
+PY
+)"
+
+log "POST /query (FakeLLMClient; timeout=${QUERY_TIMEOUT}s)"
+QUERY=$(curl -sf --max-time "${QUERY_TIMEOUT}" \
+ -X POST "http://127.0.0.1:${API_PF_PORT}/query" \
+ -H 'Content-Type: application/json' \
+ -d "${QUERY_JSON}") \
+ || fail "POST /query failed"
+
+body_contains "\"scenario_id\": \"${SCENARIO_ID}\"" "${QUERY}" \
+ || body_contains "\"scenario_id\":\"${SCENARIO_ID}\"" "${QUERY}" \
+ || fail "unexpected /query scenario_id: ${QUERY}"
+body_contains '"answer"' "${QUERY}" || fail "/query missing answer: ${QUERY}"
+body_contains 'FakeLLMClient' "${QUERY}" \
+ || fail "/query answer does not look like FakeLLMClient output (is api.llm.backend=fake?): ${QUERY}"
+log "PASS POST /query (fake LLM)"
+
+log "All Kind deployment verification checks passed."
diff --git a/scripts/ci/kind-with-registry.sh b/scripts/ci/kind-with-registry.sh
new file mode 100755
index 0000000..b9aaa1a
--- /dev/null
+++ b/scripts/ci/kind-with-registry.sh
@@ -0,0 +1,66 @@
+#!/bin/sh
+# Local Kind cluster + registry mirror (localhost:5001).
+# Set USE_PODMAN=1 for Podman (GHA and local). Otherwise uses docker, or podman if docker is absent.
+set -o errexit
+
+use_podman() {
+ [ "${USE_PODMAN:-0}" = "1" ] || ! command -v docker >/dev/null 2>&1
+}
+
+if use_podman; then
+ if ! command -v podman >/dev/null 2>&1; then
+ echo "podman is required but not installed" >&2
+ exit 1
+ fi
+ echo "Using Podman for Kind and the local registry (KIND_EXPERIMENTAL_PROVIDER=podman)"
+ export KIND_EXPERIMENTAL_PROVIDER=podman
+ docker() {
+ podman "$@"
+ }
+else
+ echo "Using Docker for Kind and the local registry"
+fi
+
+reg_name='kind-registry'
+reg_port='5001'
+if [ "$(docker inspect -f '{{.State.Running}}' "${reg_name}" 2>/dev/null || true)" != 'true' ]; then
+ docker run \
+ -d --restart=always -p "127.0.0.1:${reg_port}:5000" --network bridge --name "${reg_name}" \
+ registry:2
+fi
+
+cat </dev/null || true)" = 'null' ] || \
+ [ "$(docker inspect -f='{{json .NetworkSettings.Networks.kind}}' "${reg_name}" 2>/dev/null || true)" = '' ]; then
+ docker network connect kind "${reg_name}" 2>/dev/null || true
+fi
+
+cat <>> $*"; }
+fail() { echo "ERROR: $*" >&2; exit 1; }
+
+usage() {
+ sed -n '2,24p' "$0" | sed 's/^# //'
+}
+
+need_cmd() {
+ command -v "$1" >/dev/null 2>&1 || fail "'$1' is required but not on PATH"
+}
+
+container_cli() {
+ if [[ "${USE_PODMAN}" == "1" ]]; then
+ echo podman
+ elif command -v docker >/dev/null 2>&1; then
+ echo docker
+ else
+ echo podman
+ fi
+}
+
+kind_cluster_exists() {
+ kind get clusters 2>/dev/null | grep -qx "${KIND_CLUSTER}"
+}
+
+delete_kind_stack() {
+ local cli
+ cli="$(container_cli)"
+ log "Deleting Kind cluster '${KIND_CLUSTER}' and registry '${REG_NAME}'"
+ kind delete cluster --name "${KIND_CLUSTER}" 2>/dev/null || true
+ "${cli}" rm -f "${REG_NAME}" >/dev/null 2>&1 || true
+}
+
+dump_cluster() {
+ set +e
+ echo "=== kubectl get deploy,sts,svc,pvc,job,pods -n ${NAMESPACE} ==="
+ kubectl get deploy,sts,svc,pvc,job,pods -n "${NAMESPACE}" -o wide
+ echo "=== kubectl get events -n ${NAMESPACE} (last 40) ==="
+ kubectl get events -n "${NAMESPACE}" --sort-by=.lastTimestamp 2>/dev/null | tail -40
+ echo "=== helm status ==="
+ helm status "${HELM_RELEASE}" -n "${NAMESPACE}" || true
+ set -e
+}
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --recreate) RECREATE=1 ;;
+ --skip-build) SKIP_BUILD=1 ;;
+ --cleanup) CLEANUP=1 ;;
+ -h|--help)
+ usage
+ exit 0
+ ;;
+ *)
+ fail "Unknown argument: $1 (see --help)"
+ ;;
+ esac
+ shift
+done
+
+need_cmd kind
+need_cmd kubectl
+need_cmd helm
+need_cmd make
+if [[ "${USE_PODMAN}" == "1" ]]; then
+ need_cmd podman
+fi
+
+log "Running Kind preflight (Podman VM / node RAM)"
+USE_PODMAN="${USE_PODMAN}" make kind-preflight
+
+if [[ "${RECREATE}" == "1" ]]; then
+ delete_kind_stack
+fi
+
+if kind_cluster_exists; then
+ log "Kind cluster '${KIND_CLUSTER}' already exists — skipping create (pass --recreate for a clean cluster)"
+ USE_PODMAN="${USE_PODMAN}" make kind-preflight
+else
+ log "Creating Kind cluster with local registry (USE_PODMAN=${USE_PODMAN})"
+ USE_PODMAN="${USE_PODMAN}" bash "${ROOT}/scripts/ci/kind-with-registry.sh"
+ USE_PODMAN="${USE_PODMAN}" make kind-preflight
+fi
+
+if [[ "${SKIP_BUILD}" == "1" ]]; then
+ log "Skipping image build (--skip-build)"
+else
+ log "Building images for ${REGISTRY}"
+ make kind-build-images REGISTRY="${REGISTRY}"
+ log "Pushing images to ${REGISTRY}"
+ make kind-push-images REGISTRY="${REGISTRY}" PUSH_EXTRA_ARGS=--tls-verify=false
+fi
+
+log "Helm install (values-kind.yaml, registry=${REGISTRY})"
+if ! make helm-install-kind \
+ NAMESPACE="${NAMESPACE}" \
+ HELM_RELEASE_NAME="${HELM_RELEASE}" \
+ REGISTRY="${REGISTRY}"; then
+ dump_cluster
+ fail "helm-install-kind failed (cluster dump above)"
+fi
+
+log "Running Kind verify (health + seed + /query)"
+make kind-verify NAMESPACE="${NAMESPACE}" HELM_RELEASE_NAME="${HELM_RELEASE}"
+
+if [[ "${CLEANUP}" == "1" ]]; then
+ delete_kind_stack
+ log "Cleanup complete"
+else
+ log "Kind smoke passed. Cluster left running (pass --cleanup to delete it)."
+ log " kubectl get pods -n ${NAMESPACE}"
+ log " make kind-undeploy NAMESPACE=${NAMESPACE} HELM_RELEASE_NAME=${HELM_RELEASE}"
+fi
diff --git a/scripts/smoke-uk-closure.sh b/scripts/smoke-uk-closure.sh
index 860a7b0..54c1ef7 100755
--- a/scripts/smoke-uk-closure.sh
+++ b/scripts/smoke-uk-closure.sh
@@ -9,8 +9,10 @@
# SEED_MODE:
# auto — cluster when general-sim-api exists in NAMESPACE, else local (default)
# local — uv run seed-demo from this repo (needs DB env / port-forwards)
-# cluster — oc exec into general-sim-api; health/query hit localhost:8000 in-pod
+# cluster — oc/kubectl exec into general-sim-api; health/query hit localhost:8000 in-pod
# (avoids OpenShift Route timeouts on long /query LLM calls)
+#
+# Cluster CLI: prefers `oc`, falls back to `kubectl` (Kind / plain Kubernetes).
set -euo pipefail
PY="${SMOKE_PYTHON:-/app/.venv/bin/python}"
@@ -21,10 +23,24 @@ QUERY_TIMEOUT="${QUERY_TIMEOUT:-600}"
NAMESPACE="${NAMESPACE:-general-simulation}"
API_BASE="${API_BASE:-}"
+_k8s() {
+ if command -v oc &>/dev/null; then
+ oc "$@"
+ elif command -v kubectl &>/dev/null; then
+ kubectl "$@"
+ else
+ echo "ERROR: neither 'oc' nor 'kubectl' found on PATH" >&2
+ return 127
+ fi
+}
+
_cluster_resources_present() {
local name="${1:-general-sim-api}"
- oc get deployment "$name" -n "$NAMESPACE" &>/dev/null ||
- oc get route "$name" -n "$NAMESPACE" &>/dev/null
+ if ! command -v oc &>/dev/null && ! command -v kubectl &>/dev/null; then
+ return 1
+ fi
+ _k8s get deployment "$name" -n "$NAMESPACE" &>/dev/null ||
+ { command -v oc &>/dev/null && oc get route "$name" -n "$NAMESPACE" &>/dev/null; }
}
_resolve_seed_mode() {
@@ -32,7 +48,7 @@ _resolve_seed_mode() {
printf '%s' "$SEED_MODE"
return
fi
- if ! command -v oc &>/dev/null; then
+ if ! command -v oc &>/dev/null && ! command -v kubectl &>/dev/null; then
printf 'local'
return
fi
@@ -72,7 +88,7 @@ _cluster_http() {
local method="$1"
local path="$2"
local body="${3:-}"
- oc exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- \
+ _k8s exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- \
env METHOD="$method" PATH="$path" BODY="$body" TIMEOUT="$QUERY_TIMEOUT" \
"$PY" -c '
import json, os, sys
@@ -139,21 +155,21 @@ _fail_http() {
_cluster_seed() {
local pod seed_script repo_root
- pod="$(oc get pod -n "$NAMESPACE" -l app.kubernetes.io/name=general-sim-api \
+ pod="$(_k8s get pod -n "$NAMESPACE" -l app.kubernetes.io/name=general-sim-api \
-o jsonpath='{.items[0].metadata.name}' 2>/dev/null || true)"
if [[ -z "$pod" ]]; then
echo "ERROR: no general-sim-api pod in namespace ${NAMESPACE}" >&2
exit 1
fi
- if oc exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- \
+ if _k8s exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- \
test -x /app/.venv/bin/seed-demo 2>/dev/null; then
- oc exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- seed-demo
+ _k8s exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- seed-demo
return
fi
- if oc exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- \
+ if _k8s exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- \
test -f /app/scripts/seed_demo.py 2>/dev/null; then
- oc exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- \
+ _k8s exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- \
"$PY" /app/scripts/seed_demo.py
return
fi
@@ -166,18 +182,18 @@ _cluster_seed() {
exit 1
fi
echo "==> API image has no bundled seed script; copying from repo to pod /tmp/seed_demo.py"
- oc cp "$seed_script" "${NAMESPACE}/${pod}:/tmp/seed_demo.py" -c "$CLUSTER_CONTAINER"
- oc exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- \
+ _k8s cp "$seed_script" "${NAMESPACE}/${pod}:/tmp/seed_demo.py" -c "$CLUSTER_CONTAINER"
+ _k8s exec -n "$NAMESPACE" "$CLUSTER_DEPLOY" -c "$CLUSTER_CONTAINER" -- \
"$PY" /tmp/seed_demo.py
}
echo "==> Seeding demo data (mode=${SEED_MODE})"
case "$SEED_MODE" in
local)
- if command -v oc &>/dev/null; then
+ if command -v oc &>/dev/null || command -v kubectl &>/dev/null; then
deploy_name="${CLUSTER_DEPLOY#deployment/}"
if _cluster_resources_present "$deploy_name"; then
- echo "ERROR: OpenShift resources exist in namespace '${NAMESPACE}' but seed mode is 'local'." >&2
+ echo "ERROR: cluster resources exist in namespace '${NAMESPACE}' but seed mode is 'local'." >&2
echo "Run: SEED_MODE=cluster make smoke-test" >&2
exit 1
fi