@polymorphism-tech/morph-spec 7.0.0 → 7.1.0

package/framework/standards/STANDARDS.json

@@ -1,1133 +1,1729 @@
-{
-  "version": "1.0.0",
-  "standards": [
-    {
-      "id": "ai-agents-production",
-      "name": "production",
-      "path": "ai-agents/production.md",
-      "category": "ai-agents",
-      "subcategory": null,
-      "tags": [
-        "ai-agents"
-      ],
-      "aliases": [
-        "AI production",
-        "agent reliability",
-        "production AI",
-        "agent safety",
-        "autonomous systems"
-      ],
-      "anchors": {
-        "reliability": "#reliability-patterns",
-        "safety": "#safety-guardrails",
-        "monitoring": "#monitoring-and-logging"
-      },
-      "digest": "Add rate limiting and retry with exponential backoff. Log all agent decisions and tool calls. Implement circuit breakers for external calls. Validate agent output before acting. Never give agents unaudited write access to production systems.",
-      "stacks": [
-        "*"
-      ]
-    },
-    {
-      "id": "ai-agents-setup",
-      "name": "setup",
-      "path": "ai-agents/setup.md",
-      "category": "ai-agents",
-      "subcategory": null,
-      "tags": [
-        "ai-agents"
-      ],
-      "aliases": [
-        "AI agent setup",
-        "MCP configuration",
-        "tool configuration",
-        "Claude setup",
-        "agent initialization"
-      ],
-      "anchors": {
-        "mcp": "#mcp-configuration",
-        "tools": "#tool-definitions",
-        "spawn": "#spawn-configuration"
-      },
-      "digest": "Initialize agents with explicit tool lists — never allow unlimited tool access. Configure MCP servers before spawning subagents. Define system prompts with role + constraints + output format. Validate tool availability before dispatch.",
-      "stacks": [
-        "*"
-      ]
-    },
-    {
-      "id": "ai-agents-workflows",
-      "name": "workflows",
-      "path": "ai-agents/workflows.md",
-      "category": "ai-agents",
-      "subcategory": null,
-      "tags": [
-        "ai-agents"
-      ],
-      "aliases": [
-        "agent workflow",
-        "multi-agent",
-        "orchestration pattern",
-        "agent chain",
-        "parallel agents"
-      ],
-      "anchors": {
-        "orchestration": "#orchestration-patterns",
-        "parallel": "#parallel-execution",
-        "handoff": "#agent-handoff"
-      },
-      "digest": "Use orchestrator→specialist pattern for complex tasks. Parallelize independent subtasks. Pass structured context between agents, not raw conversation. Define explicit success criteria before spawning. Implement timeout and fallback strategies.",
-      "stacks": [
-        "*"
-      ]
-    },
-    {
-      "id": "architecture-vertical-slice-vertical-slice",
-      "name": "vertical slice",
-      "path": "architecture/vertical-slice/vertical-slice.md",
-      "category": "architecture",
-      "subcategory": "vertical-slice",
-      "tags": [
-        "architecture",
-        "vertical-slice"
-      ],
-      "aliases": [
-        "vertical slice",
-        "VSA",
-        "slice architecture",
-        "feature slice",
-        "CQRS slice"
-      ],
-      "anchors": {
-        "structure": "#slice-structure",
-        "rules": "#slice-rules",
-        "cqrs": "#cqrs-in-slices"
-      },
-      "digest": "Organize by feature, not layer. Each slice contains Command/Query, Handler, Validator, Response. No cross-slice dependencies — shared code goes to a dedicated Shared project. Use MediatR for in-process CQRS dispatch.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "backend-api-validation",
-      "name": "validation",
-      "path": "backend/api/validation.md",
-      "category": "backend",
-      "subcategory": "api",
-      "tags": [
-        "backend",
-        "api"
-      ],
-      "aliases": [
-        "FluentValidation",
-        "input validation",
-        "request validation",
-        "API validation",
-        "model validation"
-      ],
-      "anchors": {
-        "fluent": "#fluentvalidation-setup",
-        "rules": "#validation-rules"
-      },
-      "digest": "Use FluentValidation for all request validation. Register validators as scoped services. Return 422 UnprocessableEntity with field-level error messages. Validate at API boundary — not inside domain logic. Never trust client-side validation alone.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "backend-database-postgresql-database",
-      "name": "database",
-      "path": "backend/database/postgresql/database.md",
-      "category": "backend",
-      "subcategory": "database",
-      "tags": [
-        "backend",
-        "database",
-        "postgresql"
-      ],
-      "aliases": [
-        "PostgreSQL",
-        "postgres",
-        "pg",
-        "database design",
-        "SQL schema"
-      ],
-      "anchors": {
-        "schema": "#schema-design",
-        "indexes": "#index-strategy"
-      },
-      "digest": "Use timestamptz for all timestamps (not timestamp). UUID primary keys for public-facing IDs. Add indexes on FK columns and frequently filtered columns. Use GIN indexes for JSON/array columns. JSONB over JSON. Row-level security for multi-tenant. Never store binary in columns — use storage URLs.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "backend-database-vector-search-rag",
-      "name": "vector search rag",
-      "path": "backend/database/vector-search-rag.md",
-      "category": "backend",
-      "subcategory": "database",
-      "tags": [
-        "backend",
-        "database"
-      ],
-      "aliases": [
-        "vector search",
-        "RAG",
-        "embeddings",
-        "pgvector",
-        "semantic search"
-      ],
-      "anchors": {
-        "chunking": "#chunking-strategy",
-        "retrieval": "#retrieval-patterns"
-      },
-      "digest": "Chunk documents with 512 token size and 50 token overlap for RAG. Embed with text-embedding-3-small. Store embedding + metadata (source, chunk index). Retrieve top-k=5 by cosine similarity. Re-rank before injecting into LLM context. Use pgvector HNSW index for performance at scale.",
-      "stacks": [
-        "dotnet",
-        "nextjs",
-        "neon"
-      ]
-    },
-    {
-      "id": "backend-dotnet-result-pattern",
-      "name": "result pattern",
-      "path": "backend/dotnet/result-pattern.md",
-      "category": "backend",
-      "subcategory": "dotnet",
-      "tags": [
-        "backend",
-        "dotnet",
-        "vsa"
-      ],
-      "aliases": [
-        "Result<T>",
-        "railway oriented",
-        "error handling",
-        "Match pattern",
-        "Result monad"
-      ],
-      "anchors": {
-        "anatomy": "#result-anatomy",
-        "errors": "#error-types-7--custom",
-        "match": "#match-pattern"
-      },
-      "digest": "Use Result<T> for all handler returns — never throw for expected failures. 7 error types (Failure, Unexpected, Validation, Conflict, NotFound, Unauthorized, Forbidden) map to HTTP status codes. Use Match() in endpoints to convert Result to IResult. Implicit conversions allow returning values or errors directly from handlers.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "backend-dotnet-scrutor",
-      "name": "scrutor",
-      "path": "backend/dotnet/scrutor.md",
-      "category": "backend",
-      "subcategory": "dotnet",
-      "tags": [
-        "backend",
-        "dotnet",
-        "vsa"
-      ],
-      "aliases": [
-        "Scrutor",
-        "auto-discovery",
-        "assembly scanning",
-        "decorator registration",
-        "handler registration"
-      ],
-      "anchors": {
-        "handlers": "#handler-auto-discovery",
-        "decorators": "#decorator-order",
-        "endpoints": "#endpoint-auto-discovery"
-      },
-      "digest": "Use Scrutor for convention-based DI registration. AddHandlersFromAssembly() scans for IHandler<,> implementations. Decorate<> applies pipeline decorators (validation, logging) — last registered wraps outermost. Register validators before handlers. RegisterApiEndpointsFromAssembly() auto-discovers IApiEndpoint implementations.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "backend-dotnet-fluent-validation-vsa",
-      "name": "fluent validation vsa",
-      "path": "backend/dotnet/fluent-validation-vsa.md",
-      "category": "backend",
-      "subcategory": "dotnet",
-      "tags": [
-        "backend",
-        "dotnet",
-        "vsa"
-      ],
-      "aliases": [
-        "FluentValidation VSA",
-        "validation decorator",
-        "validation pipeline",
-        "AbstractValidator",
-        "ValidationDecorator"
-      ],
-      "anchors": {
-        "validator": "#validator-structure",
-        "decorator": "#validationdecorator-pattern",
-        "conversion": "#fluentvalidation-to-validationerror-conversion"
-      },
-      "digest": "Use AbstractValidator<T> per request DTO in feature folders. ValidationDecorator intercepts all handlers via Scrutor, runs validators in parallel, and short-circuits to Result.Failure(ValidationError) on failure. Register AddValidatorsFromAssembly() before AddHandlersFromAssembly(). Never validate inside handlers.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "backend-dotnet-scalar-ui",
-      "name": "scalar ui",
-      "path": "backend/dotnet/scalar-ui.md",
-      "category": "backend",
-      "subcategory": "dotnet",
-      "tags": [
-        "backend",
-        "dotnet",
-        "vsa"
-      ],
-      "aliases": [
-        "Scalar",
-        "API documentation",
-        "OpenAPI UI",
-        "Swagger replacement",
-        "Scalar.AspNetCore"
-      ],
-      "anchors": {
-        "setup": "#programcs-configuration",
-        "tags": "#apitags-organization",
-        "metadata": "#endpoint-metadata"
-      },
-      "digest": "Use Scalar.AspNetCore 2.12.40 as API documentation UI — replaces Swagger. MapScalarApiReference() with DeepSpace theme. Group endpoints with .WithTags() and ApiTags constants. Document responses with .Produces<T>(). Guard MapOpenApi() with IsDevelopment(). No Swashbuckle needed.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "backend-dotnet-vsa-handler-patterns",
-      "name": "vsa handler patterns",
-      "path": "backend/dotnet/vsa-handler-patterns.md",
-      "category": "backend",
-      "subcategory": "dotnet",
-      "tags": [
-        "backend",
-        "dotnet",
-        "vsa"
-      ],
-      "aliases": [
-        "VSA handler",
-        "vertical slice handler",
-        "feature slice",
-        "IHandler pattern",
-        "handler endpoint"
-      ],
-      "anchors": {
-        "handler": "#ihandlertrequest-tresponse",
-        "folder": "#feature-folder-structure-5-files-per-slice",
-        "endpoint": "#complete-endpoint-example",
-        "registration": "#programcs-di-registration-order"
-      },
-      "digest": "Each VSA feature is 5 files: Request, Response, Handler, Validator, Endpoint. Use IHandler<TReq,TRes> (not MediatR). Sealed records for DTOs, primary constructors for DI, Guid.CreateVersion7() for IDs. Handler calls Repository+UnitOfWork directly — no service layer. CancellationToken in every async call.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "backend-integrations-asaas-asaas-api",
-      "name": "asaas api",
-      "path": "backend/integrations/asaas/asaas-api.md",
-      "category": "backend",
-      "subcategory": "integrations",
-      "tags": [
-        "backend",
-        "integrations",
-        "asaas"
-      ],
-      "aliases": [
-        "asaas",
-        "payment",
-        "PIX",
-        "boleto",
-        "Brazilian payment"
-      ],
-      "anchors": {
-        "payments": "#payment-types",
-        "webhooks": "#webhook-handling"
-      },
-      "digest": "Use AsaasClient SDK — never call REST API directly. Register as scoped service. Implement webhook signature verification. Map SDK enums to domain enums at integration boundary. Use idempotency keys for retry safety. Test with Asaas sandbox environment.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "backend-integrations-neon-auth-neon-auth",
-      "name": "neon auth",
-      "path": "backend/integrations/neon-auth/neon-auth.md",
-      "category": "backend",
-      "subcategory": "integrations",
-      "tags": [
-        "backend",
-        "integrations",
-        "neon-auth",
-        "better-auth"
-      ],
-      "aliases": [
-        "neon auth",
-        "better auth",
-        "authentication",
-        "OAuth",
-        "JWT",
-        "session management"
-      ],
-      "anchors": {
-        "setup": "#installation--setup",
-        "middleware": "#route-protection-middleware",
-        "dotnet": "#net-backend-integration",
-        "rls": "#row-level-security-integration"
-      },
-      "digest": "Use @neondatabase/auth SDK for Next.js. Auth data lives in neon_auth schema — no external provider, no webhooks. Server: createNeonAuth() with NEON_AUTH_BASE_URL + NEON_AUTH_COOKIE_SECRET. Client: createAuthClient(). Pages: AuthView component. Protection: auth.middleware(). .NET: JWT Bearer with Neon Auth authority, NameClaimType=sub. RLS: auth.user_id() via pg_session_jwt.",
-      "stacks": [
-        "neon"
-      ]
-    },
-    {
-      "id": "backend-integrations-hangfire-hangfire-jobs",
-      "name": "hangfire jobs",
-      "path": "backend/integrations/hangfire/hangfire-jobs.md",
-      "category": "backend",
-      "subcategory": "integrations",
-      "tags": [
-        "backend",
-        "integrations",
-        "hangfire"
-      ],
-      "aliases": [
-        "hangfire",
-        "background jobs",
-        "scheduled jobs",
-        "recurring",
-        "cron",
-        "fire and forget"
-      ],
-      "anchors": {
-        "jobs": "#job-types",
-        "retry": "#retry-policies"
-      },
-      "digest": "Use IDbContextFactory for scoped DB operations in jobs — never inject DbContext directly into job classes. BackgroundJob.Enqueue for fire-and-forget, RecurringJob.AddOrUpdate for cron. Add RetryCountAttribute for retries. Secure Hangfire Dashboard with auth in production. Never put long-running work in a single job — decompose.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "backend-integrations-resend-resend-email",
-      "name": "resend email",
-      "path": "backend/integrations/resend/resend-email.md",
-      "category": "backend",
-      "subcategory": "integrations",
-      "tags": [
-        "backend",
-        "integrations",
-        "resend"
-      ],
-      "aliases": [
-        "resend",
-        "email",
-        "transactional email",
-        "SMTP",
-        "email notification"
-      ],
-      "anchors": {
-        "sending": "#send-email",
-        "templates": "#email-templates"
-      },
-      "digest": "Register ResendClient as singleton. Provide both HTML and plain-text alternatives. Handle bounce/complaint webhooks to maintain sender reputation. Never send from test domains in production. Queue emails via Hangfire for reliability — don't send inline in request handlers.",
-      "stacks": [
-        "dotnet"
-      ]
-    },
-    {
-      "id": "data-nosql-cache-redis",
-      "name": "redis",
-      "path": "data/nosql/cache/redis.md",
-      "category": "data",
-      "subcategory": "nosql",
-      "tags": [
-        "data",
-        "nosql",
-        "cache"
-      ],
-      "aliases": [
-        "redis",
-        "cache",
-        "distributed cache",
-        "IDistributedCache",
-        "cache-aside",
-        "StackExchange.Redis"
-      ],
-      "anchors": {
-        "patterns": "#cache-patterns",
-        "invalidation": "#cache-invalidation"
-      },
-      "digest": "IDistributedCache for cache-aside pattern. Set TTL on every entry — never cache without expiry. Serialize with System.Text.Json. Sliding expiration for sessions, absolute for computed results. Invalidate by key prefix. Redis eviction policy must be set (allkeys-lru). Never cache PII without encryption.",
-      "stacks": [
-        "dotnet",
-        "azure"
-      ]
-    },
-    {
-      "id": "data-nosql-cosmos-db",
-      "name": "cosmos db",
-      "path": "data/nosql/cosmos-db.md",
-      "category": "data",
-      "subcategory": "nosql",
-      "tags": [
-        "data",
-        "nosql"
-      ],
-      "aliases": [
-        "cosmos",
-        "CosmosDB",
-        "document database",
-        "partition key",
-        "RUs"
-      ],
-      "anchors": {
-        "modeling": "#document-modeling",
-        "queries": "#query-patterns"
-      },
-      "digest": "Choose partition key with high cardinality for even distribution. Design documents for single-partition reads. Enable TTL for ephemeral data. Prefer point reads (O(1)) over cross-partition queries. Set provisioned throughput based on measured RUs. Use change feed for event-driven processing.",
-      "stacks": [
-        "dotnet",
-        "azure"
-      ]
-    },
-    {
-      "id": "data-vector-search-rag-chunking",
-      "name": "rag chunking",
-      "path": "data/vector-search/rag-chunking.md",
-      "category": "data",
-      "subcategory": "vector-search",
-      "tags": [
-        "data",
-        "vector-search"
-      ],
-      "aliases": [
-        "RAG chunking",
-        "document chunking",
-        "text splitting",
-        "chunk overlap",
-        "embedding chunks"
-      ],
-      "anchors": {
-        "strategies": "#chunking-strategies",
-        "retrieval": "#retrieval-pipeline"
-      },
-      "digest": "Recursive character splitting: 512 token chunks, 50 token overlap. Embed with text-embedding-3-small (1536 dims). Store chunk + metadata (source, page, section). Retrieve top-k=5 by cosine similarity. Re-rank with cross-encoder before LLM injection. Evaluate retrieval quality with RAGAS.",
-      "stacks": [
-        "dotnet",
-        "azure"
-      ]
-    },
-    {
-      "id": "frontend-design-system-animations",
-      "name": "animations",
-      "path": "frontend/design-system/animations.md",
-      "category": "frontend",
-      "subcategory": "design-system",
-      "tags": [
-        "frontend",
-        "design-system"
-      ],
-      "aliases": [
-        "animations",
-        "transitions",
-        "motion",
-        "CSS animations",
-        "keyframes",
-        "prefers-reduced-motion"
-      ],
-      "anchors": {
-        "tokens": "#animation-tokens",
-        "principles": "#motion-principles"
-      },
-      "digest": "Use CSS custom properties for durations: --duration-fast (100ms), --duration-normal (200ms), --duration-slow (300ms). Prefer transform/opacity for GPU-accelerated animations. Always respect prefers-reduced-motion. No decorative animations over 300ms. Ease-out for entrances, ease-in for exits.",
-      "stacks": [
-        "*"
-      ]
-    },
-    {
-      "id": "frontend-design-system-naming",
-      "name": "naming",
-      "path": "frontend/design-system/naming.md",
-      "category": "frontend",
-      "subcategory": "design-system",
-      "tags": [
-        "frontend",
-        "design-system"
-      ],
-      "aliases": [
-        "BEM",
-        "CSS naming",
-        "class naming",
-        "design token naming",
-        "component naming"
-      ],
-      "anchors": {
-        "blocks": "#bem-blocks",
-        "tokens": "#token-naming"
-      },
-      "digest": "BEM for CSS: .block__element--modifier. Design tokens: --color-primary-500, --spacing-4, --font-size-base. Component names PascalCase (React/Next.js) / kebab-case (CSS). No generic names (blue, big). Semantic names only: --color-action, --spacing-page-gutter. Tokens are the single source of truth.",
-      "stacks": [
-        "*"
-      ]
-    },
-    {
-      "id": "frontend-nextjs-motion-patterns",
-      "name": "motion patterns",
-      "path": "frontend/nextjs/motion-patterns.md",
-      "category": "frontend",
-      "subcategory": "nextjs",
-      "tags": [
-        "frontend",
-        "nextjs",
-        "framer-motion"
-      ],
-      "aliases": [
-        "framer-motion",
-        "animation variants",
-        "motion design",
-        "page transition",
-        "AnimatePresence"
-      ],
-      "anchors": {
-        "variants": "#core-variants-library",
-        "tokens": "#design-token-bridge",
-        "scroll": "#scroll-animations",
-        "accessibility": "#wcag-accessibility-mandatory"
-      },
-      "digest": "Canonical Framer Motion variants (fadeIn, slideIn, scaleIn, stagger, pageTransition) with design token bridge. Use whileInView for scroll reveals. Respect prefers-reduced-motion via useReducedMotion() — strip transforms, keep opacity.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-gsap-core",
-      "name": "gsap core",
-      "path": "frontend/gsap/gsap-core.md",
-      "category": "frontend",
-      "subcategory": "gsap",
-      "tags": [
-        "frontend",
-        "gsap",
-        "animation",
-        "react"
-      ],
-      "aliases": [
-        "GSAP",
-        "GreenSock",
-        "gsap.to",
-        "gsap.from",
-        "useGSAP",
-        "gsap timeline",
-        "gsap utils",
-        "gsap performance"
-      ],
-      "anchors": {
-        "apis": "#core-animation-apis",
-        "react": "#reactnextjs-integration",
-        "timeline": "#timeline-sequencing",
-        "performance": "#performance",
-        "accessibility": "#accessibility"
-      },
-      "digest": "Use gsap.to/from/fromTo for imperative animations. In React, always use useGSAP() hook from @gsap/react with scope ref for automatic cleanup. Timelines sequence with position parameter. Animate only transforms + opacity for 60fps. Check prefers-reduced-motion. Import durations/easings from design tokens.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-gsap-scrolltrigger",
-      "name": "gsap scrolltrigger",
-      "path": "frontend/gsap/gsap-scrolltrigger.md",
-      "category": "frontend",
-      "subcategory": "gsap",
-      "tags": [
-        "frontend",
-        "gsap",
-        "scrolltrigger",
-        "scroll-animation"
-      ],
-      "aliases": [
-        "ScrollTrigger",
-        "scroll animation",
-        "pinning",
-        "scrubbing",
-        "parallax",
-        "scroll-driven"
-      ],
-      "anchors": {
-        "basic": "#basic-scrolltrigger",
-        "scrub": "#scrubbing",
-        "pin": "#pinning",
-        "batch": "#batch-processing"
-      },
-      "digest": "Register ScrollTrigger plugin client-side only. Use scrub for scroll-linked progress. Pin sections with pin:true. Batch-process list items with ScrollTrigger.batch(). Call ScrollTrigger.refresh() after dynamic content. Kill all triggers in useGSAP cleanup.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-gsap-plugins",
-      "name": "gsap plugins",
-      "path": "frontend/gsap/gsap-plugins.md",
-      "category": "frontend",
-      "subcategory": "gsap",
-      "tags": [
-        "frontend",
-        "gsap",
-        "plugins"
-      ],
-      "aliases": [
-        "Flip",
-        "SplitText",
-        "MorphSVG",
-        "DrawSVG",
-        "MotionPath",
-        "Draggable",
-        "Observer",
-        "ScrollToPlugin"
-      ],
-      "anchors": {
-        "flip": "#flip-plugin",
-        "splittext": "#splittext",
-        "morphsvg": "#morphsvg",
-        "drawsvg": "#drawsvg"
-      },
-      "digest": "Flip for layout animations (getState then from). SplitText for char/word/line reveals (always revert on cleanup). MorphSVG for path morphing. DrawSVG for stroke animation. MotionPath for path-following. Draggable for drag with bounds/snap. Observer for gesture detection. Register all plugins before use.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-nextjs-app-router",
-      "name": "app router",
-      "path": "frontend/nextjs/app-router.md",
-      "category": "frontend",
-      "subcategory": "nextjs",
-      "tags": [
-        "frontend",
-        "nextjs"
-      ],
-      "aliases": [
-        "app router",
-        "Next.js 14",
-        "server components",
-        "app directory",
-        "RSC"
-      ],
-      "anchors": {
-        "layout": "#layout-patterns",
-        "routing": "#routing-patterns"
-      },
-      "digest": "Server Components by default — only add 'use client' when needed (interactivity, browser APIs, hooks). Layouts persist across navigations. Parallel Routes with @folder for simultaneous views. Route Groups with (folder) to organize without affecting URL. Use generateMetadata() for dynamic SEO metadata.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-nextjs-components",
-      "name": "components",
-      "path": "frontend/nextjs/components.md",
-      "category": "frontend",
-      "subcategory": "nextjs",
-      "tags": [
-        "frontend",
-        "nextjs"
-      ],
-      "aliases": [
-        "react components",
-        "server component",
-        "client component",
-        "shadcn/ui",
-        "UI components"
-      ],
-      "anchors": {
-        "patterns": "#component-patterns",
-        "shadcn": "#shadcn-usage"
-      },
-      "digest": "Server Components for data fetching and static content. Client Components for interactivity. shadcn/ui components are copy-paste — customize in src/components/ui/. Never use index.tsx for named exports. One component per file. Avoid prop drilling — use composition or Context API.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-nextjs-data-fetching",
-      "name": "data fetching",
-      "path": "frontend/nextjs/data-fetching.md",
-      "category": "frontend",
-      "subcategory": "nextjs",
-      "tags": [
-        "frontend",
-        "nextjs"
-      ],
-      "aliases": [
-        "TanStack Query",
-        "react-query",
-        "server actions",
-        "data fetching",
-        "useQuery"
-      ],
-      "anchors": {
-        "server": "#server-fetching",
-        "client": "#client-fetching"
-      },
-      "digest": "Server Components: fetch() with caching tags for static/ISR. Client Components: TanStack Query useQuery/useMutation for client-side state. Server Actions for mutations from Client Components. Never fetch in useEffect — use TanStack Query. Set revalidate intervals for ISR. Use React Suspense for loading states.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-nextjs-forms",
-      "name": "forms",
-      "path": "frontend/nextjs/forms.md",
-      "category": "frontend",
-      "subcategory": "nextjs",
-      "tags": [
-        "frontend",
-        "nextjs"
-      ],
-      "aliases": [
-        "react-hook-form",
-        "Zod",
-        "form validation",
-        "Server Actions forms",
-        "useFormState"
-      ],
-      "anchors": {
-        "validation": "#zod-schemas",
-        "submission": "#form-submission"
-      },
-      "digest": "react-hook-form with Zod resolver for client forms. Define Zod schema before component. Server Actions for mutations: 'use server' directive. Use useFormState/useActionState for Server Action feedback. Never submit to API routes — use Server Actions or React Query mutations. Display field-level errors from Zod.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-nextjs-naming-conventions",
-      "name": "naming conventions",
-      "path": "frontend/nextjs/naming-conventions.md",
-      "category": "frontend",
-      "subcategory": "nextjs",
-      "tags": [
-        "frontend",
-        "nextjs"
-      ],
-      "aliases": [
-        "naming conventions",
-        "file naming",
-        "component naming",
-        "Next.js naming",
-        "TypeScript naming"
-      ],
-      "anchors": {
-        "files": "#file-naming",
-        "components": "#component-naming"
-      },
-      "digest": "Pages: lowercase kebab-case (user-profile/page.tsx). Components: PascalCase (UserProfile.tsx). Hooks: camelCase with 'use' prefix (useUserProfile.ts). API routes: kebab-case. Types: PascalCase. No default exports except page.tsx and layout.tsx. Feature-based co-location preferred.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-nextjs-nextjs-patterns",
-      "name": "nextjs patterns",
-      "path": "frontend/nextjs/nextjs-patterns.md",
-      "category": "frontend",
-      "subcategory": "nextjs",
-      "tags": [
-        "frontend",
-        "nextjs"
-      ],
-      "aliases": [
-        "Next.js patterns",
-        "middleware",
-        "auth patterns",
-        "caching patterns",
-        "image optimization"
-      ],
-      "anchors": {
-        "auth": "#auth-patterns",
-        "caching": "#caching-patterns"
-      },
-      "digest": "Middleware for auth redirects (use matcher config). next/image for all images (auto-optimization). next/link for navigation (prefetching). loading.tsx for Suspense boundaries per route. error.tsx for error boundaries. Use unstable_cache for expensive server computations with tag-based revalidation.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-nextjs-project-structure",
-      "name": "project structure",
-      "path": "frontend/nextjs/project-structure.md",
-      "category": "frontend",
-      "subcategory": "nextjs",
-      "tags": [
-        "frontend",
-        "nextjs"
-      ],
-      "aliases": [
-        "project structure",
-        "folder structure",
-        "src directory",
-        "app directory organization"
-      ],
-      "anchors": {
-        "structure": "#directory-structure",
-        "organization": "#feature-organization"
-      },
-      "digest": "src/app/ for routes, src/components/ for shared UI, src/lib/ for utilities, src/hooks/ for custom hooks, src/types/ for TypeScript types. Co-locate feature components near their routes. Public API via components/index.ts. Avoid barrel files in app/ directory. Keep pages thin — logic in hooks and utilities.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-nextjs-state-management",
-      "name": "state management",
-      "path": "frontend/nextjs/state-management.md",
-      "category": "frontend",
-      "subcategory": "nextjs",
-      "tags": [
-        "frontend",
-        "nextjs"
-      ],
-      "aliases": [
-        "zustand",
-        "React context",
-        "global state",
-        "state management",
-        "client state"
-      ],
-      "anchors": {
-        "patterns": "#state-patterns",
-        "server": "#server-state"
-      },
-      "digest": "TanStack Query for server state (caching, background sync, optimistic updates). Zustand for global client state (auth, theme, user preferences). URL params for shareable UI state (filters, pagination). useState for local component state. Avoid Redux — Zustand is sufficient for most Next.js use cases.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "frontend-nextjs-testing",
-      "name": "testing",
-      "path": "frontend/nextjs/testing.md",
-      "category": "frontend",
-      "subcategory": "nextjs",
-      "tags": [
-        "frontend",
-        "nextjs"
-      ],
-      "aliases": [
-        "vitest",
-        "jest",
-        "testing-library",
-        "Playwright",
-        "Next.js testing",
-        "component tests"
-      ],
-      "anchors": {
-        "unit": "#unit-tests",
-        "e2e": "#e2e-tests"
-      },
-      "digest": "Vitest for unit tests, React Testing Library for component tests. Mock next/navigation with vi.mock. Test Server Actions with direct function calls. Use MSW for API mocking in component tests. Playwright for E2E tests against running app. Never test implementation details — test user behavior and output.",
-      "stacks": [
-        "nextjs"
-      ]
-    },
-    {
-      "id": "infrastructure-docker-easypanel-deploy",
-      "name": "easypanel deploy",
-      "path": "infrastructure/docker/easypanel-deploy.md",
-      "category": "infrastructure",
-      "subcategory": "docker",
-      "tags": [
-        "infrastructure",
-        "docker"
-      ],
-      "aliases": [
-        "easypanel",
-        "docker deploy",
-        "self-hosted",
-        "VPS deployment",
-        "docker compose"
-      ],
-      "anchors": {
-        "setup": "#easypanel-setup",
-        "deployment": "#deployment-flow"
-      },
-      "digest": "Create app in EasyPanel from container registry image. Configure environment variables in EasyPanel UI — not in Dockerfile. Use EasyPanel's managed Postgres/Redis for databases. Configure /health endpoint for health checks. Enable HTTPS via Let's Encrypt automatically. Use EasyPanel volumes for persistent storage.",
-      "stacks": [
-        "docker"
-      ]
-    },
-    {
-      "id": "infrastructure-neon-setup",
-      "name": "neon setup",
-      "path": "infrastructure/neon/neon-setup.md",
-      "category": "infrastructure",
-      "subcategory": "neon",
-      "tags": [
-        "infrastructure",
-        "neon",
-        "postgresql"
-      ],
-      "aliases": [
-        "Neon",
-        "neonctl",
-        "serverless postgres",
-        "Neon CLI",
-        "Neon setup"
-      ],
-      "anchors": {
-        "setup": "#neon-project-setup",
-        "connection": "#connection-strings"
-      },
-      "digest": "Use neonctl CLI for project management and connection strings. Two connection strings: pooled (-pooler) for application code, direct for EF Core migrations. Configure connection retry for scale-to-zero cold starts. Use database branches for PR previews.",
-      "stacks": [
-        "neon"
-      ]
-    },
-    {
-      "id": "infrastructure-neon-pgvector",
-      "name": "neon pgvector",
-      "path": "infrastructure/neon/neon-pgvector.md",
-      "category": "infrastructure",
-      "subcategory": "neon",
-      "tags": [
-        "infrastructure",
-        "neon",
-        "pgvector"
-      ],
-      "aliases": [
-        "pgvector",
-        "vector embeddings",
-        "similarity search",
-        "Neon vectors",
-        "HNSW index"
-      ],
-      "anchors": {
-        "setup": "#pgvector-setup",
-        "queries": "#similarity-queries"
-      },
-      "digest": "Enable: CREATE EXTENSION vector. Define column as vector(1536) for OpenAI embeddings. Create HNSW index with tuned maintenance_work_mem. Use direct SQL for similarity search. Batch insert embeddings (100 at a time). RLS policies apply to vector queries.",
-      "stacks": [
-        "neon"
-      ]
-    },
-    {
-      "id": "infrastructure-neon-pgrag",
-      "name": "neon pgrag",
-      "path": "infrastructure/neon/neon-pgrag.md",
-      "category": "infrastructure",
-      "subcategory": "neon",
-      "tags": [
-        "infrastructure",
-        "neon",
-        "pgrag"
-      ],
-      "aliases": [
-        "pgrag",
-        "RAG in SQL",
-        "embedding pipeline",
-        "Neon RAG",
-        "in-database RAG"
-      ],
-      "anchors": {
-        "setup": "#pgrag-setup",
-        "pipeline": "#rag-pipeline"
-      },
-      "digest": "Use pgrag extensions (rag, rag_bge_small_en_v15, rag_jina_reranker_v1_tiny_en) for chunking, embedding, search, and reranking entirely in SQL. No external embedding service needed for basic RAG. Combine with pgvector HNSW indexes for production performance.",
-      "stacks": [
-        "neon"
-      ]
-    },
-    {
-      "id": "infrastructure-neon-semantic-kernel",
-      "name": "neon semantic kernel",
-      "path": "infrastructure/neon/neon-semantic-kernel.md",
-      "category": "infrastructure",
-      "subcategory": "neon",
-      "tags": [
-        "infrastructure",
-        "neon",
-        "semantic-kernel"
-      ],
-      "aliases": [
-        "Semantic Kernel",
-        "vector store",
-        "Neon Semantic Kernel",
-        "SK vector store",
-        "AI memory"
-      ],
-      "anchors": {
-        "setup": "#semantic-kernel-setup",
-        "store": "#vector-store-integration"
-      },
-      "digest": "Use Neon as Semantic Kernel vector store via Npgsql connector. Register IVectorStore with NpgsqlDataSource pointing to pooled Neon endpoint. Store and retrieve embeddings using SK memory abstractions. Combine with pgvector HNSW indexes.",
-      "stacks": [
-        "neon",
-        "semantic-kernel"
-      ]
-    },
-    {
-      "id": "integration-mcp-mcp-tools",
-      "name": "mcp tools",
-      "path": "integration/mcp/mcp-tools.md",
-      "category": "integration",
-      "subcategory": "mcp",
-      "tags": [
-        "integration",
-        "mcp"
-      ],
-      "aliases": [
-        "MCP",
-        "Model Context Protocol",
-        "Claude tools",
-        "MCP server",
-        "MCP client"
-      ],
-      "anchors": {
-        "tools": "#tool-definitions",
-        "setup": "#server-setup"
-      },
-      "digest": "MCP tools extend Claude with external data and actions. Tools are synchronous request-response with typed inputSchema. Resources provide read-only data access. Prompts are reusable templates. Register MCP servers in .claude/settings.json. Prefer @context7 for live library docs. Test tools with MCP Inspector before integrating.",
-      "stacks": [
-        "*"
-      ]
-    },
-    {
-      "id": "frontend-design-system-ai-image-generation",
-      "name": "AI Image Generation",
-      "path": "frontend/design-system/ai-image-generation.md",
-      "category": "frontend",
-      "subcategory": "design-system",
-      "tags": [
-        "image",
-        "gemini",
-        "asset",
-        "ai-generation",
-        "placeholder",
-        "mcp"
-      ],
-      "aliases": [
-        "Image Generation",
-        "AI Assets",
-        "Gemini Images"
-      ],
-      "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"
-      },
-      "digest": "Guidelines for generating project images with Gemini Image MCP — prompt patterns, aspect ratios, design-system-aware prompts, iterative editing, and assets.md format.",
-      "stacks": [
-        "nextjs"
-      ]
-    }
-  ]
-}
+{
+  "version": "1.0.0",
+  "standards": [
+    {
+      "id": "ai-agents-production",
+      "name": "production",
+      "path": "ai-agents/production.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "agent middleware",
+        "production agent",
+        "a2a protocol",
+        "mcp integration",
+        "agent observability",
+        "agent telemetry",
+        "anti-hallucination",
+        "semantic caching"
+      ],
+      "anchors": {
+        "middleware": "#middleware-pipeline",
+        "a2a": "#a2a-protocol-agent-to-agent",
+        "mcp": "#mcp-integration-model-context-protocol",
+        "observability": "#observability--opentelemetry"
+      },
+      "digest": "Production panorama for MAF agents. Middleware (3 levels) and MCP integration are summarized here and treated canonically in ai-agents-middleware-patterns / ai-agents-mcp-tools / ai-agents-mcp-server. Owns: A2A protocol via Microsoft.Agents.AI.A2A; Redis semantic + HybridCache caching; OpenTelemetry observability with AgentOpenTelemetryConsts.DefaultSourceName; security and production checklists."
+    },
+    {
+      "id": "ai-agents-setup",
+      "name": "setup",
+      "path": "ai-agents/setup.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "MAF setup",
+        "Microsoft Agents AI",
+        "ChatClient",
+        "AsAIAgent",
+        "AIAgent dotnet",
+        "agent framework setup",
+        "MAF packages",
+        "MAF nuget"
+      ],
+      "anchors": {
+        "packages": "#1-packages-nuget",
+        "quickstart": "#2-quick-start-canonical-minimal-agent",
+        "providers": "#3-setup-by-provider",
+        "telemetry": "#5-opentelemetry"
+      },
+      "digest": "Use Microsoft.Agents.AI 1.0 GA packages. Register IChatClient via DI. Create agents with AsAIAgent() or new ChatClientAgent(). OpenTelemetry source is AgentOpenTelemetryConsts.DefaultSourceName. Provider-agnostic, direct models only. Do NOT use Semantic Kernel or Microsoft.Extensions.AI 9.x."
+    },
+    {
+      "id": "ai-agents-workflows",
+      "name": "workflows",
+      "path": "ai-agents/workflows.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "workflow",
+        "agent workflow",
+        "fan-in",
+        "fan-out",
+        "when not to use workflow",
+        "orchestration",
+        "AgentWorkflowBuilder",
+        "concurrent workflow"
+      ],
+      "anchors": {
+        "when-not": "#quando-não-usar-um-workflow",
+        "when-justified": "#quando-um-workflow-é-justificado",
+        "canonical-example": "#exemplo-canônico--fan-in-concurrent"
+      },
+      "digest": "Workflows are advanced and rare — 95% of agents need only a single agent (see ai-agents-sweet-spot). Reach for a Workflow ONLY for genuine fan-in/out over many inputs or long-running human-in-the-loop. A foreach + LINQ aggregate usually beats a Workflow. APIs (AgentWorkflowBuilder, InProcessExecution) ship in Microsoft.Agents.AI 1.0 GA."
+    },
+    {
+      "id": "ai-agents-sweet-spot",
+      "name": "sweet spot",
+      "path": "ai-agents/sweet-spot.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "decision-tree"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "sweet spot",
+        "when to use agent",
+        "agent vs workflow",
+        "when not to use workflow",
+        "MAF decision",
+        "simple agent default",
+        "4 feature rule",
+        "single agent default"
+      ],
+      "anchors": {
+        "rule": "#the-4-feature-rule",
+        "decision-tree": "#decision-tree-claude-reads-this-in-plan-phase",
+        "anti-patterns": "#anti-patterns-what-claude-should-not-do"
+      },
+      "digest": "The 4-feature rule (Chat + Structured Output + Tools + RAG Custom) covers 95% of agents. Single-agent is the default; reach for multi-agent or workflow only when fan-in/out or genuine handoff is needed. Read in plan phase before deciding architecture."
+    },
+    {
+      "id": "ai-agents-providers-model-registry",
+      "name": "model registry",
+      "path": "ai-agents/providers/model-registry.md",
+      "category": "ai-agents",
+      "subcategory": "providers",
+      "tags": [
+        "ai-agents",
+        "maf",
+        "providers",
+        "model-config"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "model registry",
+        "provider agnostic",
+        "model alias",
+        "IChatClient factory",
+        "multi-model",
+        "model selection",
+        "model config",
+        "switch provider",
+        "openai google anthropic ollama",
+        "direct model"
+      ],
+      "anchors": {
+        "schema": "#schema-canonical",
+        "providers": "#providers-first-class",
+        "implementation": "#implementation-pattern",
+        "checklist": "#checklist-verifiable-by-morph-eval"
+      },
+      "digest": "Provider-agnostic pattern: project keeps config/model-registry.json mapping aliases (text-default, vision, reasoning, etc.) to provider+model+options. Agents reference aliases, never hardcoded models. Direct models only (openai/google/anthropic/ollama). Switching provider/model is a one-file change."
+    },
+    {
+      "id": "ai-agents-structured-output",
+      "name": "structured output",
+      "path": "ai-agents/structured-output.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "s-tier"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "structured output",
+        "typed response",
+        "response format",
+        "schema validated output",
+        "record output",
+        "JSON schema agent",
+        "RunAsync generic",
+        "typed agent output"
+      ],
+      "anchors": {
+        "api": "#a-api-maf-10-ga",
+        "type": "#definindo-o-tipo-de-saída",
+        "validation": "#validação-pós-call"
+      },
+      "digest": "Always return typed records from agents that feed downstream systems. MAF 1.0: RunAsync<T>() returns AgentResponse<T>.Result, or ChatResponseFormat.ForJsonSchema<T>(). Output type is a sealed record/class with [Description] + [JsonPropertyName]. Validate business rules after the call."
+    },
+    {
+      "id": "ai-agents-multi-agent-patterns",
+      "name": "multi-agent patterns",
+      "path": "ai-agents/multi-agent-patterns.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "multi-agent",
+        "agent as tool",
+        "agent composition",
+        "sequential agents",
+        "handoff",
+        "sub-agent",
+        "agent orchestration"
+      ],
+      "anchors": {
+        "agent-as-tool": "#agent-as-tool-padrão-recomendado",
+        "sequential": "#sequential-cadeia-fixa",
+        "decision-tree": "#decision-tree"
+      },
+      "digest": "Compose agents only when a single agent is not enough (see ai-agents-sweet-spot). Agent-as-Tool (agent.AsAIFunction()) is the simplest and recommended pattern. Sequential = plain imperative C#. Handoff for intent routing. Workflows only for genuine fan-in/out."
+    },
+    {
+      "id": "ai-agents-prompts-in-db",
+      "name": "prompts in db",
+      "path": "ai-agents/prompts-in-db.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "prompts"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "prompts in db",
+        "agent prompts",
+        "prompt versioning",
+        "prompt hot-reload",
+        "editable instructions",
+        "prompt management"
+      ],
+      "anchors": {
+        "pattern": "#o-pattern",
+        "schema": "#schema-da-tabela",
+        "versioning": "#versionamento"
+      },
+      "digest": "Store agent instructions in an agent_prompts table, not hardcoded — the team tunes without a deploy. A PromptRepository loads the active prompt by agent_key with an in-memory cache. Versioning is immutable: INSERT a new version and flip is_active, never UPDATE content."
+    },
+    {
+      "id": "ai-agents-rag-custom-pgvector",
+      "name": "rag custom pgvector",
+      "path": "ai-agents/rag-custom-pgvector.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "rag",
+        "pgvector"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "rag",
+        "vector search",
+        "pgvector",
+        "embeddings",
+        "custom rag",
+        "retrieval",
+        "semantic search",
+        "knowledge base",
+        "RAG tool"
+      ],
+      "anchors": {
+        "architecture": "#arquitetura",
+        "tool": "#vectorsearchtool-tool-maf",
+        "multi-tenant": "#multi-tenant"
+      },
+      "digest": "Custom RAG you control: an EmbeddingService generates vectors, a pgvector table stores chunk+embedding+metadata, a typed MAF VectorSearchTool runs the cosine query. Replaces the deleted Semantic Kernel vector-store path. Multi-tenant via tenant_id filter + RLS. Never use hosted RAG."
+    },
+    {
+      "id": "ai-agents-middleware-patterns",
+      "name": "middleware patterns",
+      "path": "ai-agents/middleware-patterns.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "middleware"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "middleware",
+        "agent middleware",
+        "function calling middleware",
+        "retry",
+        "anti-hallucination",
+        "resilience",
+        "telemetry middleware",
+        "agent run middleware"
+      ],
+      "anchors": {
+        "levels": "#os-3-níveis-de-middleware",
+        "resilience": "#pattern-resilência-retry--rate-limit",
+        "anti-hallucination": "#pattern-anti-hallucination"
+      },
+      "digest": "Three middleware levels intercept agent behavior: Agent Run (whole invocation), Function Calling (individual tool calls), IChatClient (raw LLM calls). Register via .AsBuilder().Use(...). Patterns: telemetry, resilience (retry/rate-limit), anti-hallucination (validate tool args before next())."
+    },
+    {
+      "id": "ai-agents-modalities-vision",
+      "name": "modalities vision",
+      "path": "ai-agents/modalities-vision.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "multimodal",
+        "vision"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "vision",
+        "image to text",
+        "OCR",
+        "image analysis",
+        "multimodal input",
+        "image agent",
+        "PDF analysis",
+        "visual understanding"
+      ],
+      "anchors": {
+        "when": "#quando-usar-vision",
+        "api": "#a-api",
+        "example": "#exemplo-c-completo",
+        "content-types": "#datacontent-vs-uricontent"
+      },
+      "digest": "Use vision when the agent needs to interpret images, screenshots, scanned documents or PDFs. MAF exposes multimodal ChatMessage with DataContent (inline bytes) or UriContent (remote URL). Covers OCR, diagram understanding, UI screenshot analysis, and document extraction. Anti-patterns: sending raw Base64 blobs without MIME type, ignoring resolution limits."
+    },
+    {
+      "id": "ai-agents-modalities-image-gen",
+      "name": "modalities image gen",
+      "path": "ai-agents/modalities-image-gen.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "multimodal",
+        "image-generation"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "image generation",
+        "text to image",
+        "dall-e",
+        "gpt-image",
+        "mockup",
+        "image synthesis",
+        "generate image",
+        "image from text"
+      ],
+      "anchors": {
+        "when": "#quando-usar-geração-de-imagem",
+        "api": "#a-api",
+        "example": "#exemplo-c-completo",
+        "params": "#parâmetros"
+      },
+      "digest": "Use image generation when the agent must produce images from text prompts — mockups, thumbnails, placeholders, or dynamic visuals. MAF uses ImageClient wrapping the DALL-E / gpt-image provider. Covers quality/size parameters, response format (URL vs Base64), and storing generated images to blob storage. Anti-patterns: generating images inline in HTTP request handlers without queuing."
+    },
+    {
+      "id": "ai-agents-modalities-speech-to-text",
+      "name": "modalities speech to text",
+      "path": "ai-agents/modalities-speech-to-text.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "multimodal",
+        "stt",
+        "audio"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "speech to text",
+        "transcription",
+        "whisper",
+        "audio to text",
+        "voice transcription",
+        "STT",
+        "audio transcription"
+      ],
+      "anchors": {
+        "when": "#quando-usar-stt",
+        "api": "#a-api",
+        "example": "#exemplo-c-completo",
+        "formats": "#formatos-e-limites"
+      },
+      "digest": "Use STT when the agent receives voice input or audio files that must be transcribed to text before processing. MAF wraps the Whisper/AudioClient API. Covers supported audio formats (mp3, wav, webm, mp4), file-size limits, language hints, and streaming vs batch transcription. Anti-patterns: piping raw audio into a chat message without transcribing first."
+    },
+    {
+      "id": "ai-agents-modalities-text-to-speech",
+      "name": "modalities text to speech",
+      "path": "ai-agents/modalities-text-to-speech.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "multimodal",
+        "tts",
+        "audio"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "text to speech",
+        "TTS",
+        "voice synthesis",
+        "audio generation",
+        "speech synthesis",
+        "voice output",
+        "speak text"
+      ],
+      "anchors": {
+        "when": "#quando-usar-tts",
+        "api": "#a-api",
+        "example": "#exemplo-c-completo",
+        "params": "#parâmetros"
+      },
+      "digest": "Use TTS when the agent must return audio output — voice assistants, accessibility narration, podcast generation. MAF uses AudioClient for text-to-speech with configurable voice, speed, and output format (mp3, opus, flac). Covers streaming audio response, voice selection, and integration with blob storage for async delivery. Anti-patterns: synthesizing long texts synchronously in a request handler."
+    },
+    {
+      "id": "ai-agents-batching",
+      "name": "batching",
+      "path": "ai-agents/batching.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "batching",
+        "cost-optimization"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "batching",
+        "batch api",
+        "bulk prompts",
+        "batch processing",
+        "async batch",
+        "bulk inference",
+        "offline batch"
+      ],
+      "anchors": {
+        "when": "#quando-usar-batch",
+        "api": "#a-api",
+        "example": "#exemplo-c-completo",
+        "when-not": "#quando-não-usar"
+      },
+      "digest": "Use the OpenAI Batch API when processing large volumes of independent prompts (classification, extraction, summarisation) where latency is not critical. Batch jobs receive a ~50% cost discount and run asynchronously with a 24-hour completion window. MAF wraps batch submission, polling, and result parsing. Anti-patterns: using batch for interactive user-facing calls or tasks requiring immediate results."
+    },
+    {
+      "id": "ai-agents-service-tier-flex",
+      "name": "service tier flex",
+      "path": "ai-agents/service-tier-flex.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "cost-optimization",
+        "service-tier"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "service tier",
+        "flex tier",
+        "cost optimization",
+        "async tier",
+        "priority tier",
+        "tier flex",
+        "background inference"
+      ],
+      "anchors": {
+        "when": "#quando-usar-tier-flex",
+        "api": "#a-api",
+        "example": "#exemplo-c",
+        "decision": "#decision"
+      },
+      "digest": "The Flex service tier routes requests to spare capacity at lower cost, accepting variable latency in exchange. Use for background jobs, nightly reports, and any async workload where cost matters more than response time. MAF sets service_tier=flex in ChatOptions. Covers the decision matrix (flex vs default vs batch) and anti-patterns such as using flex for real-time user interactions."
+    },
+    {
+      "id": "ai-agents-agent-session",
+      "name": "agent session",
+      "path": "ai-agents/agent-session.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "conversation",
+        "session"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "agent session",
+        "chat history",
+        "conversation state",
+        "chat reducer",
+        "history truncation",
+        "AgentThread",
+        "multi-turn",
+        "persistent session"
+      ],
+      "anchors": {
+        "when": "#quando-usar-agentsession",
+        "api": "#a-api",
+        "example": "#exemplo-c--agente-conversacional-com-session-persistente-entre-turnos",
+        "history": "#history-management"
+      },
+      "digest": "AgentSession manages conversational state across multiple turns — stores and retrieves chat history, applies reducers to trim token usage, and persists sessions between HTTP requests. Use for chat UIs, voice assistants, and any multi-turn interaction. Covers history reducers (sliding window, summarisation), session serialisation, and multi-tenant session isolation. Anti-patterns: keeping history in memory without persistence."
+    },
+    {
+      "id": "ai-agents-context-providers",
+      "name": "context providers",
+      "path": "ai-agents/context-providers.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "context",
+        "dependency-injection"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "context provider",
+        "dynamic context",
+        "context injection",
+        "AIContextProvider",
+        "memory provider",
+        "inject context",
+        "system prompt injection"
+      ],
+      "anchors": {
+        "when": "#quando-usar-context-provider",
+        "api": "#a-api",
+        "example": "#exemplo-c--context-provider-que-injeta-data-atual-e-perfil-do-tenant",
+        "comparison": "#context-provider-vs-tools-vs-rag"
+      },
+      "digest": "AIContextProvider injects dynamic context into the agent's system prompt at runtime — current date, tenant profile, feature flags, user preferences — without requiring the caller to pass it explicitly. Registered via DI, executed before each agent invocation. Covers the decision matrix (Context Provider vs Tools vs RAG), provider chaining, and async data loading. Anti-patterns: fetching slow external data synchronously in a provider."
+    },
+    {
+      "id": "ai-agents-mcp-tools",
+      "name": "mcp tools (agent consumer)",
+      "path": "ai-agents/mcp-tools.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "mcp",
+        "tools"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "mcp",
+        "model context protocol",
+        "mcp client",
+        "consume mcp server",
+        "mcp tools",
+        "external tools",
+        "McpClientFactory",
+        "agent mcp client"
+      ],
+      "anchors": {
+        "what": "#o-que-é-no-contexto-de-um-agente-maf",
+        "api": "#a-api",
+        "example": "#exemplo-c",
+        "comparison": "#mcp-server-vs-tool-nativa"
+      },
+      "digest": "Covers how a MAF agent consumes external MCP servers as tool sources. McpClientFactory connects to an MCP server (stdio or SSE transport), discovers available tools, and exposes them as MAF AIFunctions. Use when an MCP server already exposes the capability you need. Covers popular MCP servers, the decision matrix (MCP server vs native MAF tool), and anti-patterns such as wrapping an MCP tool unnecessarily in a native function."
+    },
+    {
+      "id": "ai-agents-mcp-server",
+      "name": "mcp server",
+      "path": "ai-agents/mcp-server.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "mcp",
+        "server"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "mcp server",
+        "expose mcp",
+        "build mcp server",
+        "mcp host",
+        "publish tools",
+        "create mcp server",
+        "ModelContextProtocol server"
+      ],
+      "anchors": {
+        "when": "#quando-criar-um-mcp-server",
+        "api": "#a-api",
+        "example": "#exemplo-c--tools-por-atributo-stdio",
+        "http": "#exemplo-c--transport-http",
+        "security": "#segurança"
+      },
+      "digest": "Covers building an MCP server that exposes project capabilities (business logic, databases, internal APIs) to external agents and Claude Code. Uses the ModelContextProtocol .NET SDK: tools via [McpServerToolType]/[McpServerTool] attributes (WithToolsFromAssembly) or McpServerTool.Create for a MAF agent. Covers stdio vs HTTP transport (ModelContextProtocol.AspNetCore, WithHttpTransport stateless, MapMcp), authentication, the decision matrix (native MAF tool vs exposed MCP server), and security such as input validation and rate limiting."
+    },
+    {
+      "id": "architecture-vertical-slice-vertical-slice",
+      "name": "vertical slice",
+      "path": "architecture/vertical-slice/vertical-slice.md",
+      "category": "architecture",
+      "subcategory": "vertical-slice",
+      "tags": [
+        "architecture",
+        "vertical-slice"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "vertical slice",
+        "VSA",
+        "slice architecture",
+        "feature slice",
+        "CQRS slice"
+      ],
+      "anchors": {
+        "structure": "#estrutura-de-pastas",
+        "rules": "#padrões-obrigatórios",
+        "cqrs": "#anti-patterns-nunca-fazer-em-vsa"
+      },
+      "digest": "Organize by feature, not layer. Each slice contains Command/Query, Handler, Validator, Response. No cross-slice dependencies — shared code goes to a dedicated Shared project. Use MediatR for in-process CQRS dispatch."
+    },
+    {
+      "id": "backend-api-validation",
+      "name": "validation",
+      "path": "backend/api/validation.md",
+      "category": "backend",
+      "subcategory": "api",
+      "tags": [
+        "backend",
+        "api"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "FluentValidation",
+        "input validation",
+        "request validation",
+        "API validation",
+        "model validation"
+      ],
+      "anchors": {
+        "fluent": "#validation-patterns",
+        "rules": "#validation-patterns"
+      },
+      "digest": "Use FluentValidation for all request validation. Register validators as scoped services. Return 422 UnprocessableEntity with field-level error messages. Validate at API boundary — not inside domain logic. Never trust client-side validation alone."
+    },
+    {
+      "id": "backend-database-postgresql-database",
+      "name": "database",
+      "path": "backend/database/postgresql/database.md",
+      "category": "backend",
+      "subcategory": "database",
+      "tags": [
+        "backend",
+        "database",
+        "postgresql"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "PostgreSQL",
+        "postgres",
+        "pg",
+        "database design",
+        "SQL schema"
+      ],
+      "anchors": {
+        "schema": "#schema-design",
+        "indexes": "#indexes"
+      },
+      "digest": "Use timestamptz for all timestamps (not timestamp). UUID primary keys for public-facing IDs. Add indexes on FK columns and frequently filtered columns. Use GIN indexes for JSON/array columns. JSONB over JSON. Row-level security for multi-tenant. Never store binary in columns — use storage URLs."
+    },
+    {
+      "id": "backend-database-vector-search-rag",
+      "name": "vector search rag",
+      "path": "backend/database/vector-search-rag.md",
+      "category": "backend",
+      "subcategory": "database",
+      "tags": [
+        "backend",
+        "database"
+      ],
+      "stacks": [
+        "dotnet",
+        "nextjs",
+        "neon"
+      ],
+      "aliases": [
+        "vector search",
+        "RAG",
+        "embeddings",
+        "pgvector",
+        "semantic search"
+      ],
+      "anchors": {
+        "chunking": "#📥-indexação-de-documentos",
+        "retrieval": "#🔍-vector-search-com-ef-core-10"
+      },
+      "digest": "Chunk documents with 512 token size and 50 token overlap for RAG. Embed with text-embedding-3-small. Store embedding + metadata (source, chunk index). Retrieve top-k=5 by cosine similarity. Re-rank before injecting into LLM context. Use pgvector HNSW index for performance at scale."
+    },
+    {
+      "id": "backend-dotnet-result-pattern",
+      "name": "result pattern",
+      "path": "backend/dotnet/result-pattern.md",
+      "category": "backend",
+      "subcategory": "dotnet",
+      "tags": [
+        "backend",
+        "dotnet",
+        "vsa"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "Result<T>",
+        "railway oriented",
+        "error handling",
+        "Match pattern",
+        "Result monad"
+      ],
+      "anchors": {
+        "anatomy": "#result-anatomy",
+        "errors": "#error-types-7--custom",
+        "match": "#match-pattern"
+      },
+      "digest": "Use Result<T> for all handler returns — never throw for expected failures. 7 error types (Failure, Unexpected, Validation, Conflict, NotFound, Unauthorized, Forbidden) map to HTTP status codes. Use Match() in endpoints to convert Result to IResult. Implicit conversions allow returning values or errors directly from handlers."
+    },
+    {
+      "id": "backend-dotnet-scrutor",
+      "name": "scrutor",
+      "path": "backend/dotnet/scrutor.md",
+      "category": "backend",
+      "subcategory": "dotnet",
+      "tags": [
+        "backend",
+        "dotnet",
+        "vsa"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "Scrutor",
+        "auto-discovery",
+        "assembly scanning",
+        "decorator registration",
+        "handler registration"
+      ],
+      "anchors": {
+        "handlers": "#handler-auto-discovery",
+        "decorators": "#decorator-order",
+        "endpoints": "#endpoint-auto-discovery"
+      },
+      "digest": "Use Scrutor for convention-based DI registration. AddHandlersFromAssembly() scans for IHandler<,> implementations. Decorate<> applies pipeline decorators (validation, logging) — last registered wraps outermost. Register validators before handlers. RegisterApiEndpointsFromAssembly() auto-discovers IApiEndpoint implementations."
+    },
+    {
+      "id": "backend-dotnet-fluent-validation-vsa",
+      "name": "fluent validation vsa",
+      "path": "backend/dotnet/fluent-validation-vsa.md",
+      "category": "backend",
+      "subcategory": "dotnet",
+      "tags": [
+        "backend",
+        "dotnet",
+        "vsa"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "FluentValidation VSA",
+        "validation decorator",
+        "validation pipeline",
+        "AbstractValidator",
+        "ValidationDecorator"
+      ],
+      "anchors": {
+        "validator": "#validator-structure",
+        "decorator": "#validationdecorator-pattern",
+        "conversion": "#fluentvalidation-to-validationerror-conversion"
+      },
+      "digest": "Use AbstractValidator<T> per request DTO in feature folders. ValidationDecorator intercepts all handlers via Scrutor, runs validators in parallel, and short-circuits to Result.Failure(ValidationError) on failure. Register AddValidatorsFromAssembly() before AddHandlersFromAssembly(). Never validate inside handlers."
+    },
+    {
+      "id": "backend-dotnet-scalar-ui",
+      "name": "scalar ui",
+      "path": "backend/dotnet/scalar-ui.md",
+      "category": "backend",
+      "subcategory": "dotnet",
+      "tags": [
+        "backend",
+        "dotnet",
+        "vsa"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "Scalar",
+        "API documentation",
+        "OpenAPI UI",
+        "Swagger replacement",
+        "Scalar.AspNetCore"
+      ],
+      "anchors": {
+        "setup": "#programcs-configuration",
+        "tags": "#apitags-organization",
+        "metadata": "#endpoint-metadata"
+      },
+      "digest": "Use Scalar.AspNetCore 2.12.40 as API documentation UI — replaces Swagger. MapScalarApiReference() with DeepSpace theme. Group endpoints with .WithTags() and ApiTags constants. Document responses with .Produces<T>(). Guard MapOpenApi() with IsDevelopment(). No Swashbuckle needed."
+    },
+    {
+      "id": "backend-dotnet-vsa-handler-patterns",
+      "name": "vsa handler patterns",
+      "path": "backend/dotnet/vsa-handler-patterns.md",
+      "category": "backend",
+      "subcategory": "dotnet",
+      "tags": [
+        "backend",
+        "dotnet",
+        "vsa"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "VSA handler",
+        "vertical slice handler",
+        "feature slice",
+        "IHandler pattern",
+        "handler endpoint"
+      ],
+      "anchors": {
+        "handler": "#ihandlertrequest-tresponse",
+        "folder": "#feature-folder-structure-5-files-per-slice",
+        "endpoint": "#complete-endpoint-example",
+        "registration": "#programcs-di-registration-order"
+      },
+      "digest": "Each VSA feature is 5 files: Request, Response, Handler, Validator, Endpoint. Use IHandler<TReq,TRes> (not MediatR). Sealed records for DTOs, primary constructors for DI, Guid.CreateVersion7() for IDs. Handler calls Repository+UnitOfWork directly — no service layer. CancellationToken in every async call."
+    },
+    {
+      "id": "backend-integrations-asaas-asaas-api",
+      "name": "asaas api",
+      "path": "backend/integrations/asaas/asaas-api.md",
+      "category": "backend",
+      "subcategory": "integrations",
+      "tags": [
+        "backend",
+        "integrations",
+        "asaas"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "asaas",
+        "payment",
+        "PIX",
+        "boleto",
+        "Brazilian payment"
+      ],
+      "anchors": {
+        "payments": "#create-pix-payment",
+        "webhooks": "#webhook-handler"
+      },
+      "digest": "Use AsaasClient SDK — never call REST API directly. Register as scoped service. Implement webhook signature verification. Map SDK enums to domain enums at integration boundary. Use idempotency keys for retry safety. Test with Asaas sandbox environment."
+    },
+    {
+      "id": "backend-integrations-neon-auth-neon-auth",
+      "name": "neon auth",
+      "path": "backend/integrations/neon-auth/neon-auth.md",
+      "category": "backend",
+      "subcategory": "integrations",
+      "tags": [
+        "backend",
+        "integrations",
+        "neon-auth",
+        "better-auth"
+      ],
+      "stacks": [
+        "neon"
+      ],
+      "aliases": [
+        "neon auth",
+        "better auth",
+        "authentication",
+        "OAuth",
+        "JWT",
+        "session management"
+      ],
+      "anchors": {
+        "setup": "#installation--setup",
+        "middleware": "#route-protection-middleware",
+        "dotnet": "#net-backend-integration",
+        "rls": "#row-level-security-integration"
+      },
+      "digest": "Use @neondatabase/auth SDK for Next.js. Auth data lives in neon_auth schema — no external provider, no webhooks. Server: createNeonAuth() with NEON_AUTH_BASE_URL + NEON_AUTH_COOKIE_SECRET. Client: createAuthClient(). Pages: AuthView component. Protection: auth.middleware(). .NET: JWT Bearer with Neon Auth authority, NameClaimType=sub. RLS: auth.user_id() via pg_session_jwt."
+    },
+    {
+      "id": "backend-integrations-hangfire-hangfire-jobs",
+      "name": "hangfire jobs",
+      "path": "backend/integrations/hangfire/hangfire-jobs.md",
+      "category": "backend",
+      "subcategory": "integrations",
+      "tags": [
+        "backend",
+        "integrations",
+        "hangfire"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "hangfire",
+        "background jobs",
+        "scheduled jobs",
+        "recurring",
+        "cron",
+        "fire and forget"
+      ],
+      "anchors": {
+        "jobs": "#job-types",
+        "retry": "#retry--error-handling"
+      },
+      "digest": "Use IDbContextFactory for scoped DB operations in jobs — never inject DbContext directly into job classes. BackgroundJob.Enqueue for fire-and-forget, RecurringJob.AddOrUpdate for cron. Add RetryCountAttribute for retries. Secure Hangfire Dashboard with auth in production. Never put long-running work in a single job — decompose."
+    },
+    {
+      "id": "backend-integrations-resend-resend-email",
+      "name": "resend email",
+      "path": "backend/integrations/resend/resend-email.md",
+      "category": "backend",
+      "subcategory": "integrations",
+      "tags": [
+        "backend",
+        "integrations",
+        "resend"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "resend",
+        "email",
+        "transactional email",
+        "SMTP",
+        "email notification"
+      ],
+      "anchors": {
+        "sending": "#send-email-api-route",
+        "templates": "#common-email-templates"
+      },
+      "digest": "Register ResendClient as singleton. Provide both HTML and plain-text alternatives. Handle bounce/complaint webhooks to maintain sender reputation. Never send from test domains in production. Queue emails via Hangfire for reliability — don't send inline in request handlers."
+    },
+    {
+      "id": "data-nosql-cache-redis",
+      "name": "redis",
+      "path": "data/nosql/cache/redis.md",
+      "category": "data",
+      "subcategory": "nosql",
+      "tags": [
+        "data",
+        "nosql",
+        "cache"
+      ],
+      "stacks": [
+        "dotnet",
+        "azure"
+      ],
+      "aliases": [
+        "redis",
+        "cache",
+        "distributed cache",
+        "IDistributedCache",
+        "cache-aside",
+        "StackExchange.Redis"
+      ],
+      "anchors": {
+        "patterns": "#cache-aside-pattern",
+        "invalidation": "#ttl-strategy"
+      },
+      "digest": "IDistributedCache for cache-aside pattern. Set TTL on every entry — never cache without expiry. Serialize with System.Text.Json. Sliding expiration for sessions, absolute for computed results. Invalidate by key prefix. Redis eviction policy must be set (allkeys-lru). Never cache PII without encryption."
+    },
+    {
+      "id": "data-nosql-cosmos-db",
+      "name": "cosmos db",
+      "path": "data/nosql/cosmos-db.md",
+      "category": "data",
+      "subcategory": "nosql",
+      "tags": [
+        "data",
+        "nosql"
+      ],
+      "stacks": [
+        "dotnet",
+        "azure"
+      ],
+      "aliases": [
+        "cosmos",
+        "CosmosDB",
+        "document database",
+        "partition key",
+        "RUs"
+      ],
+      "anchors": {
+        "modeling": "#container-design",
+        "queries": "#repository-pattern"
+      },
+      "digest": "Choose partition key with high cardinality for even distribution. Design documents for single-partition reads. Enable TTL for ephemeral data. Prefer point reads (O(1)) over cross-partition queries. Set provisioned throughput based on measured RUs. Use change feed for event-driven processing."
+    },
+    {
+      "id": "data-vector-search-rag-chunking",
+      "name": "rag chunking",
+      "path": "data/vector-search/rag-chunking.md",
+      "category": "data",
+      "subcategory": "vector-search",
+      "tags": [
+        "data",
+        "vector-search"
+      ],
+      "stacks": [
+        "dotnet",
+        "azure"
+      ],
+      "aliases": [
+        "RAG chunking",
+        "document chunking",
+        "text splitting",
+        "chunk overlap",
+        "embedding chunks"
+      ],
+      "anchors": {
+        "strategies": "#chunking-strategies",
+        "retrieval": "#chunking-strategies"
+      },
+      "digest": "Recursive character splitting: 512 token chunks, 50 token overlap. Embed with text-embedding-3-small (1536 dims). Store chunk + metadata (source, page, section). Retrieve top-k=5 by cosine similarity. Re-rank with cross-encoder before LLM injection. Evaluate retrieval quality with RAGAS."
+    },
+    {
+      "id": "frontend-design-system-animations",
+      "name": "animations",
+      "path": "frontend/design-system/animations.md",
+      "category": "frontend",
+      "subcategory": "design-system",
+      "tags": [
+        "frontend",
+        "design-system"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "animations",
+        "transitions",
+        "motion",
+        "CSS animations",
+        "keyframes",
+        "prefers-reduced-motion"
+      ],
+      "anchors": {
+        "tokens": "#stagger--timing",
+        "principles": "#css-animation-patterns"
+      },
+      "digest": "Use CSS custom properties for durations: --duration-fast (100ms), --duration-normal (200ms), --duration-slow (300ms). Prefer transform/opacity for GPU-accelerated animations. Always respect prefers-reduced-motion. No decorative animations over 300ms. Ease-out for entrances, ease-in for exits."
+    },
+    {
+      "id": "frontend-design-system-naming",
+      "name": "naming",
+      "path": "frontend/design-system/naming.md",
+      "category": "frontend",
+      "subcategory": "design-system",
+      "tags": [
+        "frontend",
+        "design-system"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "BEM",
+        "CSS naming",
+        "class naming",
+        "design token naming",
+        "component naming"
+      ],
+      "anchors": {
+        "blocks": "#bem-for-reusable-components",
+        "tokens": "#css-variables-with-namespace"
+      },
+      "digest": "BEM for CSS: .block__element--modifier. Design tokens: --color-primary-500, --spacing-4, --font-size-base. Component names PascalCase (React/Next.js) / kebab-case (CSS). No generic names (blue, big). Semantic names only: --color-action, --spacing-page-gutter. Tokens are the single source of truth."
+    },
+    {
+      "id": "frontend-nextjs-motion-patterns",
+      "name": "motion patterns",
+      "path": "frontend/nextjs/motion-patterns.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs",
+        "framer-motion"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "framer-motion",
+        "animation variants",
+        "motion design",
+        "page transition",
+        "AnimatePresence"
+      ],
+      "anchors": {
+        "variants": "#section-1-core-variants-library",
+        "tokens": "#section-2-design-token-bridge",
+        "scroll": "#section-3-scroll-animations",
+        "accessibility": "#section-7-wcag-accessibility-mandatory"
+      },
+      "digest": "Canonical Framer Motion variants (fadeIn, slideIn, scaleIn, stagger, pageTransition) with design token bridge. Use whileInView for scroll reveals. Respect prefers-reduced-motion via useReducedMotion() — strip transforms, keep opacity."
+    },
+    {
+      "id": "frontend-gsap-core",
+      "name": "gsap core",
+      "path": "frontend/gsap/gsap-core.md",
+      "category": "frontend",
+      "subcategory": "gsap",
+      "tags": [
+        "frontend",
+        "gsap",
+        "animation",
+        "react"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "GSAP",
+        "GreenSock",
+        "gsap.to",
+        "gsap.from",
+        "useGSAP",
+        "gsap timeline",
+        "gsap utils",
+        "gsap performance"
+      ],
+      "anchors": {
+        "apis": "#section-3-core-animation-apis",
+        "react": "#section-4-reactnextjs-integration",
+        "timeline": "#section-5-timeline-sequencing",
+        "performance": "#section-7-performance",
+        "accessibility": "#section-8-accessibility"
+      },
+      "digest": "Use gsap.to/from/fromTo for imperative animations. In React, always use useGSAP() hook from @gsap/react with scope ref for automatic cleanup. Timelines sequence with position parameter. Animate only transforms + opacity for 60fps. Check prefers-reduced-motion. Import durations/easings from design tokens."
+    },
+    {
+      "id": "frontend-gsap-scrolltrigger",
+      "name": "gsap scrolltrigger",
+      "path": "frontend/gsap/gsap-scrolltrigger.md",
+      "category": "frontend",
+      "subcategory": "gsap",
+      "tags": [
+        "frontend",
+        "gsap",
+        "scrolltrigger",
+        "scroll-animation"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "ScrollTrigger",
+        "scroll animation",
+        "pinning",
+        "scrubbing",
+        "parallax",
+        "scroll-driven"
+      ],
+      "anchors": {
+        "basic": "#section-2-basic-scrolltrigger",
+        "scrub": "#section-3-scrubbing",
+        "pin": "#section-4-pinning",
+        "batch": "#section-5-batch-processing"
+      },
+      "digest": "Register ScrollTrigger plugin client-side only. Use scrub for scroll-linked progress. Pin sections with pin:true. Batch-process list items with ScrollTrigger.batch(). Call ScrollTrigger.refresh() after dynamic content. Kill all triggers in useGSAP cleanup."
+    },
+    {
+      "id": "frontend-gsap-plugins",
+      "name": "gsap plugins",
+      "path": "frontend/gsap/gsap-plugins.md",
+      "category": "frontend",
+      "subcategory": "gsap",
+      "tags": [
+        "frontend",
+        "gsap",
+        "plugins"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "Flip",
+        "SplitText",
+        "MorphSVG",
+        "DrawSVG",
+        "MotionPath",
+        "Draggable",
+        "Observer",
+        "ScrollToPlugin"
+      ],
+      "anchors": {
+        "flip": "#flip-plugin-free",
+        "splittext": "#splittext",
+        "morphsvg": "#morphsvg",
+        "drawsvg": "#drawsvg"
+      },
+      "digest": "Flip for layout animations (getState then from). SplitText for char/word/line reveals (always revert on cleanup). MorphSVG for path morphing. DrawSVG for stroke animation. MotionPath for path-following. Draggable for drag with bounds/snap. Observer for gesture detection. Register all plugins before use."
+    },
+    {
+      "id": "frontend-nextjs-app-router",
+      "name": "app router",
+      "path": "frontend/nextjs/app-router.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "app router",
+        "Next.js 14",
+        "server components",
+        "app directory",
+        "RSC"
+      ],
+      "anchors": {
+        "layout": "#root-layout--required-providers",
+        "routing": "#app-directory-structure"
+      },
+      "digest": "Server Components by default — only add 'use client' when needed (interactivity, browser APIs, hooks). Layouts persist across navigations. Parallel Routes with @folder for simultaneous views. Route Groups with (folder) to organize without affecting URL. Use generateMetadata() for dynamic SEO metadata."
+    },
+    {
+      "id": "frontend-nextjs-components",
+      "name": "components",
+      "path": "frontend/nextjs/components.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "react components",
+        "server component",
+        "client component",
+        "shadcn/ui",
+        "UI components"
+      ],
+      "anchors": {
+        "patterns": "#three-tier-hierarchy",
+        "shadcn": "#tier-1--shadcnui-primitives"
+      },
+      "digest": "Server Components for data fetching and static content. Client Components for interactivity. shadcn/ui components are copy-paste — customize in src/components/ui/. Never use index.tsx for named exports. One component per file. Avoid prop drilling — use composition or Context API."
+    },
+    {
+      "id": "frontend-nextjs-data-fetching",
+      "name": "data fetching",
+      "path": "frontend/nextjs/data-fetching.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "TanStack Query",
+        "react-query",
+        "server actions",
+        "data fetching",
+        "useQuery"
+      ],
+      "anchors": {
+        "server": "#server-component--tanstack-query-handoff",
+        "client": "#usequery-hook-pattern"
+      },
+      "digest": "Server Components: fetch() with caching tags for static/ISR. Client Components: TanStack Query useQuery/useMutation for client-side state. Server Actions for mutations from Client Components. Never fetch in useEffect — use TanStack Query. Set revalidate intervals for ISR. Use React Suspense for loading states."
+    },
+    {
+      "id": "frontend-nextjs-forms",
+      "name": "forms",
+      "path": "frontend/nextjs/forms.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "react-hook-form",
+        "Zod",
+        "form validation",
+        "Server Actions forms",
+        "useFormState"
+      ],
+      "anchors": {
+        "validation": "#schema-composition",
+        "submission": "#complete-form-pattern"
+      },
+      "digest": "react-hook-form with Zod resolver for client forms. Define Zod schema before component. Server Actions for mutations: 'use server' directive. Use useFormState/useActionState for Server Action feedback. Never submit to API routes — use Server Actions or React Query mutations. Display field-level errors from Zod."
+    },
+    {
+      "id": "frontend-nextjs-naming-conventions",
+      "name": "naming conventions",
+      "path": "frontend/nextjs/naming-conventions.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "naming conventions",
+        "file naming",
+        "component naming",
+        "Next.js naming",
+        "TypeScript naming"
+      ],
+      "anchors": {
+        "files": "#complete-reference-table",
+        "components": "#complete-reference-table"
+      },
+      "digest": "Pages: lowercase kebab-case (user-profile/page.tsx). Components: PascalCase (UserProfile.tsx). Hooks: camelCase with 'use' prefix (useUserProfile.ts). API routes: kebab-case. Types: PascalCase. No default exports except page.tsx and layout.tsx. Feature-based co-location preferred."
+    },
+    {
+      "id": "frontend-nextjs-nextjs-patterns",
+      "name": "nextjs patterns",
+      "path": "frontend/nextjs/nextjs-patterns.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "Next.js patterns",
+        "middleware",
+        "auth patterns",
+        "caching patterns",
+        "image optimization"
+      ],
+      "anchors": {
+        "auth": "#route-handlers-bff-pattern",
+        "caching": "#react-query--neon"
+      },
+      "digest": "Middleware for auth redirects (use matcher config). next/image for all images (auto-optimization). next/link for navigation (prefetching). loading.tsx for Suspense boundaries per route. error.tsx for error boundaries. Use unstable_cache for expensive server computations with tag-based revalidation."
+    },
+    {
+      "id": "frontend-nextjs-project-structure",
+      "name": "project structure",
+      "path": "frontend/nextjs/project-structure.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "project structure",
+        "folder structure",
+        "src directory",
+        "app directory organization"
+      ],
+      "anchors": {
+        "structure": "#canonical-folder-tree",
+        "organization": "#feature-index-pattern"
+      },
+      "digest": "src/app/ for routes, src/components/ for shared UI, src/lib/ for utilities, src/hooks/ for custom hooks, src/types/ for TypeScript types. Co-locate feature components near their routes. Public API via components/index.ts. Avoid barrel files in app/ directory. Keep pages thin — logic in hooks and utilities."
+    },
+    {
+      "id": "frontend-nextjs-state-management",
+      "name": "state management",
+      "path": "frontend/nextjs/state-management.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "zustand",
+        "React context",
+        "global state",
+        "state management",
+        "client state"
+      ],
+      "anchors": {
+        "patterns": "#state-decision-tree",
+        "server": "#server-state-tanstack-query"
+      },
+      "digest": "TanStack Query for server state (caching, background sync, optimistic updates). Zustand for global client state (auth, theme, user preferences). URL params for shareable UI state (filters, pagination). useState for local component state. Avoid Redux — Zustand is sufficient for most Next.js use cases."
+    },
+    {
+      "id": "frontend-nextjs-testing",
+      "name": "testing",
+      "path": "frontend/nextjs/testing.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "vitest",
+        "jest",
+        "testing-library",
+        "Playwright",
+        "Next.js testing",
+        "component tests"
+      ],
+      "anchors": {
+        "unit": "#component-test-pattern",
+        "e2e": "#test-file-co-location"
+      },
+      "digest": "Vitest for unit tests, React Testing Library for component tests. Mock next/navigation with vi.mock. Test Server Actions with direct function calls. Use MSW for API mocking in component tests. Playwright for E2E tests against running app. Never test implementation details — test user behavior and output."
+    },
+    {
+      "id": "infrastructure-docker-easypanel-deploy",
+      "name": "easypanel deploy",
+      "path": "infrastructure/docker/easypanel-deploy.md",
+      "category": "infrastructure",
+      "subcategory": "docker",
+      "tags": [
+        "infrastructure",
+        "docker"
+      ],
+      "stacks": [
+        "docker"
+      ],
+      "aliases": [
+        "easypanel",
+        "docker deploy",
+        "self-hosted",
+        "VPS deployment",
+        "docker compose"
+      ],
+      "anchors": {
+        "setup": "#easypanel-service-config",
+        "deployment": "#zero-downtime-deploys"
+      },
+      "digest": "Create app in EasyPanel from container registry image. Configure environment variables in EasyPanel UI — not in Dockerfile. Use EasyPanel's managed Postgres/Redis for databases. Configure /health endpoint for health checks. Enable HTTPS via Let's Encrypt automatically. Use EasyPanel volumes for persistent storage."
+    },
+    {
+      "id": "infrastructure-neon-setup",
+      "name": "neon setup",
+      "path": "infrastructure/neon/neon-setup.md",
+      "category": "infrastructure",
+      "subcategory": "neon",
+      "tags": [
+        "infrastructure",
+        "neon",
+        "postgresql"
+      ],
+      "stacks": [
+        "neon"
+      ],
+      "aliases": [
+        "Neon",
+        "neonctl",
+        "serverless postgres",
+        "Neon CLI",
+        "Neon setup"
+      ],
+      "anchors": {
+        "setup": "#neon-cli-setup",
+        "connection": "#connection-strings"
+      },
+      "digest": "Use neonctl CLI for project management and connection strings. Two connection strings: pooled (-pooler) for application code, direct for EF Core migrations. Configure connection retry for scale-to-zero cold starts. Use database branches for PR previews."
+    },
+    {
+      "id": "infrastructure-neon-pgvector",
+      "name": "neon pgvector",
+      "path": "infrastructure/neon/neon-pgvector.md",
+      "category": "infrastructure",
+      "subcategory": "neon",
+      "tags": [
+        "infrastructure",
+        "neon",
+        "pgvector"
+      ],
+      "stacks": [
+        "neon"
+      ],
+      "aliases": [
+        "pgvector",
+        "vector embeddings",
+        "similarity search",
+        "Neon vectors",
+        "HNSW index"
+      ],
+      "anchors": {
+        "setup": "#enable-pgvector",
+        "queries": "#similarity-search"
+      },
+      "digest": "Enable: CREATE EXTENSION vector. Define column as vector(1536) for OpenAI embeddings. Create HNSW index with tuned maintenance_work_mem. Use direct SQL for similarity search. Batch insert embeddings (100 at a time). RLS policies apply to vector queries."
+    },
+    {
+      "id": "infrastructure-neon-pgrag",
+      "name": "neon pgrag",
+      "path": "infrastructure/neon/neon-pgrag.md",
+      "category": "infrastructure",
+      "subcategory": "neon",
+      "tags": [
+        "infrastructure",
+        "neon",
+        "pgrag"
+      ],
+      "stacks": [
+        "neon"
+      ],
+      "aliases": [
+        "pgrag",
+        "RAG in SQL",
+        "embedding pipeline",
+        "Neon RAG",
+        "in-database RAG"
+      ],
+      "anchors": {
+        "setup": "#install-pgrag",
+        "pipeline": "#full-rag-pipeline-example"
+      },
+      "digest": "Use pgrag extensions (rag, rag_bge_small_en_v15, rag_jina_reranker_v1_tiny_en) for chunking, embedding, search, and reranking entirely in SQL. No external embedding service needed for basic RAG. Combine with pgvector HNSW indexes for production performance."
+    },
+    {
+      "id": "integration-mcp-mcp-tools",
+      "name": "mcp tools",
+      "path": "integration/mcp/mcp-tools.md",
+      "category": "integration",
+      "subcategory": "mcp",
+      "tags": [
+        "integration",
+        "mcp"
+      ],
+      "stacks": [
+        "*"
+      ],
+      "aliases": [
+        "MCP",
+        "Model Context Protocol",
+        "Claude tools",
+        "MCP server",
+        "MCP client"
+      ],
+      "anchors": {
+        "tools": "#mcp-providers-by-phase",
+        "setup": "#mcp-availability-detection"
+      },
+      "digest": "MCP tools extend Claude with external data and actions. Tools are synchronous request-response with typed inputSchema. Resources provide read-only data access. Prompts are reusable templates. Register MCP servers in .claude/settings.json. Prefer @context7 for live library docs. Test tools with MCP Inspector before integrating."
+    },
+    {
+      "id": "frontend-design-system-ai-image-generation",
+      "name": "AI Image Generation",
+      "path": "frontend/design-system/ai-image-generation.md",
+      "category": "frontend",
+      "subcategory": "design-system",
+      "tags": [
+        "image",
+        "gemini",
+        "asset",
+        "ai-generation",
+        "placeholder",
+        "mcp"
+      ],
+      "stacks": [
+        "nextjs"
+      ],
+      "aliases": [
+        "Image Generation",
+        "AI Assets",
+        "Gemini Images"
+      ],
+      "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"
+      },
+      "digest": "Guidelines for generating project images with Gemini Image MCP — prompt patterns, aspect ratios, design-system-aware prompts, iterative editing, and assets.md format."
+    }
+  ],
+  "sharedAliases": {
+    "agent middleware": [
+      "ai-agents-production",
+      "ai-agents-middleware-patterns"
+    ],
+    "anti-hallucination": [
+      "ai-agents-production",
+      "ai-agents-middleware-patterns"
+    ],
+    "when not to use workflow": [
+      "ai-agents-workflows",
+      "ai-agents-sweet-spot"
+    ],
+    "rag": [
+      "ai-agents-rag-custom-pgvector",
+      "backend-database-vector-search-rag"
+    ],
+    "vector search": [
+      "ai-agents-rag-custom-pgvector",
+      "backend-database-vector-search-rag"
+    ],
+    "pgvector": [
+      "ai-agents-rag-custom-pgvector",
+      "backend-database-vector-search-rag",
+      "infrastructure-neon-pgvector"
+    ],
+    "embeddings": [
+      "ai-agents-rag-custom-pgvector",
+      "backend-database-vector-search-rag"
+    ],
+    "semantic search": [
+      "ai-agents-rag-custom-pgvector",
+      "backend-database-vector-search-rag"
+    ],
+    "middleware": [
+      "ai-agents-middleware-patterns",
+      "frontend-nextjs-nextjs-patterns"
+    ],
+    "image generation": [
+      "ai-agents-modalities-image-gen",
+      "frontend-design-system-ai-image-generation"
+    ],
+    "mcp": [
+      "ai-agents-mcp-tools",
+      "integration-mcp-mcp-tools"
+    ],
+    "model context protocol": [
+      "ai-agents-mcp-tools",
+      "integration-mcp-mcp-tools"
+    ],
+    "mcp client": [
+      "ai-agents-mcp-tools",
+      "integration-mcp-mcp-tools"
+    ],
+    "mcp server": [
+      "ai-agents-mcp-server",
+      "integration-mcp-mcp-tools"
+    ],
+    "feature slice": [
+      "architecture-vertical-slice-vertical-slice",
+      "backend-dotnet-vsa-handler-patterns"
+    ],
+    "component naming": [
+      "frontend-design-system-naming",
+      "frontend-nextjs-naming-conventions"
+    ]
+  }
+}