Enhance portfolio review skill to conditionally generate CSV exports and update documentation for clarity

INSTALL_FOR_AGENTS.md

@@ -54,6 +54,9 @@ For portfolio review:
 /path/to/xtb-portfolio-review/scripts/run-review.sh /path/to/report.xlsx
 ```
 
+Append `--csv` to `run-review.sh` only when the user explicitly asks for the
+per-section CSV exports.
+
 For Wealthfolio export:
 
 ```bash

README.md

@@ -9,6 +9,76 @@ The parser is generic for XTB exports in this format. Tests generate a small
 synthetic workbook at runtime, while personal brokerage exports should stay
 local and untracked.
 
+## Quick Start
+
+### Use the skills in your own agent
+
+This is the recommended path if you want an LLM or coding agent to run the XTB
+workflows for you. Give your agent access to this repository and ask it to
+follow [`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md). That file tells the
+agent how to install or use the portable skill folders, validate them, and run
+the right workflow for your XTB workbook.
+
+Install prompt:
+
+```text
+Read https://github.com/farcasclaudiu/xtb-investment-tools/blob/main/INSTALL_FOR_AGENTS.md and install the XTB skills for your agent harness.
+```
+
+Portfolio review prompt examples:
+
+```text
+Use the XTB portfolio review skill to generate and verify a report for my XTB
+workbook.
+```
+
+```text
+Use the XTB portfolio review skill to generate the HTML report, export the CSV
+tables, and summarize the reconciliation status and data-quality caveats.
+```
+
+```text
+Use the XTB portfolio review skill with EUR_demo_report.xlsx as the input file.
+Generate the review, run validation, and report the generated output paths.
+```
+
+Wealthfolio export prompt examples:
+
+```text
+Use the XTB Wealthfolio export skill to create and validate a Wealthfolio CSV
+from my XTB workbook.
+```
+
+```text
+Use the XTB Wealthfolio export skill to inspect the generated CSV rows and tell
+me whether they are ready to import into Wealthfolio.
+```
+
+```text
+Use the XTB Wealthfolio export skill with EUR_demo_report.xlsx as the input file
+and write the Wealthfolio CSV to results/EUR_demo_report_wealthfolio.csv.
+```
+
+### Run the tools directly
+
+From the repository root:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install --upgrade pip
+.venv/bin/python -m pip install -r requirements.txt
+
+.venv/bin/python main.py path/to/xtb-report.xlsx
+.venv/bin/python exporter.py path/to/xtb-report.xlsx
+```
+
+Outputs are written to `results/`, including
+`results/<stem>_review.html` for the portfolio review and
+`results/<stem>_wealthfolio.csv` for the Wealthfolio import file. If there is
+exactly one `.xlsx` file in the current folder, both tools can auto-detect it
+when the path is omitted. Add `--csv` to the portfolio review command only when
+you want the extra per-section CSV exports.
+
 ---
 
 ## Background: the XTB export format

skills/xtb-portfolio-review/SKILL.md

@@ -16,7 +16,8 @@ Use this skill to run and assess XTB portfolio reviews from a copied skill folde
    `<skill-folder>/scripts/validate-review.sh`
 4. Generate the review from the directory where outputs should be written:
    `<skill-folder>/scripts/run-review.sh <report.xlsx>`
-5. Inspect `results/` outputs named from the workbook stem, especially `_review.html`, `_holdings.csv`, `_cash_flows.csv`, `_performance.csv`, `_income.csv`, and `_evolution.csv`.
+   Add `--csv` only when the user explicitly asks for CSV exports.
+5. Inspect the `results/<stem>_review.html` output. If CSV export was requested, also inspect outputs named from the workbook stem, especially `_holdings.csv`, `_cash_flows.csv`, `_performance.csv`, `_income.csv`, and `_evolution.csv`.
 6. Check whether computed ending cash reconciles to the broker `Total` row within EUR/USD/etc. `0.01`.
 7. Report findings with caveats: cost-priced tickers, missing live prices, cash mismatch, XIRR availability, concentration, income tax drag, and any generated file paths.
 
@@ -25,7 +26,7 @@ Use this skill to run and assess XTB portfolio reviews from a copied skill folde
 - `scripts/main.py`: standalone XTB portfolio review generator.
 - `scripts/html_charts.py`: offline Chart.js report rendering helper.
 - `scripts/assets/chartjs.umd.min.js`: vendored Chart.js bundle for self-contained HTML.
-- `scripts/run-review.sh`: shell wrapper that runs the bundled review tool with `--csv`.
+- `scripts/run-review.sh`: shell wrapper that runs the bundled review tool. It writes only the HTML report by default; pass `--csv` to also write CSV outputs.
 - `scripts/validate-review.sh`: dependency and asset smoke check.
 - `scripts/setup-env.sh`: creates `.venv` in the current working directory and installs dependencies.
 - `scripts/requirements.txt`: Python dependencies.
@@ -38,5 +39,5 @@ Use this skill to run and assess XTB portfolio reviews from a copied skill folde
 ## Guardrails
 
 - Do not treat the generated report as investment advice; describe what the tool computed and the data-quality limits.
-- Prefer the bundled validation script and generated CSVs over eyeballing the HTML alone.
+- Prefer the bundled validation script and generated outputs over eyeballing the HTML alone.
 - Preserve offline/self-contained HTML behavior; do not introduce CDN dependencies when modifying the report.

skills/xtb-portfolio-review/scripts/run-review.sh

@@ -10,4 +10,4 @@ else
   PYTHON_BIN="python3"
 fi
 
-exec "$PYTHON_BIN" "$SCRIPT_DIR/main.py" "$@" --csv
+exec "$PYTHON_BIN" "$SCRIPT_DIR/main.py" "$@"

test_portfolio.py

@@ -1,3 +1,5 @@
+import os
+import subprocess
 import warnings
 
 import pandas as pd
@@ -827,6 +829,42 @@ class TestSyntheticReport:
         assert holdings["allocation_pct"].sum() == pytest.approx(100.0, abs=0.05)
 
 
+# ---------------------------------------------------------------------------
+# Bundled script wrappers
+# ---------------------------------------------------------------------------
+class TestPortfolioReviewWrapper:
+    def test_run_review_does_not_generate_csv_unless_requested(self, tmp_path):
+        calls_file = tmp_path / "python-args.txt"
+        fake_python = tmp_path / "fake-python.sh"
+        fake_python.write_text(
+            "#!/usr/bin/env bash\n"
+            "printf '%s\\n' \"$@\" > \"$CALLS_FILE\"\n",
+            encoding="utf-8",
+        )
+        fake_python.chmod(0o755)
+
+        env = os.environ | {"PYTHON": str(fake_python), "CALLS_FILE": str(calls_file)}
+        subprocess.run(
+            ["skills/xtb-portfolio-review/scripts/run-review.sh", "EUR_demo_report.xlsx"],
+            check=True,
+            env=env,
+        )
+        default_args = calls_file.read_text(encoding="utf-8").splitlines()
+        assert "--csv" not in default_args
+
+        subprocess.run(
+            [
+                "skills/xtb-portfolio-review/scripts/run-review.sh",
+                "EUR_demo_report.xlsx",
+                "--csv",
+            ],
+            check=True,
+            env=env,
+        )
+        explicit_args = calls_file.read_text(encoding="utf-8").splitlines()
+        assert "--csv" in explicit_args
+
+
 # ---------------------------------------------------------------------------
 # HTML report
 # ---------------------------------------------------------------------------