@polymorphism-tech/morph-spec 8.45.0 → 8.47.0

package/framework/standards/data/nosql/cache/redis.md

@@ -1,66 +1,126 @@
-# Data Standard: Redis Cache (Azure Cache for Redis)
+# Data Standard: Redis Cache
 
 > **Scope:** data-nosql-cache
 > **Layer:** 2
 > **Keywords:** redis, cache, distributed-cache, session, rate-limiting, stackexchange-redis, azure-cache
 > **Load When:** caching, session storage, or rate limiting is in scope
 
-**Verified against:** .NET 10 + StackExchange.Redis 2.x + Microsoft.Extensions.Caching.StackExchangeRedis. Last-verified: 2026-05-20.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + Microsoft.Extensions.Caching.StackExchangeRedis 10.0.12 + StackExchange.Redis 2.13.17 + EF Core 10.0.12. The registration, cache-aside handler, invalidation and rate-limit blocks compile with `TreatWarningsAsErrors` over the `Result` of `result-pattern.md`; package dependencies read from the nuget.org nuspec on 2026-10-03. Last-verified: 2026-10-03.
 
 ---
 
 ## Overview
-Distributed cache for session data, rate limiting, and frequently-read data.
+Distributed cache for session data, rate limiting, and frequently-read data -- a Redis on the Coolify VPS or a managed one (Azure Cache for Redis, Upstash); the code is the same. Redis is never the primary store: the `ApplicationDbContext` is.
 
 ## Setup
 ```xml
-<PackageReference Include="StackExchange.Redis" Version="2.*" />
-<PackageReference Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="9.*" />
+<PackageReference Include="Microsoft.Extensions.Caching.StackExchangeRedis" Version="10.0.12" />
+<!-- only when you inject IConnectionMultiplexer directly (rate limiting, pub/sub) -->
+<PackageReference Include="StackExchange.Redis" Version="2.13.17" />
 ```
 
+`Microsoft.Extensions.Caching.StackExchangeRedis` 10.0.12 depends on `StackExchange.Redis` >= 2.7.27, so NuGet resolves that floor unless you pin a newer one. When the code touches `IConnectionMultiplexer`, reference `StackExchange.Redis` explicitly at the latest **2.x**: the 3.x line is a new major that the caching package has not moved to.
+
 ```csharp
-// Program.cs
-builder.Services.AddStackExchangeRedisCache(opts =>
+// Program.cs (or an AddRedisCache extension)
+using Microsoft.Extensions.Caching.StackExchangeRedis;
+using StackExchange.Redis;
+
+public static class RedisRegistration
 {
-    opts.Configuration = config["Redis:ConnectionString"]; // from Key Vault
-    opts.InstanceName = "myapp:"; // Prefix to avoid key collisions
-});
+    public static IServiceCollection AddRedisCache(this IServiceCollection services, IConfiguration configuration)
+    {
+        var connectionString = configuration.GetConnectionString("Redis")
+            ?? throw new InvalidOperationException("ConnectionStrings:Redis is not configured.");
+
+        services.AddSingleton<IConnectionMultiplexer>(_ => ConnectionMultiplexer.Connect(connectionString));
+        services.AddStackExchangeRedisCache(options => options.InstanceName = "myapp:");
+        services.AddOptions<RedisCacheOptions>().Configure<IServiceProvider>((options, sp) =>
+            options.ConnectionMultiplexerFactory = () => Task.FromResult(sp.GetRequiredService<IConnectionMultiplexer>()));
+        return services;
+    }
+}
 ```
 
+- The connection string comes from configuration: user-secrets in development, a Coolify environment variable (`ConnectionStrings__Redis`) in production -- never from code.
+- `InstanceName` prefixes every `IDistributedCache` key (`myapp:`), so two apps on one Redis do not collide.
+- The missing-connection-string `throw` runs once at startup, which is configuration validation, not control flow.
+- One shared `IConnectionMultiplexer` serves both the cache and direct Redis calls (it is thread-safe and expensive to create). It is registered as a **lazy** singleton and handed to the cache through `Configure<IServiceProvider>`, so the first use connects -- never `ConnectionMultiplexer.Connect` during registration: with `AbortOnConnectFail` (the default outside Azure) an unreachable Redis would stop the app from booting, making the cache a hard dependency. Never call `services.BuildServiceProvider()` inside the factory either: that builds a second container with a second multiplexer. If you do not need the multiplexer directly, drop it and set `options.Configuration = connectionString`.
+
 ## Cache-Aside Pattern
+
+Cache-aside lives in the slice handler, next to the `ApplicationDbContext` -- no `CachedProductService` wrapping a repository. Cache the **response DTO**, not the EF entity (navigation properties and change tracking do not serialize cleanly), and return a `Result`: a miss in both cache and database is `NotFound`, never `null`.
+
 ```csharp
-public class CachedProductService : IProductService
+// Features/ProductFeature/GetProduct/GetProductHandler.cs
+using System.Text.Json;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Caching.Distributed;
+
+public sealed record GetProductRequest(Guid Id);
+public sealed record ProductResponse(Guid Id, string Name, decimal Price);
+
+public static class ProductCacheKeys
+{
+    public static string Detail(Guid id) => $"product:detail:{id}";
+}
+
+public sealed class GetProductHandler(ApplicationDbContext db, IDistributedCache cache)
+    : IHandler<GetProductRequest, Result<ProductResponse>>
 {
-    private readonly IDistributedCache _cache;
-    private readonly ApplicationDbContext _db;
+    private static readonly DistributedCacheEntryOptions CacheEntry = new()
+    {
+        AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(15),
+        SlidingExpiration = TimeSpan.FromMinutes(5)
+    };
 
-    public async Task<Product?> GetAsync(Guid id, CancellationToken ct = default)
+    public async Task<Result<ProductResponse>> HandleAsync(GetProductRequest request, CancellationToken cancellationToken)
     {
-        var cacheKey = $"product:{id}";
-
-        // Try cache first
-        var cached = await _cache.GetStringAsync(cacheKey, ct);
-        if (cached != null)
-            return JsonSerializer.Deserialize<Product>(cached);
-
-        // Cache miss → read from DB
-        var product = await _db.Products.FindAsync([id], ct);
-        if (product == null) return null;
-
-        // Cache with TTL
-        await _cache.SetStringAsync(cacheKey,
-            JsonSerializer.Serialize(product),
-            new DistributedCacheEntryOptions
-            {
-                AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(15),
-                SlidingExpiration = TimeSpan.FromMinutes(5)
-            }, ct);
+        var key = ProductCacheKeys.Detail(request.Id);
+
+        var cached = await cache.GetStringAsync(key, cancellationToken);
+        if (cached is not null)
+            return JsonSerializer.Deserialize<ProductResponse>(cached);
+
+        var product = await db.Products
+            .Where(p => p.Id == request.Id)
+            .Select(p => new ProductResponse(p.Id, p.Name, p.Price))
+            .FirstOrDefaultAsync(cancellationToken);
+
+        if (product is null)
+            return ProductErrors.NotFound(request.Id);
 
+        await cache.SetStringAsync(key, JsonSerializer.Serialize(product), CacheEntry, cancellationToken);
         return product;
     }
+}
+```
+
+### Invalidation
 
-    public async Task InvalidateAsync(Guid id, CancellationToken ct = default)
-        => await _cache.RemoveAsync($"product:{id}", ct);
+The handler that writes invalidates the exact key, **after** `SaveChangesAsync`:
+
+```csharp
+// Features/ProductFeature/UpdateProductPrice/UpdateProductPriceHandler.cs
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Caching.Distributed;
+
+public sealed record UpdateProductPriceRequest(Guid Id, decimal Price);
+
+public sealed class UpdateProductPriceHandler(ApplicationDbContext db, IDistributedCache cache)
+    : IHandler<UpdateProductPriceRequest, Result>
+{
+    public async Task<Result> HandleAsync(UpdateProductPriceRequest request, CancellationToken cancellationToken)
+    {
+        var product = await db.Products.FirstOrDefaultAsync(p => p.Id == request.Id, cancellationToken);
+        if (product is null)
+            return ProductErrors.NotFound(request.Id);
+
+        product.Price = request.Price;
+        await db.SaveChangesAsync(cancellationToken);
+        await cache.RemoveAsync(ProductCacheKeys.Detail(request.Id), cancellationToken);
+        return Result.Success();
+    }
 }
 ```
 
@@ -85,22 +145,38 @@ Examples:
   auth:ratelimit:user123:login
 ```
 
+Keep key builders in one static class per feature (`ProductCacheKeys`) so the reader and the invalidator cannot drift.
+
 ## Rate Limiting Pattern
+
+For a single instance, ASP.NET Core's built-in rate limiter (`AddRateLimiter`) is enough. Across several instances the counter must be shared, so it lives in Redis:
+
 ```csharp
-public async Task<bool> IsRateLimitedAsync(string userId, string action, int maxPerMinute)
+// Infrastructure/RateLimiting/RedisRateLimiter.cs
+using StackExchange.Redis;
+
+public sealed class RedisRateLimiter(IConnectionMultiplexer redis, TimeProvider timeProvider)
 {
-    var key = $"ratelimit:{action}:{userId}:{DateTime.UtcNow:yyyyMMddHHmm}";
-    var db = _redis.GetDatabase();
+    public async Task<bool> IsRateLimitedAsync(string userId, string action, int maxPerMinute)
+    {
+        var key = $"ratelimit:{action}:{userId}:{timeProvider.GetUtcNow():yyyyMMddHHmm}";
+        var db = redis.GetDatabase();
 
-    var count = await db.StringIncrementAsync(key);
-    if (count == 1) await db.KeyExpireAsync(key, TimeSpan.FromMinutes(1));
+        var count = await db.StringIncrementAsync(key);
+        if (count == 1)
+            await db.KeyExpireAsync(key, TimeSpan.FromMinutes(1));
 
-    return count > maxPerMinute;
+        return count > maxPerMinute;
+    }
 }
 ```
 
+The minute comes from `TimeProvider` (testable with `FakeTimeProvider`), never `DateTime.UtcNow`.
+
 ## Anti-Patterns
 - Never cache sensitive data (passwords, tokens, PII) without encryption
-- Never use Redis as primary store — it's a cache, not a database
-- Never omit TTL — unbounded keys fill memory
-- Never catch RedisException silently — degrade gracefully to DB
+- Never use Redis as primary store -- it's a cache, not a database
+- Never omit TTL -- unbounded keys fill memory
+- Never wrap the cache in a `XService`/repository class -- cache-aside is three lines in the handler
+- Never return `null` for "not found" -- the handler returns `Result` with `NotFound`
+- Never swallow `RedisConnectionException` in an empty `catch`: a cache outage must be visible (health check + logs). Falling back to the database while Redis is down is a product decision: record it in `decisions.md` and implement it once, at the cache boundary, not per call site

package/framework/standards/data/nosql/cosmos-db.md

@@ -1,26 +1,29 @@
-# Data Standard: Azure Cosmos DB
+# Data Standard: Azure Cosmos DB (optional — outside the baked-in stack)
 
 > **Scope:** data-nosql
-> **Layer:** 2
+> **Layer:** 3 (opcional — nenhuma rule nem persona o carrega; só sob demanda via `morph-spec standards --find`, depois de a decisão existir)
 > **Keywords:** cosmos-db, nosql, document-database, event-store, partition-key, azure-cosmos
-> **Load When:** a NoSQL document store, event store, or globally distributed data is in scope
+> **Load When:** `decisions.md` already records the choice of Cosmos DB over Neon for a specific store
 
-**Verified against:** .NET 10 + Microsoft.Azure.Cosmos SDK v3. Last-verified: 2026-05-20.
+**Verified against:** .NET 10 (SDK 10.0.400-preview) + Microsoft.Azure.Cosmos 3.63.2 + Newtonsoft.Json 13.0.4 — every `csharp` block below compiles with `TreatWarningsAsErrors` against the `Result`/`Error` types of `backend-dotnet-result-pattern`. Last-verified: 2026-10-03.
 
 ---
 
 ## Overview
-NoSQL document database — use for high-throughput, globally distributed, or schema-flexible data.
 
-## When to Use Cosmos DB
-✅ Event store (append-only, high write throughput)
-✅ User activity/session data (variable schema)
-✅ Multi-region writes required
-✅ JSON documents with flexible schema
-❌ Relational data with complex joins (use Azure SQL)
-❌ Small datasets (cost inefficient)
+**Cosmos DB is not part of the stack.** The default store is Neon (Postgres) through EF Core, with the `ApplicationDbContext` used directly in the slice. Reach for Cosmos only when a requirement Postgres cannot meet is written down in `decisions.md` (the "why not Neon" included). Everything below applies the stack conventions to that exception: the client is injected straight into the slice handler, ids are `Guid.CreateVersion7()`, expected failures are `Result` values, and classes are `sealed`.
+
+## When It Can Be Justified
+
+✅ Multi-region writes are a hard requirement
+✅ Append-only event stream with write throughput beyond what the Neon plan sustains
+✅ Documents whose schema varies per tenant and is never joined
+❌ Relational data, joins, reporting — use Neon (Postgres) via EF Core
+❌ Small datasets — cost-inefficient, and one more store to operate
+❌ "Flexible schema" alone — Postgres `jsonb` already covers it
 
 ## Container Design
+
 ```json
 {
   "partitionKey": "/tenantId",
@@ -37,88 +40,128 @@ NoSQL document database — use for high-throughput, globally distributed, or sc
 ### Partition Key Strategy
 - High cardinality: userId, tenantId, orderId
 - Even distribution: avoid hot partitions (e.g., /status = "active" for 90% of docs)
-- Query alignment: partition key should appear in most queries
+- Query alignment: the partition key appears in most queries — a cross-partition query fans out to every partition and is billed for each
 
 ## SDK Setup
+
+Packages: `Microsoft.Azure.Cosmos` **and** an explicit `Newtonsoft.Json` reference — the Cosmos 3.x build targets fail the build without it, even when the client serializes with System.Text.Json.
+
+One `CosmosClient` per process (it owns the connection pool), and the `Container` registered as a keyed singleton so a slice asks for exactly the container it uses. No repository wrapper: `Container` already is the data-access API, the same way `DbSet<T>` is under EF Core.
+
 ```csharp
-// Program.cs
-builder.Services.AddSingleton(sp =>
-    new CosmosClient(
-        config["CosmosDb:ConnectionString"],
-        new CosmosClientOptions
-        {
-            SerializerOptions = new CosmosSerializationOptions
-            {
-                PropertyNamingPolicy = CosmosPropertyNamingPolicy.CamelCase
-            },
-            ApplicationName = "MyApp"
-        }));
-
-builder.Services.AddSingleton<ICosmosRepository<Order>>(sp =>
-    new CosmosRepository<Order>(
-        sp.GetRequiredService<CosmosClient>(),
-        config["CosmosDb:DatabaseId"],
-        "orders"));
+builder.Services.AddSingleton(_ => new CosmosClient(
+    builder.Configuration["CosmosDb:ConnectionString"],
+    new CosmosClientOptions
+    {
+        UseSystemTextJsonSerializerWithOptions = new JsonSerializerOptions(JsonSerializerDefaults.Web),
+        ApplicationName = "MyApp"
+    }));
+
+builder.Services.AddKeyedSingleton("order-events", (sp, _) =>
+    sp.GetRequiredService<CosmosClient>().GetContainer(
+        builder.Configuration["CosmosDb:DatabaseId"], "order-events"));
 ```
 
-## Repository Pattern
+## Document Shape
+
 ```csharp
-public class CosmosRepository<T> where T : CosmosDocument
+public sealed record OrderEvent(
+    string Id,
+    string TenantId,
+    string Type,
+    DateTimeOffset CreatedAt,
+    int? Ttl = null);
+```
+
+`JsonSerializerDefaults.Web` serializes `Id` as `id`, which is the property Cosmos requires.
+
+## Handler in the Slice
+
+The stream APIs return the status code instead of throwing, so a missing item or a duplicate id is an expected outcome mapped to a `Result` — not a `try/catch` around `CosmosException`. Unexpected failures still surface as exceptions and reach the global exception handler.
+
+```csharp
+public sealed record AppendOrderEvent(string TenantId, string Type);
+
+public static class OrderEventErrors
 {
-    private readonly Container _container;
+    public static Error NotFound(string id) =>
+        Error.NotFound("OrderEvent.NotFound", $"Order event '{id}' was not found.");
+
+    public static Error Duplicate(string id) =>
+        Error.Conflict("OrderEvent.Duplicate", $"Order event '{id}' already exists.");
 
-    public async Task<T?> GetAsync(string id, string partitionKey)
+    public static Error StoreFailure(HttpStatusCode status) =>
+        Error.Unexpected("OrderEvent.StoreFailure", $"Cosmos DB answered {(int)status}.");
+}
+
+public sealed class AppendOrderEventHandler(
+    [FromKeyedServices("order-events")] Container container,
+    TimeProvider clock)
+{
+    public async Task<Result<OrderEvent>> HandleAsync(AppendOrderEvent command, CancellationToken ct)
     {
-        try
-        {
-            var response = await _container.ReadItemAsync<T>(id, new PartitionKey(partitionKey));
-            return response.Resource;
-        }
-        catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
+        var item = new OrderEvent(
+            Guid.CreateVersion7().ToString(),
+            command.TenantId,
+            command.Type,
+            clock.GetUtcNow());
+
+        using var payload = new MemoryStream(JsonSerializer.SerializeToUtf8Bytes(item, JsonSerializerOptions.Web));
+        using var response = await container.CreateItemStreamAsync(
+            payload, new PartitionKey(item.TenantId), cancellationToken: ct);
+
+        return response.StatusCode switch
         {
-            return null;
-        }
+            HttpStatusCode.Created => item,
+            HttpStatusCode.Conflict => OrderEventErrors.Duplicate(item.Id),
+            _ => OrderEventErrors.StoreFailure(response.StatusCode)
+        };
     }
+}
 
-    public async Task<IReadOnlyList<T>> QueryAsync(string sql, Dictionary<string, object>? parameters = null)
+public sealed class GetOrderEventHandler([FromKeyedServices("order-events")] Container container)
+{
+    public async Task<Result<OrderEvent>> HandleAsync(string tenantId, string id, CancellationToken ct)
     {
-        var query = new QueryDefinition(sql);
-        if (parameters != null)
-            foreach (var (k, v) in parameters) query = query.WithParameter(k, v);
+        using var response = await container.ReadItemStreamAsync(
+            id, new PartitionKey(tenantId), cancellationToken: ct);
 
-        var results = new List<T>();
-        using var feed = _container.GetItemQueryIterator<T>(query);
-        while (feed.HasMoreResults)
-        {
-            var page = await feed.ReadNextAsync();
-            results.AddRange(page);
-        }
-        return results;
-    }
+        if (response.StatusCode == HttpStatusCode.NotFound)
+            return OrderEventErrors.NotFound(id);
+        if (!response.IsSuccessStatusCode)
+            return OrderEventErrors.StoreFailure(response.StatusCode);
 
-    public async Task UpsertAsync(T document)
-        => await _container.UpsertItemAsync(document, new PartitionKey(document.PartitionKey));
+        var item = await JsonSerializer.DeserializeAsync<OrderEvent>(
+            response.Content, JsonSerializerOptions.Web, ct);
+        return item is null ? OrderEventErrors.NotFound(id) : item;
+    }
 }
 ```
 
-## Document Base Class
-```csharp
-public abstract class CosmosDocument
-{
-    [JsonPropertyName("id")]
-    public string Id { get; set; } = Guid.NewGuid().ToString();
+The endpoint maps the `Result` exactly as any other slice does (`result.Match(...)` with the `ErrorType` → HTTP mapping of `backend-dotnet-result-pattern`).
 
-    [JsonPropertyName("_partitionKey")]
-    public abstract string PartitionKey { get; }
+Queries take parameters, never string concatenation, and pin the partition key in `QueryRequestOptions` so the query does not fan out:
 
-    [JsonPropertyName("type")]
-    public string Type => GetType().Name;
+```csharp
+var query = new QueryDefinition("SELECT * FROM c WHERE c.tenantId = @tenantId AND c.type = @type")
+    .WithParameter("@tenantId", tenantId)
+    .WithParameter("@type", type);
 
-    [JsonPropertyName("createdAt")]
-    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
-}
+using var feed = container.GetItemQueryIterator<OrderEvent>(
+    query, requestOptions: new QueryRequestOptions { PartitionKey = new PartitionKey(tenantId) });
 ```
 
+## Anti-Patterns
+
+| Do NOT | Do Instead |
+|--------|------------|
+| Pick Cosmos without a `decisions.md` entry | Neon (Postgres) via EF Core is the default store |
+| Wrap `Container` in a generic `CosmosRepository<T>` | Inject the keyed `Container` into the slice handler |
+| `try/catch (CosmosException)` for 404/409 | Stream APIs + `StatusCode` → `Result` |
+| `Guid.NewGuid()` for document ids | `Guid.CreateVersion7()` |
+| `DateTime.UtcNow` in the handler | `TimeProvider` (testable with `FakeTimeProvider`) |
+| A `CosmosClient` per request | One singleton client per process |
+
 ## Cost Optimization
 - Enable TTL on transient data (session, temp tokens)
 - Use serverless mode for dev/test environments

package/framework/standards/frontend/design-system/animations.md

@@ -1,7 +1,7 @@
 # CSS Animation Patterns
 
 > **Scope:** universal
-> **Layer:** 0 (always load)
+> **Layer:** 0 (resumo injetado pela rule `frontend-standards` ao editar `**/*.tsx`/`**/*.css`/`**/*.scss`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** css, animation, keyframe, transition, stagger, shimmer
 > **Load When:** always
 

package/framework/standards/frontend/design-system/naming.md

@@ -1,7 +1,7 @@
 # CSS Naming Convention
 
 > **Scope:** universal
-> **Layer:** 0 (always load)
+> **Layer:** 0 (resumo injetado pela rule `frontend-standards` ao editar `**/*.tsx`/`**/*.css`/`**/*.scss`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** css, bem, naming, class names, conventions
 > **Load When:** always
 

package/framework/standards/frontend/nextjs/motion-patterns.md

@@ -1,15 +1,15 @@
-# Motion Patterns — Motion for React
+# Motion Patterns — Motion for React (formerly Framer Motion)
 
 > **Scope:** frontend-nextjs-ui
 > **Layer:** 3
 > **Keywords:** motion, framer-motion, animation, transition, variants, gesture, scroll
 > **Load When:** nextjs-expert active
 
-**Verified against:** Motion for React 12 (`motion`, imports from `motion/react`). Last-verified: 2026-05-20.
+**Verified against:** Motion for React 12+ (`motion`, imports from `motion/react`); the npm registry and the `motion`/`framer-motion`/`motion-dom` 14.0.0 typings were read on 2026-10-03 (`motion/react` re-exports `framer-motion`, which re-exports `motion-dom`: `Variants`, `useInView`, `AnimatePresence`, `useReducedMotion`, `staggerChildren`/`delayChildren` all present). The TSX snippets are documentary. Last-verified: 2026-10-03.
 
 ---
 
-Reference guide for implementing animations and transitions in Next.js projects using **Motion for React**, the library formerly published as `framer-motion`. The package is now `motion` and components import from `motion/react`; the `framer-motion` name only survives inside the Framer design tool. Covers the canonical variants library, design token bridge, scroll and gesture patterns, loading states, and mandatory WCAG accessibility compliance.
+Reference guide for implementing animations and transitions in Next.js projects using **Motion for React** -- the library the stack table calls "Framer Motion" (its former name). Install the `motion` package and import from `motion/react`. `framer-motion` is still published in lockstep (`motion@14` depends on `framer-motion@14` and re-exports it), so both import paths reach the same code; the rule is one path per codebase, and it is `motion/react`. Covers the canonical variants library, design token bridge, scroll and gesture patterns, loading states, and mandatory WCAG accessibility compliance.
 
 **Scope, and where the other motion stack starts.** This standard governs component-level motion: enter and exit, gestures, mount and unmount transitions, short scroll reveals in an app or product UI. When the scroll position itself drives the scene (frame scrubs, pinned sequences, parallax, a cinematic landing page), that is GSAP plus ScrollTrigger plus Lenis: see `frontend/scroll-driven/smooth-scroll.md` and `frontend/gsap/gsap-core.md`. The two stacks may share a page but never the same element, because both write inline styles and will fight for control. On a page that runs Lenis, use the `useReveal` recipe in `frontend/scroll-driven/scroll-components.md` rather than `whileInView`, so a single library owns the answer to when an element is visible.
 
@@ -80,11 +80,11 @@ export const pageTransition: Variants = {
 
 ## Section 2: Design Token Bridge
 
-This file bridges the CSS variables defined in `.morph/context/design-system.md` to JavaScript values consumed by Framer Motion. Place at `lib/design-tokens.ts`.
+This file bridges the CSS variables defined in `.morph/context/design-system.md` to JavaScript values consumed by Motion. Place at `lib/design-tokens.ts`.
 
 ```typescript
 // lib/design-tokens.ts
-// Maps CSS variables from .morph/context/design-system.md to JS values for Framer Motion
+// Maps CSS variables from .morph/context/design-system.md to JS values for Motion
 export const durations = {
   instant: 0.05,
   fast: 0.15,
@@ -171,38 +171,54 @@ import { durations, easings } from '@/lib/design-tokens';
 
 ## Section 5: AnimatePresence (Page Transitions)
 
-Integrate `AnimatePresence` at the layout level to animate between routes:
+The root `app/layout.tsx` stays a **Server Component** -- marking it `'use client'` turns the whole tree into client code and forbids `metadata` exports there. The client-only part (`AnimatePresence`, `usePathname`) lives in a small provider that the layout renders:
 
 ```tsx
-// app/layout.tsx
+// components/page-transition.tsx
 'use client';
 import { AnimatePresence, motion } from 'motion/react';
 import { usePathname } from 'next/navigation';
 import { pageTransition } from '@/motion/variants';
 
-export default function Layout({ children }: { children: React.ReactNode }) {
+export function PageTransition({ children }: { children: React.ReactNode }) {
   const pathname = usePathname();
 
   return (
-    <html>
+    <AnimatePresence mode="wait">
+      <motion.main
+        key={pathname}
+        variants={pageTransition}
+        initial="hidden"
+        animate="visible"
+        exit="exit"
+      >
+        {children}
+      </motion.main>
+    </AnimatePresence>
+  );
+}
+```
+
+```tsx
+// app/layout.tsx — Server Component (no 'use client')
+import type { Metadata } from 'next';
+import { PageTransition } from '@/components/page-transition';
+
+export const metadata: Metadata = { title: 'App' };
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="pt-BR">
       <body>
-        <AnimatePresence mode="wait">
-          <motion.main
-            key={pathname}
-            variants={pageTransition}
-            initial="hidden"
-            animate="visible"
-            exit="exit"
-          >
-            {children}
-          </motion.main>
-        </AnimatePresence>
+        <PageTransition>{children}</PageTransition>
       </body>
     </html>
   );
 }
 ```
 
+`children` passed from the server layout into the client provider stay Server Components; only `PageTransition` ships to the browser.
+
 - `mode="wait"` ensures the exit animation completes before the entering page renders.
 - The `key` prop must change on navigation — use `usePathname()` from `next/navigation`.
 - Keep page transitions subtle (`y: 8`, fast duration) — aggressive transitions hurt perceived performance.
@@ -211,7 +227,7 @@ export default function Layout({ children }: { children: React.ReactNode }) {
 
 ## Section 6: Loading Patterns
 
-Prefer CSS `animate-pulse` for skeleton loaders over Framer Motion — CSS animations run off the main thread and have lower performance overhead.
+Prefer CSS `animate-pulse` for skeleton loaders over Motion — CSS animations run off the main thread and have lower performance overhead.
 
 ```tsx
 // components/skeleton.tsx
@@ -242,7 +258,7 @@ function SkeletonCard() {
 
 - Use design token CSS variables (`--radius-md`, `--color-neutral-200`, `--space-*`) — never hardcode dimensions or colors.
 - Skeleton shapes should mirror the actual content layout to minimize layout shift on load.
-- For spinner/progress indicators that need JS control, use a simple Framer Motion `animate={{ rotate: 360 }}` with `repeat: Infinity`.
+- For spinner/progress indicators that need JS control, use a simple Motion `animate={{ rotate: 360 }}` with `repeat: Infinity`.
 
 ---
 
@@ -288,7 +304,7 @@ When `shouldReduceMotion` is `true`:
 }
 ```
 
-This CSS fallback catches animations outside Framer Motion (Tailwind `animate-*`, third-party components, CSS keyframes).
+This CSS fallback catches animations outside Motion (Tailwind `animate-*`, third-party components, CSS keyframes).
 
 ---
 
@@ -303,7 +319,7 @@ This CSS fallback catches animations outside Framer Motion (Tailwind `animate-*`
 | Forgetting `animation-fill-mode: backwards` in stagger | Will cause a flash before the animation starts |
 | `AnimatePresence` without `key` changes | Exit animations will never fire |
 | Using `motion` for skeleton loaders | Use CSS `animate-pulse` — lower performance cost |
-| `npm install framer-motion` / `import ... from 'framer-motion'` | `npm install motion` / `import ... from 'motion/react'` — `framer-motion` is the legacy name |
+| `npm install framer-motion` / `import ... from 'framer-motion'` | `npm install motion` / `import ... from 'motion/react'` — same code underneath, but one import path per codebase |
 | Need ScrollTrigger, SVG morph, or complex timelines | Use GSAP — see `frontend/gsap/gsap-core.md` |
 
 ---
@@ -314,12 +330,12 @@ This CSS fallback catches animations outside Framer Motion (Tailwind `animate-*`
 npm install motion
 ```
 
-> The package is `motion` and components import from `motion/react`. The old
-> `framer-motion` package still resolves as a deprecated alias, but new code
-> should depend on `motion` directly. The `framer-motion` import name is only
-> kept for projects running inside the Framer design tool.
+> The package is `motion` and components import from `motion/react`. `framer-motion`
+> is not deprecated: it is published with the same version and `motion` depends on
+> it. New code still depends on `motion` and imports from `motion/react`, so the
+> codebase has a single import path; do not add `framer-motion` alongside it.
 
-Verify the installed version supports the features used here (requires motion >= 11):
+Verify the installed version supports the features used here (requires motion >= 11; current major on npm is 14):
 
 ```bash
 npm list motion

package/framework/standards/frontend/nextjs/naming-conventions.md

@@ -1,7 +1,7 @@
 # Next.js Naming Conventions Standard
 
 > **Scope:** frontend/nextjs/naming-conventions
-> **Layer:** 1 (always)
+> **Layer:** 1 (resumo injetado pela rule `nextjs-standards` ao editar `**/*.ts`/`**/*.tsx`; texto completo sob demanda via `morph-spec standards --find`)
 > **Keywords:** naming, conventions, file names, component names, hooks, typescript
 > **Load When:** creating any new file in a Next.js project