From a09f7e9720f4178f200ecc393f6c58c5a7dc8555 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Mon, 28 Sep 2026 19:45:23 +0000
Subject: [PATCH 1/8] Makefile: add help target and target descriptions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012DSzm4XsY7riy11DAVjsaB
---
 Makefile | 118 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 89 insertions(+), 29 deletions(-)

diff --git a/Makefile b/Makefile
index f6c8e07..bca73de 100644
--- a/Makefile
+++ b/Makefile
@@ -2,13 +2,24 @@ DOCKER_IMAGE=dockette/php
 DOCKER_PLATFORM?=linux/amd64
 VERSION?=8.5
 
-.PHONY: build test run test-cli-% test-fpm-% test-pcov-%
+.DEFAULT_GOAL := help
 
-build: build-${VERSION}
+##@ Help
 
-test: test-cli-${VERSION} test-fpm-${VERSION}
+.PHONY: help
+help: ## Show this help
+	@awk 'BEGIN {FS = ":.*##"; printf "Usage: make \033[36m<target>\033[0m\n"} /^[a-zA-Z0-9_.-]+:.*##/ { sub(/^ +/, "", $$2); printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) }' $(firstword $(MAKEFILE_LIST))
 
-run:
+##@ Docker
+
+.PHONY: build
+build: build-${VERSION} ## Build one image (VERSION=8.5 or VERSION=8.5-fpm)
+
+.PHONY: test
+test: test-cli-${VERSION} test-fpm-${VERSION} ## Test the CLI and FPM images of VERSION (VERSION=8.5, no -fpm)
+
+.PHONY: run
+run: ## Run the image with the current folder in /srv (VERSION=8.5)
 	docker run --rm -it -v ${PWD}:/srv ${DOCKER_IMAGE}:${VERSION}
 
 _build-%: VERSION=$*
@@ -20,31 +31,6 @@ _build-%:
 		-t ${DOCKER_IMAGE}:${VERSION} \
 		./${VERSION}
 
-build-5.6: _build-5.6
-build-5.6-fpm: _build-5.6-fpm
-build-7.0: _build-7.0
-build-7.0-fpm: _build-7.0-fpm
-build-7.1: _build-7.1
-build-7.1-fpm: _build-7.1-fpm
-build-7.2: _build-7.2
-build-7.2-fpm: _build-7.2-fpm
-build-7.3: _build-7.3
-build-7.3-fpm: _build-7.3-fpm
-build-7.4: _build-7.4
-build-7.4-fpm: _build-7.4-fpm
-build-8.0: _build-8.0
-build-8.0-fpm: _build-8.0-fpm
-build-8.1: _build-8.1
-build-8.1-fpm: _build-8.1-fpm
-build-8.2: _build-8.2
-build-8.2-fpm: _build-8.2-fpm
-build-8.3: _build-8.3
-build-8.3-fpm: _build-8.3-fpm
-build-8.4: _build-8.4
-build-8.4-fpm: _build-8.4-fpm
-build-8.5: _build-8.5
-build-8.5-fpm: _build-8.5-fpm
-
 test-cli-%:
 	docker run --rm ${DOCKER_IMAGE}:$* sh -lc 'php -v && composer --version'
 	${MAKE} test-pcov-$*
@@ -57,3 +43,77 @@ test-fpm-%:
 test-pcov-%:
 	docker run --rm ${DOCKER_IMAGE}:$* php -r 'exit(PHP_VERSION_ID < 70100 || extension_loaded("pcov") ? 0 : 1);' \
 		|| { echo "ERROR: pcov is not loaded in ${DOCKER_IMAGE}:$*" >&2; exit 1; }
+
+##@ Versions
+
+.PHONY: build-5.6
+build-5.6: _build-5.6 ## Build the PHP 5.6 CLI image
+
+.PHONY: build-5.6-fpm
+build-5.6-fpm: _build-5.6-fpm ## Build the PHP 5.6 FPM image
+
+.PHONY: build-7.0
+build-7.0: _build-7.0 ## Build the PHP 7.0 CLI image
+
+.PHONY: build-7.0-fpm
+build-7.0-fpm: _build-7.0-fpm ## Build the PHP 7.0 FPM image
+
+.PHONY: build-7.1
+build-7.1: _build-7.1 ## Build the PHP 7.1 CLI image
+
+.PHONY: build-7.1-fpm
+build-7.1-fpm: _build-7.1-fpm ## Build the PHP 7.1 FPM image
+
+.PHONY: build-7.2
+build-7.2: _build-7.2 ## Build the PHP 7.2 CLI image
+
+.PHONY: build-7.2-fpm
+build-7.2-fpm: _build-7.2-fpm ## Build the PHP 7.2 FPM image
+
+.PHONY: build-7.3
+build-7.3: _build-7.3 ## Build the PHP 7.3 CLI image
+
+.PHONY: build-7.3-fpm
+build-7.3-fpm: _build-7.3-fpm ## Build the PHP 7.3 FPM image
+
+.PHONY: build-7.4
+build-7.4: _build-7.4 ## Build the PHP 7.4 CLI image
+
+.PHONY: build-7.4-fpm
+build-7.4-fpm: _build-7.4-fpm ## Build the PHP 7.4 FPM image
+
+.PHONY: build-8.0
+build-8.0: _build-8.0 ## Build the PHP 8.0 CLI image
+
+.PHONY: build-8.0-fpm
+build-8.0-fpm: _build-8.0-fpm ## Build the PHP 8.0 FPM image
+
+.PHONY: build-8.1
+build-8.1: _build-8.1 ## Build the PHP 8.1 CLI image
+
+.PHONY: build-8.1-fpm
+build-8.1-fpm: _build-8.1-fpm ## Build the PHP 8.1 FPM image
+
+.PHONY: build-8.2
+build-8.2: _build-8.2 ## Build the PHP 8.2 CLI image
+
+.PHONY: build-8.2-fpm
+build-8.2-fpm: _build-8.2-fpm ## Build the PHP 8.2 FPM image
+
+.PHONY: build-8.3
+build-8.3: _build-8.3 ## Build the PHP 8.3 CLI image
+
+.PHONY: build-8.3-fpm
+build-8.3-fpm: _build-8.3-fpm ## Build the PHP 8.3 FPM image
+
+.PHONY: build-8.4
+build-8.4: _build-8.4 ## Build the PHP 8.4 CLI image
+
+.PHONY: build-8.4-fpm
+build-8.4-fpm: _build-8.4-fpm ## Build the PHP 8.4 FPM image
+
+.PHONY: build-8.5
+build-8.5: _build-8.5 ## Build the PHP 8.5 CLI image
+
+.PHONY: build-8.5-fpm
+build-8.5-fpm: _build-8.5-fpm ## Build the PHP 8.5 FPM image

From 7e1ec402cd0214acc119791b293661a4a444ce94 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Mon, 28 Sep 2026 19:45:23 +0000
Subject: [PATCH 2/8] AI: add agents instructions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012DSzm4XsY7riy11DAVjsaB
---
 AGENTS.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 76 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1a243ef
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,75 @@
+# Dockette / PHP
+
+Instructions for AI coding agents working in this repository.
+
+## Overview
+
+`dockette/php` builds Debian based PHP images with the CLI or FPM, Composer and about 25 extensions. It is a
+runtime image (see IMAGES.md), the base for `dockette/deploy` and other tools. It ships no application code and
+no web server.
+
+- **Image**: `dockette/php`, tags `5.6` to `8.5`, each also as `-fpm`. CI publishes no `latest` tag
+- **Base**: `dockette/debian:bookworm` for every tag, PHP packages from `packages.sury.org`
+- **Platforms**: `linux/amd64`, `linux/arm64` in CI (reusable workflow default); `make build` builds `linux/amd64`
+- **Layout**: one folder per tag (`8.5/`, `8.5-fpm/`), each with its own `Dockerfile` and `conf.d/custom.ini`;
+  FPM folders also have `fpm/php-fpm.conf`
+
+## Documentation
+
+- `README.md` lists every tag and the extensions per version, and is the Docker Hub description; the `docs` job
+  publishes it from `master`.
+- Supported versions and the deprecation steps are in
+  [IMAGES.md](https://github.com/dockette/dockette/blob/master/specs/IMAGES.md).
+
+## Commands
+
+```bash
+# Build one image; VERSION defaults to 8.5
+make build
+make build VERSION=8.5-fpm
+make build VERSION=8.4
+
+# Test the CLI and FPM image of one version (both must be built first)
+make test
+make test VERSION=8.4
+
+# Run the CLI image with the current folder mounted in /srv
+make run
+```
+
+`make help` lists every per-tag target (`build-8.4`, `build-8.4-fpm`, ...). There is no `build-all`, `test-all`
+or `push`. CI tests only `8.5` and `8.5-fpm`: it builds each with `docker/build-push-action` and runs
+`make test-cli-8.5` or `make test-fpm-8.5`. The `build` job then builds all 24 tags with the reusable workflow and
+pushes from `master` only.
+
+## Conventions
+
+- Binaries are versioned: `php8.5`, `php-fpm8.5`. `conf.d/custom.ini` is copied to `mods-available/` and linked as
+  `999-custom.ini` into the CLI, CGI (and FPM) `conf.d` folders.
+- A new PHP version is a new folder pair, a `build-*` target pair in the `Makefile`, two matrix entries in
+  `.github/workflows/docker.yml` and a README row and column. Move `VERSION?=` and the CI `test` matrix to it.
+- Smoke tests live in the `Makefile` (`test-cli-%`, `test-fpm-%`, `test-pcov-%`). The workflow only calls them;
+  add new checks there, not as workflow steps.
+
+## Traps
+
+- **Every version folder is a full copy.** There is no shared template; `8.4/Dockerfile` and `8.5/Dockerfile`
+  differ only in the version number. A change for all versions is made in all 24 folders.
+- **`make test` takes a base version, not a tag.** It tests `${VERSION}` and `${VERSION}-fpm`, so
+  `make test VERSION=8.4-fpm` looks for `8.4-fpm-fpm`. Build both images of a version before `make test`.
+- **PHP comes from `packages.sury.org`, not from the official `php` image.** Extension names are Debian packages
+  (`php8.5-intl`), not `docker-php-ext-install`. The set differs per version (`redis` up to 8.1, `ssh2` up to 7.2,
+  `geoip` up to 7.4); keep the README extension table in sync with the Dockerfiles.
+- **`pcov` is required from PHP 7.1 up.** `test-pcov-%` fails when it is missing; `5.6` and `7.0` are expected
+  not to have it.
+- **`5.6` to `8.1` are Legacy.** They build while Bookworm is supported and must be marked EOL in the README.
+  Don't add features to them; fix only what breaks the build.
+- **`custom.ini` sets `memory_limit = 521M`, 256 MB uploads and `Europe/Prague`.** The Dockerfile also sets
+  `TZ=Europe/Prague`. Users rely on these defaults; change them in all 24 folders or not at all.
+- **The FPM pool is ours, not Debian's.** `www.conf` is deleted and `fpm/php-fpm.conf` listens on `[::]:9000` as
+  `www-data`, with `open_basedir` limited to `/data:/srv:/var/tmp:/tmp` and `clear_env = yes`.
+- **Composer comes from `getcomposer.org/installer` piped to `php`.** It is Composer 2 and not pinned to a minor
+  version; each weekly rebuild takes the current release.
+- **Child images depend on these tags.** After changing a tag used by `dockette/deploy`, trigger its workflow by
+  hand instead of waiting for the Monday rebuild.
+- Usage for image users (volumes, FPM setup, Composer, extensions) lives in `README.md`, not here.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md

From 63594e09fdcf2bfe28877b57c7d862cee89f582a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Mon, 28 Sep 2026 19:45:23 +0000
Subject: [PATCH 3/8] Editorconfig: init

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012DSzm4XsY7riy11DAVjsaB
---
 .editorconfig | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 .editorconfig

diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..decaff9
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,17 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[Makefile]
+indent_style = tab
+
+[*.{json,yml,yaml}]
+indent_size = 2

From 7e82fa5c68805dbfdde935e87d4e996aafad7908 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Mon, 28 Sep 2026 19:45:23 +0000
Subject: [PATCH 4/8] Config: add fxnorm configuration

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012DSzm4XsY7riy11DAVjsaB
---
 fxnorm.yml | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 fxnorm.yml

diff --git a/fxnorm.yml b/fxnorm.yml
new file mode 100644
index 0000000..5b45951
--- /dev/null
+++ b/fxnorm.yml
@@ -0,0 +1,12 @@
+# fxnorm configuration, written by `fxnorm init`.
+# `fxnorm config` prints what runs and why; `fxnorm rules` lists every rule with its group.
+
+# A Dockette Docker image repository (a Dockerfile in the root or one folder below)
+presets:
+  - dockette-image
+
+# groups:              # add a group, or drop one with a leading minus
+#   - -ci
+
+# rules:               # false, true, error, warning, or options
+#   common/agents-md-length: {min: 50, max: 120}

From 8349a11bab2e066ebc90d7e39e2a2f8593c1b54d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Mon, 28 Sep 2026 19:45:23 +0000
Subject: [PATCH 5/8] Readme: describe package, usage and development

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012DSzm4XsY7riy11DAVjsaB
---
 README.md | 194 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 112 insertions(+), 82 deletions(-)

diff --git a/README.md b/README.md
index 78a20b0..f45dab7 100644
--- a/README.md
+++ b/README.md
@@ -1,117 +1,147 @@
 <h1 align=center>Dockette / PHP</h1>
 
 <p align=center>
-   Ready-to-use Debian based images for PHP 5.6-8.5 with CLI or FPM and Composer preinstalled.
+   <a href="https://github.com/dockette/php/actions"><img src="https://github.com/dockette/php/actions/workflows/docker.yml/badge.svg" alt="GitHub Actions"></a>
+   <a href="https://hub.docker.com/r/dockette/php"><img src="https://img.shields.io/docker/pulls/dockette/php.svg" alt="Docker Hub pulls"></a>
+   <a href="https://github.com/sponsors/f3l1x"><img src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ea4aaa" alt="GitHub Sponsors"></a>
+   <a href="https://github.com/orgs/dockette/discussions"><img src="https://img.shields.io/badge/support-discussions-6f42c1" alt="Support/Discussions"></a>
 </p>
 
 <p align=center>
-    Trying to follow the latest releases with official PHP.
+   PHP 5.6 to 8.5 CLI and FPM images on Debian Bookworm, with <a href="https://getcomposer.org">Composer</a> 2 and about 25 extensions installed. PHP comes from the <a href="https://deb.sury.org">Sury</a> packages. For running PHP tools and applications in CI and local development, and as a base for your own images.
 </p>
 
 <p align=center>
 🕹 <a href="https://f3l1x.io">f3l1x.io</a> | 💻 <a href="https://github.com/f3l1x">f3l1x</a> | 🐦 <a href="https://twitter.com/xf3l1x">@xf3l1x</a>
 </p>
 
-<p align=center>
-   <a href="https://github.com/dockette/php/actions"><img src="https://github.com/dockette/php/actions/workflows/docker.yml/badge.svg" alt="GitHub Actions"></a>
-   <a href="https://hub.docker.com/r/dockette/php"><img src="https://img.shields.io/docker/pulls/dockette/php.svg" alt="Docker Hub pulls"></a>
-   <a href="https://github.com/sponsors/f3l1x"><img src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ea4aaa" alt="GitHub Sponsors"></a>
-   <a href="https://github.com/orgs/dockette/discussions"><img src="https://img.shields.io/badge/support-discussions-6f42c1" alt="Support/Discussions"></a>
-</p>
-
 -----
 
 ## Usage
 
+Install the Composer dependencies of the project in the current folder:
+
+```sh
+docker run --rm -v "$(pwd)":/srv dockette/php:8.5 composer install
 ```
-docker run -v /path/to/site:/srv dockette/php:8.5
-docker run -v /path/to/site:/srv dockette/php:8.5-fpm
-docker run -v /path/to/site:/srv dockette/php:8.4
-docker run -v /path/to/site:/srv dockette/php:8.4-fpm
-docker run -v /path/to/site:/srv dockette/php:8.3
-docker run -v /path/to/site:/srv dockette/php:8.3-fpm
-docker run -v /path/to/site:/srv dockette/php:8.2
-docker run -v /path/to/site:/srv dockette/php:8.2-fpm
-docker run -v /path/to/site:/srv dockette/php:8.1
-docker run -v /path/to/site:/srv dockette/php:8.1-fpm
-docker run -v /path/to/site:/srv dockette/php:8.0
-docker run -v /path/to/site:/srv dockette/php:8.0-fpm
-docker run -v /path/to/site:/srv dockette/php:7.4
-docker run -v /path/to/site:/srv dockette/php:7.4-fpm
-docker run -v /path/to/site:/srv dockette/php:7.3
-docker run -v /path/to/site:/srv dockette/php:7.3-fpm
-docker run -v /path/to/site:/srv dockette/php:7.2
-docker run -v /path/to/site:/srv dockette/php:7.2-fpm
-docker run -v /path/to/site:/srv dockette/php:7.1
-docker run -v /path/to/site:/srv dockette/php:7.1-fpm
-docker run -v /path/to/site:/srv dockette/php:7.0
-docker run -v /path/to/site:/srv dockette/php:7.0-fpm
-docker run -v /path/to/site:/srv dockette/php:5.6
-docker run -v /path/to/site:/srv dockette/php:5.6-fpm
+
+Based on `dockette/debian:bookworm`. The working directory is `/srv`; mount your project there. The CLI images
+run `php` by default and run as root.
+
+Run PHP-FPM on port `9000`:
+
+```sh
+docker run --rm -p 9000:9000 -v "$(pwd)":/srv dockette/php:8.5-fpm
 ```
 
-**Base image**
+The FPM images run `php-fpm8.5` (or the matching version) in the foreground and log to stderr. They speak
+FastCGI only, so put a web server such as Nginx or Caddy in front of them.
+
+Use an image as the base for your own:
 
 ```Dockerfile
 FROM dockette/php:8.5-fpm
 
-RUN apt update && apt install -y curl
+RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
 ```
 
-## Documentation
+The Sury repository is already configured, so more `php8.5-*` extension packages install the same way.
+
+## Versions
+
+Every version has a CLI tag and an `-fpm` tag. Each is built for `linux/amd64` and `linux/arm64` and rebuilt
+every Monday. There is no `latest` tag; pin a version.
 
-### Linux packages
+| Tag | Base | Upstream EOL | State |
+|-----|------|--------------|-------|
+| `dockette/php:8.5`, `dockette/php:8.5-fpm` | `dockette/debian:bookworm` | 2029-12-31 | Supported |
+| `dockette/php:8.4`, `dockette/php:8.4-fpm` | `dockette/debian:bookworm` | 2028-12-31 | Supported |
+| `dockette/php:8.3`, `dockette/php:8.3-fpm` | `dockette/debian:bookworm` | 2027-12-31 | Supported |
+| `dockette/php:8.2`, `dockette/php:8.2-fpm` | `dockette/debian:bookworm` | 2026-12-31 | Supported |
+| `dockette/php:8.1`, `dockette/php:8.1-fpm` | `dockette/debian:bookworm` | 2025-12-31 | Legacy (EOL runtime) |
+| `dockette/php:8.0`, `dockette/php:8.0-fpm` | `dockette/debian:bookworm` | 2023-11-26 | Legacy (EOL runtime) |
+| `dockette/php:7.4`, `dockette/php:7.4-fpm` | `dockette/debian:bookworm` | 2022-11-28 | Legacy (EOL runtime) |
+| `dockette/php:7.3`, `dockette/php:7.3-fpm` | `dockette/debian:bookworm` | 2021-12-06 | Legacy (EOL runtime) |
+| `dockette/php:7.2`, `dockette/php:7.2-fpm` | `dockette/debian:bookworm` | 2020-11-30 | Legacy (EOL runtime) |
+| `dockette/php:7.1`, `dockette/php:7.1-fpm` | `dockette/debian:bookworm` | 2019-12-01 | Legacy (EOL runtime) |
+| `dockette/php:7.0`, `dockette/php:7.0-fpm` | `dockette/debian:bookworm` | 2019-01-10 | Legacy (EOL runtime) |
+| `dockette/php:5.6`, `dockette/php:5.6-fpm` | `dockette/debian:bookworm` | 2018-12-31 | Legacy (EOL runtime) |
 
-These images have preinstalled couple of linux packages: apt-transport-https ca-certificates git.
+> [!WARNING]
+> PHP 8.1 and older get no security fixes from upstream. The Legacy tags keep building while Debian Bookworm is
+> supported; use them only to run old code.
 
-### PHP extensions
+## Packages
 
-These images have preinstalled a couple of PHP extensions. The table shows which extension each version has.
+The images include `apt-transport-https`, `ca-certificates`, `git`, `unzip` and Composer 2 in
+`/usr/local/bin/composer`. Every version has the `cli`, `cgi` and `phpdbg` SAPIs; the `-fpm` tags add `fpm`.
+
+The extensions per version:
 
 | Extension | 5.6 | 7.0 | 7.1 | 7.2 | 7.3 | 7.4 | 8.0 | 8.1 | 8.2 | 8.3 | 8.4 | 8.5 |
 |---|---|---|---|---|---|---|---|---|---|---|---|---|
-| apcu | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| bcmath | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| bz2 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| calendar | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| ctype | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| curl | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| gd | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| geoip | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| gettext | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| imagick | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| imap | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| intl | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| ldap | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| mbstring | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| mcrypt | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| memcached | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| mysql | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| pcov | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| pdo | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| pgsql | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| redis | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
-| soap | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| sqlite3 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| ssh2 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
-| xmlrpc | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| xsl | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| zip | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-
-All versions also have these SAPIs: cli, cgi and phpdbg. The `*-fpm` images have fpm in addition.
-
-### Composer
-
-![Composer](https://avatars3.githubusercontent.com/u/837015?v=3&s=200)
-
-This super image has also preinstalled [Composer](https://getcomposer.org).
-
-### Customization
-
-In case of customization PHP 5.6 - 8.5:
-
-- /etc/php/{5.6-8.5}/{cli,cgi,fpm}/conf.d/991-custom.ini
+| apcu | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| bcmath | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| bz2 | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| calendar | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| ctype | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| curl | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| gd | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| geoip | yes | yes | yes | yes | yes | yes | - | - | - | - | - | - |
+| gettext | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| imagick | yes | yes | yes | - | - | - | - | - | - | - | - | - |
+| imap | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| intl | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| ldap | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| mbstring | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| mcrypt | yes | yes | yes | - | - | - | - | - | - | - | - | - |
+| memcached | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| mysql | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| pcov | - | - | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| pdo | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| pgsql | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| redis | yes | yes | yes | yes | yes | yes | yes | yes | - | - | - | - |
+| soap | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| sqlite3 | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| ssh2 | yes | yes | yes | yes | - | - | - | - | - | - | - | - |
+| xmlrpc | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| xsl | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| zip | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+
+## Configuration
+
+Each image adds one `custom.ini`, stored in `/etc/php/{version}/mods-available/custom.ini` and linked as
+`999-custom.ini` into the `cli`, `cgi` and (for `-fpm`) `fpm` config folders. It sets:
+
+```ini
+memory_limit = 521M
+upload_max_filesize = 256M
+post_max_size = 256M
+date.timezone=Europe/Prague
+```
+
+The container time zone is also `Europe/Prague` (`TZ`). To change a setting, mount your own file over
+`/etc/php/8.5/mods-available/custom.ini`, or add a file with a higher number to the `conf.d` folder.
+
+The `-fpm` tags replace the Debian pool with `/etc/php/{version}/fpm/php-fpm.conf`: one `www` pool on port `9000`
+as `www-data`, `pm = dynamic` with up to 9 children, `open_basedir` set to `/data:/srv:/var/tmp:/tmp` and
+`clear_env = yes`. Put your application under `/srv` or `/data`, or PHP can't open its files. Extra pools go to
+`/etc/php/{version}/fpm/pool.d/*.conf`.
+
+## Development
+
+Build and test the latest version, then run it with the current folder in `/srv`:
+
+```sh
+make build
+make build VERSION=8.5-fpm
+make test
+make run
+```
+
+`VERSION` selects another version (`make build VERSION=8.4`); `make test` tests the CLI and FPM image of one
+version, so build both first. `make help` lists all targets.
 
 ## Maintenance
 
-See [how to contribute](https://github.com/dockette/.github/blob/master/CONTRIBUTING.md) to this package. Consider to [support](https://github.com/sponsors/f3l1x) **f3l1x**. Thank you for using this package.
+See [how to contribute](https://github.com/dockette/.github/blob/master/CONTRIBUTING.md) to this package. Consider [supporting](https://github.com/sponsors/f3l1x) **f3l1x**. Thank you for using this package.

From 195cf1aba6d4fd505d1b11c41c3ec82296ab7734 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Tue, 29 Sep 2026 17:26:15 +0000
Subject: [PATCH 6/8] AI: simplify agents instructions to development
 essentials

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012DSzm4XsY7riy11DAVjsaB
---
 AGENTS.md | 81 ++++++++++++-------------------------------------------
 1 file changed, 17 insertions(+), 64 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 1a243ef..eeec454 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,75 +1,28 @@
 # Dockette / PHP
 
-Instructions for AI coding agents working in this repository.
+PHP CLI and FPM images with Composer and common extensions, one tag per PHP version.
 
-## Overview
+## Stack
 
-`dockette/php` builds Debian based PHP images with the CLI or FPM, Composer and about 25 extensions. It is a
-runtime image (see IMAGES.md), the base for `dockette/deploy` and other tools. It ships no application code and
-no web server.
+- Docker image built with `docker buildx`, base `dockette/debian:bookworm`
+- PHP 5.6 to 8.5 from packages.sury.org, each as CLI and `-fpm`, with Composer
+- Published to Docker Hub as `dockette/php` by GitHub Actions
 
-- **Image**: `dockette/php`, tags `5.6` to `8.5`, each also as `-fpm`. CI publishes no `latest` tag
-- **Base**: `dockette/debian:bookworm` for every tag, PHP packages from `packages.sury.org`
-- **Platforms**: `linux/amd64`, `linux/arm64` in CI (reusable workflow default); `make build` builds `linux/amd64`
-- **Layout**: one folder per tag (`8.5/`, `8.5-fpm/`), each with its own `Dockerfile` and `conf.d/custom.ini`;
-  FPM folders also have `fpm/php-fpm.conf`
-
-## Documentation
-
-- `README.md` lists every tag and the extensions per version, and is the Docker Hub description; the `docs` job
-  publishes it from `master`.
-- Supported versions and the deprecation steps are in
-  [IMAGES.md](https://github.com/dockette/dockette/blob/master/specs/IMAGES.md).
-
-## Commands
+## Development
 
 ```bash
-# Build one image; VERSION defaults to 8.5
-make build
-make build VERSION=8.5-fpm
-make build VERSION=8.4
-
-# Test the CLI and FPM image of one version (both must be built first)
-make test
-make test VERSION=8.4
-
-# Run the CLI image with the current folder mounted in /srv
-make run
+make build       # build the image (VERSION=8.5)
+make test        # smoke test the CLI and FPM images (VERSION=8.5)
+make run         # run it locally with the current folder in /srv
+make build-8.4   # build one version; also build-8.4-fpm
 ```
 
-`make help` lists every per-tag target (`build-8.4`, `build-8.4-fpm`, ...). There is no `build-all`, `test-all`
-or `push`. CI tests only `8.5` and `8.5-fpm`: it builds each with `docker/build-push-action` and runs
-`make test-cli-8.5` or `make test-fpm-8.5`. The `build` job then builds all 24 tags with the reusable workflow and
-pushes from `master` only.
-
-## Conventions
-
-- Binaries are versioned: `php8.5`, `php-fpm8.5`. `conf.d/custom.ini` is copied to `mods-available/` and linked as
-  `999-custom.ini` into the CLI, CGI (and FPM) `conf.d` folders.
-- A new PHP version is a new folder pair, a `build-*` target pair in the `Makefile`, two matrix entries in
-  `.github/workflows/docker.yml` and a README row and column. Move `VERSION?=` and the CI `test` matrix to it.
-- Smoke tests live in the `Makefile` (`test-cli-%`, `test-fpm-%`, `test-pcov-%`). The workflow only calls them;
-  add new checks there, not as workflow steps.
+`make build VERSION=8.4` builds one version. Run `make` to list every target.
 
-## Traps
+## Principles
 
-- **Every version folder is a full copy.** There is no shared template; `8.4/Dockerfile` and `8.5/Dockerfile`
-  differ only in the version number. A change for all versions is made in all 24 folders.
-- **`make test` takes a base version, not a tag.** It tests `${VERSION}` and `${VERSION}-fpm`, so
-  `make test VERSION=8.4-fpm` looks for `8.4-fpm-fpm`. Build both images of a version before `make test`.
-- **PHP comes from `packages.sury.org`, not from the official `php` image.** Extension names are Debian packages
-  (`php8.5-intl`), not `docker-php-ext-install`. The set differs per version (`redis` up to 8.1, `ssh2` up to 7.2,
-  `geoip` up to 7.4); keep the README extension table in sync with the Dockerfiles.
-- **`pcov` is required from PHP 7.1 up.** `test-pcov-%` fails when it is missing; `5.6` and `7.0` are expected
-  not to have it.
-- **`5.6` to `8.1` are Legacy.** They build while Bookworm is supported and must be marked EOL in the README.
-  Don't add features to them; fix only what breaks the build.
-- **`custom.ini` sets `memory_limit = 521M`, 256 MB uploads and `Europe/Prague`.** The Dockerfile also sets
-  `TZ=Europe/Prague`. Users rely on these defaults; change them in all 24 folders or not at all.
-- **The FPM pool is ours, not Debian's.** `www.conf` is deleted and `fpm/php-fpm.conf` listens on `[::]:9000` as
-  `www-data`, with `open_basedir` limited to `/data:/srv:/var/tmp:/tmp` and `clear_env = yes`.
-- **Composer comes from `getcomposer.org/installer` piped to `php`.** It is Composer 2 and not pinned to a minor
-  version; each weekly rebuild takes the current release.
-- **Child images depend on these tags.** After changing a tag used by `dockette/deploy`, trigger its workflow by
-  hand instead of waiting for the Monday rebuild.
-- Usage for image users (volumes, FPM setup, Composer, extensions) lives in `README.md`, not here.
+- KISS: one image does one job; no extra services or tools.
+- DRY: shared steps live in the base image, not copied into every Dockerfile.
+- YAGNI: add a package only when the image needs it.
+- Pin versions, keep layers small, clean package caches in the same `RUN`.
+- Every change is built and smoke tested with `make build test` before a commit.

From 24cf1b5056d5acf9ee97b2581d88a5d021eb59ec Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Tue, 29 Sep 2026 20:32:36 +0000
Subject: [PATCH 7/8] AI: drop CLAUDE.md, agents read AGENTS.md directly

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012DSzm4XsY7riy11DAVjsaB
---
 CLAUDE.md | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index 43c994c..0000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1 +0,0 @@
-@AGENTS.md

From 121f5d59fed3b72ddeb2828c1dfc9278b203500d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milan=20Felix=20=C5=A0ulc?= <rkfelix@gmail.com>
Date: Tue, 29 Sep 2026 20:42:44 +0000
Subject: [PATCH 8/8] Readme: simplify usage and development

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012DSzm4XsY7riy11DAVjsaB
---
 README.md | 61 +++++++++----------------------------------------------
 1 file changed, 10 insertions(+), 51 deletions(-)

diff --git a/README.md b/README.md
index f45dab7..9bf92c2 100644
--- a/README.md
+++ b/README.md
@@ -19,33 +19,16 @@
 
 ## Usage
 
-Install the Composer dependencies of the project in the current folder:
+Mount your project in `/srv` and run a command in it:
 
 ```sh
-docker run --rm -v "$(pwd)":/srv dockette/php:8.5 composer install
+docker run -v "$(pwd)":/srv dockette/php:8.5 composer install
 ```
 
-Based on `dockette/debian:bookworm`. The working directory is `/srv`; mount your project there. The CLI images
-run `php` by default and run as root.
-
-Run PHP-FPM on port `9000`:
-
-```sh
-docker run --rm -p 9000:9000 -v "$(pwd)":/srv dockette/php:8.5-fpm
-```
-
-The FPM images run `php-fpm8.5` (or the matching version) in the foreground and log to stderr. They speak
-FastCGI only, so put a web server such as Nginx or Caddy in front of them.
-
-Use an image as the base for your own:
-
-```Dockerfile
-FROM dockette/php:8.5-fpm
-
-RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
-```
-
-The Sury repository is already configured, so more `php8.5-*` extension packages install the same way.
+The image adds Composer 2, about 25 extensions and a `custom.ini` with PHP limits and the `Europe/Prague` time
+zone. The `-fpm` tags run PHP-FPM with one FastCGI pool on port `9000` and `open_basedir` set to
+`/data:/srv:/var/tmp:/tmp`; mount your own `.ini` file into `/etc/php/8.5/cli/conf.d` or
+`/etc/php/8.5/fpm/conf.d` to change a setting, see the [PHP configuration reference](https://www.php.net/manual/en/ini.list.php).
 
 ## Versions
 
@@ -108,39 +91,15 @@ The extensions per version:
 | xsl | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
 | zip | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
 
-## Configuration
-
-Each image adds one `custom.ini`, stored in `/etc/php/{version}/mods-available/custom.ini` and linked as
-`999-custom.ini` into the `cli`, `cgi` and (for `-fpm`) `fpm` config folders. It sets:
-
-```ini
-memory_limit = 521M
-upload_max_filesize = 256M
-post_max_size = 256M
-date.timezone=Europe/Prague
-```
-
-The container time zone is also `Europe/Prague` (`TZ`). To change a setting, mount your own file over
-`/etc/php/8.5/mods-available/custom.ini`, or add a file with a higher number to the `conf.d` folder.
-
-The `-fpm` tags replace the Debian pool with `/etc/php/{version}/fpm/php-fpm.conf`: one `www` pool on port `9000`
-as `www-data`, `pm = dynamic` with up to 9 children, `open_basedir` set to `/data:/srv:/var/tmp:/tmp` and
-`clear_env = yes`. Put your application under `/srv` or `/data`, or PHP can't open its files. Extra pools go to
-`/etc/php/{version}/fpm/pool.d/*.conf`.
-
 ## Development
 
-Build and test the latest version, then run it with the current folder in `/srv`:
-
 ```sh
-make build
-make build VERSION=8.5-fpm
-make test
-make run
+make build   # build the image (VERSION=8.5)
+make test    # smoke test the CLI and FPM image
+make run     # run it with the current folder in /srv
 ```
 
-`VERSION` selects another version (`make build VERSION=8.4`); `make test` tests the CLI and FPM image of one
-version, so build both first. `make help` lists all targets.
+Run `make` to list every target.
 
 ## Maintenance