docs: reorganize Orleans documentation navigation

[ReubenBond]

Summary

• Reorganizes the Orleans documentation into task-oriented, operational, architectural, sample, reference, and Orleans 10 upgrade tracks.
• Integrates all maintained pages introduced by the dependency PRs and adds explicit, anchor-preserving redirects for retired compatibility entry points.
• Keeps Architecture and internals as an expanded advanced track, distinguishes supported Event Sourcing from experimental Journaling, and aligns Kubernetes navigation with the explicit endpoint configuration baseline.

Dependencies

Depends on #10327, #10328, #10329, #10330, #10331, #10332, #10333, #10334, and #10335.

This stacked PR includes the dependency commits so the complete documentation hierarchy can be validated together. As each dependency merges, its aggregate ancestor commits will disappear from this PR diff, leaving the shared navigation and integration changes.

Microsoft Reviewers: Open in CodeFlow

[Copilot]

Pull request overview

Reorganizes the Orleans documentation site into updated task/operations/architecture/migration/streaming tracks, updates navigation and samples entry points, and adds explicit legacy URL redirects which preserve anchors for retired pages.

Changes:

• Updates DocFX → Starlight sidebar generation to support absolute site-root links (for example, /samples/) and adjusts tests accordingly.
• Adds explicit redirect mapping (redirects.json) and integrates it into the legacy redirect generator and rendered-output audit.
• Large-scale docs refresh: adds new Orleans 10 operational, migration, streaming, and runtime-architecture pages while removing legacy/retired tutorials and platform guidance (for example, Service Fabric/Cloud Services content and older snippet projects).

Show a summary per file

File	Description
docs/site/tests/docfx.test.mjs	Extends sidebar conversion test coverage to include an absolute /samples/ link.
docs/site/src/data/redirects.json	Adds explicit, anchor-preserving redirects for retired legacy entry points.
docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Silo/Silo.csproj	Removes legacy minimal tutorial snippet project file.
docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Silo/Program.cs	Removes legacy minimal tutorial silo snippet source.
docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/minimal.sln	Removes legacy minimal tutorial solution file.
docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Grains/HelloGrain.cs	Removes legacy minimal tutorial grain snippet.
docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Grains/Grains.csproj	Removes legacy minimal tutorial grains project file.
docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/GrainInterfaces/IHello.cs	Removes legacy minimal tutorial interface snippet.
docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/GrainInterfaces/GrainInterfaces.csproj	Removes legacy minimal tutorial interfaces project file.
docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Client/Program.cs	Removes legacy minimal tutorial client snippet source.
docs/site/src/content/docs/tutorials-and-samples/snippets/minimal/Client/Client.csproj	Removes legacy minimal tutorial client project file.
docs/site/src/content/docs/tutorials-and-samples/snippets/helloworld/SiloProgram.cs	Removes legacy Hello World tutorial silo snippet.
docs/site/src/content/docs/tutorials-and-samples/snippets/helloworld/IHello.cs	Removes legacy Hello World tutorial interface snippet.
docs/site/src/content/docs/tutorials-and-samples/snippets/helloworld/helloworld.csproj	Removes legacy Hello World tutorial project file.
docs/site/src/content/docs/tutorials-and-samples/snippets/helloworld/HelloGrain.cs	Removes legacy Hello World tutorial grain snippet.
docs/site/src/content/docs/tutorials-and-samples/snippets/helloworld/ClientProgram.cs	Removes legacy Hello World tutorial client snippet.
docs/site/src/content/docs/tutorials-and-samples/snippets-v3/custom-storage/Program.cs	Removes legacy Orleans v3 custom-storage snippet.
docs/site/src/content/docs/tutorials-and-samples/snippets-v3/custom-storage/FileSiloBuilderExtensions.cs	Removes legacy Orleans v3 custom-storage snippet extension methods.
docs/site/src/content/docs/tutorials-and-samples/snippets-v3/custom-storage/FileGrainStorageOptions.cs	Removes legacy Orleans v3 custom-storage options snippet.
docs/site/src/content/docs/tutorials-and-samples/snippets-v3/custom-storage/FileGrainStorageFactory.cs	Removes legacy Orleans v3 custom-storage factory snippet.
docs/site/src/content/docs/tutorials-and-samples/snippets-v3/custom-storage/custom-storage.csproj	Removes legacy Orleans v3 custom-storage project file.
docs/site/src/content/docs/tutorials-and-samples/overview-helloworld.md	Removes legacy Hello World tutorial page (replaced by new quickstart/redirects).
docs/site/src/content/docs/tutorials-and-samples/adventure.md	Updates sample instructions and refreshes metadata date.
docs/site/src/content/docs/streaming/streaming-operations.md	Adds new Orleans 10 streaming operations/tuning guidance.
docs/site/src/content/docs/streaming/snippets/streaming/streaming.csproj	Updates streaming snippet package set/versions for current Orleans 10 examples.
docs/site/src/content/docs/streaming/snippets/streaming/ImplicitSubscriptions.cs	Reworks implicit subscription example to a typed telemetry scenario.
docs/site/src/content/docs/streaming/snippets/streaming/ExplicitSubscriptions.cs	Reworks explicit subscription example with typed telemetry and subscribe/unsubscribe APIs.
docs/site/src/content/docs/streaming/snippets/streaming/BasicStreaming.cs	Replaces basic streaming examples with typed contracts, identities, and a producer grain.
docs/site/src/content/docs/streaming/snippets-v3/streams-quickstart/streams-quickstart.csproj	Removes legacy Orleans v3 streams quickstart snippet project.
docs/site/src/content/docs/streaming/snippets-v3/streams-quickstart/StreamConfiguration.cs	Removes legacy Orleans v3 streams configuration snippet.
docs/site/src/content/docs/streaming/snippets-v3/streams-quickstart/ReceiverGrain.cs	Removes legacy Orleans v3 receiver-grain snippet.
docs/site/src/content/docs/streaming/snippets-v3/streams-quickstart/ProducerGrain.cs	Removes legacy Orleans v3 producer-grain snippet.
docs/site/src/content/docs/streaming/snippets-v3/streams-quickstart/IRandomReceiver.cs	Removes legacy Orleans v3 receiver interface snippet.
docs/site/src/content/docs/streaming/pubsub-storage.md	Adds focused PubSubStore configuration guidance.
docs/site/src/content/docs/streaming/delivery-semantics.md	Adds provider-aware delivery/ordering/replay/recovery guidance for streams.
docs/site/src/content/docs/resources/orleans-thinking-big-and-small.md	Refreshes and modernizes “big vs small” resource article framing for Orleans 10.
docs/site/src/content/docs/resources/orleans-architecture-principles-and-approach.md	Rewrites architecture principles page for Orleans 10 framing and terminology.
docs/site/src/content/docs/quickstarts/snippets/deploy-scale-orleans-on-azure/cosmos/Program.cs	Adds Cosmos-based deployment quickstart snippet.
docs/site/src/content/docs/quickstarts/snippets/deploy-scale-orleans-on-azure/cosmos/Cosmos.csproj	Adds Cosmos quickstart snippet project file.
docs/site/src/content/docs/quickstarts/snippets/deploy-scale-orleans-on-azure/azure-storage/Program.cs	Adds Azure Table Storage-based deployment quickstart snippet.
docs/site/src/content/docs/quickstarts/snippets/deploy-scale-orleans-on-azure/azure-storage/AzureStorage.csproj	Adds Azure Table Storage quickstart snippet project file.
docs/site/src/content/docs/migration/snippets/Orleans10MigrationSnippets.csproj	Adds a dedicated Orleans 10 migration snippets project for compile validation.
docs/site/src/content/docs/migration/snippets/Orleans10MigrationExamples.cs	Adds Orleans 10 migration examples (timeouts, placement, filters, timers, serialization).
docs/site/src/content/docs/migration/deployment-and-rollback.md	Adds major-upgrade deployment and rollback prerequisites/checklists.
docs/site/src/content/docs/migration/8-to-10.md	Adds Orleans 8→10 migration path with explicit checkpoints and validation steps.
docs/site/src/content/docs/migration/7-to-10.md	Adds Orleans 7→10 migration path with sequencing and compatibility notes.
docs/site/src/content/docs/migration/3-to-7-archive.md	Adds archived Orleans 3→7 migration notes and warnings.
docs/site/src/content/docs/index.yml	Updates docs hub page metadata and refreshes highlighted links for new structure.
docs/site/src/content/docs/implementation/runtime-architecture.md	Adds new runtime call-path architecture page (client → messaging → placement → activation).
docs/site/src/content/docs/implementation/provider-authoring.md	Adds new provider authoring architecture guidance.
docs/site/src/content/docs/implementation/index.md	Replaces/expands implementation track index into a structured runtime-architecture guide.
docs/site/src/content/docs/implementation/activation-lifecycle.md	Adds detailed activation lifecycle/migration page with diagrams and invariants.
docs/site/src/content/docs/host/snippets/snippets.sln	Adds the new hosting snippets project to the snippets solution.
docs/site/src/content/docs/host/snippets/hosting/Hosting.csproj	Introduces a hosting snippet project with provider package references.
docs/site/src/content/docs/host/snippets/aspire/Silo/SiloProgram.cs	Updates Aspire snippets to use Azure Tables keyed service clients.
docs/site/src/content/docs/host/snippets/aspire/Silo/Silo.csproj	Adds Azure Storage clustering/persistence/reminders packages to Aspire silo snippet.
docs/site/src/content/docs/host/snippets/aspire/AppHost/AppHostExamples.cs	Adjusts Aspire app host example to use tables for grain storage.
docs/site/src/content/docs/host/snippets/aspire/AppHost/AppHost.csproj	Updates Aspire app host SDK and package references.
docs/site/src/content/docs/host/monitoring/snippets/observability/Program.cs	Adds a concrete OpenTelemetry configuration example for Orleans hosting.
docs/site/src/content/docs/host/monitoring/snippets/observability/Observability.csproj	Adds an Observability snippet project to compile the OTel example.
docs/site/src/content/docs/host/monitoring/silo-error-code-monitoring.md	Removes stale error-code table and points readers to source/xref and signal-based guidance.
docs/site/src/content/docs/host/monitoring/signals.md	Adds a new “interpret signals” observability guide.
docs/site/src/content/docs/host/monitoring/client-error-code-monitoring.md	Removes stale client error-code table and points to source/xref and troubleshooting guides.
docs/site/src/content/docs/host/heterogeneous-silos.md	Updates heterogeneous silo guidance for Orleans 10 patterns and current options.
docs/site/src/content/docs/host/configuration-guide/shutting-down-orleans.md	Rewrites shutdown guidance around Generic Host ownership and shutdown budgets.
docs/site/src/content/docs/host/configuration-guide/serialization.md	Links configuration guide to new serialization internals page.
docs/site/src/content/docs/host/configuration-guide/configuring-garbage-collection.md	Modernizes GC guidance and aligns it with container limits and activation management.
docs/site/src/content/docs/grains/oneway.md	Reframes one-way calls with clearer semantics and updated example.
docs/site/src/content/docs/grains/grain-versioning/version-selector-strategy.md	Updates selector strategy explanations and clarifies behavior.
docs/site/src/content/docs/grains/grain-versioning/grain-versioning.md	Modernizes versioning overview with explicit routing semantics and limitations.
docs/site/src/content/docs/grains/grain-versioning/deploying-new-versions-of-grains.md	Rewrites deployment strategy guidance, including rollback and observability.
docs/site/src/content/docs/grains/grain-versioning/compatible-grains.md	Reworks compatibility strategies page with explicit numeric rules and cautions.
docs/site/src/content/docs/grains/grain-persistence/snippets/persistence/Interfaces.cs	Updates persistence snippet interface for nullable ETag and optional cancellation token overloads.
docs/site/src/content/docs/grains/grain-persistence/dynamodb-storage.md	Rewrites DynamoDB provider guidance with production-oriented configuration notes.
docs/site/src/content/docs/grains/grain-persistence/azure-cosmos-db.md	Rewrites Cosmos DB storage guidance with clearer separation from clustering and migration cautions.
docs/site/src/content/docs/grains/event-sourcing/replicated-instances.md	Updates JournaledGrain replication/conflict guidance and clarifies boundaries.
docs/site/src/content/docs/grains/event-sourcing/notifications.md	Modernizes notification guidance and clarifies callback semantics.
docs/site/src/content/docs/grains/event-sourcing/log-consistency-providers.md	Refactors provider comparison and clarifies durability/scale constraints.
docs/site/src/content/docs/grains/event-sourcing/journaledgrain-diagnostics.md	Updates diagnostics guidance and clarifies intended use.
docs/site/src/content/docs/grains/event-sourcing/index.md	Expands event sourcing overview and distinguishes supported vs experimental journaling.
docs/site/src/content/docs/grains/event-sourcing/immediate-vs-delayed-confirmation.md	Updates confirmation semantics guidance and aligns with Orleans scheduling model.
docs/site/src/content/docs/deployment/upgrades.md	Adds new upgrade/shutdown/scale-in operational guidance page.
docs/site/src/content/docs/deployment/troubleshooting-azure-cloud-services-deployments.md	Removes retired Azure Cloud Services troubleshooting page.
docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/Program.cs	Removes legacy Service Fabric stateless hosting snippet.
docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/PackageRoot/ServiceManifest.xml	Removes legacy Service Fabric manifest snippet.
docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/PackageRoot/Config/Settings.xml	Removes legacy Service Fabric settings snippet.
docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/OrleansHostedStatelessService.cs	Removes legacy Service Fabric wrapper type snippet.
docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/Orleans.ServiceFabric.Stateless.csproj	Removes legacy Service Fabric snippet project.
docs/site/src/content/docs/deployment/snippets/service-fabric/stateless/HostedServiceCommunicationListener.cs	Removes legacy Service Fabric communication listener snippet.
docs/site/src/content/docs/deployment/snippets/service-fabric/snippets.5000.json	Removes legacy Visual Studio snippet metadata.
docs/site/src/content/docs/deployment/snippets/service-fabric/service-fabric.sln	Removes legacy Service Fabric solution file.
docs/site/src/content/docs/deployment/snippets/service-fabric/app/PublishProfiles/Local.5Node.xml	Removes legacy Service Fabric publish profile.
docs/site/src/content/docs/deployment/snippets/service-fabric/app/PublishProfiles/Local.1Node.xml	Removes legacy Service Fabric publish profile.
docs/site/src/content/docs/deployment/snippets/service-fabric/app/PublishProfiles/Cloud.xml	Removes legacy Service Fabric publish profile.
docs/site/src/content/docs/deployment/snippets/service-fabric/app/packages.config	Removes legacy Service Fabric packages.config.
docs/site/src/content/docs/deployment/snippets/service-fabric/app/Orleans.ServiceFabric.App.sfproj	Removes legacy Service Fabric application project file.
docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationParameters/Local.5Node.xml	Removes legacy Service Fabric app parameters file.
docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationParameters/Local.1Node.xml	Removes legacy Service Fabric app parameters file.
docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationParameters/Cloud.xml	Removes legacy Service Fabric app parameters file.
docs/site/src/content/docs/deployment/snippets/service-fabric/app/ApplicationPackageRoot/ApplicationManifest.xml	Removes legacy Service Fabric application manifest.
docs/site/src/content/docs/deployment/snippets/consul/Silo/Silo.csproj	Removes legacy Consul snippet project.
docs/site/src/content/docs/deployment/snippets/consul/Silo/Properties/launchSettings.json	Removes legacy Consul snippet launch settings.
docs/site/src/content/docs/deployment/snippets/consul/Silo/Program.cs	Removes legacy Consul snippet program.
docs/site/src/content/docs/deployment/service-fabric.md	Removes legacy Service Fabric hosting guidance page.
docs/site/src/content/docs/deployment/production-readiness.md	Adds a production-readiness checklist page.
docs/site/src/content/docs/deployment/platform-guides.md	Adds platform requirements/guidance page for evaluating hosting platforms.
docs/site/src/content/docs/deployment/networking.md	Adds a topology/networking/clustering page with explicit endpoint guidance.
docs/site/src/content/docs/deployment/index.md	Replaces “Run an Orleans application” with a structured deploy/operate track index.
docs/site/src/content/docs/deployment/includes/deployment/create-service-principal.md	Removes legacy service principal creation include (secrets-based guidance).
docs/site/src/content/docs/deployment/includes/deployment/create-github-secret.md	Removes legacy GitHub secret creation include (secrets-based guidance).
docs/site/src/content/docs/deployment/includes/deployment/create-azure-resources.md	Removes legacy Azure resource group include.
docs/site/src/content/docs/deployment/health-and-observability.md	Adds health/readiness/liveness and observability design guidance.
docs/site/src/content/docs/deployment/disaster-recovery.md	Adds backup/restore/disaster recovery guidance.
docs/site/src/content/docs/deployment/capacity-planning.md	Adds capacity planning and scaling guidance page.
docs/site/src/content/docs/dashboard/snippets/secure-dashboard/SecureDashboard.csproj	Adds a secure dashboard snippet project.
docs/site/src/content/docs/dashboard/snippets/secure-dashboard/Program.cs	Adds secure dashboard configuration example with authn/z and routing.
docs/site/scripts/lib/docfx.mjs	Updates sidebar generation to allow absolute-path links and skip local file validation for them.
docs/site/scripts/generate-legacy-redirects.mjs	Integrates explicit redirects, adds safer output path resolution, and validates redirect targets.
docs/site/scripts/audit-output.mjs	Integrates explicit redirects validation in rendered output audit and adds safer output path resolution.
docs/site/README.md	Documents the new explicit redirect override mechanism.
docs/site/astro.config.mjs	Removes the extra “Reference” sidebar section and relies on toc/sidebar generation instead.

Copilot's findings

• Files reviewed: 126/223 changed files
• Comments generated: 1

[Copilot]

Copilot's findings

Files not reviewed (1)

• docs/site/package-lock.json: Generated file

Suppressed comments (1)

docs/site/src/content/docs/grains/grain-persistence/snippets/persistence/Interfaces.cs:1

• These default interface implementations accept a CancellationToken but ignore it, which can encourage callers to believe cancellation will be honored. If this is intended as a compatibility shim for samples, consider explicitly checking cancellationToken.ThrowIfCancellationRequested() before delegating, or avoid providing token overloads unless the underlying methods can actually observe cancellation.

• Files reviewed: 129/270 changed files
• Comments generated: 0 new

[Copilot]

Copilot's findings

Files not reviewed (1)

• docs/site/package-lock.json: Generated file

• Files reviewed: 124/283 changed files
• Comments generated: 0 new

[Copilot]

Copilot's findings

Files not reviewed (1)

• docs/site/package-lock.json: Generated file

Suppressed comments (1)

docs/site/scripts/generate-legacy-redirects.mjs:82

• The explicit redirect-source validation only checks source.includes('..'), which doesn’t catch encoded traversal (for example, %2e%2e) or other unsafe segments until later (when compatibilityOutputPath is invoked). To ensure consistent safety checks (and clearer error reporting), validate each source by calling compatibilityOutputPath(source, distRoot) inside this loop (and fail with an explicit message) before proceeding.

for (const [source, target] of Object.entries(redirects)) {
  if (!source.startsWith(`${deploymentBase}/`) || source.includes('..')) {
    throw new Error(`Unsafe redirect source '${source}'.`);
  }
  if (!currentRoutes.has(target)) {
    throw new Error(`Redirect target '${target}' for '${source}' is not a current route.`);
  }
}

• Files reviewed: 124/283 changed files
• Comments generated: 0 new

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.