diff --git a/mac_app.md b/mac_app.md
new file mode 100644
index 0000000..1d68916
--- /dev/null
+++ b/mac_app.md
@@ -0,0 +1,247 @@
+# Mac App Store / TestFlight ビルドガイド
+
+UE5プロジェクトをMac App Store / TestFlightにアップロードするための手順。
+
+## 必要なもの
+
+### Apple Developer 証明書
+
+| 証明書 | 用途 |
+|--------|------|
+| Apple Distribution | アプリ署名 |
+| 3rd Party Mac Developer Installer | PKG署名 |
+
+確認方法:
+```bash
+security find-identity -v -p codesigning
+```
+
+### Provisioning Profile
+
+1. [Apple Developer](https://developer.apple.com/account/resources/profiles/list) からダウンロード
+2. プロジェクトルートに `embedded.provisionprofile` として配置
+
+```bash
+# UUIDを確認
+security cms -D -i embedded.provisionprofile | grep -A1 UUID
+```
+
+### App Store Connect API Key
+
+1. [App Store Connect](https://appstoreconnect.apple.com/access/integrations/api) で作成
+2. `.p8` ファイルをダウンロード
+3. Issuer ID と Key ID をメモ
+
+## 設定ファイル
+
+### .env
+
+```bash
+# 署名証明書
+IOS_CERTIFICATE_NAME="Apple Distribution: Your Name (TEAMID)"
+DEVELOPMENT_TEAM="TEAMID"
+
+# App Store Connect API
+ASC_ISSUER_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+ASC_KEY_ID="XXXXXXXXXX"
+ASC_KEY_PATH="/path/to/XXXXXXXXXX.p8"
+```
+
+### Config/DefaultEngine.ini
+
+```ini
+[/Script/MacTargetPlatform.XcodeProjectSettings]
+CodeSigningTeam=TEAMID
+bUseModernXcode=true
+bUseAutomaticCodeSigning=true
+BundleIdentifier=com.example.app
+CodeSigningPrefix=com.example
+bUseAppStoreConnect=True
+AppStoreConnectIssuerID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+AppStoreConnectKeyID=XXXXXXXXXX
+AppStoreConnectKeyPath=(FilePath="path/to/key.p8")
+```
+
+## ビルドワークフロー
+
+```bash
+# 1. Macビルド
+./bin/build.zsh mac
+
+# 2. PKG作成（アイコン差し替え + 署名）
+./bin/build.zsh pkg
+
+# 3. アイコン検証（オプション）
+./bin/verify-icon.zsh
+
+# 4. TestFlightにアップロード
+./bin/build.zsh upload-mac
+```
+
+## コマンド詳細
+
+### mac - UE5ビルド
+
+```bash
+./bin/build.zsh mac
+```
+
+実行内容:
+- BuildCookRun でMac向けビルド
+- `-distribution` フラグでApp Store配布用
+- `-iterate` で増分クック（高速化）
+- 出力: `Mac/*.xcarchive`
+
+### pkg - PKG作成
+
+```bash
+./bin/build.zsh pkg
+```
+
+実行内容:
+1. 最新の xcarchive を検出
+2. カスタムアイコンに差し替え（AppIcon.icns + Assets.car再ビルド）
+3. EpicWebHelper に sandbox entitlements で署名
+4. メインアプリを再署名
+5. `xcodebuild -exportArchive` でPKG生成
+6. 出力: `build/Airse.pkg`
+
+### upload-mac - アップロード
+
+```bash
+./bin/build.zsh upload-mac
+```
+
+実行内容:
+- `xcrun altool` でApp Store Connectにアップロード
+- API Key認証（推奨）またはユーザー名/パスワード認証
+
+## 必須ファイル
+
+```
+Project/
+├── .env                              # 環境変数
+├── embedded.provisionprofile         # Mac用プロビジョニングプロファイル
+├── XXXXXXXXXX.p8                     # App Store Connect API Key
+├── Build/
+│   └── Mac/
+│       └── Resources/
+│           ├── AppIcon.icns          # カスタムアイコン
+│           └── Sandbox.Server.entitlements  # サンドボックス設定
+└── Config/
+    └── DefaultEngine.ini             # プロジェクト設定
+```
+
+## Sandbox Entitlements
+
+Mac App Storeでは、すべての実行ファイルにサンドボックス権限が必要。
+
+### Sandbox.Server.entitlements
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.app-sandbox</key>
+    <true/>
+    <key>com.apple.security.inherit</key>
+    <true/>
+</dict>
+</plist>
+```
+
+### EpicWebHelper 署名
+
+UE5のEpicWebHelper（CEFベースのWebブラウザヘルパー）は別途署名が必要:
+
+```bash
+codesign -f -s "Apple Distribution: ..." \
+    --entitlements Sandbox.Server.entitlements \
+    "Airse.app/Contents/UE/Engine/Binaries/Mac/EpicWebHelper"
+```
+
+これは `create_pkg()` で自動実行される。
+
+## トラブルシューティング
+
+### No profiles for 'bundle.id'
+
+**原因**: Provisioning profileがインストールされていない
+
+**解決**:
+```bash
+# UUIDを取得
+PROFILE_UUID=$(security cms -D -i embedded.provisionprofile | grep -A1 UUID | tail -1 | sed 's/.*<string>\(.*\)<\/string>.*/\1/')
+
+# 正しい場所にコピー
+cp embedded.provisionprofile ~/Library/MobileDevice/Provisioning\ Profiles/${PROFILE_UUID}.provisionprofile
+```
+
+### Certificate mismatch
+
+**原因**: "3rd Party Mac Developer Installer" 証明書がない
+
+**解決**: Keychain Accessで証明書を確認、なければApple Developerから作成
+
+### App sandbox not enabled on EpicWebHelper
+
+**原因**: EpicWebHelperにサンドボックス権限がない
+
+**解決**: `create_pkg()` で自動署名される。手動で署名する場合:
+```bash
+codesign -f -s "$CERT" --entitlements Sandbox.Server.entitlements EpicWebHelper
+codesign -f -s "$CERT" --entitlements Sandbox.Server.entitlements Airse.app
+```
+
+### Missing asset catalog
+
+**原因**: Assets.car が削除された
+
+**解決**: Assets.carを削除せず、`actool` で再ビルドする（現在のスクリプトで対応済み）
+
+### アイコンが変わらない
+
+**原因**: Assets.car にデフォルトアイコンが含まれている
+
+**解決**:
+1. キャッシュクリア: `rm -rf Saved/StagedBuilds Binaries/Mac`
+2. `./bin/build.zsh pkg` を再実行
+3. `./bin/verify-icon.zsh` で確認
+
+## ビルドログ
+
+ログファイルの場所:
+- UE5ビルドログ: `build_mac.log`
+- Xcodeログ: `~/Library/Logs/Unreal Engine/LocalBuildLogs/`
+
+## バージョン管理
+
+TestFlightにアップロードするたびにビルド番号を上げる必要がある。
+
+`Config/DefaultGame.ini`:
+```ini
+[/Script/EngineSettings.GeneralProjectSettings]
+ProjectVersion=1.0.0
+```
+
+または UE Editor の Project Settings > Project > Description で設定。
+
+## 参考コマンド
+
+```bash
+# 証明書一覧
+security find-identity -v -p codesigning
+
+# Provisioning profile の内容確認
+security cms -D -i embedded.provisionprofile
+
+# PKG の内容確認
+pkgutil --expand Airse.pkg /tmp/pkg_contents
+
+# アプリの署名確認
+codesign -dv --verbose=4 Airse.app
+
+# Entitlements 確認
+codesign -d --entitlements - Airse.app
+```
\ No newline at end of file