go-duck-cli 1.0.9 → 1.1.1

package/templates/docs/pages/rest.hbs

@@ -1,227 +1,145 @@
-<div class="mb-10 text-center lg:text-left border-b border-slate-200 pb-8 text-neutral-900">
-    <div class="inline-flex items-center px-3 py-1 rounded-full bg-indigo-100 text-indigo-700 text-xs font-semibold tracking-wide uppercase mb-4">
-        Communication Layer
-    </div>
-    <h1 class="text-4xl lg:text-5xl font-extrabold text-slate-900 tracking-tight leading-tight mb-4">REST & Search API</h1>
-    <p class="text-lg lg:text-xl text-slate-600 max-w-2xl leading-relaxed">High-performance, tenant-aware JSON endpoints powered by Gin Gonic and GORM.</p>
-</div>
-
-<!-- Mode Overview -->
-<div class="grid grid-cols-1 md:grid-cols-2 gap-8 mb-12">
-    <div class="bg-gradient-to-br from-indigo-600 to-indigo-800 p-8 rounded-[2rem] text-white shadow-xl shadow-indigo-200/50">
-        <h3 class="text-xl font-bold mb-3 flex items-center">
-            <svg class="w-6 h-6 mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10"></path></svg>
-            Entity-Specific CRUD
-        </h3>
-        <p class="text-indigo-100 text-sm leading-relaxed mb-6">Standard strongly-typed controllers for every entity. Includes built-in caching, MQTT eventing, and multi-tenancy.</p>
-        <div class="text-xs font-mono bg-white/10 p-3 rounded-xl border border-white/20">
-            GET /api/articles<br>
-            GET /api/articles/:id?eager=true
-        </div>
-    </div>
-    <div class="bg-gradient-to-br from-slate-800 to-slate-900 p-8 rounded-[2rem] text-white shadow-xl shadow-slate-300/50">
-        <h3 class="text-xl font-bold mb-3 flex items-center">
-            <svg class="w-6 h-6 mr-3 text-emerald-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path></svg>
-            Generic Search RPC
-        </h3>
-        <p class="text-slate-300 text-sm leading-relaxed mb-6">A single, ultra-flexible engine mirroring PostgREST. Filter by any column using powerful operators WITHOUT writing code.</p>
-        <div class="text-xs font-mono bg-white/10 p-3 rounded-xl border border-white/20">
-            GET /api/rpc/articles?status=eq.PUBLISHED<br>
-            GET /api/rpc/articles?id=gt.100&order=id.desc
+<div class="prose prose-slate max-w-none">
+    <!-- Marketing Hero -->
+    <div class="flex items-center space-x-3 mb-8">
+        <div class="p-4 bg-gradient-to-br from-indigo-600 to-indigo-800 rounded-2xl shadow-lg shadow-indigo-200">
+            <svg class="w-8 h-8 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 18h.01M8 21h8a2 2 0 002-2V5a2 2 0 00-2-2H8a2 2 0 00-2 2v14a2 2 0 002 2z" />
+            </svg>
         </div>
+        <h1 class="text-5xl font-black text-slate-900 m-0 tracking-tight leading-tight">PostgREST-like <br><span class="text-indigo-600 italic">RPC Search Engine.</span></h1>
     </div>
-</div>
 
-<section class="mb-12">
-    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
-        <span class="w-8 h-8 rounded-lg bg-indigo-100 text-indigo-600 flex items-center justify-center mr-3 text-sm">
-            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16m-7 6h7"></path></svg>
-        </span>
-        Standard Controller Features
-    </h2>
+    <p class="text-2xl text-slate-500 font-medium mb-12 leading-relaxed">
+        Stop writing boiler-plate search controllers. GO-DUCK generates an high-performance, unified RPC layer for deep, transactional querying across your multi-silo empire.
+    </p>
 
-    <div class="space-y-8">
-        <!-- Relationship Loading -->
-        <div class="bg-white border border-slate-200 rounded-2xl p-6 shadow-sm">
-            <h4 class="font-bold text-slate-900 mb-3">📦 Eager vs. Lazy Loading</h4>
-            <p class="text-slate-600 text-sm mb-4 leading-relaxed">
-                By default, entities are loaded <strong>Lazily</strong> (IDs only for foreign keys). To perform a Join and fetch the full object graph, use the <code class="bg-slate-100 px-1 py-0.5 rounded text-indigo-600 font-mono">eager</code> parameter.
-            </p>
-            <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-                <div class="bg-slate-50 p-4 rounded-xl">
-                    <span class="text-[10px] font-bold uppercase tracking-widest text-slate-400">Lazy (Default)</span>
-                    <p class="font-mono text-xs mt-2 text-slate-700">GET /api/article/1</p>
-                </div>
-                <div class="bg-emerald-50 p-4 rounded-xl">
-                    <span class="text-[10px] font-bold uppercase tracking-widest text-emerald-500">Eager (Joined)</span>
-                    <p class="font-mono text-xs mt-2 text-slate-700">GET /api/article/1?eager=true</p>
-                </div>
-            </div>
+    <!-- Key Features Highlights -->
+    <div class="grid grid-cols-1 md:grid-cols-3 gap-8 mb-16">
+        <div class="p-8 bg-slate-50 rounded-3xl border border-slate-100 shadow-sm border-l-4 border-l-orange-500">
+            <h4 class="font-bold text-slate-900 mb-2 italic tracking-tight">Pure Full-Text Search</h4>
+            <p class="text-xs text-slate-600">Native <strong>Elasticsearch</strong> engine for sub-millisecond fuzzy matching on millions of records.</p>
         </div>
+        <div class="p-8 bg-slate-50 rounded-3xl border border-slate-100 shadow-sm border-l-4 border-l-indigo-600">
+            <h4 class="font-bold text-slate-900 mb-2 italic tracking-tight">Transactional RPC</h4>
+            <p class="text-xs text-slate-600">Dynamic, server-side filtering with <code>?filter=eq.val</code> directly on your GORM models.</p>
+        </div>
+        <div class="p-8 bg-slate-50 rounded-3xl border border-slate-100 shadow-sm border-l-4 border-l-purple-600">
+            <h4 class="font-bold text-slate-900 mb-2 italic tracking-tight">Postgres Arrow Power</h4>
+            <p class="text-xs text-slate-600">Query your <strong>JSONB</strong> fields using Postgres arrow operators (<code>-></code>, <code>->></code>) in your URI.</p>
+        </div>
+    </div>
 
-        <!-- Pagination -->
-        <div class="bg-white border border-slate-200 rounded-2xl p-6 shadow-sm">
-            <h4 class="font-bold text-slate-900 mb-3">📏 Offset Pagination</h4>
-            <p class="text-slate-600 text-sm mb-4 leading-relaxed">
-                All collection endpoints support built-in pagination to keep your frontend lightning fast.
-            </p>
-            <table class="w-full text-xs text-left border-collapse">
-                <thead>
-                    <tr class="text-slate-400 border-b border-slate-100">
-                        <th class="py-2">Parameter</th>
-                        <th class="py-2">Description</th>
-                        <th class="py-2">Default</th>
+    <!-- API ENDPOINT MAP -->
+    <section class="mb-20">
+        <h2 class="text-3xl font-black text-slate-900 mb-8 tracking-tight">API Reference & Endpoint Map</h2>
+        <div class="overflow-x-auto rounded-[2.5rem] border border-slate-200 shadow-sm transition-all duration-300">
+            <table class="min-w-full divide-y divide-slate-200">
+                <thead class="bg-indigo-50/50 text-indigo-900">
+                    <tr>
+                        <th class="px-6 py-4 text-left text-xs font-black uppercase tracking-widest">Verb</th>
+                        <th class="px-6 py-4 text-left text-xs font-black uppercase tracking-widest">Endpoint Pattern</th>
+                        <th class="px-6 py-4 text-left text-xs font-black uppercase tracking-widest">Discovery Power</th>
                     </tr>
                 </thead>
-                <tbody class="text-slate-700">
-                    <tr class="border-b border-slate-50"><td class="py-3 font-mono font-bold">page</td><td class="py-3">The index of the page to fetch</td><td class="py-3">0</td></tr>
-                    <tr class="border-b border-slate-50"><td class="py-3 font-mono font-bold">size</td><td class="py-3">Number of records per page</td><td class="py-3">20</td></tr>
+                <tbody class="bg-white divide-y divide-slate-100 text-sm italic font-medium">
+                    <tr class="bg-orange-50/20"><td class="px-6 py-4 font-bold text-orange-600">GET</td><td class="px-6 py-4 font-mono">/api/search/{entity}?q=keyword</td><td class="px-6 py-4 font-bold text-orange-800">Elite Elasticsearch Fuzzy Search</td></tr>
+                    <tr><td class="px-6 py-4 font-bold text-green-600">GET</td><td class="px-6 py-4 font-mono">/api/v1/{entity}</td><td class="px-6 py-4 text-slate-600">List and Search with GORM Filter Logic</td></tr>
+                    <tr><td class="px-6 py-4 font-bold text-orange-600">POST</td><td class="px-6 py-4 font-mono">/api/v1/{entity}</td><td class="px-6 py-4 text-slate-600">Atomic Primary Write + Saga Multi-Broadcast</td></tr>
+                    <tr><td class="px-6 py-4 font-bold text-purple-600">PATCH</td><td class="px-6 py-4 font-mono">/api/v1/{entity}/{id}</td><td class="px-6 py-4 text-slate-600">Partial Update (Single Silo or Global)</td></tr>
+                    <tr><td class="px-6 py-4 font-bold text-red-600">DELETE</td><td class="px-6 py-4 font-mono">/api/v1/{entity}/{id}</td><td class="px-6 py-4 text-slate-600">Distributed Atomic Deletion</td></tr>
+                    <tr class="bg-indigo-50/30"><td class="px-6 py-4 font-bold text-indigo-800">POST</td><td class="px-6 py-4 font-mono">/api/v1/{entity}/bulk</td><td class="px-6 py-4 text-indigo-900">Bulk Multi-Silo Transaction</td></tr>
+                    <tr class="bg-slate-900"><td class="px-6 py-4 font-bold text-yellow-400">GET</td><td class="px-6 py-4 font-mono text-slate-300">/api/admin/audit</td><td class="px-6 py-4 text-slate-400">Centralized Audit Log Retrieval (SuperAdmin)</td></tr>
+                    <tr class="bg-slate-900"><td class="px-6 py-4 font-bold text-yellow-400">POST</td><td class="px-6 py-4 font-mono text-slate-300">/management/tenant/assign</td><td class="px-6 py-4 text-slate-400">Dynamic Tenant DB Provisioning (SuperAdmin)</td></tr>
                 </tbody>
             </table>
         </div>
+    </section>
 
-        <!-- Distributed Caching -->
-        <div class="bg-gradient-to-r from-blue-500 to-indigo-600 rounded-2xl p-6 text-white text-sm shadow-lg">
-            <div class="flex items-start">
-                <div class="bg-white/20 p-2 rounded-lg mr-4">
-                    <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"></path></svg>
-                </div>
-                <div>
-                    <h4 class="font-bold mb-1">Distributed Redis Shield</h4>
-                    <p class="text-blue-50 leading-relaxed">
-                        Every <code class="bg-white/20 px-1 rounded">GetByID</code> request is automatically protected by a Redis cache layer. Mutations (Create/Update/Delete) trigger <strong>Automatic Cache Invalidation</strong> across the cluster, ensuring data consistency with zero effort.
-                    </p>
+    <!-- SILO NARROWING MASTERCLASS -->
+    <section class="mb-20">
+        <h2 class="text-3xl font-black text-slate-900 mb-8 tracking-tight italic underline decoration-blue-600 underline-offset-8">Silo Precision: Transactional Isolation</h2>
+        <div class="bg-slate-900 rounded-[3rem] p-12 text-white shadow-2xl relative overflow-hidden">
+            <div class="relative z-10">
+                <p class="text-lg text-slate-300 mb-8 leading-relaxed italic">
+                    While GO-DUCK defaults to global federation, sometimes you need surgical precision. Our <strong>Dual-Path Orchestrator</strong> is controlled by your headers.
+                </p>
+                
+                <div class="grid grid-cols-1 md:grid-cols-2 gap-8">
+                    <div class="p-8 bg-slate-800 rounded-3xl border border-white/10">
+                        <h4 class="text-blue-400 font-bold mb-4">Federal Broadcast (Default)</h4>
+                        <p class="text-xs text-slate-400 mb-4 font-mono uppercase tracking-widest font-black">Headers: Empty</p>
+                        <p class="text-sm text-slate-200">Writes synchronize to all silos. Reads aggregate data from the entire dealership empire into a single view.</p>
+                    </div>
+                    <div class="p-8 border-2 border-blue-500/50 bg-blue-600/10 rounded-3xl">
+                        <h4 class="text-green-400 font-bold mb-4">Silo Narrowing (Precision)</h4>
+                        <p class="text-xs text-green-400 mb-4 font-mono uppercase tracking-widest font-black">X-Tenant-ID: {Opaque-Silo-ID}</p>
+                        <p class="text-sm text-slate-200">Bypasses federation. Reads and writes are isolated to <strong>ONLY</strong> that specific silo. Perfect for site-specific audits or sensitive data entries.</p>
+                    </div>
                 </div>
             </div>
         </div>
-    </div>
-</section>
+    </section>
 
-<section class="mb-12">
-    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
-        <span class="w-8 h-8 rounded-lg bg-emerald-100 text-emerald-600 flex items-center justify-center mr-3 text-sm">
-            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path></svg>
-        </span>
-        Generic Search RPC Engine
-    </h2>
-    <p class="mb-6 text-slate-600 leading-relaxed text-sm">Accessed via <code class="bg-slate-100 px-1 py-0.5 rounded text-indigo-600 font-mono">/api/rpc/:tableName</code>, this engine provides a dynamic interface to your database.</p>
-    
-    <div class="grid grid-cols-1 md:grid-cols-2 gap-6 mb-8 text-sm">
-        <div class="bg-slate-900 rounded-2xl p-6 text-slate-300 font-mono text-xs overflow-x-auto">
-            <span class="text-emerald-400"># Complex query example</span><br>
-            curl -X GET "http://localhost:8080/api/rpc/articles?status=eq.PUBLISHED&views=gt.500&order=views.desc&limit=5"
-        </div>
-        <div class="bg-slate-50 border border-slate-200 rounded-2xl p-6">
-            <h5 class="text-slate-900 font-bold mb-3">Supported Operators</h5>
-            <div class="grid grid-cols-2 gap-2 text-[11px] font-mono">
-                <div class="flex justify-between border-b pb-1"><span>eq</span><span class="text-indigo-600">Equals</span></div>
-                <div class="flex justify-between border-b pb-1"><span>neq</span><span class="text-indigo-600">Not Equals</span></div>
-                <div class="flex justify-between border-b pb-1"><span>gt / gte</span><span class="text-indigo-600">Greater Than</span></div>
-                <div class="flex justify-between border-b pb-1"><span>lt / lte</span><span class="text-indigo-600">Less Than</span></div>
-                <div class="flex justify-between border-b pb-1"><span>like</span><span class="text-indigo-600">Search (%)</span></div>
-                <div class="flex justify-between border-b pb-1"><span>ilike</span><span class="text-indigo-600">Case-Insensitive</span></div>
-                <div class="flex justify-between border-b pb-1"><span>in</span><span class="text-indigo-600">List (1,2,3)</span></div>
+    <!-- BULK OPERATIONS -->
+    <section class="mb-20">
+        <h2 class="text-3xl font-black text-slate-900 mb-8 tracking-tight">Industrial Velocity: Bulk Operations</h2>
+        <div class="bg-indigo-900 rounded-[3rem] p-10 text-white shadow-2xl relative overflow-hidden">
+            <div class="absolute top-0 right-0 w-64 h-64 bg-indigo-500/20 blur-3xl -mr-32 -mt-32"></div>
+            <div class="relative z-10">
+                <p class="text-lg text-indigo-100 mb-8 leading-relaxed italic">
+                    For high-velocity data ingestion, GO-DUCK generates transaction-aware <strong>Bulk Endpoints</strong>. A single request can mutate thousands of records across your silos.
+                </p>
+                
+                <div class="grid grid-cols-1 md:grid-cols-2 gap-8">
+                    <div class="p-6 bg-slate-800 rounded-2xl border border-white/5">
+                        <h4 class="text-indigo-400 font-bold mb-2">Endpoint: POST /api/v1/{entity}/bulk</h4>
+                        <p class="text-xs text-slate-400 mb-4 font-mono font-black italic">Payload: Array of Objects</p>
+                        <pre class="bg-slate-900 p-4 rounded-xl text-xs text-indigo-300"><code>[
+  { "make": "Tesla", "model": "Model S" },
+  { "make": "Lucid", "model": "Air" }
+]</code></pre>
+                    </div>
+                    <div class="p-6 bg-slate-800 rounded-2xl border border-white/5">
+                        <h4 class="text-emerald-400 font-bold mb-2">Atomic & Federated</h4>
+                        <p class="text-sm text-slate-300">Bulk operations are wrapped in a database transaction. If one record fails validation or insertion, the entire batch is rolled back across all Silos.</p>
+                    </div>
+                </div>
             </div>
         </div>
-    </div>
+    </section>
 
-    <!-- JSON Querying Section -->
-    <div class="bg-white border border-slate-200 rounded-2xl p-8 shadow-sm">
-        <h4 class="text-xl font-bold text-slate-900 mb-4 flex items-center">
-            <svg class="w-6 h-6 mr-3 text-indigo-500" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4"></path></svg>
-            Deep JSON/JSONB Querying
-        </h4>
-        <p class="text-slate-600 text-sm mb-6 leading-relaxed">
-            The GO-DUCK generator natively supports PostgreSQL JSONB operators. You can drill down into nested fields directly from the URL using arrow notation.
-        </p>
-        
-        <div class="space-y-4">
-            <div class="bg-slate-50 p-5 rounded-xl border border-slate-100">
-                <div class="flex items-center justify-between mb-2">
-                    <span class="text-xs font-bold text-indigo-600 uppercase tracking-widest">Text Extraction (->>)</span>
-                    <span class="px-2 py-0.5 rounded bg-indigo-100 text-indigo-700 text-[10px] font-bold">Standard Use</span>
+    <!-- RELATIONSHIP LOADING -->
+    <section class="mb-20">
+        <h2 class="text-3xl font-black text-slate-900 mb-8 tracking-tight italic underline decoration-indigo-600 underline-offset-8">Relational Intelligence: Eager Loading</h2>
+        <div class="p-8 bg-slate-50 border border-slate-200 rounded-[2.5rem] shadow-sm">
+            <p class="text-slate-600 mb-6">By default, GO-DUCK uses <strong>Lazy Loading</strong> to keep responses lightweight. However, you can toggle relational graph expansion using our intelligent URI flags.</p>
+            
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-8">
+                <div class="p-6 bg-white rounded-2xl border border-slate-100 shadow-sm border-l-4 border-l-indigo-600">
+                    <h4 class="font-bold text-slate-900 mb-2">Eager Expansion (?eager=true)</h4>
+                    <p class="text-xs text-slate-500 mb-4">Recursively loads all 1:m and m:1 relationships defined in your GDL. Perfect for building complex dashboard views in a single call.</p>
+                    <code class="text-xs font-mono font-bold text-indigo-700 bg-indigo-50 px-3 py-1 rounded-full">GET /api/v1/car/1?eager=true</code>
                 </div>
-                <code class="text-xs text-slate-800">GET /api/rpc/users?metadata->>role=eq.ADMIN</code>
-                <p class="text-[11px] text-slate-500 mt-2">Extracts the value as text. Perfect for equality checks on nested strings.</p>
-            </div>
-
-            <div class="bg-slate-50 p-5 rounded-xl border border-slate-100">
-                <div class="flex items-center justify-between mb-2">
-                    <span class="text-xs font-bold text-purple-600 uppercase tracking-widest">Object Extraction (->)</span>
+                <div class="p-6 bg-white rounded-2xl border border-slate-100 shadow-sm border-l-4 border-l-slate-400">
+                    <h4 class="font-bold text-slate-900 mb-2">Lazy Defaults</h4>
+                    <p class="text-xs text-slate-500 mb-4">Returns only the primary entity fields. Relationships remain hydrated as IDs, reducing bandwidth and database overhead.</p>
+                    <code class="text-xs font-mono font-bold text-slate-700 bg-slate-100 px-3 py-1 rounded-full">GET /api/v1/car/1</code>
                 </div>
-                <code class="text-xs text-slate-800">GET /api/rpc/orders?details->itemsCount=gt.5</code>
-                <p class="text-[11px] text-slate-500 mt-2">Treats the extracted value as a JSON object/numeric, allowing for range checks on nested numbers.</p>
-            </div>
-        </div>
-
-        <div class="mt-6 p-4 bg-amber-50 rounded-xl border border-amber-100">
-            <p class="text-[11px] text-amber-800 leading-relaxed">
-                <strong>Pro Tip:</strong> For high-performance JSON querying, ensure you have a <code>GIN</code> index on the JSONB column in your database.
-            </p>
-        </div>
-    </div>
-</section>
-
-<section class="mb-12">
-    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
-        <span class="w-8 h-8 rounded-lg bg-orange-100 text-orange-600 flex items-center justify-center mr-3 text-sm">
-            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"></path></svg>
-        </span>
-        Bulk Mission Control (High Velocity)
-    </h2>
-    <p class="text-slate-600 text-sm mb-6 leading-relaxed">
-        For batch processing and migrations, avoid the overhead of multiple HTTP calls. Use the specialized <code class="bg-orange-50 px-1 rounded text-orange-700">/bulk</code> endpoints to process hundreds of records in a single transaction.
-    </p>
-
-    <div class="space-y-6">
-        <!-- Bulk Create -->
-        <div class="bg-white border border-slate-200 rounded-2xl overflow-hidden">
-            <div class="bg-slate-50 px-6 py-3 border-b border-slate-200 flex items-center justify-between">
-                <span class="text-[10px] font-bold text-slate-500 uppercase tracking-widest">Bulk Create Transaction</span>
-                <span class="px-2 py-0.5 rounded bg-emerald-100 text-emerald-700 text-[10px] font-bold">POST /api/:entities/bulk</span>
-            </div>
-            <div class="p-6">
-                <pre class="bg-slate-900 rounded-xl p-4 text-xs text-slate-300 font-mono">[
-  { "title": "Bulk Article A", "status": "DRAFT" },
-  { "title": "Bulk Article B", "status": "PUBLISHED" }
-]</pre>
             </div>
         </div>
+    </section>
 
-        <!-- Bulk Patch -->
-        <div class="bg-white border border-slate-200 rounded-2xl overflow-hidden">
-            <div class="bg-slate-50 px-6 py-3 border-b border-slate-200 flex items-center justify-between">
-                <span class="text-[10px] font-bold text-slate-500 uppercase tracking-widest">Multi-Entity Patch</span>
-                <span class="px-2 py-0.5 rounded bg-blue-100 text-blue-700 text-[10px] font-bold">PATCH /api/:entities/bulk</span>
-            </div>
-            <div class="p-6">
-                <pre class="bg-slate-900 rounded-xl p-4 text-xs text-slate-300 font-mono">[
-  { "id": 1, "changes": { "status": "ARCHIVED" } },
-  { "id": 2, "changes": { "title": "Updated Title via Bulk" } }
-]</pre>
-            </div>
+    <!-- RPC OPERATORS -->
+    <section class="mb-10 text-center">
+        <h2 class="text-2xl font-black text-slate-900 mb-6 italic italic underline decoration-indigo-200 underline-offset-8 decoration-8 font-serif uppercase tracking-widest">GORM Filter Reference</h2>
+        <div class="flex flex-wrap justify-center gap-2">
+            <span class="px-4 py-2 bg-slate-100 rounded-full text-xs font-mono font-bold text-indigo-700">eq. (Equals)</span>
+            <span class="px-4 py-2 bg-slate-100 rounded-full text-xs font-mono font-bold text-indigo-700">ne. (Not Equal)</span>
+            <span class="px-4 py-2 bg-slate-100 rounded-full text-xs font-mono font-bold text-indigo-700">gt. (Greater)</span>
+            <span class="px-4 py-2 bg-slate-100 rounded-full text-xs font-mono font-bold text-indigo-700">lt. (Lesser)</span>
+            <span class="px-4 py-2 bg-slate-100 rounded-full text-xs font-mono font-bold text-indigo-700">like. (%)</span>
+            <span class="px-4 py-2 bg-slate-100 rounded-full text-xs font-mono font-bold text-indigo-700">in. (A,B,C)</span>
+            <span class="px-4 py-2 bg-slate-100 rounded-full text-xs font-mono font-bold text-indigo-700">is. (null)</span>
         </div>
-    </div>
-</section>
-
-<section class="mb-12">
-    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
-        <span class="w-8 h-8 rounded-lg bg-rose-100 text-rose-600 flex items-center justify-center mr-3 text-sm">
-            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"></path></svg>
-        </span>
-        Security & Context
-    </h2>
-    <div class="bg-rose-50 border border-rose-100 rounded-2xl p-6 flex items-start">
-        <div class="bg-rose-100 p-2 rounded-lg mr-4">
-            <svg class="w-6 h-6 text-rose-600" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"></path></svg>
-        </div>
-        <div>
-            <h4 class="font-bold text-rose-900 mb-1">Mandatory Headers</h4>
-            <p class="text-rose-700 text-sm leading-relaxed mb-4">Every Go-Duck API request must satisfy the Identity and Multi-Tenancy gatekeepers.</p>
-            <ul class="space-y-2 text-xs font-mono text-rose-800">
-                <li><span class="font-bold">Authorization:</span> Bearer &lt;Keycloak_JWT&gt;</li>
-                <li><span class="font-bold">X-Tenant-ID:</span> Subdomain or ID of the tenant dashboard</li>
-            </ul>
-        </div>
-    </div>
-</section>
+    </section>
+</div>

package/templates/docs/pages/saga.hbs

@@ -0,0 +1,94 @@
+<div class="prose prose-slate max-w-none">
+    <div class="flex items-center space-x-3 mb-8">
+        <div class="p-3 bg-red-100 rounded-xl">
+            <svg class="w-8 h-8 text-red-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z" />
+            </svg>
+        </div>
+        <h1 class="text-4xl font-bold text-slate-900 m-0">Distributed Saga & Outbox</h1>
+    </div>
+
+    <p class="text-xl text-slate-600 mb-12">
+        Maintain 100% data consistency across federated database silos, even during network failures, using the Transactional Outbox pattern.
+    </p>
+
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-8 mb-16">
+        <div class="bg-white p-8 rounded-2xl shadow-sm border border-slate-200">
+            <h3 class="text-xl font-bold mb-4 flex items-center text-slate-800">
+                <span class="w-8 h-8 bg-slate-100 rounded-full flex items-center justify-center text-sm mr-3">01</span>
+                Atomic Persistence
+            </h3>
+            <p class="text-slate-600">
+                When a mutation occurs (Create/Update/Delete), the primary silo transaction atomatically persists both the entity and a "Pending Task" in the <code>distributed_outbox</code> table.
+            </p>
+        </div>
+            <div class="p-8 bg-slate-100 rounded-3xl border border-slate-200">
+                <h4 class="font-bold text-slate-800 mb-2 font-mono flex items-center">
+                    <span class="w-2 h-2 rounded-full bg-blue-500 mr-2"></span>
+                    NATS Streaming (CQRS)
+                </h4>
+                <p class="text-xs text-slate-600 mb-4 font-mono font-black italic">Subject Pattern: go.duck.events.{entity}.{action}</p>
+                <p class="text-sm text-slate-700 leading-relaxed">High-performance internal messaging bridge. Supports <strong>wildcard subscriptions</strong> (e.g., <code>go.duck.events.article.*</code>) for ultra-fast, decoupled service-to-service orchestration.</p>
+            </div>
+        </div>
+
+        <div class="mt-8 p-10 bg-slate-900 rounded-[2.5rem] border border-white/5 shadow-2xl relative overflow-hidden">
+            <div class="relative z-10">
+                <h3 class="text-2xl font-black text-white mb-6 tracking-tight italic">NATS Performance & CQRS</h3>
+                <p class="text-slate-400 text-sm leading-relaxed mb-8">NATS acts as the nervous system for your microservice. While MQTT is optimized for UI/WebSockets, NATS provides the dot-separated power needed for enterprise message routing.</p>
+                
+                <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+                    <div class="p-4 bg-white/5 rounded-xl border border-white/10 italic text-xs text-slate-300">
+                        <span class="text-blue-400 font-bold block mb-1">Subject Strategy</span>
+                        Dot-separated subjects for hierarchical routing and filtering.
+                    </div>
+                    <div class="p-4 bg-white/5 rounded-xl border border-white/10 italic text-xs text-slate-300">
+                        <span class="text-blue-400 font-bold block mb-1">CQRS Evolution</span>
+                        Easily separate Reads and Writes by listening to NATS events for cache invalidation.
+                    </div>
+                </div>
+            </div>
+        </div>
+    </section>
+
+    <section class="mb-16">
+        <h2 class="text-3xl font-bold text-slate-900 mb-6">How it Works</h2>
+        <div class="bg-slate-900 rounded-3xl p-8 overflow-hidden shadow-2xl">
+            <pre class="text-blue-300 font-mono text-sm leading-relaxed">
+# The Saga Workflow
+1. Client sends POST /cars (Federated Entity)
+2. Controller opens transaction on Master Silo
+3. Local Car record is saved
+4. "PROPAGATE_CREATE" task is saved to `distributed_outbox`
+5. Transaction COMMIT
+6. OutboxWorker picks up the task
+7. OutboxWorker broadcasts to Silo B, C, D...
+8. On Success, task is marked "COMPLETED"
+            </pre>
+        </div>
+    </section>
+
+    <section class="mb-16">
+        <h2 class="text-3xl font-bold text-slate-900 mb-6">Outbox Schema</h2>
+        <p class="text-slate-600 mb-6">
+            Every silo in your infrastructure includes this safety net automatically:
+        </p>
+        <div class="overflow-x-auto rounded-xl border border-slate-200">
+            <table class="min-w-full divide-y divide-slate-200">
+                <thead class="bg-slate-50">
+                    <tr>
+                        <th class="px-6 py-4 text-left text-xs font-semibold text-slate-500 uppercase tracking-wider">Field</th>
+                        <th class="px-6 py-4 text-left text-xs font-semibold text-slate-500 uppercase tracking-wider">Type</th>
+                        <th class="px-6 py-4 text-left text-xs font-semibold text-slate-500 uppercase tracking-wider">Description</th>
+                    </tr>
+                </thead>
+                <tbody class="bg-white divide-y divide-slate-200">
+                    <tr><td class="px-6 py-4 font-mono text-sm text-indigo-600">event_type</td><td class="px-6 py-4 text-sm">String</td><td class="px-6 py-4 text-sm">CREATE, UPDATE, DELETE, BULK_...</td></tr>
+                    <tr><td class="px-6 py-4 font-mono text-sm text-indigo-600">payload</td><td class="px-6 py-4 text-sm">JSONB</td><td class="px-6 py-4 text-sm">The delta or entity data</td></tr>
+                    <tr><td class="px-6 py-4 font-mono text-sm text-indigo-600">status</td><td class="px-6 py-4 text-sm">String</td><td class="px-6 py-4 text-sm">PENDING, COMPLETED, FAILED</td></tr>
+                    <tr><td class="px-6 py-4 font-mono text-sm text-indigo-600">retry_count</td><td class="px-6 py-4 text-sm">Int</td><td class="px-6 py-4 text-sm">Exponential backoff tracking</td></tr>
+                </tbody>
+            </table>
+        </div>
+    </section>
+</div>