Skip to content

Add Cursor Cloud dev-environment notes (macOS-only build constraints) #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
faint-dev wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Add Cursor Cloud dev-environment notes (macOS-only build constraints) #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# AGENTS.md

## Cursor Cloud specific instructions

### Platform constraint (read first)

Zog is a **native macOS app** (Swift/SwiftUI + AppKit, plus Apple-only frameworks
`CoreWLAN`, `IOKit`, `SystemConfiguration`, `ApplicationServices`). It has **zero
third-party dependencies** — there is no `Package.swift`, `Podfile`, or `Cartfile`;
everything comes from the Apple SDK. It is built and run exclusively with **Xcode /
`xcodebuild`** on **macOS 14+** (see `README.md` for the exact commands), and CI runs
on `macos-14` (`.github/workflows/build.yml`).

Cursor Cloud Agent VMs are **Linux x86_64**. This app therefore **cannot be built,
run, tested, or lint-checked on the Cloud VM**: there is no `swift`/`xcodebuild`
toolchain, and the required frameworks (AppKit, SwiftUI, CoreWLAN, IOKit, …) are
macOS-only and cannot be installed on Linux. This is a fundamental platform mismatch,
not a missing-dependency problem — do not attempt to install a Swift toolchain to
"fix" it (Linux Swift still lacks these Apple frameworks). There are also no unit/UI
test targets in the project to run.

### What you CAN do on the Linux Cloud VM

- Read, edit, and reason about the Swift sources under `Zog/` and the Xcode project
(`Zog.xcodeproj/project.pbxproj`).
- Preview the static design mock `docs/design-preview.html` in a browser — it is a
self-contained HTML/CSS reference of the intended UI (menu-bar "islands" + vertical
dock) and is the only artifact that renders cross-platform. Serve it with e.g.
`python3 -m http.server 8099 --directory docs` and open
`http://localhost:8099/design-preview.html`. Note: this is a design reference, NOT
the compiled application.

### What requires macOS (cannot be verified on the Cloud VM)

- Build: `xcodebuild -project Zog.xcodeproj -scheme Zog -configuration Debug build`
- Run: open the built `Zog.app` (or `open Zog.xcodeproj` and Run in Xcode). At runtime
the app autohides the native Dock/menu bar and needs **Accessibility** + **Automation**
permissions to read/click the frontmost app's menus.
- Any compile/lint feedback on the Swift code. Validate Swift changes via the macOS CI
workflow (or a local macOS machine); the Linux VM cannot surface Swift build errors.

### No update/setup script is needed

There is nothing to install on Linux for this repo (no package manifests, no
dependencies). The Cloud environment update script is intentionally a no-op.
Loading