XBOX-GDK-dotnet

# AGENTS.md: `gdk-dotnet`

## What this repository is

The **dotnet** implementation of the Microsoft GDK idiomatic projection. It is one of eight
sibling language repositories split out of the `gdk-projections-plans` meta repo.

## The specification lives in the meta repo

The authoritative specification for this repository is `plans/dotnet.md` in the
`gdk-projections-plans` meta repo, alongside the nine shared, language-agnostic reference docs
under `reference/` (`gdk-surface.md`, `xuser-pilot.md`, `state-change.md`, `multiplayer-pilot.md`,
`roadmap.md`, `security-privacy.md`, `compliance.md`, `glossary.md`, `testing.md`). The plan follows
a shared 15-section template; §4 (the mapping table) is the heart, §9 is the acceptance slice (the
`XUser` pilot, plus the PFMP Lobby state-change slice).

Those documents are **not vendored into this repository**. This repo is public and the meta repo is
not, so the specification is not mirrored here and must not be copied back in. Read it in the meta
repo, and fix it there.

## Everything under `docs/` is authored here

`docs/` is canonical for this repository. There is no vendored content and no re-vendor step.

| Path | Notes |
|---|---|
| `docs/README.md` | The documentation index. Add new authored pages here. |
| `docs/building.md` | Build, test, run, package. |
| `docs/getting-started.md` | Idioms and a first sign-in. |
| `docs/architecture.md` | Layering, target frameworks, the AOT contract. |
| `docs/gdk-edition.md` | The re-pin procedure and minimum version. |
| `docs/status.md` | What is projected, what is out of scope, the coverage numbers. |
| `docs/native-aot.md` | How AOT safety is enforced, and how to AOT-publish a title. |
| `docs/custom-game-ui.md` | Title-implemented UI and its threading rules. |
| `docs/repository-layout.md` | Where things live; what is generated. |
| `docs/api/` | **Generated.** Do not hand-edit; edit the XML doc comments and run `eng/generate-docs.ps1`. One folder per namespace, each with a generated `README.md` index. |

Because this repository is public, do not add links to the meta repo or to any other private
resource in documentation, source comments or commit messages: they resolve for nobody outside
Microsoft.

## Public API changes must stay documented

`src/GDK.Net/GDK.Net.csproj` sets `GenerateDocumentationFile`, and `TreatWarningsAsErrors` is on
repo-wide, so a new public type or member without an XML doc comment **fails the build** (CS1591).
This is deliberate: it is what keeps `docs/api/` complete.

- Hand-written code: write the doc comment.
- Generated PlayFab/Party code: fix the emitter under `eng/playfab/`, never the output. The enum
  member summaries come from `emit_native.emit_enum(..., document: true)`.
- After any public API change, re-run `pwsh eng/generate-docs.ps1` and commit `docs/api/`.
  `ApiReferenceDriftTests` fails when a type has no page or a page outlives its type.
- `docs/api/` is one folder per namespace, each holding the type pages and a generated `README.md`
  index. The layout is applied by `eng/api-layout.ps1`, which `generate-docs.ps1` calls last and
  which can also be run alone. Never add or rename a folder there by hand: change
  `eng/api-areas.json` and re-run. Folders exist because GitHub truncates a directory listing at
  1,000 entries and the flat output is past that.


## Ground rules

1. **Idiomatic, not mechanical.** Callers must never see an `HRESULT`, a raw handle, an
   `XAsyncBlock`, a registration token, or a two-call size buffer.
2. **Scope.** In: the core `X*` runtime + the `_c` services (XSAPI, libHttpClient, GameChat2,
   PlayFab incl. PFMP and Party). Out: XCurl, XAL, GameInput, the GXDK console tree.
3. **Pinned GDK edition `260404`**. Headers come from the edition's `windows\include` tree and
   import libraries from `windows\lib\{x64,arm64}`. **Never** use the `GRDK\GameKit\*` paths:
   they omit the XBOX Live / PlayFab stack and ship no `arm64` libraries. Derive paths from
   `%GameDKCoreLatest%` (the edition root), never `%GRDKLatest%` or `%GXDKLatest%`.
4. **Cancellation** (`E_ABORT`) routes to the language's cancellation idiom, never a generic error.
   The numeric HRESULT is always preserved for diagnostics.
5. **Testing is live.** The pilot is validated in a packaged GDK app against a real sandbox; CI only
   builds and lints.
6. **Supported versions are declared in `README.md`.** Any change to the supported runtime,
   architecture, engine, or toolchain matrix must update that table in the same change.