Refine reconciliation descriptions in documentation and tests for clarity on cash checks

README.md

@@ -101,7 +101,8 @@ An XTB report is an `.xlsx` file with a fixed layout:
   - `Cash Operations` — every cash flow: stock purchases/sales, deposits, withdrawals,
     dividends, dividend tax, free-funds interest, currency conversions. Each trade row
     carries a comment like `OPEN BUY 6 @ 301.50` or `CLOSE SELL 2 @ 100.00`, and the
-    sheet ends with a `Total` row (the broker-reported ending cash balance).
+    sheet ends with a `Total` row. That `Total` is the final cash left in the account,
+    not the value of stocks or ETFs.
 
 Two quirks the code handles explicitly:
 
@@ -278,7 +279,8 @@ The generated review HTML is a single offline file. It includes:
 - **Realized P/L** prefers the broker's `Closed Positions` `Profit/Loss` column; when that
   is absent, it falls back to **FIFO lot matching** from CLOSE trades.
 - **Cash flows** are categorized (deposits, withdrawals, interest, dividends, dividend tax,
-  FX fees, invested, proceeds) and reconciled against the broker's `Total` (ending cash).
+  FX fees, invested, proceeds). The report then checks whether its calculated ending cash
+  matches XTB's `Total` row, which is the final cash left in the account.
 - **Performance** combines **live market value** (or cost basis fallback) with cash to give
   portfolio value, total gain, total return %, money-weighted return (XIRR), and
   income yield. XIRR uses external deposits/withdrawals plus terminal portfolio
@@ -327,8 +329,9 @@ only used for inline `BUY`/`SELL` commissions. Pure-cash rows use the `$CASH-<CC
   table, and evolution chart. The methodology section lists every cost fallback ticker.
 - **Money-weighted return (XIRR)** requires at least one external cash outflow and
   one inflow. When the dated cash-flow series cannot be solved, the report shows `n/a`.
-- **Reconciliation** compares computed ending cash against the XTB `Total` row; it reports
+- **Reconciliation** checks whether the report's calculated ending cash matches XTB's
-  `[OK]` when they match within €0.01.
+  `Total` row. This is a cash check only: it does not compare the full value of the
+  portfolio. It reports `[OK]` when the two cash numbers match within €0.01.
 - **HTML interactions** (charts, sorting, filtering, sticky navigation) are all inline
   and offline; no CDN or network access is required to open the generated report.
 - Thousand-separators are intentionally **not** parsed in numeric fields (ambiguous with

skills/xtb-portfolio-review/scripts/main.py

@@ -1535,12 +1535,12 @@ TERM_TOOLTIPS = {
     "Pricing coverage": "How many holdings use live prices versus cost fallback values.",
     "Cost fallback tickers": "Tickers valued at cost because a trusted live price was unavailable. Their real market value may be higher or lower.",
     "Cost fallback positions": "Positions valued at cost because a trusted live price was unavailable. Their real market value may be higher or lower.",
-    "Reconciliation": "A check that computed ending cash matches the broker's reported cash total.",
+    "Reconciliation": "A check that the report's cash math matches the final cash amount shown by XTB.",
-    "Cash reconciliation": "A check that computed ending cash matches the broker's reported cash total.",
+    "Cash reconciliation": "A check that the report's cash math matches the final cash amount shown by XTB.",
-    "Computed ending cash": "Computed ending cash is the cash balance calculated from all cash operations in the report.",
+    "Computed ending cash": "The cash balance calculated by this report from deposits, withdrawals, trades, dividends, fees, and taxes.",
-    "Broker 'Total' (cash)": "Broker 'Total' (cash) is the cash total reported by XTB at the end of the Cash Operations sheet.",
+    "Broker 'Total' (cash)": "The final cash amount shown by XTB. This is cash left in the account, not the value of your stocks or ETFs.",
-    "Difference": "Difference shows computed cash minus broker-reported cash. A value near zero means the calculation reconciles.",
+    "Difference": "Computed cash minus XTB cash. A value close to zero means the cash movements were read correctly.",
-    "Status": "Status tells you whether the reconciliation check passed or needs attention.",
+    "Status": "Shows whether the cash check passed or whether the numbers need attention.",
     "Gross income": "Dividends plus interest before dividend tax.",
     "Dividend tax": "Tax withheld from dividend payments.",
     "Net income": "Income remaining after dividend tax.",
@@ -2085,7 +2085,7 @@ def build_html_report(
     <div class="card" id='reconciliation'>
       <h2>Reconciliation</h2>
       {_kv_table(recon_rows)}
-      <p class="muted">XTB "Total" row reflects ending free cash; reconciled against computed cash balance.</p>
+      <p class="muted">This check makes sure the report read your cash movements correctly. XTB's "Total" row is the cash left in your account at the end of the period, not the value of your stocks or ETFs. The report calculates the same cash balance from deposits, withdrawals, trades, dividends, fees, and taxes, then compares both numbers.</p>
     </div>
   </div>
 

skills/xtb-wealthfolio-export/scripts/main.py

@@ -1535,12 +1535,12 @@ TERM_TOOLTIPS = {
     "Pricing coverage": "How many holdings use live prices versus cost fallback values.",
     "Cost fallback tickers": "Tickers valued at cost because a trusted live price was unavailable. Their real market value may be higher or lower.",
     "Cost fallback positions": "Positions valued at cost because a trusted live price was unavailable. Their real market value may be higher or lower.",
-    "Reconciliation": "A check that computed ending cash matches the broker's reported cash total.",
+    "Reconciliation": "A check that the report's cash math matches the final cash amount shown by XTB.",
-    "Cash reconciliation": "A check that computed ending cash matches the broker's reported cash total.",
+    "Cash reconciliation": "A check that the report's cash math matches the final cash amount shown by XTB.",
-    "Computed ending cash": "Computed ending cash is the cash balance calculated from all cash operations in the report.",
+    "Computed ending cash": "The cash balance calculated by this report from deposits, withdrawals, trades, dividends, fees, and taxes.",
-    "Broker 'Total' (cash)": "Broker 'Total' (cash) is the cash total reported by XTB at the end of the Cash Operations sheet.",
+    "Broker 'Total' (cash)": "The final cash amount shown by XTB. This is cash left in the account, not the value of your stocks or ETFs.",
-    "Difference": "Difference shows computed cash minus broker-reported cash. A value near zero means the calculation reconciles.",
+    "Difference": "Computed cash minus XTB cash. A value close to zero means the cash movements were read correctly.",
-    "Status": "Status tells you whether the reconciliation check passed or needs attention.",
+    "Status": "Shows whether the cash check passed or whether the numbers need attention.",
     "Gross income": "Dividends plus interest before dividend tax.",
     "Dividend tax": "Tax withheld from dividend payments.",
     "Net income": "Income remaining after dividend tax.",
@@ -2035,7 +2035,7 @@ def build_html_report(
     <div class="card" id='reconciliation'>
       <h2>Reconciliation</h2>
       {_kv_table(recon_rows)}
-      <p class="muted">XTB "Total" row reflects ending free cash; reconciled against computed cash balance.</p>
+      <p class="muted">This check makes sure the report read your cash movements correctly. XTB's "Total" row is the cash left in your account at the end of the period, not the value of your stocks or ETFs. The report calculates the same cash balance from deposits, withdrawals, trades, dividends, fees, and taxes, then compares both numbers.</p>
     </div>
   </div>
 

test_portfolio.py

@@ -1306,10 +1306,11 @@ class TestHtmlReport:
         )
         assert "A ticker is the short code used by markets and brokers" in html
         assert "realized_pl means realized profit or loss" in html
-        assert "Computed ending cash is the cash balance calculated from all cash operations" in html
+        assert "cash balance calculated by this report from deposits, withdrawals, trades" in html
-        assert "Broker 'Total' (cash) is the cash total reported by XTB" in html
+        assert "cash left in the account, not the value of your stocks or ETFs" in html
-        assert "Difference shows computed cash minus broker-reported cash" in html
+        assert "Computed cash minus XTB cash" in html
-        assert "Status tells you whether the reconciliation check passed" in html
+        assert "whether the cash check passed" in html
+        assert "This check makes sure the report read your cash movements correctly" in html
 
 
 # ---------------------------------------------------------------------------