@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/templates/docs/ui-mockups.md

@@ -1,98 +1,115 @@
-# UI Mockups & Wireframes: {{titleCase FEATURE_NAME}}
-
-| Field | Value |
-|-------|-------|
-| **Feature** | {{FEATURE_NAME}} |
-| **Created** | {{DATE}} |
-
----
-
-## Screen Inventory
-
-| Screen ID | Name | Route | Priority |
-|-----------|------|-------|----------|
-| **S001** | {Screen Name} | /path | High |
-| **S002** | {Screen Name} | /path | Medium |
-
----
-
-## S001: {Primary Screen}
-
-### Desktop Layout
-
-```
-┌─────────────────────────────────────┐
-│  Header                    [User ▼] │
-├─────────────────────────────────────┤
-│                                     │
-│  [Title]                            │
-│                                     │
-│  ┌──────────────────────────────┐  │
-│  │ Main Content Area            │  │
-│  │                              │  │
-│  │  [Card 1]    [Card 2]        │  │
-│  │                              │  │
-│  │  ┌────────────────────────┐  │  │
-│  │  │ Data Table             │  │  │
-│  │  │ ...                    │  │  │
-│  │  └────────────────────────┘  │  │
-│  └──────────────────────────────┘  │
-│                                     │
-└─────────────────────────────────────┘
-```
-
-### Mobile Layout
-
-```
-┌──────────────────────┐
-│ ☰  Title    [User ▼]│
-├──────────────────────┤
-│                      │
-│ [Card 1]             │
-│                      │
-│ [Card 2]             │
-│                      │
-│ [View All Items]     │
-│                      │
-└──────────────────────┘
-```
-
----
-
-## States
-
-### Loading
-- Show skeleton placeholders
-- Spinner for primary content
-
-### Empty
-- Icon + message
-- Clear call-to-action button
-
-### Error
-- Warning icon
-- User-friendly message
-- Retry button
-
-### Success (After Action)
-- Toast notification
-- Auto-dismiss after 3s
-
----
-
-## Interactions
-
-- **Hover**: Subtle elevation increase
-- **Click**: Scale down (0.98)
-- **Transitions**: Fade-in 200ms
-
----
-
-## Accessibility
-- [ ] 44x44px minimum touch targets
-- [ ] Focus indicators visible
-- [ ] Proper heading hierarchy (H1 → H2 → H3)
-
----
-
-*Generated with MORPH Framework*
+# UI Mockups & Wireframes: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **Feature** | {{FEATURE_NAME}} |
+| **Created** | {{DATE}} |
+
+---
+
+## Screen Inventory
+
+| Screen ID | Name | Route | Priority |
+|-----------|------|-------|----------|
+| **S001** | {Screen Name} | /path | High |
+| **S002** | {Screen Name} | /path | Medium |
+
+---
+
+## Tela: {Primary Screen}
+
+### Desktop Layout
+
+```
+┌─────────────────────────────────────┐
+│  Header                    [User ▼] │
+├─────────────────────────────────────┤
+│                                     │
+│  [Title]                            │
+│                                     │
+│  ┌──────────────────────────────┐  │
+│  │ Main Content Area            │  │
+│  │                              │  │
+│  │  [Card 1]    [Card 2]        │  │
+│  │                              │  │
+│  │  ┌────────────────────────┐  │  │
+│  │  │ Data Table             │  │  │
+│  │  │ ...                    │  │  │
+│  │  └────────────────────────┘  │  │
+│  └──────────────────────────────┘  │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+### Mobile Layout
+
+```
+┌──────────────────────┐
+│ ☰  Title    [User ▼]│
+├──────────────────────┤
+│                      │
+│ [Card 1]             │
+│                      │
+│ [Card 2]             │
+│                      │
+│ [View All Items]     │
+│                      │
+└──────────────────────┘
+```
+
+### Checklist de tela
+
+Troque cada `…` pela decisão — "não se aplica" vale se escrito; `…`, vazio ou "a definir" reprovam o Gate uiux.
+
+| Item | Decisão |
+|---|---|
+| Superfície | … |
+| Volume esperado | … |
+| Paginação | … |
+| Ordenação | … |
+| Filtro | … |
+| Estado vazio | … |
+| Estado carregando | … |
+| Estado de erro | … |
+| Mobile | … |
+| Abas | … |
+
+---
+
+## States
+
+### Loading
+- Show skeleton placeholders
+- Spinner for primary content
+
+### Empty
+- Icon + message
+- Clear call-to-action button
+
+### Error
+- Warning icon
+- User-friendly message
+- Retry button
+
+### Success (After Action)
+- Toast notification
+- Auto-dismiss after 3s
+
+---
+
+## Interactions
+
+- **Hover**: Subtle elevation increase
+- **Click**: Scale down (0.98)
+- **Transitions**: Fade-in 200ms
+
+---
+
+## Accessibility
+- [ ] 44x44px minimum touch targets
+- [ ] Focus indicators visible
+- [ ] Proper heading hierarchy (H1 → H2 → H3)
+
+---
+
+*Generated with MORPH Framework*

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentApi.cs

@@ -1,65 +1,18 @@
 namespace Morph.AiKit.Agents;
 
-/// <summary>
-/// Protocolo pelo qual um modelo e alcancado. E o campo <c>api:</c> por alias que a
-/// issue #92 exige: a MESMA familia de modelos e atendida por dois protocolos
-/// diferentes, e qual deles vale e decisao de configuracao — nunca folclore espalhado
-/// por condicional no meio do codigo.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <see cref="Responses"/> e <b>0 de proposito</b>: <c>default(AgentApi)</c> e a Responses
-/// API porque essa e a decisao da casa (Responses por padrao, Chat Completions como
-/// opt-in explicito por alias). Um alias que omite <c>api:</c> no
-/// <c>model-registry.v2.json</c> cai em Responses; usar Chat Completions exige escrever
-/// <c>"api": "chat"</c> — ou seja, exige alguem assumir a escolha por escrito.
-/// </para>
-/// <para>
-/// O enum descreve a escolha ENTRE OS DOIS PROTOCOLOS DA OpenAI. Provider que expoe um
-/// unico protocolo (Google, Ollama) ignora o campo, e por isso declara — ou omite,
-/// caindo em — <see cref="Responses"/>: escrever <c>chat</c> ali sugeriria uma escolha
-/// que naquele provider nao existe.
-/// </para>
-/// </remarks>
 public enum AgentApi
 {
-    /// <summary>Responses API — o padrao da casa. Valor 0, logo <c>default(AgentApi)</c>.</summary>
+    // 0 de proposito: default(AgentApi) e alias sem 'api:' caem em Responses; Chat e opt-in escrito.
     Responses = 0,
 
-    /// <summary>
-    /// Chat Completions — opt-in explicito por alias. Carrega limites que a Responses API
-    /// nao tem; ver <c>Morph.AiKit.Providers.ModelAliasConstraints</c>.
-    /// </summary>
     Chat = 1,
 
-    /// <summary>
-    /// Images — geracao/edicao de imagem. <b>Nao e um protocolo de conversa</b>: um alias
-    /// com este <c>api</c> e recusado pela <c>AgentFactory</c>, com erro nomeado.
-    /// </summary>
-    /// <remarks>
-    /// Um registry so, um vocabulario so de alias: quem procura "qual modelo este projeto
-    /// usa" encontra o de imagem no mesmo lugar que o de chat. A alternativa era um
-    /// <c>media-registry.json</c> separado — duas verdades sobre o mesmo fato.
-    /// </remarks>
     Images = 2,
 
-    /// <summary>
-    /// Videos — geracao de video. Mesma regra de <see cref="Images"/>: alias de midia nao
-    /// vira agente.
-    /// </summary>
     Videos = 3,
 }
 
-/// <summary>Predicados sobre <see cref="AgentApi"/>.</summary>
 public static class AgentApiExtensions
 {
-    /// <summary>
-    /// Se o protocolo e de MIDIA (imagem ou video) e portanto nao fala conversa.
-    /// </summary>
-    /// <remarks>
-    /// Escrito uma vez, aqui, porque duas copias deste predicado sao como a
-    /// <c>AgentFactory</c> e o <c>ModelRegistry</c> passariam a discordar sobre o mesmo
-    /// alias.
-    /// </remarks>
     public static bool IsMedia(this AgentApi api) => api is AgentApi.Images or AgentApi.Videos;
 }

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentFactory.cs

@@ -5,48 +5,11 @@ using Morph.AiKit.Providers;
 
 namespace Morph.AiKit.Agents;
 
-/// <summary>
-/// Transforma uma <see cref="AgentSpec"/> (o agente como dado) num
-/// <see cref="AIAgent"/> pronto para rodar. E o unico lugar do kit que conhece a ORDEM do
-/// pipeline.
-/// </summary>
-/// <remarks>
-/// <para><b>A ordem, de fora para dentro, e o contrato desta classe:</b></para>
-/// <code>
-/// OpenTelemetryAgent            span invoke_agent — cobre a invocacao inteira (T12)
-///  +- ChatClientAgent           UseProvidedChatClientAsIs = true: o pipeline abaixo e nosso
-///      +- timeout               TimeoutSeconds vira CancellationToken
-///      +- usage-cost            ve UMA resposta com o uso ja somado das voltas (T11)
-///      +- FunctionInvoking      MaxToolIterations / AllowConcurrentToolInvocation
-///      +- telemetria de chat    span chat, ABAIXO do FICC (T12)
-///      +- cliente do provider   memoizado pelo ModelRegistry
-/// </code>
-/// <para>
-/// Cada posicao foi <b>medida</b> contra o pin, nao herdada de folclore. Acima do FICC o
-/// middleware de custo recebe o uso agregado (10/4 + 30/6 chegam como 40/10); abaixo dele
-/// receberia uma resposta por volta, e ainda leria um <c>UsageDetails</c> que o FICC muta
-/// para acumular. A telemetria de chat fica abaixo do FICC porque o MAF 1.20.0 escreve, na
-/// documentacao do proprio slot que ele reserva, que so assim o span de chat fecha antes
-/// das tools e o <c>invoke_agent</c> vira raiz.
-/// </para>
-/// <para>
-/// <b>Por que <c>UseProvidedChatClientAsIs = true</c>:</b> com o default, o
-/// <c>ChatClientAgent</c> monta ele mesmo o FICC — e nao ha onde ajustar
-/// <c>MaximumIterationsPerRequest</c> nem onde encaixar o custo entre o FICC e o cliente.
-/// O preco medido dessa escolha e que o slot de telemetria que o MAF reservaria deixa de
-/// existir: sem a T12 ligada, um agente desta fabrica emite <c>invoke_agent</c> e
-/// <b>nenhum</b> span de chat. E por isso que a telemetria de chat e um encaixe nomeado, e
-/// nao um detalhe opcional.
-/// </para>
-/// </remarks>
 public sealed class AgentFactory
 {
     private readonly ModelRegistry _registry;
     private readonly AgentFactoryOptions _options;
 
-    /// <summary>Cria a fabrica sobre um registry ja carregado.</summary>
-    /// <param name="registry">Fonte unica de alias, protocolo e tarifa.</param>
-    /// <param name="options">Infraestrutura e encaixes. Nulo = nenhum encaixe preenchido.</param>
     public AgentFactory(ModelRegistry registry, AgentFactoryOptions? options = null)
     {
         ArgumentNullException.ThrowIfNull(registry);
@@ -55,15 +18,6 @@ public sealed class AgentFactory
         _options = options ?? new AgentFactoryOptions();
     }
 
-    /// <summary>
-    /// Materializa a spec. Alias desconhecido, limite de alias violado ou troca de
-    /// protocolo sem seletor sao recusas <b>na construcao</b> — nunca um agente meio certo.
-    /// </summary>
-    /// <remarks>
-    /// Recusar aqui e falha de composicao, nao excecao como fluxo de controle: acontece uma
-    /// vez, na montagem, e seguir adiante seria seguir sem regua. Quem quiser inspecionar
-    /// antes chama <c>registry.Resolve(alias).CheckRequest(...)</c>, que e Result.
-    /// </remarks>
     public AIAgent Create(AgentSpec spec)
     {
         ArgumentNullException.ThrowIfNull(spec);
@@ -71,11 +25,6 @@ public sealed class AgentFactory
         var alias = _registry.Resolve(spec.Alias);
         var api = spec.ResolveApi(alias.Api);
 
-        // Alias de MIDIA nao vira agente, e a recusa e aqui, na construcao. Sem ela, um
-        // alias de imagem passado por engano viraria um agente de chat apontando para um
-        // modelo que nao fala chat: a falha apareceria tarde, no primeiro turno, com uma
-        // mensagem do provider que nao diz o que aconteceu. E a companheira obrigatoria de
-        // AgentApi.Images/Videos existirem — enum novo sem recusa e uma armadilha nova.
         if (alias.Api.IsMedia() || api.IsMedia())
         {
             throw AgentFactoryException.MediaAliasIsNotAnAgent(spec.Alias, alias.Api.IsMedia() ? alias.Api : api);
@@ -98,6 +47,7 @@ public sealed class AgentFactory
             Name = spec.Name,
             Description = spec.Description,
             ChatOptions = BuildChatOptions(spec, alias),
+            // Com o default o ChatClientAgent monta o proprio FICC, sem MaximumIterationsPerRequest nem slot para o custo.
             UseProvidedChatClientAsIs = true,
         };
 
@@ -112,12 +62,6 @@ public sealed class AgentFactory
             : agent;
     }
 
-    /// <summary>
-    /// As opcoes de requisicao do agente. <c>ModelId</c> vem do alias — a spec nunca cita
-    /// modelo. <c>Tools</c> e <c>ResponseFormat</c> entram antes de
-    /// <see cref="AgentSpecOptions.ApplyTo"/>, que por contrato nao sobrescreve o que ja
-    /// foi definido.
-    /// </summary>
     private static ChatOptions BuildChatOptions(AgentSpec spec, ModelAlias alias)
     {
         var options = new ChatOptions
@@ -151,6 +95,8 @@ public sealed class AgentFactory
             : throw AgentFactoryException.ProtocolWithoutSelector(alias.Name, alias.Api, api);
     }
 
+    // A ordem e o contrato: o custo fica ACIMA do FICC para ver o uso ja somado das voltas, e a
+    // telemetria de chat ABAIXO dele porque so assim o span de chat fecha antes das tools (MAF 1.20.0).
     private IChatClient BuildChatPipeline(IChatClient leaf, AgentSpec spec, ModelAlias alias)
     {
         var builder = leaf.AsBuilder();
@@ -186,11 +132,6 @@ public sealed class AgentFactory
         return builder.Build(_options.ServiceProvider);
     }
 
-    /// <summary>
-    /// Realiza <see cref="AgentSpecOptions.TimeoutSeconds"/>. Vive aqui, privado, porque e
-    /// a traducao de UMA opcao para o <see cref="CancellationToken"/> que o pipeline ja
-    /// carrega — e nao um conceito que alguem deva compor por fora.
-    /// </summary>
     private sealed class TimeoutChatClient(IChatClient inner, TimeSpan timeout) : DelegatingChatClient(inner)
     {
         public override async Task<ChatResponse> GetResponseAsync(
@@ -222,43 +163,31 @@ public sealed class AgentFactory
     }
 }
 
-/// <summary>Motivo de uma recusa da <see cref="AgentFactory"/>.</summary>
 public enum AgentFactoryError
 {
-    /// <summary>A requisicao viola um limite declarado no alias, com procedencia.</summary>
     ConstraintViolated = 0,
 
-    /// <summary>A spec pede um protocolo diferente do alias e nao ha seletor de cliente.</summary>
     ProtocolWithoutSelector = 1,
 
-    /// <summary>O seletor de cliente devolveu nulo.</summary>
     NoChatClient = 2,
 
-    /// <summary>O alias e de midia (<c>api: images</c> ou <c>api: videos</c>) e nao fala conversa.</summary>
     MediaAliasIsNotAnAgent = 3,
 }
 
-/// <summary>
-/// Recusa de composicao da <see cref="AgentFactory"/>. <c>sealed</c> e discriminada por
-/// <see cref="Reason"/>: quem trata precisa do motivo, nao de herdar do tipo.
-/// </summary>
 public sealed class AgentFactoryException : InvalidOperationException
 {
     private AgentFactoryException(AgentFactoryError reason, string message)
         : base(message)
         => Reason = reason;
 
-    /// <summary>Por que a fabrica recusou.</summary>
     public AgentFactoryError Reason { get; }
 
-    /// <summary>A requisicao viola limites do alias. A mensagem traz cada violacao com sua procedencia.</summary>
     public static AgentFactoryException ConstraintViolated(string alias, IReadOnlyList<string> violations)
         => new(
             AgentFactoryError.ConstraintViolated,
             $"alias '{alias}': a spec viola limite(s) declarado(s) do alias e o agente NAO foi criado. " +
             string.Join(" | ", violations));
 
-    /// <summary>Divergencia de protocolo sem seletor que saiba construir o outro cliente.</summary>
     public static AgentFactoryException ProtocolWithoutSelector(string alias, AgentApi aliasApi, AgentApi specApi)
         => new(
             AgentFactoryError.ProtocolWithoutSelector,
@@ -268,10 +197,6 @@ public sealed class AgentFactoryException : InvalidOperationException
             "alias com o api pedido no model-registry.v2.json, ou preencha " +
             $"{nameof(AgentFactoryOptions)}.{nameof(AgentFactoryOptions.ChatClientSelector)}.");
 
-    /// <summary>
-    /// O alias e de midia. Recusa nomeada, na construcao — nunca um agente que aponta para
-    /// um modelo que nao fala chat.
-    /// </summary>
     public static AgentFactoryException MediaAliasIsNotAnAgent(string alias, AgentApi api)
         => new(
             AgentFactoryError.MediaAliasIsNotAnAgent,
@@ -280,7 +205,6 @@ public sealed class AgentFactoryException : InvalidOperationException
             $"{nameof(Morph.AiKit.Media.IMediaGenerator)}.{nameof(Morph.AiKit.Media.IMediaGenerator.EnqueueAsync)}, " +
             "que devolve um id de job e nunca bytes. Ver ai-agents/media-pipeline.md.");
 
-    /// <summary>O seletor devolveu nulo — nao ha cliente para o par alias/protocolo.</summary>
     public static AgentFactoryException NoChatClient(string alias, AgentApi api)
         => new(
             AgentFactoryError.NoChatClient,

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentFactoryOptions.cs

@@ -5,87 +5,18 @@ using Morph.AiKit.Providers;
 
 namespace Morph.AiKit.Agents;
 
-/// <summary>
-/// O que a <see cref="AgentFactory"/> precisa saber que NAO esta na
-/// <see cref="AgentSpec"/>: infraestrutura do processo (log, DI) e os tres encaixes do
-/// pipeline que outras tasks preenchem.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que encaixes e nao dependencias diretas:</b> a ORDEM do pipeline e do kit — ela
-/// esta escrita, medida e testada dentro da <see cref="AgentFactory"/>. O CONTEUDO de cada
-/// posicao e de quem tem o tipo: o middleware de custo mora na T11 e a telemetria na T12.
-/// Se a fabrica referenciasse os dois diretamente, ou ela nasceria depois deles, ou eles
-/// nasceriam dentro dela. Com encaixe nomeado, a fabrica continua dona do lugar e cada
-/// task continua dona do que ocupa o lugar.
-/// </para>
-/// <para>
-/// Encaixe nulo = posicao vazia. Um agente sem custo e sem telemetria e um agente valido,
-/// nao um agente pela metade.
-/// </para>
-/// </remarks>
 public sealed record AgentFactoryOptions
 {
-    /// <summary>
-    /// Fabrica de log repassada ao <c>FunctionInvokingChatClient</c> e ao
-    /// <c>ChatClientAgent</c>. Nula = sem log, que e o default do MAF.
-    /// </summary>
     public ILoggerFactory? LoggerFactory { get; init; }
 
-    /// <summary>
-    /// Container usado para resolver servicos ao montar os pipelines. Nulo = os builders
-    /// do <c>Microsoft.Extensions.AI</c> usam o provider vazio deles.
-    /// </summary>
     public IServiceProvider? ServiceProvider { get; init; }
 
-    /// <summary>
-    /// De onde sai o <see cref="IChatClient"/> quando o protocolo efetivo NAO e o do alias.
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// O <c>ModelRegistry</c> memoiza <b>um</b> cliente por alias, construido pela
-    /// <c>IProviderClientFactory</c> a partir do <c>api:</c> daquele alias. Logo, uma spec
-    /// que pede Chat Completions num alias declarado <c>responses</c> nao pode ser servida
-    /// pelo cliente memoizado — ele fala o outro protocolo. Sem este seletor a fabrica
-    /// <b>recusa</b> a combinacao, nomeando os dois protocolos, em vez de devolver um agente
-    /// que diz falar um protocolo e fala outro.
-    /// </para>
-    /// <para>
-    /// Nulo (o normal) = todo agente usa o cliente memoizado do alias, e
-    /// <see cref="AgentSpec.Api"/> divergente vira recusa. Preenchido, recebe o alias e o
-    /// protocolo <b>efetivo</b> (ja resolvido por <see cref="AgentSpec.ResolveApi"/>) e
-    /// devolve o cliente correspondente.
-    /// </para>
-    /// </remarks>
     public Func<ModelAlias, AgentApi, IChatClient>? ChatClientSelector { get; init; }
 
-    /// <summary>
-    /// Encaixe do middleware de custo (T11), <b>acima</b> do <c>FunctionInvokingChatClient</c>.
-    /// Preencha com <c>(b, _, alias) =&gt; b.UseUsageCost(alias, sink)</c>.
-    /// </summary>
-    /// <remarks>
-    /// A posicao e medida, nao opinada: acima do FICC o middleware ve <b>uma</b> resposta
-    /// com o uso ja somado de todas as voltas de tool (medido: 40/10 num roteiro de duas
-    /// voltas de 10/4 e 30/6); abaixo do FICC ele ve uma resposta por volta. Pior, o FICC
-    /// <b>acumula no proprio objeto</b> <c>UsageDetails</c> da primeira volta — um sink que
-    /// guardasse a referencia abaixo do FICC leria valores que mudaram depois.
-    /// </remarks>
+    // Abaixo do FICC um sink veria uma resposta por volta, e o FICC muta o UsageDetails da primeira volta para acumular.
     public Func<ChatClientBuilder, AgentSpec, ModelAlias, ChatClientBuilder>? ConfigureUsageCost { get; init; }
 
-    /// <summary>
-    /// Encaixe da telemetria de chat (T12), <b>abaixo</b> do <c>FunctionInvokingChatClient</c>
-    /// e imediatamente acima do cliente do provider.
-    /// </summary>
-    /// <remarks>
-    /// A posicao e exigencia escrita do proprio MAF 1.20.0: com a instrumentacao abaixo do
-    /// FICC o span de chat fecha <b>antes</b> de as tools rodarem, o que deixa o
-    /// <c>invoke_agent</c> como span raiz e permite ao FICC emitir <c>execute_tool</c>.
-    /// </remarks>
     public Func<ChatClientBuilder, AgentSpec, ModelAlias, ChatClientBuilder>? ConfigureChatTelemetry { get; init; }
 
-    /// <summary>
-    /// Encaixe da telemetria de agente (T12) — o span mais externo, que cobre a invocacao
-    /// inteira. Preencha com <c>(b, _, _) =&gt; b.UseMorphTelemetry(telemetryOptions)</c>.
-    /// </summary>
     public Func<AIAgentBuilder, AgentSpec, ModelAlias, AIAgentBuilder>? ConfigureAgentTelemetry { get; init; }
 }

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentSpec.cs

@@ -3,30 +3,11 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Agents;
 
-/// <summary>
-/// O agente <b>como dado</b>: tudo o que a <c>AgentFactory</c> (T10) precisa para
-/// materializar um <c>AIAgent</c>, e nada mais. Nao tem comportamento de execucao, nao
-/// abre conexao, nao le configuracao — o que permite descrever um agente em teste, em
-/// JSON ou em banco sem arrastar infraestrutura junto.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>O modelo nao aparece aqui.</b> So o <see cref="Alias"/>, que e resolvido pelo
-/// <c>ModelRegistry</c>. E a regra do standard <c>ai-agents-providers-model-registry</c>:
-/// agentes referenciam alias, nunca id de modelo — trocar de provider e mudanca de um
-/// arquivo so.
-/// </para>
-/// </remarks>
 public sealed record AgentSpec
 {
     private readonly string _alias = string.Empty;
     private readonly string _instructions = string.Empty;
 
-    /// <summary>
-    /// Chave no <c>ModelRegistry</c>. Nunca um id de modelo.
-    /// Vazio ou so espaco e rejeitado na construcao: um alias em branco viraria uma falha
-    /// de resolucao ilegivel varias camadas adiante.
-    /// </summary>
     public required string Alias
     {
         get => _alias;
@@ -37,7 +18,6 @@ public sealed record AgentSpec
         }
     }
 
-    /// <summary>Prompt de sistema do agente. Vazio ou so espaco e rejeitado na construcao.</summary>
     public required string Instructions
     {
         get => _instructions;
@@ -48,44 +28,18 @@ public sealed record AgentSpec
         }
     }
 
-    /// <summary>
-    /// Protocolo desta spec. <b>Nulo = usa o <c>api:</c> do alias</b> — o caso normal.
-    /// Preenchido, vence o alias (ver <see cref="ResolveApi"/>).
-    /// </summary>
     public AgentApi? Api { get; init; }
 
-    /// <summary>Tools do agente. Vazio por padrao — nunca nulo.</summary>
     public IReadOnlyList<AITool> Tools { get; init; } = [];
 
-    /// <summary>
-    /// Schema JSON da saida estruturada. Nulo = saida livre.
-    /// <para>
-    /// <b>Armadilha de tempo de vida:</b> um <see cref="JsonElement"/> so e valido enquanto
-    /// o <see cref="JsonDocument"/> que o originou estiver vivo. Guarde aqui um
-    /// <see cref="JsonElement.Clone"/> quando o documento for descartado — senao o schema
-    /// morre silenciosamente entre a montagem da spec e o uso dela.
-    /// </para>
-    /// </summary>
+    // Guarde um JsonElement.Clone(): o elemento morre junto com o JsonDocument que o originou.
     public JsonElement? OutputSchema { get; init; }
 
-    /// <summary>Bag unico de opcoes. Nunca nulo; o default nao envia opcao nenhuma.</summary>
     public AgentSpecOptions Options { get; init; } = new();
 
-    /// <summary>Nome legivel do agente (telemetria, logs). Nulo = sem nome.</summary>
     public string? Name { get; init; }
 
-    /// <summary>Descricao legivel do agente. Nulo = sem descricao.</summary>
     public string? Description { get; init; }
 
-    /// <summary>
-    /// Precedencia entre o <c>api:</c> da spec e o <c>api:</c> do alias, num lugar so.
-    /// <b>A spec vence quando presente; o alias vence quando a spec e nula.</b>
-    /// </summary>
-    /// <remarks>
-    /// A regra mora aqui, e nao dentro da <c>AgentFactory</c>, porque divergencia silenciosa
-    /// entre spec e registry e exatamente o bug que o <c>api:</c> por alias existe para
-    /// eliminar — e uma regra copiada em dois lugares e uma regra que ja divergiu.
-    /// </remarks>
-    /// <param name="aliasApi">O <c>api:</c> declarado no alias resolvido.</param>
     public AgentApi ResolveApi(AgentApi aliasApi) => Api ?? aliasApi;
 }