@freelog-cli/cli2 0.5.1 → 0.5.2

package/dist/docs/01-/345/277/253/351/200/237/344/270/212/346/211/213.md

@@ -1,81 +1,83 @@
-# 快速开始：发行一个普通文件
-
-本例把 `video.mp4` 作为普通单资源发成首版 `1.0.0`。以下示例以 dev 环境为例；不要把真实密码写进命令行参数或脚本文件。
-
-## 1. 安装、确认与登录
-
-CLI 要求 Node.js 20 或更高版本。尚未安装时，先执行：
-
-```powershell
-node --version
-npm install --global @freelog-cli/cli2
-freelog-cli --cli-version
-```
-
-如果 `freelog-cli` 找不到，重新打开终端；仍无法使用时，检查 npm 全局可执行目录是否已加入 `PATH`。以下统一写作 `freelog-cli`。
-
-首次使用推荐在交互终端直接登录；CLI 会安全地隐藏密码输入：
-
-```powershell
-freelog-cli login --env dev
-```
-
-```powershell
-# 登录成功后，可查看安装包内自带的完整手册路径
-freelog-cli --help
-```
-
-自动化或非交互终端需要同时传 `--login-name`、`--password-stdin`、`--yes`；由 CI 的保密输入把密码写入标准输入，绝不把密码写进命令行、脚本或环境变量。登录成功后，工程只保存账号选择器；token、Cookie 等秘密由系统凭据库保存。
-
-## 2. 建立工程身份
-
-普通资源要先登录，因为资源类型来自平台的当前类型树。已知最终叶子 code 时可直接初始化：
-
-```powershell
-freelog-cli init . --type RT006003 --yes --env dev
-```
-
-不知道 code 时先查询，或不传 `--type` 进入交互式层级选择：
-
-```powershell
-freelog-cli type search 视频 --env dev
-freelog-cli type info RT006003 --env dev
-freelog-cli init . --env dev
-```
-
-`init` 只写 `.freelog/1.json`，不会创建线上资源、上传文件或创建版本。
-
-上一步已在当前目录写入 `.freelog/auth` 也可以再执行 `init .`：CLI 会保留这一个账号选择器，并拒绝覆盖任何其它已有工程内容或资源身份。
-
-## 3. 创建线上资源壳
-
-```powershell
-freelog-cli create `
-  --title "我的视频" `
-  --name my-video `
-  --artifact video.mp4 `
-  --yes --env dev
-```
-
-因为工程已经通过 `init` 记录了类型，这里不必重复传 `--type`；CLI 会在提交前重新验证该类型。没有先 `init` 时也可以直接创建，但必须额外传入 `--type <最终叶子 code>`。
-
-此步只创建资源壳并回写 `resourceId`、`name`、环境和文件路径，**不会上传视频**。
-
-## 4. 上传、检查并提交首版
-
-最稳妥的做法是先准备工作稿：
-
-```powershell
-freelog-cli create-version --prepare --artifact video.mp4 --env dev
-freelog-cli version show --local --env dev
-freelog-cli create-version --yes --artifact video.mp4 --env dev
-```
-
-第一条会校验文件、计算 SHA1、上传并等待平台解析，但不提交版本。确认本地工作稿后，最后一条会再次从当前文件校验、上传和解析，再提交固定首版号 `1.0.0`。提交成功会删除工作稿；失败或中断会保留工作稿以便继续处理。
-
-## 5. 下一步
-
-- 要增加属性、可选配置或依赖：看 [版本工作稿](./04-版本工作稿.md)。
-- 要发布后续版本：看 [日常操作](./02-日常路径.md#发布新版本)。
-- 要给资源配置策略并上架：看 [资源管理](./05-资源管理.md)。
-- 要发行主题或插件：不要照本页的 `init`，改看 [主题与插件](./03-主题与插件.md)。
+# 快速开始：发行一个普通文件
+
+本页是第一次使用的可执行教程：把 `video.mp4` 作为普通资源发成首版 `1.0.0`。以下示例以 dev 环境为例；不要把真实密码写进命令行参数或脚本文件。已有工程、已有线上资源或主题/插件不要套用本页，先到[按场景操作](./09-按场景操作.md)选入口。
+
+## 1. 安装、确认与登录
+
+CLI 要求 Node.js 20 或更高版本。尚未安装时，先执行：
+
+```powershell
+node --version
+npm install --global @freelog-cli/cli2
+freelog-cli --cli-version
+```
+
+如果 `freelog-cli` 找不到，重新打开终端；仍无法使用时，检查 npm 全局可执行目录是否已加入 `PATH`。以下统一写作 `freelog-cli`。
+
+首次使用推荐在交互终端直接登录；CLI 会安全地隐藏密码输入：
+
+```powershell
+freelog-cli login --env dev
+```
+
+```powershell
+# 登录成功后，可查看安装包内自带的完整手册路径
+freelog-cli --help
+```
+
+自动化或非交互终端需要同时传 `--login-name`、`--password-stdin`、`--yes`；由 CI 的保密输入把密码写入标准输入，绝不把密码写进命令行、脚本或环境变量。登录成功后，工程只保存账号选择器；token、Cookie 等秘密由系统凭据库保存。
+
+## 2. 建立工程身份
+
+普通资源要先登录，因为资源类型来自平台的当前类型树。已知最终叶子 code 时可直接初始化：
+
+```powershell
+freelog-cli init . --type RT006003 --yes --env dev
+```
+
+不知道 code 时先查询，或不传 `--type` 进入交互式层级选择：
+
+```powershell
+freelog-cli type search 视频 --env dev
+freelog-cli type list --env dev
+freelog-cli type info RT006003 --env dev
+freelog-cli init . --env dev
+```
+
+`init` 只写 `.freelog/1.json`，不会创建线上资源、上传文件或创建版本。
+
+上一步已在当前目录写入 `.freelog/auth` 也可以再执行 `init .`：CLI 会保留这一个账号选择器，并拒绝覆盖任何其它已有工程内容或资源身份。
+
+## 3. 创建线上资源壳
+
+```powershell
+freelog-cli create `
+  --title "我的视频" `
+  --name my-video `
+  --artifact video.mp4 `
+  --yes --env dev
+```
+
+因为工程已经通过 `init` 记录了类型，这里不必重复传 `--type`；CLI 会在提交前重新验证该类型。没有先 `init` 时也可以直接创建，但必须额外传入 `--type <最终叶子 code>`。
+
+此步只创建资源壳并回写 `resourceId`、`name`、环境和文件路径，**不会上传视频**。
+
+## 4. 上传、检查并提交首版
+
+最稳妥的做法是先准备工作稿：
+
+```powershell
+freelog-cli create-version --prepare --artifact video.mp4 --env dev
+freelog-cli version show --local --env dev
+freelog-cli create-version --yes --artifact video.mp4 --env dev
+```
+
+第一条会校验文件、计算 SHA1、上传并等待平台解析，但不提交版本。确认本地工作稿后，最后一条会再次从当前文件校验、上传和解析，再提交固定首版号 `1.0.0`。提交成功会删除工作稿；失败或中断会保留工作稿以便继续处理。
+
+## 5. 下一步
+
+- 要增加属性、可选配置或依赖：看 [版本工作稿](./04-版本工作稿.md)。
+- 要发布后续版本：看 [日常操作](./02-日常路径.md#发布新版本)。
+- 要给资源配置策略并上架：看 [资源管理](./05-资源管理.md)。
+- 要发行主题或插件：不要照本页的 `init`，改看 [主题与插件](./03-主题与插件.md)。
+- 要查任一命令的全部前置条件和影响：看 [完整命令参考](./10-命令参考.md)。

package/dist/docs/02-/346/227/245/345/270/270/350/267/257/345/276/204.md

@@ -1,90 +1,92 @@
-# 日常操作
-
-## 创建新资源
-
-```text
-login → init（可选）→ create → create-version → 配策略 / 上架（可选）
-```
-
-| 阶段 | 命令 | 结果 |
-|---|---|---|
-| 选类型并立项 | `init [dir] --type <leaf-code>` | 写未绑定本地身份，不创建线上资源。 |
-| 建壳 | `create --title <title> --name <name> [--type <leaf-code>] [--artifact <path>]` | 创建线上资源，写入 `resourceId`。 |
-| 仅准备首版 | `create-version --prepare` | 上传并解析文件，留下首版工作稿。 |
-| 提交首版 | `create-version --yes` | 提交 `1.0.0` 并清理成功的工作稿。 |
-
-`create-version` 只适用于尚无线上版本的资源。`--prepare` 与 `--yes` 都会以当前产物上传并等待解析；前者只保存可编辑的工作稿，后者才提交固定的 `1.0.0`。已经有版本时它会停止并提示使用 `update-version`。
-
-## 发布新版本
-
-```text
-version draft pull → 改工作稿 → update-version
-```
-
-先把已发版本作为新版本的底：
-
-```powershell
-freelog-cli version draft pull --version 1.0.0 --env dev
-freelog-cli version show --local --env dev
-freelog-cli update-version --version 1.1.0 --yes --env dev
-```
-
-也可以让 CLI 按规则递增版本号：
-
-```powershell
-freelog-cli update-version --bump patch --yes --env dev
-freelog-cli update-version --bump minor --yes --env dev
-freelog-cli update-version --bump major --yes --env dev
-```
-
-规则如下：
-
-- `--version` 必须是合法 semver，且严格大于提交瞬间的线上 latest。
-- `--version` 与 `--bump` 不能同时使用。
-- `--yes` 必须提供其中之一，CLI 不会擅自猜测版本号。
-- `update-version` 不支持 `--prepare`；需要分阶段编辑时用 `version draft pull` 建稿。
-- 发版前改文件可附 `--artifact <文件或构建目录>`；成功确认后该路径会回写身份记录。多资源工程同时传 `--file <已记录路径>` 选择身份。
-
-## 接入已有资源
-
-当资源已在网页、另一台机器或别的工程中创建时，不要再运行 `create`：
-
-```powershell
-freelog-cli bind <resourceId 或 username/name> --artifact video.mp4 --env dev
-```
-
-`bind` 会读取平台详情，且只接入当前账号拥有的单资源。它不会下载文件、拉取版本工作稿或修改线上资源。
-
-接入后按线上是否已有版本分流：
-
-| 线上状态 | 下一步 |
-|---|---|
-| 没有 `latestVersion` | `create-version --prepare` 后编辑并 `create-version --yes`，发行首版。 |
-| 已有 `latestVersion` | `version draft pull`，编辑工作稿后以 `update-version --version` 或 `--bump` 发新号。 |
-
-主题/插件的 `<path>` 必须是构建目录（`dist` / `build`）；在尚无目录记录的既有项目中，`bind --artifact` 必填。
-
-- 已有相同资源 id 时，重复 `bind` 是幂等的。
-- 要将一份本地身份换绑到另一个资源，使用 `bind <id> --force --yes`；旧工作稿会被清理。
-
-## 查看与只读操作
-
-```powershell
-freelog-cli status --env dev
-freelog-cli version show --env dev
-freelog-cli version show --version 1.0.0 --env dev
-freelog-cli version show --local --env dev
-```
-
-前三条读取线上事实；`version show --local` 只读取未提交工作稿。它们不会覆盖、提交或删除工作稿。
-
-## `--artifact` 的含义
-
-一个工程只有一份资源身份，`--artifact` 是唯一的本地产物路径。`create` / `bind` 用它记录将来默认使用的路径，路径可以暂时不存在；`create-version` / `update-version` 用它指定本次文件或目录，发版产物必须真实存在：
-
-| 场景 | 传入的路径 |
-|---|---|
-| 普通资源 `--artifact` | 一个实际文件。目录会被拒绝。 |
-| 主题 / 插件 `--artifact` | 一个构建产物目录，例如 `dist` 或 `build`。zip 文件会被拒绝。 |
-
-发版未传 `--artifact` 时，CLI 只会在已记录路径确实存在时采用它；`--yes` 遇到缺失路径会失败，要求显式给出 `--artifact`。不再支持 `--file` 或一个工程多资源身份。
+# 资源生命周期：创建、接入与发版
+
+本页解释资源从“还不存在”到“后续持续发版”的日常路径。它回答该用 `init`、`create` 还是 `bind`，以及首版和更新版为何是两条命令。版本工作稿的字段编辑、恢复细节见[版本工作稿](./04-版本工作稿.md)；按你当前实际处境直接执行的方案见[按场景操作](./09-按场景操作.md)。
+
+## 创建新资源
+
+```text
+login → init（可选）→ create → create-version → 配策略 / 上架（可选）
+```
+
+| 阶段 | 命令 | 结果 |
+|---|---|---|
+| 选类型并立项 | `init [dir] --type <leaf-code>` | 写未绑定本地身份，不创建线上资源。 |
+| 建壳 | `create --title <title> --name <name> [--type <leaf-code>] [--artifact <path>]` | 创建线上资源，写入 `resourceId`。 |
+| 仅准备首版 | `create-version --prepare` | 上传并解析文件，留下首版工作稿。 |
+| 提交首版 | `create-version --yes` | 提交 `1.0.0` 并清理成功的工作稿。 |
+
+`create-version` 只适用于尚无线上版本的资源。`--prepare` 与 `--yes` 都会以当前产物上传并等待解析；前者只保存可编辑的工作稿，后者才提交固定的 `1.0.0`。已经有版本时它会停止并提示使用 `update-version`。
+
+## 发布新版本
+
+```text
+version draft pull → 改工作稿 → update-version
+```
+
+先把已发版本作为新版本的底：
+
+```powershell
+freelog-cli version draft pull --version 1.0.0 --env dev
+freelog-cli version show --local --env dev
+freelog-cli update-version --version 1.1.0 --yes --env dev
+```
+
+也可以让 CLI 按规则递增版本号：
+
+```powershell
+freelog-cli update-version --bump patch --yes --env dev
+freelog-cli update-version --bump minor --yes --env dev
+freelog-cli update-version --bump major --yes --env dev
+```
+
+规则如下：
+
+- `--version` 必须是合法 semver，且严格大于提交瞬间的线上 latest。
+- `--version` 与 `--bump` 不能同时使用。
+- 提交更新版时，必须同时明确提供 `--version <新号>` 或 `--bump <方向>`，并带 `--yes`；CLI 不会擅自猜测版本号或执行提交。
+- `update-version` 不支持 `--prepare`；需要分阶段编辑时用 `version draft pull` 建稿。
+- 发版前改文件可附 `--artifact <文件或构建目录>`；成功确认后该路径会回写身份记录。多资源工程以 `--resource <selector>` 选择身份。
+
+## 接入已有资源
+
+当资源已在网页、另一台机器或别的工程中创建时，不要再运行 `create`：
+
+```powershell
+freelog-cli bind <resourceId 或 username/name> --artifact video.mp4 --env dev
+```
+
+`bind` 会读取平台详情，且只接入当前账号拥有的单资源。它不会下载文件、拉取版本工作稿或修改线上资源。
+
+接入后按线上是否已有版本分流：
+
+| 线上状态 | 下一步 |
+|---|---|
+| 没有 `latestVersion` | `create-version --prepare` 后编辑并 `create-version --yes`，发行首版。 |
+| 已有 `latestVersion` | `version draft pull`，编辑工作稿后以 `update-version --version` 或 `--bump` 发新号。 |
+
+主题/插件的 `<path>` 必须是构建目录（`dist` / `build`）；在尚无目录记录的既有项目中，`bind --artifact` 必填。
+
+- 已有相同资源 id 时，重复 `bind` 是幂等的。
+- 要将一份本地身份换绑到另一个资源，使用 `bind <id> --force --yes`；旧工作稿会被清理。
+
+## 查看与只读操作
+
+```powershell
+freelog-cli status --env dev
+freelog-cli version show --env dev
+freelog-cli version show --version 1.0.0 --env dev
+freelog-cli version show --local --env dev
+```
+
+前三条读取线上事实；`version show --local` 只读取未提交工作稿。它们不会覆盖、提交或删除工作稿。
+
+## `--artifact` 的含义
+
+一个工程可管理多份独立资源身份；每一份身份各自有一个默认 `filePath`。`--artifact` 只表示**本次选中资源**的产物路径，绝不选择资源。多份状态时先传 `--resource file:N.json`、`id:<资源ID>`、`name:<短标识或username/name>` 或 `title:<标题>`；不传时交互终端列出完整信息供选择，非交互会列出可复制的 `file:N.json` 示例并停止。标题可重复且会变化，脚本优先使用稳定的 `file:` 或 `id:`。`create` / `bind` 用 `--artifact` 记录将来默认使用的路径，路径可以暂时不存在；`create-version` / `update-version` 用它指定本次文件或目录，发版产物必须真实存在：
+
+| 场景 | 传入的路径 |
+|---|---|
+| 普通资源 `--artifact` | 一个实际文件。目录会被拒绝。 |
+| 主题 / 插件 `--artifact` | 一个构建产物目录，例如 `dist` 或 `build`。zip 文件会被拒绝。 |
+
+发版未传 `--artifact` 时，CLI 只会在已记录路径确实存在时采用它；`--yes` 遇到缺失路径会失败，要求显式给出 `--artifact`。不支持 `--file`；一个工程可管理多份独立资源身份。

package/dist/docs/03-/344/270/273/351/242/230/344/270/216/346/217/222/344/273/266.md

@@ -1,124 +1,124 @@
-# 主题与插件
-
-主题和插件仍是**单资源**。它们与普通文件资源共用登录、建壳、版本工作稿、属性、依赖、策略、管理和上下架流程；可选配置是否可编辑始终由当前类型详情决定。区别集中在工程初始化、路径形态和发版前的压缩。
-
-| 项目 | 主题 | 插件 | 普通文件资源 |
-|---|---|---|---|
-| 初始化 | `init theme` | `init widget` | `init --type <最终叶子>` |
-| 固定类型 | `RT001` | `RT002` | 由类型树选择并在线复验 |
-| 初始 `filePath` | `dist` 目录 | `dist` 目录 | 可无；建壳或发版时记录一个文件 |
-| 模板元数据 | 本期不保存；模板只决定初始化时复制什么工程 | 本期不保存；模板只决定初始化时复制什么工程 | 没有 |
-| 发版输入 | 构建产物目录 | 构建产物目录 | 一个普通文件 |
-| 上传前处理 | CLI 临时打 zip | CLI 临时打 zip | 直接上传原文件 |
-
-## 1. 从线上模板创建工程
-
-先查看 CLI 固定的线上模板清单：
-
-```powershell
-freelog-cli template list
-```
-
-推荐先登录，再创建主题或插件工程：
-
-```powershell
-freelog-cli login --env dev
-freelog-cli init theme my-theme --template vite-react-ts --yes
-freelog-cli init widget my-widget --template vite-vue-ts --yes
-```
-
-`init theme` / `init widget` 本身不需要登录，因为类型固定；但先登录能使随后 `create --cwd <工程>` 直接复用同一账号。它们从固定版本的线上 npm 模板包下载并只复制包内 `template/` 内容。CLI 不从 `packages/templates/` 复制，也不会执行模板脚本、渲染项目名/版本、安装依赖或执行构建。
-
-成功后会生成：
-
-```text
-my-theme/
-  .freelog/1.json             # typeCode=RT001，filePath=dist
-  ...模板文件
-```
-
-本期不保存模板元数据，也不渲染占位符。构建目录始终记录在 `N.json.filePath`。
-
-## 1.1 接入已有本地主题或插件项目
-
-非空的既有项目不能再运行 `init`。若它还没有线上资源壳，在项目根直接建壳，并显式记录构建目录：
-
-```powershell
-freelog-cli login --env dev
-freelog-cli create --title "已有主题" --name existing-theme --type RT001 --file dist --yes --env dev
-freelog-cli create-version --file dist --prepare --env dev
-freelog-cli create-version --file dist --yes --env dev
-```
-
-若线上资源已经存在，先 `bind`。它是否已有发行版本决定后续路径：
-
-```powershell
-# 线上还没有 latestVersion：接入后发行首版
-freelog-cli login --env dev
-freelog-cli bind <resourceId或username/name> --file dist --env dev
-freelog-cli create-version --file dist --prepare --env dev
-freelog-cli create-version --file dist --yes --env dev
-```
-
-```powershell
-# 线上已有 latestVersion：接入、拉稿并提交新版本
-freelog-cli login --env dev
-freelog-cli bind <resourceId或username/name> --file dist --env dev
-freelog-cli version draft pull --env dev
-freelog-cli update-version --file dist --bump patch --yes --env dev
-```
-
-不要在已发行资源上再运行 `create-version`，也不要在没有发行版本的资源上运行 `draft pull` / `update-version`。
-
-主题/插件既有项目路径都会把 `dist` / `build` 记录为目录，并在发版时临时压缩；不会补造元数据，也不会覆盖你的源码。
-
-## 2. 创建主题或插件资源壳
-
-初始化只建立本地工程，仍要登录并创建线上资源：
-
-```powershell
-freelog-cli login --env dev
-freelog-cli create --cwd my-theme --title "我的主题" --name my-theme --yes --env dev
-```
-
-不要再传 `--type RT001` / `RT002`：CLI 会使用工程已记录的固定类型并在线复验。若显式传入不同的 `--type`，命令会失败，不能把模板工程改造成普通资源。
-
-## 3. 先自行得到构建产物
-
-CLI 不运行包管理器或构建命令。你需要在工程自己的开发流程中产生 `dist/`（或其他构建目录）。如果产物目录不是 `dist`，只更新记录：
-
-```powershell
-freelog-cli version set --cwd my-theme --artifact build
-```
-
-这条命令不上传、不压缩、不创建版本。目录可以暂时还不存在；真正发版时必须存在且非空。
-
-## 4. 发布版本：传目录，不传 zip
-
-```powershell
-freelog-cli create-version --cwd my-theme --file dist --prepare --env dev
-freelog-cli version show --cwd my-theme --local --env dev
-freelog-cli create-version --cwd my-theme --file dist --yes --env dev
-```
-
-对于 `RT001` / `RT002`，CLI 会把 `dist` 的**内容**打入临时 zip（不会再包一层 `dist/`），然后计算 SHA1、上传、等待解析并提交。临时 zip 无论成功或失败都会删除，不写入工程，也不写入 `N.json` 或工作稿。
-
-以下输入会停止：
-
-| 输入 | 结果 |
-|---|---|
-| `dist` 不存在 | 要求先生成构建产物。 |
-| 空目录 | 要求先生成实际文件。 |
-| 工程根目录（其中含 `.freelog/`） | 拒绝将工程根作为产物目录。 |
-| 一个 `.zip` 或普通文件 | 拒绝；主题和插件只能交构建目录。 |
-
-后续版本与普通资源完全相同：`version draft pull` → 编辑工作稿 → `update-version --version ...` 或 `--bump ...`；只要传入的仍是构建目录，CLI 会重新生成临时 zip。当前 dev 的主题类型 `RT001` 不支持可选配置；不要把 `version option` 当作主题的固定能力。
-
-## 5. 这不是两套版本系统
-
-主题/插件和普通资源都使用同一份 `N.version.json` 工作稿，版本号规则、依赖签约规则、属性校验、成功清稿和失败保留规则完全一致；可选配置仅在类型详情允许时可用。唯一的文件层差异是：
-
-- 普通资源的 `filePath` 指向文件，文件 SHA1 即上传文件的 SHA1；
-- 主题/插件的 `filePath` 指向目录，文件 SHA1 与 `filename` 指向 CLI 临时 zip 的结果。
-
-因此不要手工把 zip 记进 `filePath`，也不要因为主题是目录而另建一套版本缓存。
+# 主题与插件
+
+本页只解释主题/插件相对普通文件的差异：模板初始化、固定类型、构建目录与临时压缩。它们仍是“一条资源一次一条命令”，并与普通文件共用登录、建壳、版本工作稿、属性、依赖、策略、管理和上下架流程；可选配置是否可编辑始终由当前类型详情决定。完整生命周期见[资源生命周期](./02-日常路径.md)，准确命令与参数见[完整命令参考](./10-命令参考.md)。
+
+| 项目 | 主题 | 插件 | 普通文件资源 |
+|---|---|---|---|
+| 初始化 | `init theme` | `init widget` | `init --type <最终叶子>` |
+| 固定类型 | `RT001` | `RT002` | 由类型树选择并在线复验 |
+| 初始 `filePath` | `dist` 目录 | `dist` 目录 | 可无；建壳或发版时记录一个文件 |
+| 模板元数据 | 本期不保存；模板只决定初始化时复制什么工程 | 本期不保存；模板只决定初始化时复制什么工程 | 没有 |
+| 发版输入 | 构建产物目录 | 构建产物目录 | 一个普通文件 |
+| 上传前处理 | CLI 临时打 zip | CLI 临时打 zip | 直接上传原文件 |
+
+## 从线上模板创建工程
+
+先查看 CLI 固定的线上模板清单：
+
+```powershell
+freelog-cli template list
+```
+
+推荐先登录，再创建主题或插件工程：
+
+```powershell
+freelog-cli login --env dev
+freelog-cli init theme my-theme --template vite-react-ts --yes
+freelog-cli init widget my-widget --template vite-vue-ts --yes
+```
+
+`init theme` / `init widget` 本身不需要登录，因为类型固定；但先登录能使随后 `create --cwd <工程>` 直接复用同一账号。它们从固定版本的线上 npm 模板包下载并只复制包内 `template/` 内容。CLI 不从 `packages/templates/` 复制，也不会执行模板脚本、渲染项目名/版本、安装依赖或执行构建。
+
+成功后会生成：
+
+```text
+my-theme/
+  .freelog/1.json             # typeCode=RT001，filePath=dist
+  ...模板文件
+```
+
+本期不保存模板元数据，也不渲染占位符。构建目录始终记录在 `N.json.filePath`。
+
+## 接入已有主题或插件项目
+
+非空的既有项目不能再运行 `init`。若它还没有线上资源壳，在项目根直接建壳，并显式记录构建目录：
+
+```powershell
+freelog-cli login --env dev
+freelog-cli create --title "已有主题" --name existing-theme --type RT001 --artifact dist --yes --env dev
+freelog-cli create-version --prepare --env dev
+freelog-cli create-version --yes --env dev
+```
+
+若线上资源已经存在，先 `bind`。它是否已有发行版本决定后续路径：
+
+```powershell
+# 线上还没有 latestVersion：接入后发行首版
+freelog-cli login --env dev
+freelog-cli bind <resourceId或username/name> --artifact dist --env dev
+freelog-cli create-version --prepare --env dev
+freelog-cli create-version --yes --env dev
+```
+
+```powershell
+# 线上已有 latestVersion：接入、拉稿并提交新版本
+freelog-cli login --env dev
+freelog-cli bind <resourceId或username/name> --artifact dist --env dev
+freelog-cli version draft pull --env dev
+freelog-cli update-version --bump patch --yes --env dev
+```
+
+不要在已发行资源上再运行 `create-version`，也不要在没有发行版本的资源上运行 `draft pull` / `update-version`。
+
+主题/插件既有项目路径都会把 `dist` / `build` 记录为目录，并在发版时临时压缩；不会补造元数据，也不会覆盖你的源码。
+
+## 创建主题或插件资源壳
+
+初始化只建立本地工程，仍要登录并创建线上资源：
+
+```powershell
+freelog-cli login --env dev
+freelog-cli create --cwd my-theme --title "我的主题" --name my-theme --yes --env dev
+```
+
+不要再传 `--type RT001` / `RT002`：CLI 会使用工程已记录的固定类型并在线复验。若显式传入不同的 `--type`，命令会失败，不能把模板工程改造成普通资源。
+
+## 先自行得到构建产物
+
+CLI 不运行包管理器或构建命令。你需要在工程自己的开发流程中产生 `dist/`（或其他构建目录）。如果产物目录不是 `dist`，只更新记录：
+
+```powershell
+freelog-cli version set --cwd my-theme --artifact build
+```
+
+这条命令不上传、不压缩、不创建版本。目录可以暂时还不存在；真正发版时必须存在且非空。
+
+## 发布版本：传目录，不传 zip
+
+```powershell
+freelog-cli create-version --cwd my-theme --prepare --env dev
+freelog-cli version show --cwd my-theme --local --env dev
+freelog-cli create-version --cwd my-theme --yes --env dev
+```
+
+对于 `RT001` / `RT002`，CLI 会把 `dist` 的**内容**打入临时 zip（不会再包一层 `dist/`），然后计算 SHA1、上传、等待解析并提交。临时 zip 无论成功或失败都会删除，不写入工程，也不写入 `N.json` 或工作稿。
+
+以下输入会停止：
+
+| 输入 | 结果 |
+|---|---|
+| `dist` 不存在 | 要求先生成构建产物。 |
+| 空目录 | 要求先生成实际文件。 |
+| 工程根目录（其中含 `.freelog/`） | 拒绝将工程根作为产物目录。 |
+| 一个 `.zip` 或普通文件 | 拒绝；主题和插件只能交构建目录。 |
+
+后续版本与普通资源完全相同：`version draft pull` → 编辑工作稿 → `update-version --version ...` 或 `--bump ...`；只要传入的仍是构建目录，CLI 会重新生成临时 zip。当前 dev 的主题类型 `RT001` 不支持可选配置；不要把 `version option` 当作主题的固定能力。
+
+## 这不是两套版本系统
+
+主题/插件和普通资源都使用同一份 `N.version.json` 工作稿，版本号规则、依赖签约规则、属性校验、成功清稿和失败保留规则完全一致；可选配置仅在类型详情允许时可用。唯一的文件层差异是：
+
+- 普通资源的 `filePath` 指向文件，文件 SHA1 即上传文件的 SHA1；
+- 主题/插件的 `filePath` 指向目录，文件 SHA1 与 `filename` 指向 CLI 临时 zip 的结果。
+
+因此不要手工把 zip 记进 `filePath`，也不要因为主题是目录而另建一套版本缓存。