diff --git a/.woodpecker/deploy.yaml b/.woodpecker/deploy.yaml
index 9e97551..07019f1 100644
--- a/.woodpecker/deploy.yaml
+++ b/.woodpecker/deploy.yaml
@@ -29,11 +29,17 @@ steps:
   rubocop:
     image: ruby:3.3
     environment:
-      BUNDLE_PATH: .bundle-ci # a workspace-ben marad, a teszt step újrahasználja
+      BUNDLE_PATH: /cache/bundle
+    volumes:
+      # A gemek a szerveren maradnak futások között; a ruby-verzió a kulcs, mert a
+      # natív kiterjesztések (mysql2) egy ABI-hoz fordulnak.
+      - /srv/ci-cache/bundle/api-ruby3.3:/cache/bundle
     commands:
       - apt-get update && apt-get install -y --no-install-recommends default-libmysqlclient-dev
       - cd apps/api
-      - bundle install --jobs 4
+      # A lock a párhuzamos futásokat választja szét: két pipeline nem ír egyszerre
+      # ugyanabba a bundle könyvtárba.
+      - flock -w 900 /cache/bundle/.install.lock bundle install --jobs 4
       - bundle exec rubocop
 
   test-host:
@@ -47,12 +53,14 @@ steps:
       IMAGE_CONTAINER_PATH: /tmp/images
       UPDATE_SECRET: ci-test
       SECRET_KEY_BASE: ci-test
-      BUNDLE_PATH: .bundle-ci
+      BUNDLE_PATH: /cache/bundle
+    volumes:
+      - /srv/ci-cache/bundle/api-ruby3.3:/cache/bundle
     commands:
       - apt-get update && apt-get install -y --no-install-recommends default-libmysqlclient-dev default-mysql-client
       - mkdir -p /tmp/softwares /tmp/images
       - cd apps/api
-      - bundle install --jobs 4
+      - flock -w 900 /cache/bundle/.install.lock bundle install --jobs 4
       - |
         echo "==> Varakozas a mysql-re"
         for i in $(seq 1 60); do
diff --git a/.woodpecker/warp_engine.yaml b/.woodpecker/warp_engine.yaml
index 65a61b1..4e572e9 100644
--- a/.woodpecker/warp_engine.yaml
+++ b/.woodpecker/warp_engine.yaml
@@ -50,11 +50,17 @@ steps:
   rubocop:
     image: ruby:3.2
     environment:
-      BUNDLE_PATH: .bundle-ci # a workspace-ben marad, a következő step újrahasználja
+      BUNDLE_PATH: /cache/bundle
+    volumes:
+      # A gemek a szerveren maradnak futások között. Külön könyvtár ruby-verziónként:
+      # a natív kiterjesztések (mysql2) egy ABI-hoz fordulnak.
+      - /srv/ci-cache/bundle/warp_engine-ruby3.2:/cache/bundle
     commands:
       - apt-get update && apt-get install -y --no-install-recommends default-libmysqlclient-dev
       - cd libs/ruby/warp_engine
-      - bundle install --jobs 4
+      # A lock a párhuzamos futásokat választja szét: két pipeline nem ír egyszerre
+      # ugyanabba a bundle könyvtárba.
+      - flock -w 900 /cache/bundle/.install.lock bundle install --jobs 4
       - bundle exec rubocop
 
   test-engine:
@@ -62,11 +68,13 @@ steps:
     environment:
       RAILS_ENV: test
       DB_HOST: mysql
-      BUNDLE_PATH: .bundle-ci
+      BUNDLE_PATH: /cache/bundle
+    volumes:
+      - /srv/ci-cache/bundle/warp_engine-ruby3.2:/cache/bundle
     commands:
       - apt-get update && apt-get install -y --no-install-recommends default-libmysqlclient-dev default-mysql-client
       - cd libs/ruby/warp_engine
-      - bundle install --jobs 4
+      - flock -w 900 /cache/bundle/.install.lock bundle install --jobs 4
       - |
         echo "==> Varakozas a mysql-re"
         for i in $(seq 1 60); do
diff --git a/README.md b/README.md
index 1fbc06d..a71d988 100644
--- a/README.md
+++ b/README.md
@@ -173,6 +173,32 @@ the very pipeline doing the deploy.
 `db/migrate` to the host's migration paths. A failing migration stops the
 deploy before the restart, so the old code keeps running.
 
+### Gem cache
+
+Both workflows install gems into a host directory that survives runs:
+
+| Workflow | Host path | `BUNDLE_PATH` |
+|---|---|---|
+| `warp_engine.yaml` | `/srv/ci-cache/bundle/warp_engine-ruby3.2` | `/cache/bundle` |
+| `deploy.yaml` | `/srv/ci-cache/bundle/api-ruby3.3` | `/cache/bundle` |
+
+Cold install is ~35 s, warm ~6 s (113 MB of gems). The directory is keyed by
+Ruby version because native extensions (mysql2) are built against one ABI; the
+`flock` around `bundle install` keeps two concurrent pipelines from writing the
+same directory at once. Docker creates the directories on first run — to drop
+the cache, delete them.
+
+This needs the same *Trusted → Volumes* flag the deploy does.
+
+### Why a MySQL service and not a stub
+
+Two thirds of the engine suite (22 of 36 spec files, all 11 request specs)
+create rows and assert on what comes back, and both `schema.rb` files are
+MySQL-shaped (`charset: utf8mb4`, `collation: utf8mb4_0900_ai_ci`, unsigned
+keys). A null adapter answers every query with nothing, and SQLite would test a
+database we do not run. The service container costs a start, not a download —
+the agent's Docker daemon already has the image.
+
 Secret used by both workflows: `forge_token` — a Forgejo token with
 repository read/write and package:write.