docs: explain cleanup when updating existing machines

.github/CONCEPTS.md

@@ -48,6 +48,8 @@ Not every configuration is fully replaced. Applications such as Codex and Claude
 
 Replace subtrees that source fully owns so that removed fields disappear from the destination. For shared subtrees, preserve application-owned fields through an overlay or explicit exceptions during replacement. Establish ownership from the application's writers rather than the shape of the configuration. An overlay preserves undeclared fields; removing a source declaration does not by itself retire its destination state.
 
+Deleting a source file likewise leaves its existing destination in place, and `chezmoi status` no longer reports that unmanaged path. The repository avoids persistent deletion lists and migration markers so source describes the current configuration without accumulating past removals. The trade-off is that existing machines need explicit cleanup; `.chezmoiremove` would automate file deletion but not cleanup of fields in shared configurations.
+
 The JSON and TOML modifiers compare parsed values before serializing, so reordering object keys in their fragments alone leaves the destination unchanged. Fragments embedded in scripts, such as [`codex/requirements.toml`](../.chezmoitemplates/codex/requirements.toml), also affect script trigger hashes; their ordering changes can rerun the consuming script.
 
 Chezmoi source manages portable, durable preferences, including established interaction habits, when they should remain consistent across machines. It leaves matching convenience defaults implicit unless an explicit value enforces a repository boundary or counters observed write-back drift. Generated runtime state, machine-specific paths, and settings synchronized elsewhere remain owned by their existing systems.

.github/README.md

@@ -51,6 +51,10 @@ Editing encrypted files requires a YubiKey and should not be delegated to an age
 
 See chezmoi's [daily operations guide](https://www.chezmoi.io/user-guide/daily-operations/) for other commands.
 
+## Updating existing machines
+
+When updating an existing Mac or merging upstream into a fork, review commits since the version last applied on that machine for retired paths and fields. Check their current contents before removing them, keeping any local changes you still need. Applying the new source [does not clean up all retired configuration](CONCEPTS.md#configuration-ownership), even when `chezmoi status` is empty.
+
 ## Reuse
 
 Fork this repository and adapt it to your environment, or copy only the parts you need. Before applying the full setup, review and adjust `.chezmoi.toml.tmpl`, `Brewfile`, and `.chezmoiscripts/`.

.github/README_CN.md

@@ -51,6 +51,10 @@ chezmoi edit-encrypted <filename>  # 编辑未由 chezmoi 管理的加密文件
 
 其他命令参见 [chezmoi 日常操作指南](https://www.chezmoi.io/user-guide/daily-operations/)。
 
+## 更新已有配置的机器
+
+更新已有的 Mac 或向 fork 合并上游变更时，请检查这台机器上次应用版本之后的提交，确认哪些路径和字段需要清理。删除前先核对当前内容，保留仍然需要的本地修改。应用新版本[不会清理所有已退役的配置](CONCEPTS.md#configuration-ownership)，即使 `chezmoi status` 没有输出。
+
 ## 取用
 
 可以 Fork 本仓库并根据自己的环境调整，也可以只取用需要的部分。若要应用整套配置，请先检查并调整 `.chezmoi.toml.tmpl`、`Brewfile` 和 `.chezmoiscripts/`。

AGENTS.md

@@ -9,7 +9,7 @@ Dotfiles managed by [chezmoi](https://www.chezmoi.io/) from `~/.local/share/chez
 - Before committing, run `chezmoi status --exclude=encrypted <dest-path>` and `chezmoi diff <dest-path>` for each changed non-secret managed target in scope; never run bare `chezmoi status` or `chezmoi diff`, which can generate decrypted target content. Reserve repository-wide status checks for requested drift audits, and report inaccessible targets as gaps in those audits without widening permissions. Read `-` as destination-only and `+` as rendered-target-only. Re-add destination-only drift only when it belongs to the requested change; report unrelated drift without modifying it. When both destination and target changed, show the scoped diff.
 - Use `chezmoi merge <dest-path>` only for an explicitly selected non-secret, non-`modify_` target; a templated target requires manual review to preserve template directives.
 - Fold a follow-up change to the same logical unit into its existing unpushed commit (`git commit --amend` or fixup) instead of appending a commit per request; append-only committing turns one feature into a chain that later needs a history rewrite. Start a new commit only for a separate concern, a pushed base, or another author's commit.
-- When retiring or replacing a managed path, verify the exact non-secret destination, then delete the obsolete source and the existing live destination in the same change. Never add `remove_` entries, compatibility readers, or other migration markers; handle any later residue through an explicit audit.
+- When retiring or replacing a managed path, verify the exact non-secret destination, then delete the obsolete source and the existing live destination in the same change. Never add `remove_` entries, compatibility readers, or other migration markers; handle any later residue through an explicit audit. In retirement commits, name the affected non-secret target paths or fields, explain why they were removed, and note any local content to preserve.
 - For agent skill changes, run `ruby dot_agents/skills/scripts/validate-skills.rb --smoke`. Keep `CLI_SMOKE_COMMANDS` in sync only for skills whose instructions depend on current CLI behavior.
 - Preserve order where it affects behavior, including workflow steps, hook lists, and script prefixes. When choosing a layout for unordered configuration keys, prefer an established upstream order from the schema, examples, or generated output; otherwise use alphabetical order for small or unrelated sets and functional groups when they aid navigation. Do not reorder an existing file merely to match another one.
 - In Markdown source, never hard-wrap prose to a fixed column. Keep each prose paragraph, including the prose portion of a list item or blockquote, on one physical line; when content needs intentional separation, create an explicit Markdown block instead of a soft line break. Preserve separate lines for headings, blank paragraph boundaries, separate list items, table rows, fenced code, and explicit hard breaks ending in two spaces or a backslash.