docs: align purge and repository contracts

Author: Vonng

content/blog/design/repo-yaml-catalog-json.md

@@ -60,7 +60,7 @@ moved, a version was deprecated, or a provenance statement changed.
 
 `catalog.json` materializes policy against the local repository. For every
 variant it records the exact filename, byte count, SHA-256, qcow2 virtual size,
-boot contract, source user, and immutable upstream fallback.
+boot contract, source user, and immutable upstream provenance.
 
 Those fields come from scanning the artifact, not from copying values out of
 the YAML. Build forces qcow2 parsing, rejects backing files, external data,
@@ -135,10 +135,11 @@ application artifacts and checksum manifest. The two key sets are intentionally
 independent: permission to publish a VM image must not imply permission to ship
 a new Farrow binary, or vice versa.
 
-Ordinary public builds also compile no private development mirror as a default.
-They begin with the embedded Catalog and its immutable HTTPS upstream URLs. A
-public mirror can become a compiled default only after the mirror itself is
-live. Source configuration, generated Catalog, uploaded artifacts, signing,
+Ordinary public builds default to `https://repo.pigsty.io/farrow` and expose
+`--mirror` for `https://repo.pigsty.cc/farrow`; `--repo` remains the explicit
+custom override. Once selected, that repository is the only artifact source.
+Embedded Catalog upstream URLs retain provenance but never become a hidden
+fallback. Source configuration, generated Catalog, uploaded artifacts, signing,
 and public availability remain separate release gates.
 
 That is the larger design principle: policy should be pleasant to review, but

content/blog/design/repo-yaml-catalog-json.zh.md

@@ -53,7 +53,7 @@ images:
 ## `catalog.json`：仓库能够证明什么
 
 `catalog.json` 把策略落实到本地仓库。每个 Variant 都包含准确文件名、字节数、SHA-256、
-qcow2 Virtual Size、Boot Contract、Source User 与 Immutable Upstream Fallback。
+qcow2 Virtual Size、Boot Contract、Source User 与 Immutable Upstream Provenance。
 
 这些字段来自扫描 Artifact，而不是从 YAML 复制。Build 会强制解析 qcow2，拒绝 Backing File、
 External Data、Encryption 与未知 Incompatible Feature，执行结构检查后才原子替换 Catalog。
@@ -110,9 +110,10 @@ Base Image 变为只读，Node Root Disk 使用 Overlay，因此普通 VM 写入
 Image Catalog Key 授权镜像策略；Release Signing 证明 Farrow 应用工件与 Checksum Manifest。
 两组 Key 刻意独立：有权发布 VM Image 不应自动获得发布 Farrow Binary 的权限，反之亦然。
 
-普通 Public Build 也不会把私有开发 Mirror 编译成默认值，而是从 Embedded Catalog 及其
-Immutable HTTPS Upstream 开始。只有 Public Mirror 本身已经上线，它才可以成为 Compiled
-Default。源码配置、生成 Catalog、上传 Artifact、签名与公开可用性仍是彼此独立的发布门禁。
+普通 Public Build 默认使用 `https://repo.pigsty.io/farrow`，并通过 `--mirror` 显式选择
+`https://repo.pigsty.cc/farrow`；`--repo` 仍是自定义覆盖。仓库一旦选定，它就是唯一工件源；
+Embedded Catalog 的 Upstream URL 继续提供溯源，但绝不会变成隐藏回退。源码配置、生成
+Catalog、上传 Artifact、签名与公开可用性仍是彼此独立的发布门禁。
 
 更大的设计原则是：策略应当便于人类审查，而关于已发布字节的事实必须可生成、可复现，并能
 被独立验证。

content/docs/about/engineering.md

@@ -48,11 +48,18 @@ and its `origin` remote because GoReleaser records repository identity.
 
 ## Image normalization
 
-`packaging/image-pipeline/` accepts an explicit local qcow2 source; it never
-downloads or uploads. It copies and hashes the source, forces qcow2 parsing,
-rejects backing/external/encrypted/unknown features, runs `qemu-img check`, and
-can perform a no-network offline Guest mutation in an explicit QEMU sandbox.
-UID/GID 88 collisions are rejected rather than rewritten ambiguously.
+The low-level `packaging/image-pipeline/build.sh` accepts an explicit local
+qcow2 source and never downloads or uploads. It copies and hashes the source,
+forces qcow2 parsing, rejects backing/external/encrypted/unknown features, runs
+`qemu-img check`, and can perform a no-network offline Guest mutation in an
+explicit QEMU sandbox. UID/GID 88 collisions are rejected rather than rewritten
+ambiguously.
+
+`build-official.py` adds a fixed digest-pinned wrapper for Debian 12/13 and
+Rocky Linux 8/9 on amd64/arm64. It may fetch only the locked source and offline
+package inputs, then emits unsigned `testing` candidates and can assemble a
+separate candidate repository. Native smoke, repeat-build comparison,
+production signing, upload, and Catalog activation remain later gates.
 
 Catalog bytes are exported with:
 

content/docs/about/engineering.zh.md

@@ -42,10 +42,15 @@ GoReleaser 会记录仓库身份。
 
 ## 镜像归一化
 
-`packaging/image-pipeline/` 只接受显式本地 qcow2，不下载也不上传。它复制并哈希源文件，
-强制 qcow2 解析，拒绝 Backing/External/Encryption/未知 Feature，运行 `qemu-img check`，
-并可在显式 QEMU Sandbox 中做无网络 Offline Guest Mutation。UID/GID 88 冲突会拒绝，
-不会含糊改写。
+底层 `packaging/image-pipeline/build.sh` 只接受显式本地 qcow2，不下载也不上传。它复制并
+哈希源文件，强制 qcow2 解析，拒绝 Backing/External/Encryption/未知 Feature，运行
+`qemu-img check`，并可在显式 QEMU Sandbox 中做无网络 Offline Guest Mutation。
+UID/GID 88 冲突会拒绝，不会含糊改写。
+
+`build-official.py` 为 Debian 12/13、Rocky Linux 8/9 的 amd64/arm64 目标增加固定、
+摘要锁定的 Wrapper。它只允许获取锁定的源镜像与离线软件包输入，输出未签名的 `testing`
+Candidate，并可组装独立候选仓库。真机 Smoke、双构建比较、生产签名、上传与 Catalog
+激活仍是后续门禁。
 
 Catalog 逐字节导出命令：
 

content/docs/reference/cli.md

@@ -28,7 +28,7 @@ structured usage error; explicit `--help` always renders human help.
 | Area | Commands |
 |---|---|
 | Prepare | `setup`, `init`, `validate`, `doctor` |
-| Lifecycle | `plan`, `up`, `start`, `stop`, `restart`, `reload`, `recreate`, `status`, `destroy` |
+| Lifecycle | `plan`, `up`, `start`, `stop`, `restart`, `reload`, `recreate`, `status`, `destroy`, `purge` |
 | Access | `ssh`, `exec`, `logs`, `provision`, `ssh-config`, `hosts install/uninstall` |
 | Images | `update`, `image list/info/pull/import/sync/prune/reset`, `repo scan/build/verify` |
 | Host network | `network status/install/uninstall` |
@@ -49,9 +49,11 @@ Frequently used commands have scoped aliases:
 | `ssh-config` | `sc` | `image` | `images`, `im` |
 | `doctor` | `dt` | `network` | `n`, `net` |
 | `exec` / `logs` | `ex` / `l` | `version` | `ver` |
+| `purge` | `rm` |  |  |
 
 `up`, `ssh`, `init`, `start`, `stop`, `restart`, `reload`, `provision`,
-`hosts`, and `completion` have no aliases. Inside a namespace, `hosts` and
+`hosts`, and `completion` have no aliases. `purge` uses `rm` as its explicit
+whole-deployment disposal alias. Inside a namespace, `hosts` and
 `network` use `i`/`u` for install/uninstall; `network status` uses `st`; and
 `image` maps `list=ls`, `info=in`, `pull=p`, `prune=pr`, `sync=sy`,
 and `import=i`. `image reset` keeps `reset-manifest` as a compatibility alias.
@@ -75,7 +77,8 @@ is command-scoped; `-f` is deliberately not a global flag:
 | `-v`, `--verbose` | bounded diagnostics on stderr |
 | `-c`, `--cidr` | select the RFC1918 `/24` for generated `init`/`setup` templates or host-network inspection/install |
 | `-f`, `--file` | select an Inventory for commands that read desired state |
-| `-r`, `--repo` | choose an image/artifact repository for commands that resolve downloads |
+| `-r`, `--repo` | choose an image/artifact repository; overrides `--mirror` and `FARROW_REPO` |
+| `--mirror` | use the China official repository for setup, Catalog, and image-resolving lifecycle commands |
 | `-m`, `--mode` | select `host` or `shared` where the command exposes the macOS network mode |
 | `-d`, `--dry-run` | show a setup/image plan without changing state |
 | `-y`, `--yes` | apply a displayed host/setup/image plan |
@@ -85,12 +88,20 @@ is command-scoped; `-f` is deliberately not a global flag:
 | `--delete-persistent` | during whole destroy, also delete retained data disks; invalid with node selectors |
 | `--purge` | whole-deployment disposal: delete disks, keys, and deployment state; keep images |
 
-Rare or safety-widening controls such as `--force`, `--rollback`, `--remove`,
-`--allow-downgrade`, `--sudo`, `--delete-persistent`, and `--purge` are
+Rare, selection, or safety-widening controls such as `--mirror`, `--force`,
+`--rollback`, `--remove`, `--allow-downgrade`, `--sudo`,
+`--delete-persistent`, and `--purge` are
 long-only. On commands that read an Inventory, `-f` always selects a file;
 `logs -f` retains the conventional `--follow`. `-n` always means `--no-wait`,
 and `-d` always means a dry run.
 
+`farrow purge` (alias `farrow rm`) is the no-confirmation shortcut for
+`farrow destroy --force --purge`. It accepts no nodes or Inventory, removes the
+complete deployment plus persistent disks, keys, state, and the default SSH
+fragment, and keeps images and the host network. With no deployment it succeeds
+without changing the image cache. Missing state never authorizes deletion of
+residual node artifacts whose identity cannot be proven.
+
 If a failing command has not already emitted a richer typed result, structured
 mode writes one object containing `error` and `message` before returning the
 documented non-zero exit code. Existing typed failure results are never followed

content/docs/reference/cli.zh.md

@@ -27,7 +27,7 @@ JSON/YAML 模式下，空命名空间返回结构化用法错误。显式 `--hel
 | 范围 | 命令 |
 |---|---|
 | 准备 | `setup`、`init`、`validate`、`doctor` |
-| 生命周期 | `plan`、`up`、`start`、`stop`、`restart`、`reload`、`recreate`、`status`、`destroy` |
+| 生命周期 | `plan`、`up`、`start`、`stop`、`restart`、`reload`、`recreate`、`status`、`destroy`、`purge` |
 | 访问 | `ssh`、`exec`、`logs`、`provision`、`ssh-config`、`hosts install/uninstall` |
 | 镜像 | `update`、`image list/info/pull/import/sync/prune/reset`、`repo scan/build/verify` |
 | 宿主网络 | `network status/install/uninstall` |
@@ -47,9 +47,11 @@ JSON/YAML 模式下，空命名空间返回结构化用法错误。显式 `--hel
 | `ssh-config` | `sc` | `image` | `images`、`im` |
 | `doctor` | `dt` | `network` | `n`、`net` |
 | `exec` / `logs` | `ex` / `l` | `version` | `ver` |
+| `purge` | `rm` |  |  |
 
 `up`、`ssh`、`init`、`start`、`stop`、`restart`、`reload`、`provision`、`hosts`、
-`completion` 没有别名。命名空间内部，`hosts` 与 `network` 的 install/uninstall 使用
+`completion` 没有别名。`purge` 使用 `rm` 作为明确的整套 Deployment 处置别名。
+命名空间内部，`hosts` 与 `network` 的 install/uninstall 使用
 `i`/`u`，`network status` 使用 `st`；`image` 使用 `list=ls`、`info=in`、`pull=p`、
 `prune=pr`、`sync=sy`、`import=i`。`image reset` 保留 `reset-manifest` 作为兼容别名。
 
@@ -71,7 +73,8 @@ JSON/YAML 模式下，空命名空间返回结构化用法错误。显式 `--hel
 | `-v`、`--verbose` | stderr 有界诊断 |
 | `-c`、`--cidr` | 为 `init`/`setup` 生成模板或宿主网络检查/安装选择 RFC1918 `/24` |
 | `-f`、`--file` | 为读取期望状态的命令选择 Inventory |
-| `-r`、`--repo` | 为需要解析下载的命令选择镜像/制品仓库 |
+| `-r`、`--repo` | 选择镜像/制品仓库；覆盖 `--mirror` 与 `FARROW_REPO` |
+| `--mirror` | 为 setup、Catalog 与需要解析镜像的生命周期命令选择中国官方仓库 |
 | `-m`、`--mode` | 在提供该参数的命令中选择 macOS `host`/`shared` 网络模式 |
 | `-d`、`--dry-run` | 只展示 setup/image 计划，不改变状态 |
 | `-y`、`--yes` | 应用已展示的宿主/setup/image 计划 |
@@ -81,11 +84,16 @@ JSON/YAML 模式下，空命名空间返回结构化用法错误。显式 `--hel
 | `--delete-persistent` | 整体销毁时也删持久盘；不能与节点选择器一起使用 |
 | `--purge` | 整体处置：删除磁盘、密钥与 deployment 状态，保留镜像 |
 
-`--force`、`--rollback`、`--remove`、`--allow-downgrade`、`--sudo`、
+`--mirror`、`--force`、`--rollback`、`--remove`、`--allow-downgrade`、`--sudo`、
 `--delete-persistent`、`--purge` 等低频或扩大风险边界的参数只保留长版本。读取
 Inventory 的命令中 `-f` 始终选择文件；`logs -f` 保留惯用的 `--follow`。
 `-n` 始终表示 `--no-wait`，`-d` 始终表示 Dry-run。
 
+`farrow purge`（别名 `farrow rm`）是不经确认的
+`farrow destroy --force --purge` 快捷路径。它不接受节点或 Inventory，删除整套 Deployment、
+持久盘、密钥、状态和默认 SSH Fragment，保留镜像与宿主网络。没有 Deployment 时幂等成功；
+缺少状态文件绝不会授权按路径删除无法证明身份的遗留节点工件。
+
 如果失败命令尚未输出更丰富的类型化结果，结构化模式会先输出一份包含 `error` 与
 `message` 的对象，再返回约定的非零退出码；已经携带失败状态的结果后面绝不会追加第二份
 JSON/YAML 文档。

content/docs/reference/image-pipeline.md

@@ -5,9 +5,10 @@ weight: 40
 icon: fa-solid fa-shield-halved
 ---
 
-`packaging/image-pipeline/` accepts one already-downloaded immutable qcow2 and
-an independently obtained SHA-256. It never downloads, uploads, touches Farrow
-runtime/network state, reads signing keys, or marks an image `supported`.
+The low-level `packaging/image-pipeline/build.sh` accepts one already-downloaded
+immutable qcow2 and an independently obtained SHA-256. It never downloads,
+uploads, touches Farrow runtime/network state, reads signing keys, or marks an
+image `supported`.
 
 ## Modes
 
@@ -20,6 +21,34 @@ runtime/network state, reads signing keys, or marks an image `supported`.
   removes keys/history/host identity/cloud-init cache, restores targeted SELinux
   labels, and reads back a deterministic marker.
 
+## Official candidate matrix
+
+`build-official.py` wraps the same offline boundary for a fixed eight-target
+matrix: Debian 12/13 and Rocky Linux 8/9, each on amd64 and arm64. Every
+upstream qcow2, RPM/DEB input, release name, digest, and source epoch is pinned
+in `official-v1.json`.
+
+```bash
+./packaging/image-pipeline/build-official.py --list
+
+./packaging/image-pipeline/build-official.py \
+  --source-cache /absolute/source-cache \
+  --package-cache /absolute/package-cache \
+  --output /absolute/existing-output-root \
+  --target d13/arm64 --fetch
+```
+
+Without `--fetch`, every locked input must already exist in the two canonical
+cache directories. With it, the wrapper downloads only the pinned HTTPS URLs
+and rejects any digest mismatch before invoking offline normalization. Debian
+12/13 install the locked XFS userspace closure; Rocky Linux 8 installs the
+locked Python/SELinux closure, and Rocky Linux 9 needs no extra package input.
+
+Each result remains an unsigned `testing` candidate. Supplying all eight bundle
+roots to `--assemble-from` creates a new candidate static repository and runs
+`farrow repo build` plus `verify`; this still does not perform native smoke,
+signing, upload, or Catalog publication.
+
 ```bash
 SOURCE_DATE_EPOCH=1787486400
 

content/docs/reference/image-pipeline.zh.md

@@ -5,8 +5,9 @@ weight: 40
 icon: fa-solid fa-shield-halved
 ---
 
-`packaging/image-pipeline/` 接受一份已下载的不可变 qcow2 与独立获得的 SHA-256。它绝不
-下载、上传、修改 Farrow 运行时/网络状态、读取签名密钥，也不会把镜像标成 `supported`。
+底层 `packaging/image-pipeline/build.sh` 接受一份已下载的不可变 qcow2 与独立获得的
+SHA-256。它绝不下载、上传、修改 Farrow 运行时/网络状态、读取签名密钥，也不会把镜像
+标成 `supported`。
 
 ## 模式
 
@@ -17,6 +18,31 @@ icon: fa-solid fa-shield-halved
   Root SSH，清理密钥/历史/Host Identity/cloud-init Cache，恢复定向 SELinux Label，
   并回读确定性 Marker。
 
+## 官方 Candidate 矩阵
+
+`build-official.py` 在同一离线边界上封装固定的八目标矩阵：Debian 12/13 与 Rocky Linux
+8/9，各自覆盖 amd64、arm64。每份上游 qcow2、RPM/DEB 输入、Release 名称、Digest 与
+Source Epoch 都锁定在 `official-v1.json`。
+
+```bash
+./packaging/image-pipeline/build-official.py --list
+
+./packaging/image-pipeline/build-official.py \
+  --source-cache /absolute/source-cache \
+  --package-cache /absolute/package-cache \
+  --output /absolute/existing-output-root \
+  --target d13/arm64 --fetch
+```
+
+不加 `--fetch` 时，全部锁定输入必须已经位于两个 Canonical Cache 目录；加上后，Wrapper
+也只下载固定 HTTPS URL，并在调用离线归一化前拒绝任何 Digest 不匹配。Debian 12/13
+安装锁定的 XFS 用户态闭包；Rocky Linux 8 安装锁定的 Python/SELinux 闭包；Rocky Linux 9
+不需要额外软件包输入。
+
+每份结果仍是未签名的 `testing` Candidate。把八个 Bundle Root 全部传给
+`--assemble-from` 会创建新的候选静态仓库，并运行 `farrow repo build` 与 `verify`；这仍不
+包含真机 Smoke、签名、上传或 Catalog 发布。
+
 ```bash
 SOURCE_DATE_EPOCH=1787486400