Skip to content

docs: add Cursor Cloud specific instructions to AGENTS.md #73

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
kploch wants to merge 1 commit into
base: main
Choose a base branch
from
+36 −0
Draft

docs: add Cursor Cloud specific instructions to AGENTS.md #73

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
36 changes: 36 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -778,3 +778,39 @@ The `samples/SampleApp/` directory contains a Knowledge Base sample application

- Treat SampleApp csproj files as if they were in a separate repository.
- Update `PlochDataPackagesVersion` after publishing new package versions.

## Cursor Cloud specific instructions

### Overview

Ploch.Data is a .NET library suite (targeting `net8.0` + `net10.0`) providing entity model interfaces, Generic Repository / Unit of Work pattern over EF Core, and utility packages. There is no long-running server; the product is a set of NuGet libraries plus a `samples/SampleApp/ConsoleApp` demo.

### Required sibling repositories

The build depends on two sibling repos cloned **one level above** the workspace root:

| Repo | Path | Purpose |
|------|------|---------|
| `mrploch-development` | `../mrploch-development` | Shared `*.Packages.props` files imported by `Directory.Packages.props` |
| `ploch-common` | `../ploch-common` | `Ploch.Common.*` and `TestingSupport.XUnit3.*` project references |

The update script handles cloning these automatically. `ploch-common` must **not** be a shallow clone (depth 1) because Nerdbank.GitVersioning needs commit history to compute version heights; the update script uses `git fetch --unshallow` to fix this.

### Build, test, and run

All commands use Debug configuration with `UsePlochProjectReferences=true` so Ploch.* packages resolve via ProjectReference (no GitHub Packages auth needed):

```bash
dotnet restore ./Ploch.Data.slnx -p:UsePlochProjectReferences=true
dotnet build ./Ploch.Data.slnx --no-restore -p:UsePlochProjectReferences=true
dotnet test ./Ploch.Data.slnx --no-build -p:UsePlochProjectReferences=true
dotnet run --project samples/SampleApp/src/ConsoleApp/Ploch.Data.SampleApp.ConsoleApp.csproj --no-build
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

To maintain consistency with the previous commands and the statement that all commands use UsePlochProjectReferences=true, it is recommended to include this property in the dotnet run command as well. This ensures that if the --no-build flag is removed, the command still functions as intended with project references.

Suggested change
dotnet run --project samples/SampleApp/src/ConsoleApp/Ploch.Data.SampleApp.ConsoleApp.csproj --no-build
dotnet run --project samples/SampleApp/src/ConsoleApp/Ploch.Data.SampleApp.ConsoleApp.csproj --no-build -p:UsePlochProjectReferences=true

```

### Gotchas

- **NBGV shallow clone error**: If the build fails with `Shallow clone lacks the objects required to calculate version height`, the `ploch-common` repo needs `git fetch --unshallow`.
- **Duplicate import warning (MSB4011)**: `Ploch.Packages.props` is imported twice in `Directory.Packages.props`. This is a known non-blocking warning in the repo.
- **SQL Server test skipped**: `Data.EFCore.SqlServer.Tests` has one test explicitly skipped (`[Fact(Skip = ...)]`). No Docker/SQL Server setup is needed.
- **No `global.json`**: The repo does not pin SDK versions via `global.json`. The update script installs both .NET 8.0 and 10.0 SDKs.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The heading No global.json is misleading because a global.json file is present in the repository (as seen in Ploch.Data.slnx, line 102). It would be more accurate to state that the file exists but is not used for SDK pinning.

Suggested change
- **No `global.json`**: The repo does not pin SDK versions via `global.json`. The update script installs both .NET 8.0 and 10.0 SDKs.
- **global.json usage**: The repository contains a global.json file, but it does not pin specific SDK versions. The update script installs both .NET 8.0 and 10.0 SDKs.

- **GitHub Packages NuGet source**: The `NuGet.Config` includes a `github` source for `Ploch.*` packages. In Debug mode with `UsePlochProjectReferences=true`, these resolve via ProjectReference so no auth token is required. Release builds or standalone SampleApp builds would need a `GH_PACKAGES_TOKEN`.
Loading