diff --git a/README.md b/README.md
index e1300315..65af00e7 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,14 @@
 # QuantPlatformKit
 
+
+## QSL architecture role
+
+- **Layer**: `core`.
+- **Responsibility**: shared runtime contracts and platform adapters.
+- **Owns**: stable contracts, broker adapters, runtime helpers, notifications, risk utilities.
+- **Consumes**: platforms, strategies, pipelines, lifecycle tooling.
+- **Must not**: decide which strategy is live or store environment-specific secrets.
+
 [Chinese README](README.zh-CN.md)
 
 > Investing involves risk. This project does not provide investment advice and is for education, research, and engineering review only.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 004547d9..0981066d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,5 +1,14 @@
 # QuantPlatformKit
 
+
+## QSL 架构角色
+
+- **层级**：`核心共享库`。
+- **职责**：共享 runtime contracts 和平台 adapters。
+- **事实源/归属**：稳定 contracts、broker adapters、runtime helpers、notifications、risk utilities。
+- **消费对象**：platforms、strategies、pipelines、lifecycle tooling。
+- **禁止事项**：决定哪个策略 live 或保存环境 secrets。
+
 [English README](README.md)
 
 > 投资有风险。本项目不构成投资建议，仅用于学习、研究和工程审阅。