# doany.ai — Microsoft Docs Source-of-Truth Mapping

> **Created:** 2026-04-13
> **Purpose:** Canonical reference for the team — maps each topic to the correct documentation surface and verified URLs.
> **Context:** Replaces broken/wrong links found in `engineer-handbook.md` during 2026-04-10 incident review.

---

## 1. Azure Blob Storage — Upload & Download

**Docs surface:** [learn.microsoft.com](https://learn.microsoft.com) (formerly docs.microsoft.com — old domain redirects but should not be used in bookmarks)

| Question | Verified URL |
|----------|-------------|
| What is Blob Storage? (overview) | https://learn.microsoft.com/azure/storage/blobs/storage-blobs-introduction |
| Quickstart (.NET, SDK v12) | https://learn.microsoft.com/azure/storage/blobs/storage-quickstart-blobs-dotnet |
| Get started & developer guides (.NET) | https://learn.microsoft.com/azure/storage/blobs/storage-blob-dotnet-get-started |
| Upload blobs (.NET) | https://learn.microsoft.com/azure/storage/blobs/storage-blob-upload |
| Download blobs (.NET) | https://learn.microsoft.com/azure/storage/blobs/storage-blob-download |
| BlobServiceClient API reference | https://learn.microsoft.com/dotnet/api/azure.storage.blobs.blobserviceclient |
| BlobClient API reference | https://learn.microsoft.com/dotnet/api/azure.storage.blobs.blobclient |
| Managed identity auth (DefaultAzureCredential + Blob) | https://learn.microsoft.com/azure/app-service/tutorial-connect-msi-azure-database#access-blob-storage |
| Azure Identity client library overview | https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme |
| Quickstart (Java) | https://learn.microsoft.com/azure/storage/blobs/storage-quickstart-blobs-java |
| Quickstart (Node.js) | https://learn.microsoft.com/azure/storage/blobs/storage-quickstart-blobs-nodejs |
| Quickstart (Python) | https://learn.microsoft.com/azure/storage/blobs/storage-blob-python-get-started |
| Blob Storage REST API | https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api |

### Answers to open questions

- **`BlobClient.UploadAsync` with overwrite semantics:** Covered in the [Upload blobs (.NET)](https://learn.microsoft.com/azure/storage/blobs/storage-blob-upload) developer guide. Pass `overwrite: true` to `UploadAsync`.
- **Managed identity + upload code sample:** The [quickstart](https://learn.microsoft.com/azure/storage/blobs/storage-quickstart-blobs-dotnet) shows `DefaultAzureCredential` + upload end-to-end. For a web-app-specific walkthrough, see the [App Service managed identity tutorial](https://learn.microsoft.com/azure/app-service/tutorial-connect-msi-azure-database).

### Version notes

- Use NuGet package `Azure.Storage.Blobs` (v12). The older `WindowsAzure.Storage` and `Microsoft.Azure.Storage.Blob` packages are deprecated.
- Use `Azure.Identity` for `DefaultAzureCredential`. Avoid account access keys in production.

---

## 2. .NET Aspire — Redis & PostgreSQL Integrations

**Docs surface:** [aspire.dev](https://aspire.dev) — NOT learn.microsoft.com. Aspire docs moved to aspire.dev as of 2025. Links to `learn.microsoft.com/dotnet/aspire/*` will 404 or show outdated content.

| Question | Verified URL |
|----------|-------------|
| Aspire overview | https://learn.microsoft.com/dotnet/aspire/get-started/aspire-overview |
| Build your first Aspire app (quickstart) | https://learn.microsoft.com/dotnet/aspire/get-started/build-your-first-aspire-app |
| Aspire setup & tooling | https://learn.microsoft.com/dotnet/aspire/fundamentals/setup-tooling |
| App host / orchestration overview | https://learn.microsoft.com/dotnet/aspire/fundamentals/app-host-overview |
| Integrations overview | https://aspire.dev/integrations/overview/ |
| Integrations gallery (browse all) | https://aspire.dev/integrations/gallery/ |
| Redis integration — get started (`AddRedis`) | https://aspire.dev/integrations/caching/redis/redis-get-started/ |
| Redis hosting extensions | https://aspire.dev/integrations/caching/redis-extensions/ |
| PostgreSQL integration — get started (`AddPostgres`) | https://aspire.dev/integrations/databases/postgres/postgres-get-started/ |
| Persist data with volumes/bind mounts | https://aspire.dev/fundamentals/persist-data-volumes/ |
| What's new in Aspire 13.1 | https://aspire.dev/whats-new/aspire-13-1/ |

### Answers to open questions

- **Where do Aspire integration docs live?** Integration-specific docs (Redis, Postgres, etc.) live on **aspire.dev**. High-level overview and quickstart pages are still on learn.microsoft.com under `/dotnet/aspire/`.
- **Correct page for `AddRedis` / `AddPostgres` in Aspire 13:** See the get-started links above on aspire.dev.

### Version notes

- Team uses Aspire 13. Aspire CLI 13.2+ includes built-in MCP docs search tools (`list_docs`, `search_docs`, `get_doc`).
- Update CLI: `aspire update --self --channel daily`.

---

## 3. VS Code — Remote Debugging Python Services

**Docs surface:** [code.visualstudio.com](https://code.visualstudio.com/docs) — NOT learn.microsoft.com. VS Code docs have never been on Learn.

| Question | Verified URL |
|----------|-------------|
| Debugging overview | https://code.visualstudio.com/docs/debugtest/debugging |
| Debug configuration (launch.json reference) | https://code.visualstudio.com/docs/debugtest/debugging-configuration |
| Python debugging (debugpy config) | https://code.visualstudio.com/docs/python/debugging |
| Remote Development overview | https://code.visualstudio.com/docs/remote/remote-overview |
| Remote SSH — setup & usage | https://code.visualstudio.com/docs/remote/ssh |
| Remote SSH — tutorial | https://code.visualstudio.com/docs/remote/ssh-tutorial |
| Remote Development tips & troubleshooting | https://code.visualstudio.com/docs/remote/troubleshooting |
| Remote Development FAQ | https://code.visualstudio.com/docs/remote/faq |
| Node.js debugging | https://code.visualstudio.com/docs/nodejs/nodejs-debugging |
| C/C++ launch.json reference | https://code.visualstudio.com/docs/cpp/launch-json-reference |
| C# debugger settings | https://code.visualstudio.com/docs/csharp/debugger-settings |

### Answers to open questions

- **Correct base URL for VS Code docs:** `https://code.visualstudio.com/docs/`
- **Official `debugpy` attach configuration reference:** [Python debugging in VS Code](https://code.visualstudio.com/docs/python/debugging) — covers `request: "attach"`, `connect`, and `pathMappings`.
- **Remote-SSH + Python debugging together:** Use [Remote SSH](https://code.visualstudio.com/docs/remote/ssh) to connect, then the [Python debugging](https://code.visualstudio.com/docs/python/debugging) page for attach config. There is no single combined page; the two docs are complementary.

### Version notes

- The team's launch.json uses `"type": "debugpy"` which is the current Python debugger extension (replaced the older `"type": "python"`).

---

## 4. Agent Framework — DevUI REST API & Workflow Orchestration

**Docs surface:** Split across two locations:
- **Tutorials & guides:** [learn.microsoft.com/agent-framework/](https://learn.microsoft.com/agent-framework/)
- **API-level detail** (REST endpoints, CLI flags, .NET integration): [github.com/microsoft/agent-framework](https://github.com/microsoft/agent-framework) — repo docs are often ahead of published Learn content.

| Question | Verified URL |
|----------|-------------|
| Agent Framework overview | https://learn.microsoft.com/agent-framework/overview/ |
| Get started (step-by-step tutorial) | https://learn.microsoft.com/agent-framework/get-started/ |
| Your first agent | https://learn.microsoft.com/agent-framework/get-started/your-first-agent |
| Agent development journey (full learning path) | https://learn.microsoft.com/agent-framework/journey/ |
| DevUI overview | https://learn.microsoft.com/agent-framework/devui/ |
| DevUI API reference (REST endpoints) | https://learn.microsoft.com/agent-framework/devui/api-reference |
| DevUI directory discovery | https://learn.microsoft.com/agent-framework/devui/directory-discovery |
| DevUI tracing & observability | https://learn.microsoft.com/agent-framework/devui/tracing |
| DevUI security & deployment | https://learn.microsoft.com/agent-framework/devui/security |
| DevUI samples | https://learn.microsoft.com/agent-framework/devui/samples |
| Workflows overview | https://learn.microsoft.com/agent-framework/workflows/ |
| Workflow orchestrations (all patterns) | https://learn.microsoft.com/agent-framework/workflows/orchestrations/ |
| Sequential orchestration | https://learn.microsoft.com/agent-framework/workflows/orchestrations/sequential |
| Concurrent orchestration | https://learn.microsoft.com/agent-framework/workflows/orchestrations/concurrent |
| Handoff orchestration | https://learn.microsoft.com/agent-framework/workflows/orchestrations/handoff |
| Group Chat orchestration | https://learn.microsoft.com/agent-framework/workflows/orchestrations/group-chat |
| Magentic orchestration | https://learn.microsoft.com/agent-framework/workflows/orchestrations/magentic |
| Human-in-the-loop | https://learn.microsoft.com/agent-framework/workflows/human-in-the-loop |
| Workflows as agents | https://learn.microsoft.com/agent-framework/workflows/as-agents |
| Multi-agent architecture pattern (Azure) | https://learn.microsoft.com/azure/architecture/ai-ml/idea/multiple-agent-workflow-automation |
| GitHub repo (source, API detail) | https://github.com/microsoft/agent-framework |

### DevUI REST API quick reference

From the [API Reference](https://learn.microsoft.com/agent-framework/devui/api-reference):

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/responses` | POST | Execute an agent or workflow |
| `/v1/entities` | GET | List discovered agents/workflows |
| `/v1/entities/{id}/info` | GET | Get entity details |
| `/v1/entities/{id}/reload` | POST | Hot-reload entity |
| `/v1/conversations` | POST | Create a conversation |
| `/v1/conversations/{id}` | GET | Get conversation details |
| `/health` | GET | Health check |
| `/meta` | GET | Server metadata & capabilities |

### Answers to open questions

- **Which docs are on Learn vs. GitHub?** Tutorials, DevUI guides, workflow orchestration patterns, and the development journey are all on learn.microsoft.com. The GitHub repo has source code, runnable samples, and sometimes documents API details ahead of Learn.
- **REST API reference for DevUI:** Now published on Learn at [DevUI API Reference](https://learn.microsoft.com/agent-framework/devui/api-reference).
- **Workflow orchestration with conditional edges:** See the [Workflows overview](https://learn.microsoft.com/agent-framework/workflows/) (covers graph-based routing with conditional edges) and individual orchestration pattern pages.

### Version notes

- Python: `pip install agent-framework` / `pip install agent-framework-devui --pre`
- .NET: `dotnet add package Microsoft.Agents.AI.Foundry --prerelease`
- DevUI C# docs are marked "coming soon" — use Python docs for conceptual guidance.

---

## Quick-Reference: Documentation Surface Map

| Technology | Primary docs site | Common mistake |
|------------|-------------------|----------------|
| Azure Blob Storage | learn.microsoft.com | Using old `docs.microsoft.com` domain |
| .NET Aspire (overview) | learn.microsoft.com/dotnet/aspire | — |
| .NET Aspire (integrations) | **aspire.dev** | Using learn.microsoft.com paths that 404 |
| VS Code | **code.visualstudio.com/docs** | Using learn.microsoft.com (never hosted VS Code docs) |
| Agent Framework (tutorials) | learn.microsoft.com/agent-framework | Guessing URL paths that don't exist |
| Agent Framework (API detail) | **github.com/microsoft/agent-framework** | Expecting all API docs on Learn |