From 340e98020285e54e697f663a6fd6486c5cd985b8 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Wed, 3 Jun 2026 15:20:23 +0000
Subject: [PATCH] Add AGENTS.md with Cursor Cloud dev environment instructions

Document .NET SDK setup, EnableWindowsTargeting requirement on Linux,
CI-equivalent publish commands, and Windows-only runtime limitations.

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

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..a4b812c6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,70 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+### Product overview
+
+Cairo Shell is a **Windows-only WPF desktop application** (menu bar, taskbar, dynamic desktop). There are no web servers, databases, or Docker services. CI runs on `windows-latest` (see `.github/workflows/build.yml`).
+
+### Linux Cloud Agent limitations
+
+Cloud Agent VMs run **Linux**. You can **restore and cross-compile** the solution here, but you **cannot launch `CairoDesktop.exe`** (PE/WinExe). Manual GUI testing requires Windows.
+
+### Prerequisites
+
+- **.NET SDK 6.x** installed to `$HOME/.dotnet` (matches CI `net6.0-windows` builds)
+- **NuGet** access to `https://api.nuget.org/v3/index.json`
+
+### Required MSBuild property on Linux
+
+All `dotnet` commands that touch Windows-targeted projects must pass:
+
+```bash
+-p:EnableWindowsTargeting=true
+```
+
+Without this flag, restore/build fails with `NETSDK1100`.
+
+### Common commands
+
+From repo root (`/workspace`):
+
+```bash
+export DOTNET_ROOT="$HOME/.dotnet"
+export PATH="$HOME/.dotnet:$PATH"
+
+# Restore dependencies
+dotnet restore "Cairo Desktop/Cairo Desktop.sln" -p:EnableWindowsTargeting=true
+
+# Build/publish (same as CI x64 .NET 6 profile)
+cd "Cairo Desktop/Cairo Desktop"
+dotnet publish -p:PublishProfile=x64_net6 -p:Platform=x64 -f net6.0-windows -p:EnableWindowsTargeting=true
+```
+
+Publish output: `Cairo Desktop/Cairo Desktop/bin/Release/net6.0-windows/publish-x64/CairoDesktop.exe`
+
+### Tests
+
+`Tests/Cairo Desktop.Tests/` targets **.NET Framework 4.7.1** (legacy non-SDK project). It does **not** build on Linux (missing .NET Framework reference assemblies). Run tests on Windows with Visual Studio or MSBuild.
+
+### Linting
+
+No dedicated linter is configured in-repo. CI only builds/publishes; warnings from the compiler are informational.
+
+### Services to run
+
+| Service | Required on Linux VM? | Notes |
+|---------|----------------------|-------|
+| Cairo Desktop (`CairoDesktop.exe`) | No (cannot run) | Windows GUI app |
+| NuGet restore | Yes | Via `dotnet restore` |
+| External APIs (Bing wallpaper, WinSparkle) | Optional | Not needed for build |
+
+### Windows development (full E2E)
+
+On Windows with Visual Studio 2022 or `dotnet` SDK:
+
+1. Open `Cairo Desktop/Cairo Desktop.sln`
+2. Build configuration: `Debug|x64` (or publish profile above)
+3. Run `Cairo Desktop` startup project — launches the shell UI
+
+No separate backend processes need to be started.