[Docs] Small developer docs clean-up (#7799)

## Summary of changes

Small docs clean-up to resolve pending comments from #7639.

## Reason for change

Improve documentation clarity and structure.

## Implementation details

- `AGENTS.md` 🤖
  - Removed reference to old `Datadog.Monitoring.Distribution`
  - Added `Datadog.Trace.Bundle`
- `docs/development/AzureFunctions.md`
- Clarified package usage patterns for `Datadog.AzureFunctions` vs
`Datadog.Trace`
- `docs/development/for-ai/AzureFunctions-Architecture.md` 🤖
- moved to `docs/development/for-ai/` subdirectory to indicate AI
agent-focused content
- Updated cross-references to reflect new Azure Functions Architecture
doc location
- Small formatting tweaks

## Test coverage

Documentation changes only - no functional code changes.

---------

Co-authored-by: Claude <[email protected]>

Author: lucaspimentel

AGENTS.md

@@ -21,22 +21,22 @@
 
 ## NuGet Package Architecture
 
-### Datadog.Trace Package
+### `Datadog.Trace` Package
 The `Datadog.Trace` NuGet package provides the **manual instrumentation API** for customers:
 - **Contains**: `Datadog.Trace.Manual.dll` - Public API for manual instrumentation
 - **Does NOT contain**: Auto-instrumentation code or native profiler binaries
 - **Usage**: Reference in application code for manual tracing (e.g., `Tracer.Instance.StartActive()`)
 
 Auto-instrumentation comes from the tracer "monitoring home" deployed separately (via installers, MSI, container images, or specialized packages like `Datadog.AzureFunctions`).
 
-### Datadog.Trace.dll vs Datadog.Trace.Manual.dll
+### `Datadog.Trace.dll` vs `Datadog.Trace.Manual.dll`
 - `Datadog.Trace.dll` - The full managed tracer with all auto-instrumentation code, loaded by the native profiler into instrumented processes
 - `Datadog.Trace.Manual.dll` - Lightweight manual instrumentation API packaged in the `Datadog.Trace` NuGet package for customer reference
 
 ### Specialized Packages
-- **Datadog.AzureFunctions**: Bundles `Datadog.Trace.dll` and native profiler for Azure Functions (see `docs/development/AzureFunctions.md`)
-- **Datadog.Monitoring.Distribution**: MSI installer for Windows (IIS, Windows Services)
-- Other serverless/platform-specific packages may bundle the full tracer similarly
+- **Datadog.Trace.Bundle**: Complete bundle with managed/native libraries for all supported .NET runtimes, OS/arch combinations, and products (APM, ASM, Continuous Profiler). An alternative distribution mechanism for auto instrumentation
+- **Datadog.AzureFunctions**: Leaner bundle for Azure Functions (see `docs/development/AzureFunctions.md`)
+- Other serverless/platform-specific packages may bundle the tracer similarly
 
 ## Tracer Structure
 
@@ -217,14 +217,13 @@ tracer/src/Datadog.Trace
 **Quick reference:**
 - **Setup**: Use Azure App Services Site Extension on Windows Premium/Elastic Premium/Dedicated plans; use `Datadog.AzureFunctions` NuGet package for Linux Consumption/Container Apps
 - **Tests**: `BuildAndRunWindowsAzureFunctionsTests` Nuke target; samples under `tracer/test/test-applications/azure-functions/`
-- **Dependencies**: `Datadog.AzureFunctions` → `Datadog.Serverless.Compat` ([datadog-serverless-compat-dotnet](https://github.com/DataDog/datadog-serverless-compat-dotnet)) contains agent executable
 - **External Repos**: [Azure Functions Host](https://github.com/Azure/azure-functions-host) and [.NET Worker](https://github.com/Azure/azure-functions-dotnet-worker)
 
 📖 **Load when**: Working on Azure Functions instrumentation or debugging serverless issues
-- **`docs/development/AzureFunctions.md`** — In-process vs isolated worker models, instrumentation specifics, ASP.NET Core integration, GRPC context propagation, and debugging guide
+- **`docs/development/AzureFunctions.md`** — Setup, testing, instrumentation specifics, and debugging guide
 
 📖 **Load when**: Need detailed architectural understanding of Azure Functions internals
-- **`docs/development/AzureFunctions-Architecture.md`** — Deep dive into Azure Functions Host and .NET Worker architecture, gRPC protocol, middleware model, distributed tracing integration, environment variables, and instrumentation hook points
+- **`docs/development/for-ai/AzureFunctions-Architecture.md`** — Deep dive into Azure Functions Host and .NET Worker architecture, gRPC protocol, and instrumentation hook points
 
 📖 **Load when**: Working on AWS Lambda or general serverless instrumentation
 - **`docs/development/Serverless.md`** — Serverless instrumentation patterns across cloud providers
@@ -315,7 +314,7 @@ The tracer runs in-process with customer applications and must have minimal perf
 - `docs/development/AutomaticInstrumentation.md` — Creating integrations
 - `docs/development/DuckTyping.md` — Duck typing guide
 - `docs/development/AzureFunctions.md` — Azure Functions integration
-- `docs/development/AzureFunctions-Architecture.md` — Azure Functions architecture deep dive
+- `docs/development/for-ai/AzureFunctions-Architecture.md` — Azure Functions architecture deep dive
 - `docs/development/Serverless.md` — Serverless instrumentation
 - `docs/development/UpdatingTheSdk.md` — SDK updates
 - `docs/development/QueryingDatadogAPIs.md` — Querying Datadog APIs for debugging (spans, logs)

docs/development/AzureFunctions.md

@@ -3,7 +3,7 @@
 This document describes how dd-trace-dotnet integrates with Azure Functions for distributed tracing.
 
 **Related Documentation:**
-- [Azure Functions Architecture Deep Dive](AzureFunctions-Architecture.md) - Detailed architectural information about Azure Functions Host and .NET Worker
+- [Azure Functions Architecture Deep Dive](for-ai/AzureFunctions-Architecture.md) - Detailed architectural information about Azure Functions Host and .NET Worker
 
 Azure functions operates in one of two ways:
 
@@ -16,11 +16,11 @@ Azure functions operates in one of two ways:
 
 The `Datadog.AzureFunctions` NuGet package is the primary instrumentation package for Azure Functions. It contains:
 
-- **Datadog.Trace.dll** - The full managed tracer with all auto-instrumentation code
-- **Native profiler binaries** - Platform-specific profiler libraries (e.g., `Datadog.Trace.ClrProfiler.Native.so` for Linux)
+- **Datadog.Trace.dll** - The full managed tracer component with all auto-instrumentation code
+- **Native binaries** - Platform-specific native libraries (e.g., `Datadog.Trace.ClrProfiler.Native.so` for Linux)
 - **Monitoring home directory structure** - Deployed to `/home/site/wwwroot/datadog/` (Linux) or equivalent on Windows
 
-When profiling is enabled globally (via `CORECLR_ENABLE_PROFILING=1`), the native profiler loads `Datadog.Trace.dll` into **both the host process (`func.exe` or `Microsoft.Azure.WebJobs.Script.WebHost`) and the worker process**. This allows instrumentation code to run in both processes, which is essential for:
+When instrumentation is enabled globally (via `CORECLR_ENABLE_PROFILING=1`), the native profiler loads `Datadog.Trace.dll` into **both the host process (`func.exe` or `Microsoft.Azure.WebJobs.Script.WebHost`) and the worker process**. This allows instrumentation code to run in both processes, which is essential for:
 - Instrumenting host process methods (e.g., `GrpcMessageConversionExtensions.ToRpcHttp()`)
 - Instrumenting worker process methods (e.g., `FunctionExecutionMiddleware`)
 - Ensuring correct trace context propagation across the process boundary
@@ -33,7 +33,7 @@ The `Datadog.Trace` NuGet package is different from `Datadog.AzureFunctions`:
 - **Does NOT contain** auto-instrumentation code or native profiler binaries
 - Used by application code for manual instrumentation (e.g., `Tracer.Instance.StartActive()`)
 
-In Azure Functions scenarios, the worker application references `Datadog.Trace` for manual instrumentation, while `Datadog.AzureFunctions` provides the auto-instrumentation. The version of `Datadog.Trace` referenced by the application doesn't need to match `Datadog.AzureFunctions` exactly, as the auto-instrumentation comes entirely from `Datadog.Trace.dll` bundled in `Datadog.AzureFunctions`.
+In Azure Functions scenarios, applications typically only need to reference `Datadog.AzureFunctions`, which provides both auto-instrumentation and pulls in `Datadog.Trace` as a transitive dependency for manual instrumentation APIs. If an application explicitly references `Datadog.Trace` (e.g., for version pinning), the version doesn't need to match `Datadog.AzureFunctions` exactly, as the auto-instrumentation comes entirely from `Datadog.Trace.dll` bundled in `Datadog.AzureFunctions`.
 
 ## In-process Azure Functions integration
 
@@ -47,7 +47,7 @@ We also instrument the `FunctionExecutor`. This provides all the details about t
 
 Isolated functions are the only supported model for Azure Functions going forward. In this model, instead of the customer's app being a class library, its a real ASP.NET Core application. The host `func.exe` starts the customer app as a sub process, and sets up a GRPC channel between the two apps. The `func.exe` host acts as a proxy for requests to the customer's app.
 
-For detailed information about the isolated worker architecture, gRPC protocol, and middleware model, see [Azure Functions Architecture Deep Dive](AzureFunctions-Architecture.md).
+For detailed information about the isolated worker architecture, gRPC protocol, and middleware model, see [Azure Functions Architecture Deep Dive](for-ai/AzureFunctions-Architecture.md).
 
 `func.exe` sets up an in-process Azure Function for every function in the customer's app. Each of the functions in `func.exe` are simple calls that proxy the request to the customer app, and then return the response.
 
@@ -113,16 +113,16 @@ gantt
 
 ### Isolated Azure Functions with ASP.NET Core Integration
 
-Isolated Azure Functions also supports an [ASP.NET Core Integration](https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide?tabs=hostbuilder%2Cwindows#aspnet-core-integration) that operates differently from the standard gRPC-based communication.
+Isolated Azure Functions also supports an [ASP.NET Core Integration](https://learn.microsoft.com/en-us/azure/azure-functions/dotnet-isolated-process-guide?tabs=hostbuilder%2Cwindows#aspnet-core-integration) mode where the host uses HTTP proxying instead of sending all request details over gRPC.
 
-#### HTTP Proxying Architecture
+**For architectural details** about HTTP proxying, YARP, and detection, see [Azure Functions Architecture Deep Dive](for-ai/AzureFunctions-Architecture.md).
 
 When ASP.NET Core integration is enabled, the `func.exe` host uses **HTTP proxying** instead of sending all request details over gRPC:
 
 1. **Request Reception**: `func.exe` receives the incoming HTTP request
 2. **Capability Detection**: Host checks if worker advertised the `HttpUri` capability
-3. **Minimal gRPC Message**: `GrpcMessageConversionExtensions.ToRpcHttp()` returns an **empty** or minimal gRPC message (see [GrpcMessageConversionExtensions.cs:123-125](https://github.com/Azure/azure-functions-host/blob/dev/src/WebJobs.Script.Grpc/MessageExtensions/GrpcMessageConversionExtensions.cs#L123-L125))
-4. **HTTP Forwarding**: Host uses [YARP (Yet Another Reverse Proxy)](https://microsoft.github.io/reverse-proxy/) to forward the original HTTP request to the worker process via `DefaultHttpProxyService.StartForwarding()` ([source](https://github.com/Azure/azure-functions-host/blob/dev/src/WebJobs.Script/Http/DefaultHttpProxyService.cs#L82-L108))
+3. **Minimal gRPC Message**: `GrpcMessageConversionExtensions.ToRpcHttp()` returns an **empty** or minimal gRPC message (see [GrpcMessageConversionExtensions.cs:123-125](https://github.com/Azure/azure-functions-host/blob/de87f37cec3cf02b3e29716764d4ceb6c2856fa8/src/WebJobs.Script.Grpc/MessageExtensions/GrpcMessageConversionExtensions.cs#L123-L125))
+4. **HTTP Forwarding**: Host uses [YARP (Yet Another Reverse Proxy)](https://microsoft.github.io/reverse-proxy/) to forward the original HTTP request to the worker process via `DefaultHttpProxyService.StartForwarding()` ([source](https://github.com/Azure/azure-functions-host/blob/de87f37cec3cf02b3e29716764d4ceb6c2856fa8/src/WebJobs.Script/Http/DefaultHttpProxyService.cs#L82-L108))
 5. **Worker Processing**: Worker receives the HTTP request and processes the function
 6. **Response Proxying**: Worker's HTTP response is proxied back through the host to the client
 
@@ -182,6 +182,8 @@ Worker spans (serialized by PID 56, tagged as "worker"):
       └─ ... (additional spans)
 ```
 
+<!-- TODO: Update this section if/when span parenting is fixed to properly connect host and worker spans -->
+
 **Key insight**: When troubleshooting traces in Datadog, a single distributed trace will contain spans from both processes with different `aas.function.process` tag values. This is expected behavior.
 
 ## Local Development

docs/development/AzureFunctions-Architecture.md renamed to docs/development/for-ai/AzureFunctions-Architecture.md

@@ -3,8 +3,8 @@
 This document provides detailed architectural information about Azure Functions Host and .NET Worker, focusing on aspects relevant to dd-trace-dotnet instrumentation and distributed tracing.
 
 **Related Documentation:**
-- [Azure Functions Integration Guide](AzureFunctions.md) - Setup, testing, and instrumentation specifics for dd-trace-dotnet
-- [AGENTS.md](../../AGENTS.md) - Repository structure and development guidelines
+- [Azure Functions Integration Guide](../AzureFunctions.md) - Setup, testing, and instrumentation specifics for dd-trace-dotnet
+- [AGENTS.md](../../../AGENTS.md) - Repository structure and development guidelines
 
 **External Resources:**
 - [Azure Functions Host Repository](https://github.com/Azure/azure-functions-host)
@@ -910,10 +910,10 @@ Capture exceptions from:
 
 ### Related dd-trace-dotnet Documentation
 
-- [AzureFunctions.md](AzureFunctions.md) - Integration guide for dd-trace-dotnet
-- [AutomaticInstrumentation.md](AutomaticInstrumentation.md) - Creating integrations
-- [DuckTyping.md](DuckTyping.md) - Duck typing patterns for third-party types
-- [AGENTS.md](../../AGENTS.md) - Repository structure
+- [AzureFunctions.md](../AzureFunctions.md) - Integration guide for dd-trace-dotnet
+- [AutomaticInstrumentation.md](../AutomaticInstrumentation.md) - Creating integrations
+- [DuckTyping.md](../DuckTyping.md) - Duck typing patterns for third-party types
+- [AGENTS.md](../../../AGENTS.md) - Repository structure
 
 ---