docs: clarify per-version Gitea compatibility

AGENTS.md

@@ -3,12 +3,12 @@
 
 ## Project Overview
 
-A curated collection of email template themes (10 visual styles) for self-hosted Gitea instances. Each theme contains 11 Go `html/template` files covering all Gitea notification email types.
+A growing collection of email template themes for self-hosted Gitea instances. Each theme contains 11 Go `html/template` files covering all supported Gitea notification email types.
 
 ## Repository Layout
 
 ```
-themes/             # Template themes (10 styles, 11 .tmpl each = 110 source files)
+themes/             # One directory per theme, with 11 .tmpl files each
   aurora/           #   Ethereal / Dreamlike
   bloom/            #   Creative / Startup (glassmorphism)
   ember/            #   Community / Open Source
@@ -19,6 +19,7 @@ themes/             # Template themes (10 styles, 11 .tmpl each = 110 source fil
   neon/             #   Cyberpunk / Gaming
   terminal/         #   Developers / Tech
   terra/            #   Nature / Sustainability
+  .../              #   Additional themes can be added
 tools/              # Go CLI tooling (modular; uses urfave/cli/v2)
   tools.go          #   Main entry point
   cli/              #   CLI subcommands: list, create, delete, preview
@@ -75,11 +76,11 @@ docs/               # Bilingual documentation (English + Simplified Chinese)
 <!-- RELEASE:CURRENT -->
 - Current template release: **v28.0.0**.
 <!-- /RELEASE:CURRENT -->
-- v28.0.0 was verified against Gitea 28.0.0. Gitea 28 removes `FileSize` in favor of `FormatByteSize`, so v28.0.0 is not compatible with Gitea 1.25.0–1.27.3; use v1.27.3 for those versions. The quick-reference table in `COMPATIBILITY.md` lists the active release first
+- v28.0.0 was verified against Gitea 28.0.0. Gitea 28 replaces the mail-template `FileSize` function with `FormatByteSize`; earlier template releases can fail on Gitea 28, and v28.0.0 is not a drop-in replacement for earlier mail contexts. Choose an archive from the per-version matrix in `COMPATIBILITY.md`; v1.27.2 is a known partial fix for push notifications
 <!-- TRACKER:UPSTREAM -->
 - Latest upstream Gitea release: 28.1.0 [PENDING].
 <!-- /TRACKER:UPSTREAM -->
-- When a new Gitea version appears, the tracker updates pending rows, marked version lines, and the pending README badge. After verification, update the top `COMPATIBILITY.md` tested range and README tested text/badge; keep unreleased fixes distinct from the published release
+- When a new Gitea version appears, the tracker adds pending compatibility and history rows and updates marked version lines and the pending README badge. After verification, update that version's matrix row and README tested text/badge; keep unreleased fixes distinct from the published release
 - Tag a new release (`vX.Y.Z`) only when the template content itself changes. On the new Gitea host, do not assume tag pushes automatically build or upload archives; verify the Gitea workflow before relying on it
 - Before tagging, add `.github/release-notes/vX.Y.Z.md`, run `go test ./...` and `go run . preview all` from `tools/`. The release workflow packages the tag, publishes the reviewed notes, and then updates `RELEASE` blocks on `main` when the host supports those Actions and write permissions; otherwise build/upload and update the labels manually
 - Participating Markdown documents declare their blocks in a `DOC-TAGS` JSON comment. Each block uses a paired opening `<!-- SUBJECT:CONTENT -->` and closing `<!-- /SUBJECT:CONTENT -->` comment; its body is the managed text. `TRACKER` handles upstream-pending content, `RELEASE` handles published-template labels, and `TRACKER:LATEST-TESTED` / `TRACKER:LATEST-VERIFIED` are manual-only. Within a document, the first block for a subject/content pair wins