📝 docs(readme): clarify project docs vs standards

README.md

@@ -62,7 +62,43 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
    main --squash
    ```
 
-3. 目录约定（建议）
+#### 快速落地（最小 4 步）
+
+在目标项目中按以下顺序执行即可完成落地（推荐固定使用 `--prefix docs/standards/tsl`）：
+
+1. 引入标准快照（见上文 `git subtree add`）
+2. 同步到项目根目录（生成/更新 `.agents/tsl/`、更新 `.gitattributes`）：
+
+   ```bash
+   sh docs/standards/tsl/scripts/sync_standards.sh
+   ```
+
+3. 验收（任意满足其一即可）：
+
+   - 目录存在：`.agents/tsl/`
+   - 规则入口可读：`.agents/tsl/index.md`
+   - 标准文档可读：`docs/standards/tsl/docs/index.md`
+   - `.gitattributes` 包含区块：`# BEGIN tsl-playbook .gitattributes` / `# END tsl-playbook .gitattributes`
+
+4. 将同步产物纳入版本控制（目标项目建议提交）：
+   - `docs/standards/tsl/`（标准快照）
+   - `.agents/tsl/`（落地规则集）
+   - `.gitattributes`（managed block 更新）
+
+#### 可选：项目包装脚本（多 playbook 串联）
+
+多语言项目建议在目标项目创建一个包装脚本（便于一键同步多个规则集）：
+
+```sh
+#!/usr/bin/env sh
+set -eu
+
+sh docs/standards/tsl/scripts/sync_standards.sh
+# sh docs/standards/python/scripts/sync_standards.sh
+# sh docs/standards/cpp/scripts/sync_standards.sh
+```
+
+#### 目录约定（建议）
 
 目标项目推荐采用以下结构（Playbook 快照与项目文档分离）：
 
@@ -79,7 +115,7 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
 │   │       ├── .agents/           # 标准代理规则快照
 │   │       ├── .gitattributes
 │   │       └── SOURCE.md          # 记录来源版本/commit（项目自行维护）
-    │   └── project/                   # 目标项目自己的文档
+│   └── project/                   # 目标项目自己的文档（非语言标准：架构/运行/ADR/使用说明/业务约定等）
 └── README.md                      # 说明遵循 standards
 ```
 
@@ -100,11 +136,20 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则
 同步脚本行为（目标项目内的最终落地内容）：
 
 - 覆盖/更新：`.agents/<AGENTS_NS>/`（默认 `.agents/tsl/`）
-    - 更新 `.gitattributes`：默认只维护 `# BEGIN tsl-playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=overwrite|block|skip` 控制）
+- 更新 `.gitattributes`：默认只维护 `# BEGIN tsl-playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制）
 - 缺省创建：`.agents/index.md`
 - 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀）
 - 不修改：`.gitignore`（项目自行维护）
 
+#### 环境变量（可选）
+
+同步脚本支持以下可选环境变量（默认值可满足大多数项目）：
+
+| 变量名              | 默认值  | 说明                                                                                        |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `AGENTS_NS`         | `tsl`   | 规则集落地目录名：`.agents/<AGENTS_NS>/`                                                    |
+| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式：`block` 仅维护 managed 区块；`overwrite` 全量覆盖；`skip` 不更新 |
+
 ### 方式二：手动复制快照
 
 如果不使用 `git subtree`，也可以由有权限的人手动复制 Playbook 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。