From 21bc63701d8e567c1e5991ccda546f8454be3748 Mon Sep 17 00:00:00 2001
From: David Gwilliam <dhgwilliam@gmail.com>
Date: Tue, 31 Mar 2026 22:12:42 -0700
Subject: [PATCH] docs: update documentation with CI image info

---
 AGENTS.md | 20 ++++++++++++++++++++
 README.md | 28 ++++++++++++++++++++++++++++
 justfile  | 10 ++++++++++
 3 files changed, 58 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 464ab1c..cc1bd0c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -127,6 +127,26 @@ npm run db:setup-postgres
 DATABASE_PROVIDER=sqlite DATABASE_URL=file:./prisma/ci.db npm run test:acceptance
 ```
 
+### CI Runner Image
+
+To speed up CI runs, the project uses a pre-built CI runner image with all dependencies pre-installed.
+
+**Building the CI image locally:**
+```bash
+./scripts/build-ci-image.sh [tag]
+```
+
+**Using the CI image:**
+- Workflows automatically use `ghcr.io/<repo>/ci-runner:latest` when available
+- Falls back to `node:20-alpine` if image is not found
+- Image is automatically rebuilt when `package.json` changes
+
+**CI Image contains:**
+- Node.js 20 Alpine
+- All npm dependencies pre-installed
+- Prisma client pre-generated
+- System tools (bash, git, python, make, g++)
+
 ### CI/CD Pipeline
 The project uses Gitea Actions for continuous integration:
 
diff --git a/README.md b/README.md
index 2dd2f42..43809f9 100644
--- a/README.md
+++ b/README.md
@@ -373,6 +373,31 @@ The application uses Gitea Actions for continuous integration and deployment:
    - Docker image building and testing
    - Registry push and deployment
 
+4. **CI Image Builder** (`.gitea/workflows/ci-image-builder.yml`): Runs when dependencies change
+   - Automatically builds CI runner image with all dependencies pre-installed
+   - Triggered by changes to `package.json`, `package-lock.json`, or `Dockerfile.ci`
+
+### CI Runner Image
+
+To avoid installing dependencies on every workflow run, we use a pre-built CI runner image:
+
+**Dockerfile.ci** - Contains:
+- Node.js 20 Alpine
+- All npm dependencies pre-installed
+- Prisma client pre-generated
+- System tools (bash, git, python, make, g++)
+
+**Automatic Rebuilding:**
+- The CI image is automatically rebuilt when `package.json` or `package-lock.json` changes
+- Images are tagged with commit SHA for traceability
+- Falls back to `node:20-alpine` if custom image is not available
+
+**Manual Build:**
+```bash
+docker build -f Dockerfile.ci -t euchre-camp-ci:latest .
+docker run --rm euchre-camp-ci:latest node --version
+```
+
 ### Database Strategy for CI
 - **CI Tests**: SQLite database (fast, no server required)
 - **Production**: PostgreSQL (production-like environment)
@@ -385,6 +410,9 @@ npm run test:run
 
 # Run acceptance tests with SQLite
 DATABASE_PROVIDER=sqlite DATABASE_URL=file:./prisma/ci.db npm run test:acceptance
+
+# Run tests in CI container (if built)
+docker run --rm -v $(pwd):/app -w /app euchre-camp-ci:latest npm run test:run
 ```
 
 ## Docker Deployment
diff --git a/justfile b/justfile
index eb24680..b25676e 100644
--- a/justfile
+++ b/justfile
@@ -173,6 +173,16 @@ pr-validate: lint typecheck test-unit test-acceptance-sqlite
 ci-postgres: lint typecheck test-unit test-acceptance-postgres docker-build
     @echo "CI Pipeline with PostgreSQL completed successfully!"
 
+# --- CI Image ---
+
+# Build CI runner image locally
+ci-build:
+    @./scripts/build-ci-image.sh
+
+# Build CI runner image with custom tag
+ci-build-tag TAG:
+    @./scripts/build-ci-image.sh {{TAG}}
+
 # --- Utilities ---
 
 # Show help information