Merge upstream sync b86d4505 (README resolved toward CN rewrite)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QKxGW1raAWaqeU8WdHsMsp

AGENTS.md

@@ -11,13 +11,25 @@ matching guide before starting:
 - [`agents/skills/visual-verification.md`](agents/skills/visual-verification.md) - verifying any change with a visual effect in the running UI
 - [`agents/skills/migrations.md`](agents/skills/migrations.md) - creating or changing migrations under `migrations/`
 
+# OmarchyCN Layer
+
+This fork carries the OmarchyCN China-integration layer on top of upstream `basecamp/omarchy`:
+
+- `bin/omarchycn` routes to `omarchy cn <command>`; all cn commands are `bin/omarchy-cn-*` and follow the upstream bin conventions (metadata, helpers, `$OMARCHY_PATH` — sole exception: the overlay installer bootstraps by resolving its own checkout)
+- `cn/` holds the data layer: `mirrors.json`, `dev-mirrors.json`, `apps.json`, `registry/` (AI providers/harnesses/compatibility), `fcitx5/`, `fontconfig/`, `keys/`, `lib/` (sourced helpers), `release` (cn release number)
+- cn migrations live in `cn/migrations/*.sh`, run by `omarchy-cn-update` with per-file completion markers under `~/.local/state/omarchycn/`
+- Packaging: `packages/omarchy-pkgs-cn.patch` must be applied to the sibling `omarchy-pkgs` checkout so `omarchy-dev` ships `cn/`; keyring in `packages/omarchycn-keyring/`
+- Release process: `docs/release-checklist.md`; signing: `docs/release-signing.md`; pacman repo: `docs/pacman-repo.md`
+- Upstream sync: `.gitea/workflows/upstream-sync.yml` opens a PR per upstream change; keep upstream file edits minimal (currently: one `GROUP_DESCRIPTIONS[cn]` line in `bin/omarchy`, the OmarchyCN section in `default/omarchy/omarchy-menu.jsonc`, a rewritten `README.md` (known recurring sync conflict, resolve toward ours), `AGENTS.md` additions, and two `.gitignore` lines)
+- cn tests: `test/shell.d/omarchycn-test.sh`, `test/shell.d/omarchycn-ai-test.sh`
+
 # Documentation Layout
 
 Three documentation trees, split by genre and audience:
 
 - `agents/skills/` - task procedure ("do this when doing X"), for anyone working on the codebase
 - `docs/` - reference on how the system is shaped (file layout, update pipeline, theming, shell architecture), for anyone working on the codebase; skills link here for depth
-- `manual/` - end-user documentation for using Omarchy, published; never codebase internals
+- `manual/` - end-user documentation for using Omarchy, published; never codebase internals. Chinese user manual for the cn layer lives in `manual/zh-cn/`
 
 # Style
 

bin/omarchy-cn-channel

@@ -0,0 +1,29 @@
+#!/bin/bash
+# omarchy:summary=Show or set the OmarchyCN release channel
+# omarchy:args=[stable|beta|nightly]
+# omarchy:examples=omarchycn channel | omarchycn channel beta
+
+set -euo pipefail
+
+CHANNEL_FILE="$HOME/.config/omarchycn/channel"
+
+if (( $# == 0 )); then
+  if [[ -f $CHANNEL_FILE ]]; then
+    cat "$CHANNEL_FILE"
+  else
+    echo "beta (default)"
+  fi
+  exit 0
+fi
+
+case "$1" in
+stable | beta | nightly)
+  mkdir -p "${CHANNEL_FILE%/*}"
+  echo "$1" > "$CHANNEL_FILE"
+  echo "Channel: $1"
+  ;;
+*)
+  echo "Unknown channel: $1 (stable|beta|nightly)" >&2
+  exit 1
+  ;;
+esac

bin/omarchy-cn-update

@@ -19,10 +19,49 @@ if [[ ! -d $src/.git ]]; then
   exit 1
 fi
 
+channel=$(omarchy-cn-channel)
+channel=${channel%% *}
+
 old=$(git -C "$src" rev-parse --short HEAD)
-git -C "$src" pull --ff-only
+git -C "$src" fetch -q --tags origin
+
+case "$channel" in
+nightly)
+  git -C "$src" checkout -q quattro
+  git -C "$src" pull --ff-only origin quattro
+  ;;
+beta)
+  tag=$(git -C "$src" tag -l "*-cn.*" | sort -V | tail -1)
+  if [[ -z $tag ]]; then
+    echo "beta 通道无可用发布 tag" >&2
+    exit 1
+  fi
+  git -C "$src" checkout -q "$tag"
+  ;;
+stable)
+  tag=$(git -C "$src" tag -l "*-cn.*" | grep -vE "alpha|beta|rc" | sort -V | tail -1 || true)
+  if [[ -z $tag ]]; then
+    echo "当前尚无 stable 发布（omarchycn channel beta 可跟随预发布）" >&2
+    exit 1
+  fi
+  git -C "$src" checkout -q "$tag"
+  ;;
+*)
+  echo "Unknown channel: $channel" >&2
+  exit 1
+  ;;
+esac
+
+# Never move onto a tree that predates the channel mechanism: its update
+# command cannot switch back, stranding the install
+if [[ ! -f $src/bin/omarchy-cn-channel ]]; then
+  git -C "$src" checkout -q "$old"
+  echo "$channel 通道的目标发布早于通道机制，已回退；请使用 nightly 或更新的发布" >&2
+  exit 1
+fi
+
 new=$(git -C "$src" rev-parse --short HEAD)
-echo "Source: $old -> $new"
+echo "Channel: $channel, source: $old -> $new"
 
 "$src/bin/omarchy-cn-install-overlay"
 

bin/omarchy-launch-docker-tui

@@ -9,10 +9,12 @@
 # no prompt. lazydocker needs the root-owned Docker socket, so when the group is
 # absent, gate that access behind a polkit prompt. If the user has opted into
 # sudoless Docker (omarchy-setup-security-sudoless-docker), the socket is already
-# reachable, so run lazydocker directly. pkexec sanitizes the environment, so
-# carry TERM through for the TUI to render and run lazydocker from root's PATH.
-if id -nG 2>/dev/null | grep -qw docker; then
-  exec lazydocker
-else
+# reachable, so run lazydocker directly — omarchy-sudo-docker answers that for
+# this session, so the prompt stays until the reboot that grants the group.
+# pkexec sanitizes the environment, so carry TERM through for the TUI to render
+# and run lazydocker from root's PATH.
+if omarchy-sudo-docker; then
   exec pkexec /usr/bin/env TERM="${TERM:-xterm-256color}" lazydocker
+else
+  exec lazydocker
 fi

bin/omarchy-remove-security-sudoless-docker

@@ -5,7 +5,10 @@
 
 set -e
 
-if ! id -nG "$USER" 2>/dev/null | grep -qw docker; then
+# Ask about the configured groups, not this session's: right after enabling,
+# sudoless Docker is on for the account even though the running session still
+# needs a prompt, and this command is what turns it back off.
+if omarchy-sudo-docker --configured; then
   echo "Sudoless Docker is not enabled: $USER is not in the docker group."
   exit 0
 fi
@@ -13,13 +16,19 @@ fi
 echo "Removing $USER from the docker group..."
 sudo gpasswd -d "$USER" docker >/dev/null
 
-# Group membership is fixed at login, so the running session keeps its docker
-# access until it ends. Flag a reboot so omarchy-update-restart prompts for one
-# (and the bar shows it pending); a plain log out and back in works too.
+# Group membership is only re-read by a fresh session, and in practice logging
+# out or newgrp isn't enough — only a reboot reliably applies it. Record it so a
+# later `omarchy update` still prompts (omarchy-update-restart reads this), then
+# offer to do it now.
 omarchy-state set reboot-required
 
 echo ""
-echo "Sudoless Docker DISABLED. Reboot (or log out and back in) for the change to take effect."
-echo "Docker access now goes through a polkit/sudo prompt again: the Docker TUI"
-echo "(Super + Shift + D) and the Windows VM will ask when they need it, and the"
-echo "plain 'docker' CLI runs under sudo."
+echo "Sudoless Docker DISABLED. Docker access goes through a polkit/sudo prompt"
+echo "again: the Docker TUI (Super + Shift + D) and the Windows VM ask when they"
+echo "need it, and the plain 'docker' CLI runs under sudo. It takes effect after a reboot."
+echo ""
+# The migration reuses this command during 'omarchy update' and defers the
+# reboot to omarchy-update-restart, so it doesn't cut the update short.
+if [[ -z ${OMARCHY_DEFER_REBOOT:-} ]] && gum confirm "Reboot now to apply?"; then
+  omarchy-system-reboot
+fi

bin/omarchy-setup-security-sudoless-docker

@@ -5,7 +5,9 @@
 
 set -e
 
-if id -nG "$USER" 2>/dev/null | grep -qw docker; then
+# Ask about the configured groups, not this session's: once enabled it stays
+# enabled for the account even before the reboot that lets this session use it.
+if ! omarchy-sudo-docker --configured; then
   echo "Sudoless Docker is already enabled: $USER is in the docker group."
   echo "To disable it again, run: omarchy-remove-security-sudoless-docker"
   exit 0
@@ -28,14 +30,20 @@ echo ""
 
 if gum confirm "Enable sudoless Docker? This gives anything running as you passwordless root."; then
   sudo usermod -aG docker "$USER"
-  # Group membership is fixed at login, so docker won't be reachable without a
-  # prompt until the session restarts. Flag a reboot so omarchy-update-restart
-  # prompts for one (and the bar shows it pending).
+  # A new docker group membership is only picked up by a fresh session, and in
+  # practice logging out or newgrp isn't enough — only a reboot reliably applies
+  # it. Record it so a later `omarchy update` still prompts
+  # (omarchy-update-restart reads this), then offer to do it now.
   omarchy-state set reboot-required
   echo ""
-  echo "Sudoless Docker ENABLED. Reboot, or log out and back in (or run 'newgrp docker'),"
-  echo "for the new group membership to take effect."
-  echo "To disable it again, run: omarchy-remove-security-sudoless-docker"
+  echo "Sudoless Docker ENABLED. It takes effect after a reboot."
+  echo "To disable it again: Setup > Security > Sudoless Docker."
+  echo ""
+  # The migration reuses this command during 'omarchy update' and defers the
+  # reboot to omarchy-update-restart, so it doesn't cut the update short.
+  if [[ -z ${OMARCHY_DEFER_REBOOT:-} ]] && gum confirm "Reboot now to apply?"; then
+    omarchy-system-reboot
+  fi
 else
   echo "Aborted. No changes made. Docker access still goes through a prompt."
 fi

bin/omarchy-sudo-docker

@@ -0,0 +1,44 @@
+#!/bin/bash
+
+# omarchy:summary=Succeed when Docker needs sudo, fail when it can be used directly
+# omarchy:args=[--configured]
+# omarchy:examples=omarchy-sudo-docker && echo "needs sudo" | omarchy-sudo-docker --configured
+# omarchy:hidden=true
+
+# The docker group is root-equivalent, so Omarchy leaves users out of it by
+# default and reaches the daemon through a prompt instead. Everything that has
+# to make that choice asks here rather than testing group membership itself.
+#
+# Two questions, because they have different answers between toggling sudoless
+# Docker and the reboot that applies it (group membership is fixed when the
+# session is created):
+#
+#   (default)      Does Docker need sudo *right now*? Answered by whether this
+#                  process can actually reach the socket, which is what decides
+#                  if a command must elevate. Still true in the window after
+#                  sudoless Docker is enabled but before the reboot.
+#   --configured   Will it need sudo once the account's groups take effect?
+#                  Answered from the account's configured groups, so the menu
+#                  offers the toggle that can actually change state.
+#
+# Succeeds (exit 0) when sudo is needed, so it reads as `if omarchy-sudo-docker`.
+
+DOCKER_SOCKET="${OMARCHY_DOCKER_SOCKET:-/var/run/docker.sock}"
+
+case "${1:-}" in
+--configured)
+  # An account in the docker group will not need sudo after the next login.
+  id -nG "$USER" 2>/dev/null | grep -qw docker && exit 1
+  exit 0
+  ;;
+"")
+  # A socket we can write is a daemon we can drive without elevating. A missing
+  # socket counts as needing sudo: reaching it means starting it as root anyway.
+  [[ -w $DOCKER_SOCKET ]] && exit 1
+  exit 0
+  ;;
+*)
+  echo "Usage: omarchy-sudo-docker [--configured]" >&2
+  exit 2
+  ;;
+esac

bin/omarchy-windows-vm

@@ -31,8 +31,11 @@ CONTAINER="omarchy-windows"
 
 # --- privilege helpers -------------------------------------------------------
 
-# True when the user can reach the Docker socket directly (sudoless Docker on).
-in_docker_group() { id -nG 2>/dev/null | grep -qw docker; }
+# True when this session can reach the Docker socket directly (sudoless Docker
+# on and in effect). Asking about the socket rather than the configured groups
+# keeps the prompt in place through the window where sudoless Docker is enabled
+# but the reboot that grants the group has not happened yet.
+docker_needs_sudo() { omarchy-sudo-docker; }
 
 # The command to hand pkexec for the privileged re-exec. pkexec runs whatever
 # executable it is given (after authorization) and only shows the path in the
@@ -64,7 +67,7 @@ priv_target() {
 priv() {
   local action="$1"
   shift
-  if [[ $action != write_compose ]] && in_docker_group; then
+  if [[ $action != write_compose ]] && ! docker_needs_sudo; then
     "__priv_$action" "$@"
     return
   fi

cn/release

@@ -1 +1 @@
-2
+3

default/omarchy/omarchy-menu.jsonc

@@ -179,7 +179,7 @@
   "setup.security.fido2": {"icon":"","label":"Fido2","action":"omarchy-launch-floating-terminal-with-presentation omarchy-setup-security-fido2"},
   "setup.security.sshd": {"icon":"󰣀","label":"SSHD","action":"omarchy-launch-floating-terminal-with-presentation omarchy-setup-security-sshd"},
   "setup.security.passwordless-sudo": {"icon":"󰟵","label":"Passwordless Sudo","action":"omarchy-launch-floating-terminal-with-presentation omarchy-sudo-passwordless"},
-  "setup.security.sudoless-docker": {"icon":"󰡨","label":"Sudoless Docker","action":"omarchy-launch-floating-terminal-with-presentation omarchy-setup-security-sudoless-docker"},
+  "setup.security.sudoless-docker": {"icon":"󰡨","label":"Sudoless Docker","when":"omarchy-sudo-docker --configured","action":"omarchy-launch-floating-terminal-with-presentation omarchy-setup-security-sudoless-docker"},
   "setup.config.hyprland": {"icon":"","label":"Hyprland","action":"omarchy-launch-config-editor \"$HOME/.config/hypr/hyprland.lua\""},
   "setup.config.hyprsunset": {"icon":"","label":"Hyprsunset","action":"omarchy-launch-config-editor ~/.config/hypr/hyprsunset.conf && omarchy-restart-hyprsunset"},
   "setup.config.xcompose": {"icon":"󰞅","label":"XCompose","action":"omarchy-launch-config-editor ~/.XCompose && omarchy-restart-xcompose"},
@@ -291,7 +291,7 @@
   "remove.security.fingerprint": {"icon":"󰈷","label":"Fingerprint","when":"omarchy-pkg-present fprintd","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-security-fingerprint"},
   "remove.security.fido2": {"icon":"","label":"Fido2","when":"omarchy-pkg-present pam-u2f","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-security-fido2"},
   "remove.security.sshd": {"icon":"󰣀","label":"SSHD","when":"systemctl is-enabled --quiet sshd","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-security-sshd"},
-  "remove.security.sudoless-docker": {"icon":"󰡨","label":"Sudoless Docker","when":"id -nG | grep -qw docker","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-security-sudoless-docker"},
+  "remove.security.sudoless-docker": {"icon":"󰡨","label":"Sudoless Docker","when":"! omarchy-sudo-docker --configured","action":"omarchy-launch-floating-terminal-with-presentation omarchy-remove-security-sudoless-docker"},
   "remove.browser.chrome": {"icon":"","label":"Chrome","when":"omarchy-pkg-present google-chrome","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-browser chrome'"},
   "remove.browser.edge": {"icon":"󰇩","label":"Edge","when":"omarchy-pkg-present microsoft-edge-stable-bin","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-browser edge'"},
   "remove.browser.brave": {"icon":"","label":"Brave","when":"omarchy-pkg-present brave-bin","action":"omarchy-launch-floating-terminal-with-presentation 'omarchy-remove-browser brave'"},

docs/release-checklist.md

@@ -0,0 +1,30 @@
+# Release Checklist
+
+每次发布 `<upstream>-cn.<n>` 按序执行，任一步失败即停止：
+
+1. `./test/all`：相对上游基线零新增失败；`test/shell.d/omarchycn-*.sh` 全绿
+2. 用 `--local-source` 重建 ISO（`packages/omarchy-pkgs-cn.patch` 已应用到 omarchy-pkgs）
+3. 验证 omarchy-dev 包含 cn 层（`tar -tf … | grep usr/share/omarchy/cn/`）
+4. QEMU OVMF UEFI 冒烟：进入安装器欢迎屏
+5. `sha256sum` → `SHA256SUMS.txt`；签名 SUMS 与 ISO（发布子钥）
+6. SBOM 两份：syft（live airootfs）+ 离线仓库 .PKGINFO 采集
+7. `release.json`（版本、双向提交、包版本表、迁移列表、min_compatible、产物清单）→ 签名 release.json
+8. 建 tag 与 Release，上传全部产物，Release Notes 写明上游基线与已知问题
+9. 匿名回读已发布 ISO 并 sha256 复核 == 本地构建值
+10. `cn/release` 数字 +1，提交
+
+## 版本规则
+
+`<omarchy-upstream-version>-cn.<n>`；`min_compatible` 只在有破坏性迁移时前移。
+
+# 上游同步 SLA
+
+- `upstream-sync.yml` 每日拉取 basecamp/omarchy quattro，自动开同步 PR（含试合并冲突标注）
+- 常规变更：7 天内完成审查合并；上游安全修复：48 小时内
+- 合并后必须重跑第 1 步测试门禁
+
+# 安全响应
+
+- 接报渠道见 `SECURITY.md`，72 小时内确认
+- 涉及发布密钥泄露：按 `docs/release-signing.md` 轮换流程处理，吊销并公告
+- 修复发布走本清单完整流程，不走捷径

manual/zh-cn/01-install.md

@@ -0,0 +1,35 @@
+# 安装 OmarchyCN
+
+## 下载与校验
+
+从 [Releases](https://git.zacharyzhang.com/ZacharyZhang-NY/omarchycn/releases) 下载最新 ISO 及 `SHA256SUMS.txt`、`SHA256SUMS.txt.asc`：
+
+```bash
+curl -sSf https://git.zacharyzhang.com/ZacharyZhang-NY/omarchycn/raw/branch/quattro/cn/keys/omarchycn-release.asc | gpg --import
+gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt
+sha256sum -c SHA256SUMS.txt
+```
+
+签名主钥指纹应为 `04490F065F6ADD262A7243506EDF7B8603B5D247`（详见 `docs/release-signing.md`）。
+
+## 写盘与启动
+
+Linux 用 `caligula` 或 `dd`，Mac/Windows 用 balenaEtcher 写入 U 盘，UEFI 模式启动，按提示完成 Omarchy 安装（磁盘、用户、加密等流程与上游一致）。
+
+## 首次进入桌面后
+
+```bash
+omarchycn setup
+```
+
+向导依次配置：语言、时区、显示缩放、中文 locale、中文字体、Fcitx5+Rime 输入法、输入法切换键、pacman 镜像、开发工具镜像、国内应用、AI Hub、隐私说明。每一步都可跳过，中断后重跑会从未完成的步骤继续。
+
+## 现有 Omarchy 叠加安装（Overlay）
+
+```bash
+git clone https://git.zacharyzhang.com/ZacharyZhang-NY/omarchycn.git
+cd omarchycn && ./bin/omarchy-cn-install-overlay
+omarchy cn version   # 验证
+```
+
+卸载：`omarchy-cn-install-overlay --uninstall`。更新：`omarchycn update`。

manual/zh-cn/02-mirrors.md

@@ -0,0 +1,37 @@
+# 镜像管理
+
+## pacman 镜像
+
+```bash
+omarchycn mirror benchmark        # 测速：延迟、吞吐、同步新鲜度
+omarchycn mirror apply china      # 自动选最优中国镜像（1 主 + 2 备）
+omarchycn mirror apply official   # 回到官方全球源
+omarchycn mirror pin tuna         # 固定单一镜像
+omarchycn mirror status           # 当前策略与镜像列表
+omarchycn mirror restore          # 恢复最近一次备份
+```
+
+每次写入 `/etc/pacman.d/mirrorlist` 前自动生成带时间戳备份。候选列表在 `cn/mirrors.json`。
+
+主镜像失效时：
+
+```bash
+omarchycn doctor mirror --fix     # 检测并自动切换到健康镜像
+```
+
+## 开发工具镜像
+
+覆盖 npm、pip、cargo、go、gem、docker 六个生态：
+
+```bash
+omarchycn dev-mirror list                          # 当前各生态源
+omarchycn dev-mirror apply china                   # 全部切国内
+omarchycn dev-mirror apply official --target npm   # 指定生态切官方
+omarchycn dev-mirror set npm https://my.registry/  # 自定义
+omarchycn dev-mirror doctor                        # 连通性检查
+```
+
+写入前备份到 `~/.local/state/omarchycn/backups/dev-mirror/<时间戳>/`，
+恢复：`omarchycn restore list` + `omarchycn restore config <时间戳>`（仅用户级文件）。
+docker 目标写 `/etc/docker/daemon.json`（需 sudo，重启 docker 生效；系统文件不参与
+自动恢复，回退用 `omarchycn dev-mirror apply official --target docker`）。

manual/zh-cn/03-ime.md

@@ -0,0 +1,34 @@
+# 中文输入与字体
+
+## 一键配置
+
+```bash
+omarchycn locale apply   # 生成 zh_CN.UTF-8 / en_US.UTF-8
+omarchycn font apply     # 思源黑体/宋体 + emoji + fallback 优先级
+omarchycn ime apply      # Fcitx5 + Rime，默认拼音
+```
+
+字体配置保证中文优先落到简体字形（含无语言标签的 Chromium/Electron 路径），
+日文/韩文标签内容仍使用各自原生变体。验证：`omarchycn font status`。
+
+## 切换键
+
+默认 `Ctrl+Space`（Fcitx5 原生）。改用 `Super+Space`：
+
+```bash
+omarchycn ime hotkey super-space
+```
+
+此时 Omarchy 主菜单自动迁移到 `Super+Alt+Space`（原 Apps 菜单快捷键让位，
+可从主菜单进入 Apps 或在 `~/.config/hypr/bindings.lua` 自行改绑）。
+切回：`omarchycn ime hotkey ctrl-space`（自动移除迁移块）。
+
+## 排查
+
+```bash
+omarchycn ime status     # 包、profile、切换键冲突、进程状态
+omarchycn doctor ime
+```
+
+上游已内置 fcitx 环境变量（`INPUT_METHOD/QT_IM_MODULE/XMODIFIERS/SDL_IM_MODULE`）
+与 `omarchy-fcitx5` 用户服务，OmarchyCN 不重复配置。

manual/zh-cn/04-ai.md

@@ -0,0 +1,36 @@
+# AI Hub
+
+Harness（工具）与 Provider（模型服务）分层管理，配置数据在 `cn/registry/`。
+
+## 快速开始
+
+```bash
+omarchycn ai setup       # 向导：Harness → Provider → 模型 → API Key → 测试
+omarchycn ai launch      # 以默认 Profile 启动
+```
+
+支持组合（stable = 有 mock 回归覆盖的适配器）：
+
+| Harness | DeepSeek | Kimi | Z.AI/GLM |
+|---|---|---|---|
+| Claude Code | stable | stable | stable |
+| Codex | stable | — | — |
+| OpenCode | stable | — | — |
+| Kimi Code | — | 官方 CLI 自管 | — |
+| Deep Code | 官方 CLI 自管 | — | — |
+
+## 手动操作
+
+```bash
+omarchycn ai secret set deepseek          # 存 Key（Secret Service → pass → 0600 文件）
+omarchycn ai profile create work claude-code deepseek default-coding
+omarchycn ai profile use work
+omarchycn ai test work                    # 真实连通/鉴权/模型调用测试
+omarchycn ai doctor                       # 安装、凭据、端点诊断
+omarchycn ai default work                 # 映射到 Super+Shift+Ctrl+A / omarchy agent
+```
+
+`ai default` 把配置持久化进 Harness 自身文件（Claude Code 的 settings.json /
+Codex 的 config.toml，均 0600 并保留你的其它设置），上游快捷键即以国内模型启动。
+
+注意：`ai test` 消耗一次极小请求（max_tokens=8），需有效 API Key 与账户额度。

manual/zh-cn/05-recovery.md

@@ -0,0 +1,36 @@
+# 更新与恢复
+
+## 更新
+
+- ISO 安装：系统随上游 `omarchy update`；cn 层当前随新版 ISO 迭代（[omarchycn] pacman 仓库暂只分发 keyring，omarchy-dev 包上仓后将改为 pacman 更新）
+- Overlay 安装：`omarchycn update`（拉取源码 → 重装 overlay → 执行未跑过的 cn 迁移）
+
+## 备份位置
+
+| 内容 | 位置 |
+|---|---|
+| pacman mirrorlist | `/etc/pacman.d/mirrorlist.omarchycn-bak-<时间戳>` |
+| 开发工具镜像配置 | `~/.local/state/omarchycn/backups/dev-mirror/<时间戳>/` |
+| 输入法 profile | `~/.local/state/omarchycn/backups/ime/<时间戳>/` |
+| 显示缩放 | `~/.config/hypr/monitors.lua.omarchycn-prev` |
+| Codex/Claude 配置 | 同目录 `*.omarchycn-bak-<时间戳>` |
+
+## 恢复
+
+```bash
+omarchycn restore list               # 列出全部备份
+omarchycn restore config <时间戳>    # 恢复开发工具镜像配置
+omarchycn mirror restore             # 恢复 pacman mirrorlist
+```
+
+系统级快照与回滚沿用上游 Btrfs + Snapper 机制（见上游手册 System snapshots）。
+
+## 诊断
+
+```bash
+omarchycn doctor            # network + mirror + dev-mirror + ime
+omarchycn ai doctor
+omarchycn status            # 版本与配置概览
+```
+
+诊断只在本地输出，不上传任何数据。

migrations/1787580187.sh

@@ -2,13 +2,15 @@ echo "Move this install to the opt-in docker group default (the group is root-eq
 
 # The docker group grants passwordless root (a container can bind-mount / and
 # rewrite the host), so Omarchy no longer puts users in it by default. Bring
-# existing installs in line: remove this user from the group if present. It takes
-# effect at next login, and the current session keeps working until then. Anyone
-# who wants passwordless docker back can opt in, behind a warning, with
+# existing installs in line: remove this user from the group if present. The
+# change applies after a reboot, so it stays reachable until then. Anyone who
+# wants passwordless docker back can opt in, behind a warning, with
 # Setup > Security > Sudoless Docker. Reuses the removal command so there is one
-# source of truth for the privileged change and its notice.
+# source of truth for the privileged change and its notice; DEFER_REBOOT keeps
+# it from prompting mid-update — omarchy-update-restart handles the reboot once
+# the whole update has finished.
 if id -nG "$USER" | grep -qw docker; then
-  omarchy-remove-security-sudoless-docker
+  OMARCHY_DEFER_REBOOT=1 omarchy-remove-security-sudoless-docker
 fi
 
 # The Docker app entry copied into ~/.local/share/applications used to run

test/shell.d/docker-group-migration-test.sh

@@ -39,16 +39,30 @@ cat >"$stub_bin/gpasswd" <<'STUB'
 #!/bin/bash
 echo "$@" >>"${GPASSWD_CALLS:?}"
 STUB
-chmod +x "$stub_bin/id" "$stub_bin/sudo" "$stub_bin/gpasswd"
+# gum confirm always says yes, and reboot records that it fired: the migration
+# must still NOT reboot (it defers to omarchy-update-restart), so neither should
+# be reached.
+cat >"$stub_bin/gum" <<'STUB'
+#!/bin/bash
+[[ $1 == confirm ]] && exit 0
+exit 0
+STUB
+cat >"$stub_bin/omarchy-system-reboot" <<'STUB'
+#!/bin/bash
+touch "${REBOOT_CALLED:?}"
+STUB
+chmod +x "$stub_bin/id" "$stub_bin/sudo" "$stub_bin/gpasswd" "$stub_bin/gum" "$stub_bin/omarchy-system-reboot"
 
 reboot_flag="$home/.local/state/omarchy/reboot-required"
 gpasswd_calls="$test_dir/gpasswd-calls"
+reboot_called="$test_dir/reboot-called"
 launcher="$home/.local/share/applications/Docker.desktop"
 
 run_migration() {
-  rm -f "$gpasswd_calls" "$reboot_flag"
+  rm -f "$gpasswd_calls" "$reboot_flag" "$reboot_called"
   HOME="$home" OMARCHY_PATH="$omarchy_path" USER="tester" STUB_GROUPS="$1" \
-    GPASSWD_CALLS="$gpasswd_calls" PATH="$stub_bin:$ROOT/bin:$PATH" \
+    GPASSWD_CALLS="$gpasswd_calls" REBOOT_CALLED="$reboot_called" \
+    PATH="$stub_bin:$ROOT/bin:$PATH" \
     bash -euo pipefail "$migration" >/dev/null 2>&1
 }
 
@@ -56,6 +70,7 @@ run_migration() {
 run_migration "wheel input docker" || fail "migration runs when the user is in the docker group"
 grep -q -- "-d tester docker" "$gpasswd_calls" || fail "migration removes the user from the docker group"
 [[ -f $reboot_flag ]] || fail "migration flags a reboot so the group change takes effect"
+[[ ! -f $reboot_called ]] || fail "migration must defer the reboot (not reboot mid-update)"
 [[ $(cat "$launcher") == "NEW-LAUNCHER" ]] || fail "migration refreshes the stale Docker launcher entry"
 pass "migration removes the group, flags a reboot, and refreshes the launcher"
 

test/shell.d/sudo-docker-test.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+#
+# omarchy-sudo-docker is the single answer to "does Docker need sudo", and it
+# answers two different questions on purpose. The default asks whether this
+# session can reach the socket, which is what decides if a command must elevate.
+# --configured asks whether the account is set up for sudoless Docker, which is
+# what the menu needs so it offers the toggle that can change state. Between
+# enabling sudoless Docker and the reboot that grants the group, those disagree.
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+TMPDIR=$(mktemp -d)
+trap 'rm -rf "$TMPDIR"' EXIT
+
+command="$ROOT/bin/omarchy-sudo-docker"
+
+# Stub id so the configured groups are controllable.
+mkdir -p "$TMPDIR/bin"
+cat >"$TMPDIR/bin/id" <<'STUB'
+#!/bin/bash
+printf '%s\n' "${STUB_GROUPS:-wheel input}"
+STUB
+chmod +x "$TMPDIR/bin/id"
+
+# A writable stand-in means the socket is reachable; an unwritable one means it
+# is not. Test the file mode rather than a live daemon.
+reachable_socket="$TMPDIR/reachable.sock"
+blocked_socket="$TMPDIR/blocked.sock"
+touch "$reachable_socket" "$blocked_socket"
+chmod 600 "$reachable_socket"
+chmod 400 "$blocked_socket"
+
+run() { # SOCKET GROUPS [--configured]
+  env PATH="$TMPDIR/bin:$PATH" OMARCHY_DOCKER_SOCKET="$1" STUB_GROUPS="$2" USER=tester \
+    bash "$command" ${3:+"$3"}
+}
+
+# Default mode follows the socket, not the group list.
+run "$blocked_socket" "wheel input" || fail "an unreachable socket means Docker needs sudo"
+run "$reachable_socket" "wheel input" && fail "a reachable socket means Docker does not need sudo"
+pass "default mode answers from the socket this session can reach"
+
+# A socket that isn't there at all still needs elevation (starting it is root work).
+run "$TMPDIR/absent.sock" "wheel input docker" || fail "a missing socket means Docker needs sudo"
+pass "a missing socket counts as needing sudo"
+
+# --configured follows the account's groups, not the socket.
+run "$blocked_socket" "wheel input docker" --configured && fail "a configured docker group means no sudo is needed"
+run "$reachable_socket" "wheel input" --configured || fail "no docker group means sudo is needed"
+pass "--configured answers from the account's groups"
+
+# The window this split exists for: sudoless Docker has just been enabled, so the
+# account carries the group while the running session still cannot use it. The
+# menu must offer Remove (--configured says no sudo) while lazydocker and the
+# Windows VM must still prompt (default says sudo).
+run "$blocked_socket" "wheel input docker" || fail "the session still needs sudo before the reboot"
+run "$blocked_socket" "wheel input docker" --configured && fail "the account is already configured for sudoless Docker"
+pass "the two modes disagree between enabling sudoless Docker and the reboot"
+
+# An unknown argument is a usage error, not a silent answer either way.
+run "$reachable_socket" "wheel input" --bogus 2>/dev/null && fail "an unknown flag exits non-zero"
+status=0
+run "$reachable_socket" "wheel input" --bogus >/dev/null 2>&1 || status=$?
+(( status == 2 )) || fail "an unknown flag exits 2, not the boolean 1"
+pass "an unknown flag is a usage error"

test/shell.d/sudoless-docker-toggle-test.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+#
+# Toggling sudoless Docker changes the docker group, which only takes effect on a
+# reboot. The setup/remove commands must flag the reboot and offer to do it now
+# (gum confirm), but defer it when OMARCHY_DEFER_REBOOT is set (the migration
+# reuses them inside `omarchy update`, where omarchy-update-restart handles it).
+
+set -euo pipefail
+
+source "$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)/base-test.sh"
+
+test_dir=$(mktemp -d)
+trap 'rm -rf "$test_dir"' EXIT
+home="$test_dir/home"
+stub_bin="$test_dir/bin"
+mkdir -p "$home" "$stub_bin"
+
+cat >"$stub_bin/id" <<'STUB'
+#!/bin/bash
+printf '%s\n' "${STUB_GROUPS:-wheel input}"
+STUB
+cat >"$stub_bin/sudo" <<'STUB'
+#!/bin/bash
+exec "$@"
+STUB
+cat >"$stub_bin/usermod" <<'STUB'
+#!/bin/bash
+echo "$@" >>"${USERMOD_CALLS:?}"
+STUB
+cat >"$stub_bin/gpasswd" <<'STUB'
+#!/bin/bash
+echo "$@" >>"${GPASSWD_CALLS:?}"
+STUB
+cat >"$stub_bin/gum" <<'STUB'
+#!/bin/bash
+touch "${GUM_CALLED:?}"
+exit "${GUM_ANSWER:-0}"
+STUB
+cat >"$stub_bin/omarchy-system-reboot" <<'STUB'
+#!/bin/bash
+touch "${REBOOT_CALLED:?}"
+STUB
+chmod +x "$stub_bin"/*
+
+reboot_flag="$home/.local/state/omarchy/reboot-required"
+gum_called="$test_dir/gum-called"
+reboot_called="$test_dir/reboot-called"
+gpasswd_calls="$test_dir/gpasswd-calls"
+usermod_calls="$test_dir/usermod-calls"
+
+run() { # command STUB_GROUPS GUM_ANSWER DEFER(0|1)
+  rm -f "$reboot_flag" "$gum_called" "$reboot_called" "$gpasswd_calls" "$usermod_calls"
+  local defer_env=()
+  [[ ${4:-0} == 1 ]] && defer_env=(OMARCHY_DEFER_REBOOT=1)
+  env HOME="$home" USER="tester" STUB_GROUPS="$2" GUM_ANSWER="$3" \
+    GUM_CALLED="$gum_called" REBOOT_CALLED="$reboot_called" \
+    GPASSWD_CALLS="$gpasswd_calls" USERMOD_CALLS="$usermod_calls" \
+    PATH="$stub_bin:$ROOT/bin:$PATH" "${defer_env[@]}" \
+    bash "$ROOT/bin/$1" >/dev/null 2>&1
+}
+
+# Remove, interactive, reboot confirmed -> group removed, flag set, reboot fired.
+run omarchy-remove-security-sudoless-docker "wheel input docker" 0 0
+grep -q -- "-d tester docker" "$gpasswd_calls" || fail "remove drops the user from the docker group"
+[[ -f $reboot_flag ]] || fail "remove flags a reboot"
+[[ -f $reboot_called ]] || fail "remove reboots when the prompt is confirmed"
+pass "remove drops the group, flags a reboot, and reboots on confirm"
+
+# Remove, interactive, reboot declined -> flag set, but no reboot.
+run omarchy-remove-security-sudoless-docker "wheel input docker" 1 0
+[[ -f $reboot_flag ]] || fail "remove still flags a reboot when the prompt is declined"
+[[ ! -f $reboot_called ]] || fail "remove does not reboot when the prompt is declined"
+pass "remove leaves the reboot to the user when declined"
+
+# Remove, deferred (migration/update) -> flag set, prompt never shown.
+run omarchy-remove-security-sudoless-docker "wheel input docker" 0 1
+[[ -f $reboot_flag ]] || fail "deferred remove still flags a reboot"
+[[ ! -f $gum_called ]] || fail "deferred remove must not prompt to reboot"
+[[ ! -f $reboot_called ]] || fail "deferred remove must not reboot"
+pass "deferred remove flags the reboot without prompting"
+
+# Remove, already out of the group -> no-op, nothing flagged.
+run omarchy-remove-security-sudoless-docker "wheel input" 0 0
+[[ ! -f $gpasswd_calls ]] || fail "remove is a no-op when the user is not in the docker group"
+[[ ! -f $reboot_flag ]] || fail "remove does not flag a reboot when nothing changed"
+pass "remove is a no-op when sudoless Docker is already off"
+
+# Setup, enable confirmed then reboot confirmed -> group added, flag set, reboot.
+run omarchy-setup-security-sudoless-docker "wheel input" 0 0
+grep -q -- "-aG docker tester" "$usermod_calls" || fail "setup adds the user to the docker group"
+[[ -f $reboot_flag ]] || fail "setup flags a reboot"
+[[ -f $reboot_called ]] || fail "setup reboots when the prompt is confirmed"
+pass "setup adds the group, flags a reboot, and reboots on confirm"