docs: rewrite open-source readmes

Rewrite the README pair as separate English and Chinese open-source project entry points.

Author: Pigbibi

README.md

@@ -2,63 +2,54 @@
 
 [Chinese README](README.zh-CN.md)
 
-> ⚠️ Investing involves risk. This project does not provide investment advice and is for educational and research purposes only.
+> Investing involves risk. This project does not provide investment advice and is for education, research, and engineering review only.
 
-## What this project does
+## What this repository is
 
-InteractiveBrokersPlatform is an **Execution platform** in the QuantStrategyLab ecosystem. It executes QuantStrategyLab US and Hong Kong equity strategies through Interactive Brokers runtime services, including account-group config, region handling, dry-run controls, and SEHK/HKD support.
+InteractiveBrokersPlatform is a QuantStrategyLab Interactive Brokers multi-market execution platform. It runs US and HK equity profiles through IBKR runtime services with dry-run, paper, and live controls.
 
-## Who this is for
+It is an execution layer, not a strategy research repository. Strategy logic comes from `UsEquityStrategies / HkEquityStrategies`; snapshot and validation artifacts come from `UsEquitySnapshotPipelines / HkEquitySnapshotPipelines` when a profile requires them.
 
-- Engineers and researchers who want to inspect, reproduce, or extend this part of the QuantStrategyLab stack.
-- Operators who need a clear entry point before reading the deeper runbooks or workflow files.
-- Reviewers who need to understand the repository purpose, safety boundary, and evidence requirements before enabling automation.
+## Runtime boundary
 
-## Current status
+- Loads only runtime-enabled strategy profiles exposed by the strategy packages.
+- Handles broker/API connectivity, dry-run checks, notifications, and deployment settings.
+- Must keep credentials in GitHub Secrets, cloud secret stores, or the broker-specific secret system, never in Git.
+- Should start with dry-run or paper mode before any live order path is enabled.
 
-Production-oriented broker integration; use paper or dry-run validation before real trading.
+## Direct vs snapshot-backed profiles
+
+Direct runtime profiles can usually run from market history or portfolio state. Snapshot-backed profiles need a current artifact bundle from the matching snapshot pipeline before this platform should execute them. The platform should not invent strategy eligibility; it should consume the status and artifacts published by the strategy and snapshot repositories.
+
+## Deploy safely
+
+1. Configure secrets and runtime variables outside Git.
+2. Run the workflow or service in dry-run mode.
+3. Review generated orders, logs, notifications, and reconciliation output.
+4. Confirm rollback steps and artifact versions.
+5. Enable scheduled or live execution only after the above checks are clear.
 
 ## Repository layout
 
-- `application/`, `entrypoints/`, `notifications/`, `strategy/`: Python package code.
-- `tests/`: unit and contract tests.
-- `docs/`: detailed design notes, runbooks, and evidence docs.
-- `.github/workflows/`: CI, scheduled jobs, and deployment workflows.
+- `tests/`: unit, contract, and regression tests.
+- `docs/`: runbooks, design notes, evidence, and integration contracts.
+- `.github/workflows/`: CI, scheduled jobs, release, or deployment workflows.
 - `scripts/`: operator scripts and local helpers.
+- `research/`: research configs and non-live candidate artifacts.
 
 ## Quick start
 
-From a fresh clone:
-
 ```bash
 python -m pip install -r requirements.txt
 python -m pytest -q
 ```
 
-If a command requires credentials, run it only after reading the relevant workflow or runbook and configuring secrets outside Git.
-
-## Deployment and operation
-
-Prepare IBKR connectivity, account identifiers, runtime variables, and strategy source. Run the workflow or service in dry-run mode, verify orders and notifications, then schedule production runs.
-
-Prefer manual or dry-run execution first. Enable schedules or live execution only after logs, artifacts, permissions, and rollback steps are reviewed.
-
-## Strategy performance and evidence
-
-Execution performance is measured by reliability and order correctness. Strategy performance must be reviewed in the strategy/snapshot repositories before routing orders through IBKR.
-
-README files are intentionally not a source of dated performance promises. Re-run the relevant tests, backtests, or pipeline jobs before relying on any result.
-
-## Safety notes
-
-- Never commit API keys, broker credentials, OAuth tokens, cookies, or account identifiers.
-- Run new strategies and platform changes in dry-run or paper mode before any live execution.
-- Review generated orders, artifacts, and logs manually before enabling schedules.
-
-## Contributing
+## Useful docs
 
-Keep changes small, reproducible, and covered by the narrowest useful tests. For strategy-facing changes, include the evidence artifact or command used to validate behavior.
+- [`docs/hk_equity_runtime.md`](docs/hk_equity_runtime.md)
+- [`docs/ibkr_paper_top50_switch.md`](docs/ibkr_paper_top50_switch.md)
+- [`docs/ibkr_runtime_rollout.md`](docs/ibkr_runtime_rollout.md)
 
 ## License
 
-See [LICENSE](LICENSE) if present in this repository.
+See [LICENSE](LICENSE).

README.zh-CN.md

@@ -2,63 +2,54 @@
 
 [English README](README.md)
 
-> ⚠️ 投资有风险，不构成投资建议，仅供学习交流用途。
+> 投资有风险。本项目不构成投资建议，仅用于学习、研究和工程审阅。
 
-## 这个项目做什么
+## 这个仓库是什么
 
-InteractiveBrokersPlatform 是 QuantStrategyLab 体系中的**执行平台**。通过 Interactive Brokers 执行 QuantStrategyLab 的美股和港股策略，包含账户组配置、区域处理、dry-run 控制以及港股/HKD 支持。
+InteractiveBrokersPlatform 是 QuantStrategyLab 的Interactive Brokers 多市场执行平台。通过 IBKR 运行服务执行美股和港股 profile，支持 dry-run、paper 和 live 控制。
 
-## 适合谁使用
+它属于执行层，不是策略研究仓库。策略逻辑来自 `UsEquityStrategies / HkEquityStrategies`；如果 profile 依赖 snapshot，验证和产物来自 `UsEquitySnapshotPipelines / HkEquitySnapshotPipelines`。
 
-- 希望阅读、复现或扩展 QuantStrategyLab 相关模块的工程师和研究人员。
-- 在阅读详细 runbook 或 workflow 前，需要先理解项目入口的运维人员。
-- 在启用自动化前，需要确认项目职责、安全边界和证据要求的 reviewer。
+## 运行边界
 
-## 当前状态
+- 只加载策略包暴露的 runtime-enabled profile。
+- 负责券商/API 连接、dry-run 检查、通知和部署配置。
+- 凭据必须放在 GitHub Secrets、云密钥系统或券商专用密钥系统中，不能提交到 Git。
+- 任何 live 下单路径启用前，都应先从 dry-run 或 paper mode 开始。
 
-生产型券商接入；真实交易前必须先完成 paper 或 dry-run 验证。
+## 普通 profile 与 snapshot-backed profile
+
+普通 runtime profile 通常可以直接基于 market history 或 portfolio state 执行。Snapshot-backed profile 需要先从对应 snapshot pipeline 获取当前 artifact bundle，平台才应该执行。平台不应该自行判断策略资格，而应消费策略仓和 snapshot 仓发布的状态与产物。
+
+## 安全部署顺序
+
+1. 在 Git 之外配置 secrets 和 runtime variables。
+2. 先以 dry-run 模式运行 workflow 或服务。
+3. 检查生成订单、日志、通知和 reconciliation 输出。
+4. 确认回滚步骤和 artifact 版本。
+5. 上述检查清楚后，再启用定时任务或 live 执行。
 
 ## 仓库结构
 
-- `application/`, `entrypoints/`, `notifications/`, `strategy/`：Python 包代码。
-- `tests/`：单元测试和契约测试。
-- `docs/`：详细设计说明、运行手册和证据文档。
-- `.github/workflows/`：CI、定时任务和部署 workflow。
+- `tests/`：单元测试、契约测试和回归测试。
+- `docs/`：运行手册、设计说明、证据和集成契约。
+- `.github/workflows/`：CI、定时任务、发布或部署 workflow。
 - `scripts/`：运维脚本和本地辅助工具。
+- `research/`：研究配置和非 live 候选产物。
 
 ## 快速开始
 
-从全新 clone 开始：
-
 ```bash
 python -m pip install -r requirements.txt
 python -m pytest -q
 ```
 
-如果命令需要凭据，请先阅读相关 workflow 或 runbook，并把密钥配置在 Git 之外。
-
-## 部署和运行
-
-准备 IBKR 连接、账户标识、运行变量和策略来源。先以 dry-run 运行 workflow 或服务，确认订单和通知无误后再启用生产定时任务。
-
-建议先手工运行或 dry-run。只有在日志、产物、权限和回滚步骤都检查过之后，才启用定时任务或 live 执行。
-
-## 策略表现与证据边界
-
-执行平台关注可靠性和订单正确性。策略表现需要在策略/快照仓库中确认后，才能通过 IBKR 路由订单。
-
-README 不应该承诺固定收益或过期指标。实际使用前，请重新运行对应测试、回测或流水线任务。
-
-## 安全注意事项
-
-- 不要把 API key、券商凭据、OAuth token、Cookie 或账户标识提交到 Git。
-- 新策略或平台变更在 live 前必须先跑 dry-run 或 paper 流程。
-- 启用定时任务前，需要人工检查生成的订单、产物和日志。
-
-## 参与贡献
+## 延伸文档
 
-请保持改动小、可复现，并用最小必要测试覆盖。涉及策略的改动，需要附上验证行为的证据产物或命令。
+- [`docs/hk_equity_runtime.md`](docs/hk_equity_runtime.md)
+- [`docs/ibkr_paper_top50_switch.md`](docs/ibkr_paper_top50_switch.md)
+- [`docs/ibkr_runtime_rollout.md`](docs/ibkr_runtime_rollout.md)
 
 ## 许可证
 
-如仓库包含 [LICENSE](LICENSE)，请以该文件为准。
+详见 [LICENSE](LICENSE)。