From c1f01b4493124f585e70fdd9cb0ac34d63f5bb68 Mon Sep 17 00:00:00 2001
From: argszero <argszero@gmail.com>
Date: Tue, 11 Aug 2026 19:01:52 +0800
Subject: [PATCH] emrg: document gen-assets.sh for local packaging (post-#688
 host symmetry)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#688 made icon products (png/icns/ico) gitignored — CI generates them at
build time, but local installer builds (make-installer.sh / build-runtime.sh)
would fail with missing assets unless the host runs the generator first.

- DEVELOPMENT.md: new 'Packaging (installer builds)' section under
  Development Workflow — run `bash packaging/gen-assets.sh` first
  (idempotent; renderer priority rsvg-convert → Chrome headless → sips;
  .icns needs macOS iconutil, skipped elsewhere)
- Agent.md: 'Packaging' section under Test Commands with the same note
- mirrors the #467/#468 host-symmetry principle: CI validation + documented
  host-side self-check
---
 Agent.md       |  4 ++++
 DEVELOPMENT.md | 10 ++++++++++
 2 files changed, 14 insertions(+)

diff --git a/Agent.md b/Agent.md
index c58c6428..031ffd90 100644
--- a/Agent.md
+++ b/Agent.md
@@ -117,6 +117,10 @@ GUI: `cd emrg/gui && npm test` (212: 43 daemon_client + 19 conn-manager + 22 app
 CI: `uv run pytest` + GUI tests + **actionlint workflow lint** (`rhysd/actionlint@v1.7.12` gate, #444 — workflow 解析错误在 PR CI 即失败，如 `if:` secrets 上下文)
 Re-trigger: `scripts/re-trigger-ci.sh [branch]` (workflow_dispatch, #527 — 替代空 commit 重触发：Actions outage 会整段丢弃 push 事件，dispatch 走 API 路径不受影响)
 
+## Packaging
+
+Generated icon products (`packaging/assets/icon.png/icon-512/icon-256/icon.icns/icon.ico`) are **gitignored** — only `icon.svg` design source is committed (#688); CI generates them in Build Release. Local installer builds (`make-installer.sh` / `build-runtime.sh`) require running `bash packaging/gen-assets.sh` first (idempotent; renderer priority rsvg-convert → Chrome headless → sips; `.icns` needs macOS `iconutil`, skipped elsewhere).
+
 ## Configuration
 
 `~/.emrg/config.toml`:
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 74bef5a7..1aa2493f 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -162,6 +162,16 @@ npm start            # launch GUI (auto-starts daemon)
 npm test             # run Node tests (178: 43 daemon_client + 19 conn-manager + 22 app-commands + 59 renderer smoke + 15 i18n + 7 integration + 3 commands + 3 build-config + 7 gui-state; integration runs in CI, local: npm run test:integration)
 ```
 
+### Packaging (installer builds)
+
+Generated icon products (`icon.png`/`icon-512`/`icon-256`/`icon.icns`/`icon.ico`) are **not committed** — the repo keeps only the SVG design source (`packaging/assets/icon.svg`); CI generates them at build time (#688). When building installers locally (`packaging/make-installer.sh` / `build-runtime.sh`), run the generator first:
+
+```bash
+bash packaging/gen-assets.sh   # icon.svg → png/icns/ico (idempotent)
+```
+
+Renderer priority: `rsvg-convert` → Chrome/Chromium headless → `sips` (last resort, glow may be lost). Requires macOS `iconutil` for `.icns` (skipped with a notice on Linux/Windows).
+
 CI runs tests and checks for conflict markers automatically via GitHub Actions (`.github/workflows/test.yml`).
 
 > **Self-evolution from source**: the evolution workspace expects the repo at `~/.emrg/evolution/emrg`. Packaged installs self-heal (clone on demand + auto-bootstrap projects/tasks); source installs should clone there explicitly if you want the evolution daemon to work on this repo.