From f638e71a23b44758824cdfc187cb4c8a81ff9227 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 28 May 2026 14:05:04 +0000
Subject: [PATCH] Add AGENTS.md with Cursor Cloud development instructions

- Document platform constraints (iOS/watchOS project requires macOS + Xcode)
- Document available Linux tools: SwiftLint for linting, swiftc -parse for syntax
- Include environment setup notes and project structure quick reference

Co-authored-by: Tim Champ <bisonbet@users.noreply.github.com>
---
 AGENTS.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..749363d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,56 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+### Platform constraints
+
+This is a **native iOS/watchOS Xcode project**. It requires **macOS with Xcode 15+** to build, run the iOS Simulator, and execute unit/UI tests. On a Linux Cloud Agent VM:
+
+- **Cannot build**: `xcodebuild` is macOS-only.
+- **Cannot run**: iOS Simulator requires macOS.
+- **Cannot run unit/UI tests**: Tests require Xcode and the simulator.
+- **Cannot resolve SPM dependencies via Xcode**: The project uses Xcode-managed SPM (no standalone `Package.swift`), and packages depend on Apple-only frameworks.
+
+### What you CAN do on Linux
+
+- **Lint**: Run `swiftlint lint` against Swift files (requires `LINUX_SOURCEKIT_LIB_PATH` set; see below).
+- **Syntax-check**: Run `swiftc -parse <file.swift>` to validate Swift syntax (works for files without Apple framework imports).
+- **Code review/editing**: Read, search, and edit all Swift source files, Core Data model XML, plists, entitlements, etc.
+- **Git operations**: Full git workflow including branching, committing, and pushing.
+
+### Environment setup (already done by update script)
+
+- **Swift 6.3.x** installed via [Swiftly](https://swift.org/install/linux/) at `~/.local/share/swiftly/`.
+- **SwiftLint 0.58.x** installed at `/usr/local/bin/swiftlint`.
+- Environment variables sourced from `~/.bashrc`:
+  - Swiftly env: `. "${SWIFTLY_HOME_DIR:-$HOME/.local/share/swiftly}/env.sh"`
+  - SourceKit path: `export LINUX_SOURCEKIT_LIB_PATH=...` (auto-computed from installed toolchain)
+
+### Running SwiftLint
+
+```bash
+cd "BisonNotes AI/BisonNotes AI"
+swiftlint lint                    # Full lint with all details
+swiftlint lint --reporter summary # Summary table only
+```
+
+SwiftLint runs with default rules (no `.swiftlint.yml` exists in the repo). The codebase has ~9,000 pre-existing violations (mostly `trailing_whitespace` and `line_length`), so lint errors from these rules are expected and not introduced by agents.
+
+### Running Swift syntax checks
+
+```bash
+swiftc -parse "BisonNotes AI/BisonNotes AI/Models/AudioModels.swift"
+```
+
+Note: `swiftc -parse` validates syntax only. Files that import Apple frameworks (SwiftUI, CoreData, AVFoundation, etc.) will parse successfully but cannot be compiled on Linux.
+
+### Project structure quick reference
+
+See `README.md` (Build and Test section) and `CLAUDE.md` (Architecture Overview) for full details. Key paths:
+
+- Xcode project: `BisonNotes AI/BisonNotes AI.xcodeproj`
+- iOS app source: `BisonNotes AI/BisonNotes AI/`
+- Watch app: `BisonNotes AI/BisonNotes AI Watch App/`
+- Unit tests: `BisonNotes AI/BisonNotes AITests/`
+- UI tests: `BisonNotes AI/BisonNotes AIUITests/`
+- Pre-compiled framework: `Frameworks/llama.xcframework/`