# FenixAI v2.5.0 Release

Status: local preparation only, not published.

FenixAI v2.5 is a release-candidate cleanup focused on live/paper reliability, NanoFenix integration, and clearer English release documentation. This version should still be treated as experimental trading software and tested in paper mode before any live deployment.

For the long-form history of what changed after v2.0 and why those changes were made, see
[`v2.5-development-history.md`](./v2.5-development-history.md).

For the public guide to the new v2.5 systems, including NanoFenix, MiniFenix, Fenix Experimental, model-role teams, and live slot runners, see
[`v2.5-new-systems.md`](./v2.5-new-systems.md).

For the script-by-script evolution map, including the v25 and v31 live-safe launcher lineage and which scripts belong in the public release surface, see
[`v2.5-script-evolution.md`](./v2.5-script-evolution.md).

## Release goals

- Reduce false confidence from paper/live mismatches.
- Make live execution state recover more safely after restarts.
- Improve NanoFenix behavior in noisy real-market conditions.
- Prepare public-facing documentation in English.
- Keep internal run artifacts and private live-test notes out of the release surface.
- Be explicit about mixed live canary results instead of presenting v2.5 as a proven-profit release.

## Trading and execution changes

- Paper/hybrid execution now rejects invalid prices instead of opening positions with missing or zero-price data.
- Paper trade sizing now uses `FENIX_BALANCE_FALLBACK_USDT` directly instead of querying the live executor balance path, preventing zero-balance paper runs from silently skipping otherwise actionable simulated entries.
- Live engine startup hydrates an already-open exchange position so a restart does not assume the account is flat when Binance still has exposure.
- Failed execution attempts are no longer counted as realized risk-manager trading losses.
- Protective-order verification checks open algorithmic orders, not only standard open orders.
- The hybrid runner supports staged TP/SL levels with partial closes at TP1 and TP2, then full close at TP3.
- Live entries can reconcile stale local state before opening a fresh trade if Binance is already flat.
- Opposite-signal live exits now execute/reconcile exchange-side reduce-only exits before recording local close state.
- Margin-aware notional caps and exchange minimum-quantity flooring reduce oversized or invalid live orders on small accounts.
- Live slot accounting now treats an exchange-hydrated position as valid opening context, so a safe reduce-only close of inherited exposure no longer creates a false `completed_with_accounting_gap` summary.
- Timed paper and testnet slots now isolate runtime-risk state with per-slot `FENIX_RISK_MANAGER_STORAGE_PATH` files, preventing paper release tests from inheriting prior live PnL.
- Long paper suite plans now pass lite/MTF guard options explicitly into `run_fenix_live_slot.py`, including `technical_mtf_qabba_guard`, strict MTF timeframe, confirmation thresholds, and timeout settings.
- The lite MTF guard now records a clear reason when strict-MTF context is unavailable instead of leaving `_mtf_bias` empty.
- Technical timeout/error fallbacks can no longer act as a clean Technical HOLD for the optional MTF+QABBA entry path.
- GARCH convergence warnings from optional technical indicators are suppressed through the supported `arch` fit option, keeping release-run logs focused on actionable failures.

## NanoFenix changes

- NanoFenix keeps adaptive dual-horizon fusion instead of requiring rigid short/long agreement.
- Companion signal output remains enabled so NanoFenix can inform Fenix without becoming a single point of decision.
- Trailing stops now estimate fees before treating a trailing exit as acceptable.
- `MIN_TRAILING_NET_PCT` adds a configurable net-profit floor for trailing exits.
- Runtime and signal state remain local and scoped by symbol/timeframe.
- Companion policy now exposes uncertainty, net actionable edge, calibration health, and sizing hints to help Fenix distinguish direction from tradable edge.

## MiniFenix and experimental systems

- MiniFenix is now documented as the slow-brain/fast-trigger research prototype that informed NanoFenix and short-timeframe engine work.
- `fenix_experimental/` is documented as the bridge between Fenix agent snapshots and fast-trigger paper execution.
- Optional Web3 Intelligence code is documented as an experimental path, not a default public dependency.
- Model-role teams are documented as a v2.5 pattern so Technical, QABBA, Visual, Decision, and Risk can use different models.

## Documentation changes

- Public changelog now includes an unreleased v2.5 section.
- NanoFenix changelog has been translated to English.
- MiniFenix README has been translated to English and marked as a research prototype.
- Runtime comments/docstrings in the hybrid runner and adaptive fusion module have been translated to English where they affect maintainability.
- A v2.5 release checklist has been added for local validation before publishing.
- `scripts/README.md` now separates recommended v2.5 entry points from analysis tools, maintenance helpers, fixes, generated files, and historical launchers.
- `docs/releases/v2.5-script-evolution.md` documents how the recent v25/v31 live-safe scripts evolved and which launchers should be considered current, historical, internal, or experimental.
- The May 2026 SOLUSDT v31 canary is documented as a safety/observability result: 26 live cycles, no new entries, one inherited position closed through exchange-side reduce-only reconciliation, and no remaining exchange exposure.
- The May 2026 short v2.5 release paper suite is documented as an execution/observability check: 5/5 SOLUSDT paper slots completed OK across 1m, 3m, 5m, 15m, and 30m, with no simulated trades, clean risk state, and one NanoFenix hard veto on the only BUY signal.
- The later May 2026 long MTF/NanoFenix paper suite is documented as a regression target: it completed 6/6 slots, but exposed the zero-balance paper sizing defect that blocked simulated fills despite multiple SELL decisions.
- The May 22 follow-up long suite is documented separately: the paper sizing defect did not recur, but every decision was HOLD because the suite runner had not carried explicit strict-MTF settings, leaving `_mtf_bias` empty. The May 24 runner fix makes that configuration explicit for the next soak.

## Verification targets

Before publishing v2.5, run at minimum:

```bash
pytest tests/test_hybrid_runner.py tests/test_engine_position_management.py tests/test_executor_clamp.py tests/test_nanofenixv3_executor.py tests/test_run_fenix_live_slot.py tests/test_lite_pipeline_parallelism.py tests/test_technical_tools_stochastic.py -q
python -m py_compile scripts/run_hybrid_live_paper.py scripts/run_fenix_live_slot.py scripts/run_fenix_live_suite.py nanofenixv3/adaptive_fusion.py nanofenixv3/executor.py run_nanofenixv3.py src/trading/engine.py src/trading/market_data.py src/tools/technical_tools.py
```

For an official release, also run:

```bash
pytest -q
ruff check src scripts nanofenixv3
```

## Open release blockers

- Rerun a longer paper/testnet soak with the explicit MTF suite fields active. The latest post-sizing-fix run completed without zero-balance skips, but did not validate fills because strict-MTF context was not actually configured by the suite runner.
- Confirm no private API keys, account identifiers, or local-only artifacts are included in public docs.
- Decide whether old Spanish analysis reports should remain archived, be translated, or be excluded from the v2.5 package.
- Re-test the bot on at least one trending and one ranging market session before publishing.
- Review `docs/releases/v2.5-development-history.md` for public tone and remove any private operational detail before publishing.
- Review `docs/releases/v2.5-new-systems.md` against the actual release surface before publishing.
- Review `docs/releases/v2.5-script-evolution.md` and confirm no account-specific live canary details should be removed before publishing.
- Review `scripts/README.md` against the actual release package before publishing.
