chore: migrate mail themes to shared framework and locked upstream inputs

COMPATIBILITY.md

@@ -31,6 +31,20 @@ v1.0.1 retains the pre-1.27 push-commit fields used by the listed Gitea 1.25/1.2
 > **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. For other Gitea versions, follow the per-version matrix above.
 <!-- /TRACKER:LATEST-VERIFIED -->
 
+## Snapshot-Driven Source Status
+
+The refactor on `main` is **unreleased**. It locks Gitea **v28.0.0**, commit `15b8a5805adf57c5189602008d38cccfd3c795e0`, with 13 mail files (11 entrypoints and 2 shared partials) and 28 official locale files. New source architecture supports Gitea 28+; it does not replace historical release assets or change recommendations in the published matrix.
+
+Theme sources contain CSS and metadata only. A shared framework organizes official mail values/translations into reusable branding, action/fallback and footer controls. Its single alignment layer preserves notification branches, subjects and functional link targets while allowing presentation changes. Only generated `gitea.lock.json` is committed; immutable official inputs are downloaded to ignored `build/upstream/`. Builds fail on checksum, English-key, adapter-reference or unreviewed action-anchor changes. New mail types require framework alignment and fixtures.
+
+Missing translations in other languages follow the official English fallback and are reported as `[FALLBACK]`. Gitea v28.0.0's Polish `mail.team_invite.text_1` starts with malformed `%[1]z…` instead of `%[1]s`; preview preserves this official defect and reports `[UPSTREAM-WARN]`. The exception matches the exact source text; other formatting defects fail rendering.
+
+Gitea 28.1.0 remains [PENDING]. Updating pending documentation does not synchronize the snapshot or verify a new version.
+
+`upstream prepare` requires the committed root lock and creates only an absent cache; `upstream verify` requires both lock and cache and performs no download. Missing locks are not inferred from cache or latest releases. Explicit `upstream sync --tag vX.Y.Z` can initialize or replace the lock, but does not update this matrix or certify compatibility. See [command usage and cache recovery](CONTRIBUTING.md#official-snapshot-updates).
+
+Current-source validation includes all-theme/all-language rendering and notification parity, browser checks for static/HTTP language switching and mobile layouts, and an isolated Gitea 28.0.0 template-loading/password-reset mail smoke test. This does not certify rendering in Gmail, Outlook or Apple Mail; those clients still require deployment-specific testing. The optional real-Gitea and browser suites are not automatically run by the current release workflow.
+
 ## Versioning and Known Exceptions
 
 Release tags name actual downloadable packages. A matching version is useful, but it is not a compatibility guarantee: v1.27.2 has a known defect, and there is no v1.27.1 template tag. Use the recommended package in the matrix; do not infer support from a tag number or from the current `main` branch.
@@ -72,7 +86,7 @@ This table describes changes in **Gitea**, not fixes in this template repository
 
 ## Template Variable Reference
 
-All 11 template types use only Gitea built-in variables and functions. Verified against Gitea source (`services/mailer/` + `modules/templates/mail.go`).
+The downloaded official inputs define mail variables and calls; themes do not add business variables. The table below summarizes preview contexts. The locked upstream commit, shared alignment layer and strict fixture rendering are authoritative.
 
 ### Relevant Template Functions
 
@@ -106,24 +120,25 @@ All 11 template types use only Gitea built-in variables and functions. Verified
 | `user/auth/reset_passwd` | `DisplayName`, `Code`, `ResetPwdCodeLives` |
 | `org/team_invite` | `Inviter`, `Team`, `Organization`, `InviteURL`, `Invite` |
 | `repo/collaborator` | `Subject`, `RepoName`, `Link` |
-| `repo/transfer` | `Doer`, `User`, `Repo`, `Link`, `Destination` |
+| `repo/transfer` | `Subject`, `Repo`, `Link` |
 | `repo/release` | `Release` (with `Publisher`, `TagName`, `Title`, `RenderedNote`, `Attachments`), `Link` |
-| `repo/actions/workflow_run` | `Run` (with `WorkflowID`, `HTMLURL`), `Jobs`, `RunStatusText` |
-| `repo/issue/assigned` | `Doer`, `Issue`, `Link`, `IsPull` |
+| `repo/actions/workflow_run` | `Subject`, `Run` (with `WorkflowID`, `HTMLURL`), `Jobs` (with status class, icon CID/alt, attempt, URL and duration) |
+| `repo/issue/assigned` | `Subject`, `Doer`, `Issue`, `Link`, `IsPull`, `CanReply` |
 | `repo/issue/default` | `Doer`, `Issue`, `Link`, `Body`, `ActionName`, `Comment`, `IsPull`, `IsMention`, `ReviewComments`, `CanReply` |
 
 > [WARN] **`.DisplayName`** is not available in collaborator, transfer, release, workflow_run, assigned, and default templates — do not reference it.
 
 ### Translation Keys
 
-All templates use Gitea's official `mail.*` translation namespace. Every referenced key was checked against Gitea 28.0.0's English locale file.
+Official templates reference `mail.*` keys and `actions.runs.attempt`. AST-based checks inspect `.locale.Tr`, `$.locale.Tr` and both plural keys in `TrN`, including nested pipelines. Every referenced key must exist in the locked English catalog. Preview loads full official locale JSON files rather than a copied Go dictionary; formatting, escaping and plural selection follow the reviewed Gitea adapter.
 
 ## How Compatibility Is Verified
 
-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 every discovered theme
-4. **Release checklist** — Each release records its verified Gitea version in the matrix above
+1. **Locked input verification** — run `go run . upstream prepare` then `go run . upstream verify` from `tools/`; first preparation downloads missing cache files, verification checks hashes, adapter references and English keys offline.
+2. **Framework alignment** — `go test ./...` checks deterministic shared adaptation/generation and fails on changed primary-action anchors; theme sources cannot own business templates.
+3. **Notification semantics and controls** — tests compare subjects, notification text and functional links for every theme/language and critical branches, accounting explicitly for added controls/branding. Browser QA checks translated button labels, identical fallback targets, logos and mobile layout. `go run . preview all` builds all language bundles and reports fallback/upstream defects.
+4. **Matching-instance smoke test** — before publication, load generated overrides in an isolated Gitea matching the snapshot and capture a real notification or password-reset mail. The admin test email does not exercise custom templates.
+5. **Release identity** — the release tag must match the snapshot tag. Only mark the new release verified after its tests and smoke check; published tags/assets remain unchanged.
 
 ## Version Tracking