diff --git a/INSTRUCTIONS.md b/INSTRUCTIONS.md
new file mode 100644
index 0000000..3979f8f
--- /dev/null
+++ b/INSTRUCTIONS.md
@@ -0,0 +1,125 @@
+# Converting a Web App to iOS / iPadOS / macOS
+
+Step-by-step instructions for using the XCode-Claude-Workflow to convert any web-based project (React, HTML5, Vue, vanilla JS, etc.) into a native SwiftUI app.
+
+## Prerequisites
+
+- **Xcode 16.3+** installed
+- **xcodegen** installed (`brew install xcodegen`)
+- **Claude Code** running in your terminal or IDE
+- A **Forgejo/GitHub account** for the new repo
+- The **source project** folder on your local machine
+
+## Steps
+
+### 1. Create a new repo for the app
+
+On your Forgejo (or GitHub) instance, create an empty repo. Use a descriptive name:
+
+```
+MyApp-iOS-iPadOS-MacOS
+```
+
+Clone it locally:
+
+```bash
+cd ~/Documents/FORGEJO
+git clone https://git.istratai.cloud/aj/MyApp-iOS-iPadOS-MacOS.git
+cd MyApp-iOS-iPadOS-MacOS
+```
+
+### 2. Copy the workflow prompt
+
+```bash
+cp ~/Documents/FORGEJO/XCode-Claude-Workflow/PROMPT.md .
+```
+
+### 3. Open Claude Code in the new repo
+
+```bash
+claude
+```
+
+Or open the folder in VS Code / Cursor with Claude Code extension.
+
+### 4. Start the workflow
+
+Tell Claude:
+
+```
+@PROMPT.md execute this prompt
+```
+
+Claude will ask for the target platform (iOS, macOS, etc.) and then ask you to point to the source code folder. Provide the full path:
+
+```
+/Users/macpro2019/Documents/FORGEJO/my-web-app/
+```
+
+### 5. Follow the 8 phases
+
+Claude will walk you through each phase and ask for approval before proceeding:
+
+| Phase | What Happens | Your Role |
+|-------|-------------|-----------|
+| **0 — Audit** | Reads every file, produces audit report | Review and approve |
+| **1 — Architecture** | Proposes MVVM/TCA, scaffolds Xcode project | Choose architecture, confirm |
+| **2 — Features** | Implements one feature at a time with tests | Test in Simulator after each |
+| **3 — Persistence** | Adds SwiftData, auto-save, preferences | Verify save/resume works |
+| **4 — Accessibility** | VoiceOver, Dynamic Type, localization | Test with VoiceOver on |
+| **5 — Quality** | Static analysis, 70%+ test coverage | Review test results |
+| **6 — App Store** | Privacy manifest, icons, metadata | Provide App Store details |
+| **7 — Documentation** | SETUP.md, CHANGELOG.md, ARCHITECTURE.md | Review and commit |
+
+### 6. Test on simulators
+
+```bash
+# Generate Xcode project
+xcodegen generate
+
+# Build and run on iPhone
+xcodebuild build -project MyApp.xcodeproj -scheme MyApp \
+  -destination 'platform=iOS Simulator,name=iPhone 16'
+
+# Build and run on iPad
+xcodebuild build -project MyApp.xcodeproj -scheme MyApp \
+  -destination 'platform=iOS Simulator,name=iPad Pro 11-inch (M4)'
+
+# Build and run on Mac
+xcodebuild build -project MyApp.xcodeproj -scheme MyApp \
+  -destination 'platform=macOS' CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO
+```
+
+Or just open the `.xcodeproj` in Xcode and press **Cmd+R**.
+
+### 7. Commit and push
+
+```bash
+git add -A
+git commit -m "feat: MyApp v1.0.0 — native SwiftUI for iOS, iPadOS, macOS"
+git push origin main
+```
+
+## Tips
+
+- **Don't rush** — approve each phase before moving on. Quality > speed.
+- **Test on device** — Simulator is good but real devices catch touch/scroll issues.
+- **Screenshot everything** — share screenshots with Claude when something looks off. It will fix the layout.
+- **Landscape matters** — always test both orientations on iPhone.
+- **Start a new game/session** — if Claude's context gets too long, start a new conversation and point it to the repo + PROMPT.md again. It will pick up where you left off.
+- **Keep PROMPT.md in the app repo** — it serves as documentation of the conversion methodology used.
+
+## Template repo
+
+The workflow template lives at:
+```
+https://git.istratai.cloud/aj/XCode-Claude-Workflow
+```
+
+## Example project
+
+SoliCards (solitaire card game) was converted using this exact workflow:
+```
+Source:  https://git.istratai.cloud/aj/game-SoliCards
+Result:  https://git.istratai.cloud/aj/SoliCards-iOS-iPadOS-MacOS
+```