diff --git a/docs/pacman-repo.md b/docs/pacman-repo.md
new file mode 100644
index 00000000..2ad6a6de
--- /dev/null
+++ b/docs/pacman-repo.md
@@ -0,0 +1,41 @@
+# [omarchycn] 软件仓库
+
+OmarchyCN 的 pacman 仓库托管在 Gitea Arch package registry，每个上传的包由
+registry 密钥自动签名，数据库同源生成。
+
+## 接入
+
+```bash
+# 1. 导入并信任 registry 公钥（首次）
+curl -sSf https://git.zacharyzhang.com/api/packages/ZacharyZhang-NY/arch/repository.key -o /tmp/omarchycn-reg.key
+sudo pacman-key --add /tmp/omarchycn-reg.key
+sudo pacman-key --lsign-key 74DCF57ACD812B24D959F146BD386048867B33B4
+
+# 2. 添加仓库
+cat << 'EOF' | sudo tee -a /etc/pacman.conf
+[omarchycn]
+SigLevel = Required DatabaseOptional
+Server = https://git.zacharyzhang.com/api/packages/ZacharyZhang-NY/arch/omarchycn/x86_64
+EOF
+
+# 3. 安装 keyring（含 registry 与 release 两把公钥及信任配置）
+sudo pacman -Sy omarchycn-keyring
+```
+
+## 密钥
+
+| 用途 | 指纹 |
+|---|---|
+| Registry 包签名（Gitea 自动） | `74DCF57ACD812B24D959F146BD386048867B33B4` |
+| Release 产物签名（ISO/清单） | `04490F065F6ADD262A7243506EDF7B8603B5D247`（见 [release-signing.md](release-signing.md)） |
+
+## 发布包
+
+维护者构建与上传（keyring 示例）：
+
+```bash
+./packages/build-keyring.sh
+curl -X PUT -H "Authorization: token <token>" \
+  --upload-file packages/out/omarchycn-keyring-<ver>-any.pkg.tar.zst \
+  https://git.zacharyzhang.com/api/packages/ZacharyZhang-NY/arch/omarchycn
+```