advanced pipeline fix

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.