aalmada · aalmada · Feb 20, 2026 · Feb 16, 2026 · Feb 16, 2026 · Feb 16, 2026
diff --git a/.claude/skills/ops__doctor_check/SKILL.md b/.claude/skills/ops__doctor_check/SKILL.md
@@ -20,7 +20,16 @@ Perform a health check on the development environment to ensure all prerequisite
    - **Requirement**: Aspire CLI must be installed.
    - *Action*: If missing, see [Install instructions](https://aspire.dev/get-started/install-cli/)
 
-5. **Report Summary**
+5. **Playwright Browsers** (for `BookStore.AppHost.Tests`)
+   - Check if the chromium binary exists inside the build output: `ls tests/BookStore.AppHost.Tests/bin/Debug/net10.0/.playwright/package/` (requires the project to have been built)
+   - **Requirement**: Chromium must be installed for browser-based integration tests.
+   - *Action*: If missing or the project hasn't been built yet, run:
+     ```bash
+     dotnet build tests/BookStore.AppHost.Tests/BookStore.AppHost.Tests.csproj
+     node tests/BookStore.AppHost.Tests/bin/Debug/net10.0/.playwright/package/index.js install chromium
+     ```
+
+6. **Report Summary**
    - If all checks pass: "✅ Environment is healthy"
    - If issues found: List specific missing tools with installation instructions
 

diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,9 @@
+{
+    "recommendations": [
+        "microsoft-aspire.aspire-vscode",
+        "ms-dotnettools.csdevkit",
+        "ms-azuretools.vscode-containers",
+        "editorconfig.editorconfig",
+        "bits.csharp-test-filter"
+    ]
+}
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -0,0 +1,31 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug TUnit Test",
+      "type": "coreclr",
+      "request": "launch",
+      "preLaunchTask": "build",
+      "program": "${input:dllPath}",
+      "args": [
+        "--treenode-filter",
+        "${input:testFilter}"
+      ],
+      "cwd": "${workspaceFolder}",
+      "console": "integratedTerminal",
+      "stopAtEntry": false
+    }
+  ],
+  "inputs": [
+    {
+      "id": "dllPath",
+      "type": "command",
+      "command": "csharp-test-filter.getDllPath"
+    },
+    {
+      "id": "testFilter",
+      "type": "command",
+      "command": "csharp-test-filter.getFilter"
+    }
+  ]
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -6,12 +6,27 @@ Use this file for agent-only context: build and test commands, conventions, and
 
 ## Quick Reference
 
-- **Stack**: .NET 10, C# 14, Marten, Wolverine, HybridCache, Aspire
+- **Stack**: .NET 10, C# 14, Marten, Wolverine, HybridCache, Aspire, Playwright
 - **Solution**: `BookStore.slnx` (new .NET 10 solution format)
 - **Common commands**: `dotnet restore`, `aspire run`, `dotnet test`, `dotnet format`
 - **Docs**: `docs/getting-started.md`, `docs/guides/`
 - **Testing instructions**: `tests/AGENTS.md`
 
+### Running Tests (TUnit)
+
+TUnit-specific arguments must be passed after `--` so they are forwarded as program arguments rather than parsed by `dotnet test`:
+
+```bash
+# Run all tests (uses all available cores by default)
+dotnet test
+
+# Limit parallelism in resource-constrained environments
+dotnet test -- --maximum-parallel-tests 4
+
+# Filter tests by category
+dotnet test -- --treenode-filter "/*/*/*/*[Category=Integration]"
+```
+
 ## Repository Map
 
 - `src/BookStore.ApiService/`: Event-sourced API (Marten + Wolverine)
@@ -38,9 +53,9 @@ Use this file for agent-only context: build and test commands, conventions, and
 2. Write verification first
 3. Implement
 4. Verify all steps pass
-5. Run `dotnet format` to ensure code style compliance
+5. Run `dotnet format` to ensure code style compliance. Issues not automatically fixed must be resolved manually.
 
-**A feature is not complete until `dotnet format` has been executed successfully.**
+**A feature is not complete until `dotnet format --verify-no-changes` exits with code 0.**
 
 ## Code Rules (MUST follow)
 
@@ -52,6 +67,7 @@ Use this file for agent-only context: build and test commands, conventions, and
 ✅ [Test] async Task (TUnit)      ❌ [Fact] (xUnit)
 ✅ WaitForConditionAsync          ❌ Task.Delay / Thread.Sleep
 ✅ [LoggerMessage(...)]           ❌ _logger.LogInformation(...) / LogWarning / LogError / etc.
+✅ MultiTenancyConstants.*        ❌ Hardcoded "*DEFAULT*" / "default"
 ```
 
 ### Logging Pattern
@@ -82,6 +98,16 @@ Use this file for agent-only context: build and test commands, conventions, and
 - SSE not working: run `/frontend__debug_sse`
 - Cache issues: run `/cache__debug_cache`
 - Environment issues: run `/ops__doctor_check`
+- Playwright browser missing (integration tests fail with browser launch error): install browsers with `node tests/BookStore.AppHost.Tests/bin/Debug/net10.0/.playwright/package/index.js install chromium` (build the project first)
+
+## MCP Servers for Documentation
+
+Use MCP servers to get up-to-date documentation instead of relying on training data:
+
+- **Context7** (`mcp_context7_resolve-library-id` → `mcp_context7_get-library-docs`): Use for any library in the stack — Marten, Wolverine, Aspire, Refit, Bogus, TUnit, etc.
+- **Microsoft Learn** (`mcp_microsoftdocs_microsoft_docs_search` / `mcp_microsoftdocs_microsoft_docs_fetch`): Use for .NET, ASP.NET Core, Entity Framework, Azure, and any Microsoft technology.
+
+Always prefer MCP server lookups over guessing API shapes or behaviour from training data.
 
 ## Documentation Index
 

diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -38,6 +38,7 @@
     <PackageVersion Include="Microsoft.IdentityModel.Tokens" Version="8.15.0" />
     <PackageVersion Include="Microsoft.JSInterop" Version="10.0.2" />
     <PackageVersion Include="MimeKit" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.Playwright" Version="1.58.0" />
     <PackageVersion Include="MudBlazor" Version="8.15.0" />
     <PackageVersion Include="Npgsql" Version="10.0.1" />
     <PackageVersion Include="NSubstitute" Version="5.3.0" />
@@ -59,4 +60,4 @@
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.102" />
     <PackageVersion Include="Roslynator.Analyzers" Version="4.15.0" />
   </ItemGroup>
-</Project>
+</Project>
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -271,7 +271,7 @@ curl -H "Accept-Language: pt-PT" http://localhost:5000/api/categories
 -- Connect to the database via PgAdmin
 
 -- View all events
-SELECT 
+SELECT
     id,
     seq_id,
     type,
@@ -283,12 +283,12 @@ ORDER BY timestamp DESC
 LIMIT 10;
 
 -- View events for a specific correlation ID
-SELECT * FROM mt_events 
+SELECT * FROM mt_events
 WHERE correlation_id = 'getting-started-001'
 ORDER BY timestamp;
 
 -- View a specific stream
-SELECT * FROM mt_streams 
+SELECT * FROM mt_streams
 WHERE id = '<book-id>';
 ```
 
@@ -364,6 +364,18 @@ BookStore/
 
 The project uses **TUnit**, a modern testing framework for .NET with built-in code coverage and source-generated tests.
 
+### Playwright Browser Setup
+
+The integration tests (`BookStore.AppHost.Tests`) use **Microsoft.Playwright** for browser-based flows. Playwright browsers must be installed once after building the project:
+
+```bash
+dotnet build tests/BookStore.AppHost.Tests/BookStore.AppHost.Tests.csproj
+node tests/BookStore.AppHost.Tests/bin/Debug/net10.0/.playwright/package/index.js install chromium
+```
+
+> [!NOTE]
+> Re-run the install command after a `dotnet clean` or if you switch between `Debug` and `Release` configurations — the `.playwright` directory is regenerated by the build.
+
 ### Running Tests
 
 ```bash
@@ -451,7 +463,7 @@ curl http://localhost:5000/health
 
 **Error**: "Container runtime 'docker' was found but appears to be unhealthy"
 
-**Solution**: 
+**Solution**:
 1. Open Docker Desktop
 2. Wait for it to fully start
 3. Run `aspire run` again

diff --git a/src/BookStore.ApiService/AGENTS.md b/src/BookStore.ApiService/AGENTS.md
@@ -24,13 +24,16 @@
 
 **Error Handling**: Use `/lang__problem_details` skill for all errors. Return `Result.Failure(Error.<Type>(code, message)).ToProblemDetails()`.
 
+**CRITICAL**: ALL failures MUST return RFC 7807 ProblemDetails with a machine-readable error code. This includes endpoints, handlers, AND middleware. Never return plain JSON errors.
+
 ## Common Mistakes
 - ❌ Business logic in endpoints → Put logic in aggregates/handlers
 - ❌ Missing SSE notification → Add to `MartenCommitListener`
 - ❌ Missing cache invalidation → Call `RemoveByTagAsync` after mutations
 - ❌ Manually running Marten async daemon → Async projections are updated by Wolverine
 - ❌ Skipping tenant context → Use tenant-scoped sessions and cache keys
 - ❌ Ignoring ETag checks → Use `IHaveETag` and `ETagHelper`
+- ❌ Returning plain JSON errors → ALL failures must return ProblemDetails with error codes (endpoints, handlers, middleware)
 
 ## Project Layout
 | Path | Purpose |

diff --git a/src/BookStore.ApiService/BookStore.ApiService.csproj b/src/BookStore.ApiService/BookStore.ApiService.csproj
@@ -1,51 +1,52 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
-
-  <PropertyGroup>
-    <!-- Garbage Collection Optimization for Server Workloads -->
-    <!-- Server GC: Uses multiple heaps and threads for better throughput -->
-    <ServerGarbageCollection>true</ServerGarbageCollection>
-
-    <!-- Concurrent GC: Reduces pause times by running GC concurrently with application -->
-    <ConcurrentGarbageCollection>true</ConcurrentGarbageCollection>
-
-    <!-- Retain VM: Keeps virtual memory allocated for better performance -->
-    <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
-
-    <!-- Dynamic PGO: Profile-guided optimization for hot paths -->
-    <TieredCompilation>true</TieredCompilation>
-    <TieredCompilationQuickJit>true</TieredCompilationQuickJit>
-    <NoWarn>$(NoWarn);EXTEXP0018</NoWarn>
-    <Nullable>enable</Nullable>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\BookStore.ServiceDefaults\BookStore.ServiceDefaults.csproj" />
-    <ProjectReference Include="..\BookStore.ApiService.Analyzers\BookStore.ApiService.Analyzers.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
-    <ProjectReference Include="..\BookStore.Shared\BookStore.Shared.csproj" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Asp.Versioning.Http" />
-    <PackageReference Include="AspNetCore.HealthChecks.NpgSql" />
-    <PackageReference Include="Aspire.Azure.Storage.Blobs" />
-    <PackageReference Include="Aspire.StackExchange.Redis.DistributedCaching" />
-    <PackageReference Include="Bogus" />
-    <PackageReference Include="JasperFx.Core" />
-    <PackageReference Include="Marten" />
-    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" />
-    <PackageReference Include="Microsoft.AspNetCore.OpenApi" />
-    <PackageReference Include="Microsoft.Extensions.Caching.Hybrid" />
-    <PackageReference Include="Scalar.AspNetCore" />
-    <PackageReference Include="SkiaSharp" />
-    <PackageReference Include="SkiaSharp.NativeAssets.Linux.NoDependencies" />
-    <PackageReference Include="SkiaSharp.NativeAssets.macOS" />
-    <PackageReference Include="WolverineFx.Http" />
-    <PackageReference Include="WolverineFx.Marten" />
-    <PackageReference Include="MailKit" />
-    <PackageReference Include="MimeKit" />
-    <PackageReference Include="System.IdentityModel.Tokens.Jwt" />
-    <PackageReference Include="Microsoft.IdentityModel.Tokens" />
-    <PackageReference Include="Microsoft.IdentityModel.JsonWebTokens" />
-  </ItemGroup>
-
-</Project>
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <!-- Garbage Collection Optimization for Server Workloads -->
+    <!-- Server GC: Uses multiple heaps and threads for better throughput -->
+    <ServerGarbageCollection>true</ServerGarbageCollection>
+
+    <!-- Concurrent GC: Reduces pause times by running GC concurrently with application -->
+    <ConcurrentGarbageCollection>true</ConcurrentGarbageCollection>
+
+    <!-- Retain VM: Keeps virtual memory allocated for better performance -->
+    <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
+
+    <!-- Dynamic PGO: Profile-guided optimization for hot paths -->
+    <TieredCompilation>true</TieredCompilation>
+    <TieredCompilationQuickJit>true</TieredCompilationQuickJit>
+    <NoWarn>$(NoWarn);EXTEXP0018</NoWarn>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\BookStore.ServiceDefaults\BookStore.ServiceDefaults.csproj" />
+    <ProjectReference Include="..\BookStore.ApiService.Analyzers\BookStore.ApiService.Analyzers.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
+    <ProjectReference Include="..\BookStore.Shared\BookStore.Shared.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Npgsql" />
+    <PackageReference Include="Asp.Versioning.Http" />
+    <PackageReference Include="AspNetCore.HealthChecks.NpgSql" />
+    <PackageReference Include="Aspire.Azure.Storage.Blobs" />
+    <PackageReference Include="Aspire.StackExchange.Redis.DistributedCaching" />
+    <PackageReference Include="Bogus" />
+    <PackageReference Include="JasperFx.Core" />
+    <PackageReference Include="Marten" />
+    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" />
+    <PackageReference Include="Microsoft.Extensions.Caching.Hybrid" />
+    <PackageReference Include="Scalar.AspNetCore" />
+    <PackageReference Include="SkiaSharp" />
+    <PackageReference Include="SkiaSharp.NativeAssets.Linux.NoDependencies" />
+    <PackageReference Include="SkiaSharp.NativeAssets.macOS" />
+    <PackageReference Include="WolverineFx.Http" />
+    <PackageReference Include="WolverineFx.Marten" />
+    <PackageReference Include="MailKit" />
+    <PackageReference Include="MimeKit" />
+    <PackageReference Include="System.IdentityModel.Tokens.Jwt" />
+    <PackageReference Include="Microsoft.IdentityModel.Tokens" />
+    <PackageReference Include="Microsoft.IdentityModel.JsonWebTokens" />
+  </ItemGroup>
+
+</Project>