cmux 的 Ghostty 子模組與 GhosttyKit 工作流程規範。當修改 ghostty 子模組、重新建置 GhosttyKit.xcframework、更新父專案子模組指標，或是記錄 Fork 衝突筆記時使用。
cmux Ghostty
GhosttyKit 建置
請務必使用 Release 最佳化設定來重新建置 xcframework：
cd ghostty && zig build -Demit-xcframework=true -Dxcframework-target=universal -Doptimize=ReleaseFast
子模組工作流程
Ghostty 的修改需提交至 ghostty 子模組，並推送至 manaflow-ai/ghostty 的 Fork 儲存庫。請保持 docs/ghostty-fork.md 為最新狀態，以包含 Fork 變更與衝突記錄。
執行前請務必先執行 git remote -v，並推送到代表 manaflow-ai/ghostty 的遠端（remote）。.gitmodules 已將子模組 URL 設定為該 Fork，因此在一般 checkout 下通常為 origin；在較舊的環境中，上游（upstream）可能被設為 origin，而 Fork 則被新增為 manaflow。請根據實際狀況替換下方命令中的名稱。
cd ghostty
git remote -v # 找到 manaflow-ai/ghostty 的遠端（通常是 origin）
git checkout -b <branch>
git add <files>
git commit -m "..."
git push origin <branch>
若要同步上游 ghostty-org/ghostty 的變更，由於預設的 checkout 不會包含上游遠端，請先手動新增：
cd ghostty
git remote add upstream https://github.com/ghostty-org/ghostty.git # 執行一次即可
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
接著在父專案中記錄新的 SHA：
cd ..
git add ghostty
git commit -m "Update ghostty submodule"
子模組安全規範
針對任何子模組（ghostty、vendor/bonsplit、homebrew-cmux），在父專案中提交更新後的指標之前，必須先將子模組的 commit 推送到其遠端分支。切勿在游離 HEAD（detached HEAD）或臨時分支上進行 commit：否則父專案會指向一個無法從任何遠端分支存取的 SHA，導致日後的 checkout 或 CI 工作流無法順利取得（fetch）。
請使用剛才推送的遠端，確認該 commit 是否可從指標預期追蹤的分支存取：
cd ghostty && git fetch origin main && git merge-base --is-ancestor HEAD origin/main
詳細參考資料
- references/submodule-safety.md：按順序執行的安全流程與 Fork 文件規範要求。
