Reorganize market docs and primers

README.md

@@ -29,55 +29,55 @@ structure so the two versions can be read side by side; docs marked
 Market-neutral educational material — no venture-specific analysis.
 与具体业务无关的背景知识读物。
 
-**`primers/grid/` — the grid & markets series 电网与市场系列** (read in order 按序阅读):
+**Grid & markets series 电网与市场系列** (read in order 按序阅读):
 
 | # | EN | 中文 | Contents 内容 |
 |---|---|---|---|
-| 01 | [01_how_the_grid_works_en.md](primers/grid/01_how_the_grid_works_en.md) | [zh](primers/grid/01_how_the_grid_works_zh.md) | Grid physics, the balancing act, blackouts — from first principles. 电网物理原理、实时平衡与停电机理。 |
-| 02 | [02_us_electricity_markets_en.md](primers/grid/02_us_electricity_markets_en.md) | [zh](primers/grid/02_us_electricity_markets_zh.md) | How US wholesale markets are organized. 美国批发电力市场结构。 |
-| 03 | [03_china_electricity_markets_en.md](primers/grid/03_china_electricity_markets_en.md) | [zh](primers/grid/03_china_electricity_markets_zh.md) | China's market structure and reform path. 中国电力市场结构与改革路径。 |
-| 04 | [04_market_mechanics_companion_en.md](primers/grid/04_market_mechanics_companion_en.md) | [zh](primers/grid/04_market_mechanics_companion_zh.md) | Market mechanics companion — clearing, pricing, settlement. 市场机制手册——出清、定价、结算。 |
-| 05 | [05_trading_under_uncertainty_en.md](primers/grid/05_trading_under_uncertainty_en.md) | [zh](primers/grid/05_trading_under_uncertainty_zh.md) | Trading under uncertainty. 不确定性下的交易。 |
+| 01 | [core_01_how_the_grid_works_en.md](primers/core_01_how_the_grid_works_en.md) | [zh](primers/core_01_how_the_grid_works_zh.md) | Grid physics, the balancing act, blackouts — from first principles. 电网物理原理、实时平衡与停电机理。 |
+| 02 | [core_02_us_electricity_markets_en.md](primers/core_02_us_electricity_markets_en.md) | [zh](primers/core_02_us_electricity_markets_zh.md) | How US wholesale markets are organized. 美国批发电力市场结构。 |
+| 03 | [core_03_china_electricity_markets_en.md](primers/core_03_china_electricity_markets_en.md) | [zh](primers/core_03_china_electricity_markets_zh.md) | China's market structure and reform path. 中国电力市场结构与改革路径。 |
+| 04 | [core_04_market_mechanics_companion_en.md](primers/core_04_market_mechanics_companion_en.md) | [zh](primers/core_04_market_mechanics_companion_zh.md) | Market mechanics companion — clearing, pricing, settlement. 市场机制手册——出清、定价、结算。 |
+| 05 | [core_05_trading_under_uncertainty_en.md](primers/core_05_trading_under_uncertainty_en.md) | [zh](primers/core_05_trading_under_uncertainty_zh.md) | Trading under uncertainty. 不确定性下的交易。 |
 
 **Topical primers 专题读物**:
 
 | Doc 文档 | EN | 中文 | Contents 内容 |
 |---|---|---|---|
-| Power grid & AC fundamentals 电网与交流电基础 | [power_grid_ac_fundamentals_en.md](primers/power_grid_ac_fundamentals_en.md) | [power_grid_ac_fundamentals_zh.md](primers/power_grid_ac_fundamentals_zh.md) | Grid structure, AC, impedance, inductors, capacitors, and Kirchhoff’s laws. 电网结构、交流电、阻抗、电感、电容与基尔霍夫定律。 |
-| SCUC & SCED | [scuc_sced_en.md](primers/scuc_sced_en.md) | EN only | The two optimization problems that clear US wholesale markets; N-1 security, LMP as dual variables. 出清美国批发市场的两大优化问题。 |
-| Newsvendor 报童模型 | [newsvendor_en.md](primers/newsvendor_en.md) | EN only | The newsvendor problem applied to electricity bidding — underpins the bid loop in `pjm/design_models_*`. 报童模型在电力竞价中的应用。 |
-| Stochastic optimization 随机优化 | [stochastic_optimization_en.md](primers/stochastic_optimization_en.md) | EN only | Stochastic optimization in power systems — scenarios, recourse, hydro, offering under uncertainty. 电力系统中的随机优化。 |
+| Power grid & AC fundamentals 电网与交流电基础 | [technical_power_grid_ac_fundamentals_en.md](primers/technical_power_grid_ac_fundamentals_en.md) | [technical_power_grid_ac_fundamentals_zh.md](primers/technical_power_grid_ac_fundamentals_zh.md) | Grid structure, AC, impedance, inductors, capacitors, and Kirchhoff’s laws. 电网结构、交流电、阻抗、电感、电容与基尔霍夫定律。 |
+| SCUC & SCED | [technical_scuc_sced_en.md](primers/technical_scuc_sced_en.md) | EN only | The two optimization problems that clear US wholesale markets; N-1 security, LMP as dual variables. 出清美国批发市场的两大优化问题。 |
+| PJM market PJM 市场 | [market_pjm_en.md](primers/market_pjm_en.md) | [market_pjm_zh.md](primers/market_pjm_zh.md) | PJM explained for readers familiar with China's market. 面向熟悉中国市场读者的 PJM 入门。 |
+| Newsvendor 报童模型 | [technical_newsvendor_en.md](primers/technical_newsvendor_en.md) | EN only | The newsvendor problem applied to electricity bidding — underpins the bid loop in `markets/us/pjm/design_models_*`. 报童模型在电力竞价中的应用。 |
+| Stochastic optimization 随机优化 | [technical_stochastic_optimization_en.md](primers/technical_stochastic_optimization_en.md) | EN only | Stochastic optimization in power systems — scenarios, recourse, hydro, offering under uncertainty. 电力系统中的随机优化。 |
 
-### `us_market/` — US market reference 美国市场综述
+### `markets/us/` — US market reference 美国市场综述
 
 | Doc 文档 | EN | 中文 | Contents 内容 |
 |---|---|---|---|
-| Field guide 实务指南 | [field_guide_en.md](us_market/field_guide_en.md) | EN only | Bidding, trading, and the impact of AI — consolidated working discussions, July 2026. 竞价、交易与 AI 影响综合笔记。 |
-| Economists survey 经济学家综述 | [economists_survey_en.md](us_market/economists_survey_en.md) | [economists_survey_zh.md](us_market/economists_survey_zh.md) | How economists shaped US electricity markets — theory, practice, milestones. 经济学家如何塑造美国电力市场——理论、实践与里程碑。 |
-| Forecasting open ecosystem 预测开放生态 | [forecasting_open_ecosystem_en.md](us_market/forecasting_open_ecosystem_en.md) | EN only | Open US wholesale-market datasets, models, benchmarks, structural tools, and evaluation design for price, load, renewable, and capacity forecasting. 美国批发电力市场预测的开放数据、模型、基准、结构化工具与评估设计。 |
+| Field guide 实务指南 | [field_guide_en.md](markets/us/field_guide_en.md) | EN only | Bidding, trading, and the impact of AI — consolidated working discussions, July 2026. 竞价、交易与 AI 影响综合笔记。 |
+| Economists survey 经济学家综述 | [economists_survey_en.md](markets/us/economists_survey_en.md) | [economists_survey_zh.md](markets/us/economists_survey_zh.md) | How economists shaped US electricity markets — theory, practice, milestones. 经济学家如何塑造美国电力市场——理论、实践与里程碑。 |
+| Forecasting open ecosystem 预测开放生态 | [forecasting_open_ecosystem_en.md](markets/us/forecasting_open_ecosystem_en.md) | EN only | Open US wholesale-market datasets, models, benchmarks, structural tools, and evaluation design for price, load, renewable, and capacity forecasting. 美国批发电力市场预测的开放数据、模型、基准、结构化工具与评估设计。 |
 
-### `pjm/` — US market 美国市场
+### `markets/us/pjm/` — PJM product research PJM 产品研究
 
 | Doc 文档 | EN | 中文 | Contents 内容 |
 |---|---|---|---|
-| Market primer 市场入门 | [market_primer_en.md](pjm/market_primer_en.md) | [market_primer_zh.md](pjm/market_primer_zh.md) | PJM explained for readers familiar with China's market — institutions, DA/RT, LMP, virtuals/FTR, RPM, BORD, tax credits, with a PJM–China comparison table. 面向熟悉中国市场读者的 PJM 入门，含中美对照表。 |
-| Product design 产品设计 | [design_models_en.md](pjm/design_models_en.md) | [design_models_zh.md](pjm/design_models_zh.md) | Models A–C (price regime, probabilistic production, DA–RT spread), the newsvendor bid loop, BORD, data/licensing, build order, glossary. 模型 A–C、报童竞价闭环、BORD、数据与许可、建设顺序、术语表。 |
-| Vendor due diligence 供应商尽调 | [vendor_dd_en.md](pjm/vendor_dd_en.md) | [vendor_dd_zh.md](pjm/vendor_dd_zh.md) | Six US autobidder/optimization vendors profiled (Fluence Mosaic, Ascend SmartBidder, Tyba, Gridmatic, Dexter, enspired), comparative matrix, whitespace synthesis. 六家美国竞价优化服务商档案、对比矩阵与空白研判。 |
+| Product design 产品设计 | [design_models_en.md](markets/us/pjm/design_models_en.md) | [design_models_zh.md](markets/us/pjm/design_models_zh.md) | Models A–C (price regime, probabilistic production, DA–RT spread), the newsvendor bid loop, BORD, data/licensing, build order, glossary. 模型 A–C、报童竞价闭环、BORD、数据与许可、建设顺序、术语表。 |
+| Vendor due diligence 供应商尽调 | [vendor_dd_en.md](markets/us/pjm/vendor_dd_en.md) | [vendor_dd_zh.md](markets/us/pjm/vendor_dd_zh.md) | Six US autobidder/optimization vendors profiled (Fluence Mosaic, Ascend SmartBidder, Tyba, Gridmatic, Dexter, enspired), comparative matrix, whitespace synthesis. 六家美国竞价优化服务商档案、对比矩阵与空白研判。 |
 
-### `china/` — China market 中国市场
+### `markets/china/` — China market 中国市场
 
 | Doc 文档 | EN | 中文 | Contents 内容 |
 |---|---|---|---|
-| Market & vendor DD 市场与供应商尽调 | [market_vendor_dd_en.md](china/market_vendor_dd_en.md) | [market_vendor_dd_zh.md](china/market_vendor_dd_zh.md) | China market primer (Doc 136/394, mechanism price, MLT–spot deep dive §1.4–1.6, bargaining dynamics), six Chinese vendors (国能日新, 远景, 清能互联, 清鹏, 兰木达, 心知能源), synthesis, glossary. 中国市场入门（含中长期深度解析）、六家中国服务商、综合研判、术语表。 |
-| Product design 产品设计 | [product_design_en.md](china/product_design_en.md) | [product_design_zh.md](china/product_design_zh.md) | Chinese adaptations of Models A–C and the full Model D spec (MLT position optimizer) with the hedge-ratio mathematics, build order, open questions. 模型 A–C 中国化调整与模型 D（中长期头寸优化器）完整规格及数学推导。 |
+| Market & vendor DD 市场与供应商尽调 | [market_vendor_dd_en.md](markets/china/market_vendor_dd_en.md) | [market_vendor_dd_zh.md](markets/china/market_vendor_dd_zh.md) | China market primer (Doc 136/394, mechanism price, MLT–spot deep dive §1.4–1.6, bargaining dynamics), six Chinese vendors (国能日新, 远景, 清能互联, 清鹏, 兰木达, 心知能源), synthesis, glossary. 中国市场入门（含中长期深度解析）、六家中国服务商、综合研判、术语表。 |
+| Product design 产品设计 | [product_design_en.md](markets/china/product_design_en.md) | [product_design_zh.md](markets/china/product_design_zh.md) | Chinese adaptations of Models A–C and the full Model D spec (MLT position optimizer) with the hedge-ratio mathematics, build order, open questions. 模型 A–C 中国化调整与模型 D（中长期头寸优化器）完整规格及数学推导。 |
 
 ## Suggested reading order 建议阅读顺序
 
-1. **New to power markets entirely 电力市场零基础** → `primers/grid/01–05` in order 按序阅读
-2. **New to PJM 不熟悉 PJM** → `pjm/market_primer_*` → `pjm/design_models_*`
-3. **New to China's market 不熟悉中国市场** → `china/market_vendor_dd_*` §1 → `china/product_design_*`
+1. **New to power markets entirely 电力市场零基础** → `primers/core_01–05` in order 按序阅读
+2. **New to PJM 不熟悉 PJM** → `primers/market_pjm_*` → `markets/us/pjm/design_models_*`
+3. **New to China's market 不熟悉中国市场** → `markets/china/market_vendor_dd_*` §1 → `markets/china/product_design_*`
 4. **Business/competitive view 商业与竞争视角** → the two vendor DD docs 两份供应商尽调 → synthesis sections 综合研判章节
-5. **Modeling 建模视角** → `primers/newsvendor_en.md` + `primers/stochastic_optimization_en.md` → `pjm/design_models_*` (A–C + newsvendor) → `china/product_design_*` (Model D math)
+5. **Modeling 建模视角** → `primers/technical_newsvendor_en.md` + `primers/technical_stochastic_optimization_en.md` → `markets/us/pjm/design_models_*` (A–C + newsvendor) → `markets/china/product_design_*` (Model D math)
 
 ## Conventions 体例约定
 

markets/china/product_design_en.md

@@ -1,7 +1,7 @@
 # China Product Design: Forecasting & Optimization Models for Renewable Power Trading
 
 **Working design document — v0.1 (July 2026)**
-**Companion to:** `../pjm/design_models_en.md` (PJM design, Models A–C) and
+**Companion to:** `../us/pjm/design_models_en.md` (PJM design, Models A–C) and
 `market_vendor_dd_en.md` (market & vendor context, esp. §1.4–1.6).
 
 Scope: the China product line. Models A–C are imported by reference with their
@@ -43,7 +43,7 @@ declaration (报量报价) → (6) RT. Model D owns (1)–(4); the DA optimizer
 
 | Model | PJM spec | Chinese delta |
 |---|---|---|
-| A — price level/regime | `../pjm/design_models_en.md` §1 | Per-province spot forecasting (DA & RT); negative-price/floor-hit and cap-hit classifiers; supply-demand regime. **New job: monthly-horizon time-weighted spot forecasts per contract segment (D's key input).** Structural-lite features adapt: provincial supply stack, coal price, inter-provincial flows, mechanism/MLT disclosure data |
+| A — price level/regime | `../us/pjm/design_models_en.md` §1 | Per-province spot forecasting (DA & RT); negative-price/floor-hit and cap-hit classifiers; supply-demand regime. **New job: monthly-horizon time-weighted spot forecasts per contract segment (D's key input).** Structural-lite features adapt: provincial supply stack, coal price, inter-provincial flows, mechanism/MLT disclosure data |
 | B — production quantiles | §2 | Same two-stage pipeline and calibration discipline. **New requirement: monthly production distributions** (sum of hourly, with intra-month correlation preserved — ensemble/scenario route preferred over pure quantile regression). Dual monetization: 两个细则 assessment avoidance + bidding |
 | C — DA–RT spread | §3 | Same regime × conditional-distribution × covariance architecture on the DA-vs-RT deviation settlement. Congestion layer largely replaced by provincial supply-demand and renewable-surplus regimes (zonal pricing); 两个细则 assessment terms enter the optimizer alongside the spread (the "BORD-style" analog — see design doc §4.1 contrast) |
 

markets/china/product_design_zh.md

@@ -1,7 +1,7 @@
 # 中国产品设计：新能源电力交易的预测与优化模型
 
 **工作设计文档 —— v0.1（2026年7月）**
-**配套文档：** `../pjm/design_models_zh.md`（PJM 设计，模型 A–C）与 `market_vendor_dd_zh.md`（市场与供应商背景，尤其 1.4–1.6 节）。
+**配套文档：** `../us/pjm/design_models_zh.md`（PJM 设计，模型 A–C）与 `market_vendor_dd_zh.md`（市场与供应商背景，尤其 1.4–1.6 节）。
 
 范围：中国产品线。模型 A–C 以引用方式导入，其中国化调整在第一节汇总；模型 D——中长期头寸优化器，在 PJM 无对应物——在本文档中获得完整的一级规格说明，包括合同头寸问题的数学表述。
 
@@ -34,7 +34,7 @@
 
 | 模型 | PJM 规格 | 中国增量 |
 |---|---|---|
-| A——价格水平/状态 | `../pjm/design_models_zh.md` 第 1 节 | 分省现货预测（日前与实时）；负电价/触底与触顶分类器；供需格局。 **新任务：按合同分段的月度尺度加权现货预测（D 的关键输入）。** 轻量结构化特征相应调整：省级供给堆栈、煤价、省间来电、机制/中长期披露数据 |
+| A——价格水平/状态 | `../us/pjm/design_models_zh.md` 第 1 节 | 分省现货预测（日前与实时）；负电价/触底与触顶分类器；供需格局。 **新任务：按合同分段的月度尺度加权现货预测（D 的关键输入）。** 轻量结构化特征相应调整：省级供给堆栈、煤价、省间来电、机制/中长期披露数据 |
 | B——出力分位数 | 第 2 节 | 两阶段管线与校准纪律不变。 **新要求：月度出力分布** （逐小时加总且保留月内相关性——优先采用集合/情景路线而非纯分位数回归）。双重变现：规避"两个细则"考核 + 竞价 |
 | C——日前–实时价差 | 第 3 节 | 在日前对实时的偏差结算上沿用"状态分类 × 条件分布 × 协方差"架构。阻塞层大体被省级供需与新能源过剩状态取代（分区/统一定价）；"两个细则"考核项与价差一同进入优化器（即"BORD 类"机制的对应物——见 PJM 设计文档 4.1 节的对照） |
 

primers/market_pjm_en.md

@@ -1,10 +1,10 @@
 # PJM Market Primer: Written for Readers Familiar with China's Power Market
 
 **Working document — v0.1 (July 2026)**
-**Positioning:** the mirror of Section 1 of `../china/market_vendor_dd_en.md`
+**Positioning:** the mirror of Section 1 of `../markets/china/market_vendor_dd_en.md`
 (the China market primer) — it explains PJM for readers who know China's
 market, with Chinese concepts as the constant point of comparison. Chinese
-version: `market_primer_zh.md`.
+version: `market_pjm_zh.md`.
 
 ---
 
@@ -114,7 +114,7 @@ cost. One-line contrast: **PJM prices the externality; China grades the
 homework.** Product implication: in PJM, deviations are optimized against a
 forecastable stochastic *price*; in China, forecasts are engineered against
 a fixed *rulebook* — which is why China developed a compliance-procurement
-forecasting market and the US never did. (Details: `design_models_en.md`
+forecasting market and the US never did. (Details: `../markets/us/pjm/design_models_en.md`
 §4.1.)
 
 ## 6. Renewables: tax credits, not mechanism prices
@@ -193,5 +193,5 @@ procurement). Policy support flows through **tax credits**:
 
 ---
 
-*Glossary: appendix of `design_models_en.md`; China-side concepts: appendix
-of `../china/market_vendor_dd_en.md`.*
+*Glossary: appendix of `../markets/us/pjm/design_models_en.md`; China-side concepts: appendix
+of `../markets/china/market_vendor_dd_en.md`.*

primers/market_pjm_zh.md

@@ -1,7 +1,7 @@
 # PJM 市场入门：写给中国读者
 
 **工作文档 —— v0.1（2026年7月）**
-**定位：** 本文是 `../china/market_vendor_dd_zh.md` 第一节（中国市场入门）的镜像——为熟悉中国电力市场的读者解释 PJM，处处以中国概念作对照。英文版：`market_primer_en.md`。
+**定位：** 本文是 `../markets/china/market_vendor_dd_zh.md` 第一节（中国市场入门）的镜像——为熟悉中国电力市场的读者解释 PJM，处处以中国概念作对照。英文版：`market_pjm_en.md`。
 
 ---
 
@@ -37,7 +37,7 @@ PJM 日前市场对 **纯金融参与** 开放，这是与中国最深刻的结
 
 ## 五、结算与偏差：BORD 对"两个细则"
 
-PJM 通过 **平衡运行备用偏差（BORD）费用** 约束偏差：实时平衡产生的补偿成本（uplift）按成本因果分摊给偏离日前头寸的主体（发电偏差、负荷偏差、虚拟交易），费率按日随实际成本浮动。中国通过"两个细则"行政考核约束预测精度与计划执行，力度与当日系统实际成本脱钩。一句话对照： **PJM 给外部性定价；中国给作业打分。** 产品含义：在 PJM，偏差是对一个可预测随机价格的优化对象；在中国，预测是对一套固定规则手册的工程对象——这也是中国出现"合规采购型"功率预测市场、而美国没有的原因。（详见 `design_models_zh.md` 4.1 节。）
+PJM 通过 **平衡运行备用偏差（BORD）费用** 约束偏差：实时平衡产生的补偿成本（uplift）按成本因果分摊给偏离日前头寸的主体（发电偏差、负荷偏差、虚拟交易），费率按日随实际成本浮动。中国通过"两个细则"行政考核约束预测精度与计划执行，力度与当日系统实际成本脱钩。一句话对照： **PJM 给外部性定价；中国给作业打分。** 产品含义：在 PJM，偏差是对一个可预测随机价格的优化对象；在中国，预测是对一套固定规则手册的工程对象——这也是中国出现"合规采购型"功率预测市场、而美国没有的原因。（详见 `../markets/us/pjm/design_models_zh.md` 4.1 节。）
 
 ## 六、新能源的处境：税收抵免而非机制电价
 
@@ -80,4 +80,4 @@ PJM 通过 **平衡运行备用偏差（BORD）费用** 约束偏差：实时平
 
 ---
 
-*术语表见 `design_models_zh.md` 附录；中国侧概念见 `../china/market_vendor_dd_zh.md` 附录。*
+*术语表见 `../markets/us/pjm/design_models_zh.md` 附录；中国侧概念见 `../markets/china/market_vendor_dd_zh.md` 附录。*