@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(task:*)",
+      "Bash(sbt -client:*)",
+      "Bash(git:*)"
+    ]
+  }
+}
@@ -0,0 +1,27 @@
+---
+name: upgrade-elasticsearch
+description: Upgrade Elasticsearch end-to-end: bump versions, check Lucene, compile, unit test, integration test, open PR.
+argument-hint: "[target version, e.g. 8.18.5]"
+---
+
+Upgrade Elasticsearch to the version specified by the user (or infer it from context). Follow these steps in order, fixing any issues before moving to the next step:
+
+1. **Bump versions** in all four places:
+   - `ElasticsearchVersion` in `build.sbt`
+   - Image tag in `docker/Dockerfile`
+   - Image tag and release download URL in `docs/pages/installation.md`
+   - `version` file (format: `X.Y.Z.0`)
+
+2. **Check if LuceneVersion needs updating.** ES ships with a bundled Lucene. If it changed, the old pinned version will show as "evicted" in the dependency tree:
+   ```
+   sbt -client "elastiknn-plugin/dependencyTree" | grep lucene
+   ```
+   If evicted, bump `LuceneVersion` in `build.sbt` to match.
+
+3. **Verify compilation:** `task jvmCompile`. Fix any issues before proceeding.
+
+4. **Verify unit tests:** `task jvmUnitTest`. Fix any failures before proceeding.
+
+5. **Verify integration tests:** `task dockerRunTestingCluster` then `task jvmIntegrationTest`. Fix any failures.
+
+Once all steps pass, open a PR.
@@ -0,0 +1,69 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Test Commands
+
+### Task CLI
+
+Use the `task` CLI — read Taskfile.yaml for all available tasks and to understand how they work.
+
+### SBT
+
+The underlying tool for most tasks is `sbt`, specifically `sbt -client` (thin client connecting to a persistent sbt server).
+Sometimes you need to use it directly rather than using 
+
+**Running a single test class:**
+```bash
+sbt -client "elastiknn-plugin/testOnly com.klibisz.elastiknn.query.SomeSpec"
+```
+
+### Integration Testing
+
+Integration tests require a Docker cluster (see `dockerRunTestingCluster` / `dockerStopTestingCluster` tasks in Taskfile.yaml).
+
+### Java Version
+
+The project uses Java 21 (see `.tool-versions`). Manage via asdf. Building with a newer JDK will embed that version in `plugin-descriptor.properties`, causing the plugin install to fail in the Docker container (which runs ES's bundled JDK).
+
+## Project Structure
+
+The project has seven SBT subprojects (Scala 3.3.6):
+
+| Module | Role |
+|--------|------|
+| `elastiknn-api4s` | API types: (`Vec`, `Mapping`, `NearestNeighborsQuery`, etc.) XContent serialization |
+| `elastiknn-models` | LSH model implementations and vector similarity math (Java + Panama SIMD) |
+| `elastiknn-lucene` | Custom Lucene queries (`MatchHashesAndScoreQuery`) and field types |
+| `elastiknn-plugin` | ES plugin: mappers, query builders, score functions |
+| `elastiknn-plugin-integration-tests` | Full end-to-end tests against a live ES cluster |
+| `elastiknn-client-elastic4s` | Scala client library using elastic4s |
+| `elastiknn-jmh-benchmarks` | JMH microbenchmarks |
+
+Dependency order: `api4s` ← `models` ← `lucene` ← `plugin` ← `integration-tests`
+
+## Key Version Variables (build.sbt)
+
+```scala
+ElasticsearchVersion  // must match docker/Dockerfile and version file
+LuceneVersion         // must match the Lucene bundled in the ES release
+ElastiknnVersion      // read from the `version` file (e.g. 8.18.4.0)
+```
+
+When upgrading ES, update all four: `build.sbt`, `docker/Dockerfile`, `docs/pages/installation.md`, and `version`. Also check whether the bundled Lucene version changed (`sbt elastiknn-plugin/dependencyTree | grep lucene`).
+
+## Dependency Upgrades
+
+Use `/upgrade-elasticsearch` to perform an Elasticsearch upgrade end-to-end.
+
+Other JVM dependencies are mostly handled by Scala Steward via automated PRs (see git log for the pattern).
+
+## SIMD / Panama Vector API
+
+`PanamaFloatVectorOps` uses `jdk.incubator.vector` for SIMD-accelerated dot product, cosine, L1, and L2 computations. It is enabled at runtime via the `elastiknn.jdk-incubator-vector.enabled` setting. The sbt server and ES container both need `--add-modules jdk.incubator.vector` (already configured in `.sbtopts` and `build.sbt`).
+
+SIMD `reduceLanes(ADD)` can produce slightly different floating-point results before vs. after JIT compilation — relevant when writing determinism tests.
+
+## CI
+
+`.github/workflows/ci.yaml` runs: lint → compile → assemble → unit tests → start Docker cluster → integration tests. Scala compiler is strict (`CiMode`) when `CI=true`; locally it uses `DevMode` (relaxed).
@@ -7,7 +7,7 @@ Global / scalaVersion := "3.3.6"
 Global / scalacOptions += "-explain"
 
 lazy val CirceVersion = "0.14.14"
-lazy val ElasticsearchVersion = "8.18.4"
+lazy val ElasticsearchVersion = "8.18.5"
 lazy val Elastic4sVersion = "8.19.0"
 lazy val ElastiknnVersion = IO.read(file("version")).strip()
 lazy val LuceneVersion = "9.12.1"
 
@@ -1,3 +1,3 @@
-FROM docker.elastic.co/elasticsearch/elasticsearch:8.18.4
+FROM docker.elastic.co/elasticsearch/elasticsearch:8.18.5
 COPY elastiknn-plugin/target/elastiknn*.zip .
 RUN elasticsearch-plugin install -b file:$(ls elastiknn*zip | sort | tail -n1)
@@ -42,8 +42,8 @@ Make a Dockerfile like below.
 The image version (`elasticsearch:A.B.C`) must match the plugin's version (e.g. `A.B.C.x/elastiknn-A.B.C.x`).
 
 ```docker
-FROM docker.elastic.co/elasticsearch/elasticsearch:8.18.4
-RUN elasticsearch-plugin install --batch https://github.com/alexklibisz/elastiknn/releases/download/8.18.4.0/elastiknn-8.18.4.0.zip
+FROM docker.elastic.co/elasticsearch/elasticsearch:8.18.5
+RUN elasticsearch-plugin install --batch https://github.com/alexklibisz/elastiknn/releases/download/8.18.5.0/elastiknn-8.18.5.0.zip
 ```
 
 Build and run the Dockerfile. If you have any issues please refer to the [official docs.](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html)
 
@@ -1 +1 @@
-8.18.4.0
+8.18.5.0