Skip to content

Add Cursor Cloud dev environment documentation (AGENTS.md) #1

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
cyrasafia wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Add Cursor Cloud dev environment documentation (AGENTS.md) #1

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
70 changes: 70 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.