feat: add per-user avatar seed regeneration with irreversible random avatar replacement

Implement a new `avatar_seed` column on the users table that overrides the username-based seed for Multiavatar generation. Introduce a null-safe `avatar_seed(user)` choke point in `avatar.py` that resolves `user.get("avatar_seed") or user.get("username")`, registered as a Jinja global so every render site (`_avatar_link.html`, `avatar_url(...)` calls, SEO `og_image`, issues ad-hoc dicts, devRant payload/PNG) propagates a regenerated seed. Add `POST /profile/{username}/regenerate-avatar` endpoint (owner-or-admin only) that writes a fresh `generate_uid()` to `avatar_seed`, invalidates the target's user cache, and audits `profile.avatar.regenerate`. The previous seed is overwritten and never stored, making regeneration irreversible. Document the feature in `AGENTS.md` and `README.md`, add the API endpoint to `docs_api.py`, and include the `regenerate_avatar` Devii tool in `CONFIRM_REQUIRED`.

tests/unit/services/game/economy.py

@@ -157,3 +157,71 @@ def test_farm_score_handles_legacy_null_columns():
     assert economy.farm_score(
         {"xp": 50, "prestige": None, "perk_yield": None, "streak": None}
     ) == 50
+
+
+# --- legacy upgrades ---------------------------------------------------------
+
+
+def test_legacy_for_known_and_unknown():
+    assert economy.legacy_for("multiplier") is not None
+    assert economy.legacy_for("does_not_exist") is None
+
+
+def test_legacy_cost_grows_with_level():
+    up = economy.legacy_for("multiplier")
+    assert economy.legacy_cost(up, 0) == up.base_cost
+    assert economy.legacy_cost(up, 2) > economy.legacy_cost(up, 1)
+
+
+def test_legacy_multiplier_steps():
+    assert economy.legacy_multiplier(0) == 1.0
+    assert economy.legacy_multiplier(3) == 1 + economy.LEGACY_MULT_STEP * 3
+
+
+def test_stars_for_refactor_scales_with_level_and_prestige():
+    assert economy.stars_for_refactor(0, 0) == economy.STAR_BASE
+    assert economy.stars_for_refactor(10, 0) == economy.STAR_BASE + 2
+    assert economy.stars_for_refactor(0, 2) == economy.STAR_BASE + 2
+
+
+def test_prestige_base_plots_adds_legacy_plots():
+    assert economy.prestige_base_plots(0) == economy.STARTING_PLOTS
+    assert economy.prestige_base_plots(3) == economy.STARTING_PLOTS + 3
+
+
+# --- steal economy -----------------------------------------------------------
+
+
+def test_effective_steal_grace_extends_with_defense():
+    assert economy.effective_steal_grace(0) == economy.STEAL_GRACE_SECONDS
+    assert economy.effective_steal_grace(2) == (
+        economy.STEAL_GRACE_SECONDS + economy.LEGACY_DEFENSE_GRACE * 2
+    )
+
+
+def test_effective_steal_fraction_drops_with_defense_and_has_floor():
+    assert economy.effective_steal_fraction(0) == economy.STEAL_FRACTION
+    assert economy.effective_steal_fraction(2) < economy.STEAL_FRACTION
+    assert economy.effective_steal_fraction(99) >= 0.1
+
+
+def test_steal_reward_coins_is_a_fraction_of_harvest():
+    crop = economy.crop_for("shell")
+    full = economy.effective_reward_coins(crop)
+    stolen = economy.steal_reward_coins(crop)
+    assert 0 < stolen <= full
+
+
+# --- golden crops ------------------------------------------------------------
+
+
+def test_is_golden_deterministic_and_bounded():
+    first = economy.is_golden("plot-7", "2026-06-20T00:00:00+00:00")
+    second = economy.is_golden("plot-7", "2026-06-20T00:00:00+00:00")
+    assert first == second
+    assert isinstance(first, bool)
+
+
+def test_is_golden_requires_both_args():
+    assert economy.is_golden("", "2026-06-20T00:00:00+00:00") is False
+    assert economy.is_golden("plot-7", "") is False