Paragon: spell unlearn queue + AE/TE reconciliation

Two related additions to mod-paragon:

  * HandleCommit gains a third payload section, " u:<id>,...", carrying
    spell IDs the player wants to refund + unlearn in the same commit
    that learns / talents through. The protocol stays backward-compat
    (older clients omit the section). PanelUnlearnSpellPurchase mirrors
    the per-spell branch of HandleParagonResetAbilities: tracked passive
    children are removed first, then the chain head, then panel_spells /
    panel_spell_children / panel_spell_revoked rows for that purchase
    are dropped, then LookupSpellAECost(head) is refunded into the
    cache. Unlearns are applied before learns inside the commit so the
    refund covers the same-commit spends. Allow-list for the silence
    window now includes chain ranks + panel_spell_children for the
    intentional unlearns so "You have unlearned X" toasts stay visible
    for the targeted spell while cascade dependents stay silenced.

  * ReconcileEssenceForPlayer reads panel_spells + panel_talents and
    sets the cache to ComputeStartingAE/TE(level) - sum-of-spends.
    Self-heals drift in either direction: clamps the cache down when
    the player has more essence than their level + spends allow
    (cheese clamp), and tops up when they have less (admin-tweak /
    crash recovery). Wired into OnPlayerLogin (after LoadCurrencyFromDb,
    before PushCurrency so the first balance the client sees is the
    reconciled one) and OnPlayerLevelChanged (replaces the old
    GrantLevelUpEssence delta -- Reconcile sets the absolute correct
    balance from level + spend, so it subsumes the per-level grant and
    the cheese clamp in one call). Costs come from the same
    paragon_spell_ae_cost / config keys HandleCommit uses so the math
    stays in lockstep across any future cost rebalance.

Both features ship in patch-enUS-6.MPQ v0.9.16: right-click a learned
spell row to queue an unlearn (header shows +N AE refund preview) and
hit Learn All to apply. The icon picker also got two fixes -- the
leading INV_Misc_QuestionMark is no longer duplicated, and the
selection ring is now a tooltip-border Frame anchored to the cell
bounds (the prior UI-ActionButton-Border texture rendered nearly
invisible at non-native sizes).

Co-authored-by: Cursor <cursoragent@cursor.com>

.github/workflows/fractured-launcher-ci.yml

@@ -38,6 +38,10 @@ jobs:
           cache-dependency-path: tools/fractured-launcher-electron/package-lock.json
 
       - name: Install and pack (NSIS + portable)
+        env:
+          GITEA_BASE_URL: ${{ secrets.GITEA_BASE_URL }}
+          GITEA_OWNER: ${{ secrets.GITEA_OWNER }}
+          GITEA_REPO: ${{ secrets.GITEA_REPO }}
         run: |
           npm ci
           npm run pack:win

.github/workflows/gitea-release-sync.yml

@@ -0,0 +1,164 @@
+# Primary path for player-facing binaries: every *published* GitHub Release on this repo
+# is mirrored to your self-hosted Gitea (same tag). No public GitHub distro repo.
+#
+# Triggers:
+#   - release: published / released → GitHub “Release” (not a raw git tag alone).
+#   - workflow_dispatch → Actions → this workflow → “Run workflow” (enter tag).
+#
+# Troubleshooting: “Re-run failed jobs” on an OLD run replays the *original* workflow
+# YAML (e.g. still runs `npm run pack:win` without --publish never). After changing this
+# file on default branch, start a *new* run via “Run workflow”, not Re-run on a pre-fix run.
+#
+# Important: pushing only a git tag does NOT run this — you must create/publish a
+# Release on github.com (Releases → Draft/new release → Publish). The workflow
+# definition must exist on the repo DEFAULT branch (GitHub runs it from there).
+#
+# Steps: build Electron from tag → download this repo’s release attachments → upload all to Gitea.
+#
+# Secrets: GITEA_BASE_URL, GITEA_TOKEN, GITEA_OWNER, GITEA_REPO
+# Optional variable: GITEA_TARGET_REF (see tools/fractured-launcher-electron/README.md)
+#
+# Job guard: edit `if:` if github.repository is not Dawnforger/Fractured.
+
+name: Sync release to Gitea
+
+on:
+  release:
+    types: [published, released]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag on this GitHub repo (must exist; e.g. v1.0.0)'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: gitea-release-sync-${{ github.repository }}-${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  meta:
+    runs-on: ubuntu-latest
+    if: github.repository == 'Dawnforger/Fractured'
+    outputs:
+      tag: ${{ steps.t.outputs.tag }}
+    steps:
+      - name: Resolve tag
+        id: t
+        shell: bash
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "tag=${{ github.event.inputs.tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ github.event.release.tag_name }}" >> "$GITHUB_OUTPUT"
+          fi
+
+  build-electron:
+    needs: meta
+    if: github.repository == 'Dawnforger/Fractured'
+    runs-on: windows-latest
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.meta.outputs.tag }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: tools/fractured-launcher-electron/package-lock.json
+
+      - name: Install and pack (NSIS + portable)
+        working-directory: tools/fractured-launcher-electron
+        env:
+          # Same values as upload step — baked into default-launcher.json (no token).
+          GITEA_BASE_URL: ${{ secrets.GITEA_BASE_URL }}
+          GITEA_OWNER: ${{ secrets.GITEA_OWNER }}
+          GITEA_REPO: ${{ secrets.GITEA_REPO }}
+        run: |
+          npm ci
+          # pack:win runs inject-release-channel.js then electron-builder --publish never
+          npm run pack:win
+
+      - name: Stage launcher files for upload
+        shell: pwsh
+        run: |
+          New-Item -ItemType Directory -Force -Path launcher-publish | Out-Null
+          Copy-Item tools/fractured-launcher-electron/dist/*.exe launcher-publish/
+          if (Test-Path tools/fractured-launcher-electron/dist/latest.yml) {
+            Copy-Item tools/fractured-launcher-electron/dist/latest.yml launcher-publish/
+          }
+          Get-ChildItem tools/fractured-launcher-electron/dist/*.blockmap -ErrorAction SilentlyContinue |
+            Copy-Item -Destination launcher-publish/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: electron-dist
+          path: launcher-publish/
+
+  sync-gitea:
+    needs: [meta, build-electron]
+    if: github.repository == 'Dawnforger/Fractured'
+    runs-on: ubuntu-latest
+    env:
+      GITEA_BASE_URL: ${{ secrets.GITEA_BASE_URL }}
+      GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+      GITEA_OWNER: ${{ secrets.GITEA_OWNER }}
+      GITEA_REPO: ${{ secrets.GITEA_REPO }}
+      GITEA_TARGET_REF: ${{ vars.GITEA_TARGET_REF }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Script may not exist on older release tags; always use default branch.
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: |
+            tools/fractured-launcher-electron/scripts
+          sparse-checkout-cone-mode: true
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: electron-dist
+          path: /tmp/electron
+
+      - name: Merge GitHub release assets + Electron build
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          TAG="${{ needs.meta.outputs.tag }}"
+          mkdir -p combined
+          mkdir -p /tmp/from-main
+          if gh release download "$TAG" -R "${{ github.repository }}" -D /tmp/from-main 2>/tmp/dl.err; then
+            shopt -s nullglob
+            for f in /tmp/from-main/*; do
+              if [ -f "$f" ]; then
+                cp -f "$f" combined/
+              fi
+            done
+            echo "Merged assets from ${{ github.repository }} release $TAG"
+          else
+            echo "GitHub release download note (continuing with launcher only):"
+            cat /tmp/dl.err || true
+          fi
+          shopt -s nullglob
+          for f in /tmp/electron/*; do
+            if [ -f "$f" ]; then
+              cp -f "$f" combined/
+            fi
+          done
+          ls -la combined/
+
+      - name: Upload to Gitea
+        run: |
+          set -euo pipefail
+          for v in GITEA_BASE_URL GITEA_TOKEN GITEA_OWNER GITEA_REPO; do
+            if [ -z "${!v:-}" ]; then
+              echo "Missing secret $v — add it under repo Settings → Secrets and variables → Actions." >&2
+              exit 1
+            fi
+          done
+          bash tools/fractured-launcher-electron/scripts/upload-release-to-gitea.sh combined "${{ needs.meta.outputs.tag }}"

modules/mod-paragon/src/Paragon_Essence.cpp

@@ -257,6 +257,87 @@ uint32 GetParagonPanelSpellRequiredLevel(SpellInfo const* info)
     return std::max(1u, lv);
 }
 
+// Reconciles the player's AE/TE cache against what they SHOULD have
+// based on level (ComputeStartingAE/TE) minus what they've spent through
+// Character Advancement (sum over character_paragon_panel_spells +
+// character_paragon_panel_talents). Updates the cache + DB if either
+// direction drifts:
+//   * actual < expected: top up (handles per-level grants automatically;
+//     also self-heals from admin commands / crashes that lost essence).
+//   * actual > expected: clamp down (prevents .modify-style cheese, ghost
+//     panel rows that were rolled back, or any path that left more
+//     essence than the level allowed).
+// Logs at INFO when drift is corrected so we can spot abuse patterns.
+//
+// Cheap (two SELECTs of small per-character tables) and safe to call from
+// OnPlayerLogin and OnPlayerLevelChanged. SAFE TO CALL ANY TIME the panel
+// DB is in a steady state (i.e. NOT mid-HandleCommit).
+void ReconcileEssenceForPlayer(Player* pl)
+{
+    if (!pl || pl->getClass() != CLASS_PARAGON)
+        return;
+    if (!sConfigMgr->GetOption<bool>("Paragon.Currency.Enabled", true))
+        return;
+
+    uint32 const lowGuid = pl->GetGUID().GetCounter();
+    uint8 const  level   = pl->GetLevel();
+
+    // Sum AE / TE spent through panel purchases. Mirrors the cost lookups
+    // used by HandleCommit so reconciliation matches the spend math byte-
+    // for-byte (no off-by-one if config keys are tweaked at runtime).
+    uint32 spentAE = 0;
+    uint32 spentTE = 0;
+
+    if (QueryResult r = CharacterDatabase.Query(
+            "SELECT spell_id FROM character_paragon_panel_spells WHERE guid = {}", lowGuid))
+    {
+        do
+        {
+            spentAE += LookupSpellAECost(r->Fetch()[0].Get<uint32>());
+        } while (r->NextRow());
+    }
+
+    uint32 const tePerRank = sConfigMgr->GetOption<uint32>("Paragon.Currency.TE.TalentLearnCost", 1);
+    uint32 const aePerRank = sConfigMgr->GetOption<uint32>("Paragon.Currency.AE.TalentLearnCost", 1);
+    if (QueryResult r = CharacterDatabase.Query(
+            "SELECT talent_id, `rank` FROM character_paragon_panel_talents WHERE guid = {}", lowGuid))
+    {
+        do
+        {
+            Field const* f = r->Fetch();
+            uint32 const tid  = f[0].Get<uint32>();
+            uint32 const rank = f[1].Get<uint32>();
+            TalentEntry const* te = sTalentStore.LookupEntry(tid);
+            if (!te || !rank)
+                continue;
+            spentTE += rank * tePerRank;
+            if (te->addToSpellBook)
+                spentAE += rank * aePerRank;
+        } while (r->NextRow());
+    }
+
+    uint32 const expectedTotalAE = ComputeStartingAE(level);
+    uint32 const expectedTotalTE = ComputeStartingTE(level);
+    uint32 const expectedBalAE   = expectedTotalAE > spentAE ? expectedTotalAE - spentAE : 0;
+    uint32 const expectedBalTE   = expectedTotalTE > spentTE ? expectedTotalTE - spentTE : 0;
+
+    ParagonCurrencyData& d = GetOrCreateCacheEntry(lowGuid);
+    if (d.abilityEssence == expectedBalAE && d.talentEssence == expectedBalTE)
+        return;
+
+    LOG_INFO("module",
+        "Paragon essence reconciled for {} (lvl {}): AE {}->{} TE {}->{} (spent AE={} TE={}, expected total AE={} TE={})",
+        pl->GetName(), uint32(level),
+        d.abilityEssence, expectedBalAE,
+        d.talentEssence,  expectedBalTE,
+        spentAE, spentTE,
+        expectedTotalAE, expectedTotalTE);
+
+    d.abilityEssence = expectedBalAE;
+    d.talentEssence  = expectedBalTE;
+    SaveCurrencyToDb(pl);
+}
+
 // Forward declaration: reset handlers below need PushSnapshot, which itself
 // is defined later (after PushSpellSnapshot / PushTalentSnapshot).
 void PushSnapshot(Player* pl);
@@ -989,10 +1070,12 @@ uint32 ComputeTalentRankAnySpec(Player* pl, uint32 talentId)
 // ---- Commit handler --------------------------------------------------------
 //
 // Wire format from Net.lua Net:Commit:
-//   "C COMMIT s:<id1>,<id2>,...<empty allowed> t:<talentId>:<delta>,..."
-// Both sub-lists are optional but the leading tags are not. Examples:
+//   "C COMMIT s:<id1>,<id2>,...<empty allowed> t:<talentId>:<delta>,... u:<id>,..."
+// The " u:" spell-unlearn section is optional (omitted by older clients).
+// Both s: and t: leading tags are required. Examples:
 //   "C COMMIT s:5176,8921 t:"
 //   "C COMMIT s: t:1234:1,5678:2"
+//   "C COMMIT s: t: u:45477"
 // We parse leniently and abort on any structural error.
 //
 // On success we push:
@@ -1035,12 +1118,15 @@ std::vector<uint32> ParseCsvUInt(std::string_view csv)
 //   * full chain ids for every spell the player explicitly purchased (so
 //     the player still sees "Plague Strike (Rank 1..N) learned" toasts);
 //   * every talent rank id the player explicitly purchased (so addToSpellBook
-//     talents like Bladestorm/Starfall still toast normally).
+//     talents like Bladestorm/Starfall still toast normally);
+//   * chain ids + tracked passive children for spells intentionally unlearned
+//     in this commit (so "You have unlearned …" for those stays visible).
 // Anything else learned/unlearned during the window -- the SkillLineAbility
 // cascade and our diff-revoke cleanup -- is silenced.
 void SendSilenceOpenForCommit(Player* pl,
                               std::vector<std::pair<uint32, uint32>> const& spellsAndCosts,
-                              std::vector<std::pair<uint32, uint32>> const& talentDeltas)
+                              std::vector<std::pair<uint32, uint32>> const& talentDeltas,
+                              std::vector<uint32> const& unlearnTrackIds = {})
 {
     if (!pl)
         return;
@@ -1049,6 +1135,26 @@ void SendSilenceOpenForCommit(Player* pl,
     for (auto const& kv : spellsAndCosts)
         CollectSpellChainIds(kv.first, allow);
 
+    uint32 const lowGuid = pl->GetGUID().GetCounter();
+    for (uint32 trackId : unlearnTrackIds)
+    {
+        if (!trackId)
+            continue;
+        CollectSpellChainIds(trackId, allow);
+        if (QueryResult cr = CharacterDatabase.Query(
+                "SELECT child_spell_id FROM character_paragon_panel_spell_children "
+                "WHERE guid = {} AND parent_spell_id = {}",
+                lowGuid, trackId))
+        {
+            do
+            {
+                uint32 const cid = cr->Fetch()[0].Get<uint32>();
+                if (cid)
+                    allow.insert(cid);
+            } while (cr->NextRow());
+        }
+    }
+
     for (auto const& [tid, delta] : talentDeltas)
     {
         (void)delta;
@@ -1094,6 +1200,71 @@ void SendSilenceClose(Player* pl)
         SendAddonMessage(pl, "R SILENCE CLOSE");
 }
 
+// Removes one Character Advancement spell purchase (chain head in
+// character_paragon_panel_spells). Refunds that row's AE cost, unlearns
+// tracked passive children then the parent chain, and clears matching
+// panel_* DB rows (mirrors the per-spell portion of HandleParagonResetAbilities).
+// `spellId` may be any rank id from the bake; normalized to GetFirstSpellInChain.
+bool PanelUnlearnSpellPurchase(Player* pl, uint32 spellId, std::string* err)
+{
+    if (!pl || !spellId)
+    {
+        if (err)
+            *err = "bad player or spell";
+        return false;
+    }
+
+    uint32 const lowGuid = pl->GetGUID().GetCounter();
+    uint32 const head    = sSpellMgr->GetFirstSpellInChain(spellId);
+    uint32 const sid      = head ? head : spellId;
+
+    if (!CharacterDatabase.Query(
+            "SELECT 1 FROM character_paragon_panel_spells WHERE guid = {} AND spell_id = {} LIMIT 1",
+            lowGuid, sid))
+    {
+        if (err)
+            *err = fmt::format("spell {} is not a panel purchase", sid);
+        return false;
+    }
+
+    uint32 const refund = LookupSpellAECost(sid);
+
+    if (QueryResult cr = CharacterDatabase.Query(
+            "SELECT child_spell_id FROM character_paragon_panel_spell_children "
+            "WHERE guid = {} AND parent_spell_id = {}",
+            lowGuid, sid))
+    {
+        do
+        {
+            uint32 const cid = cr->Fetch()[0].Get<uint32>();
+            if (pl->HasSpell(cid))
+                pl->removeSpell(cid, SPEC_MASK_ALL, false);
+        } while (cr->NextRow());
+    }
+
+    if (pl->HasSpell(sid))
+        pl->removeSpell(sid, SPEC_MASK_ALL, false);
+
+    CharacterDatabase.DirectExecute(
+        "DELETE FROM character_paragon_panel_spell_children WHERE guid = {} AND parent_spell_id = {}",
+        lowGuid, sid);
+    CharacterDatabase.DirectExecute(
+        "DELETE FROM character_paragon_panel_spell_revoked WHERE guid = {} AND parent_spell_id = {}",
+        lowGuid, sid);
+
+    std::unordered_set<uint32> chainIds;
+    CollectSpellChainIds(sid, chainIds);
+    DbDeletePanelSpellRevokedForChain(lowGuid, chainIds);
+
+    CharacterDatabase.DirectExecute(
+        "DELETE FROM character_paragon_panel_spells WHERE guid = {} AND spell_id = {}",
+        lowGuid, sid);
+
+    ParagonCurrencyData& d = GetOrCreateCacheEntry(lowGuid);
+    d.abilityEssence += refund;
+    return true;
+}
+
 bool HandleCommit(Player* pl, std::string const& body, std::string* err)
 {
     // Strip leading "C COMMIT " (already stripped by caller, but be defensive)
@@ -1111,10 +1282,20 @@ bool HandleCommit(Player* pl, std::string const& body, std::string* err)
         return false;
     }
 
-    std::string_view spellsCsv  = rest.substr(2, tPos - 2);
-    std::string_view talentsCsv = rest.substr(tPos + 3);
+    std::string_view spellsCsv = rest.substr(2, tPos - 2);
+    std::string_view talentsCsv;
+    std::string_view unlearnCsv;
+    size_t const uPos = rest.find(" u:", tPos);
+    if (uPos != std::string_view::npos)
+    {
+        talentsCsv = rest.substr(tPos + 3, uPos - (tPos + 3));
+        unlearnCsv = rest.substr(uPos + 3);
+    }
+    else
+        talentsCsv = rest.substr(tPos + 3);
 
     std::vector<uint32> spellIds = ParseCsvUInt(spellsCsv);
+    std::vector<uint32> unlearnRaw = ParseCsvUInt(unlearnCsv);
 
     // Talents are "id:delta,id:delta,...". Parse into vector of pairs.
     std::vector<std::pair<uint32, uint32>> talentDeltas;
@@ -1152,12 +1333,37 @@ bool HandleCommit(Player* pl, std::string const& body, std::string* err)
         }
     }
 
-    if (spellIds.size() + talentDeltas.size() > kCommitMaxItems)
+    std::unordered_set<uint32> unlearnTrackSet;
+    std::vector<uint32> unlearnTracks;
+    for (uint32 raw : unlearnRaw)
+    {
+        if (!raw)
+            continue;
+        uint32 const head = sSpellMgr->GetFirstSpellInChain(raw);
+        uint32 const tid  = head ? head : raw;
+        if (unlearnTrackSet.insert(tid).second)
+            unlearnTracks.push_back(tid);
+    }
+
+    if (spellIds.size() + talentDeltas.size() + unlearnTracks.size() > kCommitMaxItems)
     {
         *err = "commit exceeds size cap";
         return false;
     }
 
+    uint32 unlearnRefundAE = 0;
+    for (uint32 tid : unlearnTracks)
+    {
+        if (!CharacterDatabase.Query(
+                "SELECT 1 FROM character_paragon_panel_spells WHERE guid = {} AND spell_id = {} LIMIT 1",
+                pl->GetGUID().GetCounter(), tid))
+        {
+            *err = fmt::format("cannot unlearn {} (not a panel purchase)", tid);
+            return false;
+        }
+        unlearnRefundAE += LookupSpellAECost(tid);
+    }
+
     // Pre-validate spells: must be valid SpellInfo, not already learned,
     // and afford their combined AE cost.
     uint32 totalAE = 0;
@@ -1181,6 +1387,13 @@ bool HandleCommit(Player* pl, std::string const& body, std::string* err)
             *err = fmt::format("requires level {} for spell {}", reqLv, id);
             return false;
         }
+        uint32 const learnHead = sSpellMgr->GetFirstSpellInChain(id);
+        uint32 const learnTrack = learnHead ? learnHead : id;
+        if (unlearnTrackSet.count(learnTrack))
+        {
+            *err = "cannot learn and unlearn the same spell in one commit";
+            return false;
+        }
         uint32 cost = LookupSpellAECost(id);
         spellsAndCosts.emplace_back(id, cost);
         totalAE += cost;
@@ -1222,9 +1435,10 @@ bool HandleCommit(Player* pl, std::string const& body, std::string* err)
         *err = fmt::format("not enough TE (need {} have {})", talentsTE, GetTE(pl));
         return false;
     }
-    if (GetAE(pl) < (totalAE + talentsAE))
+    if (GetAE(pl) + unlearnRefundAE < (totalAE + talentsAE))
     {
-        *err = fmt::format("not enough AE (need {} have {})", totalAE + talentsAE, GetAE(pl));
+        *err = fmt::format("not enough AE (need {} total; you have {} plus {} from unlearns in this commit)",
+                          totalAE + talentsAE, GetAE(pl), unlearnRefundAE);
         return false;
     }
 
@@ -1234,8 +1448,18 @@ bool HandleCommit(Player* pl, std::string const& body, std::string* err)
     // learnSpell drags along (Death Coil/Death Grip/Blood Plague/Blood
     // Presence/Forceful Deflection/Runic Focus/...) don't spam learn/
     // unlearn toasts. Allow list = chain ranks of explicitly purchased
-    // spells + talent rank ids. Closed below at the end of the commit.
-    SendSilenceOpenForCommit(pl, spellsAndCosts, talentDeltas);
+    // spells + talent rank ids + chains/children for intentional unlearns.
+    SendSilenceOpenForCommit(pl, spellsAndCosts, talentDeltas, unlearnTracks);
+
+    // Apply spell unlearns first so refunded AE is available for spends.
+    for (uint32 tid : unlearnTracks)
+    {
+        if (!PanelUnlearnSpellPurchase(pl, tid, err))
+        {
+            SendSilenceClose(pl);
+            return false;
+        }
+    }
 
     // Apply spells: each consumes its individual AE cost. PanelLearnSpellChain
     // also grants every higher rank up to the player's current level so the
@@ -2924,6 +3148,13 @@ public:
     void OnPlayerLogin(Player* player) override
     {
         LoadCurrencyFromDb(player);
+        // Verify AE/TE matches what the player's level + panel spend
+        // permit. Self-heals admin / crash drift in either direction
+        // and is a no-op (just two small SELECTs) when the balance is
+        // already correct. Has to run BEFORE PushCurrency so the
+        // client's first balance update of the session is the
+        // reconciled one.
+        ReconcileEssenceForPlayer(player);
         PushCurrency(player);
         PushSnapshot(player);
         PushBuildCatalog(player);
@@ -3003,7 +3234,7 @@ public:
         // Player isn't fully in-world here; OnPlayerLogin will push.
     }
 
-    void OnPlayerLevelChanged(Player* player, uint8 oldLevel) override
+    void OnPlayerLevelChanged(Player* player, uint8 /*oldLevel*/) override
     {
         if (!player || player->getClass() != CLASS_PARAGON)
             return;
@@ -3017,10 +3248,13 @@ public:
         if (gParagonCurrencyCache.find(lowGuid) == gParagonCurrencyCache.end())
             LoadCurrencyFromDb(player);
 
-        GrantLevelUpEssence(player, oldLevel, player->GetLevel());
-
-        // Persist the grant immediately so a crash before next save doesn't
-        // lose freshly-awarded essence. Cheap (single REPLACE).
+        // Single source of truth: ComputeStartingAE/TE(newLevel) - spent.
+        // Subsumes the old GrantLevelUpEssence per-level delta AND catches
+        // drift in both directions (cheese clamp + restore-from-loss).
+        // SaveCurrencyToDb runs inside Reconcile when drift is detected;
+        // call it once more here so a no-drift level-up still flushes any
+        // pending cache changes from this session.
+        ReconcileEssenceForPlayer(player);
         SaveCurrencyToDb(player);
         PushCurrency(player);
     }

scripts/vps-paragon-diagnostics.sh

@@ -0,0 +1,336 @@
+#!/usr/bin/env bash
+# Collect VPS evidence for Paragon / DBUpdater / binary staleness triage.
+# Run ON the VPS (Linux). Safe: read-only; does not restart services.
+#
+# Usage (from clone):
+#   bash scripts/vps-paragon-diagnostics.sh
+#
+# Optional environment:
+#   FRACTURED_REPO           — absolute path to Fractured git root (default: parent of scripts/)
+#   FRACTURED_WS_BIN         — path to worldserver binary (default: auto-detect)
+#   FRACTURED_WORLDSERVER_CONF — path to worldserver.conf (default: guess from BIN + common layouts)
+#   FRACTURED_SYSTEMD_UNITS  — space-separated units to try (default: "fractured-world worldserver ac-worldserver")
+#   FRACTURED_MYSQL          — prefix to invoke mysql, e.g. 'mysql -uacore -pacore -h127.0.0.1'
+#                              (default Fractured local DB user/password are often both "acore"; use ~/.my.cnf if you prefer not to pass -p on the command line)
+#                              If unset, SQL blocks are printed for manual copy-paste only.
+#   FRACTURED_SPELL_IDS      — space-separated spell IDs for spell_dbc spot-check (defaults to common DK rune spenders)
+#   FRACTURED_DIAG_OUTPUT    — full log file path (default: <repo>/var/vps-paragon-diagnostics-last.txt)
+#
+# All output is mirrored to the log file (tee) while still printing to the terminal.
+# Default path lives under var/ (gitignored in this repo). Open that file in Cursor,
+# scp it down, or: git add -f var/vps-paragon-diagnostics-last.txt  if you intend to commit it.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="${FRACTURED_REPO:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+
+DIAG_OUT="${FRACTURED_DIAG_OUTPUT:-$REPO/var/vps-paragon-diagnostics-last.txt}"
+mkdir -p "$(dirname "$DIAG_OUT")"
+exec > >(tee "$DIAG_OUT") 2>&1
+echo "Logging to: $DIAG_OUT"
+
+hr() { printf '\n%s\n' "================================================================================"; }
+sub() { printf '\n-- %s\n' "$1"; }
+
+detect_worldserver_bin() {
+  local bin="" es path u units
+  if [[ -n "${FRACTURED_WS_BIN:-}" ]]; then
+    readlink -f "$FRACTURED_WS_BIN" 2>/dev/null && return
+    echo "$FRACTURED_WS_BIN"
+    return
+  fi
+
+  units="${FRACTURED_SYSTEMD_UNITS:-fractured-world worldserver ac-worldserver}"
+  for u in $units; do
+    if systemctl is-active --quiet "$u" 2>/dev/null || systemctl is-enabled --quiet "$u" 2>/dev/null; then
+      es=$(systemctl show "$u" -p ExecStart --value 2>/dev/null || true)
+      if [[ -n "$es" ]]; then
+        if [[ "$es" == \{*path=* ]]; then
+          path=$(printf '%s' "$es" | sed -n 's/.*path=\([^;]*\).*/\1/p')
+        else
+          path=$(printf '%s' "$es" | awk '{print $1}' | sed 's/^path=//')
+        fi
+        if [[ -n "$path" && -x "$path" ]]; then
+          readlink -f "$path" 2>/dev/null && return
+        fi
+      fi
+    fi
+  done
+
+  local pid
+  pid=$(pgrep -xo worldserver 2>/dev/null || true)
+  if [[ -n "$pid" ]]; then
+    readlink -f "/proc/$pid/exe" 2>/dev/null && return
+  fi
+
+  if command -v worldserver >/dev/null 2>&1; then
+    readlink -f "$(command -v worldserver)" 2>/dev/null && return
+  fi
+
+  echo ""
+}
+
+guess_worldserver_conf() {
+  local bin="$1"
+  local d cands=()
+  [[ -z "$bin" ]] && return
+  d=$(dirname "$bin")
+  cands+=("$d/../etc/worldserver.conf")
+  cands+=("$d/../../etc/worldserver.conf")
+  cands+=("$HOME/azeroth-server/etc/worldserver.conf")
+  cands+=("$HOME/env/dist/etc/worldserver.conf")
+  for f in "${cands[@]}"; do
+    f=$(readlink -f "$f" 2>/dev/null || true)
+    if [[ -n "$f" && -f "$f" ]]; then
+      echo "$f"
+      return
+    fi
+  done
+  echo ""
+}
+
+binary_strings_paths() {
+  local ws="$1"
+  [[ -z "$ws" || ! -f "$ws" ]] && return
+  strings "$ws" 2>/dev/null | grep -iE '/(home|root|opt|srv|var)[^[:space:]]*/(Fractured|fractured|azeroth|AzerothCore|acore)' | sort -u | head -40
+}
+
+hr
+echo "Fractured Paragon / native VPS diagnostics"
+echo "Date (UTC): $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
+echo "Repo (expected): $REPO"
+
+sub "1A — worldserver binary"
+WS=$(detect_worldserver_bin || true)
+if [[ -z "$WS" ]]; then
+  echo "ERROR: Could not find worldserver. Set FRACTURED_WS_BIN=/full/path/to/worldserver and re-run."
+else
+  echo "Binary: $WS"
+  if stat -c 'binary mtime: %y' "$WS" 2>/dev/null; then
+    :
+  else
+    stat -f 'binary mtime: %Sm' -t '%Y-%m-%d %H:%M:%S %z' "$WS" 2>/dev/null || stat "$WS"
+  fi
+fi
+
+sub "1B — repo HEAD + Paragon_Essence.cpp mtime"
+if [[ -d "$REPO/.git" ]]; then
+  (cd "$REPO" && git log -1 --format='HEAD commit: %h %ci %s')
+else
+  echo "WARN: not a git repo: $REPO (set FRACTURED_REPO)"
+fi
+PE="$REPO/modules/mod-paragon/src/Paragon_Essence.cpp"
+if [[ -f "$PE" ]]; then
+  if stat -c 'Paragon_Essence.cpp mtime: %y' "$PE" 2>/dev/null; then
+    :
+  else
+    stat -f 'Paragon_Essence.cpp mtime: %Sm' -t '%Y-%m-%d %H:%M:%S %z' "$PE" 2>/dev/null || stat "$PE"
+  fi
+else
+  echo "WARN: missing $PE"
+fi
+
+sub "1C — strings heuristics (0 can mean stripped binary — use 1A+1B)"
+if [[ -n "$WS" && -f "$WS" ]]; then
+  c1=$(strings "$WS" 2>/dev/null | grep -c 'CLASS_PARAGON' || true)
+  c2=$(strings "$WS" 2>/dev/null | grep -c 'C BUILD SAVE_CURRENT' || true)
+  c3=$(strings "$WS" 2>/dev/null | grep -c 'character_paragon_build_share_archive' || true)
+  echo "CLASS_PARAGON count: $c1"
+  echo "C BUILD SAVE_CURRENT count: $c2"
+  echo "character_paragon_build_share_archive count: $c3"
+else
+  echo "(skipped — no binary)"
+fi
+
+sub "1D — binary fingerprint (compare sha256 across dev vs VPS)"
+if [[ -n "$WS" && -f "$WS" ]]; then
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$WS"
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$WS"
+  else
+    echo "(no sha256sum — install coreutils)"
+  fi
+  echo "Embedded revision / version strings (first matches):"
+  strings "$WS" 2>/dev/null | grep -iE 'azerothcore|revision|git|commit|build.*20[0-9]{2}' | head -25 || echo "(none matched)"
+else
+  echo "(skipped — no binary)"
+fi
+
+CONF="${FRACTURED_WORLDSERVER_CONF:-}"
+if [[ -z "$CONF" && -n "$WS" ]]; then
+  CONF=$(guess_worldserver_conf "$WS")
+fi
+
+sub "2B — worldserver.conf (updater / source / rates / paragon)"
+if [[ -n "$CONF" && -f "$CONF" ]]; then
+  echo "Using conf: $CONF"
+  grep -E '^SourceDirectory|^Updates\.EnableDatabases|^Updates\.AutoSetup|^[[:space:]]*SourceDirectory|^[[:space:]]*Updates\.EnableDatabases|^[[:space:]]*Updates\.AutoSetup' "$CONF" 2>/dev/null || echo "(no matching lines or unreadable)"
+  echo "--- Rate.RunicPower (if set) ---"
+  grep -iE '^Rate\.RunicPower|^[[:space:]]*Rate\.RunicPower' "$CONF" 2>/dev/null || echo "(not set — server uses default)"
+  echo "--- Paragon.* module options (if any) ---"
+  grep -iE '^Paragon\.|^[[:space:]]*Paragon\.' "$CONF" 2>/dev/null || echo "(no Paragon.* keys in worldserver.conf — check etc/modules/mod_paragon.conf)"
+else
+  echo "WARN: worldserver.conf not found. Set FRACTURED_WORLDSERVER_CONF=/path/to/worldserver.conf"
+fi
+
+if [[ -n "$WS" && -f "$WS" ]]; then
+  ETCGuess=$(readlink -f "$(dirname "$WS")/../etc" 2>/dev/null || true)
+  MPC="$ETCGuess/modules/mod_paragon.conf"
+  if [[ -f "$MPC" ]]; then
+    sub "2B2 — mod_paragon.conf Paragon.* toggles (non-comment)"
+    grep -E '^Paragon\.' "$MPC" 2>/dev/null | head -40 || echo "(no uncommented Paragon.* lines)"
+  fi
+fi
+
+sub "2A — path-like strings from binary (candidate source roots)"
+if [[ -n "$WS" && -f "$WS" ]]; then
+  binary_strings_paths "$WS" || true
+else
+  echo "(skipped)"
+fi
+
+sub "Resolved source root for 2D"
+RESOLVED=""
+if [[ -n "$CONF" && -f "$CONF" ]]; then
+  sd=$(awk -F= '/^[[:space:]]*SourceDirectory[[:space:]]*=/ {
+    gsub(/^[[:space:]]+|[[:space:]]+$/, "", $2);
+    gsub(/^["'\'']|["'\'']$/, "", $2);
+    print $2; exit }' "$CONF" 2>/dev/null || true)
+  if [[ -n "${sd:-}" ]]; then
+    RESOLVED="$sd"
+  fi
+fi
+if [[ -z "$RESOLVED" ]]; then
+  RESOLVED="$REPO"
+fi
+echo "Using RESOLVED=$RESOLVED (from SourceDirectory if set in conf, else FRACTURED_REPO)"
+
+sub "2D — Paragon SQL dirs under RESOLVED"
+for subdir in \
+  "$RESOLVED/modules/mod-paragon/data/sql/db-world/updates/" \
+  "$RESOLVED/modules/mod-paragon/data/sql/db-characters/updates/"; do
+  if [[ -d "$subdir" ]]; then
+    echo "Listing: $subdir"
+    ls -la "$subdir" 2>/dev/null | tail -15
+  else
+    echo "MISSING: $subdir"
+  fi
+done
+
+sub "CMake build dir hints (common Fractured layouts)"
+for cand in "$REPO/var/build/obj" "$REPO/build" "$REPO/../build"; do
+  if [[ -f "$cand/CMakeCache.txt" ]]; then
+    echo "Found CMakeCache: $cand/CMakeCache.txt"
+    grep -E '^CMAKE_HOME_DIRECTORY:|^MODULES:|^CMAKE_INSTALL_PREFIX:' "$cand/CMakeCache.txt" 2>/dev/null | head -5
+  fi
+done
+
+sub "DATABASE — updates rows (2026_05_10 / paragon)"
+SQL_WORLD=$(cat <<'EOS'
+SELECT name, hash, speed FROM updates
+ WHERE name LIKE '2026_05_10%' OR name LIKE '%paragon%'
+ ORDER BY name DESC LIMIT 30;
+EOS
+)
+SQL_CHAR="$SQL_WORLD"
+
+if [[ -n "${FRACTURED_MYSQL:-}" ]]; then
+  echo "--- acore_world ---"
+  $FRACTURED_MYSQL acore_world -e "$SQL_WORLD" || echo "(mysql failed for acore_world)"
+  echo "--- acore_characters ---"
+  $FRACTURED_MYSQL acore_characters -e "$SQL_CHAR" || echo "(mysql failed for acore_characters)"
+
+  sub "DATABASE — DBC parity for runes / Paragon (acore_world)"
+  # Common DK rune spenders (WotLK). Override: export FRACTURED_SPELL_IDS='45477 45462'
+  SPELL_IDS="${FRACTURED_SPELL_IDS:-45477 45462 49923 55050 56815}"
+  IDS_CSV=$(echo "$SPELL_IDS" | tr ' ' ',')
+  echo "--- spell_dbc table size (world DB overrides; 0 rows = all spells from disk DBC only) ---"
+  $FRACTURED_MYSQL acore_world -e "SELECT COUNT(*) AS spell_dbc_rows FROM spell_dbc;" 2>/dev/null || echo "(spell_dbc missing or no access)"
+  echo "--- acore_world.version (last core revision written by worldserver) ---"
+  $FRACTURED_MYSQL acore_world -e "SELECT * FROM version LIMIT 5;" 2>/dev/null || echo "(version table missing?)"
+
+  echo "--- chrclasses_dbc class 6 + 12 (DisplayPower: 0=mana, 5=POWER_RUNE in AC) ---"
+  $FRACTURED_MYSQL acore_world -e "
+SELECT ID, DisplayPower, Name_Lang_enUS FROM chrclasses_dbc WHERE ID IN (6,12);
+" 2>/dev/null || echo "(query failed — chrclasses_dbc missing?)"
+  echo "Note: If only ID=12 appears, class 6 (DK) is not overridden in DB — loaded from disk DBC (normal)."
+
+  echo "--- spell_dbc: are sample DK spells overridden in DB? ---"
+  spell_sample_n=$($FRACTURED_MYSQL acore_world -N -B -e \
+    "SELECT COUNT(*) FROM spell_dbc WHERE ID IN ($IDS_CSV);" 2>/dev/null || echo 0)
+  echo "Row count in spell_dbc for sample IDs ($SPELL_IDS): ${spell_sample_n:-0}"
+  if [[ "${spell_sample_n:-0}" == "0" ]]; then
+    echo "=> 0 means those spells use on-disk Spell.dbc only; the sample block below will be empty (not an error)."
+  fi
+  echo "--- spell_dbc sample (PowerType 5 = POWER_RUNE in AC) ---"
+  $FRACTURED_MYSQL acore_world -e "
+SELECT ID, PowerType, ManaCost, RuneCostID FROM spell_dbc WHERE ID IN ($IDS_CSV);
+" 2>/dev/null || echo "(query failed — spell_dbc missing or wrong schema)"
+  echo "--- spellrunecost join for sample IDs (empty if no spell_dbc rows above) ---"
+  $FRACTURED_MYSQL acore_world -e "
+SELECT s.ID AS spell_id, s.PowerType, s.RuneCostID, r.Blood, r.Unholy, r.Frost, r.RunicPower
+FROM spell_dbc s
+LEFT JOIN spellrunecost_dbc r ON r.ID = s.RuneCostID
+WHERE s.ID IN ($IDS_CSV);
+" 2>/dev/null || echo "(join failed — check spellrunecost_dbc)"
+
+  echo "--- spell_dbc suspicious overrides: RuneCostID>0 but PowerType!=5 (can break rune checks) ---"
+  $FRACTURED_MYSQL acore_world -e "
+SELECT ID, PowerType, ManaCost, RuneCostID FROM spell_dbc
+ WHERE RuneCostID > 0 AND PowerType <> 5
+ ORDER BY ID LIMIT 40;
+" 2>/dev/null || echo "(query failed)"
+  echo "Compare counts/IDs to dev: unexpected rows here warrant a DB diff."
+
+  echo "--- spell_dbc POWER_RUNE (5) spells with RuneCostID (sample) ---"
+  $FRACTURED_MYSQL acore_world -e "
+SELECT ID, PowerType, RuneCostID FROM spell_dbc
+ WHERE PowerType = 5 AND RuneCostID > 0
+ ORDER BY ID LIMIT 15;
+" 2>/dev/null || echo "(query failed)"
+else
+  echo "FRACTURED_MYSQL not set — run manually (example: export FRACTURED_MYSQL='mysql -uUSER -hHOST')"
+  echo "acore_world:"
+  echo "$SQL_WORLD"
+  echo "acore_characters:"
+  echo "$SQL_CHAR"
+  echo ""
+  echo "Optional DBC parity (acore_world) — run after connecting:"
+  echo "  SELECT ID, DisplayPower, Name_Lang_enUS FROM chrclasses_dbc WHERE ID IN (6,12);"
+  echo "  SELECT ID, PowerType, ManaCost, RuneCostID FROM spell_dbc WHERE ID IN (45477,45462,49923,55050,56815);"
+  echo "  SELECT s.ID, s.RuneCostID, r.Blood, r.Unholy, r.Frost, r.RunicPower FROM spell_dbc s"
+  echo "    LEFT JOIN spellrunecost_dbc r ON r.ID = s.RuneCostID WHERE s.ID IN (45477,45462,49923,55050,56815);"
+fi
+
+sub "mod_paragon.conf vs .dist (install etc)"
+ETC=""
+if [[ -n "$WS" ]]; then
+  ETC=$(readlink -f "$(dirname "$WS")/../etc" 2>/dev/null || true)
+fi
+if [[ -z "$ETC" || ! -d "$ETC" ]]; then
+  ETC=$(readlink -f "$HOME/azeroth-server/etc" 2>/dev/null || true)
+fi
+if [[ -n "$ETC" && -d "$ETC/modules" ]]; then
+  MP="$ETC/modules/mod_paragon.conf"
+  MPD="$ETC/modules/mod_paragon.conf.dist"
+  if [[ -f "$MP" && -f "$MPD" ]]; then
+    diff -u "$MP" "$MPD" 2>/dev/null | head -80 || true
+  else
+    echo "ETC=$ETC — mod_paragon.conf or .dist missing (MP=$MP MPD=$MPD)"
+  fi
+else
+  echo "Could not find install etc/modules (set paths manually for diff)."
+fi
+
+hr
+echo "DELIVERABLE for maintainer:"
+echo "1) Paste 1A–1D (binary mtime, git HEAD, strings, sha256 + revision strings)."
+echo "2) Paste DATABASE blocks: updates + DBC parity (chrclasses 12, spell_dbc, spellrunecost join)."
+echo "3) Paste 2A path strings + 2D listings (or MISSING lines)."
+echo "4) From dev: same 1D sha256 of worldserver OR same SQL block — proves binary/data parity."
+echo "5) ONE sentence: exact in-game symptom."
+echo "Done."
+echo ""
+echo "Full transcript: $DIAG_OUT"

tools/fractured-launcher-electron/README.md

@@ -1,6 +1,6 @@
 # Fractured Launcher (Electron)
 
-Windows launcher with **no extra console window**, **native Browse folder** dialog, GitHub **release assets** + repo file sync, **realmlist**, optional **auth**, **Play**, and **auto-update** (via `electron-updater`). This is the **only** supported client launcher in this repo.
+Windows launcher with **no extra console window**, **native Browse folder** dialog, **Gitea or GitHub** release assets + GitHub repo file sync, **realmlist**, optional **auth**, **Play**, and **auto-update** (via `electron-updater`). This is the **only** supported client launcher in this repo.
 
 ## Requirements
 
@@ -14,7 +14,12 @@ npm install
 npm start
 ```
 
-On first run, `launcher.json` is created next to the app (dev: in this folder). By default **`github.repo`** is **`Fractured-Distro`** (public release assets); no token is required for patches. Set **GITHUB_TOKEN** only if you override `github` to a **private** repo.
+On first run, `launcher.json` is created next to the app (dev: in this folder).
+
+### Where patches download from
+
+- **Recommended (self-hosted Gitea):** set **`gitea.base_url`**, **`gitea.owner`**, **`gitea.repo`** in `launcher.json` (see **`default-launcher.json`**). Players need **`GITEA_TOKEN`** (or the env name in **`gitea.token_env`**) if the Gitea repo is **private** — same trade-off as any private host (per-player token, SSO proxy, or a read-only deploy token you accept distributing).
+- **Fallback:** if **`gitea.base_url`** is empty, **`from_release`** uses the **GitHub** Releases API against **`github.owner` / `github.repo`** (defaults to this **`Fractured`** repo for non-release paths), with optional **`GITHUB_TOKEN`** for private assets.
 
 ## Build Windows installers
 
@@ -30,63 +35,124 @@ Produces under **`dist/`**:
 | `Fractured-Launcher-${version}-Setup.exe` (NSIS) | **Recommended for players** — supports seamless **auto-update** and restart. |
 | `Fractured-Launcher-${version}-Windows-Portable.exe` | No installer; players replace the file manually. Auto-update is **less reliable** than NSIS. |
 
+### Baked Gitea channel (non-token)
+
+**`npm run pack:win`** runs **`scripts/inject-release-channel.js`** first. It merges **`gitea.base_url`**, **`owner`**, **`repo`**, and optional **`release_tag`** into **`default-launcher.json`** for that build only (then **electron-builder** packs that file).
+
+- **GitHub Actions** — **Sync release to Gitea** and **Fractured launcher CI** export **`GITEA_BASE_URL`**, **`GITEA_OWNER`**, **`GITEA_REPO`** (same names as your upload secrets) for the pack step, so installers match the repo you sync to. Nothing embeds **`GITEA_TOKEN`**.
+- **Local packs** — put the same values in **`fractured-release-channel.json`** (committed or personal copy) **or** export those env vars before **`npm run pack:win`**.
+
+First launch still copies **`default-launcher.json`** → **`launcher.json`** beside the exe, so players get the baked **`gitea.*`** without editing unless they override.
+
 ## Auto-update behaviour
 
 - **Packaged** builds only (`npm run pack:win` output). In `npm start` dev mode, update checks are skipped (button still explains that).
-- **~5 seconds** after launch, then **every 6 hours**, the app checks for a newer version.
+- **No implicit GitHub feed:** the app does **not** guess `package.json` → `repository` anymore. Without configuration you get a clear “skipped” message instead of a **404** on a private repo.
+- **Configured feeds** (first match wins): **`update_feed_url` / `LAUNCHER_UPDATE_URL`** (generic `latest.yml`); or **`gitea`** block filled in + **`GITEA_TOKEN`** when the instance is private (resolves `…/releases/download/{tag}/`); or **`GITHUB_TOKEN`** + **`github.owner` / `github.repo`** for **private** GitHub releases only.
+- **~5 seconds** after launch, then **every 6 hours**, the app checks when a feed is configured.
 - When a download finishes, a dialog offers **Restart now** (calls `quitAndInstall`) or **Later**.
 - **Manual check:** button **Check launcher updates** in the UI.
 
-### Where updates are hosted
+### Where launcher updates are hosted
 
-**`package.json`** → `build.publish` targets **`Dawnforger/Fractured-Distro`** (public). `electron-updater` reads **`latest.yml`** from the **latest** release there; players do not need a GitHub token for launcher updates.
+**`npm run publish:win`** runs **`electron-builder` with `--publish never`** — artifacts stay in **`dist/`**; CI uploads them to Gitea when you **publish a GitHub release**. For ad-hoc uploads, use **`scripts/upload-release-to-gitea.sh`**. For launcher auto-update, prefer:
 
-**Private GitHub** (if you change `build.publish` or `github` back to a private repo): set **`GH_TOKEN`** / **`GITHUB_TOKEN`** / **`github.token_env`** before starting the launcher so the updater can authenticate.
+- Set **`update_feed_url`** (or **`LAUNCHER_UPDATE_URL`**) to a **generic** HTTPS base URL where **`latest.yml`** and the installer files are hosted (often the same Gitea release attachment URLs pattern your reverse proxy exposes), **or**
+- Keep publishing to a GitHub release only for **`latest.yml`** + installers if you accept that small metadata/binary channel there.
 
-**Public generic feed** (optional CDN): set **`update_feed_url`** or **`LAUNCHER_UPDATE_URL`** to a folder that hosts `latest.yml` + installers; optional Bearer token if the host requires it.
+**Private GitHub** updater: set **`GH_TOKEN`** / **`GITHUB_TOKEN`** / **`github.token_env`** as documented in `lib/auto-update.js` behaviour.
+
+**Generic feed:** optional Bearer token via the same token envs if your static host checks `Authorization`.
 
 ### Publishing a new launcher version
 
-1. Bump **`version`** in `package.json` (semver, e.g. `1.0.1`).
-2. Create a **GitHub personal access token** with `repo` (or `public_repo` for public repos).
-3. From this directory:
+1. Bump **`version`** in `package.json` on `main` (or your release branch) and merge.
+2. Create a **GitHub release** (tag + attach patches / `Wow.exe` if needed) and click **Publish** — **Sync release to Gitea** builds Windows installers and mirrors everything to Gitea.
+3. Local check: `npm run pack:win` then **`scripts/upload-release-to-gitea.sh`** with the same **`GITEA_*`** env vars as CI if you need a manual upload.
 
-```bash
-set GH_TOKEN=ghp_your_token_here
-npm run publish:win
+## Sync to Gitea (patches + launcher binaries)
+
+CI workflow **Sync release to Gitea** (`.github/workflows/gitea-release-sync.yml`) runs on **every published GitHub release** on this repo:
+
+1. Triggers on **release published** on **`Dawnforger/Fractured`** (or **workflow_dispatch** with a tag).
+2. Builds the **Electron** app from that tag on Windows.
+3. Downloads **all assets** attached to that **GitHub** release (MPQs, patched `Wow.exe`, etc.).
+4. Merges with the built launcher artifacts and uploads everything to a **Gitea release** with the **same tag** (existing attachments on that Gitea release are replaced).
+
+**GitHub Actions secrets** (repository → Settings → Secrets and variables → Actions):
+
+| Secret | Example |
+|--------|---------|
+| **`GITEA_BASE_URL`** | `https://git.yourdomain.com` (no trailing slash) |
+| **`GITEA_TOKEN`** | Gitea personal access token with permission to manage releases and attachments on the target repo |
+| **`GITEA_OWNER`** | Organization or username on Gitea |
+| **`GITEA_REPO`** | Repository name — must already have **at least one commit** (Gitea returns HTTP 422 “repo is empty” for zero-commit repos; push e.g. a README on **`main`** or set **`GITEA_TARGET_REF`** to your default branch) |
+
+**Optional variable** (Settings → Variables): **`GITEA_TARGET_REF`** — default branch/commitish used **only when the workflow must create a new Gitea release** and Gitea needs `target_commitish` (defaults to **`main`** in the upload script if unset).
+
+**Player `launcher.json`:** packaged builds should already include **`gitea.base_url` / `owner` / `repo`** from the bake step above. Players only need to set **`GITEA_TOKEN`** (or your **`token_env`**) if the Gitea repo is **private**. To point at another instance, edit **`gitea`** in **`launcher.json`**:
+
+```json
+"gitea": {
+  "base_url": "https://git.yourdomain.com",
+  "owner": "myorg",
+  "repo": "fractured-patches",
+  "release_tag": "latest",
+  "token_env": "GITEA_TOKEN"
+}
 ```
 
-That builds NSIS + portable and **uploads** update metadata and installers to the configured GitHub repo’s **releases** (see [electron-builder publish](https://www.electron.build/configuration/publish)).
+**Manual upload:** `bash scripts/upload-release-to-gitea.sh /path/to/files v1.0.0` with the same env vars as CI.
 
-Players on an older NSIS install will pick up the next version automatically on the next check.
+### Sync did not run / Gitea unchanged — checklist
 
-## Public distro repo (patches + launcher binaries)
+1. **Git tag ≠ GitHub Release** — Only **Releases** (published on the GitHub **Releases** page) trigger this workflow. If your teammate only **`git push --tags`**, create a **Release** from that tag and click **Publish** (or run **Actions → Sync release to Gitea → Run workflow** and enter the tag).
+2. **Draft release** — Must click **Publish release**; drafts do not mirror.
+3. **Workflow on default branch** — GitHub runs `release` workflows from the **default branch** (e.g. `main`). Ensure `.github/workflows/gitea-release-sync.yml` is merged there.
+4. **Repo name guard** — Jobs use `if: github.repository == 'Dawnforger/Fractured'`. Forks or renames must change that line or runs are skipped.
+5. **Secrets** — **`GITEA_BASE_URL`**, **`GITEA_TOKEN`**, **`GITEA_OWNER`**, **`GITEA_REPO`** must be set under **Settings → Secrets and variables → Actions**. A failed “Upload to Gitea” step usually prints which is missing.
+6. **Actions tab** — Open the latest **Sync release to Gitea** run; a red **build-electron** (old tag without `package-lock.json`, etc.) or **Upload to Gitea** step shows the real error.
+7. **HTTP 422 `repo is empty`** — The Gitea repo has **no commits** yet. Push any initial commit (e.g. **Add README** in the Gitea web UI, or `git push` to **`main`**). Optionally set **`GITEA_TARGET_REF`** to match your real default branch if it is not **`main`**. From this repo you can run **`scripts/bootstrap-gitea-repo.sh`** (see script header for `GITEA_*` env or pass the HTTPS/SSH clone URL as the first argument).
 
-Default **`default-launcher.json`** uses **`github.repo`: `Fractured-Distro`** so **`from_release`** assets (`patch-Z.MPQ`, `Wow-patched.exe`, …) download from **[Dawnforger/Fractured-Distro releases](https://github.com/Dawnforger/Fractured-Distro/releases)** — **no player token**.
+### Private Gitea token for players
 
-Publish assets there by:
+Do **not** embed a shared admin PAT in a shipped `launcher.json`. Prefer read-only tokens scoped to one repo, short-lived tokens, or a small auth service that redirects to signed URLs.
 
-- **GitHub Actions** — workflow **Sync release to Fractured-Distro** (`.github/workflows/distro-release-sync.yml`): on **release published** on `Dawnforger/Fractured`, it **builds the Electron launcher** from that tag on Windows (`npm run pack:win`), **downloads every asset** attached to that release (patches, `Wow-patched.exe`, …), merges them (launcher files overwrite on duplicate names), and creates or updates the **same tag** on **`Fractured-Distro`**. Requires repository secret **`DISTRO_SYNC_TOKEN`**. **Manual:** Actions → run workflow with an existing tag.
-- **Locally:** `scripts/publish-to-distro.sh` (see script header) if you need to upload without a full release cycle.
+**Release asset names** must match **`files[].source`** when **`from_release`**: true. Use **`release_tag`**: `"latest"` or a pinned tag matching both GitHub and Gitea.
 
-If your public repo slug is not `Fractured-Distro`, edit **`DISTRO_REPO`** in the workflow / script and **`github.repo`** in `launcher.json`.
+## Patch versions (same filenames, different bytes)
 
-### Private `github.repo` (optional)
+The launcher does **not** read Git commits. For **turn-key** updates when asset names stay fixed (`patch-Z.MPQ`, `Wow-patched.exe`, …):
 
-For a **private** release source, set `GITHUB_TOKEN` (or `github.token_env`) with read access — **do not** embed a shared PAT in shipped `launcher.json` for all players.
+1. Ship **`patch-manifest.json`** next to those files on **every** release (Gitea/GitHub attachment). It lists a **`version`** label (any string you bump per release, e.g. `v0.9.0-client`) and a **`sha256`** per **`files[].source`** name.
+2. With **`patch_manifest.enabled`**: true (default in **`default-launcher.json`**), **Download updates** first fetches the manifest from the same release channel. If the files already on disk match those checksums, the player sees **“already match build … (nothing to download)”** — no redundant downloads.
+3. After a real download, the launcher **re-hashes** installed files and compares to the manifest; mismatch → clear error. It also writes **`.fractured/patch-state.json`** under the WoW folder so the UI can show **“Installed client files: …”**.
 
-**Release asset names** must match **`files[].source`** exactly when **`from_release`**: true. Use **`release_tag`: `"latest"`** for the newest release, or pin a tag.
+If **`patch-manifest.json`** is missing on a release, the launcher falls back to **always downloading** all configured files (same as before).
+
+**Generate the manifest** when you cut a release (paths are your local patch binaries):
+
+```bash
+cd /path/to/staging
+node tools/fractured-launcher-electron/scripts/generate-patch-manifest.js v0.9.0-client patch-Z.MPQ Wow-patched.exe > patch-manifest.json
+```
+
+Attach **`patch-manifest.json`** together with the MPQ/exe to the GitHub release (CI sync copies it to Gitea with everything else).
 
 ## CI
 
-Workflow **Fractured launcher CI** (`.github/workflows/fractured-launcher-ci.yml`) runs on pushes/PRs under `tools/fractured-launcher-electron/`: Windows **`npm run pack:win`** and **artifacts** (`*.exe`, `latest.yml`, blockmaps). **Actions → Fractured launcher CI → Run workflow** runs it manually.
+Workflow **Fractured launcher CI** (`.github/workflows/fractured-launcher-ci.yml`) runs on pushes/PRs under `tools/fractured-launcher-electron/`: Windows pack uses **`electron-builder … --publish never`** (not `npm run pack:win`, so tagged checkouts never require `GH_TOKEN`). **Actions → Fractured launcher CI → Run workflow** runs it manually.
+
+**Sync release to Gitea** (`.github/workflows/gitea-release-sync.yml`) uses the same pack command. If you see `GH_TOKEN` / `GitHubPublisher` errors in logs, the job is almost certainly an old **Re-run failed jobs** — open **Actions → Sync release to Gitea → Run workflow**, enter the tag, and start a **new** run instead.
 
 ## Config
 
 Schema is defined by **`default-launcher.json`** (shipped in the app; first run copies to `launcher.json` beside the executable):
 
 - **`game_dir`**: WoW 3.3.5a root (contains `Wow.exe`).
-- **`update_feed_url`**: optional generic HTTPS base for launcher auto-update (overrides default GitHub feed when set).
-- **`github`**: `owner`, `repo`, `ref` (repo file paths), **`release_tag`** (`latest` or e.g. `v1.0.0`), **`token_env`** (env var name for a PAT when using private sources).
-- **`files`**: `source`, `dest`, `backup`, **`from_release`** (asset name on GitHub release vs repo path).
-- **`realmlist`**, **`auth`**, **`launch`**.
+- **`update_feed_url`**: optional generic HTTPS base for launcher auto-update.
+- **`launcher_updates_from_github`**: default **`false`**. Only when **`true`** will a **`GITHUB_TOKEN`** (or **`github.token_env`**) enable **electron-updater**’s GitHub provider against **`github.owner` / `github.repo`**. Leave **`false`** when launcher binaries and **`latest.yml`** live on **Gitea** (use **`gitea`** + token instead) so a stray GitHub token does not produce “No published versions on GitHub”.
+- **`gitea`**: **`base_url`**, **`owner`**, **`repo`**, **`release_tag`**, **`token_env`** — when **`base_url`** is set (and owner/repo set), **`from_release`** downloads and (with token if needed) the **generic** updater feed use **Gitea**. **Required** for players if your CI mirrors patches/launchers to Gitea only.
+- **`github`**: used for **non-release** repo paths (`from_release`: false) and for **GitHub** **`from_release`** when **`gitea.base_url`** is empty.
+- **`patch_manifest`**: **`enabled`**, **`source`** (default `patch-manifest.json`), **`from_release`** — checksum-based skip + verify (see above).
+- **`files`**, **`realmlist`**, **`auth`**, **`launch`**.

tools/fractured-launcher-electron/default-launcher.json

@@ -1,13 +1,26 @@
 {
   "game_dir": "",
   "update_feed_url": "",
+  "launcher_updates_from_github": false,
+  "gitea": {
+    "base_url": "",
+    "owner": "",
+    "repo": "",
+    "release_tag": "latest",
+    "token_env": "GITEA_TOKEN"
+  },
   "github": {
     "owner": "Dawnforger",
-    "repo": "Fractured-Distro",
+    "repo": "Fractured",
     "ref": "main",
     "release_tag": "latest",
     "token_env": "GITHUB_TOKEN"
   },
+  "patch_manifest": {
+    "enabled": true,
+    "source": "patch-manifest.json",
+    "from_release": true
+  },
   "files": [
     {
       "source": "patch-Z.MPQ",

tools/fractured-launcher-electron/fractured-release-channel.json

@@ -0,0 +1,8 @@
+{
+  "gitea": {
+    "base_url": "",
+    "owner": "",
+    "repo": "",
+    "release_tag": "latest"
+  }
+}

tools/fractured-launcher-electron/lib/auto-update.js

@@ -2,28 +2,51 @@
 
 const { dialog } = require('electron');
 const { autoUpdater } = require('electron-updater');
+const { useGiteaReleases, getGiteaUpdaterFeedBase } = require('./gitea-release');
 
 /**
  * @param {import('electron').App} app
  * @param {() => import('electron').BrowserWindow | null} getMainWindow
- * @param {{ updateFeedUrl?: string, githubOwner?: string, githubRepo?: string, token?: string }} opts
+ * @param {{
+ *   updateFeedUrl?: string,
+ *   githubOwner?: string,
+ *   githubRepo?: string,
+ *   githubToken?: string,
+ *   giteaToken?: string,
+ *   allowGithubLauncherUpdates?: boolean,
+ *   config?: object,
+ * }} opts
  */
-function setupAutoUpdater(app, getMainWindow, opts = {}) {
+async function setupAutoUpdater(app, getMainWindow, opts = {}) {
   if (!app.isPackaged) {
     return {
       checkNow: async () => ({ skipped: true, reason: 'development build' }),
     };
   }
 
-  autoUpdater.autoDownload = true;
-  autoUpdater.autoInstallOnAppQuit = true;
-
-  const token = String(opts.token || '').trim();
+  const ghToken = String(opts.githubToken || '').trim();
+  const giteaTok = String(opts.giteaToken || '').trim();
   const envGeneric = String(process.env.LAUNCHER_UPDATE_URL || '').trim();
   const configGeneric = String(opts.updateFeedUrl || '').trim();
-  const genericUrl = envGeneric || configGeneric;
-  const owner = String(opts.githubOwner || 'Dawnforger').trim();
-  const repo = String(opts.githubRepo || 'Fractured').trim();
+  let genericUrl = envGeneric || configGeneric;
+  let genericAuthHeader = '';
+
+  if (!genericUrl && opts.config && useGiteaReleases(opts.config)) {
+    const gfb = await getGiteaUpdaterFeedBase(opts.config);
+    if (gfb && gfb.url) {
+      genericUrl = gfb.url;
+      const t = String(gfb.token || giteaTok || '').trim();
+      if (t) genericAuthHeader = `token ${t}`;
+    }
+  } else if (genericUrl) {
+    if (giteaTok) genericAuthHeader = `token ${giteaTok}`;
+    else if (ghToken) genericAuthHeader = `Bearer ${ghToken}`;
+  }
+
+  const owner = String(opts.githubOwner || '').trim();
+  const repo = String(opts.githubRepo || '').trim();
+
+  let feedConfigured = false;
 
   if (genericUrl) {
     const base = genericUrl.replace(/\/?$/, '/');
@@ -31,22 +54,37 @@ function setupAutoUpdater(app, getMainWindow, opts = {}) {
       provider: 'generic',
       url: base,
     });
-    if (token) {
+    if (genericAuthHeader) {
       autoUpdater.requestHeaders = {
         ...autoUpdater.requestHeaders,
-        Authorization: `Bearer ${token}`,
+        Authorization: genericAuthHeader,
       };
     }
-  } else if (token && owner && repo) {
+    feedConfigured = true;
+  } else if (opts.allowGithubLauncherUpdates && ghToken && owner && repo) {
     autoUpdater.setFeedURL({
       provider: 'github',
       owner,
       repo,
       private: true,
-      token,
+      token: ghToken,
     });
+    feedConfigured = true;
   }
 
+  if (!feedConfigured) {
+    const reason =
+      'No update channel configured. Set launcher.json → update_feed_url (HTTPS folder with latest.yml), ' +
+      'or fill gitea.base_url/owner/repo (+ GITEA_TOKEN for private), ' +
+      'or set launcher_updates_from_github to true with GITHUB_TOKEN for private GitHub release feeds.';
+    return {
+      checkNow: async () => ({ skipped: true, reason }),
+    };
+  }
+
+  autoUpdater.autoDownload = true;
+  autoUpdater.autoInstallOnAppQuit = true;
+
   const send = (msg) => {
     const w = getMainWindow();
     if (w && !w.isDestroyed()) {
@@ -63,9 +101,8 @@ function setupAutoUpdater(app, getMainWindow, opts = {}) {
     const m = (err && (err.message || String(err))) || '';
     if (/404|releases\.atom|HttpError:\s*404/i.test(m)) {
       send(
-        'Launcher update: could not read GitHub releases (404). ' +
-          'If the repo is private, set GITHUB_TOKEN (or your token_env) so the launcher can authenticate, ' +
-          'or set update_feed_url in launcher.json to a public HTTPS folder that contains latest.yml.'
+        'Launcher update: 404 (no latest.yml or wrong URL). For Gitea use gitea.* + token, or set update_feed_url. ' +
+          'For private GitHub set GITHUB_TOKEN.'
       );
       return;
     }

tools/fractured-launcher-electron/lib/github.js

@@ -3,6 +3,7 @@
 const path = require('path');
 const fs = require('fs').promises;
 const { githubToken } = require('./github-token');
+const { downloadGiteaReleaseAsset, useGiteaReleases } = require('./gitea-release');
 const { fetchToFile, downloadBodyToFile } = require('./http-download');
 
 function encodeRepoPath(repoPath) {
@@ -65,6 +66,9 @@ async function downloadGitHubRepoFile(cfg, repoPath, destPath) {
 }
 
 async function downloadReleaseAsset(cfg, assetName, destPath) {
+  if (useGiteaReleases(cfg)) {
+    return downloadGiteaReleaseAsset(cfg, assetName, destPath);
+  }
   const token = githubToken(cfg);
   const tag = (cfg.github.release_tag || 'latest').trim() || 'latest';
   const { owner, repo } = cfg.github;
@@ -78,7 +82,10 @@ async function downloadReleaseAsset(cfg, assetName, destPath) {
   const text = await res.text();
   if (!res.ok) {
     let hint = '';
-    if (res.status === 404) hint = ' (wrong tag or private repo without token?)';
+    if (res.status === 404) {
+      hint =
+        ' (wrong tag, private repo without token, or releases live on Gitea — set gitea.base_url, gitea.owner, gitea.repo in launcher.json)';
+    }
     if (res.status === 401 || res.status === 403) hint = ' (set GITHUB_TOKEN or token_env PAT)';
     throw new Error(`releases list ${res.status}${hint}: ${text.slice(0, 600)}`);
   }

tools/fractured-launcher-electron/main.js

@@ -5,6 +5,7 @@ const path = require('path');
 const { spawn } = require('child_process');
 const { loadConfig, saveGameDir, resolveGameDir } = require('./lib/config-store');
 const { applyPatches, wowExePath, wowInstallValid, doAuth } = require('./lib/patch');
+const { readPatchState } = require('./lib/patch-manifest');
 const { setupAutoUpdater } = require('./lib/auto-update');
 
 let mainWindow;
@@ -46,16 +47,23 @@ async function readMergedConfig() {
 app.whenReady().then(async () => {
   createWindow();
   const { config } = await loadConfig(app);
-  const tokenEnv = config.github && config.github.token_env;
-  const token =
-    (tokenEnv && String(process.env[tokenEnv] || '').trim()) ||
+  const ghEnv = config.github && config.github.token_env;
+  const githubToken =
+    (ghEnv && String(process.env[ghEnv] || '').trim()) ||
     String(process.env.GH_TOKEN || process.env.GITHUB_TOKEN || '').trim();
+  const giteaEnv = config.gitea && config.gitea.token_env;
+  const giteaToken =
+    (giteaEnv && String(process.env[giteaEnv] || '').trim()) ||
+    String(process.env.GITEA_TOKEN || '').trim();
   const updateFeedUrl = String(process.env.LAUNCHER_UPDATE_URL || config.update_feed_url || '').trim();
-  autoUpdateApi = setupAutoUpdater(app, () => mainWindow, {
+  autoUpdateApi = await setupAutoUpdater(app, () => mainWindow, {
     updateFeedUrl,
+    config,
     githubOwner: config.github && config.github.owner,
     githubRepo: config.github && config.github.repo,
-    token,
+    githubToken,
+    giteaToken,
+    allowGithubLauncherUpdates: config.launcher_updates_from_github === true,
   });
   app.on('activate', () => {
     if (BrowserWindow.getAllWindows().length === 0) createWindow();
@@ -68,12 +76,18 @@ app.on('window-all-closed', () => {
 
 ipcMain.handle('launcher:load', async () => {
   const { configPath, config } = await readMergedConfig();
+  let clientBuild = '';
+  if (wowInstallValid(config)) {
+    const st = await readPatchState(config.game_dir);
+    if (st && st.client_build) clientBuild = String(st.client_build);
+  }
   return {
     configPath,
     gameDir: config.game_dir || '',
     authEnabled: !!(config.auth && config.auth.enabled),
     wowExe: (config.launch && config.launch.exe) || 'Wow.exe',
     wowOk: wowInstallValid(config),
+    clientBuild,
   };
 });
 

tools/fractured-launcher-electron/package.json

@@ -9,8 +9,8 @@
   },
   "scripts": {
     "start": "electron .",
-    "pack:win": "electron-builder --win nsis portable --x64",
-    "publish:win": "electron-builder --win nsis portable --x64 --publish always"
+    "pack:win": "node scripts/inject-release-channel.js && electron-builder --win nsis portable --x64 --publish never",
+    "publish:win": "node scripts/inject-release-channel.js && electron-builder --win nsis portable --x64 --publish never"
   },
   "author": "",
   "license": "GPL-3.0",
@@ -27,13 +27,7 @@
     "directories": {
       "output": "dist"
     },
-    "publish": [
-      {
-        "provider": "github",
-        "owner": "Dawnforger",
-        "repo": "Fractured-Distro"
-      }
-    ],
+    "publish": null,
     "files": [
       "main.js",
       "preload.cjs",

tools/fractured-launcher-electron/scripts/bootstrap-gitea-repo.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Push a one-file README so the Gitea repo is non-empty (fixes HTTP 422 "repo is empty"
+# when CI creates a release). Safe to re-run only if the repo still has no commits;
+# if it already has history, skip or use the Gitea web UI instead.
+#
+# Usage:
+#   export GITEA_BASE_URL=https://git.example.com
+#   export GITEA_OWNER=myorg
+#   export GITEA_REPO=fractured-patches
+#   ./bootstrap-gitea-repo.sh
+#
+# Or pass an explicit clone URL (HTTPS or SSH):
+#   ./bootstrap-gitea-repo.sh https://git.example.com/myorg/fractured-patches.git
+#
+set -euo pipefail
+
+BRANCH="${GITEA_TARGET_REF:-main}"
+
+if [ "${1:-}" != "" ]; then
+  URL="$1"
+else
+  : "${GITEA_BASE_URL:?Set GITEA_BASE_URL or pass clone URL as first argument}"
+  : "${GITEA_OWNER:?Set GITEA_OWNER or pass clone URL as first argument}"
+  : "${GITEA_REPO:?Set GITEA_REPO or pass clone URL as first argument}"
+  BASE="${GITEA_BASE_URL%/}"
+  URL="${BASE}/${GITEA_OWNER}/${GITEA_REPO}.git"
+fi
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+cd "$TMP"
+
+git init -q
+git checkout -q -b "$BRANCH"
+
+cat >README.md <<'EOF'
+# Fractured release mirror
+
+Release assets (launcher builds, patches, `patch-manifest.json`, etc.) are uploaded here by **GitHub Actions** (“Sync release to Gitea”) from the main Fractured repository.
+
+This initial commit exists because **Gitea requires at least one commit** in the repository before releases can be created.
+EOF
+
+git add README.md
+git commit -q -m "chore: initial commit (required for Gitea releases)"
+
+git remote add origin "$URL"
+git push -u origin "$BRANCH"
+
+echo "Pushed initial README to $URL (branch $BRANCH)."

tools/fractured-launcher-electron/scripts/inject-release-channel.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Merge Gitea release channel (non-token) into default-launcher.json before pack.
+ * Precedence: env → fractured-release-channel.json → leave existing default-launcher values.
+ *
+ * Env (any of these names):
+ *   FRACTURED_LAUNCHER_GITEA_BASE_URL | GITEA_BASE_URL
+ *   FRACTURED_LAUNCHER_GITEA_OWNER   | GITEA_OWNER
+ *   FRACTURED_LAUNCHER_GITEA_REPO    | GITEA_REPO
+ *   FRACTURED_LAUNCHER_GITEA_RELEASE_TAG | GITEA_RELEASE_TAG
+ */
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const defPath = path.join(root, 'default-launcher.json');
+const channelPath = path.join(root, 'fractured-release-channel.json');
+
+function pickEnv() {
+  return {
+    base_url: String(
+      process.env.FRACTURED_LAUNCHER_GITEA_BASE_URL || process.env.GITEA_BASE_URL || ''
+    ).trim(),
+    owner: String(
+      process.env.FRACTURED_LAUNCHER_GITEA_OWNER || process.env.GITEA_OWNER || ''
+    ).trim(),
+    repo: String(
+      process.env.FRACTURED_LAUNCHER_GITEA_REPO || process.env.GITEA_REPO || ''
+    ).trim(),
+    release_tag: String(
+      process.env.FRACTURED_LAUNCHER_GITEA_RELEASE_TAG || process.env.GITEA_RELEASE_TAG || ''
+    ).trim(),
+  };
+}
+
+function main() {
+  const cfg = JSON.parse(fs.readFileSync(defPath, 'utf8'));
+  cfg.gitea = cfg.gitea && typeof cfg.gitea === 'object' ? cfg.gitea : {};
+
+  let fileGitea = {};
+  try {
+    const raw = JSON.parse(fs.readFileSync(channelPath, 'utf8'));
+    if (raw && raw.gitea && typeof raw.gitea === 'object') fileGitea = raw.gitea;
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+
+  const env = pickEnv();
+  const keys = ['base_url', 'owner', 'repo', 'release_tag'];
+  let changed = false;
+
+  for (const k of keys) {
+    const fromEnv = env[k];
+    const fromFile =
+      fileGitea[k] != null && String(fileGitea[k]).trim() !== '' ? String(fileGitea[k]).trim() : '';
+    const val = (fromEnv && String(fromEnv).trim()) || fromFile;
+    if (!val) continue;
+    if (cfg.gitea[k] !== val) {
+      cfg.gitea[k] = val;
+      changed = true;
+    }
+  }
+
+  if (!changed) {
+    console.log(
+      'inject-release-channel: no overrides (set GITEA_* env and/or fill fractured-release-channel.json)'
+    );
+    return;
+  }
+
+  fs.writeFileSync(defPath, `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
+  console.log('inject-release-channel: wrote gitea.* into default-launcher.json for this build');
+}
+
+main();

tools/fractured-launcher-electron/scripts/upload-release-to-gitea.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Upload all files in a directory as attachments on a Gitea release (create release if missing).
+#
+# Usage:
+#   export GITEA_BASE_URL=https://git.example.com
+#   export GITEA_TOKEN=gta_...
+#   export GITEA_OWNER=myorg
+#   export GITEA_REPO=fractured-patches
+#   export GITEA_TARGET_REF=main   # optional, used when creating a new release (tag must not exist yet)
+#   ./upload-release-to-gitea.sh /path/to/combined v1.0.0
+#
+set -euo pipefail
+
+COMBINED_DIR="${1:?first arg: directory of files to attach}"
+TAG="${2:?second arg: release tag (e.g. v1.0.0)}"
+
+: "${GITEA_BASE_URL:?Set GITEA_BASE_URL (no trailing slash required)}"
+: "${GITEA_TOKEN:?Set GITEA_TOKEN}"
+: "${GITEA_OWNER:?Set GITEA_OWNER}"
+: "${GITEA_REPO:?Set GITEA_REPO}"
+
+BASE="${GITEA_BASE_URL%/}"
+API="$BASE/api/v1"
+TARGET="${GITEA_TARGET_REF:-main}"
+AUTH_H=(-H "Authorization: token ${GITEA_TOKEN}" -H "Accept: application/json")
+
+TAG_ENC=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1], safe=''))" "$TAG")
+REL_JSON=$(mktemp)
+trap 'rm -f "$REL_JSON"' EXIT
+
+code=$(curl -sS -o "$REL_JSON" -w "%{http_code}" "${AUTH_H[@]}" \
+  "$API/repos/${GITEA_OWNER}/${GITEA_REPO}/releases/tags/${TAG_ENC}")
+
+if [ "$code" = "200" ]; then
+  rel_id=$(jq -r '.id' "$REL_JSON")
+elif [ "$code" = "404" ]; then
+  body=$(jq -n \
+    --arg tag "$TAG" \
+    --arg name "Fractured $TAG" \
+    --arg body "Synced from GitHub Actions (Fractured)." \
+    --arg target "$TARGET" \
+    '{tag_name:$tag,name:$name,body:$body,draft:false,prerelease:false,target_commitish:$target}')
+  code=$(curl -sS -o "$REL_JSON" -w "%{http_code}" -X POST "${AUTH_H[@]}" \
+    -H "Content-Type: application/json" \
+    -d "$body" \
+    "$API/repos/${GITEA_OWNER}/${GITEA_REPO}/releases")
+  if [ "$code" != "201" ] && [ "$code" != "200" ]; then
+    echo "Gitea create release failed HTTP $code:" >&2
+    cat "$REL_JSON" >&2
+    if [ "$code" = "422" ] && jq -e '.message == "repo is empty"' "$REL_JSON" >/dev/null 2>&1; then
+      echo >&2
+      echo "Gitea does not allow releases on a repo with zero commits. Fix: push at least one commit" >&2
+      echo "to ${GITEA_OWNER}/${GITEA_REPO} (e.g. add README.md on branch ${TARGET} via web UI or git push)," >&2
+      echo "or set Actions variable GITEA_TARGET_REF to an existing default branch name." >&2
+    fi
+    exit 1
+  fi
+  rel_id=$(jq -r '.id' "$REL_JSON")
+else
+  echo "Gitea GET release by tag failed HTTP $code:" >&2
+  cat "$REL_JSON" >&2
+  exit 1
+fi
+
+if [ -z "$rel_id" ] || [ "$rel_id" = "null" ]; then
+  echo "Could not resolve Gitea release id" >&2
+  exit 1
+fi
+
+while read -r aid; do
+  [ -z "$aid" ] || [ "$aid" = "null" ] && continue
+  curl -fsS -X DELETE "${AUTH_H[@]}" \
+    "$API/repos/${GITEA_OWNER}/${GITEA_REPO}/releases/${rel_id}/assets/${aid}" || true
+done < <(jq -r '(.attachments // .assets // [])[] | .id' "$REL_JSON")
+
+shopt -s nullglob
+files=("$COMBINED_DIR"/*)
+if [ "${#files[@]}" -eq 0 ]; then
+  echo "No files in $COMBINED_DIR" >&2
+  exit 1
+fi
+
+for f in "${files[@]}"; do
+  [ -f "$f" ] || continue
+  echo "Uploading $(basename "$f") …"
+  curl -fsS -X POST "${AUTH_H[@]}" \
+    -F "attachment=@${f}" \
+    "$API/repos/${GITEA_OWNER}/${GITEA_REPO}/releases/${rel_id}/assets"
+done
+
+echo "Gitea release $TAG (id=$rel_id) updated with ${#files[@]} file(s)."