@polymorphism-tech/morph-spec 8.28.0 → 8.31.0

package/framework/standards/STANDARDS.json

@@ -1226,7 +1226,7 @@
         "react"
       ],
       "stacks": [
-        "nextjs"
+        "*"
       ],
       "aliases": [
         "GSAP",
@@ -1260,7 +1260,7 @@
         "scroll-animation"
       ],
       "stacks": [
-        "nextjs"
+        "*"
       ],
       "aliases": [
         "ScrollTrigger",
@@ -1290,7 +1290,7 @@
         "plugins"
       ],
       "stacks": [
-        "nextjs"
+        "*"
       ],
       "aliases": [
         "Flip",
@@ -1695,21 +1695,30 @@
         "mcp"
       ],
       "stacks": [
-        "nextjs"
+        "*"
       ],
       "aliases": [
         "Image Generation",
         "AI Assets",
-        "Gemini Images"
+        "Gemini Images",
+        "brand fidelity",
+        "reference images",
+        "favicon",
+        "og image",
+        "asset generation"
       ],
       "anchors": {
         "when-to-use": "#when-to-use-ai-generated-images",
         "prompt-patterns": "#prompt-engineering-patterns",
         "aspect-ratios": "#aspect-ratio-guide",
         "assets-md": "#assetsmd-format",
-        "edit-workflows": "#iterative-editing-workflows"
+        "edit-workflows": "#iterative-editing-workflows",
+        "brand-fidelity": "#brand-fidelity-reference-dont-invent",
+        "to-video": "#downstream-images-that-become-video",
+        "favicon-og": "#the-two-assets-everyone-forgets",
+        "variations": "#variations-and-cost"
       },
-      "digest": "Guidelines for generating project images with Gemini Image MCP — prompt patterns, aspect ratios, design-system-aware prompts, iterative editing, and assets.md format."
+      "digest": "Guidelines for generating project images with the Gemini Image MCP: when to use AI versus stock versus SVG, prompt patterns, aspect ratios, iterative editing and assets.md format. Core principle is brand fidelity over invention: always pass the client's real assets as referenceImages via edit_image rather than generating in a vacuum, never AI-recreate a property developer's architectural render or a physical product (animate or reference the real one), and chain derivatives from an approved hero so the whole set shares light, palette and identity. Frame anything destined to become video WITHOUT a face, because video moderation is stricter (E005), and generate scrub frames at the video's exact ratio with the subject opposite the copy. Always produce the two forgotten assets: a favicon derived from the real logo (never a new one) and a 1200x630 OG share image. Offer two to three genuinely different variations per image, varying angle, light or composition rather than the seed, and never advance with a weak image because every derivative inherits it."
     },
     {
       "id": "ai-agents-durable-workflows-hitl",
@@ -1807,6 +1816,208 @@
         "errorbody": "#rule-2--error-path-tests-assert-the-response-body-not-just-the-status-code"
       },
       "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."
+    },
+    {
+      "id": "frontend-scroll-driven-frame-scrub",
+      "name": "frame scrub",
+      "path": "frontend/scroll-driven/frame-scrub.md",
+      "category": "frontend",
+      "subcategory": "scroll-driven",
+      "tags": [
+        "frontend",
+        "scroll-driven",
+        "motion"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "frame scrub",
+        "canvas scrub",
+        "scroll-driven video",
+        "scrollytelling video",
+        "apple scroll video",
+        "ffmpeg frames",
+        "poster fallback"
+      ],
+      "anchors": {
+        "why": "#section-1-canvas-not-video-currenttime",
+        "extraction": "#section-2-frame-extraction",
+        "cachebust": "#section-3-cache-busting-is-mandatory",
+        "bug": "#section-5-the-1x1-canvas-bug",
+        "responsive": "#section-6-responsive-and-reduced-motion",
+        "verify": "#section-8-verify-with-motion-never-with-a-still"
+      },
+      "digest": "Scroll-driven video is a preloaded JPG sequence drawn into a <canvas>, never a <video currentTime> driven by scroll (unreliable seek on iOS Safari, black-frame flashes) and never an autoplay loop (reads as a demo, not as user-driven). Extract with ffmpeg (fps=30, ~120-300 frames, -q:v 5), always extract a poster, hflip when the subject collides with the copy, and treat total sequence weight as a performance budget. Always cache-bust the frame URL (?v=N) when re-extracting under the same filenames. Known bug: a section starting hidden measures 0 and the canvas becomes 1x1 drawing one stretched pixel, so keep the canvas display:none and resize on the first loaded frame. Mobile and prefers-reduced-motion collapse to the static poster in both the JS guard and the CSS. Verify by driving the scroll through positions and comparing captured frames (allow ~350ms for scrub:0.4 to settle), never with a single screenshot."
+    },
+    {
+      "id": "frontend-scroll-driven-smooth-scroll",
+      "name": "smooth scroll",
+      "path": "frontend/scroll-driven/smooth-scroll.md",
+      "category": "frontend",
+      "subcategory": "scroll-driven",
+      "tags": [
+        "frontend",
+        "scroll-driven",
+        "motion"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "lenis",
+        "smooth scroll",
+        "scroll wiring",
+        "gsap ticker",
+        "window.__lenis",
+        "scrolltrigger refresh",
+        "HMR stale triggers"
+      ],
+      "anchors": {
+        "registry": "#section-1-central-motion-registry",
+        "raf": "#section-2-the-raf-handoff",
+        "expose": "#section-3-expose-the-instance-on-window",
+        "hmr": "#section-4-the-hmr-staleness-trap"
+      },
+      "digest": "Register GSAP plugins once in a shared lib/motion module that also exports prefersReducedMotion. Drive Lenis from gsap.ticker (never its own RAF loop), bind lenis.on(scroll, ScrollTrigger.update), set gsap.ticker.lagSmoothing(0), and call ScrollTrigger.refresh() on window load so triggers re-measure after fonts and images settle. Expose window.__lenis deliberately: overlays need stop()/start() to freeze the background, and automated verification needs scrollTo(y, {immediate:true}) to step through positions; consumers must use optional chaining because the instance is never created under reduced motion. After many hot reloads ScrollTrigger accumulates stale instances and pins/scrubs silently die, so full-reload before debugging, wrap every effect in gsap.context()/matchMedia() with revert on cleanup, and set invalidateOnRefresh on viewport-dependent triggers."
+    },
+    {
+      "id": "frontend-scroll-driven-scroll-components",
+      "name": "scroll components",
+      "path": "frontend/scroll-driven/scroll-components.md",
+      "category": "frontend",
+      "subcategory": "scroll-driven",
+      "tags": [
+        "frontend",
+        "scroll-driven",
+        "motion"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "pinned gallery",
+        "horizontal scroll",
+        "scroll reveal",
+        "parallax drift",
+        "count-up",
+        "lightbox",
+        "scroll progress",
+        "expanding modal"
+      ],
+      "anchors": {
+        "reveal": "#section-1-usereveal-the-base-brick",
+        "pinned": "#section-2-pinned-horizontal-gallery",
+        "overlays": "#section-3-expanding-modal",
+        "parallax": "#section-5-parallax-drift",
+        "rules": "#section-9-cross-cutting-rules"
+      },
+      "digest": "Toolbox of scroll-driven interaction patterns, not a mandatory list: useReveal (fade/rise with once:true) covers most content; pinned horizontal gallery needs invalidateOnRefresh:true or the travel distance stays frozen after a resize; expanding modal and lightbox mount then add an .in class on the next frame, pause the scroller via window.__lenis?.stop(), and must render OUTSIDE any pinned section because the pin transform breaks position:fixed inside it; parallax drift stays subtle at 5-8% with overflow:hidden on the figure; count-up animates a plain object and formats per locale; scroll progress uses scaleX with transform-origin 0 50% to stay on the compositor; accordions use native <details>. Cross-cutting: anything clickable that is not a button or anchor gets role=button, tabIndex 0 and Enter/Space, Escape closes overlays, every effect has a static reduced-motion fallback and reverts on cleanup."
+    },
+    {
+      "id": "frontend-design-system-premium-finish",
+      "name": "premium finish",
+      "path": "frontend/design-system/premium-finish.md",
+      "category": "frontend",
+      "subcategory": "design-system",
+      "tags": [
+        "frontend",
+        "design-system"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "premium finish",
+        "polish layer",
+        "film grain",
+        "atmosphere",
+        "load-in stagger",
+        "scrim",
+        "text over video",
+        "metallic accent",
+        "looks like a template"
+      ],
+      "anchors": {
+        "typography": "#section-1-typography-with-character",
+        "atmosphere": "#section-2-atmosphere-never-flat-color",
+        "loadin": "#section-3-one-orchestrated-load-in-beats-ten-micro-interactions",
+        "legibility": "#section-4-legibility-over-video-close-to-a-hard-rule",
+        "order": "#section-7-order-of-application"
+      },
+      "digest": "The finish layer that separates a working build from one a client reads as expensive, applied from the start rather than as a final polish pass. Principles, never a fixed recipe, and never converge on the same choices across projects: commit to a display font chosen from the brand (stack defaults and the AI-tell faces like Space Grotesk/Playfair announce machine-generated); use atmosphere instead of flat color (feTurbulence film grain at low opacity, radial brand glow, vignette); concentrate effort on ONE orchestrated hero load-in with staggered animation-delay rather than scattered micro-interactions; text over media always gets a DIRECTIONAL scrim (dark where the copy lives, clear over the subject) plus text-shadow as insurance against bright frames; one precious accent used in three places or fewer. Define brand tokens as CSS variables first, then atmosphere, then hero, then accent, then details."
+    },
+    {
+      "id": "frontend-seo-meta-schema-audit",
+      "name": "meta schema audit",
+      "path": "frontend/seo/meta-schema-audit.md",
+      "category": "frontend",
+      "subcategory": "seo",
+      "tags": [
+        "frontend",
+        "seo",
+        "accessibility"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "seo",
+        "meta tags",
+        "open graph",
+        "og:image",
+        "schema.org",
+        "json-ld",
+        "rich results",
+        "lighthouse",
+        "go-live audit",
+        "canonical"
+      ],
+      "anchors": {
+        "meta": "#section-1-essential-meta",
+        "opengraph": "#section-2-open-graph-and-twitter-cards",
+        "schema": "#section-3-schemaorg-json-ld-by-business-type",
+        "a11y": "#section-4-accessibility-also-an-seo-signal",
+        "audit": "#section-5-pre-launch-audit"
+      },
+      "digest": "Head-level SEO is cheap and pays for itself: title/description/canonical/theme-color/favicon, correct lang, font preconnects, and a full Open Graph set with an absolute 1200x630 og:image (without it a pasted link renders as a bare card). Pick the JSON-LD @type from the business (ClothingStore/Store for retail, LocalBusiness for services, RealEstateAgent or Residence for property, SoftwareApplication for SaaS) and include ONLY true fields: aggregateRating goes in only with a real rating and review count from a real source, otherwise omit the block, because fabricated structured data is a trust and manual-action risk. Accessibility doubles as an SEO signal (alt text, contrast checked against the brightest frames, focus order, one h1, reduced-motion honored). Before go-live run Lighthouse, a clean-console check, a share-card check and cross-device; if a heavy frame sequence costs Performance, confirm the cost sits in the scrub and state the trade rather than letting a low score pass unexamined."
+    },
+    {
+      "id": "frontend-design-system-ai-video-generation",
+      "name": "AI Video Generation",
+      "path": "frontend/design-system/ai-video-generation.md",
+      "category": "frontend",
+      "subcategory": "design-system",
+      "tags": [
+        "video",
+        "seedance",
+        "asset",
+        "ai-generation",
+        "motion",
+        "mcp"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "video generation",
+        "seedance",
+        "img2vid",
+        "endImage",
+        "directional footage",
+        "loop video",
+        "E005",
+        "animate render",
+        "scroll scrub footage"
+      ],
+      "anchors": {
+        "loop-vs-directional": "#section-1-the-distinction-that-decides-everything",
+        "directional": "#section-2-building-directional-footage",
+        "moderation": "#section-3-faces-trip-moderation",
+        "cost-ladder": "#section-4-the-cost-ladder",
+        "prompt-skeleton": "#section-5-prompt-skeleton"
+      },
+      "digest": "The decisive rule: a perfect loop has an end frame identical to its start, which is right for a self-playing ambient background and WRONG for scroll scrubbing, because start and end look the same and the page reads as frozen while the user scrolls. Scroll-driven footage needs directional movement via generate_video with an endImage (push-in/dolly is the most reliable, then reveal, pull-back, slow tilt); avoid orbits and any movement that returns to its origin. Client architectural renders are animated with img2vid, never AI-recreated. Human faces repeatedly trip moderation (E005), so crop the face out of frame (neck down, hands, product) and reserve faces for static image generation. Always climb the cost ladder: fast/480p/4s draft to judge framing and movement, 1080p only after approval, then re-extract frames with a bumped cache-bust. Prompts read like director notes with no hype words, and must reserve a calm dark region for the page copy with the subject on the opposite side. Generation is async: generate_video returns a request_id polled via get_video; list_videos reads local history and spends no credits."
     }
   ],
   "sharedAliases": {

package/framework/standards/ai-agents/agent-session.md

@@ -1,160 +1,160 @@
-# Agent Session — Conversation state and chat reducers
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 2 (on-keyword)
-> **Keywords:** agent session, chat history, conversation state, chat reducer, history truncation, AgentThread
-> **Read by Claude in:** implement
-
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
-
----
-
-## Quando usar AgentSession
-
-Use `AgentSession` quando o agente é **conversacional** — há uma UI de chat que mantém histórico entre turnos do usuário.
-
-**Use AgentSession quando:**
-- Existe uma interface de chat (web, mobile, CLI interativo)
-- O agente precisa lembrar o que foi dito nos turnos anteriores da mesma conversa
-- Há perguntas de follow-up ("e agora?", "altere o segundo ponto", "lembra do que disse sobre X?")
-
-**NÃO use AgentSession quando:**
-- O agente é one-shot (gerador, executor, classificador) — recebe uma entrada, devolve uma saída, fim
-- Agentes stateless em pipeline multi-agent — cada chamada é independente
-- Jobs de batch/background — não há conversa; histórico não faz sentido
-
-> "Add Memory/Session because agents need state" é um anti-pattern de `sweet-spot.md`.
-> Só adicione quando uma UI de chat real existe.
-
----
-
-## A API
-
-**Pacote:** `Microsoft.Agents.AI` (base; já requerido por `ai-agents-setup`).
-
-**Tipos confirmados via context7:**
-- `AgentSession` — container leve de estado de conversa; obtido via `agent.CreateSessionAsync()`
-- `AgentThread` — equivalente para agentes persistentes (PersistentAgentsClient); use `agent.GetNewThread()`
-- `ChatClientAgentOptions` — aceita `ChatHistoryProvider` e `AIContextProviders`
-- `InMemoryChatHistoryProvider` — implementação embutida de histórico em memória
-- `AgentResponse` — tipo retornado por `AIAgent.RunAsync` (non-generic); acesse o texto via `.Text`
-
-```csharp
-// Construção do agente com histórico em memória
-AIAgent agent = _modelRegistry.GetChatClient("text-default")
-    .AsAIAgent(new ChatClientAgentOptions
-    {
-        ChatOptions = new() { Instructions = "You are a helpful assistant." },
-        ChatHistoryProvider = new InMemoryChatHistoryProvider(),
-    });
-```
-
----
-
-## Exemplo C# — agente conversacional com session persistente entre turnos
-
-```csharp
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-// ── 1. Registrar o agente conversacional no DI ──
-// Program.cs
-builder.Services.AddSingleton<AIAgent>(sp =>
-{
-    var registry = sp.GetRequiredService<ModelRegistry>();
-    return registry.GetChatClient("text-default")
-        .AsAIAgent(new ChatClientAgentOptions
-        {
-            ChatOptions = new() { Instructions = "You are a helpful customer support assistant." },
-            // InMemoryChatHistoryProvider: histórico vive em memória, por session.
-            // Seguro registrar como parte do singleton AIAgent: cada AgentSession criada via
-            // agent.CreateSessionAsync() isola o histórico de sua conversa — conversas distintas
-            // não compartilham estado. O provider em si é stateless; o estado fica na session.
-            // Para persistência entre restarts, substitua por um provider customizado (ex: DB).
-            ChatHistoryProvider = new InMemoryChatHistoryProvider(),
-        });
-});
-
-// ── 2. Criar uma session por conversa (ex: por conexão SignalR / por request de "start chat") ──
-// ChatController.cs ou ChatHub.cs
-public class ChatService(AIAgent _agent)
-{
-    // Uma session por conversa ativa — armazene no escopo do usuário (cache, memória da conexão)
-    public async Task<AgentSession> StartConversationAsync()
-        => await _agent.CreateSessionAsync();
-
-    // Cada mensagem do usuário passa a mesma session
-    public async Task<string> SendMessageAsync(AgentSession session, string userMessage)
-    {
-        AgentResponse response = await _agent.RunAsync(userMessage, session);
-        return response.Text;
-    }
-}
-
-// ── 3. Uso no controller/hub ──
-// Primeiro turno
-AgentSession session = await chatService.StartConversationAsync();
-string reply1 = await chatService.SendMessageAsync(session, "Meu pedido #1234 está atrasado.");
-// reply1: "Vou verificar o pedido #1234 para você..."
-
-// Segundo turno — o agente lembra do contexto anterior
-string reply2 = await chatService.SendMessageAsync(session, "E quando foi despachado?");
-// reply2: "O pedido #1234 foi despachado em..."  ← contexto mantido pela session
-```
-
----
-
-## History management
-
-O histórico cresce a cada turno. Quando estoura o context window do modelo, as chamadas falham ou truncam silenciosamente.
-
-### Estratégias
-
-| Estratégia | Quando usar | Como implementar |
-|------------|-------------|------------------|
-| **Sliding window** | Conversas longas com contexto recente suficiente | Limitar `InMemoryChatHistoryProvider` a N mensagens mais recentes |
-| **Token budget** | Modelos com context window pequeno | Contar tokens acumulados; truncar quando ultrapassa threshold |
-| **Summarization** | Histórico precisa de contexto antigo comprimido | Agente periódico que resume N turnos anteriores em uma mensagem única |
-
-> **Custom history management:** Para o caso comum, `InMemoryChatHistoryProvider` cobre a
-> necessidade de histórico em memória por sessão. Se o projeto exigir truncation customizada
-> (ex: sliding window limitando a N mensagens mais recentes ou por token budget), o mecanismo
-> de extensão correto — seja subclasse de `ChatHistoryProvider`, um `IChatReducer`, ou outro
-> ponto de override — deve ser verificado contra a versão instalada de `Microsoft.Agents.AI`.
-> Consulte a documentação MAF atual antes de implementar um provider customizado, pois a API
-> exata de extensão não foi confirmada na versão GA e pode variar entre releases.
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Problema |
-|-------------|----------|
-| Adicionar session em agente one-shot (gerador, executor) | Complexidade desnecessária; estado nunca é usado |
-| Histórico ilimitado sem truncation | Context window estoura; custo aumenta linearmente com a conversa |
-| Compartilhar uma `AgentSession` entre múltiplos usuários | Histórico de um usuário vaza para outro |
-| Usar `InMemoryChatHistoryProvider` sem criar uma `AgentSession` por conversa | Sem `AgentSession` por conversa, o histórico é compartilhado entre todos os usuários; a isolation depende de `AgentSession` — sempre crie uma session por conversa via `agent.CreateSessionAsync()` |
-| Usar `AgentThread` (PersistentAgentsClient) sem necessidade | `AgentThread` requer hosted agent service; prefira `AgentSession` com direct model |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] `AgentSession` usada somente em agentes conversacionais com UI de chat real
-- [ ] `InMemoryChatHistoryProvider` (ou equivalente) registrado em `ChatClientAgentOptions`
-- [ ] Uma `AgentSession` por conversa/usuário — nunca compartilhada
-- [ ] Estratégia de truncation definida (sliding window, token budget ou summarization)
-- [ ] Agentes one-shot (gerador, executor, classificador) **não** recebem session
-
----
-
-## References
-
-- `ai-agents-setup` — packages e DI base
-- `ai-agents-sweet-spot` — decisão de quando adicionar estado ao agente
-- `ai-agents-middleware-patterns` (Onda 2) — pipeline de contexto e middleware
-- MAF Conversations docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-session.md v1.0 (2026-05-19)*
+# Agent Session — Conversation state and chat reducers
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** agent session, chat history, conversation state, chat reducer, history truncation, AgentThread
+> **Read by Claude in:** implement
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar AgentSession
+
+Use `AgentSession` quando o agente é **conversacional** — há uma UI de chat que mantém histórico entre turnos do usuário.
+
+**Use AgentSession quando:**
+- Existe uma interface de chat (web, mobile, CLI interativo)
+- O agente precisa lembrar o que foi dito nos turnos anteriores da mesma conversa
+- Há perguntas de follow-up ("e agora?", "altere o segundo ponto", "lembra do que disse sobre X?")
+
+**NÃO use AgentSession quando:**
+- O agente é one-shot (gerador, executor, classificador) — recebe uma entrada, devolve uma saída, fim
+- Agentes stateless em pipeline multi-agent — cada chamada é independente
+- Jobs de batch/background — não há conversa; histórico não faz sentido
+
+> "Add Memory/Session because agents need state" é um anti-pattern de `sweet-spot.md`.
+> Só adicione quando uma UI de chat real existe.
+
+---
+
+## A API
+
+**Pacote:** `Microsoft.Agents.AI` (base; já requerido por `ai-agents-setup`).
+
+**Tipos confirmados via context7:**
+- `AgentSession` — container leve de estado de conversa; obtido via `agent.CreateSessionAsync()`
+- `AgentThread` — equivalente para agentes persistentes (PersistentAgentsClient); use `agent.GetNewThread()`
+- `ChatClientAgentOptions` — aceita `ChatHistoryProvider` e `AIContextProviders`
+- `InMemoryChatHistoryProvider` — implementação embutida de histórico em memória
+- `AgentResponse` — tipo retornado por `AIAgent.RunAsync` (non-generic); acesse o texto via `.Text`
+
+```csharp
+// Construção do agente com histórico em memória
+AIAgent agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new() { Instructions = "You are a helpful assistant." },
+        ChatHistoryProvider = new InMemoryChatHistoryProvider(),
+    });
+```
+
+---
+
+## Exemplo C# — agente conversacional com session persistente entre turnos
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// ── 1. Registrar o agente conversacional no DI ──
+// Program.cs
+builder.Services.AddSingleton<AIAgent>(sp =>
+{
+    var registry = sp.GetRequiredService<ModelRegistry>();
+    return registry.GetChatClient("text-default")
+        .AsAIAgent(new ChatClientAgentOptions
+        {
+            ChatOptions = new() { Instructions = "You are a helpful customer support assistant." },
+            // InMemoryChatHistoryProvider: histórico vive em memória, por session.
+            // Seguro registrar como parte do singleton AIAgent: cada AgentSession criada via
+            // agent.CreateSessionAsync() isola o histórico de sua conversa — conversas distintas
+            // não compartilham estado. O provider em si é stateless; o estado fica na session.
+            // Para persistência entre restarts, substitua por um provider customizado (ex: DB).
+            ChatHistoryProvider = new InMemoryChatHistoryProvider(),
+        });
+});
+
+// ── 2. Criar uma session por conversa (ex: por conexão SignalR / por request de "start chat") ──
+// ChatController.cs ou ChatHub.cs
+public class ChatService(AIAgent _agent)
+{
+    // Uma session por conversa ativa — armazene no escopo do usuário (cache, memória da conexão)
+    public async Task<AgentSession> StartConversationAsync()
+        => await _agent.CreateSessionAsync();
+
+    // Cada mensagem do usuário passa a mesma session
+    public async Task<string> SendMessageAsync(AgentSession session, string userMessage)
+    {
+        AgentResponse response = await _agent.RunAsync(userMessage, session);
+        return response.Text;
+    }
+}
+
+// ── 3. Uso no controller/hub ──
+// Primeiro turno
+AgentSession session = await chatService.StartConversationAsync();
+string reply1 = await chatService.SendMessageAsync(session, "Meu pedido #1234 está atrasado.");
+// reply1: "Vou verificar o pedido #1234 para você..."
+
+// Segundo turno — o agente lembra do contexto anterior
+string reply2 = await chatService.SendMessageAsync(session, "E quando foi despachado?");
+// reply2: "O pedido #1234 foi despachado em..."  ← contexto mantido pela session
+```
+
+---
+
+## History management
+
+O histórico cresce a cada turno. Quando estoura o context window do modelo, as chamadas falham ou truncam silenciosamente.
+
+### Estratégias
+
+| Estratégia | Quando usar | Como implementar |
+|------------|-------------|------------------|
+| **Sliding window** | Conversas longas com contexto recente suficiente | Limitar `InMemoryChatHistoryProvider` a N mensagens mais recentes |
+| **Token budget** | Modelos com context window pequeno | Contar tokens acumulados; truncar quando ultrapassa threshold |
+| **Summarization** | Histórico precisa de contexto antigo comprimido | Agente periódico que resume N turnos anteriores em uma mensagem única |
+
+> **Custom history management:** Para o caso comum, `InMemoryChatHistoryProvider` cobre a
+> necessidade de histórico em memória por sessão. Se o projeto exigir truncation customizada
+> (ex: sliding window limitando a N mensagens mais recentes ou por token budget), o mecanismo
+> de extensão correto — seja subclasse de `ChatHistoryProvider`, um `IChatReducer`, ou outro
+> ponto de override — deve ser verificado contra a versão instalada de `Microsoft.Agents.AI`.
+> Consulte a documentação MAF atual antes de implementar um provider customizado, pois a API
+> exata de extensão não foi confirmada na versão GA e pode variar entre releases.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema |
+|-------------|----------|
+| Adicionar session em agente one-shot (gerador, executor) | Complexidade desnecessária; estado nunca é usado |
+| Histórico ilimitado sem truncation | Context window estoura; custo aumenta linearmente com a conversa |
+| Compartilhar uma `AgentSession` entre múltiplos usuários | Histórico de um usuário vaza para outro |
+| Usar `InMemoryChatHistoryProvider` sem criar uma `AgentSession` por conversa | Sem `AgentSession` por conversa, o histórico é compartilhado entre todos os usuários; a isolation depende de `AgentSession` — sempre crie uma session por conversa via `agent.CreateSessionAsync()` |
+| Usar `AgentThread` (PersistentAgentsClient) sem necessidade | `AgentThread` requer hosted agent service; prefira `AgentSession` com direct model |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `AgentSession` usada somente em agentes conversacionais com UI de chat real
+- [ ] `InMemoryChatHistoryProvider` (ou equivalente) registrado em `ChatClientAgentOptions`
+- [ ] Uma `AgentSession` por conversa/usuário — nunca compartilhada
+- [ ] Estratégia de truncation definida (sliding window, token budget ou summarization)
+- [ ] Agentes one-shot (gerador, executor, classificador) **não** recebem session
+
+---
+
+## References
+
+- `ai-agents-setup` — packages e DI base
+- `ai-agents-sweet-spot` — decisão de quando adicionar estado ao agente
+- `ai-agents-middleware-patterns` (Onda 2) — pipeline de contexto e middleware
+- MAF Conversations docs: https://learn.microsoft.com/en-us/agent-framework/agents/conversations/
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-session.md v1.0 (2026-05-19)*