@polymorphism-tech/morph-spec 7.0.0 → 7.1.1

package/framework/standards/data/vector-search/rag-chunking.md

@@ -1,104 +1,113 @@
-# Data Standard: RAG Chunking Strategies
-
-## Overview
-Chunking splits documents into segments for embedding. Chunk quality directly impacts RAG answer quality.
-
-## Chunking Strategies
-
-### 1. Fixed-Size (Baseline)
-```csharp
-public IEnumerable<Chunk> FixedSizeChunk(string text, int size = 512, int overlap = 50)
-{
-    for (int i = 0; i < text.Length; i += size - overlap)
-    {
-        yield return new Chunk
-        {
-            Content = text[i..Math.Min(i + size, text.Length)],
-            StartIndex = i,
-            EndIndex = Math.Min(i + size, text.Length)
-        };
-    }
-}
-```
-
-### 2. Sentence-Aware (Recommended for prose)
-```csharp
-public IEnumerable<Chunk> SentenceChunk(string text, int maxTokens = 256)
-{
-    var sentences = SplitSentences(text);
-    var current = new StringBuilder();
-    var tokenCount = 0;
-
-    foreach (var sentence in sentences)
-    {
-        var sentenceTokens = EstimateTokens(sentence);
-        if (tokenCount + sentenceTokens > maxTokens && current.Length > 0)
-        {
-            yield return new Chunk { Content = current.ToString().Trim() };
-            current.Clear();
-            tokenCount = 0;
-        }
-        current.Append(sentence).Append(' ');
-        tokenCount += sentenceTokens;
-    }
-
-    if (current.Length > 0)
-        yield return new Chunk { Content = current.ToString().Trim() };
-}
-```
-
-### 3. Semantic (Best quality, higher cost)
-Split at semantic boundaries (paragraphs, headers, sections) rather than character count.
-
-```csharp
-public IEnumerable<Chunk> SemanticChunk(string markdown)
-{
-    // Split at markdown headers
-    var sections = Regex.Split(markdown, @"(?=^#{1,3} )", RegexOptions.Multiline);
-    foreach (var section in sections.Where(s => s.Trim().Length > 0))
-        yield return new Chunk { Content = section.Trim() };
-}
-```
-
-## Token Estimation
-```csharp
-// Rough estimate: 1 token ≈ 4 characters (English), ≈ 3 characters (Portuguese)
-private static int EstimateTokens(string text) => text.Length / 4;
-
-// More accurate: use tiktoken (if available)
-// var encoder = TiktokenSharp.TikToken.EncodingForModel("gpt-4");
-// return encoder.Encode(text).Count;
-```
-
-## Chunk Metadata
-Always store metadata with chunks for filtering and citation:
-```csharp
-public record Chunk
-{
-    public string Content { get; init; } = "";
-    public string DocumentId { get; init; } = "";
-    public string DocumentTitle { get; init; } = "";
-    public string SourceUrl { get; init; } = "";
-    public int ChunkIndex { get; init; }
-    public int StartCharIndex { get; init; }
-    public string Section { get; init; } = ""; // H1/H2 header this belongs to
-    public DateTime IndexedAt { get; init; } = DateTime.UtcNow;
-}
-```
-
-## Strategy Selection Guide
-| Document Type | Strategy | Chunk Size |
-|---------------|----------|------------|
-| Legal documents | Sentence-aware | 256 tokens |
-| Technical docs | Semantic (headers) | Variable |
-| Q&A pairs | Keep as-is | Whole Q+A |
-| Code files | Function-boundary | Whole function |
-| News articles | Paragraph | 512 tokens |
-
-## Quality Checklist
-- [ ] Chunks overlap by 10-20% to avoid cutting context at boundaries
-- [ ] Minimum chunk size: 50 tokens (avoid noisy small chunks)
-- [ ] Maximum chunk size: 512 tokens for ada-002 (8192 token model limit)
-- [ ] Metadata preserved and searchable
-- [ ] Source URL included for citation
-- [ ] Re-index when document changes (detect via content hash)
+# Data Standard: RAG Chunking Strategies
+
+> **Scope:** data-vector-search
+> **Layer:** 2
+> **Keywords:** chunking, rag, embeddings, vector-search, document-segmentation, overlap, retrieval
+> **Load When:** building a RAG pipeline or embedding documents for vector search
+
+**Verified against:** .NET 10 (chunking algorithms — language-level, no external package). Last-verified: 2026-05-20.
+
+---
+
+## Overview
+Chunking splits documents into segments for embedding. Chunk quality directly impacts RAG answer quality.
+
+## Chunking Strategies
+
+### 1. Fixed-Size (Baseline)
+```csharp
+public IEnumerable<Chunk> FixedSizeChunk(string text, int size = 512, int overlap = 50)
+{
+    for (int i = 0; i < text.Length; i += size - overlap)
+    {
+        yield return new Chunk
+        {
+            Content = text[i..Math.Min(i + size, text.Length)],
+            StartIndex = i,
+            EndIndex = Math.Min(i + size, text.Length)
+        };
+    }
+}
+```
+
+### 2. Sentence-Aware (Recommended for prose)
+```csharp
+public IEnumerable<Chunk> SentenceChunk(string text, int maxTokens = 256)
+{
+    var sentences = SplitSentences(text);
+    var current = new StringBuilder();
+    var tokenCount = 0;
+
+    foreach (var sentence in sentences)
+    {
+        var sentenceTokens = EstimateTokens(sentence);
+        if (tokenCount + sentenceTokens > maxTokens && current.Length > 0)
+        {
+            yield return new Chunk { Content = current.ToString().Trim() };
+            current.Clear();
+            tokenCount = 0;
+        }
+        current.Append(sentence).Append(' ');
+        tokenCount += sentenceTokens;
+    }
+
+    if (current.Length > 0)
+        yield return new Chunk { Content = current.ToString().Trim() };
+}
+```
+
+### 3. Semantic (Best quality, higher cost)
+Split at semantic boundaries (paragraphs, headers, sections) rather than character count.
+
+```csharp
+public IEnumerable<Chunk> SemanticChunk(string markdown)
+{
+    // Split at markdown headers
+    var sections = Regex.Split(markdown, @"(?=^#{1,3} )", RegexOptions.Multiline);
+    foreach (var section in sections.Where(s => s.Trim().Length > 0))
+        yield return new Chunk { Content = section.Trim() };
+}
+```
+
+## Token Estimation
+```csharp
+// Rough estimate: 1 token ≈ 4 characters (English), ≈ 3 characters (Portuguese)
+private static int EstimateTokens(string text) => text.Length / 4;
+
+// More accurate: use tiktoken (if available)
+// var encoder = TiktokenSharp.TikToken.EncodingForModel("gpt-4");
+// return encoder.Encode(text).Count;
+```
+
+## Chunk Metadata
+Always store metadata with chunks for filtering and citation:
+```csharp
+public record Chunk
+{
+    public string Content { get; init; } = "";
+    public string DocumentId { get; init; } = "";
+    public string DocumentTitle { get; init; } = "";
+    public string SourceUrl { get; init; } = "";
+    public int ChunkIndex { get; init; }
+    public int StartCharIndex { get; init; }
+    public string Section { get; init; } = ""; // H1/H2 header this belongs to
+    public DateTime IndexedAt { get; init; } = DateTime.UtcNow;
+}
+```
+
+## Strategy Selection Guide
+| Document Type | Strategy | Chunk Size |
+|---------------|----------|------------|
+| Legal documents | Sentence-aware | 256 tokens |
+| Technical docs | Semantic (headers) | Variable |
+| Q&A pairs | Keep as-is | Whole Q+A |
+| Code files | Function-boundary | Whole function |
+| News articles | Paragraph | 512 tokens |
+
+## Quality Checklist
+- [ ] Chunks overlap by 10-20% to avoid cutting context at boundaries
+- [ ] Minimum chunk size: 50 tokens (avoid noisy small chunks)
+- [ ] Maximum chunk size: ~512 tokens (well under the 8192-token input limit of `text-embedding-3-small`/`-large`)
+- [ ] Metadata preserved and searchable
+- [ ] Source URL included for citation
+- [ ] Re-index when document changes (detect via content hash)

package/framework/standards/frontend/design-system/ai-image-generation.md

@@ -5,6 +5,10 @@
 > **Keywords:** image, gemini, asset, ai-generation, placeholder, mcp, next/image
 > **Load When:** feature has UI components requiring image assets
 
+**Verified against:** Gemini Image MCP + Next.js 15 `next/image`. Last-verified: 2026-05-20.
+
+---
+
 ## When to Use AI-Generated Images
 
 | Use Case | Approach | Examples |

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

@@ -1,160 +1,164 @@
-# CSS Animation Patterns
-
-> **Scope:** universal
-> **Layer:** 0 (always load)
-> **Keywords:** css, animation, keyframe, transition, stagger, shimmer
-> **Load When:** always
-
-## Keyframes Library
-
-```css
-@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
-@keyframes fadeOut { from { opacity: 1; } to { opacity: 0; } }
-@keyframes slideInUp { from { opacity: 0; transform: translateY(20px); } to { opacity: 1; transform: translateY(0); } }
-@keyframes slideInDown { from { opacity: 0; transform: translateY(-20px); } to { opacity: 1; transform: translateY(0); } }
-@keyframes slideInLeft { from { opacity: 0; transform: translateX(-20px); } to { opacity: 1; transform: translateX(0); } }
-@keyframes slideInRight { from { opacity: 0; transform: translateX(20px); } to { opacity: 1; transform: translateX(0); } }
-@keyframes scaleIn { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } }
-@keyframes bounce { 0%, 100% { transform: translateY(0); } 50% { transform: translateY(-10px); } }
-@keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
-@keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
-@keyframes shimmer { 0% { background-position: -200% 0; } 100% { background-position: 200% 0; } }
-```
-
-## Animation Classes
-
-| Class | Animation | Duration | Iteration |
-|-------|-----------|----------|-----------|
-| `.animate-fadeIn` | fadeIn | 0.3s | once |
-| `.animate-fadeOut` | fadeOut | 0.3s | once |
-| `.animate-slideInUp` | slideInUp | 0.5s | once |
-| `.animate-slideInDown` | slideInDown | 0.5s | once |
-| `.animate-slideInLeft` | slideInLeft | 0.5s | once |
-| `.animate-slideInRight` | slideInRight | 0.5s | once |
-| `.animate-scaleIn` | scaleIn | 0.3s | once |
-| `.animate-bounce` | bounce | 1s | infinite |
-| `.animate-pulse` | pulse | 2s | infinite |
-| `.animate-spin` | spin | 1s | infinite |
-
-```css
-.animate-fadeIn { animation: fadeIn 0.3s ease forwards; }
-.animate-slideInUp { animation: slideInUp 0.5s ease forwards; }
-.animate-bounce { animation: bounce 1s ease infinite; }
-```
-
-## Stagger & Timing
-
-```css
-/* Stagger delays (0.1s - 1.0s) */
-.stagger-1 { animation-delay: 0.1s; } .stagger-2 { animation-delay: 0.2s; }
-.stagger-3 { animation-delay: 0.3s; } /* ... up to .stagger-10 */
-
-/* Durations */
-.duration-fast { animation-duration: 150ms; }
-.duration-normal { animation-duration: 300ms; }
-.duration-slow { animation-duration: 500ms; }
-
-/* Easing */
-.ease-bounce { animation-timing-function: cubic-bezier(0.68, -0.55, 0.265, 1.55); }
-```
-
-## Shimmer (Skeleton Loading)
-
-```css
-.shimmer {
-  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
-  background-size: 200% 100%;
-  animation: shimmer 1.5s infinite;
-}
-```
-
----
-
-## Blazor Usage
-
-### Stagger Pattern
-
-```razor
-@for (int i = 0; i < _items.Count; i++)
-{
-    var index = i;
-    <div class="card animate-slideInUp"
-         style="@($"animation-delay: {0.05 * index}s; animation-fill-mode: backwards;")">
-        @_items[index].Name
-    </div>
-}
-```
-
-**CRITICAL:** Use `animation-fill-mode: backwards` to avoid flash before delay.
-
-### Conditional Enter/Exit
-
-```razor
-@if (_showMessage)
-{
-    <div class="@(_isEntering ? "animate-slideInUp" : "animate-fadeOut")">Msg</div>
-}
-@code {
-    private async Task HideMessage() {
-        _isEntering = false;
-        await Task.Delay(300); // wait for exit animation
-        _showMessage = false;
-    }
-}
-```
-
-### Skeleton Loading
-
-```razor
-@if (_isLoading)
-{
-    <div class="shimmer" style="width: 200px; height: 24px; border-radius: 4px;"></div>
-}
-else { <h2>@_title</h2> }
-```
-
-## Transitions (Hover/Focus)
-
-```css
-.card { transition: transform 0.2s ease, box-shadow 0.2s ease; }
-.card:hover { transform: translateY(-4px); box-shadow: var(--shadow-lg); }
-
-.button { transition: background-color 0.15s ease, transform 0.15s ease; }
-.button:active { transform: scale(0.98); }
-
-.link::after { content: ''; position: absolute; width: 0; height: 2px; background: var(--primary); transition: width 0.3s ease; }
-.link:hover::after { width: 100%; }
-```
-
-## Accessibility
-
-```css
-@media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-  }
-}
-```
-
-## Checklist
-
-- [ ] Keyframes in design-system.css
-- [ ] `.animate-*` classes created
-- [ ] `animation-fill-mode: backwards` for stagger
-- [ ] `@media (prefers-reduced-motion)` implemented
-- [ ] Shimmer for loading states
-
-## JavaScript Animation Libraries
-
-For animations beyond CSS capabilities:
-
-| Need | Library | Standard |
-|------|---------|----------|
-| Simple UI transitions (enter/exit, layout, gestures) | Framer Motion | `frontend/nextjs/motion-patterns.md` |
-| Complex animations (ScrollTrigger, SVG morph, timelines) | GSAP | `frontend/gsap/gsap-core.md` |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# CSS Animation Patterns
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** css, animation, keyframe, transition, stagger, shimmer
+> **Load When:** always
+
+**Verified against:** CSS animations/transitions (language-level, no framework). Last-verified: 2026-05-20.
+
+---
+
+## Keyframes Library
+
+```css
+@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
+@keyframes fadeOut { from { opacity: 1; } to { opacity: 0; } }
+@keyframes slideInUp { from { opacity: 0; transform: translateY(20px); } to { opacity: 1; transform: translateY(0); } }
+@keyframes slideInDown { from { opacity: 0; transform: translateY(-20px); } to { opacity: 1; transform: translateY(0); } }
+@keyframes slideInLeft { from { opacity: 0; transform: translateX(-20px); } to { opacity: 1; transform: translateX(0); } }
+@keyframes slideInRight { from { opacity: 0; transform: translateX(20px); } to { opacity: 1; transform: translateX(0); } }
+@keyframes scaleIn { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } }
+@keyframes bounce { 0%, 100% { transform: translateY(0); } 50% { transform: translateY(-10px); } }
+@keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
+@keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
+@keyframes shimmer { 0% { background-position: -200% 0; } 100% { background-position: 200% 0; } }
+```
+
+## Animation Classes
+
+| Class | Animation | Duration | Iteration |
+|-------|-----------|----------|-----------|
+| `.animate-fadeIn` | fadeIn | 0.3s | once |
+| `.animate-fadeOut` | fadeOut | 0.3s | once |
+| `.animate-slideInUp` | slideInUp | 0.5s | once |
+| `.animate-slideInDown` | slideInDown | 0.5s | once |
+| `.animate-slideInLeft` | slideInLeft | 0.5s | once |
+| `.animate-slideInRight` | slideInRight | 0.5s | once |
+| `.animate-scaleIn` | scaleIn | 0.3s | once |
+| `.animate-bounce` | bounce | 1s | infinite |
+| `.animate-pulse` | pulse | 2s | infinite |
+| `.animate-spin` | spin | 1s | infinite |
+
+```css
+.animate-fadeIn { animation: fadeIn 0.3s ease forwards; }
+.animate-slideInUp { animation: slideInUp 0.5s ease forwards; }
+.animate-bounce { animation: bounce 1s ease infinite; }
+```
+
+## Stagger & Timing
+
+```css
+/* Stagger delays (0.1s - 1.0s) */
+.stagger-1 { animation-delay: 0.1s; } .stagger-2 { animation-delay: 0.2s; }
+.stagger-3 { animation-delay: 0.3s; } /* ... up to .stagger-10 */
+
+/* Durations */
+.duration-fast { animation-duration: 150ms; }
+.duration-normal { animation-duration: 300ms; }
+.duration-slow { animation-duration: 500ms; }
+
+/* Easing */
+.ease-bounce { animation-timing-function: cubic-bezier(0.68, -0.55, 0.265, 1.55); }
+```
+
+## Shimmer (Skeleton Loading)
+
+```css
+.shimmer {
+  background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+```
+
+---
+
+## Blazor Usage
+
+### Stagger Pattern
+
+```razor
+@for (int i = 0; i < _items.Count; i++)
+{
+    var index = i;
+    <div class="card animate-slideInUp"
+         style="@($"animation-delay: {0.05 * index}s; animation-fill-mode: backwards;")">
+        @_items[index].Name
+    </div>
+}
+```
+
+**CRITICAL:** Use `animation-fill-mode: backwards` to avoid flash before delay.
+
+### Conditional Enter/Exit
+
+```razor
+@if (_showMessage)
+{
+    <div class="@(_isEntering ? "animate-slideInUp" : "animate-fadeOut")">Msg</div>
+}
+@code {
+    private async Task HideMessage() {
+        _isEntering = false;
+        await Task.Delay(300); // wait for exit animation
+        _showMessage = false;
+    }
+}
+```
+
+### Skeleton Loading
+
+```razor
+@if (_isLoading)
+{
+    <div class="shimmer" style="width: 200px; height: 24px; border-radius: 4px;"></div>
+}
+else { <h2>@_title</h2> }
+```
+
+## Transitions (Hover/Focus)
+
+```css
+.card { transition: transform 0.2s ease, box-shadow 0.2s ease; }
+.card:hover { transform: translateY(-4px); box-shadow: var(--shadow-lg); }
+
+.button { transition: background-color 0.15s ease, transform 0.15s ease; }
+.button:active { transform: scale(0.98); }
+
+.link::after { content: ''; position: absolute; width: 0; height: 2px; background: var(--primary); transition: width 0.3s ease; }
+.link:hover::after { width: 100%; }
+```
+
+## Accessibility
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## Checklist
+
+- [ ] Keyframes in design-system.css
+- [ ] `.animate-*` classes created
+- [ ] `animation-fill-mode: backwards` for stagger
+- [ ] `@media (prefers-reduced-motion)` implemented
+- [ ] Shimmer for loading states
+
+## JavaScript Animation Libraries
+
+For animations beyond CSS capabilities:
+
+| Need | Library | Standard |
+|------|---------|----------|
+| Simple UI transitions (enter/exit, layout, gestures) | Motion (formerly Framer Motion) | `frontend/nextjs/motion-patterns.md` |
+| Complex animations (ScrollTrigger, SVG morph, timelines) | GSAP | `frontend/gsap/gsap-core.md` |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*