diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..61b91ba
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,24 @@
+# SwiftApp
+
+A minimal UIKit iOS demo app (a single `ViewController` with a button that updates a label). Created with Xcode in 2017 targeting iOS 10.3, Swift 3.0.
+
+## Project layout
+
+- `SwiftApp/` — app sources: `AppDelegate.swift`, `ViewController.swift`, storyboards (`Base.lproj/*.storyboard`), `Info.plist`, `Assets.xcassets`.
+- `SwiftApp.xcodeproj/` — Xcode project (single app target `SwiftApp`, no unit/UI test target).
+
+## Building & running (macOS + Xcode required)
+
+This is an Apple platform app that depends on `UIKit` and Xcode's iOS toolchain/simulator. Build and run it on macOS:
+
+- Open in Xcode: `open SwiftApp.xcodeproj`, then press Run (select an iOS Simulator).
+- Or from the command line: `xcodebuild -project SwiftApp.xcodeproj -scheme SwiftApp -sdk iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 15' build`
+
+There are no automated tests (the scheme's `Testables` list is empty), no linter configured, and no dependency manager (no CocoaPods/SPM/Carthage) in this repo.
+
+## Cursor Cloud specific instructions
+
+- Cursor Cloud Agent VMs are **Linux (Ubuntu)**. This is an **iOS/UIKit app that can only be built and run on macOS with Xcode** (it needs the `iphoneos`/`iphonesimulator` SDK and `UIKit`, neither of which exist on Linux). Xcode does not run on Linux.
+- Consequently, on the Cloud Agent VM you **cannot build, run, lint, or test** this app. There is no Linux-installable dependency that changes this — the open-source Swift toolchain for Linux still lacks `UIKit`.
+- There is nothing to install for a Linux dev environment; the update script is intentionally a no-op.
+- To actually develop/verify changes, use a macOS machine with Xcode (see the build/run commands above). Cloud agents should limit themselves to static source edits and code review, and clearly flag that build/run/test verification must happen on macOS.