Reorganize CLI help text and command grouping for data/execution clarity (#85)

* feat: clarify CLI/docs scope as generic MT5 data and execution infrastructure

- Update app help text and module docstring to describe mt5cli as MT5 data
  and execution utilities rather than export-only tooling
- Group CLI commands under rich_help_panel sections: Data / Export, Execution,
  and Collection; command names are unchanged for compatibility
- Expand order-send docstring to explicitly flag it as the expert raw-request
  live-trading path; preserve --yes gate
- Split docs/index.md Trading section into "Trading State" (read-only) and
  "Execution (live / mutating)" with close-positions now documented
- Add TestHelpText tests verifying top-level panel grouping, order-send
  expert/live language, and close-positions safety gate coverage

Closes #78

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018yH6esaqc5D1cmo1dK2Ur9

* chore: trim trailing whitespace in docs/index.md table

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018yH6esaqc5D1cmo1dK2Ur9

* chore: bump version to 1.0.1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018yH6esaqc5D1cmo1dK2Ur9

* chore: update uv.lock for version 1.0.1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018yH6esaqc5D1cmo1dK2Ur9

* fix: address review feedback on CLI/docs scope PR

- Remove dead help invocation in test_order_send_help_mentions_expert_and_raw
  (the result was immediately overwritten by result2)
- Strengthen assertion from `or` to `and`; both "raw" and "expert" are present
  in the docstring so disjunction masked a potential regression
- Split into two `assert` statements to satisfy PT018 (ruff)
- Fix docs/index.md inaccuracy: order-check has no --yes gate; clarify that
  only order-send and close-positions require confirmation for live execution
- Move order-check from "Execution" rich_help_panel to "Data / Export" so the
  Execution panel name is truthful (order-check is read-only)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018yH6esaqc5D1cmo1dK2Ur9

* docs: move order-check out of Execution section into Trading State

order-check is read-only and now lives in the CLI's Data / Export panel,
so documenting it under "Execution (live / mutating)" was inconsistent.
Moved it to the Trading State table. The Execution section now only lists
order-send and close-positions, both of which require --yes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018yH6esaqc5D1cmo1dK2Ur9

---------

Co-authored-by: Claude <noreply@anthropic.com>

README.md

@@ -29,25 +29,29 @@ Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data han
 pip install -U mt5cli MetaTrader5
 ```
 
+Parquet export is not included by default. To enable it, install the `parquet` extra:
+
+```bash
+pip install -U "mt5cli[parquet]" MetaTrader5
+```
+
 ## Python API (downstream packages)
 
-Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives. `Mt5CliClient` remains available as a backward-compatible alias.
+Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.
 
 ```python
 from datetime import UTC, datetime
 from pathlib import Path
 
 from mt5cli import (
-    DataKind,
-    Dataset,
     MT5Client,
     build_config,
     collect_history,
-    export_dataframe,
     mt5_session,
-    normalize_dataframe,
     update_history_with_config,
 )
+from mt5cli.schemas import DataKind, normalize_dataframe
+from mt5cli.utils import Dataset, export_dataframe
 
 # Persistent session for multiple calls
 with mt5_session(build_config(login=12345, server="Broker-Demo")) as client:
@@ -83,7 +87,7 @@ update_history_with_config(
 )
 ```
 
-Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Storage helpers are re-exported from `mt5cli.storage` and the package root.
+Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Export and storage helpers are in `mt5cli.utils` (`Dataset`, `export_dataframe`) and `mt5cli.history`.
 
 `MT5Client.order_send()` is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly.
 
@@ -92,16 +96,21 @@ Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `norma
 Trading applications can depend on `mt5cli` imports only; terminal path,
 credentials, server, and timeout are forwarded to `pdmt5.Mt5Config`, numeric
 login strings are coerced to integers, and empty login strings are treated as
-unset.
+unset. Pass `allow_whole_dollar_env=True` to expand `${ENV_VAR}` and bare
+`$ENV_NAME` placeholders in connection string parameters before coercion.
 
 ```python
 from mt5cli import (
+    build_config,
     calculate_spread_ratio,
     create_trading_client,
     get_account_snapshot,
     mt5_trading_session,
 )
 
+# Login from environment — numeric string is coerced to int automatically
+config = build_config(login="$MT5_LOGIN", allow_whole_dollar_env=True)
+
 with mt5_trading_session(
     path=r"C:\Program Files\MetaTrader 5\terminal64.exe",
     login="12345",
@@ -173,10 +182,13 @@ python -m mt5cli -o account.csv account-info
 | `recent-history-deals` | Export historical deals from a recent trailing window                                                        |
 | `mt5-summary`          | Export terminal/account status summary                                                                       |
 | `order-check`          | Check funds sufficiency for a trade request                                                                  |
-| `order-send`           | Send a trade request to the trade server (`--yes` required)                                                  |
+| `order-send`           | Send a raw trade request to the trade server (`--yes` required; expert path)                                 |
+| `close-positions`      | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` available)          |
 | `collect-history`      | Bundle rates, ticks, history-orders, and history-deals for one or more symbols into a single SQLite database |
 
 Use `order-check` to validate a request payload before running `order-send --yes`.
+`close-positions` is the safer high-level alternative that builds correct close
+requests automatically. At least one `--symbol` or `--ticket` must be provided.
 
 ### `collect-history`
 
@@ -198,7 +210,8 @@ For automated pipelines, use the importable incremental API instead of re-fetchi
 
 ```python
 from pdmt5 import Mt5Config, Mt5DataClient
-from mt5cli import Dataset, update_history, update_history_with_config
+from mt5cli import update_history, update_history_with_config
+from mt5cli.utils import Dataset
 
 # Reuse an already-connected pdmt5 client (does not open/close MT5)
 client = Mt5DataClient(config=Mt5Config(login=12345))
@@ -233,7 +246,7 @@ update_history_with_config(
 - **Rate view resolution**: use `resolve_rate_view_name()` / `resolve_rate_view_names()` to map symbols and granularities to existing SQLite compatibility views without creating databases. Both accept `None` (or a missing path) and return deterministic default names unless `require_existing=True`.
 - **Rate view loading**: use `load_rate_data()` / `load_rate_data_from_connection()` to load a SQLite rate table or view into a `DatetimeIndex` DataFrame.
 - **Multi-series rate loading**: use `build_rate_targets()` to build neutral `RateTarget(symbol, timeframe)` pairs, `resolve_rate_tables()` to map them to table/view names (pass `require_existing=True` for strict resolution), and `load_rate_series_from_sqlite()` to load them into a mapping keyed by `(symbol, integer timeframe)`. The loader requires existing managed views unless `explicit_tables` is supplied, and rejects duplicate `(symbol, timeframe)` targets.
-- **Multi-account latest rates**: use `collect_latest_rates_for_accounts()` with `AccountSpec` to read the latest bars for several account groups, merged into a `(symbol, integer timeframe)` mapping. For long-running pollers, `collect_latest_rates_for_accounts_with_retries()` adds bounded exponential backoff that retries only `pdmt5.Mt5TradingError` / `pdmt5.Mt5RuntimeError` and re-raises once `retry_count` is exhausted.
+- **Multi-account latest rates**: use `collect_latest_rates_for_accounts()` with `AccountSpec` to read the latest bars for several account groups, merged into a `(symbol, integer timeframe)` mapping. For long-running pollers, `collect_latest_rates_for_accounts_with_retries()` adds bounded exponential backoff that retries only recoverable MT5 errors and re-raises once `retry_count` is exhausted.
 - **Latest closed bars**: use `collect_latest_closed_rates_for_accounts()` when downstream logic must exclude the still-forming current bar. It fetches `count + 1` bars at `start_pos=0`, drops the last row with `drop_forming_rate_bar()`, and validates each series is non-empty. `collect_latest_closed_rates_by_granularity()` returns the same data keyed by `(symbol, granularity_name)` such as `("EURUSD", "M1")`.
 
 ```python
@@ -248,9 +261,9 @@ rates = collect_latest_closed_rates_by_granularity(
 eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 ```
 
-- **Credential resolution**: use `resolve_account_spec()` / `resolve_account_specs()` to merge explicit override values over `AccountSpec` fields and expand `${ENV_VAR}` placeholders (via `substitute_env_placeholders()`), raising `ValueError` for missing variables. This keeps secrets out of plan/config files without coupling to any strategy code.
+- **Credential resolution**: use `resolve_account_spec()` / `resolve_account_specs()` to merge explicit override values over `AccountSpec` fields and expand `${ENV_VAR}` placeholders (via `substitute_env_placeholders()`), raising `ValueError` for missing variables. This keeps secrets out of plan/config files without coupling to any strategy code. For config dicts or nested structures loaded from YAML/TOML, use `substitute_mapping_values(data, keys={"login", "password"})` to expand placeholders only for caller-specified keys — key names are never hard-coded in mt5cli.
 - **Throttled history updates**: use `ThrottledHistoryUpdater` to wrap `update_history()` with a minimum `interval_seconds` between successful runs (monotonic clock). Call `should_update()` / `update(client, symbols)` from an application loop; errors propagate by default, or pass `suppress_errors=True` to swallow recoverable `Mt5*Error`, `sqlite3.Error`, `ValueError`, `OSError`, and MT5 client capability errors for history API methods without advancing the throttle (other `AttributeError` / `TypeError` values always propagate). Pass `update_backend` to inject a custom history update callable (same keyword arguments as `update_history`) instead of monkey-patching `mt5cli.sdk.update_history`.
-- **Trading session helpers**: use `mt5_trading_session()` for a trading-capable `pdmt5.Mt5TradingClient` that initializes/logs in via `Mt5Config.path` and always shuts down safely. Pair with `detect_position_side()`, `calculate_margin_and_volume()`, and `determine_order_limits()` for generic position and sizing utilities. The read-only `mt5_session()` / `Mt5CliClient` SDK is unchanged.
+- **Trading session helpers**: use `mt5_trading_session()` for a trading-capable client that initializes/logs in via `Mt5Config.path` and always shuts down safely. Pair with `detect_position_side()`, `calculate_margin_and_volume()`, and `determine_order_limits()` for generic position and sizing utilities. Keep read-only collection on `mt5_session()` / `MT5Client`.
 - **Granularity-keyed rate loading**: `load_rate_series_by_granularity()` builds targets with `build_rate_targets()`, loads them with `load_rate_series_from_sqlite()`, and returns a mapping keyed by `(symbol | None, granularity_name)` such as `("EURUSD", "M1")` to reduce downstream boilerplate.
 - **MT5 session helper**: use the `mt5_session()` context manager to attach to (or, when `Mt5Config.path` is set, launch) an MT5 terminal, log in, and yield a connected `MT5Client` that shuts down on exit.
 - **SQLite export helpers**: use `export_dataframe_to_sqlite()` for append mode, optional index export, and post-write deduplication by key columns.
@@ -317,7 +330,7 @@ finally:
     client.shutdown()
 ```
 
-Read-only collectors can keep using `mt5_session()` and `MT5Client` (or the `Mt5CliClient` alias) without changes.
+Read-only collectors can keep using `mt5_session()` and `MT5Client`.
 
 ## Development
 

docs/api/history.md

@@ -182,12 +182,14 @@ targets without hard-coding view names:
 from pathlib import Path
 
 from mt5cli import (
-    load_rate_data,
     load_rate_series_by_granularity,
     load_rate_series_from_sqlite,
-    resolve_rate_table_name,
 )
-from mt5cli.history import resolve_rate_view_name
+from mt5cli.history import (
+    load_rate_data,
+    resolve_rate_table_name,
+    resolve_rate_view_name,
+)
 
 view = resolve_rate_view_name(Path("history.db"), "EURUSD", "M1", require_existing=True)
 rates = load_rate_data(Path("history.db"), view, count=1000)

docs/api/index.md

@@ -13,7 +13,6 @@ responsibilities.
 | [Public API Contract](public-contract.md) | Stable downstream SDK exports, CLI boundary, and out-of-scope items       |
 | [Client](client.md)                       | `MT5Client` session abstraction for data access and order primitives      |
 | [Schemas](schemas.md)                     | Canonical DataFrame contracts and normalization helpers                   |
-| [Storage](storage.md)                     | CSV/JSON/Parquet/SQLite export and history collection helpers             |
 | [Converters](converters.md)               | Symbol, timeframe, timezone, and date-range utilities                     |
 | [Exceptions](exceptions.md)               | Stable mt5cli exception types and MT5 error normalization                 |
 | [SDK](sdk.md)                             | Module-level fetch helpers, multi-account collectors, incremental history |
@@ -30,15 +29,14 @@ flowchart TD
     CLI["mt5cli CLI"] --> Client
     Client --> SDK["sdk / pdmt5"]
     Client --> Schemas["schemas"]
-    Storage["storage"] --> History["history SQLite"]
-    Storage --> Utils["utils export"]
+    History["history SQLite"] --> Utils["utils export"]
     SDK --> PDMT5["pdmt5.Mt5DataClient"]
 ```
 
 Downstream packages should depend on the package root exports documented in the
 [Public API Contract](public-contract.md) (`MT5Client`,
-`DataKind`, `normalize_dataframe`, `collect_history`, `load_rate_data`,
-`resolve_rate_view_name`, etc.) rather than private modules.
+`collect_history`, `load_rate_series_from_sqlite`, etc.) rather than private
+modules. Lower-level helpers are accessible directly from their owning modules.
 
 `MT5Client.order_send()` is a live execution primitive that can place real trades. mt5cli exposes minimal execution helpers only; strategy logic, signals, backtests, and optimization remain out of scope and must be implemented downstream with explicit execution gating.
 

docs/api/public-contract.md

@@ -1,61 +1,53 @@
 # Public API Contract
 
-mt5cli is the generic MT5 data and execution infrastructure layer for downstream
-Python applications. The intended dependency direction is:
+mt5cli is the canonical operational trading SDK and CLI/batch layer over pdmt5.
+The intended dependency direction is:
 
 ```text
 downstream app -> mt5cli -> pdmt5 -> MetaTrader 5
 ```
 
+## Responsibility boundary
+
+| Layer          | Owns                                                                                                                                                                               |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **pdmt5**      | MT5 core wrapper; DataFrame/dict conversion; canonical MT5 constants and parsers; direct low-level order primitives                                                                |
+| **mt5cli**     | CLI/batch workflows; SQLite history collection; normalized datasets; closed-bar helpers; small downstream operational SDK; generic broker-facing margin/volume/order orchestration |
+| **downstream** | Strategy logic; signals; risk policy; backtesting; optimization; YAML/application semantics                                                                                        |
+
+Downstream code should import raw pdmt5 types and constants (such as
+`Mt5Config`, `Mt5RuntimeError`, `TIMEFRAME_MAP`, `COPY_TICKS_MAP`) directly
+from `pdmt5` when needed. mt5cli does not serve as a pass-through compatibility
+namespace for pdmt5. mt5cli's trading helpers type their client parameter against
+an internal protocol backed by `pdmt5.Mt5DataClient`; `Mt5TradingClient` is no
+longer required. `Mt5TradingError` is conditionally imported where still present
+in pdmt5, but mt5cli raises `Mt5OperationError` for all trading-related failures.
+
+Note: the former `mt5cli` re-export `TICK_FLAG_MAP` corresponds to `COPY_TICKS_MAP`
+in pdmt5 — the name changed, it was not simply moved.
+
 Downstream packages should import from the package root (`from mt5cli import
-...`) and treat the symbols listed below as the stable SDK contract. CLI
-commands mirror the same behavior but are not importable Python APIs.
+...`). The contract set `STABLE_SDK_EXPORTS` in `mt5cli.contract` enumerates
+every package-root symbol. Lower-level helpers (schema utilities, export
+functions, parser helpers, low-level MT5 wrappers) are available directly from
+their owning modules (`mt5cli.schemas`, `mt5cli.utils`, `mt5cli.converters`,
+`mt5cli.sdk`, etc.) and are not part of the root SDK surface.
 
 ## Stable downstream SDK API
 
-These names are exported from `mt5cli` and covered by the contract in
-`mt5cli.STABLE_SDK_EXPORTS` (defined in `mt5cli.contract`). Prefer `MT5Client` over the legacy `Mt5CliClient`
-alias for new code.
+These names are exported from `mt5cli` and enumerated in
+`mt5cli.STABLE_SDK_EXPORTS` (defined in `mt5cli.contract`).
 
 ### Session lifecycle and configuration
 
-| Symbol                                          | Role                                                                                                       |
-| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `MT5Client`, `Mt5CliClient`                     | Read-only data client with optional `order_check` / `order_send`                                           |
-| `build_config`                                  | Build `pdmt5.Mt5Config` from connection fields                                                             |
-| `mt5_session`                                   | Context manager: initialize, login, yield client, shutdown                                                 |
-| `create_trading_client`, `mt5_trading_session`  | Trading-capable `pdmt5.Mt5TradingClient` lifecycle                                                         |
-| `AccountSpec`                                   | Generic account group: symbols plus optional credentials                                                   |
-| `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders; opt-in `allow_whole_dollar_env` for bare `$NAME`     |
-| `substitute_env_placeholders`                   | Replace `${NAME}` substrings from the environment; opt-in `allow_whole_dollar_env` for whole-value `$NAME` |
-
-Credential resolution is generic: any environment variable name may appear inside
-`${...}`. mt5cli does not hard-code application-specific keys such as
-`mt5_login` or `mt5_exe`.
-
-Pass `allow_whole_dollar_env=True` to `substitute_env_placeholders()`,
-`resolve_account_spec()`, `resolve_account_specs()`, and `build_config()` to
-additionally expand strings whose entire value is a bare `$ENV_NAME` identifier.
-Partial strings such as `"plan$pass"`, `"abc$ENV"`, or `"$ENV-suffix"` are
-**never** expanded — only an exact `$IDENTIFIER` whole-string match qualifies.
-Default is `False` to preserve backward compatibility.
-
-### Read-only MT5 data access
-
-Module-level helpers open a transient connection per call. Prefer `mt5_session`
-or `MT5Client` when making many requests in one process.
-
-| Area                 | Symbols                                                                                              |
-| -------------------- | ---------------------------------------------------------------------------------------------------- |
-| Rates                | `copy_rates_from`, `copy_rates_from_pos`, `copy_rates_range`, `latest_rates`, `collect_latest_rates` |
-| Ticks                | `copy_ticks_from`, `copy_ticks_range`, `recent_ticks`                                                |
-| Account / terminal   | `account_info`, `terminal_info`, `mt5_version`, `last_error`, `mt5_summary`, `mt5_summary_as_df`     |
-| Symbols / market     | `symbols`, `symbol_info`, `symbol_info_tick`, `market_book`, `minimum_margins`                       |
-| Trading state (read) | `orders`, `positions`, `history_orders`, `history_deals`, `recent_history_deals`                     |
-
-Use `mt5_version` for MetaTrader 5 terminal version data. The name `version` at
-the package root refers to `importlib.metadata.version` (package metadata), not
-the MT5 SDK helper.
+| Symbol                                          | Role                                                                                                                                                                                                                                                                              |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MT5Client`                                     | Read-only data client with optional `order_check` / `order_send`                                                                                                                                                                                                                  |
+| `build_config`                                  | Build `pdmt5.Mt5Config` from connection fields; `login` accepts `int \| str \| None` — numeric strings are coerced to `int`, blank strings are treated as unset, and `${ENV_VAR}` / `$ENV_NAME` placeholders in string parameters are expanded when `allow_whole_dollar_env=True` |
+| `mt5_session`                                   | Context manager: initialize, login, yield client, shutdown                                                                                                                                                                                                                        |
+| `create_trading_client`, `mt5_trading_session`  | Trading-capable MT5 client lifecycle; returns a client supporting order execution and account management                                                                                                                                                                          |
+| `AccountSpec`                                   | Generic account group: symbols plus optional credentials                                                                                                                                                                                                                          |
+| `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders; opt-in `allow_whole_dollar_env` for bare `$NAME`                                                                                                                                                                            |
 
 ### Closed-bar rate helpers
 
@@ -67,29 +59,21 @@ timestamp normalization in downstream apps.
 | ------------------------------------------------ | ------------------------------------------------------------------------------- |
 | `drop_forming_rate_bar`                          | Remove the last row from chronologically ordered rate data                      |
 | `fetch_latest_closed_rates`                      | Single connected client: fetch `count + 1`, drop forming bar                    |
-| `fetch_latest_closed_rates_for_trading_client`   | Closed bars from an active `Mt5TradingClient` session; returns RangeIndex       |
+| `fetch_latest_closed_rates_for_trading_client`   | Closed bars from an active trading client session; returns RangeIndex           |
 | `fetch_latest_closed_rates_indexed`              | Same as above but returns a UTC `DatetimeIndex` named `"time"` (no time column) |
 | `collect_latest_closed_rates_for_accounts`       | Multi-account closed bars with optional retry wrapper                           |
 | `collect_latest_closed_rates_by_granularity`     | Same data keyed by `(symbol, granularity_name)`                                 |
-| `collect_latest_rates_for_accounts`              | Latest bars including the forming bar when `start_pos=0`                        |
 | `collect_latest_rates_for_accounts_with_retries` | Bounded exponential backoff for transient MT5 errors                            |
 
 ### SQLite history collection and rate loading
 
-| Symbol                                                                                                                        | Role                                                                                         |
-| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `collect_history`                                                                                                             | One-shot date-range export into SQLite                                                       |
-| `update_history`, `update_history_with_config`                                                                                | Incremental append from `MAX(time)` cursors                                                  |
-| `ThrottledHistoryUpdater`                                                                                                     | Minimum interval between successful incremental updates; optional `update_backend` injection |
-| `resolve_history_datasets`, `resolve_history_timeframes`, `resolve_history_tick_flags`                                        | History pipeline configuration                                                               |
-| `build_rate_view_name`, `resolve_rate_table_name`, `resolve_rate_view_name`, `resolve_rate_view_names`, `resolve_rate_tables` | Map symbols/timeframes to mt5cli-managed table or view names                                 |
-| `RateTarget`, `build_rate_targets`                                                                                            | Neutral `(symbol, timeframe)` series descriptors                                             |
-| `load_rate_data`, `load_rate_data_from_connection`                                                                            | Load one table/view into a time-indexed DataFrame                                            |
-| `load_rate_series_from_sqlite`, `load_rate_series_by_granularity`                                                             | Load one or many series; fail clearly when managed views are missing                         |
-
-Pass `require_existing=True` to rate view resolution helpers when downstream
-code must fail instead of receiving a best-guess view name. Multi-series loaders
-require existing managed `rate_*__*` views unless `explicit_tables` is supplied.
+| Symbol                                                            | Role                                                                                         |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `collect_history`                                                 | One-shot date-range export into SQLite                                                       |
+| `update_history`, `update_history_with_config`                    | Incremental append from `MAX(time)` cursors                                                  |
+| `ThrottledHistoryUpdater`                                         | Minimum interval between successful incremental updates; optional `update_backend` injection |
+| `RateTarget`, `build_rate_targets`                                | Neutral `(symbol, timeframe)` series descriptors                                             |
+| `load_rate_series_from_sqlite`, `load_rate_series_by_granularity` | Load one or many series; fail clearly when managed views are missing                         |
 
 See [History Collection (SQLite)](history.md) for schema, view naming, and ER
 diagrams.
@@ -99,23 +83,38 @@ diagrams.
 These helpers implement broker-facing calculations only. They do not encode
 strategy entries, exits, Kelly sizing, or signal logic.
 
-| Symbol                                                                                             | Role                                          |
-| -------------------------------------------------------------------------------------------------- | --------------------------------------------- |
-| `get_account_snapshot`, `get_symbol_snapshot`, `get_tick_snapshot`, `get_positions_frame`          | Normalized account/symbol/tick/position views |
-| `detect_position_side`                                                                             | Net long / short / flat from open positions   |
-| `calculate_spread_ratio`                                                                           | Relative bid-ask spread                       |
-| `calculate_margin_and_volume`, `calculate_volume_by_margin`, `calculate_new_position_margin_ratio` | Margin budget and volume sizing               |
-| `normalize_order_volume`, `estimate_order_margin`, `calculate_positions_margin`                    | Broker volume normalization and margin totals |
-| `determine_order_limits`                                                                           | SL/TP price levels from ratios                |
-| `ensure_symbol_selected`                                                                           | Select/verify Market Watch visibility         |
-| `place_market_order`, `close_open_positions`, `update_sltp_for_open_positions`                     | Order execution helpers (`dry_run` supported) |
-| `MarginVolume`, `OrderLimits`, `OrderExecutionResult`                                              | Typed return contracts for order helpers      |
-| `OrderSide`, `OrderFillingMode`, `OrderTimeMode`, `PositionSide`, `ExecutionStatus`                | Typed enums for order helpers                 |
+| Symbol                                                                                                                         | Role                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| `get_account_snapshot`, `get_symbol_snapshot`, `get_tick_snapshot`, `get_positions_frame`                                      | Normalized account/symbol/tick/position views                     |
+| `extract_tick_price`                                                                                                           | Positive finite bid/ask extraction from tick mappings             |
+| `detect_position_side`                                                                                                         | Net long / short / flat from open positions                       |
+| `calculate_spread_ratio`                                                                                                       | Relative bid-ask spread                                           |
+| `calculate_margin_and_volume`, `calculate_volume_by_margin`, `calculate_new_position_margin_ratio`                             | Margin budget and volume sizing                                   |
+| `normalize_order_volume`, `estimate_order_margin`, `calculate_positions_margin`                                                | Broker volume normalization and margin totals                     |
+| `calculate_positions_margin_by_symbol`                                                                                         | Per-symbol margin map (resilient, first-seen order)               |
+| `calculate_positions_margin_safe`                                                                                              | Summed total margin across symbols (failed symbols skipped)       |
+| `calculate_projected_margin_ratio`                                                                                             | Estimated symbol-scoped margin/equity after optional new exposure |
+| `calculate_account_projected_margin_ratio`                                                                                     | Account snapshot margin/equity after optional new exposure        |
+| `calculate_symbol_group_margin_ratio`                                                                                          | Estimated symbol-group margin/equity with optional exposure       |
+| `determine_order_limits`                                                                                                       | SL/TP price levels from ratios                                    |
+| `calculate_trailing_stop_updates`                                                                                              | Per-ticket generic trailing stop-loss update plan                 |
+| `ensure_symbol_selected`                                                                                                       | Select/verify Market Watch visibility                             |
+| `place_market_order`, `close_open_positions`, `update_sltp_for_open_positions`, `update_trailing_stop_loss_for_open_positions` | Order execution helpers (`dry_run` supported)                     |
+| `MarginVolume`, `OrderLimits`, `OrderExecutionResult`                                                                          | Typed return contracts for order helpers                          |
+| `OrderSide`, `OrderFillingMode`, `OrderTimeMode`, `PositionSide`, `ExecutionStatus`                                            | Typed enums for order helpers                                     |
+| `ProjectionMode`                                                                                                               | Literal type for `calculate_symbol_group_margin_ratio` projection |
+
+`calculate_symbol_group_margin_ratio` accepts an optional `projection_mode`
+parameter (`"add"` by default). Pass `projection_mode="replace_symbol"` to
+subtract current exposure for `new_symbol` before adding the candidate margin —
+useful for reversal-style projections. mt5cli only calculates broker-facing
+exposure; downstream applications own thresholds, risk guard actions, and
+strategy policy.
 
 `MT5Client.order_send()` and CLI `order-send --yes` are live execution paths.
 
 Order helpers validate broker stop-level distance in `determine_order_limits()` and
-raise `Mt5TradingError` when computed SL/TP prices are too close to the entry
+raise `Mt5OperationError` when computed SL/TP prices are too close to the entry
 quote. Validation uses `trade_stops_level * point` from the current quote and
 symbol metadata as a pre-check only; it does not guarantee live order acceptance
 after price movement and does not inspect `trade_freeze_level`. Live
@@ -125,21 +124,25 @@ sending requests. Failed, malformed, or unknown broker retcodes are fail-closed
 and returned as `status="failed"` with normalized `request` / `response` details;
 `dry_run=True` never calls `ensure_symbol_selected()` or `order_send()`.
 
-### Errors and MT5 type re-exports
+### Errors
 
-| Symbol                                                                               | Role                                            |
-| ------------------------------------------------------------------------------------ | ----------------------------------------------- |
-| `Mt5CliError`, `Mt5ConnectionError`, `Mt5OperationError`, `Mt5SchemaError`           | Stable mt5cli exception types                   |
-| `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error` | Error normalization and retry classification    |
-| `Mt5Config`, `Mt5RuntimeError`, `Mt5TradingClient`, `Mt5TradingError`                | Re-exported pdmt5 types for adapter convenience |
+| Symbol                                                                     | Role                          |
+| -------------------------------------------------------------------------- | ----------------------------- |
+| `Mt5CliError`, `Mt5ConnectionError`, `Mt5OperationError`, `Mt5SchemaError` | Stable mt5cli exception types |
 
-### Additional public exports (secondary)
+## Module-scoped helpers
 
-The package root also exports schema, storage, and parsing helpers (for example
-`DataKind`, `Dataset`, `normalize_dataframe`, `export_dataframe`,
-`parse_timeframe`, `TIMEFRAME_MAP`). These are public but oriented toward export
-pipelines and advanced integration. Prefer the stable symbols above for core
-infrastructure.
+Lower-level helpers are available from their owning modules and are not part
+of the package-root stable surface. Import them directly when needed:
+
+| Module              | Examples                                                                                       |
+| ------------------- | ---------------------------------------------------------------------------------------------- |
+| `mt5cli.history`    | `resolve_rate_view_name`, `resolve_rate_tables`, `load_rate_data`, `build_rate_view_name`      |
+| `mt5cli.sdk`        | `copy_rates_from`, `copy_ticks_from`, `account_info`, `symbols`, `mt5_summary`, `latest_rates` |
+| `mt5cli.schemas`    | `DataKind`, `normalize_dataframe`, `validate_schema`, `DEDUP_KEYS`                             |
+| `mt5cli.utils`      | `Dataset`, `IfExists`, `detect_format`, `export_dataframe`, `export_dataframe_to_sqlite`       |
+| `mt5cli.converters` | `normalize_symbol`, `ensure_utc`, `parse_date_range`, `granularity_name`                       |
+| `mt5cli.exceptions` | `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error`           |
 
 ## CLI commands
 
@@ -152,7 +155,12 @@ The Typer application in `mt5cli.cli` exposes file-export commands documented in
 - Delegate to the same Python APIs described here; they are not duplicated
   business logic.
 
-`order-send` requires `--yes` before placing live trades.
+`order-send` is the expert raw-request path; it requires `--yes` and a fully
+constructed request payload. `close-positions` is the safer high-level helper
+that closes open positions by `--symbol` or `--ticket` using
+`close_open_positions()`. Both `order-send --yes` and `close-positions --yes`
+are live execution paths. `close-positions --dry-run` previews close orders
+without placing them and does not require `--yes`.
 
 ## Internal helpers (not stable)
 
@@ -189,6 +197,6 @@ their own adapter layer.
 ## Contract verification
 
 `tests/test_contracts.py` asserts that every name in `STABLE_SDK_EXPORTS` is
-importable from `mt5cli`, documents key closed-bar, rate-view, SQLite loading,
-account-resolution, and trading-session behaviors, and keeps the contract set
-aligned with `__all__`.
+importable from `mt5cli`, that all package-root exports are covered by the
+stable set, and documents key closed-bar, SQLite loading, account-resolution,
+and trading-session behaviors.

docs/api/sdk.md

@@ -31,7 +31,7 @@ rates = collect_latest_rates_for_accounts_with_retries(
 ### Latest closed rate bars
 
 MetaTrader 5 `start_pos=0` includes the still-forming current bar as the last
-row. `fetch_latest_closed_rates()` handles one connected `Mt5CliClient`; use
+row. `fetch_latest_closed_rates()` handles one connected `MT5Client`; use
 `fetch_latest_closed_rates_for_trading_client()` from an active
 `Mt5TradingClient` session. Multi-account helpers fetch `count + 1` bars, drop
 that row with `drop_forming_rate_bar()`, and validate each series is non-empty. Returned frames are ordered
@@ -117,7 +117,8 @@ call it every iteration without over-fetching.
 ```python
 from pdmt5 import Mt5Config, Mt5DataClient
 
-from mt5cli import Dataset, ThrottledHistoryUpdater
+from mt5cli import ThrottledHistoryUpdater
+from mt5cli.utils import Dataset
 
 updater = ThrottledHistoryUpdater(
     output="history.db",
@@ -170,5 +171,5 @@ resulting `ValueError` is suppressed along with other recoverable errors.
 ## Trading-capable sessions
 
 For order placement and trading calculations, use the dedicated
-[Trading module](trading.md). The read-only `Mt5CliClient` and `mt5_session()`
-helpers in this module are unchanged.
+[Trading module](trading.md). Use `mt5_session()` / `MT5Client` for read-only
+collection.

docs/api/storage.md

@@ -1,3 +0,0 @@
-# Storage
-
-::: mt5cli.storage

docs/api/trading.md

@@ -6,8 +6,9 @@
 
 `create_trading_client()` and `mt5_trading_session()` complement the read-only
 `mt5_session()` helper in `sdk.py`. They return or yield an initialized
-`pdmt5.Mt5TradingClient`, use `Mt5Config.path` to launch the terminal when
-configured, and `mt5_trading_session()` always calls `shutdown()` on exit.
+client supporting order execution and account management, use `Mt5Config.path`
+to launch the terminal when configured, and `mt5_trading_session()` always
+calls `shutdown()` on exit.
 
 ```python
 from mt5cli import create_trading_client, mt5_trading_session
@@ -31,7 +32,7 @@ finally:
 `login` accepts `int`, numeric `str`, or an empty string; empty strings are
 treated as unset. `path`, `password`, `server`, and `timeout` are forwarded to
 `pdmt5.Mt5Config`, and omitted `timeout` values keep the lower-level default.
-The read-only `Mt5CliClient` / `mt5_session()` API is unchanged.
+Use `mt5_session()` / `MT5Client` for read-only data collection.
 
 ## State and order helpers
 
@@ -115,19 +116,19 @@ closed = close_open_positions(client, symbols="EURUSD", dry_run=True)
 `detect_position_side()` returns `long` for buy-only exposure, `short` for
 sell-only exposure, and `None` for no positions or mixed long/short exposure.
 `calculate_spread_ratio()` uses `(ask - bid) / ((ask + bid) / 2)` and raises
-`Mt5TradingError` when bid or ask is missing or non-positive.
+`Mt5OperationError` when bid or ask is missing or non-positive.
 `normalize_order_volume()` returns `0.0` for invalid constraints or
 sub-minimum requests; check the result before calling `estimate_order_margin()`,
 which requires a positive finite volume. `calculate_positions_margin()` silently
 skips rows with missing symbols, non-positive volumes, non-finite volumes, or
-unsupported position types, but propagates `Mt5TradingError` from `estimate_order_margin()` when a valid row
+unsupported position types, but propagates `Mt5OperationError` from `estimate_order_margin()` when a valid row
 encounters invalid tick data or margin results from the broker.
 
 SL/TP ratios for `determine_order_limits()` must satisfy `0 <= ratio < 1`; `0`
 omits that level. SL/TP prices are rounded with symbol `digits` metadata when
 available. `determine_order_limits()` pre-validates computed SL/TP prices against
 available `trade_stops_level * point` metadata when present; violations raise
-`Mt5TradingError`. This is a planning helper only: it does not guarantee broker
+`Mt5OperationError`. This is a planning helper only: it does not guarantee broker
 acceptance because live validation can still depend on price movement, bid/ask
 side, freeze levels, and server-side rules, and it does not validate
 `trade_freeze_level`. When symbol metadata cannot be loaded, protective prices
@@ -194,6 +195,6 @@ through the stable package root without embedding entry/exit policy.
 | Local SL/TP price derivation                             | `determine_order_limits()`                                                              |
 | Throttled SQLite history loop with ad-hoc error handling | `ThrottledHistoryUpdater(suppress_errors=True)`                                         |
 
-Keep read-only data collection on `mt5_session()` / `Mt5CliClient`; use
+Keep read-only data collection on `mt5_session()` / `MT5Client`; use
 `mt5_trading_session()` only where order placement or trading calculations are
 required.

docs/index.md

@@ -27,28 +27,30 @@ mt5cli provides a stable `MT5Client` Python API, standardized dataset schemas, s
 pip install mt5cli
 ```
 
+Parquet export is not included by default. To enable it, install the `parquet` extra:
+
+```bash
+pip install "mt5cli[parquet]"
+```
+
 ## Python API for downstream packages
 
-Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives. `Mt5CliClient` remains available as a backward-compatible alias.
+Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives.
 
 ```python
 from datetime import UTC, datetime
 from pathlib import Path
 
 from mt5cli import (
-    DataKind,
-    Dataset,
     MT5Client,
     build_config,
     collect_history,
-    export_dataframe,
-    load_rate_data,
-    minimum_margins,
     mt5_session,
-    normalize_dataframe,
-    recent_ticks,
-    resolve_rate_view_name,
 )
+from mt5cli.history import load_rate_data, resolve_rate_view_name
+from mt5cli.schemas import DataKind, normalize_dataframe
+from mt5cli.sdk import minimum_margins, recent_ticks
+from mt5cli.utils import Dataset, export_dataframe
 
 # Persistent session for multiple calls
 with mt5_session(build_config(login=12345, server="Broker-Demo")) as client:
@@ -84,7 +86,7 @@ collect_history(
 )
 ```
 
-Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Storage helpers are re-exported from `mt5cli.storage` and the package root.
+Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Export and storage helpers are in `mt5cli.utils` (`Dataset`, `export_dataframe`) and `mt5cli.history`.
 
 `MT5Client.order_send()` is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly (the CLI requires `--yes` for `order-send`).
 
@@ -145,20 +147,32 @@ mt5cli --login 12345 --password mypass --server MyBroker-Demo \
 | `minimum-margins`  | Export minimum-volume margin summary    |
 | `market-book`      | Export market depth (order book)        |
 
-### Trading
+### Trading State
 
-| Command                | Description                                                 |
-| ---------------------- | ----------------------------------------------------------- |
-| `orders`               | Export active orders                                        |
-| `positions`            | Export open positions                                       |
-| `history-orders`       | Export historical orders                                    |
-| `history-deals`        | Export historical deals                                     |
-| `recent-history-deals` | Export historical deals from a trailing window              |
-| `mt5-summary`          | Export terminal/account status summary                      |
-| `order-check`          | Check funds sufficiency for a trade request                 |
-| `order-send`           | Send a trade request to the trade server (`--yes` required) |
+| Command                | Description                                                           |
+| ---------------------- | --------------------------------------------------------------------- |
+| `orders`               | Export active orders                                                  |
+| `positions`            | Export open positions                                                 |
+| `history-orders`       | Export historical orders                                              |
+| `history-deals`        | Export historical deals                                               |
+| `recent-history-deals` | Export historical deals from a trailing window                        |
+| `mt5-summary`          | Export terminal/account status summary                                |
+| `order-check`          | Check funds sufficiency for a trade request (read-only, no `--yes`)   |
 
-Use `order-check` to validate a request payload before running `order-send --yes`.
+### Execution (live / mutating)
+
+These commands send requests to the live trade server and can place or close
+real trades. Both require `--yes` for live execution.
+
+| Command           | Description                                                                                          |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `order-send`      | Send a **raw** trade request directly to MT5 (`--yes` required; expert path — no extra validation)   |
+| `close-positions` | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` to preview) |
+
+Use `order-check` (Trading State) to validate funds before running `order-send --yes`.
+`close-positions` is the safer high-level alternative that builds correct close
+requests automatically. `order-send` is the expert raw path — downstream
+applications should prefer dedicated closing helpers or their own risk controls.
 
 ### Bulk Collection
 
@@ -215,7 +229,7 @@ See the [History schema diagram](api/history.md#entity-relationship-diagram) for
 
 Browse the API documentation for detailed module information:
 
-- [CLI Module](api/cli.md) - CLI application with export commands
+- [CLI Module](api/cli.md) - CLI application with data export and execution commands
 - [SDK Module](api/sdk.md) - Programmatic read-only data collection API
 - [Utils Module](api/utils.md) - Constants, parameter types, parsers, and export utilities
 

mkdocs.yml

@@ -59,7 +59,6 @@ nav:
       - Public API Contract: api/public-contract.md
       - Client: api/client.md
       - Schemas: api/schemas.md
-      - Storage: api/storage.md
       - Converters: api/converters.md
       - Exceptions: api/exceptions.md
       - CLI: api/cli.md

mt5cli/__init__.py

@@ -8,106 +8,35 @@ strategy responsibilities.
 
 from importlib.metadata import version
 
-from pdmt5 import Mt5Config, Mt5RuntimeError, Mt5TradingClient, Mt5TradingError
-
 from .client import MT5Client, build_config, mt5_session
 from .contract import STABLE_SDK_EXPORTS
-from .converters import (
-    ensure_utc,
-    granularity_name,
-    normalize_symbol,
-    normalize_symbols,
-    parse_date_range,
-    recent_window,
-)
 from .exceptions import (
     Mt5CliError,
     Mt5ConnectionError,
     Mt5OperationError,
     Mt5SchemaError,
-    call_with_normalized_errors,
-    is_recoverable_mt5_error,
-    normalize_mt5_exception,
 )
 from .history import (
     RateTarget,
     build_rate_targets,
-    build_rate_view_name,
     drop_forming_rate_bar,
-    load_rate_data,
-    load_rate_data_from_connection,
     load_rate_series_by_granularity,
     load_rate_series_from_sqlite,
-    resolve_history_datasets,
-    resolve_history_tick_flags,
-    resolve_history_timeframes,
-    resolve_rate_table_name,
-    resolve_rate_tables,
-    resolve_rate_view_name,
-    resolve_rate_view_names,
-)
-from .schemas import (
-    DEDUP_KEYS,
-    KNOWN_MT5_TIME_COLUMNS,
-    REQUIRED_COLUMNS,
-    TIME_COLUMNS,
-    DataKind,
-    normalize_dataframe,
-    normalize_time_columns,
-    schema_columns,
-    validate_schema,
 )
 from .sdk import (
     AccountSpec,
-    Mt5CliClient,
     ThrottledHistoryUpdater,
-    account_info,
     collect_history,
     collect_latest_closed_rates_by_granularity,
     collect_latest_closed_rates_for_accounts,
-    collect_latest_rates,
-    collect_latest_rates_for_accounts,
     collect_latest_rates_for_accounts_with_retries,
-    copy_rates_from,
-    copy_rates_from_pos,
-    copy_rates_range,
-    copy_ticks_from,
-    copy_ticks_range,
     fetch_latest_closed_rates,
-    history_deals,
-    history_orders,
-    last_error,
-    latest_rates,
-    market_book,
-    minimum_margins,
-    mt5_summary,
-    mt5_summary_as_df,
-    orders,
-    positions,
-    recent_history_deals,
-    recent_ticks,
     resolve_account_spec,
     resolve_account_specs,
-    substitute_env_placeholders,
-    symbol_info,
-    symbol_info_tick,
-    symbols,
-    terminal_info,
     update_history,
     update_history_with_config,
 )
-from .sdk import (
-    version as mt5_version,
-)
-from .storage import (
-    Dataset,
-    IfExists,
-    detect_format,
-    export_dataframe,
-    export_dataframe_to_sqlite,
-)
 from .trading import (
-    POSITION_COLUMNS,
     ExecutionStatus,
     MarginVolume,
     OrderExecutionResult,
@@ -116,10 +45,17 @@ from .trading import (
     OrderSide,
     OrderTimeMode,
     PositionSide,
+    ProjectionMode,
+    calculate_account_projected_margin_ratio,
     calculate_margin_and_volume,
     calculate_new_position_margin_ratio,
     calculate_positions_margin,
+    calculate_positions_margin_by_symbol,
+    calculate_positions_margin_safe,
+    calculate_projected_margin_ratio,
     calculate_spread_ratio,
+    calculate_symbol_group_margin_ratio,
+    calculate_trailing_stop_updates,
     calculate_volume_by_margin,
     close_open_positions,
     create_trading_client,
@@ -127,6 +63,7 @@ from .trading import (
     determine_order_limits,
     ensure_symbol_selected,
     estimate_order_margin,
+    extract_tick_price,
     fetch_latest_closed_rates_for_trading_client,
     fetch_latest_closed_rates_indexed,
     get_account_snapshot,
@@ -137,82 +74,55 @@ from .trading import (
     normalize_order_volume,
     place_market_order,
     update_sltp_for_open_positions,
-)
-from .utils import (
-    TICK_FLAG_MAP,
-    TIMEFRAME_MAP,
-    parse_datetime,
-    parse_tick_flags,
-    parse_timeframe,
+    update_trailing_stop_loss_for_open_positions,
 )
 
 __version__ = version(__package__) if __package__ else None
 
 __all__ = [
-    "DEDUP_KEYS",
-    "KNOWN_MT5_TIME_COLUMNS",
-    "POSITION_COLUMNS",
-    "REQUIRED_COLUMNS",
     "STABLE_SDK_EXPORTS",
-    "TICK_FLAG_MAP",
-    "TIMEFRAME_MAP",
-    "TIME_COLUMNS",
     "AccountSpec",
-    "DataKind",
-    "Dataset",
     "ExecutionStatus",
-    "IfExists",
     "MT5Client",
     "MarginVolume",
-    "Mt5CliClient",
     "Mt5CliError",
-    "Mt5Config",
     "Mt5ConnectionError",
     "Mt5OperationError",
-    "Mt5RuntimeError",
     "Mt5SchemaError",
-    "Mt5TradingClient",
-    "Mt5TradingError",
     "OrderExecutionResult",
     "OrderFillingMode",
     "OrderLimits",
     "OrderSide",
     "OrderTimeMode",
     "PositionSide",
+    "ProjectionMode",
     "RateTarget",
     "ThrottledHistoryUpdater",
-    "account_info",
     "build_config",
     "build_rate_targets",
-    "build_rate_view_name",
+    "calculate_account_projected_margin_ratio",
     "calculate_margin_and_volume",
     "calculate_new_position_margin_ratio",
     "calculate_positions_margin",
+    "calculate_positions_margin_by_symbol",
+    "calculate_positions_margin_safe",
+    "calculate_projected_margin_ratio",
     "calculate_spread_ratio",
+    "calculate_symbol_group_margin_ratio",
+    "calculate_trailing_stop_updates",
     "calculate_volume_by_margin",
-    "call_with_normalized_errors",
     "close_open_positions",
     "collect_history",
     "collect_latest_closed_rates_by_granularity",
     "collect_latest_closed_rates_for_accounts",
-    "collect_latest_rates",
-    "collect_latest_rates_for_accounts",
     "collect_latest_rates_for_accounts_with_retries",
-    "copy_rates_from",
-    "copy_rates_from_pos",
-    "copy_rates_range",
-    "copy_ticks_from",
-    "copy_ticks_range",
     "create_trading_client",
-    "detect_format",
     "detect_position_side",
     "determine_order_limits",
     "drop_forming_rate_bar",
     "ensure_symbol_selected",
-    "ensure_utc",
     "estimate_order_margin",
-    "export_dataframe",
-    "export_dataframe_to_sqlite",
+    "extract_tick_price",
     "fetch_latest_closed_rates",
     "fetch_latest_closed_rates_for_trading_client",
     "fetch_latest_closed_rates_indexed",
@@ -220,56 +130,16 @@ __all__ = [
     "get_positions_frame",
     "get_symbol_snapshot",
     "get_tick_snapshot",
-    "granularity_name",
-    "history_deals",
-    "history_orders",
-    "is_recoverable_mt5_error",
-    "last_error",
-    "latest_rates",
-    "load_rate_data",
-    "load_rate_data_from_connection",
     "load_rate_series_by_granularity",
     "load_rate_series_from_sqlite",
-    "market_book",
-    "minimum_margins",
     "mt5_session",
-    "mt5_summary",
-    "mt5_summary_as_df",
     "mt5_trading_session",
-    "mt5_version",
-    "normalize_dataframe",
-    "normalize_mt5_exception",
     "normalize_order_volume",
-    "normalize_symbol",
-    "normalize_symbols",
-    "normalize_time_columns",
-    "orders",
-    "parse_date_range",
-    "parse_datetime",
-    "parse_tick_flags",
-    "parse_timeframe",
     "place_market_order",
-    "positions",
-    "recent_history_deals",
-    "recent_ticks",
-    "recent_window",
     "resolve_account_spec",
     "resolve_account_specs",
-    "resolve_history_datasets",
-    "resolve_history_tick_flags",
-    "resolve_history_timeframes",
-    "resolve_rate_table_name",
-    "resolve_rate_tables",
-    "resolve_rate_view_name",
-    "resolve_rate_view_names",
-    "schema_columns",
-    "substitute_env_placeholders",
-    "symbol_info",
-    "symbol_info_tick",
-    "symbols",
-    "terminal_info",
     "update_history",
     "update_history_with_config",
     "update_sltp_for_open_positions",
-    "validate_schema",
+    "update_trailing_stop_loss_for_open_positions",
 ]

mt5cli/cli.py

@@ -1,18 +1,21 @@
-"""Command-line interface for MetaTrader 5 data export."""
+"""Command-line interface for MetaTrader 5 data and execution utilities."""
 
 from __future__ import annotations
 
+import json
 import logging
 from dataclasses import dataclass
 from datetime import datetime  # noqa: TC003
 from pathlib import Path  # noqa: TC003
 from typing import TYPE_CHECKING, Annotated, Any, cast
 
+import pandas as pd
 import typer
 from pdmt5 import Mt5Config
 
 from . import sdk
 from .client import MT5Client
+from .trading import OrderExecutionResult, close_open_positions, create_trading_client
 from .utils import (
     DATETIME_TYPE,
     REQUEST_TYPE,
@@ -29,8 +32,6 @@ from .utils import (
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    import pandas as pd
-
 logger = logging.getLogger(__name__)
 
 # ---------------------------------------------------------------------------
@@ -54,7 +55,12 @@ class _ExportContext:
 
 app = typer.Typer(
     name="mt5cli",
-    help="Export MetaTrader5 data to CSV, JSON, Parquet, or SQLite3.",
+    help=(
+        "MT5 data and execution utilities — read market data, inspect account"
+        " state, and send trade requests. Data commands write to CSV, JSON,"
+        " Parquet, or SQLite3. Execution commands (order-send, close-positions)"
+        " require --yes for live mutations."
+    ),
 )
 
 _REQUEST_OPTION_HELP = (
@@ -150,7 +156,7 @@ def _callback(  # pyright: ignore[reportUnusedFunction]
         typer.Option("--log-level", help="Logging level."),
     ] = LogLevel.WARNING,
 ) -> None:
-    """Configure shared options for all export commands.
+    """Configure shared connection and output options.
 
     Raises:
         typer.BadParameter: If the output format cannot be determined.
@@ -182,7 +188,7 @@ def _callback(  # pyright: ignore[reportUnusedFunction]
 # ---------------------------------------------------------------------------
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def rates_from(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -209,7 +215,7 @@ def rates_from(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def rates_from_pos(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -235,7 +241,7 @@ def rates_from_pos(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def latest_rates(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -264,7 +270,7 @@ def latest_rates(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def rates_range(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -291,7 +297,7 @@ def rates_range(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def ticks_from(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -315,7 +321,7 @@ def ticks_from(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def ticks_range(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -339,7 +345,7 @@ def ticks_range(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def ticks_recent(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -376,19 +382,19 @@ def ticks_recent(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def account_info(ctx: typer.Context) -> None:
     """Export account information."""
     _export_command(ctx, lambda client: client.account_info())
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def terminal_info(ctx: typer.Context) -> None:
     """Export terminal information."""
     _export_command(ctx, lambda client: client.terminal_info())
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def symbols(
     ctx: typer.Context,
     group: Annotated[
@@ -400,7 +406,7 @@ def symbols(
     _export_command(ctx, lambda client: client.symbols(group=group))
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def symbol_info(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -409,7 +415,7 @@ def symbol_info(
     _export_command(ctx, lambda client: client.symbol_info(symbol))
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def minimum_margins(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -418,7 +424,7 @@ def minimum_margins(
     _export_command(ctx, lambda client: client.minimum_margins(symbol))
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def orders(
     ctx: typer.Context,
     symbol: Annotated[str | None, typer.Option(help="Symbol filter.")] = None,
@@ -432,7 +438,7 @@ def orders(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def positions(
     ctx: typer.Context,
     symbol: Annotated[str | None, typer.Option(help="Symbol filter.")] = None,
@@ -446,7 +452,7 @@ def positions(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def history_orders(
     ctx: typer.Context,
     date_from: Annotated[
@@ -476,7 +482,7 @@ def history_orders(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def history_deals(
     ctx: typer.Context,
     date_from: Annotated[
@@ -506,7 +512,7 @@ def history_deals(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def recent_history_deals(
     ctx: typer.Context,
     hours: Annotated[float, typer.Option(help="Lookback window in hours.")],
@@ -529,25 +535,25 @@ def recent_history_deals(
     )
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def mt5_summary(ctx: typer.Context) -> None:
     """Export a compact terminal/account status summary."""
     _export_command(ctx, lambda client: client.mt5_summary_as_df())
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def version(ctx: typer.Context) -> None:
     """Export MetaTrader5 version information."""
     _export_command(ctx, lambda client: client.version())
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def last_error(ctx: typer.Context) -> None:
     """Export the last error information."""
     _export_command(ctx, lambda client: client.last_error())
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def symbol_info_tick(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -556,7 +562,7 @@ def symbol_info_tick(
     _export_command(ctx, lambda client: client.symbol_info_tick(symbol))
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def market_book(
     ctx: typer.Context,
     symbol: Annotated[str, typer.Option(help="Symbol name.")],
@@ -565,7 +571,7 @@ def market_book(
     _export_command(ctx, lambda client: client.market_book(symbol))
 
 
-@app.command()
+@app.command(rich_help_panel="Data / Export")
 def order_check(
     ctx: typer.Context,
     request: Annotated[
@@ -577,7 +583,7 @@ def order_check(
     _export_command(ctx, lambda client: client.order_check(request))
 
 
-@app.command()
+@app.command(rich_help_panel="Execution")
 def order_send(
     ctx: typer.Context,
     request: Annotated[
@@ -589,7 +595,13 @@ def order_send(
         typer.Option("--yes", help="Confirm the live trade request."),
     ] = False,
 ) -> None:
-    """Send a trading operation request to the trade server.
+    """Send a raw trade request to the trade server (expert path, live execution).
+
+    Passes the request JSON directly to MT5 ``order_send``. This is the
+    low-level expert path — it places real trades on the connected account
+    with no additional validation beyond what MT5 itself performs. Use
+    ``order-check`` first to validate funds sufficiency. Prefer
+    ``close-positions`` for closing open positions. ``--yes`` is required.
 
     Raises:
         typer.BadParameter: If --yes is not provided.
@@ -600,7 +612,97 @@ def order_send(
     _export_command(ctx, lambda client: client.order_send(request))
 
 
-@app.command()
+_EXECUTION_RESULT_COLUMNS: list[str] = [
+    "status",
+    "symbol",
+    "order_side",
+    "volume",
+    "retcode",
+    "comment",
+    "request",
+    "response",
+    "dry_run",
+]
+
+
+def _execution_results_to_df(results: list[OrderExecutionResult]) -> pd.DataFrame:
+    if not results:
+        return pd.DataFrame(columns=_EXECUTION_RESULT_COLUMNS)
+    rows = [
+        {
+            **r,
+            "request": json.dumps(r["request"]),
+            "response": json.dumps(r["response"]),
+        }
+        for r in results
+    ]
+    return pd.DataFrame(rows)
+
+
+@app.command(rich_help_panel="Execution")
+def close_positions(
+    ctx: typer.Context,
+    symbol: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--symbol",
+            "-s",
+            help="Symbol to close (repeat for multiple symbols).",
+        ),
+    ] = None,
+    ticket: Annotated[
+        list[int] | None,
+        typer.Option(
+            "--ticket",
+            "-t",
+            help="Position ticket to close (repeat for multiple tickets).",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Preview close orders without executing them."),
+    ] = False,
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", help="Confirm live position closing."),
+    ] = False,
+) -> None:
+    """Close open positions by symbol or ticket.
+
+    Delegates to :func:`mt5cli.trading.close_open_positions`. At least one
+    ``--symbol`` or ``--ticket`` must be provided to avoid accidentally closing
+    all positions. Use ``--dry-run`` to preview without executing; ``--yes`` is
+    required for live execution.
+
+    ``order-send`` is the expert raw-request path. ``close-positions`` is the
+    safer high-level helper that builds correct close requests automatically.
+
+    Raises:
+        typer.BadParameter: If neither ``--symbol`` nor ``--ticket`` is given,
+            or if ``--yes`` is missing for a live (non-dry-run) run.
+    """
+    if not symbol and not ticket:
+        msg = "Provide at least one --symbol or --ticket to close positions."
+        raise typer.BadParameter(msg)
+    if not dry_run and not yes:
+        msg = "Pass --yes to close live positions."
+        raise typer.BadParameter(msg, param_hint="--yes")
+    export_ctx = _get_export_context(ctx)
+    client = create_trading_client(config=export_ctx.config)
+    try:
+        results = close_open_positions(
+            client,
+            symbols=list(symbol) if symbol else None,
+            tickets=list(ticket) if ticket else None,
+            dry_run=dry_run,
+        )
+    finally:
+        client.shutdown()
+    df = _execution_results_to_df(results)
+    _execute_export(ctx, lambda: df)
+
+
+@app.command(rich_help_panel="Collection")
 def collect_history(
     ctx: typer.Context,
     symbol: Annotated[

mt5cli/client.py

@@ -24,9 +24,7 @@ class MT5Client(Mt5CliClient):
     """Public client for generic MT5 data access and order primitives.
 
     Extends the read-only SDK client with optional order check/send helpers and
-    exposes the same connection lifecycle as :class:`~mt5cli.sdk.Mt5CliClient`.
-    Downstream applications such as private trading packages should prefer this
-    type over the legacy ``Mt5CliClient`` name.
+    exposes the same connection lifecycle as :func:`mt5_session`.
 
     mt5cli intentionally exposes minimal execution primitives only. Trading
     decisions, signals, strategies, backtests, and optimization remain the

mt5cli/contract.py

@@ -1,59 +1,50 @@
-"""Stable downstream SDK export names for mt5cli."""
+"""Downstream SDK export tier for mt5cli."""
 
 from __future__ import annotations
 
 STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "AccountSpec",
     "MT5Client",
-    "Mt5CliClient",
     "Mt5CliError",
-    "Mt5Config",
     "Mt5ConnectionError",
     "Mt5OperationError",
-    "Mt5RuntimeError",
     "Mt5SchemaError",
-    "Mt5TradingClient",
-    "Mt5TradingError",
     "OrderFillingMode",
     "OrderSide",
     "OrderTimeMode",
     "PositionSide",
+    "ProjectionMode",
     "ExecutionStatus",
     "MarginVolume",
     "OrderExecutionResult",
     "OrderLimits",
     "RateTarget",
     "ThrottledHistoryUpdater",
-    "account_info",
     "build_config",
     "build_rate_targets",
-    "build_rate_view_name",
+    "calculate_account_projected_margin_ratio",
     "calculate_margin_and_volume",
     "calculate_new_position_margin_ratio",
+    "calculate_projected_margin_ratio",
     "calculate_positions_margin",
+    "calculate_positions_margin_by_symbol",
+    "calculate_positions_margin_safe",
     "calculate_spread_ratio",
+    "calculate_symbol_group_margin_ratio",
+    "calculate_trailing_stop_updates",
     "calculate_volume_by_margin",
-    "call_with_normalized_errors",
     "close_open_positions",
     "collect_history",
     "collect_latest_closed_rates_by_granularity",
     "collect_latest_closed_rates_for_accounts",
-    "collect_latest_rates",
-    "collect_latest_rates_for_accounts",
     "collect_latest_rates_for_accounts_with_retries",
-    "copy_rates_from",
-    "copy_rates_from_pos",
-    "copy_rates_range",
-    "copy_ticks_from",
-    "copy_ticks_range",
     "create_trading_client",
     "detect_position_side",
     "determine_order_limits",
     "drop_forming_rate_bar",
     "ensure_symbol_selected",
     "estimate_order_margin",
-    "export_dataframe",
-    "export_dataframe_to_sqlite",
+    "extract_tick_price",
     "fetch_latest_closed_rates",
     "fetch_latest_closed_rates_for_trading_client",
     "fetch_latest_closed_rates_indexed",
@@ -61,46 +52,18 @@ STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
     "get_positions_frame",
     "get_symbol_snapshot",
     "get_tick_snapshot",
-    "history_deals",
-    "history_orders",
-    "is_recoverable_mt5_error",
-    "last_error",
-    "latest_rates",
-    "load_rate_data",
-    "load_rate_data_from_connection",
     "load_rate_series_by_granularity",
     "load_rate_series_from_sqlite",
-    "market_book",
-    "minimum_margins",
     "mt5_session",
-    "mt5_summary",
-    "mt5_summary_as_df",
     "mt5_trading_session",
-    "mt5_version",
-    "normalize_mt5_exception",
     "normalize_order_volume",
-    "orders",
     "place_market_order",
-    "positions",
-    "recent_history_deals",
-    "recent_ticks",
     "resolve_account_spec",
     "resolve_account_specs",
-    "resolve_history_datasets",
-    "resolve_history_tick_flags",
-    "resolve_history_timeframes",
-    "resolve_rate_table_name",
-    "resolve_rate_tables",
-    "resolve_rate_view_name",
-    "resolve_rate_view_names",
-    "substitute_env_placeholders",
-    "symbol_info",
-    "symbol_info_tick",
-    "symbols",
-    "terminal_info",
     "update_history",
     "update_history_with_config",
     "update_sltp_for_open_positions",
+    "update_trailing_stop_loss_for_open_positions",
 })
 
 __all__ = ["STABLE_SDK_EXPORTS"]

mt5cli/exceptions.py

@@ -4,11 +4,16 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, TypeVar
 
-from pdmt5 import Mt5RuntimeError, Mt5TradingError
+from pdmt5 import Mt5RuntimeError
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
+try:
+    from pdmt5 import Mt5TradingError
+except ImportError:  # pragma: no cover
+    Mt5TradingError = None  # type: ignore[assignment]
+
 T = TypeVar("T")
 
 __all__ = [
@@ -22,7 +27,7 @@ __all__ = [
 ]
 
 _RECOVERABLE_MT5_ERRORS: tuple[type[BaseException], ...] = (
-    Mt5TradingError,
+    *([Mt5TradingError] if Mt5TradingError is not None else []),  # type: ignore[misc]
     Mt5RuntimeError,
 )
 
@@ -50,7 +55,7 @@ def is_recoverable_mt5_error(exc: BaseException) -> bool:
         exc: Exception raised by MT5 or pdmt5.
 
     Returns:
-        True for ``Mt5RuntimeError`` and ``Mt5TradingError``.
+        True for ``Mt5RuntimeError`` and ``Mt5TradingError`` (if available).
     """
     return isinstance(exc, _RECOVERABLE_MT5_ERRORS)
 
@@ -65,7 +70,7 @@ def normalize_mt5_exception(exc: BaseException) -> Mt5CliError:
         ``Mt5ConnectionError`` for runtime failures, ``Mt5OperationError`` for
         trading failures, or the original exception when it is not recognized.
     """
-    if isinstance(exc, Mt5TradingError):
+    if Mt5TradingError is not None and isinstance(exc, Mt5TradingError):
         return Mt5OperationError(str(exc))
     if isinstance(exc, Mt5RuntimeError):
         return Mt5ConnectionError(str(exc))

mt5cli/sdk.py

@@ -15,7 +15,12 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Self, TypeVar, cast
 
 import pandas as pd
-from pdmt5 import Mt5Config, Mt5DataClient, Mt5RuntimeError, Mt5TradingError
+from pdmt5 import Mt5Config, Mt5DataClient, Mt5RuntimeError
+
+try:
+    from pdmt5 import Mt5TradingError
+except ImportError:  # pragma: no cover
+    Mt5TradingError = None  # type: ignore[assignment]
 
 from .history import (
     create_cash_events_view,
@@ -40,7 +45,7 @@ from .utils import (
 from .utils import coerce_login as _coerce_login
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator, Sequence
+    from collections.abc import Callable, Collection, Iterator, Sequence
 
     UpdateHistoryBackend = Callable[..., None]
 
@@ -49,7 +54,7 @@ T = TypeVar("T")
 logger = logging.getLogger(__name__)
 
 _RECOVERABLE_HISTORY_UPDATE_ERRORS: tuple[type[BaseException], ...] = (
-    Mt5TradingError,
+    *([Mt5TradingError] if Mt5TradingError is not None else []),  # type: ignore[assignment]
     Mt5RuntimeError,
     sqlite3.Error,
     ValueError,
@@ -142,6 +147,7 @@ __all__ = [
     "resolve_account_spec",
     "resolve_account_specs",
     "substitute_env_placeholders",
+    "substitute_mapping_values",
     "symbol_info",
     "symbol_info_tick",
     "symbols",
@@ -305,7 +311,7 @@ def _fetch_minimum_margins(client: Mt5DataClient, symbol: str) -> pd.DataFrame:
 def build_config(
     *,
     path: str | None = None,
-    login: int | None = None,
+    login: int | str | None = None,
     password: str | None = None,
     server: str | None = None,
     timeout: int | None = None,
@@ -315,14 +321,19 @@ def build_config(
 
     Args:
         path: Optional terminal executable path.
-        login: Optional trading account login.
+        login: Optional trading account login. Integers are preserved. String
+            values are coerced: empty or whitespace-only strings become
+            ``None``; numeric strings such as ``"12345"`` are converted to
+            ``int``; non-numeric strings raise ``ValueError``. When
+            ``allow_whole_dollar_env=True``, ``$ENV_NAME`` and
+            ``${ENV_NAME}`` placeholders are expanded before coercion.
         password: Optional trading account password.
         server: Optional trading server name.
         timeout: Optional connection timeout in milliseconds.
         allow_whole_dollar_env: When ``True``, string parameters that are
             exactly ``$ENV_NAME`` are expanded from the environment. Applies
-            to ``path``, ``password``, and ``server``. Default ``False``
-            preserves existing behavior.
+            to ``path``, ``login``, ``password``, and ``server``. Default
+            ``False`` preserves existing behavior.
 
     Returns:
         Configured ``Mt5Config`` instance.
@@ -330,6 +341,8 @@ def build_config(
     if allow_whole_dollar_env:
         if path is not None:
             path = substitute_env_placeholders(path, allow_whole_dollar_env=True)
+        if isinstance(login, str):
+            login = substitute_env_placeholders(login, allow_whole_dollar_env=True)
         if password is not None:
             password = substitute_env_placeholders(
                 password, allow_whole_dollar_env=True
@@ -338,7 +351,7 @@ def build_config(
             server = substitute_env_placeholders(server, allow_whole_dollar_env=True)
     return Mt5Config(
         path=path,
-        login=login,
+        login=_coerce_login(login),
         password=password,
         server=server,
         timeout=timeout,
@@ -1442,6 +1455,75 @@ def substitute_env_placeholders(
     return "".join(parts)
 
 
+def substitute_mapping_values(
+    data: object,
+    *,
+    keys: Collection[str],
+    allow_whole_dollar_env: bool = False,
+    blank_string_keys_as_none: Collection[str] = (),
+) -> object:
+    """Recursively substitute environment placeholders for selected mapping keys.
+
+    Traverses nested dicts and lists, expanding ``${ENV_VAR}`` (and
+    ``$ENV_NAME`` when ``allow_whole_dollar_env=True``) in string values
+    whose immediate parent dict key is in ``keys``.  Fields whose key is
+    not in ``keys`` are preserved exactly, including literal dollar signs.
+    Strings that are direct elements of a list are never substituted;
+    substitution only applies to strings that are immediate dict values.
+
+    This is a generic downstream config utility.  Key names such as
+    ``mt5_login`` or ``mt5_password`` must be supplied by the caller;
+    mt5cli does not hard-code any application-specific key names.
+    Callers are responsible for ensuring ``data`` has bounded nesting depth;
+    deeply nested or self-referential structures will hit Python's recursion
+    limit.
+
+    Args:
+        data: Arbitrarily nested dict/list/scalar value to process.
+        keys: Mapping keys whose string values receive placeholder
+            substitution.
+        allow_whole_dollar_env: When ``True``, a string that is exactly
+            ``$ENV_NAME`` (whole value) is also expanded from the
+            environment in addition to ``${ENV_NAME}`` placeholders.
+            Default ``False`` expands ``${ENV_NAME}`` only.
+        blank_string_keys_as_none: Mapping keys for which blank strings
+            (after any substitution) are normalised to ``None``.  A key
+            may appear in ``blank_string_keys_as_none`` without also
+            appearing in ``keys``.
+
+    Returns:
+        The processed value.  Dicts and lists are rebuilt into new
+        containers with selected string values substituted and
+        blank-normalised.  Scalar inputs (non-dict, non-list) are
+        returned as-is.
+    """
+    keys_set: frozenset[str] = frozenset(keys)
+    blank_keys_set: frozenset[str] = frozenset(blank_string_keys_as_none)
+
+    def _visit(node: object, current_key: str | None) -> object:
+        if isinstance(node, dict):
+            typed = cast("dict[object, object]", node)
+            return {
+                k: _visit(v, k if isinstance(k, str) else None)
+                for k, v in typed.items()
+            }
+        if isinstance(node, list):
+            typed_list = cast("list[object]", node)
+            return [_visit(item, None) for item in typed_list]
+        if not isinstance(node, str):
+            return node
+        text = node
+        if current_key in keys_set:
+            text = substitute_env_placeholders(
+                node, allow_whole_dollar_env=allow_whole_dollar_env
+            )
+        if current_key in blank_keys_set and not text.strip():
+            return None
+        return text
+
+    return _visit(data, None)
+
+
 def _resolve_field(
     override: str | None,
     account_value: str | None,

mt5cli/storage.py

@@ -1,49 +0,0 @@
-"""Generic storage helpers for MT5 market and account history."""
-
-from __future__ import annotations
-
-from .history import (
-    RateTarget,
-    build_rate_targets,
-    build_rate_view_name,
-    drop_forming_rate_bar,
-    load_rate_data,
-    load_rate_data_from_connection,
-    load_rate_series_by_granularity,
-    load_rate_series_from_sqlite,
-    resolve_rate_tables,
-    resolve_rate_view_name,
-    resolve_rate_view_names,
-)
-from .sdk import collect_history, update_history, update_history_with_config
-from .utils import (
-    Dataset,
-    IfExists,
-    OutputFormat,
-    detect_format,
-    export_dataframe,
-    export_dataframe_to_sqlite,
-)
-
-__all__ = [
-    "Dataset",
-    "IfExists",
-    "OutputFormat",
-    "RateTarget",
-    "build_rate_targets",
-    "build_rate_view_name",
-    "collect_history",
-    "detect_format",
-    "drop_forming_rate_bar",
-    "export_dataframe",
-    "export_dataframe_to_sqlite",
-    "load_rate_data",
-    "load_rate_data_from_connection",
-    "load_rate_series_by_granularity",
-    "load_rate_series_from_sqlite",
-    "resolve_rate_tables",
-    "resolve_rate_view_name",
-    "resolve_rate_view_names",
-    "update_history",
-    "update_history_with_config",
-]

mt5cli/utils.py

@@ -10,7 +10,8 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, TypeGuard
 
 import click
-from pdmt5 import COPY_TICKS_MAP, TIMEFRAME_MAP
+from pdmt5 import COPY_TICKS_MAP as _COPY_TICKS_MAP
+from pdmt5 import TIMEFRAME_MAP as _TIMEFRAME_MAP
 from pdmt5 import parse_copy_ticks as _parse_copy_ticks
 from pdmt5 import parse_timeframe as _parse_timeframe
 
@@ -23,14 +24,11 @@ if TYPE_CHECKING:
 # Constants
 # ---------------------------------------------------------------------------
 
-# Backward-compatible snapshot; prefer ``COPY_TICKS_MAP`` from pdmt5 directly.
-TICK_FLAG_MAP: dict[str, int] = dict(COPY_TICKS_MAP)
-
 TIMEFRAME_NAMES: tuple[str, ...] = tuple(
-    name for name in TIMEFRAME_MAP if not name.startswith("TIMEFRAME_")
+    name for name in _TIMEFRAME_MAP if not name.startswith("TIMEFRAME_")
 )
 _TICK_FLAG_NAMES: tuple[str, ...] = tuple(
-    name for name in COPY_TICKS_MAP if not name.startswith("COPY_TICKS_")
+    name for name in _COPY_TICKS_MAP if not name.startswith("COPY_TICKS_")
 )
 
 _FORMAT_EXTENSIONS: dict[str, str] = {
@@ -314,6 +312,7 @@ def export_dataframe(
         table_name: Table name for SQLite3 output.
 
     Raises:
+        ImportError: If the parquet format is requested but pyarrow is not installed.
         ValueError: If the output format is not supported.
     """
     if output_format == "csv":
@@ -326,6 +325,14 @@ def export_dataframe(
             indent=2,
         )
     elif output_format == "parquet":
+        try:
+            __import__("pyarrow")
+        except ImportError as exc:
+            msg = (
+                "Parquet export requires the optional dependency pyarrow. "
+                'Install it with: pip install "mt5cli[parquet]"'
+            )
+            raise ImportError(msg) from exc
         df.to_parquet(output_path, index=False)
     elif output_format == "sqlite3":
         export_dataframe_to_sqlite(

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mt5cli"
-version = "0.9.0"
+version = "1.0.1"
 description = "Generic MT5 data and execution infrastructure for Python applications"
 authors = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
 maintainers = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
@@ -9,9 +9,8 @@ license-files = ["LICENSE"]
 readme = "README.md"
 requires-python = ">= 3.11, < 3.14"
 dependencies = [
-  "pdmt5>=0.3.0",
+  "pdmt5>=1.0.0",
   "click >= 8.1.0",
-  "pyarrow >= 19.0.0",
   "typer >= 0.15.0",
 ]
 classifiers = [
@@ -25,6 +24,9 @@ classifiers = [
   "Topic :: Office/Business :: Financial :: Investment",
 ]
 
+[project.optional-dependencies]
+parquet = ["pyarrow >= 19.0.0"]
+
 [project.scripts]
 mt5cli = "mt5cli.cli:main"
 
@@ -42,6 +44,7 @@ dev = [
   "pytest-mock >= 3.12.0",
   "pytest-cov >= 5.0.0",
   "pandas-stubs >= 2.2.3.250527",
+  "pyarrow >= 19.0.0",
   "mkdocs >= 1.6.1",
   "mkdocs-material >= 9.7.6",
   "mkdocstrings[python] >= 1.0.4",
@@ -124,7 +127,6 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-"mt5cli/history.py" = ["TC003"]
 "tests/**/*.py" = [
   "DOC201",   # Missing return documentation
   "DOC501",   # Raised exception missing from docstring
@@ -176,7 +178,10 @@ omit = [
 [tool.coverage.report]
 show_missing = true
 fail_under = 100
-exclude_lines = ["if TYPE_CHECKING:"]
+exclude_also = [
+  "if TYPE_CHECKING:",
+  "^\\s+\\.\\.\\.$",
+]
 
 [build-system]
 requires = ["hatchling"]

tests/test_cli.py

@@ -740,6 +740,366 @@ class TestCommands:
         assert "must be a JSON object" in normalize_cli_output(result.output)
 
 
+# ---------------------------------------------------------------------------
+# Help text / scope tests
+# ---------------------------------------------------------------------------
+
+
+class TestHelpText:
+    """Tests verifying CLI help text matches the documented scope."""
+
+    def test_top_level_help_mentions_execution(self) -> None:
+        """Top-level help must describe execution utilities, not export only."""
+        result = runner.invoke(app, ["--help"])
+        assert result.exit_code == 0
+        output = normalize_cli_output(result.output)
+        assert "execution" in output.lower()
+
+    def test_top_level_help_has_execution_panel(self) -> None:
+        """Top-level help must show an Execution command group."""
+        result = runner.invoke(app, ["--help"])
+        assert result.exit_code == 0
+        assert "Execution" in result.output
+
+    def test_top_level_help_has_data_export_panel(self) -> None:
+        """Top-level help must show a Data / Export command group."""
+        result = runner.invoke(app, ["--help"])
+        assert result.exit_code == 0
+        assert "Data / Export" in result.output
+
+    def test_order_send_help_mentions_expert_and_raw(self) -> None:
+        """order-send help must communicate it is the expert raw-request path."""
+        result2 = runner.invoke(
+            app,
+            ["-o", "out.csv", "order-send", "--help"],
+        )
+        assert result2.exit_code == 0
+        output = normalize_cli_output(result2.output)
+        assert "raw" in output.lower()
+        assert "expert" in output.lower()
+
+    def test_order_send_help_mentions_live_execution(self) -> None:
+        """order-send help must warn about live execution."""
+        result = runner.invoke(
+            app,
+            ["-o", "out.csv", "order-send", "--help"],
+        )
+        assert result.exit_code == 0
+        output = normalize_cli_output(result.output)
+        assert "live" in output.lower()
+
+    def test_close_positions_help_mentions_dry_run_and_yes(self) -> None:
+        """close-positions help must document both safety gates."""
+        result = runner.invoke(
+            app,
+            ["-o", "out.csv", "close-positions", "--help"],
+        )
+        assert result.exit_code == 0
+        output = normalize_cli_output(result.output)
+        assert "--dry-run" in output
+        assert "--yes" in output
+
+
+# ---------------------------------------------------------------------------
+# close-positions command
+# ---------------------------------------------------------------------------
+
+
+def _build_mock_trading_client() -> MagicMock:
+    """Return a MagicMock Mt5TradingClient with trading constants set."""
+    client = MagicMock()
+    client.mt5.POSITION_TYPE_BUY = 0
+    client.mt5.POSITION_TYPE_SELL = 1
+    client.mt5.ORDER_TYPE_BUY = 10
+    client.mt5.ORDER_TYPE_SELL = 11
+    client.mt5.TRADE_ACTION_DEAL = 20
+    client.mt5.ORDER_FILLING_IOC = 30
+    client.mt5.ORDER_TIME_GTC = 40
+    client.mt5.TRADE_RETCODE_DONE = 10009
+    client.mt5.TRADE_RETCODE_PLACED = 10008
+    client.mt5.TRADE_RETCODE_DONE_PARTIAL = 10010
+    return client
+
+
+class TestClosePositions:
+    """Tests for the close-positions command."""
+
+    @pytest.fixture
+    def trading_client(self, mocker: MockerFixture) -> MagicMock:
+        """Patch create_trading_client and return a mock trading client."""
+        client = _build_mock_trading_client()
+        client.positions_get_as_df.return_value = pd.DataFrame([
+            {"ticket": 1, "symbol": "JP225", "type": 0, "volume": 1.0},
+            {"ticket": 2, "symbol": "EURUSD", "type": 1, "volume": 0.5},
+        ])
+        client.symbol_info_tick_as_dict.return_value = {"ask": 1.2, "bid": 1.1}
+        mocker.patch("mt5cli.cli.create_trading_client", return_value=client)
+        return client
+
+    def test_dry_run_does_not_require_yes(
+        self,
+        tmp_path: Path,
+        trading_client: MagicMock,
+    ) -> None:
+        """Test --dry-run mode succeeds without --yes."""
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            ["-o", str(output), "close-positions", "--symbol", "JP225", "--dry-run"],
+        )
+        assert result.exit_code == 0, result.output
+        assert output.exists()
+        trading_client.order_send.assert_not_called()
+        trading_client.shutdown.assert_called_once()
+
+    def test_live_requires_yes(
+        self,
+        tmp_path: Path,
+        trading_client: MagicMock,
+    ) -> None:
+        """Test live close-positions fails without --yes."""
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            ["-o", str(output), "close-positions", "--symbol", "JP225"],
+        )
+        assert result.exit_code != 0
+        assert "Pass --yes" in normalize_cli_output(result.output)
+        trading_client.order_send.assert_not_called()
+
+    def test_live_with_yes_calls_order_send(
+        self,
+        tmp_path: Path,
+        trading_client: MagicMock,
+    ) -> None:
+        """Test --yes triggers live execution for matching positions."""
+        trading_client.order_send.return_value = {"retcode": 10009, "comment": "ok"}
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            ["-o", str(output), "close-positions", "--symbol", "JP225", "--yes"],
+        )
+        assert result.exit_code == 0, result.output
+        trading_client.order_send.assert_called_once()
+        trading_client.shutdown.assert_called_once()
+
+    def test_symbol_filter_passed_through(
+        self,
+        tmp_path: Path,
+        trading_client: MagicMock,
+    ) -> None:
+        """Test --symbol values are used to filter positions."""
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            [
+                "-o",
+                str(output),
+                "close-positions",
+                "--symbol",
+                "JP225",
+                "--dry-run",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        data = json.loads(output.read_text())
+        assert len(data) == 1
+        assert data[0]["symbol"] == "JP225"
+        trading_client.shutdown.assert_called_once()
+
+    def test_multiple_symbols_filter(
+        self,
+        tmp_path: Path,
+        trading_client: MagicMock,
+    ) -> None:
+        """Test multiple --symbol options are combined."""
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            [
+                "-o",
+                str(output),
+                "close-positions",
+                "--symbol",
+                "JP225",
+                "--symbol",
+                "EURUSD",
+                "--dry-run",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        data = json.loads(output.read_text())
+        assert len(data) == 2
+        symbols = {row["symbol"] for row in data}
+        assert symbols == {"JP225", "EURUSD"}
+        trading_client.shutdown.assert_called_once()
+
+    def test_ticket_filter_passed_through(
+        self,
+        tmp_path: Path,
+        trading_client: MagicMock,
+    ) -> None:
+        """Test --ticket values are used to filter positions."""
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            [
+                "-o",
+                str(output),
+                "close-positions",
+                "--ticket",
+                "2",
+                "--dry-run",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        data = json.loads(output.read_text())
+        assert len(data) == 1
+        assert data[0]["symbol"] == "EURUSD"
+        trading_client.shutdown.assert_called_once()
+
+    def test_symbol_and_ticket_combined(
+        self,
+        tmp_path: Path,
+        trading_client: MagicMock,
+    ) -> None:
+        """Test --symbol and --ticket apply AND semantics when combined."""
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            [
+                "-o",
+                str(output),
+                "close-positions",
+                "--symbol",
+                "JP225",
+                "--ticket",
+                "1",
+                "--dry-run",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        data = json.loads(output.read_text())
+        # symbol=JP225 AND ticket=1 → exactly one match
+        assert len(data) == 1
+        assert data[0]["symbol"] == "JP225"
+        trading_client.shutdown.assert_called_once()
+
+    def test_missing_symbol_and_ticket_fails(
+        self,
+        tmp_path: Path,
+        mocker: MockerFixture,
+    ) -> None:
+        """Test that omitting both --symbol and --ticket fails closed."""
+        mocker.patch("mt5cli.cli.create_trading_client")
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            ["-o", str(output), "close-positions", "--dry-run"],
+        )
+        assert result.exit_code != 0
+        assert "symbol" in normalize_cli_output(result.output).lower()
+
+    def test_output_export_dry_run(
+        self,
+        tmp_path: Path,
+        trading_client: MagicMock,
+    ) -> None:
+        """Test dry-run results export with status=dry_run."""
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            ["-o", str(output), "close-positions", "--symbol", "JP225", "--dry-run"],
+        )
+        assert result.exit_code == 0, result.output
+        trading_client.shutdown.assert_called_once()
+        data = json.loads(output.read_text())
+        assert data[0]["status"] == "dry_run"
+        assert data[0]["dry_run"] is True
+        assert data[0]["order_side"] == "SELL"
+
+    def test_order_send_unchanged(
+        self,
+        tmp_path: Path,
+        mock_client: MagicMock,
+    ) -> None:
+        """Test that order-send behavior is unchanged by close-positions addition."""
+        output = tmp_path / "out.csv"
+        request = json.dumps({"action": 1, "symbol": "EURUSD", "volume": 0.1})
+        result = runner.invoke(
+            app,
+            ["-o", str(output), "order-send", "--request", request, "--yes"],
+        )
+        assert result.exit_code == 0, result.output
+        mock_client.order_send_as_df.assert_called_once()
+
+    def test_shutdown_called_on_close_error(
+        self,
+        tmp_path: Path,
+        mocker: MockerFixture,
+    ) -> None:
+        """Test that shutdown is called even when close_open_positions raises."""
+        client = _build_mock_trading_client()
+        client.positions_get_as_df.side_effect = RuntimeError("connection lost")
+        mocker.patch("mt5cli.cli.create_trading_client", return_value=client)
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            ["-o", str(output), "close-positions", "--symbol", "JP225", "--dry-run"],
+        )
+        assert result.exit_code != 0
+        client.shutdown.assert_called_once()
+
+    def test_dry_run_wins_over_yes(
+        self,
+        tmp_path: Path,
+        trading_client: MagicMock,
+    ) -> None:
+        """Test that --dry-run takes precedence when combined with --yes."""
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            [
+                "-o",
+                str(output),
+                "close-positions",
+                "--symbol",
+                "JP225",
+                "--dry-run",
+                "--yes",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        trading_client.order_send.assert_not_called()
+        trading_client.shutdown.assert_called_once()
+
+    def test_no_matching_positions_exports_empty_result(
+        self,
+        tmp_path: Path,
+        trading_client: MagicMock,
+    ) -> None:
+        """Test that zero filter matches produces an empty JSON array."""
+        trading_client.positions_get_as_df.return_value = pd.DataFrame([
+            {"ticket": 1, "symbol": "JP225", "type": 0, "volume": 1.0},
+        ])
+        output = tmp_path / "close.json"
+        result = runner.invoke(
+            app,
+            [
+                "-o",
+                str(output),
+                "close-positions",
+                "--symbol",
+                "NONEXISTENT",
+                "--dry-run",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        trading_client.shutdown.assert_called_once()
+        assert output.exists()
+        assert json.loads(output.read_text()) == []
+
+
 # ---------------------------------------------------------------------------
 # Callback / shared options
 # ---------------------------------------------------------------------------

tests/test_contracts.py

@@ -2,11 +2,16 @@
 
 from __future__ import annotations
 
+import importlib
 import sqlite3
 from datetime import UTC, datetime
+from importlib.metadata import requires
 from typing import TYPE_CHECKING, get_type_hints
 from unittest.mock import MagicMock
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
 import pandas as pd
 import pytest
 from pdmt5 import Mt5RuntimeError, Mt5TradingError
@@ -14,13 +19,8 @@ from pytest_mock import MockerFixture  # noqa: TC002
 
 import mt5cli
 from mt5cli import (
-    DEDUP_KEYS,
-    REQUIRED_COLUMNS,
     STABLE_SDK_EXPORTS,
-    TIME_COLUMNS,
     AccountSpec,
-    DataKind,
-    Dataset,
     ExecutionStatus,
     MarginVolume,
     MT5Client,
@@ -33,44 +33,62 @@ from mt5cli import (
     RateTarget,
     build_config,
     build_rate_targets,
+    calculate_account_projected_margin_ratio,
     calculate_margin_and_volume,
     calculate_positions_margin,
-    call_with_normalized_errors,
-    detect_format,
+    calculate_projected_margin_ratio,
+    calculate_symbol_group_margin_ratio,
+    calculate_trailing_stop_updates,
     drop_forming_rate_bar,
     ensure_symbol_selected,
-    ensure_utc,
-    export_dataframe,
-    export_dataframe_to_sqlite,
+    extract_tick_price,
     fetch_latest_closed_rates,
     fetch_latest_closed_rates_for_trading_client,
     fetch_latest_closed_rates_indexed,
-    granularity_name,
-    is_recoverable_mt5_error,
-    load_rate_data,
     load_rate_series_from_sqlite,
     mt5_session,
     mt5_trading_session,
-    normalize_dataframe,
-    normalize_mt5_exception,
     normalize_order_volume,
+    place_market_order,
+    resolve_account_spec,
+    resolve_account_specs,
+)
+from mt5cli.converters import (
+    ensure_utc,
+    granularity_name,
     normalize_symbol,
     normalize_symbols,
     parse_date_range,
-    place_market_order,
     recent_window,
-    resolve_account_spec,
-    resolve_account_specs,
+)
+from mt5cli.exceptions import (
+    call_with_normalized_errors,
+    is_recoverable_mt5_error,
+    normalize_mt5_exception,
+)
+from mt5cli.history import (
+    create_rate_compatibility_views,
+    load_rate_data,
     resolve_rate_view_name,
+)
+from mt5cli.retry import retry_with_backoff
+from mt5cli.schemas import (
+    DEDUP_KEYS,
+    REQUIRED_COLUMNS,
+    TIME_COLUMNS,
+    DataKind,
+    ensure_utc_columns,
+    normalize_dataframe,
+    normalize_time_columns,
     schema_columns,
     validate_schema,
 )
-from mt5cli.history import create_rate_compatibility_views
-from mt5cli.retry import retry_with_backoff
-from mt5cli.schemas import ensure_utc_columns, normalize_time_columns
-
-if TYPE_CHECKING:
-    from pathlib import Path
+from mt5cli.utils import (
+    Dataset,
+    detect_format,
+    export_dataframe,
+    export_dataframe_to_sqlite,
+)
 
 
 def _sample_frame(kind: DataKind) -> pd.DataFrame:
@@ -228,16 +246,19 @@ def test_is_recoverable_mt5_error(exc: Exception) -> None:
     assert is_recoverable_mt5_error(exc)
 
 
-def test_normalize_mt5_exception_maps_types() -> None:
+@pytest.mark.parametrize(
+    ("exc", "expected_type"),
+    [
+        (Mt5RuntimeError("x"), Mt5ConnectionError),
+        (Mt5TradingError("x"), Mt5OperationError),
+    ],
+)
+def test_normalize_mt5_exception_maps_types(
+    exc: Exception,
+    expected_type: type[Mt5ConnectionError | Mt5OperationError],
+) -> None:
     """MT5 exceptions map to stable mt5cli types."""
-    assert isinstance(
-        normalize_mt5_exception(Mt5RuntimeError("x")),
-        Mt5ConnectionError,
-    )
-    assert isinstance(
-        normalize_mt5_exception(Mt5TradingError("x")),
-        Mt5OperationError,
-    )
+    assert isinstance(normalize_mt5_exception(exc), expected_type)
 
 
 def test_call_with_normalized_errors_reraises_mapped_type() -> None:
@@ -414,26 +435,24 @@ def test_normalize_time_columns_skips_absent_time_fields() -> None:
     assert list(result.columns) == ["open"]
 
 
-def test_normalize_time_columns_converts_unix_seconds() -> None:
-    """Numeric MT5 ``time`` values are interpreted as Unix seconds."""
-    frame = pd.DataFrame({"time": [1704067200]})
-    result = normalize_time_columns(frame, DataKind.rates)
-    assert result.loc[0, "time"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
-
-
-def test_normalize_time_columns_converts_unix_milliseconds() -> None:
-    """Numeric MT5 ``time_msc`` values are interpreted as Unix milliseconds."""
-    frame = pd.DataFrame({"time_msc": [1704067200000]})
-    result = normalize_time_columns(frame, DataKind.ticks)
-    assert result.loc[0, "time_msc"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
-
-
-def test_normalize_time_columns_preserves_utc_datetimes() -> None:
-    """Already-converted datetime values remain UTC-normalized."""
-    aware = datetime(2024, 1, 1, tzinfo=UTC)
-    frame = pd.DataFrame({"time": [aware]})
-    result = normalize_time_columns(frame, DataKind.rates)
-    assert result.loc[0, "time"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
+@pytest.mark.parametrize(
+    ("col", "value", "kind"),
+    [
+        ("time", 1704067200, DataKind.rates),
+        ("time_msc", 1704067200000, DataKind.ticks),
+        ("time", datetime(2024, 1, 1, tzinfo=UTC), DataKind.rates),
+        ("time", "2024-01-01T00:00:00+00:00", DataKind.rates),
+    ],
+)
+def test_normalize_time_columns_coerces_value(
+    col: str,
+    value: object,
+    kind: DataKind,
+) -> None:
+    """Time column values are coerced to UTC timestamps regardless of input type."""
+    frame = pd.DataFrame({col: [value]})
+    result = normalize_time_columns(frame, kind)
+    assert result.loc[0, col] == pd.Timestamp("2024-01-01T00:00:00+00:00")
 
 
 def test_normalize_time_columns_handles_optional_order_times() -> None:
@@ -483,13 +502,6 @@ def test_ensure_utc_columns_skips_missing_columns() -> None:
     assert "time" in result.columns
 
 
-def test_normalize_time_columns_coerces_string_timestamps() -> None:
-    """String timestamps are parsed with timezone-aware datetime coercion."""
-    frame = pd.DataFrame({"time": ["2024-01-01T00:00:00+00:00"]})
-    result = normalize_time_columns(frame, DataKind.rates)
-    assert result.loc[0, "time"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
-
-
 def test_ensure_utc_columns_coerces_non_mt5_columns() -> None:
     """Non-MT5 columns still coerce to UTC datetimes."""
     frame = pd.DataFrame({"created_at": ["2024-01-01T00:00:00+00:00"]})
@@ -539,6 +551,12 @@ def test_storage_export_round_trip_sqlite(tmp_path: Path) -> None:
     assert count == 1
 
 
+def test_storage_module_does_not_exist() -> None:
+    """mt5cli.storage re-export module has been removed."""
+    with pytest.raises(ModuleNotFoundError):
+        importlib.import_module("mt5cli.storage")
+
+
 class TestStableSdkContract:
     """Tests for the documented stable downstream SDK contract."""
 
@@ -547,6 +565,21 @@ class TestStableSdkContract:
         missing = sorted(STABLE_SDK_EXPORTS - set(mt5cli.__all__))
         assert not missing, f"STABLE_SDK_EXPORTS missing from __all__: {missing}"
 
+    def test_stable_exports_cover_root_api(self) -> None:
+        """STABLE_SDK_EXPORTS classifies every package-root symbol."""
+        tier_metadata = {"STABLE_SDK_EXPORTS"}
+        root_exports = set(mt5cli.__all__)
+
+        missing_from_root = sorted(STABLE_SDK_EXPORTS - root_exports)
+        assert not missing_from_root, (
+            f"STABLE_SDK_EXPORTS missing from __all__: {missing_from_root}"
+        )
+
+        unclassified = sorted(root_exports - STABLE_SDK_EXPORTS - tier_metadata)
+        assert not unclassified, (
+            f"Root exports not in STABLE_SDK_EXPORTS: {unclassified}"
+        )
+
     @pytest.mark.parametrize("name", sorted(STABLE_SDK_EXPORTS))
     def test_stable_exports_are_importable_from_package_root(self, name: str) -> None:
         """Stable SDK names resolve through ``from mt5cli import ...``."""
@@ -615,37 +648,15 @@ class TestStableSdkContract:
 
         assert calculate_positions_margin(client) == 0
 
-    def test_resolve_rate_view_name_from_package_root(self, tmp_path: Path) -> None:
-        """Rate view resolution is importable and honors require_existing."""
-        db_path = tmp_path / "rates.db"
-        with sqlite3.connect(db_path) as conn:
-            conn.execute(
-                "CREATE TABLE rates("
-                " symbol TEXT, timeframe INTEGER, time TEXT, close REAL)",
-            )
-            conn.execute(
-                "INSERT INTO rates(symbol, timeframe, time, close) VALUES (?, ?, ?, ?)",
-                ("EURUSD", 1, "2024-01-01T00:00:00+00:00", 1.0),
-            )
-            create_rate_compatibility_views(conn)
-
-        assert resolve_rate_view_name(db_path, "EURUSD", "M1") == "rate_EURUSD__1"
-        missing = tmp_path / "missing.db"
-        with pytest.raises(ValueError, match="SQLite database not found"):
-            resolve_rate_view_name(missing, "EURUSD", "M1", require_existing=True)
-
-    def test_load_rate_data_from_package_root(self, tmp_path: Path) -> None:
-        """SQLite rate loading normalizes timestamps through the stable API."""
-        db_path = tmp_path / "view.db"
-        with sqlite3.connect(db_path) as conn:
-            conn.execute(
-                'CREATE VIEW "rate_EURUSD__1" AS'
-                " SELECT '2024-01-01T00:00:00+00:00' AS time, 1.1 AS close",
-            )
-
-        frame = load_rate_data(db_path, "rate_EURUSD__1")
-        assert frame.index.name == "time"
-        assert abs(float(frame.iloc[0]["close"]) - 1.1) < 1e-9
+    def test_generic_trading_helpers_from_package_root(self) -> None:
+        """New generic trading helpers resolve through the stable surface."""
+        price = extract_tick_price({"bid": "1.2"}, "bid")
+        assert price is not None
+        assert abs(price - 1.2) < 1e-9
+        assert callable(calculate_trailing_stop_updates)
+        assert callable(calculate_account_projected_margin_ratio)
+        assert callable(calculate_projected_margin_ratio)
+        assert callable(calculate_symbol_group_margin_ratio)
 
     def test_load_rate_series_from_sqlite_requires_managed_views(
         self,
@@ -694,7 +705,7 @@ class TestStableSdkContract:
         """Trading session helper initializes and always shuts down."""
         mock_client = MagicMock()
         mocker.patch(
-            "mt5cli.trading.Mt5TradingClient",
+            "mt5cli.trading.Mt5DataClient",
             return_value=mock_client,
         )
 
@@ -723,7 +734,7 @@ class TestStableSdkContract:
         """Trading session helper shuts down even when the body raises."""
         mock_client = MagicMock()
         mocker.patch(
-            "mt5cli.trading.Mt5TradingClient",
+            "mt5cli.trading.Mt5DataClient",
             return_value=mock_client,
         )
 
@@ -764,3 +775,87 @@ class TestStableSdkContract:
         assert result.index.tz is not None
         assert "time" not in result.columns
         assert "close" in result.columns
+
+    def test_rate_view_helpers_in_history_module(self, tmp_path: Path) -> None:
+        """Rate view helpers are available from mt5cli.history."""
+        db_path = tmp_path / "rates.db"
+        with sqlite3.connect(db_path) as conn:
+            conn.execute(
+                "CREATE TABLE rates("
+                " symbol TEXT, timeframe INTEGER, time TEXT, close REAL)",
+            )
+            conn.execute(
+                "INSERT INTO rates(symbol, timeframe, time, close) VALUES (?, ?, ?, ?)",
+                ("EURUSD", 1, "2024-01-01T00:00:00+00:00", 1.0),
+            )
+            create_rate_compatibility_views(conn)
+
+        assert resolve_rate_view_name(db_path, "EURUSD", "M1") == "rate_EURUSD__1"
+        missing = tmp_path / "missing.db"
+        with pytest.raises(ValueError, match="SQLite database not found"):
+            resolve_rate_view_name(missing, "EURUSD", "M1", require_existing=True)
+
+    def test_load_rate_data_in_history_module(self, tmp_path: Path) -> None:
+        """SQLite rate loading normalizes timestamps through mt5cli.history."""
+        db_path = tmp_path / "view.db"
+        with sqlite3.connect(db_path) as conn:
+            conn.execute(
+                'CREATE VIEW "rate_EURUSD__1" AS'
+                " SELECT '2024-01-01T00:00:00+00:00' AS time, 1.1 AS close",
+            )
+
+        frame = load_rate_data(db_path, "rate_EURUSD__1")
+        assert frame.index.name == "time"
+        assert abs(float(frame.iloc[0]["close"]) - 1.1) < 1e-9
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        "Mt5Config",
+        "Mt5RuntimeError",
+        "Mt5TradingClient",
+        "Mt5TradingError",
+        "TICK_FLAG_MAP",
+        "TIMEFRAME_MAP",
+    ],
+)
+def test_pdmt5_pass_through_names_removed_from_public_contract(name: str) -> None:
+    """Removed pdmt5 pass-through names are not part of the public contract."""
+    assert name not in STABLE_SDK_EXPORTS, (
+        f"{name!r} should not be in STABLE_SDK_EXPORTS"
+    )
+    assert name not in mt5cli.__all__, f"{name!r} should not be in mt5cli.__all__"
+
+
+def test_mt5cli_does_not_import_high_level_trading_symbols() -> None:
+    """mt5cli doesn't import Mt5TradingClient or Mt5TradingError at module level."""
+    trading_module = importlib.import_module("mt5cli.trading")
+    module_dict = vars(trading_module)
+    assert "Mt5TradingClient" not in module_dict, (
+        "mt5cli.trading should not import Mt5TradingClient at module level"
+    )
+    assert "Mt5TradingError" not in module_dict, (
+        "mt5cli.trading should not import Mt5TradingError at module level"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Packaging metadata
+# ---------------------------------------------------------------------------
+
+
+def test_parquet_extra_declares_pyarrow() -> None:
+    """Package metadata lists pyarrow under the parquet optional extra."""
+    reqs = requires("mt5cli") or []
+    parquet_reqs = [r for r in reqs if "pyarrow" in r and "parquet" in r]
+    assert parquet_reqs, "pyarrow not found in parquet optional extra"
+
+
+def test_pyarrow_not_in_core_dependencies() -> None:
+    """Pyarrow is not a core dependency; it belongs only in the parquet extra."""
+    reqs = requires("mt5cli") or []
+    core_reqs = [r for r in reqs if "extra ==" not in r]
+    assert not any("pyarrow" in r for r in core_reqs), (
+        "pyarrow should not appear in core dependencies"
+    )

tests/test_history.py

@@ -15,6 +15,8 @@ from pytest_mock import MockerFixture  # noqa: TC002
 if TYPE_CHECKING:
     from pathlib import Path
 
+from pdmt5 import TIMEFRAME_MAP
+
 from mt5cli import history
 from mt5cli.history import (
     DEFAULT_HISTORY_TIMEFRAMES,
@@ -58,7 +60,7 @@ from mt5cli.history import (
     write_rates_dataset,
     write_streamed_frame,
 )
-from mt5cli.utils import TIMEFRAME_MAP, Dataset, IfExists
+from mt5cli.utils import Dataset, IfExists
 
 
 class TestResolveRateViewName:
@@ -705,19 +707,25 @@ class TestIncrementalStart:
         assert starts["EURUSD", 1] == datetime(2024, 1, 2, tzinfo=UTC)
         assert starts["GBPUSD", 1] == datetime(2024, 1, 3, tzinfo=UTC)
 
-    def test_load_incremental_start_datetimes_requires_timeframe_column(
+    @pytest.mark.parametrize(
+        ("ddl", "missing_col"),
+        [
+            ("CREATE TABLE rates(symbol TEXT, time TEXT, open REAL)", "timeframe"),
+            ("CREATE TABLE rates(timeframe INTEGER, time TEXT, open REAL)", "symbol"),
+            ("CREATE TABLE rates(symbol TEXT, timeframe INTEGER, open REAL)", "time"),
+        ],
+    )
+    def test_load_incremental_start_datetimes_requires_column(
         self,
         tmp_path: Path,
+        ddl: str,
+        missing_col: str,
     ) -> None:
-        """Test rates tables without timeframe fail fast during incremental resume."""
+        """Test rates tables missing a required column fail fast."""
         fallback = datetime(2024, 1, 1, tzinfo=UTC)
-        with sqlite3.connect(tmp_path / "rates-without-timeframe.db") as conn:
-            conn.execute("CREATE TABLE rates(symbol TEXT, time TEXT, open REAL)")
-            conn.execute(
-                "INSERT INTO rates(symbol, time, open) VALUES (?, ?, ?)",
-                ("EURUSD", "2024-01-02T00:00:00+00:00", 1.0),
-            )
-            with pytest.raises(ValueError, match="missing: timeframe") as exc_info:
+        with sqlite3.connect(tmp_path / f"rates-no-{missing_col}.db") as conn:
+            conn.execute(ddl)
+            with pytest.raises(ValueError, match=f"missing: {missing_col}") as exc_info:
                 load_incremental_start_datetimes(
                     conn,
                     Dataset.rates,
@@ -725,47 +733,7 @@ class TestIncrementalStart:
                     timeframes=[1],
                     fallback_start=fallback,
                 )
-            assert "timeframe" in str(exc_info.value)
-
-    def test_load_incremental_start_datetimes_requires_symbol_column(
-        self,
-        tmp_path: Path,
-    ) -> None:
-        """Test rates tables without symbol fail fast during incremental resume."""
-        fallback = datetime(2024, 1, 1, tzinfo=UTC)
-        with sqlite3.connect(tmp_path / "rates-no-symbol.db") as conn:
-            conn.execute(
-                "CREATE TABLE rates(timeframe INTEGER, time TEXT, open REAL)",
-            )
-            with pytest.raises(ValueError, match="missing: symbol") as exc_info:
-                load_incremental_start_datetimes(
-                    conn,
-                    Dataset.rates,
-                    symbols=["EURUSD"],
-                    timeframes=[1],
-                    fallback_start=fallback,
-                )
-            assert "symbol" in str(exc_info.value)
-
-    def test_load_incremental_start_datetimes_requires_time_column(
-        self,
-        tmp_path: Path,
-    ) -> None:
-        """Test rates tables without time fail fast during incremental resume."""
-        fallback = datetime(2024, 1, 1, tzinfo=UTC)
-        with sqlite3.connect(tmp_path / "rates-no-time.db") as conn:
-            conn.execute(
-                "CREATE TABLE rates(symbol TEXT, timeframe INTEGER, open REAL)",
-            )
-            with pytest.raises(ValueError, match="missing: time") as exc_info:
-                load_incremental_start_datetimes(
-                    conn,
-                    Dataset.rates,
-                    symbols=["EURUSD"],
-                    timeframes=[1],
-                    fallback_start=fallback,
-                )
-            assert "time" in str(exc_info.value)
+            assert missing_col in str(exc_info.value)
 
     def test_load_incremental_start_datetimes_rejects_unrelated_rates_columns(
         self,
@@ -1800,12 +1768,11 @@ class TestIncrementalIntegration:
             )
         assert written_tables == set()
 
-    def test_resolve_history_tick_flags_invalid(self) -> None:
+    @pytest.mark.parametrize("flags", ["BAD", 7])
+    def test_resolve_history_tick_flags_invalid(self, flags: str | int) -> None:
         """Test invalid tick flags raise ValueError."""
         with pytest.raises(ValueError, match="Invalid tick flags"):
-            resolve_history_tick_flags("BAD")
-        with pytest.raises(ValueError, match="Invalid tick flags"):
-            resolve_history_tick_flags(7)
+            resolve_history_tick_flags(flags)
 
     def test_resolve_history_timeframes_invalid(self) -> None:
         """Test invalid timeframes raise ValueError."""

tests/test_sdk.py

@@ -54,6 +54,7 @@ from mt5cli.sdk import (
     resolve_account_spec,
     resolve_account_specs,
     substitute_env_placeholders,
+    substitute_mapping_values,
     symbol_info,
     symbol_info_tick,
     symbols,
@@ -1937,29 +1938,28 @@ class TestResolveAccountSpec:
         assert [a.server for a in resolved] == ["Shared", "Fixed"]
         assert all(a.timeout == 1000 for a in resolved)
 
-    def test_resolve_account_spec_with_whole_dollar_env(
+    @pytest.mark.parametrize(
+        ("allow_whole_dollar_env", "expected"),
+        [
+            (True, "secret"),
+            (False, "$MT5_PASSWORD"),
+        ],
+    )
+    def test_resolve_account_spec_whole_dollar_password(
         self,
         monkeypatch: pytest.MonkeyPatch,
+        allow_whole_dollar_env: bool,
+        expected: str,
     ) -> None:
-        """Account spec expands $ENV_NAME when allow_whole_dollar_env=True."""
+        """Test resolve_account_spec expands $ENV_NAME password only with opt-in."""
         monkeypatch.setenv("MT5_PASSWORD", "secret")
         account = AccountSpec(symbols=["EURUSD"], password="$MT5_PASSWORD")
 
-        resolved = resolve_account_spec(account, allow_whole_dollar_env=True)
+        resolved = resolve_account_spec(
+            account, allow_whole_dollar_env=allow_whole_dollar_env
+        )
 
-        assert resolved.password == "secret"  # noqa: S105
-
-    def test_resolve_account_spec_whole_dollar_not_expanded_by_default(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-    ) -> None:
-        """Test resolve_account_spec leaves $ENV_NAME literal by default."""
-        monkeypatch.setenv("MT5_PASSWORD", "secret")
-        account = AccountSpec(symbols=["EURUSD"], password="$MT5_PASSWORD")
-
-        resolved = resolve_account_spec(account)
-
-        assert resolved.password == "$MT5_PASSWORD"  # noqa: S105
+        assert resolved.password == expected
 
     def test_resolve_account_specs_with_whole_dollar_env(
         self,
@@ -1993,38 +1993,27 @@ class TestResolveAccountSpec:
 class TestBuildConfigWholeDollarEnv:
     """Tests for build_config with allow_whole_dollar_env."""
 
-    def test_build_config_substitutes_server_with_opt_in(
+    @pytest.mark.parametrize(
+        ("env_var", "field", "env_value"),
+        [
+            ("MT5_SERVER", "server", "Broker-Demo"),
+            ("MT5_PASSWORD", "password", "secret"),
+            ("MT5_PATH", "path", "/opt/mt5/terminal64.exe"),
+        ],
+    )
+    def test_build_config_substitutes_field_with_opt_in(
         self,
         monkeypatch: pytest.MonkeyPatch,
+        env_var: str,
+        field: str,
+        env_value: str,
     ) -> None:
-        """build_config expands $ENV_NAME server when allow_whole_dollar_env=True."""
-        monkeypatch.setenv("MT5_SERVER", "Broker-Demo")
+        """Test build_config expands $ENV_NAME fields when opt-in is enabled."""
+        monkeypatch.setenv(env_var, env_value)
 
-        config = build_config(server="$MT5_SERVER", allow_whole_dollar_env=True)
+        config = build_config(**{field: f"${env_var}"}, allow_whole_dollar_env=True)  # type: ignore[arg-type]
 
-        assert config.server == "Broker-Demo"
-
-    def test_build_config_substitutes_password_with_opt_in(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-    ) -> None:
-        """build_config expands $ENV_NAME password when allow_whole_dollar_env=True."""
-        monkeypatch.setenv("MT5_PASSWORD", "secret")
-
-        config = build_config(password="$MT5_PASSWORD", allow_whole_dollar_env=True)
-
-        assert config.password == "secret"  # noqa: S105
-
-    def test_build_config_substitutes_path_with_opt_in(
-        self,
-        monkeypatch: pytest.MonkeyPatch,
-    ) -> None:
-        """Test build_config expands $ENV_NAME path when allow_whole_dollar_env=True."""
-        monkeypatch.setenv("MT5_PATH", "/opt/mt5/terminal64.exe")
-
-        config = build_config(path="$MT5_PATH", allow_whole_dollar_env=True)
-
-        assert config.path == "/opt/mt5/terminal64.exe"
+        assert getattr(config, field) == env_value
 
     def test_build_config_leaves_dollar_literal_by_default(
         self,
@@ -2436,3 +2425,263 @@ class TestThrottledHistoryUpdater:
             updater.update(MagicMock(), ["EURUSD"])
 
         assert updater.last_update_monotonic is None
+
+
+class TestBuildConfigStringLogin:
+    """Tests for build_config() string login coercion (issue #61)."""
+
+    @pytest.mark.parametrize(
+        ("login", "expected"),
+        [
+            (None, None),
+            (12345, 12345),
+            ("12345", 12345),
+            (" 12345 ", 12345),
+            ("", None),
+            ("   ", None),
+        ],
+    )
+    def test_coerces_login_from_string(
+        self,
+        login: int | str | None,
+        expected: int | None,
+    ) -> None:
+        """Test build_config coerces string login to int or None."""
+        config = build_config(login=login)
+        assert config.login == expected
+
+    def test_rejects_non_numeric_string_login(self) -> None:
+        """Test build_config raises ValueError for non-numeric string login."""
+        with pytest.raises(ValueError, match="invalid literal"):
+            build_config(login="abc")
+
+    def test_expands_dollar_brace_login_with_opt_in(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test build_config expands ${MT5_LOGIN} and coerces with opt-in."""
+        monkeypatch.setenv("MT5_LOGIN", "12345")
+        config = build_config(login="${MT5_LOGIN}", allow_whole_dollar_env=True)
+        assert config.login == 12345
+
+    def test_expands_whole_dollar_login_with_opt_in(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test build_config expands $MT5_LOGIN and coerces with opt-in."""
+        monkeypatch.setenv("MT5_LOGIN", "99999")
+        config = build_config(login="$MT5_LOGIN", allow_whole_dollar_env=True)
+        assert config.login == 99999
+
+    def test_missing_env_variable_raises(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test build_config raises ValueError when referenced env var is not set."""
+        monkeypatch.delenv("MT5_LOGIN", raising=False)
+        with pytest.raises(ValueError, match="'MT5_LOGIN' is not set"):
+            build_config(login="${MT5_LOGIN}", allow_whole_dollar_env=True)
+
+    def test_env_expands_to_blank_becomes_none(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test build_config coerces blank env-expanded login to None."""
+        monkeypatch.setenv("MT5_LOGIN", "")
+        config = build_config(login="${MT5_LOGIN}", allow_whole_dollar_env=True)
+        assert config.login is None
+
+    def test_dollar_brace_login_not_expanded_without_opt_in(self) -> None:
+        """Test ${MT5_LOGIN} is not expanded when allow_whole_dollar_env=False."""
+        with pytest.raises(ValueError, match="invalid literal"):
+            build_config(login="${MT5_LOGIN}")
+
+    def test_integer_login_preserved_backward_compat(self) -> None:
+        """Test existing int login callers remain backward-compatible."""
+        config = build_config(login=54321)
+        assert config.login == 54321
+
+    def test_none_login_preserved_backward_compat(self) -> None:
+        """Test existing None login callers remain backward-compatible."""
+        config = build_config(login=None)
+        assert config.login is None
+
+
+class TestSubstituteMappingValues:
+    """Tests for substitute_mapping_values() (issue #62)."""
+
+    def test_substitutes_selected_keys_in_flat_dict(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test selected keys are substituted in a flat mapping."""
+        monkeypatch.setenv("MT5_LOGIN", "12345")
+        data: dict[str, object] = {
+            "mt5_login": "${MT5_LOGIN}",
+            "strategy_name": "${MT5_LOGIN}",
+        }
+        result = substitute_mapping_values(data, keys={"mt5_login"})
+        assert result == {"mt5_login": "12345", "strategy_name": "${MT5_LOGIN}"}
+
+    def test_preserves_non_selected_literal_dollar_signs(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test literal dollar signs in non-selected fields are preserved exactly."""
+        monkeypatch.setenv("MT5_PASSWORD", "secret")
+        data: dict[str, object] = {
+            "mt5_password": "${MT5_PASSWORD}",
+            "notes": "$NOT_EXPANDED",
+        }
+        result = substitute_mapping_values(data, keys={"mt5_password"})
+        assert result == {"mt5_password": "secret", "notes": "$NOT_EXPANDED"}
+
+    def test_nested_dict_traversal_substitutes_selected_keys(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test selected keys inside nested dicts are substituted."""
+        monkeypatch.setenv("MT5_SERVER", "Broker-Demo")
+        data: dict[str, object] = {
+            "outer": {
+                "mt5_server": "${MT5_SERVER}",
+                "other": "${MT5_SERVER}",
+            }
+        }
+        result = substitute_mapping_values(data, keys={"mt5_server"})
+        assert result == {
+            "outer": {"mt5_server": "Broker-Demo", "other": "${MT5_SERVER}"}
+        }
+
+    def test_nested_list_traversal_substitutes_selected_keys(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test selected keys inside list elements are substituted."""
+        monkeypatch.setenv("MT5_LOGIN", "42")
+        data: dict[str, object] = {
+            "accounts": [
+                {"mt5_login": "${MT5_LOGIN}", "name": "${MT5_LOGIN}"},
+                {"mt5_login": "${MT5_LOGIN}", "name": "fixed"},
+            ]
+        }
+        result = substitute_mapping_values(data, keys={"mt5_login"})
+        assert result == {
+            "accounts": [
+                {"mt5_login": "42", "name": "${MT5_LOGIN}"},
+                {"mt5_login": "42", "name": "fixed"},
+            ]
+        }
+
+    def test_whole_dollar_expanded_with_opt_in(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test $ENV_NAME is expanded when allow_whole_dollar_env=True."""
+        monkeypatch.setenv("MT5_PASSWORD", "secret")
+        data: dict[str, object] = {"mt5_password": "$MT5_PASSWORD"}
+        result = substitute_mapping_values(
+            data,
+            keys={"mt5_password"},
+            allow_whole_dollar_env=True,
+        )
+        assert result == {"mt5_password": "secret"}
+
+    def test_whole_dollar_not_expanded_by_default(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test $ENV_NAME in a selected key is preserved when opt-in is False."""
+        monkeypatch.setenv("MT5_PASSWORD", "secret")
+        data: dict[str, object] = {"mt5_password": "$MT5_PASSWORD"}
+        result = substitute_mapping_values(data, keys={"mt5_password"})
+        assert result == {"mt5_password": "$MT5_PASSWORD"}
+
+    def test_blank_string_becomes_none_for_blank_keys(self) -> None:
+        """Test blank strings are normalised to None for blank_string_keys_as_none."""
+        data: dict[str, object] = {
+            "mt5_login": "",
+            "mt5_password": "  ",
+            "other": "",
+        }
+        result = substitute_mapping_values(
+            data,
+            keys=set(),
+            blank_string_keys_as_none={"mt5_login", "mt5_password"},
+        )
+        assert result == {"mt5_login": None, "mt5_password": None, "other": ""}
+
+    def test_env_expanded_blank_becomes_none(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test env-expanded blank string is normalised to None."""
+        monkeypatch.setenv("MT5_LOGIN", "")
+        data: dict[str, object] = {"mt5_login": "${MT5_LOGIN}"}
+        result = substitute_mapping_values(
+            data,
+            keys={"mt5_login"},
+            blank_string_keys_as_none={"mt5_login"},
+        )
+        assert result == {"mt5_login": None}
+
+    def test_missing_env_variable_raises_for_selected_key(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test missing env var for a selected key raises ValueError."""
+        monkeypatch.delenv("MT5_MISSING", raising=False)
+        data: dict[str, object] = {"mt5_login": "${MT5_MISSING}"}
+        with pytest.raises(ValueError, match="'MT5_MISSING' is not set"):
+            substitute_mapping_values(data, keys={"mt5_login"})
+
+    def test_non_string_values_preserved(self) -> None:
+        """Test non-string values under selected or non-selected keys are preserved."""
+        data: dict[str, object] = {
+            "mt5_login": 12345,
+            "timeout": 5000,
+            "enabled": True,
+            "ratio": 1.5,
+            "nothing": None,
+        }
+        result = substitute_mapping_values(
+            data, keys={"mt5_login", "timeout", "enabled", "ratio", "nothing"}
+        )
+        assert result == data
+
+    def test_caller_supplied_key_set_substitutes_correctly(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test helper works with any caller-supplied key set."""
+        monkeypatch.setenv("APP_LOGIN", "77777")
+        monkeypatch.setenv("APP_PASSWORD", "p4ss")
+        data: dict[str, object] = {
+            "app_login": "${APP_LOGIN}",
+            "app_password": "${APP_PASSWORD}",
+            "unrelated": "${APP_LOGIN}",
+        }
+        credential_keys = {"app_login", "app_password"}
+        result = substitute_mapping_values(data, keys=credential_keys)
+        assert result == {
+            "app_login": "77777",
+            "app_password": "p4ss",
+            "unrelated": "${APP_LOGIN}",
+        }
+
+    def test_scalar_data_returned_unchanged(self) -> None:
+        """Test a scalar (non-dict, non-list) value is returned as-is."""
+        assert substitute_mapping_values("hello", keys={"x"}) == "hello"
+        assert substitute_mapping_values(42, keys={"x"}) == 42
+        assert substitute_mapping_values(None, keys={"x"}) is None
+
+    def test_tuple_container_not_traversed(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test tuple containers are returned as-is without traversal."""
+        monkeypatch.setenv("MT5_LOGIN", "42")
+        data: dict[str, object] = {"accounts": ({"mt5_login": "${MT5_LOGIN}"},)}
+        result = substitute_mapping_values(data, keys={"mt5_login"})
+        # tuple is returned as-is; inner dict is NOT visited
+        assert result == {"accounts": ({"mt5_login": "${MT5_LOGIN}"},)}

tests/test_utils.py

@@ -4,21 +4,22 @@ from __future__ import annotations
 
 import json
 import sqlite3
+import sys
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
 import pandas as pd
 import pytest
 
+import mt5cli.utils
+
 if TYPE_CHECKING:
     from pathlib import Path
 
 from mt5cli.utils import (
     DATETIME_TYPE,
     REQUEST_TYPE,
-    TICK_FLAG_MAP,
     TICK_FLAGS_TYPE,
-    TIMEFRAME_MAP,
     TIMEFRAME_TYPE,
     Dataset,
     IfExists,
@@ -111,6 +112,17 @@ class TestExportDataframe:
         result = pd.read_parquet(output)
         pd.testing.assert_frame_equal(result, sample_df)
 
+    def test_export_parquet_without_pyarrow(
+        self,
+        tmp_path: Path,
+        sample_df: pd.DataFrame,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Test that a clear error is raised when pyarrow is not installed."""
+        monkeypatch.setitem(sys.modules, "pyarrow", None)
+        with pytest.raises(ImportError, match="mt5cli\\[parquet\\]"):
+            export_dataframe(sample_df, tmp_path / "out.parquet", "parquet")
+
     def test_export_sqlite3(self, tmp_path: Path, sample_df: pd.DataFrame) -> None:
         """Test SQLite3 export."""
         output = tmp_path / "out.db"
@@ -361,17 +373,13 @@ class TestParseRequest:
 class TestConstants:
     """Tests for module constants."""
 
-    def test_timeframe_map_has_expected_keys(self) -> None:
-        """Test that TIMEFRAME_MAP contains standard timeframes."""
-        for key in ("M1", "M5", "M15", "M30", "H1", "H4", "D1", "W1", "MN1"):
-            assert key in TIMEFRAME_MAP
+    def test_timeframe_map_is_private_in_utils(self) -> None:
+        """TIMEFRAME_MAP is a private implementation detail; not a public attribute."""
+        assert not hasattr(mt5cli.utils, "TIMEFRAME_MAP")
 
-    def test_tick_flag_map_has_expected_keys(self) -> None:
-        """Test that TICK_FLAG_MAP contains standard flags with MT5 values."""
-        assert {"ALL", "INFO", "TRADE"} <= set(TICK_FLAG_MAP)
-        assert TICK_FLAG_MAP["ALL"] == -1
-        assert TICK_FLAG_MAP["INFO"] == 1
-        assert TICK_FLAG_MAP["TRADE"] == 2
+    def test_tick_flag_map_absent_from_utils(self) -> None:
+        """TICK_FLAG_MAP is not exposed by mt5cli.utils."""
+        assert not hasattr(mt5cli.utils, "TICK_FLAG_MAP")
 
     @pytest.mark.parametrize(
         ("dataset", "expected"),

uv.lock

@@ -487,21 +487,26 @@ wheels = [
 
 [[package]]
 name = "mt5cli"
-version = "0.9.0"
+version = "1.0.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
     { name = "pdmt5" },
-    { name = "pyarrow" },
     { name = "typer" },
 ]
 
+[package.optional-dependencies]
+parquet = [
+    { name = "pyarrow" },
+]
+
 [package.dev-dependencies]
 dev = [
     { name = "mkdocs" },
     { name = "mkdocs-material" },
     { name = "mkdocstrings", extra = ["python"] },
     { name = "pandas-stubs" },
+    { name = "pyarrow" },
     { name = "pymdown-extensions" },
     { name = "pyright" },
     { name = "pytest" },
@@ -513,10 +518,11 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.1.0" },
-    { name = "pdmt5", specifier = ">=0.3.0" },
-    { name = "pyarrow", specifier = ">=19.0.0" },
+    { name = "pdmt5", specifier = ">=1.0.0" },
+    { name = "pyarrow", marker = "extra == 'parquet'", specifier = ">=19.0.0" },
     { name = "typer", specifier = ">=0.15.0" },
 ]
+provides-extras = ["parquet"]
 
 [package.metadata.requires-dev]
 dev = [
@@ -524,6 +530,7 @@ dev = [
     { name = "mkdocs-material", specifier = ">=9.7.6" },
     { name = "mkdocstrings", extras = ["python"], specifier = ">=1.0.4" },
     { name = "pandas-stubs", specifier = ">=2.2.3.250527" },
+    { name = "pyarrow", specifier = ">=19.0.0" },
     { name = "pymdown-extensions", specifier = ">=10.21.2" },
     { name = "pyright", specifier = ">=1.1.407" },
     { name = "pytest", specifier = ">=9.0.3" },
@@ -684,16 +691,16 @@ wheels = [
 
 [[package]]
 name = "pdmt5"
-version = "0.3.0"
+version = "1.0.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "metatrader5", marker = "sys_platform == 'win32'" },
     { name = "pandas" },
     { name = "pydantic" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/bf/cc/c8fa3a01e0e34178fec8527992f7bb8eda5881477ce23aaacaa9b2ef7bec/pdmt5-0.3.0.tar.gz", hash = "sha256:bb612d5c2695eafac9b2a7b74756e13bd383d7e5517bd90c9a2efa92492c484c", size = 215100, upload-time = "2026-06-11T13:26:46.976Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/21/6d/b51d2d0ec4636e914210be03a7da20e5078bc8cd7a351edd13bc30b7d2b1/pdmt5-1.0.0.tar.gz", hash = "sha256:ba53a1a5db41fdf4c022ef55353f5a4f6884f625c9310de2b0ddb20457956716", size = 123155, upload-time = "2026-06-25T23:41:50.503Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/f2/03/b12cc4c9db983d971c9172b3765161b6d91136d0624e6718a04dd815e7a1/pdmt5-0.3.0-py3-none-any.whl", hash = "sha256:5388b406cc583202600cfe22c9d781679b1d931b1ed5a2b5dcf37c566149b49f", size = 26250, upload-time = "2026-06-11T13:26:45.689Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/38/27b712c572d8146efddf571a0e4e7b6d2314a335eb0f47dec1f499ab2189/pdmt5-1.0.0-py3-none-any.whl", hash = "sha256:f969c17902f9ffcbf56d7ccf9285aab39ececd676fcca50c094abcf9d728d517", size = 23992, upload-time = "2026-06-25T23:41:49.067Z" },
 ]
 
 [[package]]