@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/standards/ai-agents/modalities-text-to-speech.md

@@ -58,17 +58,11 @@ public sealed class TextToSpeechService
 
     public TextToSpeechService(IConfiguration config)
     {
-        // tts-1: mais rápido, menor qualidade. tts-1-hd: mais lento, maior qualidade.
         var model = config["TTS:Model"] ?? "tts-1";
         var apiKey = config["OpenAI:ApiKey"]!;
         _client = new AudioClient(model, apiKey);
     }
 
-    /// <summary>
-    /// Converte texto em áudio e retorna bytes MP3.
-    /// Cachear o resultado é altamente recomendado para textos repetitivos — gerar o mesmo texto
-    /// duas vezes é desperdício de custo e latência.
-    /// </summary>
     public async Task<BinaryData> SynthesizeAsync(
         string text,
         GeneratedSpeechVoice? voice = null,
@@ -91,14 +85,13 @@ public sealed class TextToSpeechService
 }
 ```
 
-**Registro DI:**
+**Registro DI** (`Program.cs`):
 
 ```csharp
-// Program.cs
 builder.Services.AddSingleton<TextToSpeechService>();
 ```
 
-**Servindo como download ou stream:**
+**Servindo como download ou stream** — verifique o cache antes de gerar (ver Anti-patterns):
 
 ```csharp
 public class AudioController(TextToSpeechService tts) : ControllerBase
@@ -106,14 +99,12 @@ public class AudioController(TextToSpeechService tts) : ControllerBase
     [HttpPost("synthesize")]
     public async Task<IActionResult> Synthesize([FromBody] SynthesizeRequest req)
     {
-        // Verificar cache antes de gerar (ver Anti-patterns)
         BinaryData audio = await tts.SynthesizeAsync(
             text:       req.Text,
             voice:      GeneratedSpeechVoice.Nova,
             format:     GeneratedSpeechFormat.Mp3,
             speedRatio: 1.1f);
 
-        // the storage layer may assign the final name; use a timestamp-based name here
         var fileName = $"tts-{DateTime.UtcNow:yyyyMMddHHmmss}.mp3";
         return File(audio.ToStream(), "audio/mpeg", fileName);
     }

package/framework/standards/ai-agents/modalities-vision.md

@@ -31,7 +31,6 @@ Vision em MAF usa `ChatMessage` multimodal — a mesma abstração `IChatClient`
 ```csharp
 using Microsoft.Extensions.AI;
 
-// Constrói um ChatMessage com texto + imagem
 ChatMessage message = new(ChatRole.User, [
     new TextContent("O que aparece nesta imagem?"),
     new UriContent(new Uri("https://example.com/foto.jpg"), "image/jpeg")
@@ -59,7 +58,7 @@ O `IChatClient` (e portanto `AIAgent`) aceita `IEnumerable<ChatMessage>` — voc
 
 ## Exemplo C# completo
 
-Agente de visão que recebe URL de imagem e retorna descrição. Para extração de dados tipados de um documento, combine com `RunAsync<T>` (ver comentário inline).
+Agente de visão que recebe URL de imagem e retorna descrição. Três entradas: URL pública, arquivo local via `DataContent.LoadFromAsync` (o padrão canônico MAF, preferido sempre que houver o caminho do arquivo) e bytes já em memória (ex: upload de usuário já lido). Para extração de dados tipados de um documento, combine com `RunAsync<T>` em vez de `RunAsync` — `AgentResponse<InvoiceData> r = await _agent.RunAsync<InvoiceData>(message);` e `return r.Result;` —, com o padrão completo em `ai-agents-structured-output`.
 
 ```csharp
 using Microsoft.Agents.AI;
@@ -84,7 +83,6 @@ public sealed class VisionAgent
         });
     }
 
-    /// <summary>Analisa uma imagem por URL pública e retorna descrição em texto.</summary>
     public async Task<string> AnalyzeImageUrlAsync(Uri imageUri, string question, CancellationToken ct = default)
     {
         ChatMessage message = new(ChatRole.User, [
@@ -96,14 +94,6 @@ public sealed class VisionAgent
         return response.Text;
     }
 
-    /// <summary>
-    /// Analisa imagem a partir de um arquivo local ou caminho de upload.
-    /// Usa DataContent.LoadFromAsync — padrão canônico MAF para carregar imagem de arquivo.
-    /// Para extrair dados tipados, use RunAsync&lt;T&gt; em vez de RunAsync:
-    ///   AgentResponse&lt;InvoiceData&gt; r = await _agent.RunAsync&lt;InvoiceData&gt;(message);
-    ///   return r.Result;
-    /// Veja ai-agents-structured-output para o padrão completo.
-    /// </summary>
     public async Task<string> AnalyzeImageFileAsync(string filePath, string question, CancellationToken ct = default)
     {
         DataContent imageContent = await DataContent.LoadFromAsync(filePath);
@@ -116,10 +106,6 @@ public sealed class VisionAgent
         return response.Text;
     }
 
-    /// <summary>
-    /// Analisa imagem a partir de bytes já em memória (ex: upload de usuário já lido).
-    /// Use AnalyzeImageFileAsync quando tiver o caminho do arquivo — é o padrão preferido.
-    /// </summary>
     public async Task<string> AnalyzeImageBytesAsync(BinaryData imageData, string mediaType, string question, CancellationToken ct = default)
     {
         ChatMessage message = new(ChatRole.User, [
@@ -138,17 +124,14 @@ public sealed class VisionAgent
 ```csharp
 var agent = new VisionAgent(modelRegistry);
 
-// Por URL pública
 string desc = await agent.AnalyzeImageUrlAsync(
     new Uri("https://cdn.example.com/invoice-2024.jpg"),
     "Extraia os campos: número da nota, valor total e data de emissão.");
 
-// Por arquivo local — padrão canônico com DataContent.LoadFromAsync
 string desc2 = await agent.AnalyzeImageFileAsync(
     "nota-fiscal.png",
     "Liste todos os itens e valores desta nota fiscal.");
 
-// Por bytes em memória (ex: upload já lido de IFormFile)
 BinaryData data = await BinaryData.FromStreamAsync(formFile.OpenReadStream());
 string desc3 = await agent.AnalyzeImageBytesAsync(data, "image/png",
     "Descreva o conteúdo da imagem enviada.");

package/framework/standards/ai-agents/prompt-sources.md

@@ -113,10 +113,6 @@ Interface contract:
 ```csharp
 public interface IPromptRepository
 {
-    /// <summary>
-    /// Returns the content of the currently active prompt for the given agent key.
-    /// Throws <see cref="InvalidOperationException"/> if no active prompt exists.
-    /// </summary>
     Task<string> GetActivePromptAsync(string agentKey, CancellationToken ct = default);
 }
 ```

package/framework/standards/ai-agents/testing-ai.md

@@ -12,7 +12,8 @@
 ## Fronteira com o testing genérico
 
 `backend-dotnet-testing` continua dono do que é de teste em .NET: xUnit, `FakeTimeProvider`,
-isolamento entre casos, nomes de teste, organização de fixtures. **Nada disso se repete aqui.**
+isolamento entre casos, nomes de teste, organização de fixtures e o orçamento de teste por task.
+**Nada disso se repete aqui.**
 
 Este standard cobre **só o que é de agente** — e o que é de agente cabe em uma frase: o único ponto
 em que o seu código toca um provider é um `IChatClient`. Todo o resto deste arquivo é consequência

package/framework/standards/architecture/code-comments.md

@@ -0,0 +1,100 @@
+# Comentários no código
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** comentário, comentario, comment, docstring, jsdoc, xml doc, história da task, código autoexplicativo
+> **Load When:** escrevendo ou revisando código em qualquer stack
+
+**Verified against:** C#, TypeScript e JavaScript (convenção de linguagem, sem pacote externo). Last-verified: 2026-09-24.
+
+---
+
+**O padrão é nenhum comentário.** O código se explica pelos nomes, pelos tipos e pelos testes. Um
+comentário é relido a cada leitura do arquivo, por quem mantém e pelo agente que abre o arquivo na
+próxima task, e ninguém o atualiza quando o código muda. Ele só entra quando diz algo que o código
+**não consegue** dizer, e isso é raro: a maioria dos arquivos não tem nenhum.
+
+## Antes de escrever um comentário
+
+Tente, nesta ordem, e pare no primeiro que resolve:
+
+| Em vez de comentar... | Faça |
+|---|---|
+| o que uma variável ou função é | renomeie: `retryDelayMs`, `isEligibleForRefund()` |
+| o que um trecho faz | extraia uma função com esse nome |
+| um número ou string mágica | extraia uma constante nomeada |
+| um estado que não pode acontecer | expresse no tipo (enum, união, record, `required`) |
+| o que o código garante | escreva um teste que falha quando deixar de valer |
+
+Só sobrando algo que nenhum desses expressa, o comentário entra.
+
+## O que merece comentário
+
+Só o **porquê que o código não mostra**:
+
+| Merece | Exemplo |
+|---|---|
+| Invariante que o tipo não expressa | "a chave é a identidade e o hash é a versão" |
+| Ordem que importa | "invalidar o cache ANTES de publicar: o consumidor relê na hora" |
+| Peculiaridade externa | API de terceiro que devolve 200 com erro no corpo; bug de biblioteca, com o link |
+| Contrato de pacote publicado | `///` ou JSDoc só em API de pacote consumido **fora** deste repositório (NuGet, npm) |
+
+## O que não merece
+
+- **História de processo.** Task, UC, ADR, FR, Gate, avaliador, `spec.md`, mockup, "confirmado ao
+  implementar a T11", "o Gate 3 pediu". Isso vai na mensagem de commit e no `decisions.md`, onde tem
+  data e autor e não envelhece dentro do arquivo.
+- **Repetição do código.** `// incrementa o contador` sobre `count++`, `// valida o request` sobre
+  `validator.Validate(request)`. Nome bom substitui comentário.
+- **Doc-comment que repete a assinatura.** `/// <summary>Obtém o pedido.</summary>` sobre
+  `GetOrder()`, JSDoc com `@param id o id`. Membro de aplicação (handler, endpoint, componente,
+  serviço interno) não leva `///` nem JSDoc, mesmo sendo `public`.
+- **Estrutura e decoração.** Cabeçalho de arquivo, banner de seção (`// ---- Handlers ----`,
+  `#region`), comentário que só rotula o bloco seguinte.
+- **Código comentado e TODO solto.** O git guarda o código antigo; pendência vira issue, e o
+  comentário, se ficar, cita o número dela.
+- **Estado do mundo fora do arquivo.** "Public Sans é a fonte da interface" passa a mentir na
+  primeira troca de fonte, e nada avisa.
+- **Afirmação sobre comportamento.** "nunca retorna vazio", "ordenado por sobrenome": isso é
+  asserção de teste. A prosa não falha quando deixa de ser verdade; o teste falha.
+
+## Tamanho
+
+Uma linha é o normal; teto de ~3. Acima disso o comentário justifica o volume (algoritmo não
+óbvio, armadilha de terceiro com a reprodução). Bloco longo narrando decisões é `decisions.md` com
+outro nome. Em volume, código de aplicação fica perto de zero: mais de uma linha de comentário a
+cada dez de código é sinal de que os nomes não estão fazendo o trabalho.
+
+## Exemplo
+
+```ts
+// Ruim: rotula, conta a task, repete o código e afirma comportamento que nenhum teste cobra.
+/**
+ * Salva o documento.
+ * @param doc o documento
+ */
+// T8 + T11: mutação obrigatória do relatório, item c. Faz upsert e nunca duplica.
+async function save(doc: Doc) {
+  await upsert({ key: doc.sourceId, hash: sha256(doc.body) });
+}
+
+// Bom: sem comentário nenhum, porque o nome e a chamada já dizem tudo...
+async function save(doc: Doc) {
+  await upsert({ key: doc.sourceId, hash: sha256(doc.body) });
+}
+
+// ...e um comentário só quando há um porquê invisível.
+// A chave é a identidade e o hash é a versão: hash novo na mesma chave substitui.
+await upsert({ key: doc.sourceId, hash: sha256(doc.body) });
+```
+
+## Na revisão
+
+Comentário que o código dispensava é achado da rubrica `code-quality` no Gate 3. O nó `validators`
+do `morph-spec verify` mede, nas linhas que a feature adicionou (validador `code-budget`), quantas
+linhas de comentário citam processo e a densidade de comentário sobre o código adicionado, e avisa
+com os números e os arquivos mais comentados.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/backend/dotnet/testing.md

@@ -113,6 +113,28 @@ respectively and the test suite stays green.
 
 ---
 
+## Test budget
+
+The plan (`morph-plan`) gives each task a budget: **one test per postcondition, plus one
+regression test per bug fixed**. Going above it takes a one-line justification in the task.
+
+- **Table before copy.** Scenarios of the same behavior — including its edge cases (null, empty,
+  boundary) — are rows of one `[Theory]` (`[InlineData]`/`[MemberData]`), never N `[Fact]` methods
+  that differ by one value.
+- **No test that only pins text.** An assertion that is only the presence or absence of a string in
+  UI copy, tenant config or prose proves the file's version, not behavior. Enforce it with an
+  analyzer, a lint rule or a validation at publish time, outside the suite count. The versioned
+  prompt case (at most one structural test) is `ai-agents-testing-ai`.
+- **Shared fixture by default.** Reuse the project's `WebApplicationFactory` fixture, fakes and
+  builders. Before writing a new helper, look for the existing one (`morph-spec graph explain
+  <Name>`; fallback without a graph: `grep -rn`).
+- **TDD where it pays:** a bug gets its regression test first (red, then the fix), and so does pure
+  logic. Integration and endpoint tests may come after the code.
+- **A surviving mutant** of the Gate 3 mutation proof is killed by tightening an existing assertion
+  or adding a table row, not by one new test per mutant.
+
+---
+
 ## Anti-Patterns
 
 | Do NOT | Do Instead |

package/framework/standards/backend/integrations/neon-auth/neon-auth.md

@@ -125,16 +125,19 @@ real sign-in attempt, not after debugging a mysterious "session never sticks" bu
 
 ### SDK Initialization
 
+`lib/auth/client.ts` — `createAuthClient` takes the public auth URL as a positional argument, and the
+React hooks are re-exported from the client instance for ergonomic imports:
+
 ```typescript
-// lib/auth/client.ts
 'use client';
 import { createAuthClient } from '@neondatabase/auth/next';
-// createAuthClient takes the public auth URL as a positional argument
 export const authClient = createAuthClient(process.env.NEXT_PUBLIC_AUTH_URL!);
-// Re-export the React hooks from the client instance for ergonomic imports
 export const { useSession } = authClient;
+```
+
+`lib/auth/server.ts`:
 
-// lib/auth/server.ts
+```typescript
 import { createNeonAuth } from '@neondatabase/auth/next/server';
 export const auth = createNeonAuth({
   baseUrl: process.env.NEON_AUTH_BASE_URL!,
@@ -152,8 +155,9 @@ Import the Tailwind styles for the UI components in `globals.css`:
 @import '@neondatabase/auth-ui/tailwind';
 ```
 
+`app/providers.tsx`:
+
 ```tsx
-// app/providers.tsx
 'use client';
 import { NeonAuthUIProvider } from '@neondatabase/auth-ui';
 import { authClient } from '@/lib/auth/client';
@@ -169,8 +173,9 @@ export function Providers({ children }: { children: React.ReactNode }) {
 
 ### Auth API Route
 
+`app/api/auth/[...path]/route.ts`:
+
 ```typescript
-// app/api/auth/[...path]/route.ts
 import { auth } from '@/lib/auth/server';
 
 export const { GET, POST } = auth.handler();
@@ -182,8 +187,9 @@ export const { GET, POST } = auth.handler();
 
 ### Sign In / Sign Up Pages
 
+`app/auth/sign-in/page.tsx`:
+
 ```tsx
-// app/auth/sign-in/page.tsx
 import { AuthView } from '@neondatabase/auth-ui';
 
 export default function SignInPage() {
@@ -193,8 +199,11 @@ export default function SignInPage() {
     </div>
   );
 }
+```
+
+`app/auth/sign-up/page.tsx`:
 
-// app/auth/sign-up/page.tsx
+```tsx
 import { AuthView } from '@neondatabase/auth-ui';
 
 export default function SignUpPage() {
@@ -208,8 +217,9 @@ export default function SignUpPage() {
 
 ### Server-Side Auth Check
 
+`app/dashboard/page.tsx`:
+
 ```typescript
-// app/dashboard/page.tsx
 import { auth } from '@/lib/auth/server';
 import { redirect } from 'next/navigation';
 
@@ -228,8 +238,9 @@ export default async function DashboardPage() {
 
 ### Client Component with User Data
 
+`components/UserProfile.tsx`:
+
 ```tsx
-// components/UserProfile.tsx
 'use client';
 import { useSession } from '@/lib/auth/client';
 
@@ -249,14 +260,15 @@ export function UserProfile() {
 
 ### Route Protection (Middleware)
 
+`middleware.ts`. The `runtime = 'nodejs'` line is **mandatory** for any `middleware.ts` that touches
+Neon Auth: Next.js middleware runs on the Edge runtime by default, and the network call the Neon Auth
+SDK makes to mint the session-data cookie times out inside the Edge sandbox on `next dev` — the request
+silently bounces back to sign-in even with a fully valid session, with no error surfaced.
+
 ```typescript
-// middleware.ts
 import { auth } from '@/lib/auth/server';
 
-// MANDATORY for any middleware.ts that touches Neon Auth. Next.js middleware runs on the Edge
-// runtime by default, and the network call the Neon Auth SDK makes to mint the session-data cookie
-// times out inside the Edge sandbox on `next dev` — the request silently bounces back to sign-in
-// even with a fully valid session, with no error surfaced. Force the Node.js runtime instead.
+// Mandatory: on the Edge runtime the SDK's session-cookie call times out and silently bounces to sign-in.
 export const runtime = 'nodejs';
 
 export default auth.middleware({
@@ -294,7 +306,6 @@ export default function ProtectedPage() {
 ## OAuth (Social Login)
 
 ```typescript
-// Trigger OAuth sign-in
 await authClient.signIn.social({
   provider: 'google',
   callbackURL: 'http://localhost:3000/auth/callback',
@@ -307,8 +318,9 @@ Configure OAuth providers in the Neon Console under Auth > Configuration.
 
 ## API Route Protection
 
+`app/api/protected/route.ts`:
+
 ```typescript
-// app/api/protected/route.ts
 import { auth } from '@/lib/auth/server';
 
 export const dynamic = 'force-dynamic';
@@ -348,34 +360,38 @@ backend's real prefix and the proxy's public prefix don't happen to match charac
 because this is a runtime routing mismatch (404, or the proxy calling itself), it **never shows up at
 build time**, only when a human clicks the page.
 
+`lib/api/prefixes.ts` — `BACKEND_API_PREFIX` is used ONLY by Server Components / Route Handlers
+calling the .NET backend directly (e.g. `https://api.example.com`; the backend's own routes have NO
+`/api` prefix); `PROXY_API_PREFIX` is used ONLY by Client Components calling the same-origin Next.js
+proxy, and matches `app/api/proxy/[...path]/route.ts`:
+
 ```typescript
-// lib/api/prefixes.ts
-// BACKEND_API_PREFIX: used ONLY by Server Components / Route Handlers calling the .NET backend directly.
-export const BACKEND_API_PREFIX = process.env.API_URL; // e.g. https://api.example.com — backend's own routes have NO /api prefix
+export const BACKEND_API_PREFIX = process.env.API_URL;
 
-// PROXY_API_PREFIX: used ONLY by Client Components calling the same-origin Next.js proxy.
-export const PROXY_API_PREFIX = '/api/proxy'; // matches app/api/proxy/[...path]/route.ts
+export const PROXY_API_PREFIX = '/api/proxy';
 ```
 
+The two call sites below — `app/(dashboard)/catalog/page.tsx`, a Server Component calling the backend
+directly, and `features/catalog/hooks/use-items.ts`, a Client Component going through the same-origin
+proxy — MUST resolve to the same backend route:
+
 ```typescript
-// app/(dashboard)/catalog/page.tsx — Server Component, direct backend call
 import { BACKEND_API_PREFIX } from '@/lib/api/prefixes';
 
 async function getItems() {
-  // cross-reference: PROXY_API_PREFIX below MUST resolve to the same backend route
   const res = await fetch(`${BACKEND_API_PREFIX}/catalog/items`, { next: { revalidate: 60 } });
   return res.json();
 }
 ```
 
+`features/catalog/hooks/use-items.ts`:
+
 ```typescript
-// features/catalog/hooks/use-items.ts — Client Component, via same-origin proxy
 import { PROXY_API_PREFIX } from '@/lib/api/prefixes';
 
 export function useItems() {
   return useQuery({
     queryKey: ['catalog', 'items'],
-    // cross-reference: BACKEND_API_PREFIX above MUST resolve to the same backend route
     queryFn: async () => (await fetch(`${PROXY_API_PREFIX}/catalog/items`)).json(),
   });
 }
@@ -435,31 +451,30 @@ Before marking any task that adds or touches an endpoint as done:
 
 ### JWT Bearer Configuration
 
+`Infrastructure/Auth/NeonAuthOptions.cs` — `BaseUrl` is the Neon Auth Base URL, e.g.
+`https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth`:
+
 ```csharp
-// Infrastructure/Auth/NeonAuthOptions.cs
 namespace {ProjectName}.Infrastructure.Auth;
 
 public sealed class NeonAuthOptions
 {
     public const string SectionName = "NeonAuth";
 
-    /// <summary>Neon Auth Base URL, e.g. https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth</summary>
     public string BaseUrl { get; set; } = string.Empty;
 }
 ```
 
+`Infrastructure/Auth/NeonAuthJwksProvider.cs` fetches and caches Neon Auth's raw JWKS
+(`/.well-known/jwks.json` — there is no OIDC discovery document) for 15 minutes; an unknown `kid`
+forces one refresh, to survive key rotation without waiting out the TTL:
+
 ```csharp
-// Infrastructure/Auth/NeonAuthJwksProvider.cs
 namespace {ProjectName}.Infrastructure.Auth;
 
 using Microsoft.Extensions.Options;
 using Microsoft.IdentityModel.Tokens;
 
-/// <summary>
-/// Fetches and caches Neon Auth's raw JWKS (/.well-known/jwks.json — there is no OIDC discovery
-/// document). Cached for 15 minutes; a forced refresh happens once when an unknown `kid` is seen,
-/// to survive key rotation without waiting out the TTL.
-/// </summary>
 public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAuthOptions> options)
 {
     private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(15);
@@ -473,7 +488,7 @@ public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAut
         var key = keySet.Keys.FirstOrDefault(k => k.Kid == kid);
         if (key is not null) return key;
 
-        // Unknown kid — could be key rotation. Force a single refresh before giving up.
+        // Unknown kid may be key rotation: refresh once before giving up.
         keySet = await GetKeySetAsync(forceRefresh: true, cancellationToken);
         return keySet.Keys.FirstOrDefault(k => k.Kid == kid);
     }
@@ -503,8 +518,9 @@ public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAut
 }
 ```
 
+`Infrastructure/Auth/NeonAuthServiceExtensions.cs`:
+
 ```csharp
-// Infrastructure/Auth/NeonAuthServiceExtensions.cs
 namespace {ProjectName}.Infrastructure.Auth;
 
 using System.Text;
@@ -527,9 +543,7 @@ public static class NeonAuthServiceExtensions
         services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
             .AddJwtBearer(options =>
             {
-                // Do NOT set options.Authority — Neon Auth serves no /.well-known/openid-configuration,
-                // so Authority-driven metadata refresh has nothing valid to fetch. ValidIssuer is set
-                // explicitly below instead.
+                // No options.Authority: Neon Auth serves no OIDC discovery document, so ValidIssuer is explicit.
                 options.TokenValidationParameters = new TokenValidationParameters
                 {
                     ValidateIssuer = true,
@@ -537,14 +551,12 @@ public static class NeonAuthServiceExtensions
                     ValidateAudience = false,
                     ValidateLifetime = true,
                     NameClaimType = "sub",
-                    // Trust in the signing key is established entirely inside SignatureValidator
-                    // below (fetched from our own cached JWKS) — this flag doesn't gate that path.
+                    // Key trust is established inside SignatureValidator below; this flag doesn't gate that path.
                     ValidateIssuerSigningKey = false,
                 };
             });
 
-        // A second Configure<TDep> pass with DI available — AddJwtBearer's own setup has already run,
-        // so this only *adds* the SignatureValidator to the TokenValidationParameters built above.
+        // Runs after AddJwtBearer's own setup, with DI available: it only adds the SignatureValidator.
         services.AddOptions<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme)
             .Configure<NeonAuthJwksProvider>((options, jwks) =>
             {
@@ -561,9 +573,7 @@ public static class NeonAuthServiceExtensions
                     if (string.IsNullOrEmpty(kid))
                         throw new SecurityTokenInvalidSignatureException("Token is missing 'kid'.");
 
-                    // Blocking call: JWKS is cached in-memory (see NeonAuthJwksProvider), so this is
-                    // I/O-free on the hot path. SignatureValidator has no async overload in this
-                    // library version — only a cold-start / key-rotation miss ever awaits real I/O here.
+                    // Blocking is safe: SignatureValidator has no async overload and the JWKS is cached in memory.
                     var jwk = jwks.GetKeyAsync(kid, CancellationToken.None).GetAwaiter().GetResult()
                         ?? throw new SecurityTokenInvalidSignatureException($"No JWKS key found for kid '{kid}'.");
 
@@ -585,10 +595,7 @@ public static class NeonAuthServiceExtensions
                     if (!verifier.VerifySignature(signature))
                         throw new SecurityTokenInvalidSignatureException("Ed25519 signature verification failed.");
 
-                    // MUST return Microsoft.IdentityModel.JsonWebTokens.JsonWebToken — ASP.NET Core 8+
-                    // uses JsonWebTokenHandler internally. Returning a
-                    // System.IdentityModel.Tokens.Jwt.JwtSecurityToken here fails with IDX10506
-                    // ("SignatureValidator returned a token of an unexpected type").
+                    // Must be JsonWebToken: ASP.NET Core 8+ rejects a JwtSecurityToken here with IDX10506.
                     return jwt;
                 };
             });
@@ -600,6 +607,12 @@ public static class NeonAuthServiceExtensions
 }
 ```
 
+Two details of the validator above: it returns `Microsoft.IdentityModel.JsonWebTokens.JsonWebToken`
+because ASP.NET Core 8+ uses `JsonWebTokenHandler` internally — returning a
+`System.IdentityModel.Tokens.Jwt.JwtSecurityToken` fails with IDX10506 ("SignatureValidator returned a
+token of an unexpected type"); and the blocking `GetResult()` is I/O-free on the hot path, since only a
+cold-start or key-rotation miss ever awaits real I/O.
+
 ### Protected Endpoints
 
 ```csharp