From 86fb7baec99b009ee0a81b321e2ad53952edcda2 Mon Sep 17 00:00:00 2001
From: dev-belly <dev_belly@outlook.com>
Date: Wed, 14 Oct 2026 15:24:00 +0800
Subject: [PATCH] docs: clarify main and release scope and check invoice
 expectations

---
 README.md                 | 5 +++++
 README.zh-CN.md           | 4 ++++
 examples/decision_time.py | 9 +++++++++
 3 files changed, 18 insertions(+)

diff --git a/README.md b/README.md
index 8286fe1..93fd9a1 100644
--- a/README.md
+++ b/README.md
@@ -23,6 +23,11 @@ Python 3.11+ and Git are required. There are **no third-party runtime
 dependencies**. The commands use a virtual environment without requiring
 activation.
 
+These commands clone `main`. The [v0.1.0 release](https://github.com/dev-belly/PITBridge/releases/tag/v0.1.0)
+is an earlier snapshot: the optional CSV example and `benchmark` command were
+added [after that tag](https://github.com/dev-belly/PITBridge/compare/v0.1.0...main).
+Use `main` for those examples, or follow the tagged release's own instructions.
+
 **Linux / macOS**
 
 ```bash
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 4a15abf..a27ebf7 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -16,6 +16,10 @@ PITBridge 同时处理数据发生时间、公开时间、入库时间和修订
 
 需要 Git 和 Python 3.11 或更高版本。下面是 Windows PowerShell 命令，使用独立环境，无需先激活：
 
+这些命令克隆 `main`。[v0.1.0 发布版本](https://github.com/dev-belly/PITBridge/releases/tag/v0.1.0)
+是较早的代码快照；可选 CSV 示例和 `benchmark` 命令均在[该标签之后加入](https://github.com/dev-belly/PITBridge/compare/v0.1.0...main)。
+试用这些功能请使用 `main`；若选择发布标签，请按该版本自己的说明运行。
+
 ```powershell
 git clone https://github.com/dev-belly/PITBridge.git
 cd PITBridge
diff --git a/examples/decision_time.py b/examples/decision_time.py
index 544478c..fdfacce 100644
--- a/examples/decision_time.py
+++ b/examples/decision_time.py
@@ -37,6 +37,15 @@ def main():
     snapshots = build_snapshot(observations, decisions, specs)
     if snapshots != reference_snapshot(observations, decisions, specs):
         raise RuntimeError("SQL and independent temporal replay disagree")
+    # Check the documented business result independently of either engine.
+    expected = [
+        ("01-before-arrival", None, "not_available", None),
+        ("02-original-known", 100000.0, "selected", "invoice-v1"),
+        ("03-correction-known", 135000.0, "selected", "invoice-v2"),
+    ]
+    actual = [(row.decision_id, row.value, row.status, row.record_id) for row in snapshots]
+    if actual != expected:
+        raise RuntimeError("Invoice selections differ from the three documented decisions")
     print(json.dumps([asdict(row) for row in snapshots], indent=2))