[Feature] Stage 01: foundation

.editorconfig

@@ -32,6 +32,16 @@ csharp_prefer_system_threading_lock = true:suggestion
 # IDE0005 also keeps the centralized import set free of unused directives.
 dotnet_diagnostic.IDE0005.severity = error
 
+# Public API documentation is mandatory. Every public member must document its
+# summary, parameters, generic parameters, exceptions, and relevant remarks.
+dotnet_diagnostic.CS1591.severity = warning
+dotnet_diagnostic.CS1572.severity = warning
+dotnet_diagnostic.CS1573.severity = warning
+dotnet_diagnostic.CS1712.severity = warning
+dotnet_diagnostic.CS1574.severity = warning
+dotnet_diagnostic.CS1587.severity = warning
+dotnet_diagnostic.CS1591.severity = warning
+
 [*.csproj]
 dotnet_diagnostic.IDE0055.severity = error
 

.github/workflows/CI-CT-CD.yml

@@ -0,0 +1,139 @@
+name: CI - CT - CD
+
+on:
+  push:
+    branches: [main]
+    tags: [v*]
+  pull_request:
+    types: [opened, synchronize]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Continuous Integration
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: 10.0.*
+      - name: Restore
+        run: dotnet restore SPInvisivel.slnx
+      - name: Build
+        run: dotnet build SPInvisivel.slnx --configuration Release --no-restore
+
+  tests:
+    name: Continuous Testing
+    runs-on: ubuntu-latest
+    needs: build
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: 10.0.*
+      - name: Restore
+        run: dotnet restore ${{ github.workspace }}/tests/InvisibleSP.UnitTests/InvisibleSP.UnitTests.csproj
+      - name: Install ReportGenerator
+        run: dotnet tool install --global dotnet-reportgenerator-globaltool --version 5.5.11
+
+      - name: Test with Coverlet
+        id: test
+        shell: pwsh
+        continue-on-error: true
+        run: |
+          New-Item -ItemType Directory -Force -Path artifacts/test-results | Out-Null
+          $outputFile = Join-Path $env:GITHUB_WORKSPACE 'artifacts/test-output.txt'
+          & dotnet test $env:GITHUB_WORKSPACE/tests/InvisibleSP.UnitTests/InvisibleSP.UnitTests.csproj `
+            --configuration Release `
+            --no-restore `
+            --collect:"XPlat Code Coverage" `
+            --results-directory $env:GITHUB_WORKSPACE/artifacts/test-results `
+            --logger "trx;LogFileName=test-results.trx" 2>&1 | Tee-Object -FilePath $outputFile
+          $exitCode = $LASTEXITCODE
+          "dotnet test exit code: $exitCode" | Add-Content -Path $outputFile
+          "TEST_EXIT_CODE=$exitCode" | Out-File -FilePath artifacts/test-exit-code.txt -Encoding utf8
+
+      - name: Publish Test Summary
+        uses: dorny/test-reporter@v1
+        if: always()
+        with:
+          name: 'Continuous Test Results'
+          path: './artifacts/test-results/*.trx'
+          reporter: 'dotnet-trx'
+
+      - name: Generate coverage report
+        if: always()
+        shell: pwsh
+        run: |
+          New-Item -ItemType Directory -Force -Path artifacts/coverage | Out-Null
+          $coverageFiles = @(Get-ChildItem -Path artifacts/test-results -Filter coverage.cobertura.xml -Recurse -File -ErrorAction SilentlyContinue)
+          if ($coverageFiles.Count -gt 0) {
+            reportgenerator -reports:"artifacts/test-results/**/coverage.cobertura.xml" -targetdir:"artifacts/coverage" -reporttypes:"MarkdownSummary;Cobertura"
+          } else {
+            "# Coverage report unavailable`n`nCoverlet did not produce a coverage XML file." | Out-File artifacts/coverage/Summary.md -Encoding utf8
+          }
+
+      - name: Enforce 80 percent line and branch coverage
+        if: always()
+        shell: pwsh
+        run: |
+          $coverageFiles = @(Get-ChildItem -Path "$env:GITHUB_WORKSPACE/artifacts/test-results" -Directory -ErrorAction SilentlyContinue | ForEach-Object {
+            Get-ChildItem -Path $_.FullName -Filter coverage.cobertura.xml -File -ErrorAction SilentlyContinue
+          })
+
+          if ($coverageFiles.Count -eq 0) {
+            "## Coverage gate`n`nNo Coverlet XML was found under the test-results GUID subdirectories." | Out-File $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
+            return
+          }
+
+          $coverageFile = $coverageFiles | Select-Object -First 1
+          [xml]$coverage = Get-Content $coverageFile.FullName
+          $lineRate = [double]$coverage.coverage.'line-rate' * 100
+          $branchRate = [double]$coverage.coverage.'branch-rate' * 100
+
+          if ($lineRate -ge 80 -and $branchRate -ge 80) {
+            "## ✅ **Coverage threshold passed!**`n`n### Achieved `n**Line $([math]::Round($lineRate, 2))%**`n**Branch $([math]::Round($branchRate, 2))%**" | Out-File $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
+          } else {
+            "## ❌ Coverage threshold failed`n`nRequired: line >= 80% and branch >= 80%. Actual: **line $([math]::Round($lineRate, 2))%**, **branch $([math]::Round($branchRate, 2))%**." | Out-File $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
+          }
+
+          @"
+
+          ## Coverage gate
+
+          | Metric | Result | Minimum |
+          | --- | ---: | ---: |
+          | Line coverage | $([math]::Round($lineRate, 2))% | 80% |
+          | Branch coverage | $([math]::Round($branchRate, 2))% | 80% |
+
+          "@ | Out-File $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
+
+      - name: Append test execution report
+        if: always()
+        shell: pwsh
+        run: if (Test-Path artifacts/coverage/Summary.md) { Get-Content artifacts/coverage/Summary.md | Add-Content $env:GITHUB_STEP_SUMMARY } else { Add-Content $env:GITHUB_STEP_SUMMARY 'Coverage report was not generated.' }
+
+      - name: Upload test and coverage reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: Continuous-Testing-Reports
+          path: artifacts/
+          if-no-files-found: warn
+
+      - name: Fail if tests failed
+        if: always()
+        shell: pwsh
+        run: |
+          if (Test-Path artifacts/test-exit-code.txt) {
+            $exitCode = [int](Get-Content artifacts/test-exit-code.txt -Raw).Replace('TEST_EXIT_CODE=', '').Trim()
+            if ($exitCode -ne 0) { Write-Error "dotnet test failed with exit code $exitCode." }
+          }

.gitignore

@@ -485,3 +485,5 @@ $RECYCLE.BIN/
 
 # Vim temporary swap files
 *.swp
+/workload-install.ps1
+/workload-install.ps1

ARCHITECTURE.md

@@ -85,10 +85,28 @@ The feature name should represent the aggregate/use-case boundary. `Common` is a
 - Use explicit `using` aliases in `GlobalUsings.cs` when namespaces expose ambiguous type names.
 - Prefer modern C#/.NET 10 language and BCL APIs when they improve correctness, clarity, performance, or maintainability.
 - Prefer async APIs for I/O-bound operations and propagate `CancellationToken` through application and infrastructure boundaries.
-- Avoid service-locator patterns and direct `IServiceProvider` resolution in application/domain code.
-- Keep public APIs documented when they are part of a reusable abstraction or library boundary.
+- Avoid service-locator patterns and direct `IServiceProvider` resolution in application/domain code except for isolated infrastructure adapters whose responsibility is explicitly to bridge a third-party pipeline into the application abstraction.
 - Do not introduce nullable suppression (`!`) without a concrete invariant that makes the value safe.
 
+## XML documentation
+
+Every public type and public member in every C# project, including test projects, must have XML documentation.
+
+Documentation is part of the public API contract and must contain, when applicable:
+
+- `<summary>` — what the type/member does and its responsibility.
+- `<typeparam>` — every generic type parameter.
+- `<param>` — every method, constructor, indexer, or delegate parameter.
+- `<returns>` — the returned value for methods/functions that return a value or task result.
+- `<exception>` — every exception that callers can reasonably encounter as part of the documented contract.
+- `<remarks>` — important invariants, lifecycle requirements, security considerations, side effects, threading behavior, or usage constraints that are not appropriate for the summary.
+
+Use `<inheritdoc />` when the inherited/interface documentation completely describes the public member and no additional contract information is necessary. Do not use empty documentation merely to silence an analyzer.
+
+XML documentation must describe the behavior of the implementation rather than restating the member name. Public API changes must update their documentation in the same change.
+
+The compiler XML documentation diagnostics are enabled in `.editorconfig`; malformed or incomplete parameter/type-parameter documentation must not be introduced.
+
 ## Dependency injection
 
 - Register dependencies in `InvisibleSP.Composition`.
@@ -112,10 +130,20 @@ A handler should orchestrate a use case rather than become a persistence abstrac
 - Avoid anemic domain models when business invariants can naturally be expressed in the domain layer.
 - Domain events represent meaningful domain occurrences; application/infrastructure concerns subscribe through appropriate abstractions.
 
+## Testing and coverage
+
+- Every production feature must have unit tests in `tests/InvisibleSP.UnitTests` unless a documented architectural reason makes a unit test inappropriate.
+- Unit tests use xUnit v3, FluentAssertions, and `coverlet.collector`.
+- Tests must exercise both success and failure paths, including meaningful branch conditions.
+- The CI test job must collect line and branch coverage from Coverlet's XML output.
+- Minimum required coverage is **80% lines and 80% branches** for the code included in the coverage report.
+- Coverage thresholds are enforced by CI; a test run below either threshold fails the job.
+- Coverage reports must be rendered as Markdown and appended to the GitHub Actions job summary so the agent can inspect the measured line and branch percentages.
+
 ## Global build enforcement
 
-`Directory.Build.props` establishes the shared .NET 10 compiler/analyzer defaults for all projects beneath the repository root.
+`Directory.Build.props` establishes the shared .NET 10 compiler/analyzer defaults for all projects beneath the repository root and generates XML documentation files.
 
 `Directory.Build.targets` validates that every C# project has a root-level `GlobalUsings.cs` before compilation.
 
-The repository `.editorconfig` enforces file-scoped namespaces and centralized import conventions. Build-time analyzers are enabled so code-style and analyzer feedback is visible during builds.
+The repository `.editorconfig` enforces file-scoped namespaces, centralized import conventions, and XML documentation diagnostics for public APIs. Build-time analyzers are enabled so code-style and analyzer feedback is visible during builds.

Directory.Build.props

@@ -7,6 +7,6 @@
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisLevel>latest-recommended</AnalysisLevel>
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
-    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <GenerateDocumentationFile>false</GenerateDocumentationFile>
   </PropertyGroup>
 </Project>

Directory.Build.targets

@@ -4,4 +4,18 @@
       Condition="!Exists('$(MSBuildProjectDirectory)/GlobalUsings.cs')"
       Text="$(MSBuildProjectName): GlobalUsings.cs is required at the project root. Add all project-wide using directives there and do not add using directives to individual source files." />
   </Target>
+
+  <Target Name="GenerateXmlDocumentation"
+          AfterTargets="CoreCompile"
+          Condition="'$(Configuration)' == 'Release' and '$(IsTestProject)' != 'true' and '$(GenerateDocumentationFile)' == 'true'">
+    <MakeDir Directories="$(MSBuildThisFileDirectory)docs-gen" />
+    <Copy SourceFiles="$(DocumentationFile)"
+          DestinationFiles="$(MSBuildThisFileDirectory)docs-gen/$(AssemblyName).xml"
+          SkipUnchangedFiles="true" />
+  </Target>
+
+  <PropertyGroup Condition="'$(Configuration)' == 'Release' and '$(IsTestProject)' != 'true'">
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <DocumentationFile>$(MSBuildProjectDirectory)/obj/$(Configuration)/$(TargetFramework)/$(AssemblyName).xml</DocumentationFile>
+  </PropertyGroup>
 </Project>

SPInvisivel.slnx

@@ -1,9 +1,12 @@
-<Solution>
-  <Folder Name="/src/">
-    <Project Path="src/InvisibleSP.Application/InvisibleSP.Application.csproj" />
-    <Project Path="src/InvisibleSP.Composition/InvisibleSP.Composition.csproj" />
-    <Project Path="src/InvisibleSP.Domain/InvisibleSP.Domain.csproj" />
-    <Project Path="src/InvisibleSP.Infrastructure/InvisibleSP.Infrastructure.csproj" />
-    <Project Path="src/InvisibleSP/InvisibleSP.csproj" />
-  </Folder>
-</Solution>
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/InvisibleSP.Application/InvisibleSP.Application.csproj" />
+    <Project Path="src/InvisibleSP.Composition/InvisibleSP.Composition.csproj" />
+    <Project Path="src/InvisibleSP.Domain/InvisibleSP.Domain.csproj" />
+    <Project Path="src/InvisibleSP.Infrastructure/InvisibleSP.Infrastructure.csproj" />
+    <Project Path="src/InvisibleSP/InvisibleSP.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/InvisibleSP.UnitTests/InvisibleSP.UnitTests.csproj" />
+  </Folder>
+</Solution>

docs/architecture.md

@@ -0,0 +1,57 @@
+# SP Invisível Architecture
+
+## Solution layers
+
+The solution is a feature-oriented DDD application with the following dependency direction:
+
+`InvisibleSP` → `InvisibleSP.Composition` → `InvisibleSP.Infrastructure` → `InvisibleSP.Application` → `InvisibleSP.Domain`
+
+`InvisibleSP.Application` may reference `InvisibleSP.Domain` directly. `InvisibleSP.Domain` must remain independent of the other solution projects.
+
+### `src/InvisibleSP.Domain`
+
+Contains domain entities, value objects, domain events, rules, and domain abstractions. It must not reference ASP.NET Core, Entity Framework Core, Identity, HTTP, UI, logging infrastructure, or persistence implementations.
+
+### `src/InvisibleSP.Application`
+
+Contains use-case contracts and orchestration: requests, responses, handlers, validators, application abstractions, and pipeline behavior. It depends on domain concepts and abstractions, not infrastructure implementations.
+
+### `src/InvisibleSP.Infrastructure`
+
+Contains technical implementations: Entity Framework Core persistence, Identity-like authentication infrastructure, JWT services, external integrations, and concrete implementations of application abstractions.
+
+### `src/InvisibleSP.Composition`
+
+Owns dependency injection and HTTP/application composition. It provides the application service-registration extension and the HTTP pipeline extension. Application and domain code must never depend on this project.
+
+### `src/InvisibleSP`
+
+Is the presentation and entry-point project. It contains Blazor Interactive Server UI and controllers. Controllers translate HTTP requests into application requests and must not access `DbContext` or repositories directly.
+
+## Feature boundaries
+
+Features are grouped by business/use-case boundary. `Common` is reserved for types genuinely shared across multiple features. Avoid global technical folders that mix unrelated features.
+
+## Identity boundary
+
+Identity behavior is implemented by `InvisibleSP.Infrastructure.Identity.Services.IdentityService` and related infrastructure types. Application contracts expose identity operations through `IIdentityService`. Tests must target this implementation contract and its actual Identity configuration.
+
+Two-factor authentication uses the Identity authenticator token provider and an authenticator shared key. A TOTP code is generated from that key by the authenticator/client side and passed back to the service for validation.
+
+## Persistence
+
+`InvisibleSPDbContext` derives from the Identity EF Core context and owns persistence configuration. Types implementing `ISoftDeletable` receive a query filter and deleted entities are converted to updates by the save pipeline.
+
+## Composition
+
+Dependency registration belongs in `InvisibleSP.Composition`. Presentation startup calls the composition extension instead of duplicating registrations. Application handlers depend on application abstractions and infrastructure supplies their implementations.
+
+## Tests
+
+`tests/InvisibleSP.UnitTests` contains unit and infrastructure-backed tests for the production layers. It uses EF Core InMemory for persistence-focused scenarios and the real Identity implementation for identity behavior. Tests are excluded from Release XML documentation publication but are still required to contain XML documentation for public types and members.
+
+## Build documentation
+
+`Directory.Build.props` establishes common .NET 10 settings. `Directory.Build.targets` validates `GlobalUsings.cs` and defines `GenerateXmlDocumentation` for Release production builds. Generated XML files are copied to `docs-gen/` at repository root.
+
+The `docs/` directory is reserved for human- and agent-authored documentation and must never be used as the generated XML output directory.

docs/coding-style.md

@@ -0,0 +1,42 @@
+# C# Coding Style
+
+## Language
+
+- Target .NET 10.
+- Use current C# language features when they improve clarity and correctness.
+- Enable nullable reference types.
+- Prefer `async` APIs for I/O and propagate `CancellationToken` through application and infrastructure boundaries.
+- Avoid unnecessary nullable suppression (`!`).
+
+## Namespaces and imports
+
+- Use file-scoped namespaces.
+- Individual C# source files must not contain `using` directives.
+- Project-wide imports belong in the root `GlobalUsings.cs`.
+- Keep global imports minimal and use aliases when necessary to resolve ambiguous types.
+
+## API design
+
+- Prefer constructor injection.
+- Keep public APIs small and intentional.
+- Use records for immutable request/response contracts where appropriate.
+- Keep domain invariants in the domain model whenever practical.
+- Keep transport concerns in presentation and technical concerns in infrastructure.
+
+## XML documentation
+
+Public APIs must document their contract. Use `<summary>`, `<param>`, `<typeparam>`, `<returns>`, `<exception>`, and `<remarks>` when applicable. Documentation should explain behavior, constraints, and side effects rather than repeat the identifier name.
+
+Use `<inheritdoc />` for complete inherited/interface contracts. Do not use placeholder text or empty XML elements.
+
+## Formatting
+
+Follow the repository `.editorconfig`: four-space indentation for C#, LF line endings, file-scoped namespaces, braces for control flow, and centralized imports. Keep code readable rather than optimizing for compressed one-line expressions.
+
+## Dependency injection
+
+Register dependencies in `InvisibleSP.Composition`. Prefer abstractions at application boundaries. Choose service lifetimes intentionally: singleton for safe shared state/stateless thread-safe services, scoped for request/unit-of-work services, and transient for lightweight stateless services when justified.
+
+## Tests
+
+Name tests by behavior and expected outcome. Prefer one behavioral assertion group per scenario. Exercise both success and meaningful failure branches. Use the real production implementation when the purpose of the test is to validate that implementation.