docs annotate x86 config profiles

.github/workflows/X-x86_64_X.yml

@@ -252,7 +252,14 @@ jobs:
         cd openwrt
         ./scripts/feeds install -a
         make defconfig
-        make download -j${DOWNLOAD_JOBS}
+        mkdir -p dl
+        if ! make download -j${DOWNLOAD_JOBS}
+        then
+            echo "Parallel package download failed; retrying serially with verbose output."
+            find dl -type f -size -1024c -print -delete
+            make download -j1 V=s
+        fi
+        find dl -type f -size -1024c -print -delete
 
     - name: Build OpenWrt
       run: |

.github/workflows/X-x86_64_Y.yml

@@ -249,7 +249,14 @@ jobs:
         cd openwrt
         ./scripts/feeds install -a
         make defconfig
-        make download -j${DOWNLOAD_JOBS}
+        mkdir -p dl
+        if ! make download -j${DOWNLOAD_JOBS}
+        then
+            echo "Parallel package download failed; retrying serially with verbose output."
+            find dl -type f -size -1024c -print -delete
+            make download -j1 V=s
+        fi
+        find dl -type f -size -1024c -print -delete
 
     - name: Build OpenWrt
       run: |

.github/workflows/X-x86_64_Z.yml

@@ -247,7 +247,14 @@ jobs:
         cd openwrt
         ./scripts/feeds install -a
         make defconfig
-        make download -j${DOWNLOAD_JOBS}
+        mkdir -p dl
+        if ! make download -j${DOWNLOAD_JOBS}
+        then
+            echo "Parallel package download failed; retrying serially with verbose output."
+            find dl -type f -size -1024c -print -delete
+            make download -j1 V=s
+        fi
+        find dl -type f -size -1024c -print -delete
 
     - name: Build OpenWrt
       run: |

AI_CHANGELOG_GRUB2_DOWNLOAD_RETRY.md

@@ -0,0 +1,20 @@
+# AI Modification Log: GRUB2 Download Retry
+
+Date: 2026-06-29
+
+## Summary
+
+- Updated the X/Y/Z x86_64 workflows so `make download` retries serially with `V=s` after a parallel download failure.
+- Added cleanup for tiny incomplete files in `dl/` before the retry and after download completion.
+- Updated `CODEX_HANDOFF.md` to record that the config-comment task was interrupted by this build failure fix.
+
+## Reason
+
+The reported failure stopped at `package/boot/grub2` with build variant `efi` during `make package/download`. Retrying `make download` serially follows the OpenWrt error guidance and avoids common parallel download or cached partial-file failures while preserving detailed logs if the upstream package still fails.
+
+## Verification
+
+- Inspected the workflow diff and confirmed only the X/Y/Z pre-download blocks changed.
+- Parsed the edited X/Y/Z workflow files with PyYAML.
+- Checked workflow line endings and confirmed X stayed LF while Y/Z stayed CRLF.
+- Ran whitespace validation with `git -c core.whitespace=blank-at-eol,blank-at-eof,space-before-tab,cr-at-eol diff --check` because Y/Z intentionally still use CRLF.

AI_CHANGELOG_TASK_BACKLOG_REFRESH.md

@@ -0,0 +1,13 @@
+# AI Modification Log: Task Backlog Refresh
+
+Date: 2026-06-29
+
+## Summary
+
+- Updated `CODEX_HANDOFF.md` to reflect that the active working branch is `ai` tracking `origin/ai`.
+- Recorded the current requested follow-up task before editing the X/Y/Z x86_64 config files.
+- Added backlog item #35 to track config intent comments and config-specific optimization todos.
+
+## Verification
+
+- Confirmed the worktree was clean on `ai...origin/ai` before this documentation update.

AI_CHANGELOG_X86_CONFIG_COMMENTS.md

@@ -0,0 +1,21 @@
+# AI Modification Log: x86_64 Config Comments
+
+Date: 2026-06-29
+
+## Summary
+
+- Added purpose and maintenance comment headers to `Configs/x86_64-X`, `Configs/x86_64-Y`, and `Configs/x86_64-Z`.
+- Added `NOTES_X86_CONFIG_OPTIMIZATION.md` with config-specific optimization todos.
+- Updated the handoff and backlog notes to mark item #35 as completed.
+
+## Behavior Impact
+
+- No `CONFIG_*` selections were added, removed, or changed.
+- The config comment update is documentation-only.
+
+## Verification
+
+- Inspected the config diff and confirmed the three config files only gained comment headers.
+- Compared `CONFIG_*` lines against `HEAD` and confirmed no config selections changed.
+- Checked line endings and confirmed X stayed LF, Y stayed LF without EOF newline, and Z stayed CRLF without EOF newline.
+- Ran CRLF-aware whitespace validation before commit.

CODEX_HANDOFF.md

@@ -9,9 +9,11 @@ This file is the stable restart point for future Codex sessions in this reposito
 ## Current State
 
 - Repository: `X-OpenWrt-New`
-- Branch: `master`
+- Branch: `ai`
+- Remote tracking branch: `origin/ai`
 - Latest completed task batch: continued the GitHub Actions X/Y/Z optimization backlog through multiple high-priority and low-risk maintainability/script items.
-- Latest task commit at handoff update time: `5f3650c validate workflow dispatch inputs`
+- Latest task context: package download retry fix completed; #35 config documentation task completed in the current working series.
+- Current requested task: #35 completed by documenting X/Y/Z x86_64 config intent and adding `NOTES_X86_CONFIG_OPTIMIZATION.md`.
 - Backlog file: `NOTES_GHA_XYZ_OPTIMIZATION.md`
 
 ## Completed Backlog Items
@@ -39,11 +41,17 @@ Completed in this task series:
 - #27: Fixed `Get_Release_Info` command substitution bug.
 - #28: Made diagnostic external IP lookup non-blocking.
 - #30: Improved release tag comparison.
+- #35: Added x86_64 X/Y/Z config intent comments and a dedicated config optimization todo list.
+- Unplanned: Added serial verbose retry for X/Y/Z package downloads after a parallel `make download` failure.
 
 Each code fix has a corresponding `AI_CHANGELOG_*.md` file.
 
 ## Remaining Work
 
+Immediate continuation:
+
+- Config-specific cleanup follow-ups now live in `NOTES_X86_CONFIG_OPTIMIZATION.md`. Treat those todos as the source of truth for x86_64 config cleanup.
+
 The next unresolved backlog items need broader design or more careful behavior decisions:
 
 - #13: Consolidate X/Y/Z workflows. This is a large refactor; prefer a reusable workflow or matrix workflow with a separate review pass.

Configs/x86_64-X

@@ -1,3 +1,16 @@
+# X-OpenWrt x86_64-X compile config notes
+# Purpose: X profile for generic x86_64 firmware. It includes SmartDNS,
+# Docker, WiFi firmware/drivers, IPv6, common storage/network modules,
+# and a broader LuCI package set.
+# Maintenance:
+# - Keep this file limited to OpenWrt .config selections; CI-only options
+#   are appended by the workflow to openwrt/.config.
+# - Keep shared target/image/IPv6/base package choices aligned with Y/Z
+#   unless a profile intentionally differs.
+# - Use OpenWrt scripts/diffconfig.sh after a successful build before
+#   shrinking or reorganizing this profile.
+# - See NOTES_X86_CONFIG_OPTIMIZATION.md for follow-up optimization todos.
+#
 # My Changes
 # 挂载WebDav
 CONFIG_PACKAGE_davfs2=y

Configs/x86_64-Y

@@ -1,3 +1,16 @@
+# X-OpenWrt x86_64-Y compile config notes
+# Purpose: Y profile for generic x86_64 firmware. It keeps SmartDNS,
+# Passwall, AdGuardHome, Docker/Diskman, IPv6, common network services,
+# and the standard x86 image formats.
+# Maintenance:
+# - Keep this file limited to OpenWrt .config selections; CI-only options
+#   are appended by the workflow to openwrt/.config.
+# - Keep shared target/image/IPv6/base package choices aligned with X/Z
+#   unless a profile intentionally differs.
+# - Use OpenWrt scripts/diffconfig.sh after a successful build before
+#   shrinking or reorganizing this profile.
+# - See NOTES_X86_CONFIG_OPTIMIZATION.md for follow-up optimization todos.
+#
 # 挂载WebDav
 CONFIG_PACKAGE_davfs2=y
 # Smart DNS

Configs/x86_64-Z

@@ -1,3 +1,16 @@
+# X-OpenWrt x86_64-Z compile config notes
+# Purpose: Z profile for generic x86_64 firmware. It is the compact
+# Passwall/AdGuardHome/Diskman/Netdata profile and also enables Image
+# Builder options.
+# Maintenance:
+# - Keep this file limited to OpenWrt .config selections; CI-only options
+#   are appended by the workflow to openwrt/.config.
+# - Keep shared target/image/IPv6/base package choices aligned with X/Y
+#   unless a profile intentionally differs.
+# - Decide whether CONFIG_IB/CONFIG_IB_STANDALONE outputs should be
+#   uploaded, ignored, or disabled.
+# - See NOTES_X86_CONFIG_OPTIMIZATION.md for follow-up optimization todos.
+#
 # 挂载WebDav
 CONFIG_PACKAGE_davfs2=y
 # Smart DNS

NOTES_GHA_XYZ_OPTIMIZATION.md

@@ -30,6 +30,16 @@ Related directories:
 - `Scripts`: shared build/env/update helper scripts.
 - `CustomFiles`: patches, dependency files and Kconfig fragments injected by scripts.
 
+## Current Progress
+
+Updated: 2026-06-29
+
+- Active work branch: `ai`, tracking `origin/ai`.
+- Completed backlog items in the current AI task series: #1-#12, #14-#16, #20-#22, #27, #28, #30, and #35.
+- Config-specific cleanup follow-ups now live in `NOTES_X86_CONFIG_OPTIMIZATION.md`.
+- Unplanned build fix added a serial verbose retry path for `make download` after a reported `package/boot/grub2` EFI package download failure.
+- Larger unresolved items remain below; prefer one scoped commit per backlog item unless batching is requested.
+
 ## Optimization Backlog
 
 ### High Priority
@@ -236,6 +246,12 @@ Related directories:
     - Problem: commented `KERNEL_PATCHVER` lines do not affect OpenWrt config and can mislead later edits.
     - Suggested fix: remove stale comments or move kernel selection into the correct build mechanism.
 
+35. Document X/Y/Z config intent and optimization todos.
+    - Files: `Configs/x86_64-X`, `Configs/x86_64-Y`, `Configs/x86_64-Z`, `NOTES_X86_CONFIG_OPTIMIZATION.md`
+    - Problem: the three x86_64 profiles do not clearly state their intended role, shared maintenance rules, or follow-up cleanup path.
+    - Suggested fix: add safe comment headers to each config and maintain a dedicated todo list for config-specific optimization work.
+    - Status: completed; follow-up cleanup todos are tracked in `NOTES_X86_CONFIG_OPTIMIZATION.md`.
+
 ## Suggested First Fix Batch
 
 1. Fix Z upload path typo and Z mosdns build-order issue.

NOTES_X86_CONFIG_OPTIMIZATION.md

@@ -0,0 +1,37 @@
+# x86_64 X/Y/Z Config Optimization Todo
+
+Updated: 2026-06-29
+
+## Scope
+
+- `Configs/x86_64-X`
+- `Configs/x86_64-Y`
+- `Configs/x86_64-Z`
+- `.github/workflows/X-x86_64_X.yml`
+- `.github/workflows/X-x86_64_Y.yml`
+- `.github/workflows/X-x86_64_Z.yml`
+
+## Current Profile Notes
+
+- X: broad x86_64 profile with SmartDNS, Docker, WiFi firmware/drivers, IPv6, storage/network modules, and a larger LuCI package set.
+- Y: service-heavy x86_64 profile with SmartDNS, Passwall, AdGuardHome, Docker/Diskman, IPv6, and standard x86 image outputs.
+- Z: compact x86_64 profile with Passwall, AdGuardHome, Diskman/Netdata, standard x86 image outputs, and Image Builder enabled.
+
+## Todo
+
+- [ ] Extract shared target/image basics into one common x86_64 fragment, then keep X/Y/Z as small profile fragments.
+- [ ] After a successful build, run OpenWrt `scripts/diffconfig.sh` for X/Y/Z and remove redundant selected dependencies.
+- [ ] Decide the Z Image Builder policy: upload generated Image Builder artifacts, intentionally ignore them, or disable `CONFIG_IB`/`CONFIG_IB_STANDALONE`.
+- [ ] Standardize line endings and final newlines for `Configs/x86_64-Y` and `Configs/x86_64-Z` in a dedicated formatting-only commit.
+- [ ] Build a profile matrix that records intentional package deltas between X, Y, and Z.
+- [ ] Remove or relocate stale `KERNEL_PATCHVER` comments because they do not affect OpenWrt `.config` behavior.
+- [ ] Confirm each profile's `CONFIG_GRUB_IMAGES`, `CONFIG_VMDK_IMAGES`, `CONFIG_VDI_IMAGES`, `CONFIG_VHDX_IMAGES`, and upload globs still match the intended release artifacts.
+- [ ] Keep `CONFIG_DEVEL`, `CONFIG_CCACHE`, and other CI-only build toggles out of tracked config files.
+- [ ] If config fragments are introduced, add a small generation/check script so committed full configs can be reproduced.
+- [ ] Re-test X/Y/Z after cleanup with `make defconfig` and compare generated `.config` changes before committing behavior changes.
+
+## Do Not Mix
+
+- Do not normalize CRLF/LF while changing config semantics.
+- Do not remove dependency-selected `CONFIG_PACKAGE_*` lines until a successful `diffconfig.sh` pass proves they are redundant.
+- Do not change package selections in the same commit as documentation-only comment updates.