docs(agents): Add Development Environment & Build section to AGENTS.md (#73)

Documents how any agent or contributor builds the repository: an overview
of the Ploch.Data library suite, the required sibling repositories, the
build/test/run commands, and build gotchas. The one genuinely
Cursor-Cloud-specific detail is kept as a small subsection.

Replaces the original "Cursor Cloud specific instructions" framing, which
mislabelled generic repo knowledge as vendor-specific, and corrects three
factual errors: a nonexistent global.json, a non-occurring MSB4011
warning, and the scope of UsePlochProjectReferences.

Co-Authored-By: Cursor Agent <cursoragent@cursor.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

AGENTS.md

@@ -784,3 +784,44 @@ 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.
+
+## Development Environment & Build
+
+This section applies to any agent or contributor building the repository — locally, in CI, or in a cloud sandbox.
+
+### Overview
+
+Ploch.Data is a .NET library suite (targeting `net8.0` + `net10.0`) providing entity model interfaces, the 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 |
+
+`ploch-common` must **not** be a shallow clone (depth 1): Nerdbank.GitVersioning needs the full commit history to compute version heights. If it was cloned shallow, run `git fetch --unshallow` inside it.
+
+### Build, test, and run
+
+Pass `-p:UsePlochProjectReferences=true` so the `samples/SampleApp` projects build against the library source via `ProjectReference` instead of restoring published `Ploch.Data.*` NuGet packages. With both sibling repos cloned, the solution then builds entirely from source and needs no GitHub Packages token:
+
+```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 -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`.
+- **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 repository does not pin an SDK version via `global.json`. Install both the .NET 8.0 and 10.0 SDKs so each target framework can build.
+- **GitHub Packages NuGet source**: `NuGet.Config` declares a `github` source for `Ploch.*` packages. A local solution build with `-p:UsePlochProjectReferences=true` and both sibling repos present resolves everything from source, so no token is needed. Building the SampleApp standalone (`Ploch.Data.SampleApp.slnx`) or producing Release / `pack` artefacts pulls `Ploch.Data.*` from the feed and needs a `GH_PACKAGES_TOKEN`.
+
+### Cursor Cloud background agents
+
+Cursor Cloud background agents provision the workspace with an environment update script (configured in Cursor, not committed to this repo) that clones the sibling repositories listed above, runs `git fetch --unshallow` on `ploch-common`, and installs the .NET 8.0 and 10.0 SDKs.