chore: streamline compatibility tracking and documentation

COMPATIBILITY.md

@@ -4,14 +4,13 @@ This document tracks the compatibility between **Gitea Mail Templates** releases
 
 ## Quick Reference
 
-<!-- TRACKER:QUICK-REF-MAX OFFSET=3 -->
 | Template Release | Min Gitea | Max Tested Gitea | Status |
 |-----------------|-----------|-----------------|--------|
-| **v28.0.0** | **28.0.0** | **28.0.0** | ✅ Active |
-| **v1.27.3** | **1.25.0** | **1.27.3** | ✅ Superseded; release emails fail on Gitea 28.0.0 (`FileSize` removed) |
-| **v1.27.2** | **1.25.0** | **1.27.3** | ⚠️ Push notices fail in Bloom, Ember, and Heritage on Gitea 1.27.1+ |
-| **v1.0.1**      | **1.25.0** | **1.27.0** | ✅ Superseded; push notices need newer release on 1.27.1+ |
-| **v1.0.0**      | **1.25.0** | **1.26.4** | ✅ Superseded |
+| **v28.0.0** | **28.0.0** | **28.0.0** | [PASS] Active |
+| **v1.27.3** | **1.25.0** | **1.27.3** | [PASS] Superseded; release emails fail on Gitea 28.0.0 (`FileSize` removed) |
+| **v1.27.2** | **1.25.0** | **1.27.3** | [WARN] Push notices fail in Bloom, Ember, and Heritage on Gitea 1.27.1+ |
+| **v1.0.1**      | **1.25.0** | **1.27.0** | [PASS] Superseded; push notices need newer release on 1.27.1+ |
+| **v1.0.0**      | **1.25.0** | **1.26.4** | [PASS] Superseded |
 
 > **Latest verified:** Release v28.0.0 passes the Gitea 28.0.0 mail-template, mailer-context, function, and translation-key source audit plus all-theme rendering tests. This release requires Gitea 28.0.0; use v1.27.3 for Gitea 1.25.0–1.27.3. <!-- TRACKER:LATEST-VERIFIED -->
 
@@ -19,15 +18,17 @@ This document tracks the compatibility between **Gitea Mail Templates** releases
 
 The release tag identifies the downloadable template package. The supported Gitea version may be appended in parentheses in this compatibility matrix; the parenthesized version is not a Git tag. An **unreleased** row describes fixes available in the repository but not yet in a downloadable release.
 
+<!-- TRACKER:VERSION-MAP -->
 | Gitea version | Template release |
 |---------------|------------------|
+| 28.1.0        | [PENDING] Compatibility verification; no tested template release yet |
 | 28.0.0        | **v28.0.0**; older releases use the removed `FileSize` function in release emails |
 | 1.27.3        | **v1.27.3**; v1.27.2 has a push-notification issue in three themes |
 | 1.27.2        | **v1.27.3**; v1.27.2 has the same issue |
 | 1.27.1        | **v1.27.3**; v1.27.2 has the same issue |
 
-- The [tracker workflow](.github/workflows/gitea-tracker.yml) opens a PR when a new Gitea release appears, marking it ⏳ Pending Verification.
-- After verification, update the top **Template Release** row. Keep fixes on `main` marked **unreleased** until a new tag is published; the [release workflow](.github/workflows/release.yml) packages the archive on tag push.
+- The [tracker workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/gitea-tracker.yml) records new upstream versions as [PENDING] in this table, the history below, and the marked README and AGENTS lines. Its automatic PR creation has not been verified on the new Gitea host; check releases manually until Gitea automation is configured.
+- After verification, update the top **Template Release** row only when that package has been tested against the new Gitea version. Keep fixes on `main` marked **unreleased** until a new tag and downloadable Gitea Release are published; do not assume a tag push uploads archives automatically.
 - The older `v1.0.1` tag predates the Gitea 1.27.1 push notification data fix and should not be used for Gitea 1.27.1 or newer.
 - Gitea 28.0.0 replaces the mail-template `FileSize` function with `FormatByteSize`. The two functions are not interchangeable across these Gitea versions; use the matching template release.
 
@@ -41,9 +42,10 @@ gitea --version
 
 ## Gitea Version History — Mail Template Impact
 
-<!-- TRACKER:VERSION-INSERT OFFSET=2 -->
+<!-- TRACKER:HISTORY -->
 | Gitea | Release Date | Mail Template Changes | Breaking? |
 |-------|-------------|----------------------|-----------|
+| **28.1.0** | 2026-10-06 | [PENDING] Mail-template compatibility verification | TBD |
 | **28.0.0** | 2026-09-29 | `FileSize` removed and `FormatByteSize` added; mail templates now have `mail/`-prefixed internal names and shared head/footer partials; workflow emails gain status-icon fields. Our custom template paths and referenced data fields remain valid. | **Yes** (release attachment formatting) |
 | **1.27.3** | 2026-08-29 | No upstream mail template, mailer, or locale changes; an existing push-notification defect in three themes is fixed in template release v1.27.3 | No upstream break |
 | **1.27.2** | 2026-08-14 | None — security + bug fixes | No |
@@ -56,7 +58,7 @@ gitea --version
 | **1.26.0** | 2026-04-19 | AppURL cleanup; SanitizeHTML deprecated → use HTMLFormat | No |
 | **1.25.5** | 2026-03-10 | None — security + maintenance | No |
 | **1.25.0** | 2025 | **Directory restructure** — templates moved to `mail/<category>/<type>.tmpl` (PR #35150); subject/body split with `---` separator; template preview support added | **Yes** (structural) |
-| **≤ 1.24.x** | — | Flat directory structure under `custom/templates/mail/` | ❌ Unsupported |
+| **≤ 1.24.x** | — | Flat directory structure under `custom/templates/mail/` | [UNSUPPORTED] |
 
 ## Template Variable Reference
 
@@ -100,7 +102,7 @@ All 11 template types use only Gitea built-in variables and functions. Verified
 | `repo/issue/assigned` | `Doer`, `Issue`, `Link`, `IsPull` |
 | `repo/issue/default` | `Doer`, `Issue`, `Link`, `Body`, `ActionName`, `Comment`, `IsPull`, `IsMention`, `ReviewComments`, `CanReply` |
 
-> ⚠️ **`.DisplayName`** is not available in collaborator, transfer, release, workflow_run, assigned, and default templates — do not reference it.
+> [WARN] **`.DisplayName`** is not available in collaborator, transfer, release, workflow_run, assigned, and default templates — do not reference it.
 
 ### Translation Keys
 
@@ -108,17 +110,18 @@ All templates use Gitea's official `mail.*` translation namespace. Every referen
 
 ## How Compatibility Is Verified
 
-1. **Automated lint** — CI renders all templates via `go run . preview all` on every push; the preview function map mirrors Gitea 28.0.0
+1. **Local validation** — run `go test ./...` and `go run . preview all` from `tools/`; the preview function map mirrors Gitea 28.0.0
 2. **Source audit** — Template data contexts are cross-referenced against Gitea's `services/mailer/` package
 3. **Regression tests** — Go tests render push notifications and release attachments in all 10 themes
 4. **Release checklist** — Each release confirms the max-tested Gitea version in this file
 
-## Automated Tracking
+## Version Tracking
 
-A [workflow](.github/workflows/gitea-tracker.yml) runs daily (UTC 08:00) to detect new Gitea releases. When a new version is found, it automatically creates a PR updating the matrix and badges with a **⏳ Pending Verification** status. Manual trigger is also available via `workflow_dispatch`. Once verification passes, update the compatibility matrix; publish a new template tag when template changes require a release (see [Versioning](#versioning)).
+The [tracker workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/gitea-tracker.yml) scans root-level and `docs/` Markdown for `TRACKER:` markers. `VERSION-MAP` and `HISTORY` add pending rows; `UPSTREAM` updates the latest upstream version and status in English/Chinese README and AGENTS; `BADGE` shows the new version as pending while retaining the last tested version. `LATEST-TESTED` and `LATEST-VERIFIED` are manual-only markers and must change only after compatibility verification. The script rejects unknown or missing required markers and is idempotent. Its GitHub Actions schedule and PR creation have not been verified on this Gitea host; until then, check [upstream Gitea releases](https://github.com/go-gitea/gitea/releases) manually. Publish a new template tag only when template content changes (see [Versioning](#versioning)).
 
 ## Reporting Issues
 
 If you find a compatibility problem with a specific Gitea version:
+
 1. Check the [Gitea changelog](https://github.com/go-gitea/gitea/blob/main/CHANGELOG.md) for recent mail template changes
 2. Open an issue with: your Gitea version, which template, and the error