diff --git a/README.md b/README.md
index e410d6d..a68c057 100644
--- a/README.md
+++ b/README.md
@@ -97,9 +97,18 @@ $EDITOR data/projects/<id>.yaml
 # 3. 刷新指标（放在填档之后，别反过来）
 python3 scripts/fetch_stats.py --id <id>
 
+# 3.5 校验档案结构（发布/镜像前挡住结构性缺口）
+python3 scripts/validate.py            # 全部
+python3 scripts/validate.py --id <id>  # 单个
+
 # 4. 镜像源码（按许可证等级自动决定 private / public）
 bash scripts/mirror_sync.sh --id <id>
 
+#   常用选项：
+#     --depth 1          超大仓只取近期历史（>100 MB 的先这样，再 --deepen 续传）
+#     --no-fetch         跳过上游更新，用本地裸仓重做快照（GitHub 连不上时用）
+#     --set-public       把判定应为公开的仓库从 private 翻为 public（默认不自动翻）
+
 # 5. 成文（套 templates/project-article.md）
 $EDITOR articles/<id>.md
 
@@ -154,11 +163,25 @@ detail 只作为可选的健全性检查。
 | 脚本 | 作用 | 降级行为 |
 | --- | --- | --- |
 | `new_project.py` | 建档 + 自动判许可证等级 | API 失败时生成未定级骨架，要求人工填 |
+| `validate.py` | 档案 schema 校验 | WARN 不阻断（`--strict` 时视为失败） |
 | `fetch_stats.py` | 抓指标 + 累积时间序列快照 | 无 `GITHUB_TOKEN` 则匿名降级；当日缓存；失败沿用上次快照并标 `stale` |
 | `build_matrix.py` | 生成对比矩阵 + 赛道图 / 象限图 + 文章索引 | 项目 <4 个出分层图，≥4 个才出象限图；索引缺标记则跳过并警告 |
-| `mirror_sync.sh` | 源码镜像同步 | 大仓（>300MB）提示并支持 treeless clone 降级 |
+| `mirror_sync.sh` | 源码镜像同步 | 大仓（>300MB）提示并支持 treeless clone 降级；超 Gitea 45 MB 推送上限降级为源码快照 |
 | `publish_emlog.py` | emlog 发布 / 更新 | 本地正文为空时拒绝 update（防清空线上） |
 
+### `validate.py` 校验什么
+
+| 校验项 | 级别 |
+| --- | --- |
+| 必填字段（顶层 / 许可证块 / 坐标 / mirror） | ERROR |
+| `risk.claim_vs_reality` ≥ 3 条，每条含 claim/actual/source | ERROR |
+| 声明了 `mirror.excludes` 却缺 `redistributable_after_excludes` | ERROR |
+| `one_liner` 含样本计数（「七个里」等随样本增加即过时） | WARN |
+| `mode` 已镜像但 `sync_note` 仍写「尚未执行」 | WARN |
+
+第三条与 `mirror_sync.sh` 的 fail-closed 规则一致：声明了排除项却不给排除后的
+可分发性判定，镜像脚本会直接拒绝执行。在这里提前报比跑到镜像那一步才炸好定位。
+
 ---
 
 ## 已知约束