diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..31a828c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,55 @@
+# Repository instructions
+
+## iOS simulator build and deployment
+
+This Apple Silicon project builds the simulator app for `arm64`. Do not disable
+code signing: the Rust build script consumes Xcode's generated simulator
+entitlement paths. Do not request an `x86_64` simulator build unless the
+`x86_64-apple-ios` Rust target has explicitly been installed.
+
+Use this sequence from the repository root:
+
+```sh
+cd ios
+xcodegen generate
+
+xcodebuild \
+  -project Gotcha.xcodeproj \
+  -scheme Gotcha \
+  -configuration Debug \
+  -sdk iphonesimulator \
+  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
+  ARCHS=arm64 \
+  ONLY_ACTIVE_ARCH=YES \
+  build
+
+gotcha_build_dir="$(
+  xcodebuild \
+    -project Gotcha.xcodeproj \
+    -scheme Gotcha \
+    -configuration Debug \
+    -sdk iphonesimulator \
+    -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
+    -showBuildSettings -json \
+    ARCHS=arm64 \
+    ONLY_ACTIVE_ARCH=YES |
+  plutil -extract 0.buildSettings.TARGET_BUILD_DIR raw -o - -
+)"
+xcrun simctl install booted "$gotcha_build_dir/Gotcha.app"
+xcrun simctl launch booted de.rfc1437.gotcha
+```
+
+Before deploying, check for a booted simulator with
+`xcrun simctl list devices available`. If none is booted, boot an available
+iPhone (currently `xcrun simctl boot "iPhone 17 Pro"`) and open Simulator.
+CoreSimulator access may require running `xcodebuild` and `simctl` outside the
+workspace sandbox.
+
+## Generated build data
+
+Use Xcode's default DerivedData location; do not pass `-derivedDataPath`.
+Cargo's ignored `target/` directory is a disposable build cache. Cargo does not
+bound or garbage-collect stale target artifacts, so check it with
+`du -sh target` and run `cargo clean` when disk space is worth a full rebuild.
+Do not add a custom cache-pruning tool or disable incremental compilation just
+to reduce routine cache usage.
diff --git a/ios/Assets.xcassets/AppIcon.appiconset/AppIcon.png b/ios/Assets.xcassets/AppIcon.appiconset/AppIcon.png
new file mode 100644
index 0000000..c94aa7d
Binary files /dev/null and b/ios/Assets.xcassets/AppIcon.appiconset/AppIcon.png differ
diff --git a/ios/Assets.xcassets/AppIcon.appiconset/Contents.json b/ios/Assets.xcassets/AppIcon.appiconset/Contents.json
new file mode 100644
index 0000000..cefcc87
--- /dev/null
+++ b/ios/Assets.xcassets/AppIcon.appiconset/Contents.json
@@ -0,0 +1,14 @@
+{
+  "images" : [
+    {
+      "filename" : "AppIcon.png",
+      "idiom" : "universal",
+      "platform" : "ios",
+      "size" : "1024x1024"
+    }
+  ],
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
diff --git a/ios/Assets.xcassets/Contents.json b/ios/Assets.xcassets/Contents.json
new file mode 100644
index 0000000..73c0059
--- /dev/null
+++ b/ios/Assets.xcassets/Contents.json
@@ -0,0 +1,6 @@
+{
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}
diff --git a/ios/Gotcha.xcodeproj/project.pbxproj b/ios/Gotcha.xcodeproj/project.pbxproj
index df8d38d..15d6e26 100644
--- a/ios/Gotcha.xcodeproj/project.pbxproj
+++ b/ios/Gotcha.xcodeproj/project.pbxproj
@@ -6,14 +6,20 @@
 	objectVersion = 77;
 	objects = {
 
+/* Begin PBXBuildFile section */
+		E7AC0B140F5CFC5EF226D174 /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = DDAABE6B13ADC6D08D9438AF /* Assets.xcassets */; };
+/* End PBXBuildFile section */
+
 /* Begin PBXFileReference section */
 		5FB3250A93766966A60A685E /* Gotcha.app */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.application; path = Gotcha.app; sourceTree = BUILT_PRODUCTS_DIR; };
+		DDAABE6B13ADC6D08D9438AF /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXGroup section */
 		A8558BC8DD12191B80F52573 = {
 			isa = PBXGroup;
 			children = (
+				DDAABE6B13ADC6D08D9438AF /* Assets.xcassets */,
 				F059299C038F3CAFCE470831 /* Products */,
 			);
 			sourceTree = "<group>";
@@ -35,6 +41,7 @@
 			buildPhases = (
 				409DBF67E9C2743801B8F8A4 /* Sources */,
 				6334AD54CF86DAD2EC201EBC /* Build Rust app */,
+				9EDD4380917C29EE67EE344B /* Resources */,
 			);
 			buildRules = (
 			);
@@ -77,6 +84,17 @@
 		};
 /* End PBXProject section */
 
+/* Begin PBXResourcesBuildPhase section */
+		9EDD4380917C29EE67EE344B /* Resources */ = {
+			isa = PBXResourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				E7AC0B140F5CFC5EF226D174 /* Assets.xcassets in Resources */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXResourcesBuildPhase section */
+
 /* Begin PBXShellScriptBuildPhase section */
 		6334AD54CF86DAD2EC201EBC /* Build Rust app */ = {
 			isa = PBXShellScriptBuildPhase;
diff --git a/ios/project.yml b/ios/project.yml
index 3e2cf3a..8d908d4 100644
--- a/ios/project.yml
+++ b/ios/project.yml
@@ -18,7 +18,8 @@ targets:
         UILaunchScreen: {}
         UISupportedInterfaceOrientations:
           - UIInterfaceOrientationPortrait
-    sources: []
+    sources:
+      - Assets.xcassets
     postCompileScripts:
       - name: Build Rust app
         basedOnDependencyAnalysis: false