diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 82cdbdf..809d3ed 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -74,14 +74,14 @@ jobs:
         run: |
           cmake --preset mingw -DMINIPSD_REQUIRE_PSD_TOOLS=ON "-DPython3_EXECUTABLE=${{ steps.python.outputs.python-path }}"
           cmake --build --preset mingw
-          ctest --preset mingw
+          ctest --preset mingw --output-on-failure
 
       - name: Configure, build, test
         if: matrix.preset != 'mingw'
         run: |
           cmake --preset ${{ matrix.preset }} -DMINIPSD_REQUIRE_PSD_TOOLS=ON -DMINIPSD_PSD_TOOLS_FILES=${{ matrix.psd_tools_files || 'OFF' }} -DMINIPSD_VIPS_EXAMPLE=${{ matrix.vips || 'OFF' }} -DMINIPSD_VIPS_PLUGIN=${{ matrix.vips || 'OFF' }} "-DPython3_EXECUTABLE=${{ steps.python.outputs.python-path }}"
           cmake --build --preset ${{ matrix.preset }}
-          ctest --preset ${{ matrix.preset }}
+          ctest --preset ${{ matrix.preset }} --output-on-failure
 
       # The Debian package the release publishes: packed, installed, found by a consumer.
       - name: Check the Debian package
@@ -143,7 +143,7 @@ jobs:
         run: |
           cmake --preset ${{ matrix.preset }} -DMINIPSD_REQUIRE_PSD_TOOLS=${{ matrix.preset == 'linux-coverage' && 'ON' || 'OFF' }}
           cmake --build --preset ${{ matrix.preset }}
-          ctest --preset ${{ matrix.preset }}
+          ctest --preset ${{ matrix.preset }} --output-on-failure
 
       # --merge-lines: minipsd.h is compiled into several test files; count each line once.
       # --exclude-throw-branches: the C++ builds add exception edges that C code never takes.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4ce7a29
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,40 @@
+# minipsd — notes for coding agents
+
+A header-only C99 library that writes and reads PSD files, plus a libvips plugin
+(`libvips-plugin/`). Default branch: `master`.
+
+How to contribute — tests, commit messages, the CHANGELOG — is in [CONTRIBUTING.md](CONTRIBUTING.md).
+Read it before proposing a commit message or a CHANGELOG entry.
+
+## Always
+- The code compiles as C and as C++, without warnings, on every preset.
+- A change to the bytes written comes with a test and is checked by an independent reader
+  (`psd-tools`), not only by the project's own reader.
+- A round trip keeps content, not another program's layout or out-of-spec bytes: see the *Round trip* rule under
+  *What is read* in `docs/SPECIFICATION.md`. Never add an API field only to reproduce a quirk.
+- Never claim what another program writes without a file saved by it (`tests/` fixtures).
+
+## Where to look
+
+| When you… | Read (`docs/`) |
+|---|---|
+| need the contract: what is written and read, what must not break | `SPECIFICATION.md` |
+| change how the code is organised | `CODE-ARCH.md` (the target design), `ROADMAP.md` (the order of work) |
+| write C or C++ | `CODING_STYLE_C.md`, `CODING_STYLE_CPP.md` |
+| change the public API or its documentation | `MANUAL.md` |
+| ask what a user may want from the library | `USE-CASES.md` |
+| touch reading of other programs' files | `COMPATIBILITY.md` (generated by `tools/compat_report.py`, do not edit) |
+| touch packaging, FetchContent, the SBOM | `INSTALL.md` |
+| plan work by its semver impact | `TODO.md` |
+| release | `GITHUB-RELEASE.md` |
+
+## Build and test
+
+One preset per toolchain (`msvc`, `mingw`, `linux-*`); commands in `docs/CHEATSHEET.md`.
+
+- The psd-tools tests need a Python with `tests/requirements.txt`. Keep its venv in a lasting place
+  (e.g. under `build/`): a venv in a temp folder gets half-cleaned and then fails on import. When
+  psd-tools tests fail on import, check `Python3_EXECUTABLE` in the build's `CMakeCache.txt` first.
+- A `mingw` build or ctest run that fails with no compiler message (the `consumer-*` tests among them)
+  is an environment flake when run from PowerShell: rerun through bash with `C:\msys64\mingw64\bin` on
+  `PATH` before suspecting the code. A failure that prints a compiler message is real.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ba69023..f5b2207 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -22,5 +22,33 @@ right to submit it. There is no separate contributor agreement to sign.
 2. Make your changes; the tests must pass as C and as C++, without warnings.
 3. A change to the bytes written must come with a test, and must be checked with an independent
    reader (`psd-tools`), not only with the project's own test reader.
-4. Add a line to `docs/CHANGELOG.md` if users will notice the change.
+4. Update `docs/SPECIFICATION.md` and `docs/MANUAL.md` with the behaviour, and add an entry to
+   `docs/CHANGELOG.md` if users will notice the change.
 5. Open a pull request with a clear description of what and why.
+
+Everything in the repository — code, comments, documentation, commit messages — is in English.
+
+## Commit messages
+
+- Subject: `type(scope): summary`, the scope always given — `feat(reader): …`, `fix(plugin): …`.
+- The body says what changed in behaviour or architecture, and why. A comment brought in line with the
+  code is not a change, and tests are part of the change they cover: mention them only when the
+  commit is about tests.
+
+## The CHANGELOG
+
+It lists what changed for a user between two **published** releases.
+
+- One bullet per change. The title is often enough; add one or two sentences only when it is not.
+- A fix may take up to three sentences — how it was, what changed, how it is now — when it needs them.
+- Never list a fix for a bug that no published release had.
+- One feature serving several scenarios is one bullet.
+- No rationale and no options considered: those belong in `docs/`.
+- No file names, internal functions, tests or CI unless a user sees or must act on them.
+- Breaking changes come first, each with what the user must change.
+
+## AI-assisted contributions
+
+Contributions written with an AI assistant are welcome; the author answers for every line. Commits
+made with one say so in a `Co-Authored-By` trailer. [CLAUDE.md](CLAUDE.md) gives an agent the map
+of this repository.