chore: streamline compatibility tracking and documentation

AGENTS.md

@@ -18,22 +18,23 @@ themes/             # Template themes (10 styles, 11 .tmpl each = 110 source fil
   neon/             #   Cyberpunk / Gaming
   terminal/         #   Developers / Tech
   terra/            #   Nature / Sustainability
-tools/              # Go CLI tooling (modular, zero dependencies)
+tools/              # Go CLI tooling (modular; uses urfave/cli/v2)
   tools.go          #   Main entry point
   cli/              #   CLI subcommands: list, create, delete, preview
   config/           #   Config types and templates_config.json loading
   data/             #   templates_config.json — single source of truth for template metadata
   preview/          #   Template rendering engine (funcs, locale, engine)
-  go.mod            #   Go module (stdlib only, zero dependencies)
+  go.mod            #   Go module (CLI dependency declared here)
 preview/            # Browser-based live preview
   index.html        # SPA with style/template/client/viewport switching
-  rendered.js       # Pre-rendered HTML (generated, committed for clone-and-preview)
+  rendered.js       # Pre-rendered HTML (generated, ignored in source clones)
 docs/               # Bilingual documentation (English + Simplified Chinese)
 ```
 
 ## Working With Templates
 
 ### Template Files
+
 - All `.tmpl` files use Go `html/template` syntax
 - Must use only Gitea 28's built-in template functions: `AppUrl`, `DotEscape`, `QueryEscape`, `ShortSha`, `HTMLFormat`, `PathEscapeSegments`, `FormatByteSize`
 - Must use only official Gitea translation keys (`mail.*` namespace)
@@ -41,20 +42,23 @@ docs/               # Bilingual documentation (English + Simplified Chinese)
 - Each style must have all 11 template types
 
 ### Adding a New Theme
+
 1. Scaffold the new theme: `cd tools && go run . create <name>` — creates the full directory structure with placeholder `.tmpl` files for all 11 email types
 2. Write all 11 `.tmpl` files with unique visual design
 3. Run `cd tools && go run . preview all` to regenerate preview data
 4. Update README.md style gallery table
 
 ### Preview System
+
 - `preview/index.html` loads `preview/rendered.js` (pre-rendered by Go) and displays in iframes
 - Supports theme/template switching, view mode (Modern/Source), and viewport toggle (Desktop 1386x780 / Mobile 390x780)
 - Keyboard navigation: `←→` cycles focus between Theme/Template/View selects, `↑↓` selects within the focused dropdown, `d`/`m` toggles viewport
 - `REGISTRY` and `PARAMS` are auto-generated from `templates_config.json` — no manual syncing needed
-- Static preview (open `index.html` directly) — works via `file://` protocol with Modern and Source views
+- Static preview works via `file://` after running `go run . preview all` in a source clone; the updated packaging workflow includes generated preview data and screenshots for future builds (v28.0.0 and older archives include neither)
 - Dev server (`go run . dev`) — pure Go HTTP server with SSE live reload; watches `themes/` for `.tmpl` changes, re-renders in-process, and pushes reload events to the browser
 
 ### Build Tool
+
 - `tools/tools.go` is the main entry point for the modular CLI
 - Subcommands: `list`, `create`, `delete`, `preview`, `dev`
 - Template metadata lives in `tools/data/templates_config.json` — the single source of truth
@@ -67,13 +71,15 @@ docs/               # Bilingual documentation (English + Simplified Chinese)
 ## Versioning
 
 - Release tags identify actual downloadable packages; the compatibility matrix distinguishes released tags from source-only fixes
-- The current release is **v28.0.0**, 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; the tracker workflow updates that row by position
-- When a new Gitea version is checked: update the top `COMPATIBILITY.md` row and README badge; keep unreleased fixes distinct from the published release, and update verified/tested wording only after verification
-- Tag a new release (`vX.Y.Z`) only when the template content itself changes — the release workflow packages automatically on tag push
-- Before tagging, add `.github/release-notes/vX.Y.Z.md`; the release workflow validates the file, runs `go test ./...`, and publishes those reviewed notes with the archives
-- Keep the `TRACKER:` markers in `COMPATIBILITY.md` / `README.md` adjacent to their rows so the automated workflow keeps parsing them
+- The current release is **v28.0.0**, 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
+- 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
+- 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/`, then build and upload the archives with the reviewed notes. `.github/workflows/release.yml` retains the earlier GitHub Actions flow as a reference
+- Keep `TRACKER:VERSION-MAP` and `TRACKER:HISTORY` above their tables, and inline `TRACKER:BADGE`, `TRACKER:UPSTREAM`, `TRACKER:LATEST-TESTED`, and `TRACKER:LATEST-VERIFIED` markers with their text. The Python tracker updates pending markers; tested/verified markers are manual-only
 
 ## Commit Conventions
+
 - `style(name):` — template changes for a specific theme
 - `preview:` — preview tooling changes
 - `tools:` — Go CLI/build tooling changes
@@ -84,7 +90,8 @@ docs/               # Bilingual documentation (English + Simplified Chinese)
 - `chore:` — maintenance (config updates, build scripts)
 
 ## Constraints
+
 - No JavaScript framework dependencies — preview is vanilla JS
-- No external Go dependencies — build uses stdlib only
+- The CLI uses `github.com/urfave/cli/v2`; the preview server itself uses Go's standard HTTP library
 - Templates must remain compatible with Gitea's `html/template` execution environment
 - Preview works with `file://` protocol (no server needed)