AGENTS.md@telemetry-reporter git:20261008.ce94fceA

Immutable. This exact content never changes and is served at /api/v1/blob/22028ce9b2673da9.

# Telemetry Reporter Agent Guide

This directory contains a standalone .NET 10 implementation of the Azure MCP
`server plugin-telemetry` command. Read [README.md](README.md) for user-facing
build, packaging, and usage documentation. This file defines how coding agents
should modify the project.

## Scope and Structure

- `src/ghcfa-telem/` contains the console application.
- `src/Ghcfa.Telemetry/` contains command parsing, validation, telemetry, and
  platform-specific machine information behavior.
- `tests/Ghcfa.Telemetry.Tests/` contains the .NET unit tests.
- `resources/` contains Azure MCP allowlists embedded by `Ghcfa.Telemetry`.
- `eng/scripts/Build-Native.ps1` creates opt-in Native AOT packages for the
  Azure MCP operating system and architecture matrix plus musl Linux.
- `eng/native-musl/Dockerfile` supplies the same-architecture Alpine toolchain.
- `eng/scripts/NativePackaging.psm1` defines supported targets, host mappings,
  and runtime/symbol archive and checksum validation.

The repository-level `tests/AGENTS.md` does not apply to this directory.

## Compatibility Requirements

- Preserve the Azure MCP command-line contract, JSON response shape, exit
  codes, validation behavior, telemetry event names, and telemetry properties.
- The Microsoft-only telemetry exporter policy is an intentional compatibility
  divergence. Preserve `AZURE_MCP_COLLECT_TELEMETRY` as the global opt-out, and
  do not add user-configurable Application Insights or OTLP sinks.
- Treat `CompatibilityConstants.AzureMcpCommit` as the source revision for the
  copied behavior and allowlists.
- When synchronizing with a newer Azure MCP revision, update the compatibility
  constants, embedded resources, implementation, tests, README, and third-party
  notices as applicable.
- Keep telemetry disabled in build or smoke-test scenarios that invoke the
  executable.
- Add XML summary comments to every declared C# type, including test and nested
  types.

## Build and Test

Run .NET commands from this directory so `global.json` selects the expected SDK
and Microsoft Testing Platform runner:

```powershell
dotnet build .\ghcfa-telem.slnx --configuration Release
dotnet test .\ghcfa-telem.slnx --configuration Release --no-build
```

Normal builds are framework-dependent. Native AOT is opt-in and supports
`win-x64`, `win-arm64`, `linux-x64`, `linux-arm64`, `linux-musl-x64`,
`linux-musl-arm64`, `osx-x64`, and `osx-arm64`. Follow the host mapping and
platform toolchain prerequisites in the README. Musl builds run in Alpine
containers on matching-architecture glibc Linux hosts. Their smoke tests run
in Alpine even though the orchestration host uses glibc. Other executable smoke
tests run when the target RID matches the host RID; cross-compiled Windows and
macOS ARM64 packages report an explicit skip.

## Versioning

- Nerdbank.GitVersioning is configured by `version.json` with a `0.1`
  major/minor version and `pathFilters: ["."]`.
- Do not add hard-coded `<Version>` properties to project files.
- Scripts that need the computed package version must invoke NBGV's
  `GetBuildVersion` target and read `NuGetPackageVersion`.
- Keep the NBGV package reference private and centrally versioned through
  `Directory.Packages.props`.

## Repository Integration

This project is intentionally independent of the root npm build and existing
CI workflows. Do not modify root build scripts, package manifests, or CI
configuration to include it unless the user explicitly requests that work.