@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/standards/STANDARDS.json

@@ -1541,13 +1541,17 @@
         "fake clock",
         "integration test",
         "ProblemDetails",
-        "error body assertion"
+        "error body assertion",
+        "test budget",
+        "orçamento de teste",
+        "[Theory] table"
       ],
       "anchors": {
         "clock": "#rule-1--inject-timeprovider-fake-it-with-faketimeprovider-in-tests",
-        "errorbody": "#rule-2--error-path-tests-assert-the-response-body-not-just-the-status-code"
+        "errorbody": "#rule-2--error-path-tests-assert-the-response-body-not-just-the-status-code",
+        "test-budget": "#test-budget"
       },
-      "digest": "Inject TimeProvider (never DateTime.UtcNow / DateOnly.FromDateTime(DateTime.UtcNow) directly in a handler or validator) and fake it with FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) in integration tests — deterministic, no midnight-UTC flake, boundary dates (today vs. yesterday) become facts about the fake clock instead of when the suite happens to run. xUnit + WebApplicationFactory error-path tests (400/404/409) must assert the ProblemDetails response BODY (title/detail/violated field or error code), never just the HTTP status code — a status-only assertion lets the wrong validation rule or the wrong error branch pass silently as long as the status matches.",
+      "digest": "Inject TimeProvider (never DateTime.UtcNow / DateOnly.FromDateTime(DateTime.UtcNow) directly in a handler or validator) and fake it with FakeTimeProvider (Microsoft.Extensions.TimeProvider.Testing) in integration tests — deterministic, no midnight-UTC flake, boundary dates (today vs. yesterday) become facts about the fake clock instead of when the suite happens to run. xUnit + WebApplicationFactory error-path tests (400/404/409) must assert the ProblemDetails response BODY (title/detail/violated field or error code), never just the HTTP status code — a status-only assertion lets the wrong validation rule or the wrong error branch pass silently as long as the status matches. Test budget per task: one test per postcondition plus one regression test per bug, more only with a one-line justification in the task; scenarios of the same behavior (edge cases included) are rows of one [Theory], never copied [Fact]s; no test whose only assertion is a copy, config or prose string (that is an analyzer or a publish-time validation, outside the suite count); shared fixtures before new helpers; TDD for bugs (regression first) and pure logic; a surviving mutant is killed by tightening an assertion or adding a row, not by a new test.",
       "verifiedAgainst": ".NET 10 + xUnit 2 + `Microsoft.Extensions.TimeProvider.Testing`.",
       "provedBy": []
     },
@@ -2136,8 +2140,8 @@
         "patterns": "#three-tier-hierarchy",
         "shadcn": "#tier-1--shadcnui-primitives"
       },
-      "digest": "Server Components for data fetching and static content. Client Components for interactivity. shadcn/ui components are copy-paste — customize in src/components/ui/. Never use index.tsx for named exports. One component per file. Avoid prop drilling — use composition or Context API.",
-      "verifiedAgainst": "Next.js 15 + shadcn/ui CLI + TanStack Table 8.",
+      "digest": "Three tiers: components/ui is shadcn CLI output (never edit, wrap instead); components/ composes primitives with no domain knowledge; features/*/components knows the domain. 'use client' only for hooks, events or browser APIs; never pass raw API data as props — type and validate it first. The shared data table is specified once, in admin-app/data-table.md.",
+      "verifiedAgainst": "Next.js 16 + shadcn 4 CLI (the code blocks typecheck under `tsc --strict`).",
       "provedBy": []
     },
     {
@@ -2185,15 +2189,15 @@
         "react-hook-form",
         "Zod",
         "form validation",
-        "Server Actions forms",
-        "useFormState"
+        "shadcn Field",
+        "Controller"
       ],
       "anchors": {
         "validation": "#schema-composition",
         "submission": "#complete-form-pattern"
       },
-      "digest": "react-hook-form with Zod resolver for client forms. Define Zod schema before component. Server Actions for mutations: 'use server' directive. Use useFormState/useActionState for Server Action feedback. Never submit to API routes — use Server Actions or React Query mutations. Display field-level errors from Zod.",
-      "verifiedAgainst": "Next.js 15 + react-hook-form 7 + Zod 4 + @hookform/resolvers 3.",
+      "digest": "react-hook-form + Zod + shadcn Field components wired through Controller. Define the Zod schema first and derive the type with z.infer (z.input/z.output when it coerces); zodResolver connects it; Field/FieldLabel/FieldError render each field and its error; never useState per field; submit through TanStack Query useMutation and put a failed submit on root. Edit forms reuse the create schema (.partial()). Zod 4: z.email(), a single `error` param. A legacy shadcn Form/FormField screen is migrated when touched, never extended. Admin CRUD forms add the deltas of admin-app/forms.md.",
+      "verifiedAgainst": "Next.js 16 + react-hook-form 7 + Zod 4 + @hookform/resolvers 5 + shadcn 4 `Field` (the code blocks typecheck under `tsc --strict`).",
       "provedBy": []
     },
     {
@@ -2357,13 +2361,17 @@
         "testing-library",
         "Playwright",
         "Next.js testing",
-        "component tests"
+        "component tests",
+        "test budget",
+        "orçamento de teste",
+        "it.each table"
       ],
       "anchors": {
         "unit": "#component-test-pattern",
-        "e2e": "#test-file-co-location"
+        "e2e": "#test-file-co-location",
+        "test-budget": "#test-budget"
       },
-      "digest": "Vitest for unit tests, React Testing Library for component tests. Mock next/navigation with vi.mock. Test Server Actions with direct function calls. Use MSW for API mocking in component tests. Playwright for E2E tests against running app. Never test implementation details — test user behavior and output.",
+      "digest": "Vitest for unit tests, React Testing Library for component tests. Mock next/navigation with vi.mock. Test Server Actions with direct function calls. Use MSW for API mocking in component tests. Playwright for E2E tests against running app. Never test implementation details — test user behavior and output. Test budget per task: one test per postcondition plus one regression test per bug, more only with a one-line justification in the task; scenarios of the same behavior are rows of one it.each, never copied it() blocks; no test whose only assertion is a copy string (lint or publish-time validation instead); shared wrappers, MSW handlers and factories before new helpers; TDD for bugs and pure logic, component tests may come after the code.",
       "verifiedAgainst": "Vitest 3 + React Testing Library 16 + MSW 2.",
       "provedBy": []
     },
@@ -2681,8 +2689,167 @@
         "tools": "#mcp-providers-by-phase",
         "setup": "#mcp-availability-detection"
       },
-      "digest": "MCP tools extend Claude with external data and actions. Tools are synchronous request-response with typed inputSchema. Resources provide read-only data access. Prompts are reusable templates. Register MCP servers in .claude/settings.json. Prefer @context7 for live library docs. Test tools with MCP Inspector before integrating.",
-      "verifiedAgainst": "Claude Code MCP tooling — context7, Playwright; GitHub via `gh` CLI; Neon via `neonctl`.",
+      "digest": "MCP tools extend Claude with external data and actions. Tools are synchronous request-response with typed inputSchema. Resources provide read-only data access. Prompts are reusable templates. Register MCP servers in .claude/settings.json. Prefer @context7 for live library docs. Tool names follow where the server is configured: mcp__context7__query-docs from .mcp.json, mcp__plugin_context7_context7__query-docs from the plugin; a deferred tool loads via ToolSearch. Test tools with MCP Inspector before integrating.",
+      "verifiedAgainst": "Claude Code 2.1.282 MCP tooling — context7, Playwright (as plugin and as a project MCP server); GitHub via `gh` CLI; Neon via its MCP or `neonctl`.",
+      "provedBy": []
+    },
+    {
+      "id": "frontend-admin-app-data-table",
+      "name": "data table",
+      "path": "frontend/admin-app/data-table.md",
+      "category": "frontend",
+      "subcategory": "admin-app",
+      "tags": [
+        "frontend",
+        "admin-app"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "data table",
+        "admin list",
+        "server-side pagination",
+        "paginação",
+        "tabela de dados",
+        "ordenação no servidor",
+        "empty state",
+        "row selection",
+        "bulk actions",
+        "manualPagination"
+      ],
+      "anchors": {
+        "contract": "#the-list-contract-url-and-api",
+        "table": "#the-shared-datatable-tier-2",
+        "states": "#the-three-states",
+        "mobile": "#mobile"
+      },
+      "digest": "Every admin list is paged, sorted and filtered on the server, with page/pageSize/sort/dir/filters in the URL (searchParams parsed by a Zod schema with .catch defaults) and the API answering { items, totalCount } over an OrderBy plus a unique id tiebreaker. The Server Component page reads searchParams and wraps the results in a Suspense keyed by the query; one shared components/data-table.tsx on TanStack Table 9 sets manualPagination + rowCount, manualSorting and selection by a stable getRowId, and only writes the URL (router.replace with scroll:false, page reset on any filter/sort change). Three non-happy states always: loading skeleton, empty (no records vs no match for the filters), error as a value with retry via router.refresh(). Compact density, right-aligned tabular numbers, one inline row action plus a menu, a bulk bar over the selected page, a card list below md. Never 'first N + see all' instead of paging.",
+      "verifiedAgainst": "Next.js 16 App Router + @tanstack/react-table 9 + Zod 4 + shadcn 4 (the code blocks typecheck under `tsc --strict`).",
+      "provedBy": []
+    },
+    {
+      "id": "frontend-admin-app-feedback",
+      "name": "feedback",
+      "path": "frontend/admin-app/feedback.md",
+      "category": "frontend",
+      "subcategory": "admin-app",
+      "tags": [
+        "frontend",
+        "admin-app"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "confirmation dialog",
+        "confirm dialog",
+        "delete confirmation",
+        "toast",
+        "sonner",
+        "toast messages",
+        "undo toast",
+        "diálogo de confirmação"
+      ],
+      "anchors": {
+        "when": "#when-to-confirm",
+        "dialog": "#the-confirmation-dialog-tier-2",
+        "catalog": "#the-toast-catalog"
+      },
+      "digest": "One ConfirmDialog (controlled shadcn AlertDialog, a plain Button that awaits the action, stays open showing the error on failure, optional type-to-confirm) used only for destructive-irreversible, bulk or discard-changes actions; a reversible action gets a 'Desfazer' toast instead. The title names the object and the confirm label repeats the verb. Every toast string comes from a catalog (lib/toast-messages.ts for generic outcomes + per-entity EntityMessages, because Portuguese agrees in gender and number); sonner toast.success/toast.error with an id per action, a longer duration for errors, errors mapped by status (403, 409, network), never the server's raw text, and field validation never in a toast.",
+      "verifiedAgainst": "shadcn 4 `AlertDialog` (Radix) + sonner 2 + TanStack Query 5 (the code blocks typecheck under `tsc --strict`).",
+      "provedBy": []
+    },
+    {
+      "id": "frontend-admin-app-forms",
+      "name": "forms",
+      "path": "frontend/admin-app/forms.md",
+      "category": "frontend",
+      "subcategory": "admin-app",
+      "tags": [
+        "frontend",
+        "admin-app"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "admin form",
+        "crud form",
+        "server validation errors",
+        "ValidationProblemDetails",
+        "unsaved changes",
+        "formulário"
+      ],
+      "anchors": {
+        "server-errors": "#server-errors-on-the-field",
+        "placement": "#where-the-form-lives",
+        "dirty": "#unsaved-changes"
+      },
+      "digest": "Admin forms use the one pattern of nextjs/forms.md (Zod schema, zodResolver, react-hook-form Controller + shadcn Field/FieldError, useMutation) plus the CRUD deltas: map .NET ValidationProblemDetails errors onto their fields with setError (unmatched ones go to root.serverError), mode 'onTouched', submit disabled only while saving, form.reset(values) after a successful save, a guard for unsaved changes, the three useForm generics (z.input / unknown / z.output) when the schema coerces, and placement by size: dialog up to 4 fields, sheet or page up to 12, its own page beyond that, a wizard when steps depend on each other.",
+      "verifiedAgainst": "react-hook-form 7 + @hookform/resolvers 5 + Zod 4 + TanStack Query 5 + shadcn 4 `Field` (the code blocks typecheck under `tsc --strict`).",
+      "provedBy": []
+    },
+    {
+      "id": "frontend-admin-app-page-structure",
+      "name": "page structure",
+      "path": "frontend/admin-app/page-structure.md",
+      "category": "frontend",
+      "subcategory": "admin-app",
+      "tags": [
+        "frontend",
+        "admin-app"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "tabs",
+        "abas",
+        "long page",
+        "página longa",
+        "wizard",
+        "multi-step form",
+        "stepper",
+        "detail page"
+      ],
+      "anchors": {
+        "decision": "#tabs-long-page-or-wizard",
+        "tabs": "#tabs-in-the-url",
+        "wizard": "#wizard-for-long-flows"
+      },
+      "digest": "Decide per screen and write it in the mockup checklist: tabs for 3+ independent sections, a long page with sticky section nav when sections are read together or share one save, a plain page for 2 short blocks, a wizard when later fields depend on earlier answers. The active tab lives in ?tab= and only its content is rendered and fetched on the server; switching tab drops the list params of the tab being left. Unbounded related lists get their own paged tab, never a capped preview. A wizard keeps one react-hook-form across steps, validates each step with trigger(stepFields), never loses data going back, and commits on a final review step.",
+      "verifiedAgainst": "Next.js 16 App Router + shadcn 4 `Tabs` (Radix) + react-hook-form 7 + Zod 4 (the code blocks typecheck under `tsc --strict`).",
+      "provedBy": []
+    },
+    {
+      "id": "architecture-code-comments",
+      "name": "code comments",
+      "path": "architecture/code-comments.md",
+      "category": "architecture",
+      "subcategory": null,
+      "tags": [
+        "architecture",
+        "comments"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "code comments",
+        "comentário de código",
+        "comment policy",
+        "política de comentário",
+        "comentário de processo",
+        "self-documenting code"
+      ],
+      "anchors": {
+        "comment-policy": "#o-que-merece-comentário",
+        "not-worth": "#o-que-não-merece",
+        "size": "#tamanho"
+      },
+      "digest": "Default is NO comment: code explains itself through names, types and tests. Before commenting, rename, extract a function or named constant, encode the state in the type, or write a test; comment only what none of these can express: an invariant the type does not express, an order that matters, an external quirk (third-party API, library bug with its link), or the contract of a package published for consumers outside the repo. Never process history (task, UC, ADR, FR, Gate, evaluator, spec.md, mockup: commit message and decisions.md), never restate the code, no XML doc/JSDoc on application members that repeats the signature, no file headers, section banners, #region, commented-out code or loose TODOs, no claims about behavior (make them test assertions). One line is normal, ~3 is the ceiling; more than one comment line per ten code lines means the names are not doing the work. The verify validators node (code-budget) warns on added comments that cite process and on added comment density.",
+      "verifiedAgainst": "C#, TypeScript e JavaScript (convenção de linguagem, sem pacote externo).",
       "provedBy": []
     }
   ],
@@ -2767,6 +2934,14 @@
     "seedance": [
       "ai-agents-media-video",
       "frontend-design-system-ai-video-generation"
+    ],
+    "test budget": [
+      "backend-dotnet-testing",
+      "frontend-nextjs-testing"
+    ],
+    "orçamento de teste": [
+      "backend-dotnet-testing",
+      "frontend-nextjs-testing"
     ]
   }
 }

package/framework/standards/ai-agents/context-providers.md

@@ -30,8 +30,7 @@ Preciso que o agente saiba X.
 Plano por fase (instruções + **allow-list de tools** conforme o estado do funil) **não** é caso de provider. É C# puro, montado antes de criar a requisição:
 
 ```csharp
-// O CÓDIGO decide o modo; o LLM só classifica. A allow-list de tools é a parte
-// que um provider não consegue dar: AIContext.Tools ACRESCENTA tools, não remove.
+// A allow-list não cabe num provider: AIContext.Tools ACRESCENTA tools, não remove.
 public sealed record OperatorPlan(string Instructions, IReadOnlyList<AITool> Tools);
 
 public static OperatorPlan PlanFor(FunnelStage stage) => stage switch
@@ -92,10 +91,8 @@ Use um `AIContextProvider` quando o agente precisa de **contexto dinâmico compu
 
 **Método a sobrescrever:**
 
-```csharp
-// ProvideAIContextAsync  → chamado ANTES do LLM (before-run hook) — injeta contexto
-// StoreAIContextAsync    → chamado APÓS o LLM (after-run hook) — persiste estado se necessário
-```
+- `ProvideAIContextAsync` → chamado ANTES do LLM (before-run hook) — injeta contexto
+- `StoreAIContextAsync` → chamado APÓS o LLM (after-run hook) — persiste estado se necessário (opcional)
 
 ### A invariante de instância — a mesma de `ai-agents-agent-session`
 
@@ -122,32 +119,33 @@ Consequência prática: **compaction só faz sentido com histórico local**. Com
 
 ## Exemplo C# — context provider que injeta data atual e perfil do tenant
 
+O bloco tem três partes: o provider, o registro do agente com o provider no DI (`Program.cs`) e o uso
+normal. `ITenantContext` é implementado via `IHttpContextAccessor` ou `AsyncLocal` para resolver o
+tenant em runtime, nunca registrado como instância estática. O contexto volta como instrução
+adicional, não como mensagem do usuário, e `StoreAIContextAsync` fica vazio porque o provider é
+stateless. No uso, o provider é invocado a cada `RunAsync`: o agente já sabe a data, o nome do tenant
+e o idioma, sem código extra no caller.
+
 ```csharp
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 
-// ── 1. Definir o provider ──
 public sealed class TenantContextProvider : AIContextProvider
 {
     private readonly ITenantService _tenantService;
     private readonly ITenantContext _tenantContext;
 
-    // ITenantContext deve ser implementado via IHttpContextAccessor ou AsyncLocal
-    // para resolver o tenant atual em runtime — não registre como instância estática.
-    // O AIAgent é singleton, então o provider também é singleton; o tenant corrente
-    // é lido de forma ambient (IHttpContextAccessor/AsyncLocal) a cada chamada.
+    // Singleton como o AIAgent: o tenant corrente é lido ambient a cada chamada, nunca guardado.
     public TenantContextProvider(ITenantService tenantService, ITenantContext tenantContext)
     {
         _tenantService = tenantService;
         _tenantContext = tenantContext;
     }
 
-    // Sobrescreva: injetado ANTES de cada chamada ao LLM
     protected override async ValueTask<AIContext> ProvideAIContextAsync(
         InvokingContext context,
         CancellationToken cancellationToken = default)
     {
-        // Tenant resolvido via serviço injetado (ambient context, ex: IHttpContextAccessor)
         var tenantId = _tenantContext.TenantId ?? "unknown";
         var tenant = await _tenantService.GetTenantAsync(tenantId, cancellationToken);
 
@@ -159,20 +157,16 @@ public sealed class TenantContextProvider : AIContextProvider
 
         return new AIContext
         {
-            // Injeta como instrução adicional — não como mensagem do usuário
             Instructions = instructions,
         };
     }
 
-    // Sobrescreva (opcional): chamado APÓS o LLM — use para persistir estado derivado da resposta
     protected override ValueTask StoreAIContextAsync(
         InvokedContext context,
         CancellationToken cancellationToken = default)
-        => ValueTask.CompletedTask; // stateless provider — nada a persistir
+        => ValueTask.CompletedTask;
 }
 
-// ── 2. Registrar o agente com o provider no DI ──
-// Program.cs
 builder.Services.AddSingleton<AIAgent>(sp =>
 {
     var registry      = sp.GetRequiredService<ModelRegistry>();
@@ -187,19 +181,15 @@ builder.Services.AddSingleton<AIAgent>(sp =>
         });
 });
 
-// ── Alternativa: pipeline de chat (compacta/injeta SÓ o request em voo) ──
-// using Microsoft.Extensions.AI;   // a extensão vive na assembly Microsoft.Agents.AI
-// IChatClient enriched = chatClient.AsBuilder()
-//     .UseAIContextProviders(new TenantContextProvider(tenantSvc, tenantContext))
-//     .Build();
-
-// ── 3. Uso normal — provider é invocado automaticamente a cada RunAsync ──
 AgentSession session = await agent.CreateSessionAsync();
 AgentResponse response = await agent.RunAsync("Quais são meus benefícios do plano?", session);
 Console.WriteLine(response.Text);
-// O agente já sabe a data, o nome do tenant e o idioma — sem código extra no caller
 ```
 
+**Alternativa: pipeline de chat**, que compacta/injeta **só** o request em voo: registre o provider
+com `.UseAIContextProviders(...)` no `ChatClientBuilder` (`chatClient.AsBuilder()`). O `using` é
+`Microsoft.Extensions.AI`, mas a extensão vive na assembly `Microsoft.Agents.AI`.
+
 ---
 
 ## Context Provider vs Tools vs RAG

package/framework/standards/ai-agents/durable-workflows-hitl.md

@@ -22,12 +22,11 @@ If neither applies, a plain workflow (or no workflow at all — see `ai-agents-s
 
 ## Human-in-the-Loop via `RequestPort`
 
-HITL is modeled with `RequestPort` — a special node in the workflow graph that pauses execution and waits for an external (human) response instead of processing automatically.
+HITL is modeled with `RequestPort` — a special node in the workflow graph that pauses execution and waits for an external (human) response instead of processing automatically. Its two type arguments are the request type the port sends out and the response type it expects back.
 
 ```csharp
 using Microsoft.Agents.AI.Workflows;
 
-// Request type the port sends out, response type it expects back.
 RequestPort<ApprovalRequest, bool> approvalPort =
     RequestPort.Create<ApprovalRequest, bool>("RefundApproval");
 
@@ -47,8 +46,7 @@ await foreach (WorkflowEvent evt in run.WatchStreamAsync())
     switch (evt)
     {
         case RequestInfoEvent requestEvt:
-            // Surface requestEvt.Request to a human (dashboard, email, Slack, ...).
-            // This is where execution pauses until an external answer arrives.
+            // Execution pauses here until the human's answer arrives (dashboard, email, Slack, ...).
             bool approved = await GetHumanDecisionAsync(requestEvt.Request);
             await run.SendResponseAsync(requestEvt.Request.CreateResponse(approved));
             break;
@@ -77,8 +75,14 @@ O caso do agente único é o que a casa realmente tem (MORPH_OS: billing, envio
 
 ### O ciclo, medido em `Microsoft.Extensions.AI` 10.9.0
 
+Quatro passos: (1) embrulhe a tool — `ApprovalRequiredAIFunction : DelegatingAIFunction`; (2) o run
+**termina** pedindo aprovação — não bloqueia, não espera —, e `ToolApprovalRequestContent.ToolCall` é
+um `ToolCallContent` (medido; **não** é `FunctionCallContent`, que aparece em
+`ToolAutoApprovalRuleContext`); (3) responda **na mesma sessão**, com
+`CreateResponse(bool approved, string? reason)`; (4) **repita** o passo 2 até não restar pendência —
+uma volta pode pedir **outra** tool.
+
 ```csharp
-// 1. Embrulhe a tool. ApprovalRequiredAIFunction : DelegatingAIFunction.
 AIFunction charge = AIFunctionFactory.Create(BillingTools.ChargeCustomer);
 AITool guarded = new ApprovalRequiredAIFunction(charge);
 
@@ -88,22 +92,16 @@ AIAgent agent = registry.GetChatClient("text-default")
 AgentSession session = await agent.CreateSessionAsync();
 AgentResponse response = await agent.RunAsync("Cobre o cliente 42.", session);
 
-// 2. O run TERMINA pedindo aprovação — não bloqueia, não espera.
-//    ToolApprovalRequestContent.ToolCall é um ToolCallContent (medido; NÃO é
-//    FunctionCallContent — este último aparece em ToolAutoApprovalRuleContext).
 var pending = response.Messages
     .SelectMany(m => m.Contents)
     .OfType<ToolApprovalRequestContent>()
     .ToList();
 
-// 3. Responda NA MESMA SESSÃO. CreateResponse(bool approved, string? reason).
 if (pending.Count > 0)
 {
     var approvals = pending.Select(r => (AIContent)r.CreateResponse(approved: true, reason: "aprovado por lucas@…"));
     response = await agent.RunAsync(new ChatMessage(ChatRole.User, [.. approvals]), session);
 }
-
-// 4. REPITA o passo 2 até não restar pendência. Uma volta pode pedir OUTRA tool.
 ```
 
 **Os quatro pontos que erram na primeira tentativa:**
@@ -157,10 +155,11 @@ Checkpointing is part of the **base, GA** `Microsoft.Agents.AI.Workflows` namesp
 | `CheckpointManager.CreateJson(new FileSystemJsonCheckpointStore(dir))` | Local disk, survives process restart | Single-instance VPS deployments — no Azure, no preview package |
 | Custom `ICheckpointStore` implementation | Whatever backend you implement it against | **Recommended for production** — implement against the project's own Neon Postgres table, matching the ownership model already used by `ai-agents-rag-custom-pgvector` |
 
+Local-disk durability, with no Azure dependency:
+
 ```csharp
 using Microsoft.Agents.AI.Workflows;
 
-// Local-disk durability — no Azure dependency:
 var checkpointFolder = Directory.CreateDirectory("./checkpoints");
 CheckpointManager checkpointManager = CheckpointManager.CreateJson(
     new FileSystemJsonCheckpointStore(checkpointFolder));
@@ -171,13 +170,12 @@ await foreach (WorkflowEvent evt in run.WatchStreamAsync())
     if (evt is SuperStepCompletedEvent stepEvt)
     {
         CheckpointInfo? checkpoint = stepEvt.CompletionInfo?.Checkpoint;
-        // Persist checkpoint.CheckpointId alongside the business record
-        // (e.g. the refund request row) so it can be resumed after a restart.
+        // Persist checkpoint.CheckpointId with the business record (e.g. the refund row) to resume after a restart.
     }
 }
 ```
 
-Resuming after a restart — rehydrate into a **new** run instance from the last known checkpoint:
+Resuming after a restart — rehydrate into a **new** run instance from the last known checkpoint. A pending `RequestPort` request is re-emitted as a `RequestInfoEvent`, so the paused approval survives the restart:
 
 ```csharp
 StreamingRun resumedRun = await InProcessExecution.ResumeStreamingAsync(
@@ -185,8 +183,6 @@ StreamingRun resumedRun = await InProcessExecution.ResumeStreamingAsync(
 
 await foreach (WorkflowEvent evt in resumedRun.WatchStreamAsync())
 {
-    // A pending RequestPort request is re-emitted here as a RequestInfoEvent —
-    // the paused approval survives the restart.
     if (evt is RequestInfoEvent requestEvt) { /* re-surface to the human */ }
 }
 ```
@@ -211,14 +207,12 @@ internal sealed class RefundAnalyzerExecutor() : Executor("RefundAnalyzer")
 
 ### `ICheckpointStore` — Neon/Postgres-backed (recommended production pattern)
 
-Implementing `ICheckpointStore` against the project's own Postgres database keeps checkpoint durability inside the same infrastructure the rest of the project already trusts (see `infrastructure-neon-setup`), instead of introducing a new storage dependency:
+Implementing `ICheckpointStore` against the project's own Postgres database keeps checkpoint durability inside the same infrastructure the rest of the project already trusts (see `infrastructure-neon-setup`), instead of introducing a new storage dependency. The store persists and retrieves checkpoint blobs in a `workflow_checkpoints` table (`workflow_id`, `checkpoint_id`, `payload` jsonb/bytea, `created_at`), implemented per the `ICheckpointStore` contract in the `Microsoft.Agents.AI.Workflows` docs:
 
 ```csharp
 public sealed class PostgresCheckpointStore(NpgsqlDataSource dataSource) : ICheckpointStore
 {
-    // Persist/retrieve checkpoint blobs in a workflow_checkpoints table
-    // (workflow_id, checkpoint_id, payload jsonb/bytea, created_at).
-    // Implement per the ICheckpointStore contract — see Microsoft.Agents.AI.Workflows docs.
+    // ICheckpointStore members over workflow_checkpoints — elided.
 }
 ```
 

package/framework/standards/ai-agents/modalities-image-gen.md

@@ -50,8 +50,7 @@ using Microsoft.Extensions.AI;
 using OpenAI.Images;
 
 #pragma warning disable MEAI001 // IImageGenerator e experimental: a superficie pode mudar entre menores
-// AsIImageGenerator() vem de Microsoft.Extensions.AI.OpenAI — um pacote A MAIS.
-// Sem ele, escreva o adaptador (e o kit escreve: ver a nota abaixo).
+// AsIImageGenerator() exige o pacote Microsoft.Extensions.AI.OpenAI, a mais (ver a nota abaixo).
 IImageGenerator generator = new ImageClient("gpt-image-2", apiKey).AsIImageGenerator();
 
 var response = await generator.GenerateAsync(
@@ -197,35 +196,33 @@ trocar a foto de referência **é** outro pedido, mesmo com o prompt idêntico.
 
 ## Exemplo C# completo
 
+O adaptador é de **provider**, não um serviço público que um handler possa chamar: quem produz bytes
+vive atrás do enfileiramento de `ai-agents/media-pipeline.md`, e no kit esse tipo é `internal` de
+propósito. Quatro escolhas do bloco abaixo foram impostas pelo compilador:
+
+- **Sem `using OpenAI.Images;`.** O gerador chega injetado e nenhum tipo do SDK da OpenAI aparece no
+  arquivo; deixar o `using` torna `ImageGenerationOptions` ambíguo (CS0104) entre
+  `Microsoft.Extensions.AI` e `OpenAI.Images`. Onde os dois convivem de verdade, como no adaptador do
+  kit, o tipo vai qualificado.
+- **O pragma abre acima da classe**, não dentro do método: o parâmetro do construtor primário também
+  nomeia `IImageGenerator`, e `MEAI001` é erro por padrão, não aviso. Pragma dentro do corpo deixa a
+  assinatura de fora e o arquivo não compila.
+- **O `IImageGenerator` chega injetado**, não construído aqui, e é isso que faz o exemplo compilar com
+  ou sem `Microsoft.Extensions.AI.OpenAI` no pin (ver a ressalva de §A API): com o pacote,
+  `imageClient.AsIImageGenerator()`; sem ele, um `IImageGenerator` escrito à mão sobre o `ImageClient`,
+  como em `templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/OpenAIImageProvider.cs`.
+- **`ReadOnlyMemory<byte>` dos dois lados**, porque é o tipo real de `DataContent.Data`; declarar
+  `BinaryData` não converte (CS0029).
+
+`OriginalImages` é o gancho de edição: com referências, o produto real é preservado em vez de recriado.
+
 ```csharp
-// SEM `using OpenAI.Images;`. Ele nao e necessario aqui — o gerador chega injetado e nenhum
-// tipo do SDK da OpenAI aparece neste arquivo — e deixa-lo torna `ImageGenerationOptions`
-// AMBIGUO (CS0104) entre Microsoft.Extensions.AI e OpenAI.Images. Onde os dois convivem de
-// verdade, como no adaptador do kit, o tipo vai QUALIFICADO.
 using Microsoft.Extensions.AI;
 
-// O pragma abre ACIMA da classe, e nao dentro do metodo: o parametro do construtor primario
-// tambem nomeia IImageGenerator, e MEAI001 e ERRO por padrao — nao aviso. Pragma dentro do
-// corpo deixa a assinatura de fora e o arquivo nao compila.
 #pragma warning disable MEAI001 // IImageGenerator/ImageGenerationRequest sao experimentais: a superficie pode mudar entre menores.
 
-/// <summary>
-/// Adaptador de PROVIDER. Note o que ele NAO e: um servico publico que um handler
-/// possa chamar. Quem produz bytes vive atras do enfileiramento descrito em
-/// ai-agents/media-pipeline.md, e no kit esse tipo e `internal` de proposito.
-/// </summary>
-/// <remarks>
-/// O IImageGenerator chega INJETADO, e nao construido aqui. As duas formas de obte-lo
-/// sao legitimas e a escolha e do seu pin (ver a ressalva da secao "A API"):
-///   - com Microsoft.Extensions.AI.OpenAI no pin:  imageClient.AsIImageGenerator()
-///   - sem ele: um IImageGenerator escrito a mao sobre o ImageClient, como em
-///     templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/OpenAIImageProvider.cs
-/// Injetar em vez de construir e o que faz ESTE exemplo compilar nos dois casos.
-/// </remarks>
 internal sealed class OpenAiImageAdapter(IImageGenerator generator)
 {
-    // ReadOnlyMemory<byte> dos dois lados porque e o tipo REAL de DataContent.Data.
-    // Declarar BinaryData aqui nao converte (CS0029) — e o compilador que decide isso.
     public async Task<ReadOnlyMemory<byte>> ProduceAsync(
         string prompt,
         IReadOnlyList<ReadOnlyMemory<byte>> references,
@@ -234,7 +231,6 @@ internal sealed class OpenAiImageAdapter(IImageGenerator generator)
         var request = new ImageGenerationRequest { Prompt = prompt };
         if (references.Count > 0)
         {
-            // OriginalImages e o gancho de EDICAO: preserva o produto real em vez de recria-lo.
             request.OriginalImages = [.. references.Select(r => new DataContent(r, "image/png"))];
         }
 

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

@@ -49,6 +49,8 @@ O projeto injeta `AudioClient` via DI. Para transcrição com timestamps (ex: si
 
 ## Exemplo C# completo
 
+Três entradas: arquivo, bytes (ex: upload do usuário) — as duas devolvem texto simples — e a verbose, com timestamps por palavra e segmento, útil para legendas ou busca por trecho.
+
 ```csharp
 using OpenAI.Audio;
 using Microsoft.Extensions.Configuration;
@@ -64,19 +66,12 @@ public sealed class TranscriptionService
         _client = new AudioClient(model, apiKey);
     }
 
-    /// <summary>
-    /// Transcreve áudio a partir de um arquivo e retorna texto simples.
-    /// O transcript retornado pode ser passado diretamente como input para um AIAgent downstream.
-    /// </summary>
     public async Task<string> TranscribeAsync(string audioFilePath, CancellationToken ct = default)
     {
         AudioTranscription transcription = await _client.TranscribeAudioAsync(audioFilePath, cancellationToken: ct);
         return transcription.Text;
     }
 
-    /// <summary>
-    /// Transcreve áudio a partir de bytes (ex: upload do usuário) e retorna texto simples.
-    /// </summary>
     public async Task<string> TranscribeBytesAsync(
         Stream audioStream,
         string fileName,
@@ -93,9 +88,6 @@ public sealed class TranscriptionService
         return transcription.Text;
     }
 
-    /// <summary>
-    /// Transcreve com timestamps por palavra e segmento (útil para legendas ou busca por trecho).
-    /// </summary>
     public async Task<AudioTranscription> TranscribeVerboseAsync(string audioFilePath, CancellationToken ct = default)
     {
         var options = new AudioTranscriptionOptions
@@ -109,21 +101,18 @@ public sealed class TranscriptionService
 }
 ```
 
-**Alimentando um agente downstream com o transcript:**
+**Alimentando um agente downstream com o transcript** — ele é texto puro, então basta passá-lo como input para qualquer `AIAgent`; aqui, um Status Agent que extrai as ações da reunião:
 
 ```csharp
-// O transcript é texto puro — basta passar como input para qualquer AIAgent
 string transcript = await _transcription.TranscribeAsync("meeting-2024-05-19.mp3");
 
-// Ex: Status Agent que extrai ações da reunião
 AgentResponse<MeetingActions> actions = await _statusAgent.RunAsync<MeetingActions>(
     $"Extraia ações, decisões e responsáveis desta transcrição:\n\n{transcript}");
 ```
 
-**Registro DI:**
+**Registro DI** (`Program.cs`):
 
 ```csharp
-// Program.cs
 builder.Services.AddSingleton<TranscriptionService>();
 ```