diff --git a/README.md b/README.md
new file mode 100644
index 0000000..52523b4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# git.fsdpf.net/go/req（v1-legacy）
+
+老架构下资源系统的核心接口定义。只有接口，没有默认实现——具体实现放在配套的老版
+`framework`/`contracts` 仓库里，本仓库只提供类型契约，供它们和使用方共同依赖。
+
+## 这个分支有什么
+
+- `Resource`：资源接口，`GetDBTable(params ...any) *db.Builder`/`GetAuthDBTable(u User, params ...any) *db.Builder`
+  基于老版 `db.Builder`（不是 `db.SelectDataset`）构造查询；`WithRolesCondition(b *db.Builder, t string, u User) error`
+  直接挂在接口上做行级权限过滤，不是靠外部 DI 注入的钩子；`ResAuthDB`（`ResAuthOff`/`ResAuthOn`/
+  `ResAuthAll`）控制要不要做权限过滤、要不要扩展到关联资源。
+- `ResField`/`QueryField`：字段/查询字段接口，`ToValue`/`ToBlueprint`/`ToQueryField` 等方法签名
+  跟现在 `master` 分支的不兼容（比如 `GetRawDefault(driver string)` 现在改成了不带 `driver`
+  参数的版本）。
+- `User`：用户接口，角色、匿名判断、`HasUserRoles` 等，这部分跟 `master` 基本一致。
+- `RouteCtx`/`RouteMethod`/`HttpResponse`/`GlobalParams` 等 HTTP 路由和响应相关的类型
+  （`routing.go`/`response.go`/`global_params.go`）：这些在 `master` 分支上已经不在这个仓库
+  的范围内了，是这条老线特有的。
+
+## 这个分支的定位
+
+给还在维护、但还没迁移到 `master` 分支新架构（`resx` 默认实现、字段级脱敏、`ResFlags` 权限
+开关、虚拟资源等）的老项目用，比如 `zg-estate`（通过 `framework`/`contracts` 间接依赖）。
+只接受独立于新架构的 bug 修复，不会引入 `master` 上的新能力。
+
+## 依赖方怎么安装/更新
+
+Go modules 不会记住某个版本是从哪个分支解析出来的，`go.mod`/`go.sum` 里存的只是一次性解析出
+的 commit 伪版本号，分支上有新提交也不会自动同步。
+
+**首次锁定，或者要拿这个分支上新提交的更新**，都执行同一条命令：
+
+```
+go get git.fsdpf.net/go/req@v1-legacy
+```
+
+**禁止**跑裸的 `go get -u`（或者 `go get git.fsdpf.net/go/req@latest`）——这个仓库没有打
+语义化 tag，Go 对"最新版本"的解析规则是退回到仓库默认分支（`master`）的 HEAD，会把新架构的
+破坏性改动一起拉进来，而不是停留在这个分支上。