Add comprehensive DTFx documentation

README.md

@@ -2,6 +2,8 @@
 
 The Durable Task Framework (DTFx) is a library that allows users to write long running persistent workflows (referred to as _orchestrations_) in C# using simple async/await coding constructs. It is used heavily within various teams at Microsoft to reliably orchestrate long running provisioning, monitoring, and management operations. The orchestrations scale out linearly by simply adding more worker machines. This framework is also used to power the serverless [Durable Functions](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-overview) extension of [Azure Functions](https://azure.microsoft.com/services/functions/).
 
+> **📖 Documentation:** Comprehensive documentation is available in the [docs](./docs/README.md) folder. The [GitHub Wiki](https://github.com/Azure/durabletask/wiki) is no longer actively maintained — please refer to the docs folder for up-to-date content.
+
 By open sourcing this project we hope to give the community a very cost-effective alternative to heavy duty workflow systems. We also hope to build an ecosystem of providers and activities around this simple yet incredibly powerful framework.
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).

docs/README.md

@@ -0,0 +1,31 @@
+# Durable Task Framework Documentation
+
+The Durable Task Framework (DTFx) is an open-source framework for writing long-running, fault-tolerant workflow orchestrations in .NET. It provides the foundation for [Azure Durable Functions](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview) and can be used standalone with various backend storage providers.
+
+## Quick Links
+
+| Section | Description |
+| ------- | ----------- |
+| [Getting Started](getting-started/installation.md) | Installation, quickstart, and choosing a backend |
+| [Core Concepts](concepts/core-concepts.md) | Task Hubs, Workers, Clients, and architecture overview |
+| [Features](features/retries.md) | Retries, timers, external events, sub-orchestrations, and more |
+| [Providers](providers/durable-task-scheduler.md) | Backend storage providers (Durable Task Scheduler, Azure Storage, etc.) |
+| [Telemetry](telemetry/distributed-tracing.md) | Distributed tracing, logging, and Application Insights |
+| [Advanced Topics](advanced/middleware.md) | Middleware, entities, serialization, and testing |
+| [Samples](samples/catalog.md) | Sample projects and code patterns |
+
+## Recommended: Durable Task Scheduler with the modern .NET SDK
+
+For new projects, we recommend using the **[Durable Task Scheduler](providers/durable-task-scheduler.md)**—a fully managed Azure service that provides:
+
+- ✅ A more modern [Durable Task .NET SDK](https://github.com/microsoft/durabletask-dotnet) with improved developer experience
+- ✅ Zero infrastructure management
+- ✅ Built-in monitoring dashboard
+- ✅ Highest throughput of all backends
+- ✅ 24/7 Microsoft Azure support with SLA
+
+See [Choosing a Backend](getting-started/choosing-a-backend.md) for a full comparison of all available providers.
+
+## Support
+
+See [Support](support.md) for information about getting help with the Durable Task Framework.

docs/advanced/README.md

@@ -0,0 +1,15 @@
+# Advanced Topics
+
+This section covers advanced features and techniques for the Durable Task Framework.
+
+## Topics
+
+| Topic | Description |
+| ----- | ----------- |
+| [Middleware](middleware.md) | Intercept and extend orchestration/activity execution with cross-cutting concerns |
+| [Serialization](serialization.md) | Custom data converters and serialization patterns |
+| [Testing](testing.md) | Unit testing activities, integration testing with the emulator |
+| [Entities](entities.md) | Durable Entities guidance (not supported for direct use in DTFx) |
+
+> [!NOTE]
+> For Durable Entities support, see [Azure Durable Functions](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-entities) or the [Durable Task SDK](https://github.com/microsoft/durabletask-dotnet) with [Durable Task Scheduler](../providers/durable-task-scheduler.md).

docs/advanced/entities.md

@@ -0,0 +1,30 @@
+# Durable Entities
+
+Durable Entities provide a way to manage small pieces of state with well-defined operations. Entities are addressable by a unique identifier and can be called from orchestrations or signaled from anywhere.
+
+## Entity Support in the Durable Task Framework
+
+> [!IMPORTANT]
+> Durable Entities are **not directly supported** for end-user development in the Durable Task Framework. The entity-related APIs that exist in this library (such as `TaskEntity`, `EntityId`, `OrchestrationEntityContext`, etc.) are low-level infrastructure components intended to support [Azure Durable Functions](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-entities) scenarios.
+
+## Recommended Alternatives
+
+If you want to build applications that leverage the capabilities of Durable Entities, consider one of the following options:
+
+### Azure Durable Functions
+
+[Azure Durable Functions](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-entities) provides a complete, high-level programming model for Durable Entities with full support for:
+
+- Entity classes and function-based entities
+- Calling and signaling entities from orchestrations
+- Entity state persistence and management
+- Distributed locking and critical sections
+
+### Durable Task SDK with Durable Task Scheduler
+
+The [Durable Task SDK](https://github.com/microsoft/durabletask-dotnet) used together with the [Durable Task Scheduler](durable-task-scheduler.md) provides a modern programming model with entity support. This is the recommended approach for new .NET applications that need durable entity capabilities outside of Azure Functions.
+
+## Next Steps
+
+- [Durable Task Scheduler](../providers/durable-task-scheduler.md) — Learn about the Durable Task Scheduler backend
+- [Choosing a Backend](../getting-started/choosing-a-backend.md) — Compare available backend providers