Pigbibi · Oct 16, 2026 · Oct 16, 2026
diff --git a/README.md b/README.md
@@ -1,61 +1,78 @@
 # PoliticalEventTrackingResearch
 
-[Chinese README](README.zh-CN.md)
+Research-only pipeline that tracks public political and policy event evidence for US equity research.
 
-> Investing involves risk. This project does not provide investment advice and is for education, research, and engineering review only.
+English | [简体中文](README.zh-CN.md)
 
-## What this repository is
+## Status
 
-PoliticalEventTrackingResearch is a QuantStrategyLab public event evidence pipeline. It tracks public political and policy event evidence for US equity research context.
+Experimental. Use at your own risk. This project is not financial advice and
+does not guarantee any trading result. Its outputs are research evidence, not
+trading instructions.
 
-It produces research, audit, or orchestration artifacts. It should not submit broker orders or mutate live allocations by itself.
+## What this is
 
-## QSL architecture role
+PoliticalEventTrackingResearch ingests public political and policy sources,
+such as free RSS feeds and official disclosures, and builds traceable research
+artifacts: source items, extracted events, watchlist matches, and event-study
+inputs. It reads only public sources and writes CSV and JSON output, so a
+researcher can reproduce an evidence trail for US equity context. It is aimed
+at research and engineering review, not at live trading.
 
-- **Layer**: `research`.
-- **Responsibility**: public political and policy event evidence pipeline.
-- **Owns**: source items, source events, traceable research evidence.
-- **Consumes**: public RSS/web sources and downstream research consumers.
-- **Must not**: produce automatic trading instructions or mutate allocations.
+## What this is not
 
-## Output boundary
+It does not place broker orders. It does not mutate live allocations. It does
+not produce automatic trading instructions, and its reports are not
+recommendations.
 
-- Treat generated reports as evidence or review material, not automatic trading instructions.
-- Keep source traceability and artifact timestamps visible.
-- Require human review before using outputs in downstream strategy or platform changes.
-- Keep credentials, private data, and external service tokens out of Git and logs.
+## Quick start
 
-## Repository layout
+Requires Python 3.11 or newer.
 
-- `src/`: library and runtime code.
-- `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.
-- `config/`: runtime or pipeline configuration.
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+```
 
-## Quick start
+Explore the command-line entry points (each supports `--help`):
 
 ```bash
-python -m pip install -e .
-python -m pytest -q
+petr-fetch-rss-sources --help
+petr-import-official-events --help
+petr-build-tracker --help
+```
+
+## Configuration
+
+The pipeline is configured through input files rather than environment
+variables. Copy the matching file from `examples/` and edit it.
+
+| File | Required | Purpose |
+|---|---|---|
+| `config/free_rss_feeds.csv` | No | Default public RSS feed list. |
+| `config/core_us_equity_aliases.csv` | No | Symbol and name aliases used when matching sources to tickers. |
+| `examples/*.csv` | No | Sample inputs for local runs. |
+
+## Repository layout
+
+```
+src/        library code and command implementations
+scripts/    command-line helpers
+config/     default feed and alias tables
+examples/   sample inputs
+docs/       design notes and output contracts
+tests/      unit and contract tests
 ```
 
-## Useful docs
+## Contributing
 
-- [`docs/free_source_setup.zh-CN.md`](docs/free_source_setup.zh-CN.md)
-- [`docs/research_plan.zh-CN.md`](docs/research_plan.zh-CN.md)
-- [`docs/source_ingestion_options.md`](docs/source_ingestion_options.md)
-- [`docs/source_registry.md`](docs/source_registry.md)
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## Community and security
+## Security
 
-- See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request scope, local verification, and documentation expectations.
-- Follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for maintainer and contributor conduct.
-- Report credential, automation, broker, exchange, or cloud-resource vulnerabilities through [SECURITY.md](SECURITY.md); do not open public issues for secrets or live-execution risk.
+See [SECURITY.md](SECURITY.md). Do not open a public issue for a vulnerability.
+Keep credentials, private data, and external service tokens out of Git and logs.
 
 ## License
 
-See [LICENSE](LICENSE).
-
-[Project scope and operating reference](docs/project-reference.md).
+MIT. See [LICENSE](LICENSE).
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -1,59 +1,67 @@
 # PoliticalEventTrackingResearch
 
-[English README](README.md)
+面向美股研究的公开政治与政策事件证据管线。
 
-> 投资有风险。本项目不构成投资建议，仅用于学习、研究和工程审阅。
+[English](README.md) | 简体中文
 
-## 这个仓库是什么
+## 状态
 
-PoliticalEventTrackingResearch 是 QuantStrategyLab 的公开事件证据流水线。追踪政治与政策公开事件证据，为美股研究提供上下文。
+实验性项目，使用风险自负。本项目不构成投资建议，也不保证任何交易结果。它的输出是研究证据，不是交易指令。
 
-它产出研究、审计或编排类 artifact，不应自行提交券商订单，也不应直接修改 live allocation。
+## 简介
 
-## QSL 架构角色
+PoliticalEventTrackingResearch 采集公开的政治与政策来源（例如免费的 RSS feed 和官方披露），并生成可追溯的研究产物：来源条目、抽取出的活动、关注列表匹配结果和事件研究输入。它只读取公开来源，输出 CSV 和 JSON，让研究者可以复现一条美股研究所需的证据链。它面向研究与工程审阅，不面向实盘交易。
 
-- **层级**：`研究/证据`。
-- **职责**：公开政治/政策事件证据流水线。
-- **事实源/归属**：source items、source events、可追溯研究证据。
-- **消费对象**：公开 RSS/web sources 和下游研究消费者。
-- **禁止事项**：生成自动交易指令或修改 allocations。
+## 不适用范围
 
-## 输出边界
+它不提交券商订单。它不改变实盘仓位分配。它不产生自动交易指令，其报告也不构成投资建议。
 
-- 生成报告应作为证据或审阅材料，不是自动交易指令。
-- 保留来源可追溯性和 artifact 时间戳。
-- 输出用于下游策略或平台改动前，需要人工 review。
-- 凭据、私人数据和外部服务 token 不能提交到 Git，也不能写入日志。
+## 快速开始
 
-## 仓库结构
+需要 Python 3.11 或更高版本。
 
-- `src/`：库代码和运行时代码。
-- `tests/`：单元测试、契约测试和回归测试。
-- `docs/`：运行手册、设计说明、证据和集成契约。
-- `.github/workflows/`：CI、定时任务、发布或部署 workflow。
-- `scripts/`：运维脚本和本地辅助工具。
-- `config/`：运行或流水线配置。
+```bash
+python -m pip install -e '.[test]'
+python -m pytest -q
+```
 
-## 快速开始
+命令行入口（均支持 `--help`）：
 
 ```bash
-python -m pip install -e .
-python -m pytest -q
+petr-fetch-rss-sources --help
+petr-import-official-events --help
+petr-build-tracker --help
+```
+
+## 配置
+
+本管线通过输入文件配置，而不是环境变量。把 `examples/` 中的对应文件复制出来再修改。
+
+| 文件 | 必填 | 用途 |
+|---|---|---|
+| `config/free_rss_feeds.csv` | 否 | 默认的公开 RSS feed 列表。 |
+| `config/core_us_equity_aliases.csv` | 否 | 把来源匹配到代码时使用的符号与名称别名表。 |
+| `examples/*.csv` | 否 | 本地运行用的示例输入。 |
+
+## 仓库结构
+
+```
+src/        库代码和命令实现
+scripts/    命令行辅助脚本
+config/     默认 feed 与别名表
+examples/   示例输入
+docs/       设计说明与输出契约
+tests/      单元与契约测试
 ```
 
-## 延伸文档
+## 参与贡献
 
-- [`docs/free_source_setup.zh-CN.md`](docs/free_source_setup.zh-CN.md)
-- [`docs/research_plan.zh-CN.md`](docs/research_plan.zh-CN.md)
-- [`docs/source_ingestion_options.md`](docs/source_ingestion_options.md)
-- [`docs/source_registry.md`](docs/source_registry.md)
+见 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
-## 社区和安全
+## 安全
 
-- 贡献前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，确认 PR 范围、本地校验和文档要求。
-- 讨论、issue 和 review 请遵守 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。
-- 涉及密钥、自动化、券商/交易所或云资源的漏洞请按 [SECURITY.md](SECURITY.md) 私密报告；不要为 secret 或实盘风险开公开 issue。
+见 [SECURITY.md](SECURITY.md)。安全漏洞不要开公开 issue，也不要让凭据、私有数据和外部服务 token 进入 Git 或日志。
 
 ## 许可证
 
-详见 [LICENSE](LICENSE)。
+MIT，见 [LICENSE](LICENSE)。