diff --git a/AGENTS.md b/AGENTS.md
index 672750eea..ecb48a3b8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,13 +4,14 @@ Guidance for all coding agents working in this repository (included by CLAUDE.md
 
 ## Agent Context Regions — maintenance rule
 
-Non-trivial source files carry embedded context regions (`#region Purpose`, `#region Design`,
-optionally `#region Open Questions`). These are part of the code, not decoration:
+Every source file carries a `#region Purpose` block (enforced at build time by **TWPA0004**);
+files with design decisions also carry `#region Design`, and optionally `#region Open Questions`.
+These are part of the code, not decoration:
 
 - **When you edit a file that has regions, reconcile them with your change before finishing.**
   A Design region describing the old approach is a bug you just introduced.
-- **When you create a non-trivial source file, add `Purpose` and `Design` regions** at the top,
-  before the namespace.
+- **When you create a source file, add `#region Purpose`** (one honest line minimum) at the top,
+  before the namespace — plus `Design` where there are genuine decisions to record.
 - **When you read an unanswered question in `#region Open Questions` that you can answer,**
   answer it (or implement the answer and remove the pair).
 
diff --git a/kanban/to-do/082-broaden-contract-nullability-analyzer-to-api-grpc-foundation-contracts.md b/kanban/done/082-broaden-contract-nullability-analyzer-to-api-grpc-foundation-contracts.md
similarity index 80%
rename from kanban/to-do/082-broaden-contract-nullability-analyzer-to-api-grpc-foundation-contracts.md
rename to kanban/done/082-broaden-contract-nullability-analyzer-to-api-grpc-foundation-contracts.md
index 75f8d6b10..b16a0f8e3 100644
--- a/kanban/to-do/082-broaden-contract-nullability-analyzer-to-api-grpc-foundation-contracts.md
+++ b/kanban/done/082-broaden-contract-nullability-analyzer-to-api-grpc-foundation-contracts.md
@@ -1,5 +1,14 @@
 # Broaden contract nullability analyzer to api / grpc / foundation contracts
 
+> **CLOSED — ABSORBED BY
+> [[084-convention-analyzer-require-region-purpose-in-every-source-file-rename-assembly-wire-via-directorybuildprops-absorb-082]]
+> (2026-07-02).** The assembly (renamed `timewarp-architecture-convention-analyzers`) is now wired
+> once via `source/Directory.Build.props`, reaching **every** project under `source/` — a superset
+> of this task's scope. The broadened sweep found one real violation
+> (`web-server/configuration/sample-options.cs` — `= string.Empty` + validated `NotEmpty()`),
+> fixed same-axis; api/grpc/foundation contracts were clean. Stretch items (SetValidator
+> composition-following, code-fix provider) remain unpicked — revive as their own tasks if wanted.
+
 ## Description
 
 Task 080 shipped `ContractNullabilityValidatorAnalyzer` (TWPA0002: `string?` + `NotEmpty()`/
diff --git a/kanban/done/084-convention-analyzer-require-region-purpose-in-every-source-file-rename-assembly-wire-via-directorybuildprops-absorb-082.md b/kanban/done/084-convention-analyzer-require-region-purpose-in-every-source-file-rename-assembly-wire-via-directorybuildprops-absorb-082.md
new file mode 100644
index 000000000..9b22a1eec
--- /dev/null
+++ b/kanban/done/084-convention-analyzer-require-region-purpose-in-every-source-file-rename-assembly-wire-via-directorybuildprops-absorb-082.md
@@ -0,0 +1,78 @@
+# Convention analyzer: require `#region Purpose` in every source file (rename assembly, wire via Directory.Build.props, absorb 082)
+
+## Description
+
+Enforcement backstop for the agent-context-regions convention (follow-up to
+[[050-010-add-region-purpose-and-region-design-to-all-migrated-source-files]]), built on the
+080 lesson: a convention nobody enforces decays (regions sat at 4/304 for a year).
+
+**Key design decision (maintainer, 2026-07-02): the rule is UNIVERSAL, not threshold-based.**
+Every compiled `.cs` file requires `#region Purpose` — trivial files get a one-line region
+("Assembly marker enabling typed assembly references.") instead of an exemption. Rationale:
+
+- A "non-trivial file" heuristic (member counts, line thresholds) misclassifies in both
+  directions and pushes complexity into the analyzer + suppressions. A universal rule is
+  **exact**: no threshold to tune, no judgment to encode, no escape hatches to manage.
+- Even trivial files benefit — "why does this AssemblyMarker exist" is a real question a
+  one-line Purpose answers; a dead-code reference file gets "kept as reference for X".
+- Cost is one 3-line insertion per trivial file (~140 files), paid once, mechanical.
+- Generated code is excluded structurally (`GeneratedCodeAnalysisFlags.None`), not by judgment.
+
+`#region Design` is **not** analyzer-enforced: "has design decisions worth recording" cannot be
+judged mechanically. Design stays governed by the AGENTS.md maintenance rule and review.
+
+## Diagnostics
+
+- **TWPA0004** — compiled, non-generated `.cs` file lacks a `#region Purpose` block.
+  Severity Warning (build-breaking under the repo's warnings-as-errors).
+
+## Architecture / wiring (this is the other half of the task)
+
+1. **Rename** `timewarp-architecture-contract-analyzers` → `timewarp-architecture-convention-analyzers`
+   (the assembly now hosts contract rules TWPA0002/0003 *and* repo-wide convention rules; the
+   "contract" name stops fitting). Update: csproj + folder, `.slnx`, test project reference,
+   `web-contracts.csproj` reference (superseded by step 2), AnalyzerReleases files.
+2. **Wire once in `source/Directory.Build.props`** — `<ProjectReference OutputItemType="Analyzer"
+   ReferenceOutputAssembly="false">` with a condition excluding the analyzer/attributes projects
+   themselves (self-reference guard). Remove the now-redundant per-csproj reference in
+   web-contracts. Scope = `source/` only (tests deliberately excluded — a test's why is its name).
+3. **This absorbs [[082-broaden-contract-nullability-analyzer-to-api-grpc-foundation-contracts]]**:
+   TWPA0002/0003 reach api/grpc/foundation contracts through the same wiring (inert in projects
+   without `AbstractValidator` usage). Close 082 into this task.
+4. **Template effect:** generated `dotnet new timewarp-architecture` apps inherit both region and
+   nullability enforcement out of the box.
+
+## Recipe (080-proven: wire + reconcile in the same PR, tree never red)
+
+- [x] `PurposeRegionAnalyzer` (TWPA0004): syntax-tree action; region-name match; generated code
+      excluded via `GeneratedCodeAnalysisFlags.None`; registered in AnalyzerReleases.
+- [x] Fixie tests (5): without = flagged; with = clean; **anywhere-in-file counts** (placement is
+      skill guidance); Design-only still flagged; generated clean. All 21 analyzer tests green.
+- [x] Assembly renamed `timewarp-architecture-convention-analyzers`; wired once in
+      `source/Directory.Build.props` (self-excluded; `IsAspireProjectResource="false"` to keep the
+      Aspire AppHost from treating the analyzer ref as an app resource — ASPIRE004).
+- [x] Backfill: 51 formulaic files scripted (assembly markers, global-usings, identical one-liners);
+      88 small files via 8-agent fan-out (one-line Purpose, Design only where genuine — includes
+      the 050-010 skips: dead-code files now say *why they're kept*). **304/304 coverage.**
+- [x] TWPA0002/0003 broadening caught **one real violation outside web-contracts**:
+      `web-server/configuration/sample-options.cs` `SampleOption = string.Empty` (+ `NotEmpty()`
+      via the options validator) → `= null!`. api/grpc/foundation contracts were clean.
+- [x] `dev build` green (0/0); analyzer 21/21, sourcegen 14/14, web-server integration 11 passed.
+- [x] 082 closed as absorbed; `agent-context-regions` skill updated (universal Purpose, no
+      triviality exemption, TWPA0004 noted) — flow commit `25e288b`, synced.
+
+## Result — analyzer defect found & fixed via the test framework's hidden suppression pass
+
+The testing framework prepends `#pragma warning disable TWPA0004` and verifies the diagnostic
+disappears. The first implementation reported at `TextSpan(0,0)` — a position *before* any leading
+pragma takes effect — making the diagnostic **unsuppressable** (a real defect, not a test
+artifact). Fix: anchor on the file's **first token**; trivia-only files (fully commented out /
+`#if false`) have no active code and are structurally exempt.
+
+## Notes
+
+- Freshness remains out of scope — no tool can verify a region is *true*; that stays with the
+  AGENTS.md reconcile rule and PR review. This analyzer guarantees presence only.
+- Consumers who want the softer stance can downgrade via
+  `dotnet_diagnostic.TWPA0004.severity = suggestion` in `.editorconfig` — document, don't build,
+  the escape hatch.
diff --git a/source/Directory.Build.props b/source/Directory.Build.props
index 6b87517fa..9685dcf34 100644
--- a/source/Directory.Build.props
+++ b/source/Directory.Build.props
@@ -35,5 +35,15 @@
   <ItemGroup Label="Shared Package Assets">
     <None Include="$(RepositoryRoot)assets/logo.png" Pack="true" PackagePath="" />
   </ItemGroup>
-  
+
+  <!-- Repo-wide convention analyzers (analyzer-only assembly — no source generators):
+       TWPA0002/0003 (contract nullability must agree with FluentValidation presence rules) and
+       TWPA0004 (every source file carries a #region Purpose block). Wired once here so every
+       project under source/ — and every app generated from the template — is enforced. -->
+  <ItemGroup Condition="'$(MSBuildProjectName)' != 'timewarp-architecture-convention-analyzers'">
+    <ProjectReference Include="$(MSBuildThisFileDirectory)analyzers/timewarp-architecture-convention-analyzers/timewarp-architecture-convention-analyzers.csproj"
+                      OutputItemType="Analyzer" ReferenceOutputAssembly="false"
+                      IsAspireProjectResource="false" />
+  </ItemGroup>
+
 </Project>
diff --git a/source/analyzers/timewarp-architecture-analyzers/assembly-marker.cs b/source/analyzers/timewarp-architecture-analyzers/assembly-marker.cs
index f5b05dca5..837743b26 100644
--- a/source/analyzers/timewarp-architecture-analyzers/assembly-marker.cs
+++ b/source/analyzers/timewarp-architecture-analyzers/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Analyzers;
 
 /// <summary>
diff --git a/source/analyzers/timewarp-architecture-analyzers/global-usings.cs b/source/analyzers/timewarp-architecture-analyzers/global-usings.cs
index 408d23dd7..864cd527e 100644
--- a/source/analyzers/timewarp-architecture-analyzers/global-usings.cs
+++ b/source/analyzers/timewarp-architecture-analyzers/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Microsoft.CodeAnalysis;
 global using Microsoft.CodeAnalysis.CSharp;
 global using Microsoft.CodeAnalysis.CSharp.Syntax;
diff --git a/source/analyzers/timewarp-architecture-attributes/api-endpoint-attribute.cs b/source/analyzers/timewarp-architecture-attributes/api-endpoint-attribute.cs
index 47e665272..8d5d183e9 100644
--- a/source/analyzers/timewarp-architecture-attributes/api-endpoint-attribute.cs
+++ b/source/analyzers/timewarp-architecture-attributes/api-endpoint-attribute.cs
@@ -1,3 +1,13 @@
+#region Purpose
+// Marks a contract class for FastEndpoint source generation — the generator emits the endpoint class, so none is hand-written.
+#endregion
+
+#region Design
+// Lives in a small runtime-attributes assembly, separate from the analyzer, so contract projects
+// reference plain attributes without taking a Roslyn dependency.
+// EndpointType optionally overrides the generated endpoint's base class (default BaseFastEndpoint).
+#endregion
+
 namespace TimeWarp.Architecture.Attributes;
 
 [AttributeUsage(AttributeTargets.Class, Inherited = false, AllowMultiple = false)]
diff --git a/source/analyzers/timewarp-architecture-attributes/assembly-marker.cs b/source/analyzers/timewarp-architecture-attributes/assembly-marker.cs
index 9361b9ade..6be8e1cb7 100644
--- a/source/analyzers/timewarp-architecture-attributes/assembly-marker.cs
+++ b/source/analyzers/timewarp-architecture-attributes/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Attributes;
 
 /// <summary>
diff --git a/source/analyzers/timewarp-architecture-contract-analyzers/AnalyzerReleases.Shipped.md b/source/analyzers/timewarp-architecture-convention-analyzers/AnalyzerReleases.Shipped.md
similarity index 100%
rename from source/analyzers/timewarp-architecture-contract-analyzers/AnalyzerReleases.Shipped.md
rename to source/analyzers/timewarp-architecture-convention-analyzers/AnalyzerReleases.Shipped.md
diff --git a/source/analyzers/timewarp-architecture-contract-analyzers/AnalyzerReleases.Unshipped.md b/source/analyzers/timewarp-architecture-convention-analyzers/AnalyzerReleases.Unshipped.md
similarity index 83%
rename from source/analyzers/timewarp-architecture-contract-analyzers/AnalyzerReleases.Unshipped.md
rename to source/analyzers/timewarp-architecture-convention-analyzers/AnalyzerReleases.Unshipped.md
index 3b4c69eb9..8e92cb94a 100644
--- a/source/analyzers/timewarp-architecture-contract-analyzers/AnalyzerReleases.Unshipped.md
+++ b/source/analyzers/timewarp-architecture-convention-analyzers/AnalyzerReleases.Unshipped.md
@@ -7,3 +7,4 @@ Rule ID | Category | Severity | Notes
 --------|----------|----------|-------
 TWPA0002 | Design | Warning | ContractNullabilityValidatorAnalyzer: nullable property has a NotEmpty()/NotNull() presence rule
 TWPA0003 | Design | Warning | ContractNullabilityValidatorAnalyzer: required property has a fabricated empty-string default
+TWPA0004 | Documentation | Warning | PurposeRegionAnalyzer: source file lacks a #region Purpose block
diff --git a/source/analyzers/timewarp-architecture-contract-analyzers/contract-nullability-validator-analyzer.cs b/source/analyzers/timewarp-architecture-convention-analyzers/contract-nullability-validator-analyzer.cs
similarity index 100%
rename from source/analyzers/timewarp-architecture-contract-analyzers/contract-nullability-validator-analyzer.cs
rename to source/analyzers/timewarp-architecture-convention-analyzers/contract-nullability-validator-analyzer.cs
diff --git a/source/analyzers/timewarp-architecture-contract-analyzers/global-usings.cs b/source/analyzers/timewarp-architecture-convention-analyzers/global-usings.cs
similarity index 62%
rename from source/analyzers/timewarp-architecture-contract-analyzers/global-usings.cs
rename to source/analyzers/timewarp-architecture-convention-analyzers/global-usings.cs
index e686c673d..e4db51714 100644
--- a/source/analyzers/timewarp-architecture-contract-analyzers/global-usings.cs
+++ b/source/analyzers/timewarp-architecture-convention-analyzers/global-usings.cs
@@ -1,6 +1,12 @@
+#region Purpose
+// Global usings for the convention-analyzers assembly.
+#endregion
+
 global using Microsoft.CodeAnalysis;
 global using Microsoft.CodeAnalysis.CSharp;
 global using Microsoft.CodeAnalysis.CSharp.Syntax;
 global using Microsoft.CodeAnalysis.Diagnostics;
+global using Microsoft.CodeAnalysis.Text;
 global using System.Collections.Immutable;
+global using System.IO;
 global using System.Linq;
diff --git a/source/analyzers/timewarp-architecture-convention-analyzers/purpose-region-analyzer.cs b/source/analyzers/timewarp-architecture-convention-analyzers/purpose-region-analyzer.cs
new file mode 100644
index 000000000..f901a170b
--- /dev/null
+++ b/source/analyzers/timewarp-architecture-convention-analyzers/purpose-region-analyzer.cs
@@ -0,0 +1,72 @@
+#region Purpose
+// Enforces the agent-context-regions convention: every source file carries a #region Purpose block.
+#endregion
+
+#region Design
+// The rule is deliberately UNIVERSAL rather than "non-trivial files only": any triviality
+// heuristic (member counts, line thresholds) misclassifies in both directions and pushes
+// complexity into suppressions. Trivial files satisfy the rule with a one-line Purpose instead
+// of an exemption, so the check needs no judgment. Generated code is excluded structurally via
+// GeneratedCodeAnalysisFlags.None (auto-generated headers, *.g.cs), not by heuristic.
+// A #region Design block is intentionally NOT enforced — "has decisions worth recording" cannot
+// be judged mechanically; that half of the convention is governed by AGENTS.md and review.
+// Placement anywhere in the file counts: position is skill guidance, not analyzer scope.
+#endregion
+
+namespace TimeWarp.Architecture.Analyzers;
+
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public class PurposeRegionAnalyzer : DiagnosticAnalyzer
+{
+  public const string DiagnosticId = "TWPA0004";
+
+  private static readonly DiagnosticDescriptor Rule =
+    new
+    (
+      DiagnosticId,
+      title: "Source file lacks a #region Purpose block",
+      messageFormat: "File '{0}' has no '#region Purpose' block; add one (a single // line suffices) stating what the file is for",
+      category: "Documentation",
+      DiagnosticSeverity.Warning,
+      isEnabledByDefault: true,
+      description: "Every source file embeds agent/human context in a '#region Purpose' block. Trivial files use a one-line Purpose rather than being exempt. See the agent-context-regions skill."
+    );
+
+  public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics => ImmutableArray.Create(Rule);
+
+  public override void Initialize(AnalysisContext context)
+  {
+    context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+    context.EnableConcurrentExecution();
+    context.RegisterSyntaxTreeAction(AnalyzeTree);
+  }
+
+  private static void AnalyzeTree(SyntaxTreeAnalysisContext context)
+  {
+    SyntaxNode root = context.Tree.GetRoot(context.CancellationToken);
+
+    bool hasPurposeRegion = root
+      .DescendantNodes(descendIntoTrivia: true)
+      .OfType<RegionDirectiveTriviaSyntax>()
+      .Any(static region => RegionName(region) == "Purpose");
+
+    if (hasPurposeRegion) return;
+
+    // Anchor on the first token (not position 0): a diagnostic located before a leading
+    // `#pragma warning disable` could never be suppressed by it. Trivia-only files (fully
+    // commented out / #if false) have no active code and are not flagged.
+    SyntaxToken firstToken = root.GetFirstToken();
+    if (firstToken.RawKind == 0) return;
+
+    string fileName = Path.GetFileName(context.Tree.FilePath);
+    context.ReportDiagnostic(Diagnostic.Create(Rule, firstToken.GetLocation(), fileName));
+  }
+
+  // "#region Purpose" -> "Purpose" (the name rides in the directive's trailing preprocessing message).
+  private static string RegionName(RegionDirectiveTriviaSyntax region)
+  {
+    string text = region.ToString();
+    int keywordEnd = text.IndexOf("#region", System.StringComparison.Ordinal);
+    return keywordEnd < 0 ? string.Empty : text.Substring(keywordEnd + "#region".Length).Trim();
+  }
+}
diff --git a/source/analyzers/timewarp-architecture-contract-analyzers/timewarp-architecture-contract-analyzers.csproj b/source/analyzers/timewarp-architecture-convention-analyzers/timewarp-architecture-convention-analyzers.csproj
similarity index 81%
rename from source/analyzers/timewarp-architecture-contract-analyzers/timewarp-architecture-contract-analyzers.csproj
rename to source/analyzers/timewarp-architecture-convention-analyzers/timewarp-architecture-convention-analyzers.csproj
index 90fc1e330..ba12a0385 100644
--- a/source/analyzers/timewarp-architecture-contract-analyzers/timewarp-architecture-contract-analyzers.csproj
+++ b/source/analyzers/timewarp-architecture-convention-analyzers/timewarp-architecture-convention-analyzers.csproj
@@ -3,7 +3,8 @@
     <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
     <IsRoslynComponent>true</IsRoslynComponent>
     <!-- Convention-enforcement DiagnosticAnalyzers only (no source generators), so this assembly is
-         safe to reference from contract projects without triggering the FastEndpoint generator. -->
+         safe to reference from every project — including contracts — without triggering the
+         FastEndpoint generator. Wired repo-wide via source/Directory.Build.props. -->
     <!-- Suppress RS1041: Analyzer intentionally targets net10.0 for CLI usage -->
     <!-- Suppress CA1031: Analyzers must be resilient and catch general exceptions -->
     <!-- Suppress CA1062: Roslyn framework guarantees non-null analysis-context parameters -->
diff --git a/source/container-apps/api/api-application/api-application-module.cs b/source/container-apps/api/api-application/api-application-module.cs
index a98b9f939..cb0640877 100644
--- a/source/container-apps/api/api-application/api-application-module.cs
+++ b/source/container-apps/api/api-application/api-application-module.cs
@@ -1,3 +1,13 @@
+#region Purpose
+// IModule registration hook for the Api application layer's services.
+#endregion
+
+#region Design
+// ConfigureServices deliberately throws: the layer has no services to register, and the throw
+// makes accidental composition loud instead of silently succeeding. Replace the throw with real
+// registrations when the layer gains services.
+#endregion
+
 namespace TimeWarp.Architecture.Api.Application;
 
 public class ApiApplicationModule : IModule
diff --git a/source/container-apps/api/api-application/assembly-marker.cs b/source/container-apps/api/api-application/assembly-marker.cs
index c04adb60a..e325a64eb 100644
--- a/source/container-apps/api/api-application/assembly-marker.cs
+++ b/source/container-apps/api/api-application/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Api.Application;
 
 /// <summary>
diff --git a/source/container-apps/api/api-application/global-usings.cs b/source/container-apps/api/api-application/global-usings.cs
index 6b9611f83..a433cbe4a 100644
--- a/source/container-apps/api/api-application/global-usings.cs
+++ b/source/container-apps/api/api-application/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Microsoft.Extensions.Configuration;
 global using Microsoft.Extensions.DependencyInjection;
 global using OneOf;
diff --git a/source/container-apps/api/api-contracts/assembly-marker.cs b/source/container-apps/api/api-contracts/assembly-marker.cs
index 5baa15b4d..282afa811 100644
--- a/source/container-apps/api/api-contracts/assembly-marker.cs
+++ b/source/container-apps/api/api-contracts/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Api.Contracts;
 
 /// <summary>
diff --git a/source/container-apps/api/api-contracts/features/weather-forecast/feature-annotations.cs b/source/container-apps/api/api-contracts/features/weather-forecast/feature-annotations.cs
index 12e3ac820..b51927a98 100644
--- a/source/container-apps/api/api-contracts/features/weather-forecast/feature-annotations.cs
+++ b/source/container-apps/api/api-contracts/features/weather-forecast/feature-annotations.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Per-feature constants slot: FeatureGroup names the WeatherForecast group used to categorize its endpoints in API metadata.
+#endregion
+
 namespace TimeWarp.Architecture.Features.WeatherForecasts;
 
 public static class FeatureAnnotations
diff --git a/source/container-apps/api/api-contracts/global-usings.cs b/source/container-apps/api/api-contracts/global-usings.cs
index d8497e249..edce01559 100644
--- a/source/container-apps/api/api-contracts/global-usings.cs
+++ b/source/container-apps/api/api-contracts/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Ardalis.GuardClauses;
 global using FluentValidation;
 global using OneOf;
diff --git a/source/container-apps/api/api-domain/assembly-marker.cs b/source/container-apps/api/api-domain/assembly-marker.cs
index 7636084ea..97303dae7 100644
--- a/source/container-apps/api/api-domain/assembly-marker.cs
+++ b/source/container-apps/api/api-domain/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Api.Domain;
 
 /// <summary>
diff --git a/source/container-apps/api/api-domain/global-usings.cs b/source/container-apps/api/api-domain/global-usings.cs
index d2434d2b3..9ae16c421 100644
--- a/source/container-apps/api/api-domain/global-usings.cs
+++ b/source/container-apps/api/api-domain/global-usings.cs
@@ -1 +1,5 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 // global using xyz;
diff --git a/source/container-apps/api/api-infrastructure/assembly-marker.cs b/source/container-apps/api/api-infrastructure/assembly-marker.cs
index d3e55111b..e59d1b6fb 100644
--- a/source/container-apps/api/api-infrastructure/assembly-marker.cs
+++ b/source/container-apps/api/api-infrastructure/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Api.Infrastructure;
 
 /// <summary>
diff --git a/source/container-apps/api/api-infrastructure/global-usings.cs b/source/container-apps/api/api-infrastructure/global-usings.cs
index d2434d2b3..9ae16c421 100644
--- a/source/container-apps/api/api-infrastructure/global-usings.cs
+++ b/source/container-apps/api/api-infrastructure/global-usings.cs
@@ -1 +1,5 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 // global using xyz;
diff --git a/source/container-apps/api/api-server/assembly-marker.cs b/source/container-apps/api/api-server/assembly-marker.cs
index 409aef6fb..db941d68b 100644
--- a/source/container-apps/api/api-server/assembly-marker.cs
+++ b/source/container-apps/api/api-server/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Api.Server;
 
 /// <summary>
diff --git a/source/container-apps/api/api-server/features/base/base-error.cs b/source/container-apps/api/api-server/features/base/base-error.cs
index d71a14111..2c405a61a 100644
--- a/source/container-apps/api/api-server/features/base/base-error.cs
+++ b/source/container-apps/api/api-server/features/base/base-error.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Base message-bearing error type for Api server features; a convention anchor with no derived types in the template.
+#endregion
+
 namespace TimeWarp.Architecture.Features;
 
 public class BaseError
diff --git a/source/container-apps/api/api-server/features/base/base-exception.cs b/source/container-apps/api/api-server/features/base/base-exception.cs
index 1444612cb..05b026e8a 100644
--- a/source/container-apps/api/api-server/features/base/base-exception.cs
+++ b/source/container-apps/api/api-server/features/base/base-exception.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Base exception type for Api server feature failures; a convention anchor with no derived types in the template.
+#endregion
+
 namespace TimeWarp.Architecture.Features;
 
 public class BaseException : Exception
diff --git a/source/container-apps/api/api-server/global-usings.cs b/source/container-apps/api/api-server/global-usings.cs
index 6e7fbf713..9b7b3f977 100644
--- a/source/container-apps/api/api-server/global-usings.cs
+++ b/source/container-apps/api/api-server/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using FastEndpoints;
 global using FluentValidation;
 global using Microsoft.AspNetCore.Mvc;
diff --git a/source/container-apps/aspire/aspire-app-host/constants.cs b/source/container-apps/aspire/aspire-app-host/constants.cs
index 47462339a..78f443004 100644
--- a/source/container-apps/aspire/aspire-app-host/constants.cs
+++ b/source/container-apps/aspire/aspire-app-host/constants.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Aspire AppHost resource names, pinned to the ServiceNames the apps use for service discovery.
+#endregion
+
 namespace TimeWarp.Architecture.Aspire;
 
 internal class Constants
diff --git a/source/container-apps/aspire/aspire-app-host/global-usings.cs b/source/container-apps/aspire/aspire-app-host/global-usings.cs
index 79067e233..6a46cf798 100644
--- a/source/container-apps/aspire/aspire-app-host/global-usings.cs
+++ b/source/container-apps/aspire/aspire-app-host/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Aspire.Customization.AppHost;
 global using Aspire.Hosting.Yarp;
 global using Aspire.Hosting.Yarp.Transforms;
diff --git a/source/container-apps/aspire/aspire-service-defaults/global-usings.cs b/source/container-apps/aspire/aspire-service-defaults/global-usings.cs
index 2de17d97c..d7cda22c1 100644
--- a/source/container-apps/aspire/aspire-service-defaults/global-usings.cs
+++ b/source/container-apps/aspire/aspire-service-defaults/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Microsoft.AspNetCore.Builder;
 global using Microsoft.AspNetCore.Diagnostics.HealthChecks;
 global using Microsoft.Extensions.DependencyInjection;
diff --git a/source/container-apps/grpc/grpc-application/assembly-marker.cs b/source/container-apps/grpc/grpc-application/assembly-marker.cs
index 054000514..41d70dcf8 100644
--- a/source/container-apps/grpc/grpc-application/assembly-marker.cs
+++ b/source/container-apps/grpc/grpc-application/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Grpc.Application;
 
 /// <summary>
diff --git a/source/container-apps/grpc/grpc-application/global-usings.cs b/source/container-apps/grpc/grpc-application/global-usings.cs
index e7cf32471..d58960740 100644
--- a/source/container-apps/grpc/grpc-application/global-usings.cs
+++ b/source/container-apps/grpc/grpc-application/global-usings.cs
@@ -1 +1,5 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using TimeWarp.Mediator;
diff --git a/source/container-apps/grpc/grpc-contracts/assembly-marker.cs b/source/container-apps/grpc/grpc-contracts/assembly-marker.cs
index 3b30cede4..2bccb8cf3 100644
--- a/source/container-apps/grpc/grpc-contracts/assembly-marker.cs
+++ b/source/container-apps/grpc/grpc-contracts/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Grpc.Contracts;
 
 /// <summary>
diff --git a/source/container-apps/grpc/grpc-contracts/features/hello/hello-request.cs b/source/container-apps/grpc/grpc-contracts/features/hello/hello-request.cs
index c8b46bbef..6d2d0b8e4 100644
--- a/source/container-apps/grpc/grpc-contracts/features/hello/hello-request.cs
+++ b/source/container-apps/grpc/grpc-contracts/features/hello/hello-request.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-first gRPC request for the Hello sample; DataContract member ordering defines the wire shape in place of a .proto file.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Hellos;
 
 [DataContract]
diff --git a/source/container-apps/grpc/grpc-contracts/features/hello/hello-response.cs b/source/container-apps/grpc/grpc-contracts/features/hello/hello-response.cs
index 669987a43..bd497c96b 100644
--- a/source/container-apps/grpc/grpc-contracts/features/hello/hello-response.cs
+++ b/source/container-apps/grpc/grpc-contracts/features/hello/hello-response.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-first gRPC response carrying the Hello sample's greeting back to the caller.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Hellos;
 
 [DataContract]
diff --git a/source/container-apps/grpc/grpc-contracts/features/hello/i-hello-service.cs b/source/container-apps/grpc/grpc-contracts/features/hello/i-hello-service.cs
index 2ece8f132..4779da192 100644
--- a/source/container-apps/grpc/grpc-contracts/features/hello/i-hello-service.cs
+++ b/source/container-apps/grpc/grpc-contracts/features/hello/i-hello-service.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-first gRPC service contract for the Hello sample; server and clients bind to this shared interface, so no .proto file exists.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Hellos;
 
 [ServiceContract]
diff --git a/source/container-apps/grpc/grpc-contracts/features/superhero/superhero-request.cs b/source/container-apps/grpc/grpc-contracts/features/superhero/superhero-request.cs
index d7490c7aa..4f542e0b7 100644
--- a/source/container-apps/grpc/grpc-contracts/features/superhero/superhero-request.cs
+++ b/source/container-apps/grpc/grpc-contracts/features/superhero/superhero-request.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-first gRPC request asking the demo superhero service for a batch of fabricated heroes.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Superheros;
 
 [ProtoContract]
diff --git a/source/container-apps/grpc/grpc-contracts/features/superhero/superhero-response.cs b/source/container-apps/grpc/grpc-contracts/features/superhero/superhero-response.cs
index 2f5c51eac..732f11842 100644
--- a/source/container-apps/grpc/grpc-contracts/features/superhero/superhero-response.cs
+++ b/source/container-apps/grpc/grpc-contracts/features/superhero/superhero-response.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-first gRPC response carrying the fabricated superhero batch back to the client.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Superheros;
 
 [ProtoContract]
diff --git a/source/container-apps/grpc/grpc-contracts/global-usings.cs b/source/container-apps/grpc/grpc-contracts/global-usings.cs
index 28085f937..4fef0e0b2 100644
--- a/source/container-apps/grpc/grpc-contracts/global-usings.cs
+++ b/source/container-apps/grpc/grpc-contracts/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Grpc.Core;
 global using ProtoBuf;
 global using ProtoBuf.Grpc;
diff --git a/source/container-apps/grpc/grpc-domain/assembly-marker.cs b/source/container-apps/grpc/grpc-domain/assembly-marker.cs
index 342721c2f..596f8f751 100644
--- a/source/container-apps/grpc/grpc-domain/assembly-marker.cs
+++ b/source/container-apps/grpc/grpc-domain/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Grpc.Domain;
 
 /// <summary>
diff --git a/source/container-apps/grpc/grpc-domain/global-usings.cs b/source/container-apps/grpc/grpc-domain/global-usings.cs
index d2434d2b3..9ae16c421 100644
--- a/source/container-apps/grpc/grpc-domain/global-usings.cs
+++ b/source/container-apps/grpc/grpc-domain/global-usings.cs
@@ -1 +1,5 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 // global using xyz;
diff --git a/source/container-apps/grpc/grpc-infrastructure/assembly-marker.cs b/source/container-apps/grpc/grpc-infrastructure/assembly-marker.cs
index 11a5a1a53..b92ba0661 100644
--- a/source/container-apps/grpc/grpc-infrastructure/assembly-marker.cs
+++ b/source/container-apps/grpc/grpc-infrastructure/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Grpc.Infrastructure;
 
 /// <summary>
diff --git a/source/container-apps/grpc/grpc-infrastructure/global-usings.cs b/source/container-apps/grpc/grpc-infrastructure/global-usings.cs
index d2434d2b3..9ae16c421 100644
--- a/source/container-apps/grpc/grpc-infrastructure/global-usings.cs
+++ b/source/container-apps/grpc/grpc-infrastructure/global-usings.cs
@@ -1 +1,5 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 // global using xyz;
diff --git a/source/container-apps/grpc/grpc-server/assembly-marker.cs b/source/container-apps/grpc/grpc-server/assembly-marker.cs
index 8899a877f..80562ee52 100644
--- a/source/container-apps/grpc/grpc-server/assembly-marker.cs
+++ b/source/container-apps/grpc/grpc-server/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Grpc.Server;
 
 /// <summary>
diff --git a/source/container-apps/grpc/grpc-server/features/hello/hello-service.cs b/source/container-apps/grpc/grpc-server/features/hello/hello-service.cs
index 8212c15c9..714ec3814 100644
--- a/source/container-apps/grpc/grpc-server/features/hello/hello-service.cs
+++ b/source/container-apps/grpc/grpc-server/features/hello/hello-service.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Server implementation of the code-first IHelloService gRPC contract — the sample showing how Grpc.Server fulfills contracts defined in Grpc.Contracts.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Hellos;
 
 public class HelloService : IHelloService
diff --git a/source/container-apps/grpc/grpc-server/global-usings.cs b/source/container-apps/grpc/grpc-server/global-usings.cs
index 620079c60..dbc863118 100644
--- a/source/container-apps/grpc/grpc-server/global-usings.cs
+++ b/source/container-apps/grpc/grpc-server/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Grpc.Core;
 global using ProtoBuf.Grpc;
 global using ProtoBuf.Grpc.Server;
diff --git a/source/container-apps/grpc/grpc-server/services/greeter-service.cs b/source/container-apps/grpc/grpc-server/services/greeter-service.cs
index 34d3ff2ea..e6b3b23d3 100644
--- a/source/container-apps/grpc/grpc-server/services/greeter-service.cs
+++ b/source/container-apps/grpc/grpc-server/services/greeter-service.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Proto-first gRPC sample: implements the .proto-generated Greeter service, contrasting with the code-first HelloService.
+#endregion
+
 namespace TimeWarp.Architecture.GrpcServer.Services;
 
 public class GreeterService : Greeter.GreeterBase
diff --git a/source/container-apps/web/web-application/assembly-marker.cs b/source/container-apps/web/web-application/assembly-marker.cs
index 8c8586215..ea7ecf0a3 100644
--- a/source/container-apps/web/web-application/assembly-marker.cs
+++ b/source/container-apps/web/web-application/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Web.Application;
 
 /// <summary>
diff --git a/source/container-apps/web/web-application/global-usings.cs b/source/container-apps/web/web-application/global-usings.cs
index d4530ea83..2baad417f 100644
--- a/source/container-apps/web/web-application/global-usings.cs
+++ b/source/container-apps/web/web-application/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Microsoft.Extensions.Logging;
 global using OneOf;
 global using OneOf.Types;
diff --git a/source/container-apps/web/web-contracts/assembly-marker.cs b/source/container-apps/web/web-contracts/assembly-marker.cs
index 6c08c37a4..162efa7cf 100644
--- a/source/container-apps/web/web-contracts/assembly-marker.cs
+++ b/source/container-apps/web/web-contracts/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Web.Contracts;
 
 /// <summary>
diff --git a/source/container-apps/web/web-contracts/extensions/assembly-extensions.cs b/source/container-apps/web/web-contracts/extensions/assembly-extensions.cs
index e8342dadd..eb27d36e1 100644
--- a/source/container-apps/web/web-contracts/extensions/assembly-extensions.cs
+++ b/source/container-apps/web/web-contracts/extensions/assembly-extensions.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Reflection helper for discovering types in an assembly by attribute, used to register contracts without hand-maintained lists.
+#endregion
+
 namespace TimeWarp.Architecture.Extensions;
 
 public static class AssemblyExtensions
diff --git a/source/container-apps/web/web-contracts/features/admin/users/user-ids.cs b/source/container-apps/web/web-contracts/features/admin/users/user-ids.cs
index c611677b6..18fe0b72f 100644
--- a/source/container-apps/web/web-contracts/features/admin/users/user-ids.cs
+++ b/source/container-apps/web/web-contracts/features/admin/users/user-ids.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Well-known user ids so seed data, mocks, and contract handlers all reference the same sample identities.
+#endregion
+
 namespace TimeWarp.Architecture.Services;
 
 public static class UserIds
diff --git a/source/container-apps/web/web-contracts/features/infrastructure/internals-visible-to-client-and-server.cs b/source/container-apps/web/web-contracts/features/infrastructure/internals-visible-to-client-and-server.cs
index 540bd4c7b..baffcccc3 100644
--- a/source/container-apps/web/web-contracts/features/infrastructure/internals-visible-to-client-and-server.cs
+++ b/source/container-apps/web/web-contracts/features/infrastructure/internals-visible-to-client-and-server.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Grants Web.Contracts internal visibility to the SPA, the server, and their integration tests so contract internals stay inside the web boundary.
+#endregion
+
 [assembly: InternalsVisibleTo("Web.Spa")]
 [assembly: InternalsVisibleTo("Web.Spa.Integration.Tests")]
 [assembly: InternalsVisibleTo("Web.Server")]
diff --git a/source/container-apps/web/web-contracts/features/todo-items/queries/get-todo-item-by-id.cs b/source/container-apps/web/web-contracts/features/todo-items/queries/get-todo-item-by-id.cs
index 99e1a6ed5..0def05e11 100644
--- a/source/container-apps/web/web-contracts/features/todo-items/queries/get-todo-item-by-id.cs
+++ b/source/container-apps/web/web-contracts/features/todo-items/queries/get-todo-item-by-id.cs
@@ -1,3 +1,12 @@
+#region Purpose
+// Endpoint-centric wrapper for the get-todo-item-by-id query contract.
+#endregion
+
+#region Design
+// Deliberately empty stub: it reserves the wrapper name so the nested Query, Response, and Validator
+// can be added when the endpoint is built. See CreateTodoItem for the completed shape.
+#endregion
+
 namespace TimeWarp.Architecture.Features.TodoItems;
 
 public sealed partial class GetTodoItemById
diff --git a/source/container-apps/web/web-contracts/features/todo-items/queries/search-todo-items.cs b/source/container-apps/web/web-contracts/features/todo-items/queries/search-todo-items.cs
index 125c566ed..c85ebbccc 100644
--- a/source/container-apps/web/web-contracts/features/todo-items/queries/search-todo-items.cs
+++ b/source/container-apps/web/web-contracts/features/todo-items/queries/search-todo-items.cs
@@ -1,3 +1,12 @@
+#region Purpose
+// Endpoint-centric wrapper for the search-todo-items query contract.
+#endregion
+
+#region Design
+// Deliberately empty stub: it reserves the wrapper name so the nested Query, Response, and Validator
+// can be added when the endpoint is built. See CreateTodoItem for the completed shape.
+#endregion
+
 namespace TimeWarp.Architecture.Features.TodoItems;
 
 public sealed partial class SearchTodoItems
diff --git a/source/container-apps/web/web-contracts/global-usings.cs b/source/container-apps/web/web-contracts/global-usings.cs
index b89726ff1..8b5e580c8 100644
--- a/source/container-apps/web/web-contracts/global-usings.cs
+++ b/source/container-apps/web/web-contracts/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Ardalis.GuardClauses;
 global using FluentValidation;
 global using OneOf;
diff --git a/source/container-apps/web/web-contracts/types/signal-r-result.cs b/source/container-apps/web/web-contracts/types/signal-r-result.cs
index 50bcf6855..40af45ebb 100644
--- a/source/container-apps/web/web-contracts/types/signal-r-result.cs
+++ b/source/container-apps/web/web-contracts/types/signal-r-result.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Serializable success/failure envelope for SignalR hub method returns, because OneOf discriminated unions do not survive SignalR serialization.
+#endregion
+
 namespace TimeWarp.Architecture.Types;
 
 public sealed class SignalrResult<TSuccess, TFailure>
diff --git a/source/container-apps/web/web-contracts/web-contracts.csproj b/source/container-apps/web/web-contracts/web-contracts.csproj
index 470a59f01..52dfa9788 100644
--- a/source/container-apps/web/web-contracts/web-contracts.csproj
+++ b/source/container-apps/web/web-contracts/web-contracts.csproj
@@ -32,13 +32,6 @@
                       Condition="'$(UseFoundationPackages)' != 'true'" />
   </ItemGroup>
 
-  <ItemGroup>
-    <!-- Convention analyzers (TWPA0002/0003: property nullability must agree with FluentValidation
-         presence rules). Analyzer-only assembly, so no source generators run here. -->
-    <ProjectReference Include="..\..\..\analyzers\timewarp-architecture-contract-analyzers\timewarp-architecture-contract-analyzers.csproj"
-                      OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
-  </ItemGroup>
-
   <ItemGroup>
     <Folder Include="features\auth\commands\"/>
   </ItemGroup>
diff --git a/source/container-apps/web/web-domain/abstractions/i-invariants.cs b/source/container-apps/web/web-domain/abstractions/i-invariants.cs
index aa41b145c..871026860 100644
--- a/source/container-apps/web/web-domain/abstractions/i-invariants.cs
+++ b/source/container-apps/web/web-domain/abstractions/i-invariants.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker interface tagging domain invariant rule sets (the nested AbstractValidator classes on entities) so they are identifiable as invariants rather than request validators.
+#endregion
+
 namespace TimeWarp.Architecture.Abstractions;
 
 /// <summary>
diff --git a/source/container-apps/web/web-domain/aggregates/catalog/category.cs b/source/container-apps/web/web-domain/aggregates/catalog/category.cs
index 2689f1568..42c7ecf12 100644
--- a/source/container-apps/web/web-domain/aggregates/catalog/category.cs
+++ b/source/container-apps/web/web-domain/aggregates/catalog/category.cs
@@ -1,3 +1,12 @@
+#region Purpose
+// Commented-out Category entity sketch (nopCommerce-derived) kept as reference for a future catalog aggregate.
+#endregion
+
+#region Design
+// Beyond the property list, the sketch records the intended pattern for entity invariants:
+// a nested Invariants : AbstractValidator<Category> class tagged with IInvariants.
+#endregion
+
 //namespace TimeWarp.Architecture.Entities.Catalog;
 
 //using FluentValidation;
diff --git a/source/container-apps/web/web-domain/aggregates/catalog/product.cs b/source/container-apps/web/web-domain/aggregates/catalog/product.cs
index 56cdbe0b5..ff4e848a2 100644
--- a/source/container-apps/web/web-domain/aggregates/catalog/product.cs
+++ b/source/container-apps/web/web-domain/aggregates/catalog/product.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Commented-out Product entity sketch (nopCommerce-derived) kept as reference for a future catalog aggregate.
+#endregion
+
 //namespace TimeWarp.Architecture.Entities.Catalog;
 
 //using System;
diff --git a/source/container-apps/web/web-domain/assembly-marker.cs b/source/container-apps/web/web-domain/assembly-marker.cs
index 717e1390d..c6c6d596e 100644
--- a/source/container-apps/web/web-domain/assembly-marker.cs
+++ b/source/container-apps/web/web-domain/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Web.Domain;
 
 /// <summary>
diff --git a/source/container-apps/web/web-domain/global-usings.cs b/source/container-apps/web/web-domain/global-usings.cs
index 7bc18aca4..e91d3dba4 100644
--- a/source/container-apps/web/web-domain/global-usings.cs
+++ b/source/container-apps/web/web-domain/global-usings.cs
@@ -1 +1,5 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using TimeWarp.Foundation.Entities;
diff --git a/source/container-apps/web/web-infrastructure/assembly-marker.cs b/source/container-apps/web/web-infrastructure/assembly-marker.cs
index 4ee22a478..acb47ff12 100644
--- a/source/container-apps/web/web-infrastructure/assembly-marker.cs
+++ b/source/container-apps/web/web-infrastructure/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Web.Infrastructure;
 
 /// <summary>
diff --git a/source/container-apps/web/web-infrastructure/configuration/postgres-db-options.cs b/source/container-apps/web/web-infrastructure/configuration/postgres-db-options.cs
index 96a9f0ff7..1844ae475 100644
--- a/source/container-apps/web/web-infrastructure/configuration/postgres-db-options.cs
+++ b/source/container-apps/web/web-infrastructure/configuration/postgres-db-options.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Binds the PostgreSQL connection string from configuration for PostgresDbModule and the Postgres environment check.
+#endregion
+
 namespace TimeWarp.Architecture.Configuration;
 
 public sealed partial class PostgresDbOptions
diff --git a/source/container-apps/web/web-infrastructure/global-usings.cs b/source/container-apps/web/web-infrastructure/global-usings.cs
index 2077128ab..33697c5f8 100644
--- a/source/container-apps/web/web-infrastructure/global-usings.cs
+++ b/source/container-apps/web/web-infrastructure/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using FluentValidation;
 global using Microsoft.EntityFrameworkCore;
 global using Microsoft.EntityFrameworkCore.Metadata.Builders;
diff --git a/source/container-apps/web/web-infrastructure/persistence/postgres-db-context.cs b/source/container-apps/web/web-infrastructure/persistence/postgres-db-context.cs
index bf574c63f..767a0f943 100644
--- a/source/container-apps/web/web-infrastructure/persistence/postgres-db-context.cs
+++ b/source/container-apps/web/web-infrastructure/persistence/postgres-db-context.cs
@@ -1,3 +1,14 @@
+#region Purpose
+// EF Core context for the PostgreSQL store; the seam where template consumers add their entity sets.
+#endregion
+
+#region Design
+// Deliberately entity-free: the template ships the Postgres plumbing (module, health and
+// environment checks, schema-creation hosted service) and leaves the model to the consumer.
+// Connection setup lives in PostgresDbModule.ConfigurePostgresDb, not OnConfiguring, so the
+// context stays configuration-agnostic.
+#endregion
+
 namespace TimeWarp.Architecture.Persistence;
 
 public sealed partial class PostgresDbContext : DbContext { }
diff --git a/source/container-apps/web/web-infrastructure/persistence/sql-db-context.cs b/source/container-apps/web/web-infrastructure/persistence/sql-db-context.cs
index b8f796b79..cc04a79ee 100644
--- a/source/container-apps/web/web-infrastructure/persistence/sql-db-context.cs
+++ b/source/container-apps/web/web-infrastructure/persistence/sql-db-context.cs
@@ -1,3 +1,12 @@
+#region Purpose
+// Placeholder EF Core context marking the seam for a SQL Server storage option alongside Postgres.
+#endregion
+
+#region Design
+// Unregistered dead code kept as reference: its only mention is a commented-out
+// AddDbContextCheck line in Web.Server's Program, showing where SQL Server wiring would go.
+#endregion
+
 namespace TimeWarp.Architecture.Data;
 
 public class SqlDbContext : DbContext { }
diff --git a/source/container-apps/web/web-infrastructure/web-infrastructure-module.cs b/source/container-apps/web/web-infrastructure/web-infrastructure-module.cs
index 258c0e9ef..71b3ef9ca 100644
--- a/source/container-apps/web/web-infrastructure/web-infrastructure-module.cs
+++ b/source/container-apps/web/web-infrastructure/web-infrastructure-module.cs
@@ -1,3 +1,13 @@
+#region Purpose
+// DI registration hook for the Web.Infrastructure assembly, called unconditionally from Web.Server's Program.
+#endregion
+
+#region Design
+// Empty by design: Postgres wiring lives in Web.Server's PostgresDbModule behind the
+// `postgres` feature flag, so this module is the seam for flag-independent infrastructure
+// services only.
+#endregion
+
 namespace TimeWarp.Architecture.Web.Infrastructure;
 
 public class WebInfrastructureModule : IModule
diff --git a/source/container-apps/web/web-server/assembly-marker.cs b/source/container-apps/web/web-server/assembly-marker.cs
index 4a93bc36a..2560eeda2 100644
--- a/source/container-apps/web/web-server/assembly-marker.cs
+++ b/source/container-apps/web/web-server/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Web.Server;
 
 /// <summary>
diff --git a/source/container-apps/web/web-server/configuration/sample-options.cs b/source/container-apps/web/web-server/configuration/sample-options.cs
index 65a455ecd..879f00e75 100644
--- a/source/container-apps/web/web-server/configuration/sample-options.cs
+++ b/source/container-apps/web/web-server/configuration/sample-options.cs
@@ -1,6 +1,10 @@
+#region Purpose
+// Example options class demonstrating the AddFluentValidatedOptions binding-plus-validation pattern.
+#endregion
+
 namespace TimeWarp.Architecture.Configuration;
 
 public class SampleOptions
 {
-  public string SampleOption { get; set; } = string.Empty;
+  public string SampleOption { get; set; } = null!;
 }
diff --git a/source/container-apps/web/web-server/features/analytics/feature-annotations.cs b/source/container-apps/web/web-server/features/analytics/feature-annotations.cs
index 166164105..2a401150f 100644
--- a/source/container-apps/web/web-server/features/analytics/feature-annotations.cs
+++ b/source/container-apps/web/web-server/features/analytics/feature-annotations.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Names the Analytics feature group as a constant for tagging its endpoints in API metadata; no code consumes it.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Analytics;
 
 public static class FeatureAnnotations
diff --git a/source/container-apps/web/web-server/features/auth/feature-annotations.cs b/source/container-apps/web/web-server/features/auth/feature-annotations.cs
index 43f6465c7..803c5446f 100644
--- a/source/container-apps/web/web-server/features/auth/feature-annotations.cs
+++ b/source/container-apps/web/web-server/features/auth/feature-annotations.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Names the Auth feature group as a constant for tagging its endpoints in API metadata; no code consumes it.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Auth;
 
 public static class FeatureAnnotations
diff --git a/source/container-apps/web/web-server/features/auth/get-sign-in-token-endpoint.cs b/source/container-apps/web/web-server/features/auth/get-sign-in-token-endpoint.cs
index 3e0bfeae3..abba423b0 100644
--- a/source/container-apps/web/web-server/features/auth/get-sign-in-token-endpoint.cs
+++ b/source/container-apps/web/web-server/features/auth/get-sign-in-token-endpoint.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// HTTP GET adapter that exchanges a user id for a Passwordless.dev sign-in token via the mediator pipeline.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Auth;
 
 using static GetSignInToken;
diff --git a/source/container-apps/web/web-server/features/hello/feature-annotations.cs b/source/container-apps/web/web-server/features/hello/feature-annotations.cs
index b9d640853..7ee979b7e 100644
--- a/source/container-apps/web/web-server/features/hello/feature-annotations.cs
+++ b/source/container-apps/web/web-server/features/hello/feature-annotations.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Names the Hello feature group as a constant for tagging its endpoints in API metadata; no code consumes it.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Hellos;
 
 public static class FeatureAnnotations
diff --git a/source/container-apps/web/web-server/features/profile/feature-annotations.cs b/source/container-apps/web/web-server/features/profile/feature-annotations.cs
index e8bc533be..2599bda87 100644
--- a/source/container-apps/web/web-server/features/profile/feature-annotations.cs
+++ b/source/container-apps/web/web-server/features/profile/feature-annotations.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Names the Profiles feature group as a constant for tagging its endpoints in API metadata; no code consumes it.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Profiles;
 
 public static class FeatureAnnotations
diff --git a/source/container-apps/web/web-server/features/profile/get-profile-endpoint.cs b/source/container-apps/web/web-server/features/profile/get-profile-endpoint.cs
index 836d5200e..1b868c00f 100644
--- a/source/container-apps/web/web-server/features/profile/get-profile-endpoint.cs
+++ b/source/container-apps/web/web-server/features/profile/get-profile-endpoint.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// HTTP GET adapter serving the signed-in user's display profile via the mediator pipeline.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Profiles;
 
 using static GetProfile;
diff --git a/source/container-apps/web/web-server/global-usings.cs b/source/container-apps/web/web-server/global-usings.cs
index b1ac6631c..e1b6adbf5 100644
--- a/source/container-apps/web/web-server/global-usings.cs
+++ b/source/container-apps/web/web-server/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using TimeWarp.Mediator;
 global using TimeWarp.Mediator.Pipeline;
 global using FluentValidation;
diff --git a/source/container-apps/web/web-spa/assembly-marker.cs b/source/container-apps/web/web-spa/assembly-marker.cs
index 8d8bc2f91..553edb49c 100644
--- a/source/container-apps/web/web-spa/assembly-marker.cs
+++ b/source/container-apps/web/web-spa/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Web.Spa;
 
 /// <summary>
diff --git a/source/container-apps/web/web-spa/components/base/edit-mode.cs b/source/container-apps/web/web-spa/components/base/edit-mode.cs
index 345fedca2..4d1f47e00 100644
--- a/source/container-apps/web/web-spa/components/base/edit-mode.cs
+++ b/source/container-apps/web/web-spa/components/base/edit-mode.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Shared enum so form components can switch read-only, edit, and create behavior from one state value.
+#endregion
+
 namespace TimeWarp.Architecture.Components;
 
 public enum EditMode { View, Edit, New };
diff --git a/source/container-apps/web/web-spa/components/elements/HyperLink.razor.cs b/source/container-apps/web/web-spa/components/elements/HyperLink.razor.cs
index e69de29bb..7fa759f66 100644
--- a/source/container-apps/web/web-spa/components/elements/HyperLink.razor.cs
+++ b/source/container-apps/web/web-spa/components/elements/HyperLink.razor.cs
@@ -0,0 +1,3 @@
+#region Purpose
+// Empty code-behind for the HyperLink element — its logic lives in HyperLink.razor's @code block; this file marks where code-behind goes if it grows.
+#endregion
diff --git a/source/container-apps/web/web-spa/components/interfaces/i-navigable-component.cs b/source/container-apps/web/web-spa/components/interfaces/i-navigable-component.cs
index 5f0dbf3b2..65c463757 100644
--- a/source/container-apps/web/web-spa/components/interfaces/i-navigable-component.cs
+++ b/source/container-apps/web/web-spa/components/interfaces/i-navigable-component.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Lets navigation menus read a page's title, icon, and auth policy statically, without instantiating the page.
+#endregion
+
 namespace TimeWarp.Architecture.Common.Interfaces;
 
 using TimeWarp.Architecture;
diff --git a/source/container-apps/web/web-spa/components/interfaces/i-static-route.cs b/source/container-apps/web/web-spa/components/interfaces/i-static-route.cs
index 4df906979..c36bd2c8c 100644
--- a/source/container-apps/web/web-spa/components/interfaces/i-static-route.cs
+++ b/source/container-apps/web/web-spa/components/interfaces/i-static-route.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Lets links build a page's href via static GetPageUrl() instead of hard-coded route strings; implemented on pages by the [Page] source generator.
+#endregion
+
 namespace TimeWarp.Architecture.Common.Interfaces;
 public interface IStaticRoute
 {
diff --git a/source/container-apps/web/web-spa/components/pages/SideNavigation.razor.cs b/source/container-apps/web/web-spa/components/pages/SideNavigation.razor.cs
index 694465a9d..7a3f34de1 100644
--- a/source/container-apps/web/web-spa/components/pages/SideNavigation.razor.cs
+++ b/source/container-apps/web/web-spa/components/pages/SideNavigation.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the side navigation container: exposes the RenderFragment slot the shell fills with nav links.
+#endregion
+
 namespace TimeWarp.Architecture.Components;
 
 partial class SideNavigation
diff --git a/source/container-apps/web/web-spa/components/pages/SideNavigationLink.razor.cs b/source/container-apps/web/web-spa/components/pages/SideNavigationLink.razor.cs
index 13f55a563..24a20f481 100644
--- a/source/container-apps/web/web-spa/components/pages/SideNavigationLink.razor.cs
+++ b/source/container-apps/web/web-spa/components/pages/SideNavigationLink.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for a single side-nav link: merges caller-supplied CSS classes into the link via CssBuilder.
+#endregion
+
 namespace TimeWarp.Architecture.Components;
 
 using CssBuilder = BlazorComponentUtilities.CssBuilder;
diff --git a/source/container-apps/web/web-spa/constants.cs b/source/container-apps/web/web-spa/constants.cs
index 2e15c5dba..8793b42dc 100644
--- a/source/container-apps/web/web-spa/constants.cs
+++ b/source/container-apps/web/web-spa/constants.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// SPA-local constants that have no home elsewhere, such as the non-standard HTTP status representing a client-cancelled operation.
+#endregion
+
 namespace TimeWarp.Architecture;
 
 internal static class Constants
diff --git a/source/container-apps/web/web-spa/features/account/pages/ChangePasswordPage.razor.cs b/source/container-apps/web/web-spa/features/account/pages/ChangePasswordPage.razor.cs
index 2d6ee6c3e..8a897d598 100644
--- a/source/container-apps/web/web-spa/features/account/pages/ChangePasswordPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/account/pages/ChangePasswordPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the change-password placeholder page: [Page] drives source-generated routing and navigation plumbing.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/changePassword")]
diff --git a/source/container-apps/web/web-spa/features/account/pages/LogoutPage.razor.cs b/source/container-apps/web/web-spa/features/account/pages/LogoutPage.razor.cs
index 1de6b27df..220a563f4 100644
--- a/source/container-apps/web/web-spa/features/account/pages/LogoutPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/account/pages/LogoutPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the signed-out confirmation page: [Page] drives source-generated routing and navigation plumbing.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/Logout")]
diff --git a/source/container-apps/web/web-spa/features/account/pages/login-page/LoginPage.razor.cs b/source/container-apps/web/web-spa/features/account/pages/login-page/LoginPage.razor.cs
index 38e90959f..c89c12bcc 100644
--- a/source/container-apps/web/web-spa/features/account/pages/login-page/LoginPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/account/pages/login-page/LoginPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the login page (passkey sign-in demo lives in the .razor @code block): [Page] drives source-generated routing and navigation plumbing.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/Login")]
diff --git a/source/container-apps/web/web-spa/features/admin/roles/pages/RolePage.razor.cs b/source/container-apps/web/web-spa/features/admin/roles/pages/RolePage.razor.cs
index d79884826..9a11f8f4b 100644
--- a/source/container-apps/web/web-spa/features/admin/roles/pages/RolePage.razor.cs
+++ b/source/container-apps/web/web-spa/features/admin/roles/pages/RolePage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the admin New Role page, which demos contract-interface form binding (IRoleDetails): [Page] drives source-generated routing.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/Admin/Roles/New")]
diff --git a/source/container-apps/web/web-spa/features/admin/roles/role-state/role-state.cs b/source/container-apps/web/web-spa/features/admin/roles/role-state/role-state.cs
index 8cd17778e..5de1f476d 100644
--- a/source/container-apps/web/web-spa/features/admin/roles/role-state/role-state.cs
+++ b/source/container-apps/web/web-spa/features/admin/roles/role-state/role-state.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Tracks the id of the most recently created role so the roles demo page can confirm the create round-trip.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Admin.Roles;
 
 [StateAccess]
diff --git a/source/container-apps/web/web-spa/features/application/pages/HomePage.razor.cs b/source/container-apps/web/web-spa/features/application/pages/HomePage.razor.cs
index b68b3f686..40b6a8da5 100644
--- a/source/container-apps/web/web-spa/features/application/pages/HomePage.razor.cs
+++ b/source/container-apps/web/web-spa/features/application/pages/HomePage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Registers the root route for the app's landing page; markup and button handlers live in HomePage.razor.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/")]
diff --git a/source/container-apps/web/web-spa/features/authorization/custom-requirements/module-requirement.cs b/source/container-apps/web/web-spa/features/authorization/custom-requirements/module-requirement.cs
index 1659b91e7..43205f476 100644
--- a/source/container-apps/web/web-spa/features/authorization/custom-requirements/module-requirement.cs
+++ b/source/container-apps/web/web-spa/features/authorization/custom-requirements/module-requirement.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Carries the module Guid an authorization policy demands; ModuleRequirementHandler satisfies it from fetched module grants.
+#endregion
+
 namespace TimeWarp.Architecture.CustomRequirements;
 
 public sealed class ModuleRequirement
diff --git a/source/container-apps/web/web-spa/features/base/i-base-action.cs b/source/container-apps/web/web-spa/features/base/i-base-action.cs
index 1e1c052ab..3e8ab807c 100644
--- a/source/container-apps/web/web-spa/features/base/i-base-action.cs
+++ b/source/container-apps/web/web-spa/features/base/i-base-action.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Unifies MediatR's IBaseRequest with TimeWarp.State's IAction so state actions can travel through the MediatR pipeline.
+#endregion
+
 namespace TimeWarp.Architecture.Features;
 
 public interface IBaseAction : IBaseRequest, IAction;
diff --git a/source/container-apps/web/web-spa/features/counter/pages/CounterPage.razor.cs b/source/container-apps/web/web-spa/features/counter/pages/CounterPage.razor.cs
index ab3b73a98..ed2802466 100644
--- a/source/container-apps/web/web-spa/features/counter/pages/CounterPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/counter/pages/CounterPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the counter demo page; wires handlers for route navigation home and a full store reset.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/Counter")]
diff --git a/source/container-apps/web/web-spa/features/debugger/pages/TestPage.razor.cs b/source/container-apps/web/web-spa/features/debugger/pages/TestPage.razor.cs
index c310fe29e..e9355469c 100644
--- a/source/container-apps/web/web-spa/features/debugger/pages/TestPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/debugger/pages/TestPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Registers the route for a scratch page used for ad-hoc debugging experiments.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/Debugger/Test")]
diff --git a/source/container-apps/web/web-spa/features/developer/components/user-claims-base.cs b/source/container-apps/web/web-spa/features/developer/components/user-claims-base.cs
index 935621054..a2c618660 100644
--- a/source/container-apps/web/web-spa/features/developer/components/user-claims-base.cs
+++ b/source/container-apps/web/web-spa/features/developer/components/user-claims-base.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Disabled (#if false) claims-display base-class sketch kept as reference; the TODO below records the pending delete-or-integrate decision.
+#endregion
+
 // TODO [2026-06]: Reassess UserClaimsBase after web-spa builds cleanly under AnalysisMode=All.
 // 
 // Context:
diff --git a/source/container-apps/web/web-spa/features/developer/pages/AlertExamplePage.razor.cs b/source/container-apps/web/web-spa/features/developer/pages/AlertExamplePage.razor.cs
index f001038f8..3d1b42eb0 100644
--- a/source/container-apps/web/web-spa/features/developer/pages/AlertExamplePage.razor.cs
+++ b/source/container-apps/web/web-spa/features/developer/pages/AlertExamplePage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Registers the route for a developer gallery page showcasing SimpleAlert variants.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/developer/alert-example")]
diff --git a/source/container-apps/web/web-spa/features/developer/pages/UserClaimsPage.razor.cs b/source/container-apps/web/web-spa/features/developer/pages/UserClaimsPage.razor.cs
index c62b69598..75f911c80 100644
--- a/source/container-apps/web/web-spa/features/developer/pages/UserClaimsPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/developer/pages/UserClaimsPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Registers the route for a developer diagnostic page that displays the signed-in user's claims.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/Developer/UserClaims")]
diff --git a/source/container-apps/web/web-spa/features/event-stream/event-stream-state/event-stream-state.cs b/source/container-apps/web/web-spa/features/event-stream/event-stream-state/event-stream-state.cs
index 8ec985750..76cd425b3 100644
--- a/source/container-apps/web/web-spa/features/event-stream/event-stream-state/event-stream-state.cs
+++ b/source/container-apps/web/web-spa/features/event-stream/event-stream-state/event-stream-state.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Accumulates the action names captured by the event-stream middleware demo for display on the EventStream page.
+#endregion
+
 namespace TimeWarp.Architecture.Features.EventStreams;
 
 [StateAccess]
diff --git a/source/container-apps/web/web-spa/features/event-stream/pages/EventStreamPage.razor.cs b/source/container-apps/web/web-spa/features/event-stream/pages/EventStreamPage.razor.cs
index 420be277a..5fefbd6fe 100644
--- a/source/container-apps/web/web-spa/features/event-stream/pages/EventStreamPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/event-stream/pages/EventStreamPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Registers the route for the page demonstrating the EventStream middleware's captured action log.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/EventStream")]
diff --git a/source/container-apps/web/web-spa/features/superhero/pages/SuperheroPage.razor.cs b/source/container-apps/web/web-spa/features/superhero/pages/SuperheroPage.razor.cs
index 5015d5ab0..96b17e86d 100644
--- a/source/container-apps/web/web-spa/features/superhero/pages/SuperheroPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/superhero/pages/SuperheroPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the Superheros page: wires the route and kicks off the gRPC superhero fetch on initialization.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 using static TimeWarp.Architecture.Features.Superheros.SuperheroState;
diff --git a/source/container-apps/web/web-spa/features/superhero/superhero-module.cs b/source/container-apps/web/web-spa/features/superhero/superhero-module.cs
index a93e63a65..8d1439555 100644
--- a/source/container-apps/web/web-spa/features/superhero/superhero-module.cs
+++ b/source/container-apps/web/web-spa/features/superhero/superhero-module.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// DI registration for the superhero feature: the service-URI resolver and the gRPC client provider its state actions depend on.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Superheros;
 
 public class SuperheroModule
diff --git a/source/container-apps/web/web-spa/features/superhero/superhero-state/superhero-state.cs b/source/container-apps/web/web-spa/features/superhero/superhero-state/superhero-state.cs
index 20d2f0473..1a947b47d 100644
--- a/source/container-apps/web/web-spa/features/superhero/superhero-state/superhero-state.cs
+++ b/source/container-apps/web/web-spa/features/superhero/superhero-state/superhero-state.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Root partial of the superhero TimeWarp State store: holds the superhero list; actions live in sibling superhero-state.*.cs partials.
+#endregion
+
 namespace TimeWarp.Architecture.Features.Superheros;
 
 [StateAccess]
diff --git a/source/container-apps/web/web-spa/features/to-do/pages/TodoItemPage.razor.cs b/source/container-apps/web/web-spa/features/to-do/pages/TodoItemPage.razor.cs
index 1a72e1558..ae78de831 100644
--- a/source/container-apps/web/web-spa/features/to-do/pages/TodoItemPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/to-do/pages/TodoItemPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the single todo item page: binds the TodoItemId route parameter consumed by the edit form.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/todoitems/{TodoItemId:Guid}")]
diff --git a/source/container-apps/web/web-spa/features/to-do/pages/TodoItemsPage.razor.cs b/source/container-apps/web/web-spa/features/to-do/pages/TodoItemsPage.razor.cs
index 9169d987b..e3547ff62 100644
--- a/source/container-apps/web/web-spa/features/to-do/pages/TodoItemsPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/to-do/pages/TodoItemsPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the todo items list page: declares the route; the markup delegates rendering to TodoItemList.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/todoitems")]
diff --git a/source/container-apps/web/web-spa/features/to-do/todo-state.cs b/source/container-apps/web/web-spa/features/to-do/todo-state.cs
index ed7f10c72..6f239002d 100644
--- a/source/container-apps/web/web-spa/features/to-do/todo-state.cs
+++ b/source/container-apps/web/web-spa/features/to-do/todo-state.cs
@@ -1,3 +1,13 @@
+#region Purpose
+// Placeholder marking where the to-do feature's client-side state store belongs.
+#endregion
+
+#region Design
+// Deliberately empty: it neither extends State<T> nor gets registered, because the
+// to-do pages and components talk to the API directly rather than through a store.
+// Convert it to a TimeWarp State store when the feature needs shared client state.
+#endregion
+
 namespace TimeWarp.Architecture.Features.ToDo;
 
 public class TodoState
diff --git a/source/container-apps/web/web-spa/features/weather-forecast/pages/WeatherForecastsPage.razor.cs b/source/container-apps/web/web-spa/features/weather-forecast/pages/WeatherForecastsPage.razor.cs
index a1b3a9e45..bdf608d55 100644
--- a/source/container-apps/web/web-spa/features/weather-forecast/pages/WeatherForecastsPage.razor.cs
+++ b/source/container-apps/web/web-spa/features/weather-forecast/pages/WeatherForecastsPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the weather forecasts page: declares the route; the fetch-on-init logic lives in the .razor @code block.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/WeatherForecasts")]
diff --git a/source/container-apps/web/web-spa/features/weather-forecast/weather-forecast-module.cs b/source/container-apps/web/web-spa/features/weather-forecast/weather-forecast-module.cs
index 4ce60c221..473e2e284 100644
--- a/source/container-apps/web/web-spa/features/weather-forecast/weather-forecast-module.cs
+++ b/source/container-apps/web/web-spa/features/weather-forecast/weather-forecast-module.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// DI registration hook for the weather forecast feature; the body is empty because the feature needs nothing beyond shared services.
+#endregion
+
 namespace TimeWarp.Architecture.Features.WeatherForecasts;
 
 public class WeatherForecastModule
diff --git a/source/container-apps/web/web-spa/global-suppressions.cs b/source/container-apps/web/web-spa/global-suppressions.cs
index 15edfda9a..189ab2fd9 100644
--- a/source/container-apps/web/web-spa/global-suppressions.cs
+++ b/source/container-apps/web/web-spa/global-suppressions.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Assembly-level analyzer suppressions for Web.Spa, gathering warnings judged acceptable instead of scattering pragmas through code.
+#endregion
+
 // This file is used by Code Analysis to maintain SuppressMessage
 // attributes that are applied to this project.
 // Project-level suppressions either have no target or are given
diff --git a/source/container-apps/web/web-spa/global-usings.cs b/source/container-apps/web/web-spa/global-usings.cs
index b60d4d1e8..8d3500aa6 100644
--- a/source/container-apps/web/web-spa/global-usings.cs
+++ b/source/container-apps/web/web-spa/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Ardalis.GuardClauses;
 global using Icons = Microsoft.FluentUI.AspNetCore.Components.Icons;
 global using TimeWarp.State;
diff --git a/source/container-apps/web/web-spa/java-script-interop-constants.cs b/source/container-apps/web/web-spa/java-script-interop-constants.cs
index 022586d89..6dd9fef86 100644
--- a/source/container-apps/web/web-spa/java-script-interop-constants.cs
+++ b/source/container-apps/web/web-spa/java-script-interop-constants.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Names of JS interop functions as constants, so C# callers and the wwwroot/js implementations agree on a single string.
+#endregion
+
 namespace TimeWarp.Architecture;
 
 /// <summary>
diff --git a/source/container-apps/web/web-spa/pages/ProfilePage.razor.cs b/source/container-apps/web/web-spa/pages/ProfilePage.razor.cs
index 9a0d72cc5..ed1d93855 100644
--- a/source/container-apps/web/web-spa/pages/ProfilePage.razor.cs
+++ b/source/container-apps/web/web-spa/pages/ProfilePage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind for the Profile page: declares the route and gates it behind an authenticated user.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/Profile")]
diff --git a/source/container-apps/web/web-spa/pages/SettingsPage.razor.cs b/source/container-apps/web/web-spa/pages/SettingsPage.razor.cs
index a547dc001..2fb712580 100644
--- a/source/container-apps/web/web-spa/pages/SettingsPage.razor.cs
+++ b/source/container-apps/web/web-spa/pages/SettingsPage.razor.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Code-behind that binds the /Settings route to the Settings placeholder page.
+#endregion
+
 namespace TimeWarp.Architecture.Pages;
 
 [Page("/Settings")]
diff --git a/source/container-apps/web/web-spa/pipeline/notification-post-processor/post-pipeline-notification.cs b/source/container-apps/web/web-spa/pipeline/notification-post-processor/post-pipeline-notification.cs
index 77d73ed2e..884f8d5cf 100644
--- a/source/container-apps/web/web-spa/pipeline/notification-post-processor/post-pipeline-notification.cs
+++ b/source/container-apps/web/web-spa/pipeline/notification-post-processor/post-pipeline-notification.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Notification carrying a completed request/response pair so features can react to other features' actions without coupling to their handlers.
+#endregion
+
 namespace TimeWarp.Architecture.Pipeline.NotificationPostProcessor;
 
 public class PostPipelineNotification<TRequest, TResponse> : INotification
diff --git a/source/container-apps/web/web-spa/pipeline/notification-pre-processor/pre-pipeline-notification.cs b/source/container-apps/web/web-spa/pipeline/notification-pre-processor/pre-pipeline-notification.cs
index 287d4ab23..2d0a23193 100644
--- a/source/container-apps/web/web-spa/pipeline/notification-pre-processor/pre-pipeline-notification.cs
+++ b/source/container-apps/web/web-spa/pipeline/notification-pre-processor/pre-pipeline-notification.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Notification carrying a request about to be handled so features can observe or react before the handler runs, without coupling to it.
+#endregion
+
 namespace TimeWarp.Architecture.Pipeline.NotificationPreProcessor;
 
 public class PrePipelineNotification<TRequest> : INotification
diff --git a/source/container-apps/yarp/assembly-marker.cs b/source/container-apps/yarp/assembly-marker.cs
index 2b52b1779..928066bb9 100644
--- a/source/container-apps/yarp/assembly-marker.cs
+++ b/source/container-apps/yarp/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Architecture.Yarp.Server;
 
 /// <summary>
diff --git a/source/container-apps/yarp/global-usings.cs b/source/container-apps/yarp/global-usings.cs
index 2f7f34ad0..a94f6f72d 100644
--- a/source/container-apps/yarp/global-usings.cs
+++ b/source/container-apps/yarp/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Microsoft.AspNetCore.Builder;
 global using Microsoft.AspNetCore.Routing;
 global using Microsoft.Extensions.Configuration;
diff --git a/source/foundation/foundation-application/abstractions/i-current-user-service.cs b/source/foundation/foundation-application/abstractions/i-current-user-service.cs
index 7b250ca7a..8956c990d 100644
--- a/source/foundation/foundation-application/abstractions/i-current-user-service.cs
+++ b/source/foundation/foundation-application/abstractions/i-current-user-service.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Abstraction exposing the authenticated user's id so application code never reaches into HttpContext or auth plumbing.
+#endregion
+
 namespace TimeWarp.Foundation.Abstractions;
 
 public interface ICurrentUserService
diff --git a/source/foundation/foundation-application/abstractions/i-date-time-service.cs b/source/foundation/foundation-application/abstractions/i-date-time-service.cs
index a6663797d..539c3e23a 100644
--- a/source/foundation/foundation-application/abstractions/i-date-time-service.cs
+++ b/source/foundation/foundation-application/abstractions/i-date-time-service.cs
@@ -1,3 +1,12 @@
+#region Purpose
+// Injectable clock abstraction so consumers can be tested with frozen or scripted time.
+#endregion
+
+#region Design
+// NextUtcNow contracts to hand out strictly increasing timestamps for consumers that use
+// time as an ordering key; see DateTimeService in foundation-infrastructure for the mechanics.
+#endregion
+
 namespace TimeWarp.Foundation.Abstractions;
 
 public interface IDateTimeService
diff --git a/source/foundation/foundation-application/assembly-marker.cs b/source/foundation/foundation-application/assembly-marker.cs
index 560330e97..d14b13128 100644
--- a/source/foundation/foundation-application/assembly-marker.cs
+++ b/source/foundation/foundation-application/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Foundation.Common.Application;
 
 /// <summary>
diff --git a/source/foundation/foundation-application/global-usings.cs b/source/foundation/foundation-application/global-usings.cs
index d2434d2b3..9ae16c421 100644
--- a/source/foundation/foundation-application/global-usings.cs
+++ b/source/foundation/foundation-application/global-usings.cs
@@ -1 +1,5 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 // global using xyz;
diff --git a/source/foundation/foundation-contracts/assembly-marker.cs b/source/foundation/foundation-contracts/assembly-marker.cs
index f800281d8..edcf93a0c 100644
--- a/source/foundation/foundation-contracts/assembly-marker.cs
+++ b/source/foundation/foundation-contracts/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Foundation.Common.Contracts;
 
 /// <summary>
diff --git a/source/foundation/foundation-contracts/base/base-message.cs b/source/foundation/foundation-contracts/base/base-message.cs
index e74e54580..d530e2ec2 100644
--- a/source/foundation/foundation-contracts/base/base-message.cs
+++ b/source/foundation/foundation-contracts/base/base-message.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Root of the contract message hierarchy, giving requests and responses a single common ancestor.
+#endregion
+
 namespace TimeWarp.Foundation.Features;
 
 /// <summary>
diff --git a/source/foundation/foundation-contracts/base/base-paged-request.cs b/source/foundation/foundation-contracts/base/base-paged-request.cs
index 347f936c7..1fea17338 100644
--- a/source/foundation/foundation-contracts/base/base-paged-request.cs
+++ b/source/foundation/foundation-contracts/base/base-paged-request.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Base for list-style requests, supplying Page/PageSize so paging is uniform across endpoints.
+#endregion
+
 namespace TimeWarp.Foundation.Features;
 
 public abstract class BasePagedRequest : BaseRequest
diff --git a/source/foundation/foundation-contracts/base/base-request.cs b/source/foundation/foundation-contracts/base/base-request.cs
index e6e6158c9..f3d2fb886 100644
--- a/source/foundation/foundation-contracts/base/base-request.cs
+++ b/source/foundation/foundation-contracts/base/base-request.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Common ancestor for all request contracts, marking the request side of the message hierarchy.
+#endregion
+
 namespace TimeWarp.Foundation.Features;
 
 /// <summary>
diff --git a/source/foundation/foundation-contracts/base/base-response.cs b/source/foundation/foundation-contracts/base/base-response.cs
index fbcd1eb13..dbea84a27 100644
--- a/source/foundation/foundation-contracts/base/base-response.cs
+++ b/source/foundation/foundation-contracts/base/base-response.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Common ancestor for all response contracts, marking the response side of the message hierarchy.
+#endregion
+
 namespace TimeWarp.Foundation.Features;
 
 /// <summary>
diff --git a/source/foundation/foundation-contracts/base/http-verb.cs b/source/foundation/foundation-contracts/base/http-verb.cs
index 7defea962..704a365b7 100644
--- a/source/foundation/foundation-contracts/base/http-verb.cs
+++ b/source/foundation/foundation-contracts/base/http-verb.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Enum of HTTP methods so contracts can declare their verb without depending on System.Net.Http's HttpMethod class.
+#endregion
+
 namespace TimeWarp.Foundation.Features;
 public enum HttpVerb
 {
diff --git a/source/foundation/foundation-contracts/base/i-api-request.cs b/source/foundation/foundation-contracts/base/i-api-request.cs
index 040f6d547..e84afe301 100644
--- a/source/foundation/foundation-contracts/base/i-api-request.cs
+++ b/source/foundation/foundation-contracts/base/i-api-request.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Makes a request contract self-describing (route + verb) so a generic API client can dispatch it without per-endpoint plumbing.
+#endregion
+
 namespace TimeWarp.Foundation.Features;
 
 public interface IApiRequest : IBaseRequest
diff --git a/source/foundation/foundation-contracts/base/i-base-message.cs b/source/foundation/foundation-contracts/base/i-base-message.cs
index dba49c6d6..5d9085add 100644
--- a/source/foundation/foundation-contracts/base/i-base-message.cs
+++ b/source/foundation/foundation-contracts/base/i-base-message.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Root marker of the contract message hierarchy so generic plumbing can constrain to "any request or response".
+#endregion
+
 namespace TimeWarp.Foundation.Features;
 
 /// <summary>
diff --git a/source/foundation/foundation-contracts/base/i-base-request.cs b/source/foundation/foundation-contracts/base/i-base-request.cs
index 73971d8e3..603b22f4e 100644
--- a/source/foundation/foundation-contracts/base/i-base-request.cs
+++ b/source/foundation/foundation-contracts/base/i-base-request.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker that distinguishes requests from responses within the contract message hierarchy.
+#endregion
+
 namespace TimeWarp.Foundation.Features;
 
 /// <summary>
diff --git a/source/foundation/foundation-contracts/base/i-query-string-route-provider.cs b/source/foundation/foundation-contracts/base/i-query-string-route-provider.cs
index 861a5d435..d41781f24 100644
--- a/source/foundation/foundation-contracts/base/i-query-string-route-provider.cs
+++ b/source/foundation/foundation-contracts/base/i-query-string-route-provider.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Lets GET-style query contracts build their own route with parameters encoded in the query string, since GETs carry no body.
+#endregion
+
 namespace TimeWarp.Foundation.Features;
 
 public interface IQueryStringRouteProvider:IApiRequest
diff --git a/source/foundation/foundation-contracts/configuration/service-names.cs b/source/foundation/foundation-contracts/configuration/service-names.cs
index 92441abc4..7eb4c9672 100644
--- a/source/foundation/foundation-contracts/configuration/service-names.cs
+++ b/source/foundation/foundation-contracts/configuration/service-names.cs
@@ -1,3 +1,12 @@
+#region Purpose
+// Single source of truth for service-discovery names shared by the Aspire AppHost and every client that resolves a service BaseAddress.
+#endregion
+
+#region Design
+// Aspire AppHost resource names must equal these constants: service discovery resolves
+// addresses by name, and a mismatch yields a null BaseAddress during server-side rendering.
+#endregion
+
 namespace TimeWarp.Foundation.Configuration;
 public static class ServiceNames
 {
diff --git a/source/foundation/foundation-contracts/global-usings.cs b/source/foundation/foundation-contracts/global-usings.cs
index e086ae7a4..ef5638857 100644
--- a/source/foundation/foundation-contracts/global-usings.cs
+++ b/source/foundation/foundation-contracts/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Ardalis.GuardClauses;
 global using FluentValidation;
 global using FluentValidation.Results;
diff --git a/source/foundation/foundation-contracts/types/mock-response-factory.cs b/source/foundation/foundation-contracts/types/mock-response-factory.cs
index 9ce00cf00..2892fa237 100644
--- a/source/foundation/foundation-contracts/types/mock-response-factory.cs
+++ b/source/foundation/foundation-contracts/types/mock-response-factory.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Delegate shape that lets each contract supply its own canned response, so mock API services can run the SPA without a backend.
+#endregion
+
 namespace TimeWarp.Foundation.Types;
 
 public delegate TResponse MockResponseFactory<out TResponse>(IApiRequest request) where TResponse : class;
diff --git a/source/foundation/foundation-domain/assembly-marker.cs b/source/foundation/foundation-domain/assembly-marker.cs
index 30cbca440..c3262caa7 100644
--- a/source/foundation/foundation-domain/assembly-marker.cs
+++ b/source/foundation/foundation-domain/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Foundation.Common.Domain;
 
 /// <summary>
diff --git a/source/foundation/foundation-domain/entities/base/base-entity.cs b/source/foundation/foundation-domain/entities/base/base-entity.cs
index f2881864f..7128dc237 100644
--- a/source/foundation/foundation-domain/entities/base/base-entity.cs
+++ b/source/foundation/foundation-domain/entities/base/base-entity.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Common base for domain entities so every entity carries a Guid identity regardless of database provider.
+#endregion
+
 namespace TimeWarp.Foundation.Entities;
 public abstract class BaseEntity
 {
diff --git a/source/foundation/foundation-domain/entities/base/base-event.cs b/source/foundation/foundation-domain/entities/base/base-event.cs
index 4dcd77708..cec58744f 100644
--- a/source/foundation/foundation-domain/entities/base/base-event.cs
+++ b/source/foundation/foundation-domain/entities/base/base-event.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Common base for domain events so they publish through the MediatR notification pipeline.
+#endregion
+
 namespace TimeWarp.Foundation.Entities.Base;
 
 public abstract class BaseEvent : INotification { }
diff --git a/source/foundation/foundation-domain/global-usings.cs b/source/foundation/foundation-domain/global-usings.cs
index 1ac25d003..27f7ccc4c 100644
--- a/source/foundation/foundation-domain/global-usings.cs
+++ b/source/foundation/foundation-domain/global-usings.cs
@@ -1,2 +1,6 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using System.Reflection;
 global using TimeWarp.Mediator;
diff --git a/source/foundation/foundation-infrastructure/assembly-marker.cs b/source/foundation/foundation-infrastructure/assembly-marker.cs
index a23e90dd2..a161a73c4 100644
--- a/source/foundation/foundation-infrastructure/assembly-marker.cs
+++ b/source/foundation/foundation-infrastructure/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Foundation.Common.Infrastructure;
 
 /// <summary>
diff --git a/source/foundation/foundation-infrastructure/common-infrastructure-module.cs b/source/foundation/foundation-infrastructure/common-infrastructure-module.cs
index 7622bd174..c1f1b3405 100644
--- a/source/foundation/foundation-infrastructure/common-infrastructure-module.cs
+++ b/source/foundation/foundation-infrastructure/common-infrastructure-module.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Registers infrastructure services every server needs (current-user resolution) so each host wires them through one module instead of repeating the registrations.
+#endregion
+
 namespace TimeWarp.Foundation.Common.Infrastructure;
 
 public class CommonInfrastructureModule : IModule
diff --git a/source/foundation/foundation-infrastructure/global-usings.cs b/source/foundation/foundation-infrastructure/global-usings.cs
index 4c806c2a7..de3982cd7 100644
--- a/source/foundation/foundation-infrastructure/global-usings.cs
+++ b/source/foundation/foundation-infrastructure/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Microsoft.AspNetCore.Http;
 global using Microsoft.Extensions.Configuration;
 global using Microsoft.Extensions.DependencyInjection;
diff --git a/source/foundation/foundation-server/assembly-marker.cs b/source/foundation/foundation-server/assembly-marker.cs
index c41181437..91c17af5c 100644
--- a/source/foundation/foundation-server/assembly-marker.cs
+++ b/source/foundation/foundation-server/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Foundation.Common.Server;
 
 /// <summary>
diff --git a/source/foundation/foundation-server/global-usings.cs b/source/foundation/foundation-server/global-usings.cs
index 43e0a7046..5a22ab9cd 100644
--- a/source/foundation/foundation-server/global-usings.cs
+++ b/source/foundation/foundation-server/global-usings.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Ardalis.GuardClauses;
 global using Azure.Identity;
 global using FastEndpoints;
diff --git a/source/foundation/foundation-server/i-aspnet-module.cs b/source/foundation/foundation-server/i-aspnet-module.cs
index 41179ed86..f7e4c6ec3 100644
--- a/source/foundation/foundation-server/i-aspnet-module.cs
+++ b/source/foundation/foundation-server/i-aspnet-module.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Extends IModule with configuration, middleware, and endpoint hooks so a module can wire the full ASP.NET pipeline, not just DI services.
+#endregion
+
 namespace TimeWarp.Foundation;
 
 public interface IAspNetModule : IModule
diff --git a/source/foundation/foundation-server/i-aspnet-program.cs b/source/foundation/foundation-server/i-aspnet-program.cs
index a899befe1..2b250f85f 100644
--- a/source/foundation/foundation-server/i-aspnet-program.cs
+++ b/source/foundation/foundation-server/i-aspnet-program.cs
@@ -1,2 +1,6 @@
+#region Purpose
+// Marks the composition-root module of an ASP.NET host, distinguishing the program itself from the feature modules it composes.
+#endregion
+
 namespace TimeWarp.Foundation;
 public interface IAspNetProgram : IAspNetModule { }
diff --git a/source/libraries/timewarp-modules/assembly-marker.cs b/source/libraries/timewarp-modules/assembly-marker.cs
index fbcd7ea83..b8eb1c17a 100644
--- a/source/libraries/timewarp-modules/assembly-marker.cs
+++ b/source/libraries/timewarp-modules/assembly-marker.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Marker type providing a typed reference to this assembly (registration, scanning, InternalsVisibleTo).
+#endregion
+
 namespace TimeWarp.Modules;
 
 /// <summary>
diff --git a/source/libraries/timewarp-modules/global-usings.cs b/source/libraries/timewarp-modules/global-usings.cs
index 034c2451d..ba05b3572 100644
--- a/source/libraries/timewarp-modules/global-usings.cs
+++ b/source/libraries/timewarp-modules/global-usings.cs
@@ -1,2 +1,6 @@
+#region Purpose
+// Project-wide using directives so individual files omit repeated imports.
+#endregion
+
 global using Microsoft.Extensions.Configuration;
 global using Microsoft.Extensions.DependencyInjection;
diff --git a/source/libraries/timewarp-modules/i-module.cs b/source/libraries/timewarp-modules/i-module.cs
index d74a1c8f4..f31fdb781 100644
--- a/source/libraries/timewarp-modules/i-module.cs
+++ b/source/libraries/timewarp-modules/i-module.cs
@@ -1,3 +1,7 @@
+#region Purpose
+// Contract for self-registering modules; the static abstract hook lets each assembly wire its own DI services without a central composition root.
+#endregion
+
 namespace TimeWarp.Modules;
 
 public interface IModule
diff --git a/tests/analyzers/timewarp-architecture-analyzers-tests/purpose-region-analyzer-tests.cs b/tests/analyzers/timewarp-architecture-analyzers-tests/purpose-region-analyzer-tests.cs
new file mode 100644
index 000000000..dba11bf66
--- /dev/null
+++ b/tests/analyzers/timewarp-architecture-analyzers-tests/purpose-region-analyzer-tests.cs
@@ -0,0 +1,129 @@
+// ReSharper disable InconsistentNaming
+namespace PurposeRegionAnalyzer_;
+
+using Microsoft.CodeAnalysis.CSharp.Testing;
+using TimeWarp.Architecture.Analyzers;
+using TimeWarp.Architecture.Analyzers.Tests;
+
+public class Should_Enforce_Purpose_Region
+{
+  private static CSharpAnalyzerTest<PurposeRegionAnalyzer, FixieVerifier> Test(string fileName, string source) =>
+    new() { TestState = { Sources = { (fileName, source) } } };
+
+  public static async Task Given_File_Without_Purpose_Region()
+  {
+    const string Source =
+      """
+      namespace Contracts;
+
+      public class Widget
+      {
+        public string Name { get; set; } = null!;
+      }
+      """;
+
+    DiagnosticResult expectedDiagnostic = new DiagnosticResult(id: "TWPA0004", DiagnosticSeverity.Warning)
+      .WithSpan("Widget.cs", 1, 1, 1, 10)
+      .WithArguments("Widget.cs");
+
+    CSharpAnalyzerTest<PurposeRegionAnalyzer, FixieVerifier> analyzerTest = new()
+    {
+      TestState =
+      {
+        Sources =
+        {
+          ("Widget.cs", Source)
+        }
+      }
+    };
+
+    analyzerTest.ExpectedDiagnostics.Add(expectedDiagnostic);
+
+    await analyzerTest.RunAsync();
+  }
+
+  public static async Task Given_File_With_Purpose_Region_IsClean()
+  {
+    const string Source =
+      """
+      #region Purpose
+      // A widget shape used to verify the analyzer accepts a top-of-file region.
+      #endregion
+
+      namespace Contracts;
+
+      public class Widget
+      {
+        public string Name { get; set; } = null!;
+      }
+      """;
+
+    await Test("Widget.cs", Source).RunAsync();
+  }
+
+  public static async Task Given_Purpose_Region_Anywhere_In_File_IsClean()
+  {
+    // Placement is skill guidance, not analyzer scope — a nested region still satisfies the rule.
+    const string Source =
+      """
+      namespace Contracts;
+
+      public class Widget
+      {
+        #region Purpose
+        // Region nested inside the type still counts.
+        #endregion
+        public string Name { get; set; } = null!;
+      }
+      """;
+
+    await Test("Widget.cs", Source).RunAsync();
+  }
+
+  public static async Task Given_Other_Region_Names_Still_Flagged()
+  {
+    const string Source =
+      """
+      #region Design
+      // Design alone is not enough; Purpose is the universal requirement.
+      #endregion
+
+      namespace Contracts;
+
+      public class Widget;
+      """;
+
+    DiagnosticResult expectedDiagnostic = new DiagnosticResult(id: "TWPA0004", DiagnosticSeverity.Warning)
+      .WithSpan("Widget.cs", 5, 1, 5, 10)
+      .WithArguments("Widget.cs");
+
+    CSharpAnalyzerTest<PurposeRegionAnalyzer, FixieVerifier> analyzerTest = new()
+    {
+      TestState =
+      {
+        Sources =
+        {
+          ("Widget.cs", Source)
+        }
+      }
+    };
+
+    analyzerTest.ExpectedDiagnostics.Add(expectedDiagnostic);
+
+    await analyzerTest.RunAsync();
+  }
+
+  public static async Task Given_Generated_File_IsClean()
+  {
+    // <auto-generated/> header marks the tree generated; GeneratedCodeAnalysisFlags.None skips it.
+    const string Source =
+      """
+      // <auto-generated/>
+      namespace Contracts;
+
+      public class Widget;
+      """;
+
+    await Test("Widget.g.cs", Source).RunAsync();
+  }
+}
diff --git a/tests/analyzers/timewarp-architecture-analyzers-tests/timewarp-architecture-analyzers-tests.csproj b/tests/analyzers/timewarp-architecture-analyzers-tests/timewarp-architecture-analyzers-tests.csproj
index cd2782c57..8f991d58a 100644
--- a/tests/analyzers/timewarp-architecture-analyzers-tests/timewarp-architecture-analyzers-tests.csproj
+++ b/tests/analyzers/timewarp-architecture-analyzers-tests/timewarp-architecture-analyzers-tests.csproj
@@ -12,6 +12,6 @@
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\..\..\source\analyzers\timewarp-architecture-analyzers\timewarp-architecture-analyzers.csproj" />
-    <ProjectReference Include="..\..\..\source\analyzers\timewarp-architecture-contract-analyzers\timewarp-architecture-contract-analyzers.csproj" />
+    <ProjectReference Include="..\..\..\source\analyzers\timewarp-architecture-convention-analyzers\timewarp-architecture-convention-analyzers.csproj" />
   </ItemGroup>
 </Project>
\ No newline at end of file
diff --git a/timewarp-architecture.slnx b/timewarp-architecture.slnx
index b51a79897..a6bace5db 100644
--- a/timewarp-architecture.slnx
+++ b/timewarp-architecture.slnx
@@ -16,7 +16,7 @@
   <Folder Name="/source/analyzers/">
     <Project Path="source/analyzers/timewarp-architecture-attributes/timewarp-architecture-attributes.csproj" />
     <Project Path="source/analyzers/timewarp-architecture-analyzers/timewarp-architecture-analyzers.csproj" />
-    <Project Path="source/analyzers/timewarp-architecture-contract-analyzers/timewarp-architecture-contract-analyzers.csproj" />
+    <Project Path="source/analyzers/timewarp-architecture-convention-analyzers/timewarp-architecture-convention-analyzers.csproj" />
   </Folder>
   <Folder Name="/source/container-apps/">
     <!--#if (api) -->