docs: add iOS simulator build and app icon troubleshooting guide

- Document step-by-step process for building and running iOS app in simulator
- Explain common AppIcon.appiconset errors and their causes
- Provide instructions for automatic and manual icon generation
- Include troubleshooting checklist and directory structure examples
- Follows markdownlint and project documentation standards

docs/ios-simulator-build-and-icons.md

@@ -0,0 +1,164 @@
+# iOS Simulator Build and App Icon Troubleshooting
+
+**Author**: Matthew Raymer  
+**Date**: 2025-07-12  
+**Status**: 🎯 **ACTIVE** - In Use
+
+## Overview
+
+This guide documents how to build and run the TimeSafari iOS app in the
+simulator, and how to resolve common issues with iOS app icons and
+`AppIcon.appiconset` errors.
+
+---
+
+## Building and Running the iOS App in Simulator
+
+### 1. Build the App
+
+Use the npm script to build for development (debug/simulator):
+
+```bash
+npm run build:ios:dev
+```
+
+This prepares the iOS project for simulator deployment.
+
+### 2. Run in Simulator
+
+Use Capacitor to launch the app in the iOS Simulator:
+
+```bash
+npx cap run ios
+```
+
+This will:
+- Sync web assets
+- Build the native iOS app
+- Launch the iOS Simulator
+- Install and run the app
+
+### 3. Open in Xcode (Optional)
+
+To open the project in Xcode for manual simulator/device control:
+
+```bash
+npm run build:ios:dev -- --studio
+```
+
+Or:
+
+```bash
+npx cap open ios
+```
+
+---
+
+## Common App Icon and AppIcon.appiconset Errors
+
+### Typical Error Message
+
+```
+error: None of the input catalogs contained a matching stickers icon set or app
+icon set named "AppIcon".
+```
+
+### Why This Happens
+
+- The iOS build expects an `AppIcon.appiconset` in
+  `ios/App/App/Assets.xcassets/`.
+- If missing or incomplete, the build fails.
+- The icon generator may also fail if the source icon is missing or invalid.
+
+### Typical Causes
+
+- No `AppIcon.appiconset` directory
+- No or invalid `Contents.json` in the icon set
+- Missing or corrupt `icon.png` in `assets/`
+- Generator tool errors (permissions, path, or file type)
+
+---
+
+## Step-by-Step: Generating iOS App Icons
+
+### 1. Automatic Generation (Preferred)
+
+- Place a valid PNG icon (at least 1024x1024) at `assets/icon.png`.
+- Run:
+
+```bash
+npx capacitor-assets generate --ios
+```
+
+- This should create `ios/App/App/Assets.xcassets/AppIcon.appiconset/` with all
+  required icon sizes and a `Contents.json`.
+
+#### Troubleshooting Automatic Generation
+
+- If you see errors about missing directories, create them manually:
+
+```bash
+mkdir -p ios/App/App/Assets.xcassets/AppIcon.appiconset
+```
+
+- If you see errors about file type, ensure `icon.png` is a real PNG (not SVG).
+- If the generator fails with a TypeError, check for missing or corrupt files.
+
+### 2. Manual Generation (Fallback)
+
+- Use an online tool like [appicon.co](https://appicon.co/) to generate iOS
+  icons from your `icon.png`.
+- Download and extract the zip.
+- Copy the contents into:
+
+```
+ios/App/App/Assets.xcassets/AppIcon.appiconset/
+```
+
+- Ensure the `Contents.json` is present and valid.
+
+---
+
+## Directory Structure
+
+```
+ios/App/App/Assets.xcassets/
+  └── AppIcon.appiconset/
+      ├── Contents.json
+      ├── AppIcon-20x20@2x.png
+      ├── AppIcon-20x20@3x.png
+      ├── ...
+      └── AppIcon-1024x1024@1x.png
+```
+
+---
+
+## Troubleshooting Checklist
+
+- [ ] Is `assets/icon.png` present and a valid PNG?
+- [ ] Does `AppIcon.appiconset` exist in `Assets.xcassets`?
+- [ ] Is `Contents.json` present and correct?
+- [ ] Are all required icon PNGs present?
+- [ ] If using the generator, did it complete without errors?
+- [ ] If manual, did you copy all files from the zip?
+
+---
+
+## iOS Build Troubleshooting
+
+- If the build fails with icon errors, fix the icon set and rebuild.
+- If the simulator does not launch, try running:
+
+```bash
+npx cap open ios
+```
+
+and launch from Xcode.
+
+- For other build errors, check the logs for missing files or permissions.
+
+---
+
+**Status**: In Use  
+**Last Updated**: 2025-07-12  
+**Maintainer**: Matthew Raymer