go-duck-cli 1.0.0

package/templates/docs/pages/cli.hbs

@@ -0,0 +1,83 @@
+<div class="mb-10 border-b border-slate-200 pb-8">
+    <div class="inline-flex items-center px-3 py-1 rounded-full bg-slate-200 text-slate-700 text-xs font-semibold tracking-wide uppercase mb-4">
+        Generator Engine
+    </div>
+    <h1 class="text-4xl lg:text-5xl font-extrabold text-slate-900 tracking-tight leading-tight mb-4">CLI Usage & Evolution</h1>
+    <p class="text-lg lg:text-xl text-slate-600 max-w-2xl leading-relaxed">How to safely use the GO-DUCK Generator without destroying your manual Go code edits over time.</p>
+</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="M8 9l3 3-3 3m5 0h3M5 20h14a2 2 0 002-2V6a2 2 0 00-2-2H5a2 2 0 00-2 2v12a2 2 0 002 2z"></path></svg>
+        </span>
+        1. The Command Pipeline
+    </h2>
+    <p class="mb-6 text-slate-600 leading-relaxed">The GO-DUCK-CLI operates on basically two commands. The initialization of your system, and the continuous evolution pipeline.</p>
+    
+    <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-lg mb-4">
+        <div class="bg-[#2d2d2d] px-4 py-2 border-b border-[#404040] flex items-center justify-between">
+            <div class="flex items-center">
+                <div class="flex space-x-1.5 mr-4">
+                    <div class="w-3 h-3 rounded-full bg-rose-500"></div>
+                    <div class="w-3 h-3 rounded-full bg-amber-500"></div>
+                    <div class="w-3 h-3 rounded-full bg-emerald-500"></div>
+                </div>
+                <span class="text-xs text-slate-300 font-mono">Terminal</span>
+            </div>
+            <span class="text-[10px] text-slate-400 font-bold uppercase tracking-widest">Bash</span>
+        </div>
+        <div class="p-5 overflow-x-auto text-sm">
+<pre><code class="language-bash"># Command 1: Fresh Creation
+# Scaffold an entirely new ecosystem. This generates ALL baseline infrastructure.
+go-duck create -o ./MY_APP -c config.yaml -g initial_schema.gdl
+
+# Command 2: Incremental Stateful Update
+# Used whenever you modify your GDL (add an entity, drop a column, add a link)
+go-duck import-gdl my_new_schema.gdl -o ./MY_APP</code></pre>
+        </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-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="M8 7v8a2 2 0 002 2h6M8 7V5a2 2 0 012-2h4.586a1 1 0 01.707.293l4.414 4.414a1 1 0 01.293.707V15a2 2 0 01-2 2h-2M8 7H6a2 2 0 00-2 2v10a2 2 0 002 2h8a2 2 0 002-2v-2"></path></svg>
+        </span>
+        2. Persistence Intelligence & the `.go-duck/` Folder
+    </h2>
+    <p class="mb-4 text-slate-600 leading-relaxed font-medium">"If I run the generator twice, will it overwrite my database migrations?" <strong>No.</strong></p>
+    
+    <p class="mb-6 text-slate-600 leading-relaxed">The generator maintains a stateful snapshot of every entity it has ever generated inside the hidden <code class="bg-slate-100 px-1 py-0.5 rounded text-slate-800 font-mono text-sm">.go-duck/</code> directory at the root of your target project. When you run <code>import-gdl</code>, the code parser literally diffs your new file against the JSON representations in <code>.go-duck/</code> to intelligently assess the exact Table changes necessary without executing ghost migrations.</p>
+
+    <div class="bg-rose-50 border border-rose-200 p-5 mb-6 rounded-xl flex items-start shadow-sm shadow-rose-100/50">
+        <svg class="w-6 h-6 text-rose-500 mt-0.5 mr-3 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path></svg>
+        <div>
+            <h4 class="font-bold text-rose-900 mb-1">Warning</h4>
+            <p class="text-rose-800 text-sm leading-relaxed"><strong>Never delete `.go-duck/`</strong> unless you are intentionally wiping the database and starting configuration completely from zero.</p>
+        </div>
+    </div>
+</section>
+
+<section class="mb-10">
+    <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.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1"></path></svg>
+        </span>
+        3. JHipster-Style "Needles" (Safe Code Injection)
+    </h2>
+    <p class="mb-4 text-slate-600 leading-relaxed font-medium">"If I write custom endpoints in `main.go`, will running the generator wipe them out?" <strong class="text-indigo-600">No, as long as you use Needles!</strong></p>
+    
+    <p class="mb-4 text-slate-600 leading-relaxed">The generator utilizes carefully placed specific comments called "needles". For example, inside <code>main.go</code>, you will see markers exactly like <code class="bg-slate-100 px-1 py-0.5 rounded text-slate-800 font-mono text-sm">// go-duck-needle-add-init-server</code>.</p>
+    
+    <p class="mb-8 text-slate-600 leading-relaxed">When the generator runs an incremental update, it doesn't arbitrarily overwrite <code>main.go</code> via a template. It opens the <em>existing</em> compiled <code>main.go</code> file on your machine, locates the Needle anchor point via REGEX, and safely inserts the new syntax directly below it.</p>
+
+    <div class="bg-white border text-sm border-slate-200 rounded-xl overflow-hidden shadow-sm">
+        <div class="px-5 py-3 border-b border-slate-100 bg-slate-50 font-bold text-slate-700">Active Go Needle Locations (DO NOT DELETE)</div>
+        <ul class="divide-y divide-slate-100 font-mono text-slate-600">
+            <li class="px-5 py-3 flex items-center"><svg class="w-4 h-4 text-indigo-400 mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7"></path></svg>// go-duck-needle-add-import (main.go)</li>
+            <li class="px-5 py-3 flex items-center"><svg class="w-4 h-4 text-indigo-400 mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7"></path></svg>// go-duck-needle-add-init-repository (main.go)</li>
+            <li class="px-5 py-3 flex items-center"><svg class="w-4 h-4 text-indigo-400 mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7"></path></svg>// go-duck-needle-add-grpc-service (internal/server/grpc.go)</li>
+        </ul>
+    </div>
+</section>

package/templates/docs/pages/gdl.hbs

@@ -0,0 +1,223 @@
+<div class="mb-10 text-center lg:text-left border-b border-slate-200 pb-8">
+    <div class="inline-flex items-center px-3 py-1 rounded-full bg-emerald-100 text-emerald-700 text-xs font-semibold tracking-wide uppercase mb-4">
+        Domain Driven Design
+    </div>
+    <h1 class="text-4xl lg:text-5xl font-extrabold text-slate-900 tracking-tight leading-tight mb-4">GDL (Go-Duck Language)</h1>
+    <p class="text-lg lg:text-xl text-slate-600 max-w-2xl leading-relaxed">The standard DSL for generating your massive suite of code from a simple text file.</p>
+</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-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="M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4"></path></svg>
+        </span>
+        GDL Syntax & Structure
+    </h2>
+    <p class="mb-6 text-slate-600 leading-relaxed">GDL allows you to define your core business entities and the relationships between them. It looks and acts slightly similarly to JHipster's JDL.</p>
+
+    <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-lg mb-4">
+        <div class="bg-[#2d2d2d] px-4 py-2 border-b border-[#404040] flex items-center justify-between">
+            <div class="flex items-center">
+                <div class="flex space-x-1.5 mr-4">
+                    <div class="w-3 h-3 rounded-full bg-rose-500"></div>
+                    <div class="w-3 h-3 rounded-full bg-amber-500"></div>
+                    <div class="w-3 h-3 rounded-full bg-emerald-500"></div>
+                </div>
+                <span class="text-xs text-slate-300 font-mono">schema.gdl</span>
+            </div>
+        </div>
+        <div class="p-5 overflow-x-auto text-sm">
+<pre><code class="language-plaintext">@Audited 
+entity Article {
+  title String required unique
+  content Text required
+  status ArticleStatus required
+  publishedDate LocalDate
+  views Integer
+  metadata JSONB
+}
+
+enum ArticleStatus {
+  DRAFT, PUBLISHED, ARCHIVED
+}
+
+entity Author {
+  name String required
+  biography Text
+  settings JSON
+}
+
+relationship OneToMany {
+  Author{article} to Article{author} required
+}</code></pre>
+        </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-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 7v10c0 2.21 3.582 4 8 4s8-1.79 8-4V7M4 7c0 2.21 3.582 4 8 4s8-1.79 8-4M4 7c0-2.21 3.582-4 8-4s8 1.79 8 4m0 5c0 2.21-3.582 4-8 4s-8-1.79-8-4"></path></svg>
+        </span>
+        Supported Data Types
+    </h2>
+    <div class="overflow-x-auto rounded-xl border border-slate-200">
+        <table class="min-w-full text-left bg-white">
+            <thead>
+                <tr class="bg-slate-50 border-b border-slate-200 text-slate-500 uppercase text-xs tracking-wider">
+                    <th class="p-4 font-semibold">GDL Type</th>
+                    <th class="p-4 font-semibold">Go Struct Type</th>
+                    <th class="p-4 font-semibold">Postgres / SQL Type</th>
+                    <th class="p-4 font-semibold">GraphQL / Proto</th>
+                </tr>
+            </thead>
+            <tbody class="text-sm text-slate-700 divide-y divide-slate-100">
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">String</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">string</code></td><td class="p-4">VARCHAR(255)</td><td class="p-4">String / string</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">String(N)</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">string</code></td><td class="p-4">VARCHAR(N)</td><td class="p-4">String / string</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">Text</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">string</code></td><td class="p-4">TEXT</td><td class="p-4">String / string</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">JSON</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">datatypes.JSON</code></td><td class="p-4 text-emerald-600 font-semibold">JSON</td><td class="p-4">String / string</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">JSONB</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">datatypes.JSON</code></td><td class="p-4 text-emerald-600 font-semibold">JSONB</td><td class="p-4">String / string</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">Integer</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">int</code></td><td class="p-4">INT</td><td class="p-4">Int / int32</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">Long</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">int64</code></td><td class="p-4">BIGINT</td><td class="p-4">ID / int64</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">Float</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">float64</code></td><td class="p-4">DECIMAL</td><td class="p-4">Float / float32</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">BigDecimal</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">float64</code></td><td class="p-4">DECIMAL</td><td class="p-4">Float / double</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">Boolean</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">bool</code></td><td class="p-4">BOOLEAN</td><td class="p-4">Boolean / bool</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">LocalDate</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">time.Time</code></td><td class="p-4">DATE</td><td class="p-4">String / string</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">Instant</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">time.Time</code></td><td class="p-4">TIMESTAMP</td><td class="p-4">String / string</td></tr>
+                <tr class="hover:bg-slate-50 transition-colors"><td class="p-4 font-semibold font-mono text-indigo-600">Enum</td><td class="p-4"><code class="bg-slate-100 px-1 py-0.5 rounded text-xs text-slate-800">CustomType</code></td><td class="p-4">VARCHAR(50)</td><td class="p-4">String / string</td></tr>
+            </tbody>
+        </table>
+    </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-pink-100 text-pink-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>
+        Enumerations
+    </h2>
+    <p class="mb-6 text-slate-600 leading-relaxed">GDL supports custom Enum types for fields that have a predefined set of allowed values. Enums are generated as Go types with constants and mapped to safe string columns in the database.</p>
+    
+    <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-lg">
+        <div class="p-5 overflow-x-auto text-sm text-slate-300">
+<pre><code class="language-plaintext">enum Language {
+  ENGLISH, FRENCH, GERMAN
+}
+
+entity Person {
+  name String required
+  nativeLanguage Language
+}</code></pre>
+        </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-teal-100 text-teal-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="M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z"></path></svg>
+        </span>
+        Modifiers & Annotations
+    </h2>
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-5 mb-8">
+        <div class="p-5 rounded-2xl border border-slate-200 bg-white">
+            <h3 class="font-bold text-slate-900 mb-2 font-mono text-indigo-600">required</h3>
+            <p class="text-sm text-slate-600 leading-relaxed">Forces the field to be NOT NULL in the database, missing fields are blocked by the Gin validator natively.</p>
+        </div>
+        <div class="p-5 rounded-2xl border border-slate-200 bg-white">
+            <h3 class="font-bold text-slate-900 mb-2 font-mono text-indigo-600">unique</h3>
+            <p class="text-sm text-slate-600 leading-relaxed">Adds a standard UNIQUE constraint indexing configuration at the database level.</p>
+        </div>
+    </div>
+    <div class="p-6 rounded-2xl border border-rose-200 bg-rose-50/50">
+        <h3 class="font-bold text-rose-900 mb-2 font-mono drop-shadow-sm">@Audited</h3>
+        <p class="text-sm text-rose-800 leading-relaxed">An entity annotation that completely re-wires the structural behavior of the model. Standard <code class="bg-rose-100 px-1 py-0.5 rounded text-rose-900">created_at</code> triggers are bypassed and 5 highly-detailed audit columns are injected: <code>created_by, created_date, last_modified_by, last_modified_date, last_modified_user_id</code>. All changes are captured implicitly by the JWT middleware.</p>
+    </div>
+</section>
+
+<section class="mb-10">
+    <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="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>
+        </span>
+        Incremental Migration Engine
+    </h2>
+    <p class="mb-4 text-slate-600 leading-relaxed">Running <code class="bg-slate-100 px-1 py-0.5 rounded text-slate-800 font-mono text-sm">go-duck import-gdl app.gdl</code> compares your GDL file against the physical <code>.go-duck/</code> snapshot state securely stored in the repo.</p>
+    <p class="mb-6 text-slate-600 leading-relaxed">It detects exactly what changed (such as removing a field, changing field types, adding new nested JSON) and generates precise atomic standard Liquibase XML <code>migrations/liquibase/changelogs/</code> scripts to evolve the live database safely without destroying data.</p>
+    
+    <div class="bg-blue-50/80 border border-blue-200 p-5 rounded-xl flex items-start shadow-sm">
+        <svg class="w-6 h-6 text-blue-500 mt-0.5 mr-3 flex-shrink-0" 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>
+            <h4 class="font-semibold text-blue-900 mb-1">Golden Rule</h4>
+            <p class="text-blue-800 text-sm leading-relaxed mb-2">Avoid editing Liquibase XML manually unless correcting an anomaly. Let the GDL manage your migrations.</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-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="M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4"></path></svg>
+        </span>
+        Managing Relationships
+    </h2>
+    <p class="mb-6 text-slate-600 leading-relaxed">Relationships in GDL define how entities connect at the database level (foreign keys) and how they are represented in Go structs and GraphQL schemas. Just like JHipster, we support four primary types.</p>
+
+    <!-- One-to-Many -->
+    <div class="mb-8">
+        <h3 class="text-xl font-semibold text-slate-800 mb-4 flex items-center">
+            One-to-Many
+            <span class="ml-3 px-2 py-0.5 rounded bg-blue-100 text-blue-700 text-xs font-bold uppercase tracking-wider">Most Common</span>
+        </h3>
+        <p class="text-slate-600 mb-4 text-sm bg-slate-50 p-3 border-l-4 border-blue-400 rounded-r-lg">Example: An <code class="font-bold">Author</code> has many <code class="font-bold">Articles</code>.</p>
+        <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-lg">
+            <div class="p-4 overflow-x-auto text-sm">
+<pre><code class="language-plaintext">relationship OneToMany {
+  Author{article} to Article{author}
+}</code></pre>
+            </div>
+        </div>
+        <p class="mt-4 text-sm text-slate-500 italic">This generates a <code>author_id</code> foreign key in the <code>article</code> table and a slice of Articles in the Author struct.</p>
+    </div>
+
+    <!-- Many-to-One -->
+    <div class="mb-8">
+        <h3 class="text-xl font-semibold text-slate-800 mb-4">Many-to-One</h3>
+        <p class="text-slate-600 mb-4 text-sm bg-slate-50 p-3 border-l-4 border-slate-300 rounded-r-lg">Essentially the inverse of One-to-Many, used to specify the owner side explicitly.</p>
+        <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-lg">
+            <div class="p-4 overflow-x-auto text-sm">
+<pre><code class="language-plaintext">relationship ManyToOne {
+  Article{author} to Author
+}</code></pre>
+            </div>
+        </div>
+    </div>
+
+    <!-- One-to-One -->
+    <div class="mb-8">
+        <h3 class="text-xl font-semibold text-slate-800 mb-4">One-to-One</h3>
+        <p class="text-slate-600 mb-4 text-sm bg-slate-50 p-3 border-l-4 border-indigo-400 rounded-r-lg">Example: A <code class="font-bold">User</code> has exactly one <code class="font-bold">Profile</code>.</p>
+        <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-lg">
+            <div class="p-4 overflow-x-auto text-sm">
+<pre><code class="language-plaintext">relationship OneToOne {
+  User{profile} to Profile{user}
+}</code></pre>
+            </div>
+        </div>
+    </div>
+
+    <!-- Many-to-Many -->
+    <div class="mb-8">
+        <h3 class="text-xl font-semibold text-slate-800 mb-4">Many-to-Many</h3>
+        <p class="text-slate-600 mb-4 text-sm bg-slate-50 p-3 border-l-4 border-purple-400 rounded-r-lg">Example: <code class="font-bold">Students</code> enrolled in many <code class="font-bold">Courses</code>.</p>
+        <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-lg">
+            <div class="p-4 overflow-x-auto text-sm">
+<pre><code class="language-plaintext">relationship ManyToMany {
+  Student{course} to Course{student}
+}</code></pre>
+            </div>
+        </div>
+        <p class="mt-4 text-sm text-slate-500 italic">This triggers the automatic generation of a join table (e.g., <code>student_course</code>) in Liquibase.</p>
+    </div>
+</section>

package/templates/docs/pages/graphql.hbs

@@ -0,0 +1,51 @@
+<h1 class="text-4xl font-extrabold text-gray-900 mb-4">GraphQL Integration</h1>
+<p class="text-lg text-gray-600 mb-8">Access all generated GDL entities through a single unified endpoint with high-efficiency queries.</p>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Single Unified Endpoint</h2>
+    <p class="mb-4">Rather than relying entirely on REST endpoints, your application supports GraphQL via <code>POST /graphql</code>.</p>
+    
+    <div class="bg-indigo-50 border-l-4 border-indigo-500 p-4 mb-6 rounded-r">
+        <p class="text-indigo-900"><strong>Note:</strong> Just like REST, GraphQL requires standard Keycloak JWT headers to be attached to queries and mutations!</p>
+    </div>
+
+    <pre><code class="language-graphql"># Example: Querying Multiple Data Models (GORM Relational Mapping Handles JOINs)
+query {
+  get{{capitalize (defaultStr (lookup entities "0.name") "Entity")}}(id: 1) {
+    id
+    {{#if entities.length}}
+      {{#if entities.[0].fields.length}}
+        {{entities.[0].fields.[0].name}}
+      {{/if}}
+    {{/if}}
+  }
+}</code></pre>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Working with Frontend Libraries</h2>
+    <p class="mb-4">Here is how to seamlessly execute your generated queries inside modern JavaScript frameworks using <code>fetch</code>.</p>
+    
+    <pre><code class="language-javascript">const fetchEntity = async () => {
+  const query = \`
+    query {
+      list{{capitalize (defaultStr (lookup entities "0.name") "Entity")}}s(page: 1, size: 5) {
+        id
+        {{#if entities.length}}{{#if entities.[0].fields.length}}{{entities.[0].fields.[0].name}}{{/if}}{{/if}}
+      }
+    }
+  \`;
+
+  const response = await fetch('http://localhost:8080/graphql', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': 'Bearer YOUR_JWT'
+    },
+    body: JSON.stringify({ query })
+  });
+  
+  const { data } = await response.json();
+  console.log('Result array:', data);
+};</code></pre>
+</section>

package/templates/docs/pages/grpc.hbs

@@ -0,0 +1,100 @@
+<div class="mb-10 border-b border-slate-200 pb-8">
+    <div class="inline-flex items-center px-3 py-1 rounded-full bg-rose-100 text-rose-700 text-xs font-semibold tracking-wide uppercase mb-4">
+        Protocol Buffer APIs
+    </div>
+    <h1 class="text-4xl font-extrabold text-slate-900 tracking-tight mb-4">Secured Kratos gRPC APIs</h1>
+    <p class="text-lg text-slate-600">Access the generated microservices over ultra-fast gRPC using Kratos framework, fully authenticated by Keycloak.</p>
+</div>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
+        <span class="w-8 h-8 rounded-lg bg-slate-100 text-slate-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>
+        Overview
+    </h2>
+    <p class="mb-4 text-slate-600 leading-relaxed">The GO-DUCK CLI generated app binds the Gin REST webserver on port 8080 and simultaneously spins up an optimized <strong>Go-Kratos</strong> gRPC listener on <code class="bg-slate-100 px-1.5 py-0.5 rounded text-slate-800 font-mono text-sm">port 9000</code>. Both the REST and gRPC handlers share the exact same clean <code>Repository</code> architecture underneath, guaranteeing 100% data and logic consistency.</p>
+    
+    <div class="bg-emerald-50/80 border border-emerald-200 p-5 mt-6 rounded-xl flex items-start shadow-sm">
+        <svg class="w-6 h-6 text-emerald-500 mt-0.5 mr-3 flex-shrink-0" 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>
+            <h4 class="font-semibold text-emerald-900 mb-1">Automatic Compilation</h4>
+            <p class="text-emerald-800 text-sm leading-relaxed"><code class="bg-emerald-100 text-emerald-900 px-1 py-0.5 rounded">api/v1/*.proto</code> definitions are generated automatically whenever you add an entity or change fields.</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-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="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"></path></svg>
+        </span>
+        Client Connection Example (Go)
+    </h2>
+    <p class="mb-6 text-slate-600 leading-relaxed">This snippet demonstrates how a developer orchestrating another microservice connects securely using Google's <code class="bg-slate-100 px-1.5 py-0.5 rounded text-slate-800 font-mono text-sm">clientcredentials</code> to fulfill the Kratos Auth Header standards.</p>
+    
+    <div class="bg-blue-50/80 border border-blue-200 p-5 mt-6 mb-6 rounded-xl flex items-start shadow-sm">
+        <svg class="w-6 h-6 text-blue-500 mt-0.5 mr-3 flex-shrink-0" 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>
+            <h4 class="font-semibold text-blue-900 mb-1">Crucial Architecture Note (Server-to-Server)</h4>
+            <p class="text-blue-800 text-sm leading-relaxed mb-2">If an event triggers a gRPC call asynchronously in the background (meaning there is NO active human user pushing a token from a frontend), the calling microservice must authenticate itself using a <strong>Keycloak Service Account</strong>.</p>
+            <p class="text-blue-800 text-sm leading-relaxed">The calling server sends its own <code class="bg-blue-100 px-1 py-0.5 rounded">Client ID</code> and <code class="bg-blue-100 px-1 py-0.5 rounded">Client Secret</code> directly to Keycloak's Token Endpoint using the <strong>Client Credentials Grant</strong> flow. Keycloak responds with a valid JWT representing the "Server", which is then injected into the gRPC dialer below.</p>
+        </div>
+    </div>
+    
+    <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-xl mb-4">
+        <div class="bg-[#2d2d2d] px-4 py-2 border-b border-[#404040] flex items-center justify-between">
+            <div class="flex items-center">
+                <div class="flex space-x-1.5 mr-4">
+                    <div class="w-3 h-3 rounded-full bg-rose-500"></div>
+                    <div class="w-3 h-3 rounded-full bg-amber-500"></div>
+                    <div class="w-3 h-3 rounded-full bg-emerald-500"></div>
+                </div>
+                <span class="text-xs text-slate-300 font-mono">grpc_client.go</span>
+            </div>
+            <span class="text-[10px] text-slate-400 font-bold uppercase tracking-widest">Go</span>
+        </div>
+        <div class="p-5 overflow-x-auto text-sm">
+<pre><code class="language-go">import (
+    "context"
+    "log"
+    "google.golang.org/grpc"
+    "golang.org/x/oauth2/clientcredentials"
+    pb "{{appName}}/api/v1"
+)
+
+func main() {
+    // 1. Configure the Client Credentials Flow
+    // These values should match your go-duck.security block in application-dev.yml
+    config := clientcredentials.Config{
+        ClientID:     "internal",       // Matches keycloak-client-id
+        ClientSecret: "internal",       // Matches keycloak-secret
+        TokenURL:     "http://localhost:9080/realms/master/protocol/openid-connect/token",
+    }
+
+    // 2. Fetch the token dynamically from Keycloak
+    tokenSource := config.TokenSource(context.Background())
+
+    // 3. Dial the local port 9000 (GoDuck Server)
+    // grpc.WithPerRPCCredentials injects the automatically updating token into every request!
+    conn, err := grpc.Dial("localhost:9000", grpc.WithInsecure(), grpc.WithPerRPCCredentials(tokenSource))
+    if err != nil {
+        log.Fatalf("did not connect: %v", err)
+    }
+    defer conn.Close()
+
+    // 4. Initialize the Kratos-generated gRPC Client
+    client := pb.New{{capitalize (defaultStr (lookup entities "0.name") "Entity")}}ServiceClient(conn)
+
+    // 5. Execute Native Network Call over gRPC
+    res, err := client.Get{{capitalize (defaultStr (lookup entities "0.name") "Entity")}}(context.Background(), &pb.Get{{capitalize (defaultStr (lookup entities "0.name") "Entity")}}Request{Id: 1})
+    if err != nil {
+        log.Fatalf("RPC failed: %v", err)
+    }
+    
+    log.Printf("Successfully Received Data Pipeline Object OVER gRPC: %v", res)
+}
+</code></pre>
+        </div>
+    </div>
+</section>