Epic: Add iOS Project Support to iloom

docs/iloom-commands.md

@@ -701,7 +701,7 @@ il spin --complexity=complex --yolo
 
 ### il open
 
-Open loom in browser (web projects) or run configured CLI tool (CLI projects).
+Open loom in browser (web projects), Xcode (iOS projects), or run configured CLI tool (CLI projects).
 
 **Alias:** `run`
 
@@ -717,6 +717,11 @@ il open [identifier]
 
 **Behavior by Project Type:**
 
+**iOS Projects (requires macOS):**
+- React Native (`web` + `ios` capabilities): Opens the `ios/` subdirectory in Xcode
+- Native iOS (`ios` capability only): Opens the project root in Xcode (searches for `.xcworkspace` or `.xcodeproj`)
+- Non-macOS platforms produce a clear error message
+
 **Web Projects:**
 - Opens development server in default browser
 - Uses the loom's unique port (e.g., http://localhost:3025)
@@ -810,7 +815,19 @@ il dev-server [identifier] [options]
 - If omitted and inside a loom, starts dev server for current loom
 - If omitted outside a loom, prompts for selection
 
-**Behavior:**
+**Behavior by Project Type:**
+
+**React Native iOS (`web` + `ios` capabilities):**
+- Starts the Metro bundler as a foreground dev server
+- Metro is cross-platform and works on macOS, Linux, and Windows
+- The iOS Simulator must be launched separately via `il run` or Xcode
+
+**Native iOS (`ios` capability only, requires macOS):**
+- Not applicable — native iOS does not use a dev server
+- Displays a guidance message directing you to `il run`
+- Non-macOS platforms produce a clear error message
+
+**Web Projects:**
 
 1. Resolves the target loom
 2. Loads environment variables from `.env` files
@@ -930,6 +947,47 @@ Containers are named `iloom-dev-<identifier>` where the identifier is derived fr
 
 ---
 
+### iOS Project Configuration
+
+For iOS projects, declare the `"ios"` capability in `.iloom/package.iloom.json` and configure Xcode build settings in `.iloom/settings.json`:
+
+**`.iloom/package.iloom.json`:**
+```json
+{
+  "name": "MyiOSApp",
+  "capabilities": ["ios"]
+}
+```
+
+**`.iloom/settings.json`:**
+```json
+{
+  "capabilities": {
+    "ios": {
+      "simulatorDevice": "iPhone 16",
+      "scheme": "MyApp",
+      "bundleId": "com.example.myapp",
+      "configuration": "Debug",
+      "deployTarget": "simulator",
+      "developmentTeam": "TEAM123456"
+    }
+  }
+}
+```
+
+**iOS Configuration Fields:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `simulatorDevice` | `string` | `"iPhone 16"` | Target simulator device name as shown in Xcode (e.g., `"iPhone 16"`, `"iPad Pro 13-inch"`). |
+| `scheme` | `string` | — | Xcode scheme to build and run. Corresponds to the scheme name in your `.xcodeproj` or `.xcworkspace`. |
+| `bundleId` | `string` | — | App bundle identifier (e.g., `"com.example.myapp"`). Used for device installation and code signing. |
+| `configuration` | `"Debug"` \| `"Release"` | `"Debug"` | Xcode build configuration. |
+| `deployTarget` | `"simulator"` \| `"device"` | `"simulator"` | Whether to deploy to a simulator or a physical device connected via USB. |
+| `developmentTeam` | `string` | — | Apple Developer Team ID for code signing. Required when `deployTarget` is `"device"`. Find your Team ID in Xcode under Signing & Capabilities. |
+
+---
+
 ### il build
 
 Run the build script for a workspace.

docs/multi-language-projects.md

@@ -77,6 +77,9 @@ An array defining what type of project this is:
 - `"web"` - Web application with a development server
   - Enables automatic port assignment (3000 + issue number)
   - Prevents port conflicts when running multiple dev servers
+- `"ios"` - iOS application built with Xcode
+  - Enables iOS-specific build configuration (simulator device, scheme, bundle ID, etc.)
+  - Activates Xcode build strategy for dev server commands
 
 You can specify both capabilities if your project is both a CLI and web app.
 
@@ -347,6 +350,54 @@ Some projects are both CLI and web applications:
 - Compiles to a binary (`cli`)
 - Runs a web server (`web`)
 
+### iOS Capability
+
+Declare `"ios"` capability when your project is an iOS application built with Xcode:
+
+```json
+{
+  "capabilities": ["ios"]
+}
+```
+
+This tells iloom that:
+- Your project uses Xcode for building and running
+- iOS-specific settings (simulator device, scheme, bundle ID, etc.) apply
+- The dev server strategy will use `xcodebuild` or `simctl`
+
+**Use cases:**
+- Native iOS apps
+- Swift Package Manager libraries with iOS targets
+- iOS app extensions
+
+#### iOS-Specific Settings
+
+Configure iOS build behavior in `.iloom/settings.json` under the `capabilities.ios` key:
+
+```json
+{
+  "capabilities": {
+    "ios": {
+      "simulatorDevice": "iPhone 16",
+      "scheme": "MyApp",
+      "bundleId": "com.example.myapp",
+      "configuration": "Debug",
+      "deployTarget": "simulator",
+      "developmentTeam": "TEAM123456"
+    }
+  }
+}
+```
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `simulatorDevice` | string | `"iPhone 16"` | Target simulator device name |
+| `scheme` | string | — | Xcode scheme to build |
+| `bundleId` | string | — | App bundle identifier |
+| `configuration` | `"Debug"` \| `"Release"` | `"Debug"` | Build configuration |
+| `deployTarget` | `"simulator"` \| `"device"` | `"simulator"` | Whether to deploy to simulator or physical device |
+| `developmentTeam` | string | — | Apple Developer Team ID (required for physical device deployment) |
+
 ## Secret Storage Limitations
 
 iloom's environment variable isolation works by managing `.env` files. Features like database branching and loom-specific environment variables require your framework to read configuration from `.env` files.