✨ Enhance docs with WOW features: cover page, diagrams, alerts, and interactive elements

- Add stunning cyberpunk cover page with animated grid background
- Integrate Mermaid diagrams for visual architecture and flow charts
- Add flexible-alerts for tips, warnings, and notes throughout tutorials
- Enhance index.html with 15+ professional plugins (tabs, progress bar, charts)
- Add sequence diagrams for authentication and analytics flows
- Improve readability with visual callouts and interactive elements
- Add graph visualizations for system architecture
- Better UX with keyboard shortcuts, word count, and edit links

docs/ARCHITECTURE_OVERVIEW.md

@@ -8,23 +8,39 @@ Complete technical architecture of the AeThex Engine ecosystem.
 
 AeThex is a complete game development platform consisting of three core components:
 
-```
+```mermaid
-┌────────────────────────────────────────────────────────────────┐
+graph TB
-│                    AeThex Platform                              │
+    subgraph Platform["⚡ AeThex Platform"]
-├────────────────────────────────────────────────────────────────┤
+        subgraph Engine["AeThex Engine<br/>(C++/GDScript)"]
-│                                                                 │
+            E1[Game Runtime]
-│  ┌─────────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+            E2[Editor]
-│  │  AeThex Engine  │  │  Studio IDE  │  │ Cloud Services   │  │
+            E3[Cloud SDK]
-│  │                 │  │              │  │                  │  │
+            E4[AI Module]
-│  │  • Game Runtime │  │  • Browser   │  │  • Auth          │  │
+        end
-│  │  • Editor       │  │  • Collab    │  │  • Multiplayer   │  │
+        
-│  │  • Cloud SDK    │  │  • Live View │  │  • Saves         │  │
+        subgraph Studio["Studio IDE<br/>(TypeScript/React)"]
-│  │  • AI Module    │  │  • Assets    │  │  • Analytics     │  │
+            S1[Browser-Based]
-│  └─────────────────┘  └──────────────┘  └──────────────────┘  │
+            S2[Collaboration]
-│          ↕                   ↕                    ↕            │
+            S3[Live Preview]
-│       C++/GDScript      TypeScript/React       Node.js/Go      │
+            S4[Asset Manager]
-│                                                                 │
+        end
-└────────────────────────────────────────────────────────────────┘
+        
+        subgraph Cloud["Cloud Services<br/>(Node.js/Go)"]
+            C1[Authentication]
+            C2[Multiplayer]
+            C3[Cloud Saves]
+            C4[Analytics]
+        end
+    end
+    
+    Engine <-->|WebSocket/HTTP| Studio
+    Engine <-->|REST API| Cloud
+    Studio <-->|API Gateway| Cloud
+    
+    style Engine fill:#00ffff22,stroke:#00ffff,stroke-width:2px
+    style Studio fill:#ff00ff22,stroke:#ff00ff,stroke-width:2px
+    style Cloud fill:#00ffff22,stroke:#00ffff,stroke-width:2px
+    style Platform fill:#00000000,stroke:#ffffff,stroke-width:1px
 ```
 
 ---
@@ -33,21 +49,46 @@ AeThex is a complete game development platform consisting of three core componen
 
 Based on Godot Engine 4.3-stable with AeThex-specific modules.
 
+> [!NOTE]
+> The engine core is written in C++ with GDScript as the primary scripting language. All cloud and AI features are accessible via simple GDScript APIs.
+
 ### Architecture Layers
 
+```mermaid
+graph TD
+    subgraph Layer4["Application Layer"]
+        Game[Game Code<br/>GDScript/C#/C++]
+    end
+    
+    subgraph Layer3["SDK Layer"]
+        SDK[AeThex Cloud SDK<br/>GDScript APIs]
+    end
+    
+    subgraph Layer2["Module Layer"]
+        M1[aethex_cloud]
+        M2[aethex_ai]
+        M3[aethex_studio]
+        M4[aethex_analytics]
+    end
+    
+    subgraph Layer1["Engine Layer"]
+        E1[Rendering]
+        E2[Physics]
+        E3[Audio]
+        E4[Networking]
+        E5[Scripting]
+        E6[Scene System]
+    end
+    
+    Game --> SDK
+    SDK --> M1 & M2 & M3 & M4
+    M1 & M2 & M3 & M4 --> E1 & E2 & E3 & E4 & E5 & E6
+    
+    style Layer4 fill:#00ffff22,stroke:#00ffff
+    style Layer3 fill:#ff00ff22,stroke:#ff00ff
+    style Layer2 fill:#00ffff22,stroke:#00ffff
+    style Layer1 fill:#ff00ff22,stroke:#ff00ff
 ```
-┌────────────────────────────────────────────┐
-│         Game Code (GDScript/C#)            │  ← Developer's game
-├────────────────────────────────────────────┤
-│      AeThex Cloud SDK (GDScript)           │  ← Cloud API
-├────────────────────────────────────────────┤
-│     AeThex Modules (C++)                   │  ← Cloud/AI/Studio
-│  • aethex_cloud  • aethex_ai               │
-│  • aethex_studio • aethex_analytics        │
-├────────────────────────────────────────────┤
-│   Godot Core Engine (C++)                  │  ← Game engine
-│  • Rendering  • Physics  • Audio           │
-│  • Networking • Scripting • Scene System   │
 ├────────────────────────────────────────────┤
 │     Platform Layer (OS-specific)           │  ← Windows/Linux/Mac
 └────────────────────────────────────────────┘

docs/EXPORTING_GAMES.md

@@ -2,6 +2,9 @@
 
 This guide covers exporting your AeThex game to all supported platforms: Windows, Linux, macOS, Web (HTML5), and Android.
 
+> [!TIP]
+> Start with web exports for quick testing and distribution. Windows and Linux exports are easiest for desktop games.
+
 ---
 
 ## Overview
@@ -13,10 +16,42 @@ AeThex supports exporting to:
 
 Each platform has specific requirements and optimization considerations.
 
+```mermaid
+graph TD
+    Game[🎮 Your Game] --> Export{Export Target}
+    
+    Export -->|Desktop| Windows[🖥️ Windows]
+    Export -->|Desktop| Linux[🐧 Linux]
+    Export -->|Desktop| Mac[🍎 macOS]
+    Export -->|Web| HTML5[🌐 HTML5]
+    Export -->|Mobile| Android[📱 Android]
+    
+    Windows --> Steam[Steam]
+    Windows --> Itch[itch.io]
+    Linux --> Steam
+    Linux --> Itch
+    Mac --> AppStore[App Store]
+    HTML5 --> Web[Web Hosting]
+    Android --> PlayStore[Google Play]
+    
+    style Game fill:#00ffff22,stroke:#00ffff
+    style Windows fill:#ff00ff22,stroke:#ff00ff
+    style Linux fill:#00ffff22,stroke:#00ffff
+    style Mac fill:#ff00ff22,stroke:#ff00ff
+    style HTML5 fill:#00ffff22,stroke:#00ffff
+    style Android fill:#ff00ff22,stroke:#ff00ff
+```
+
+> [!NOTE]
+> Each platform requires specific export templates. Download them from the editor or the AeThex website.
+
 ---
 
 ## Before Exporting
 
+> [!WARNING]
+> Always test your game in release mode before exporting. Some bugs only appear in release builds due to optimizations and different code paths.
+
 ### 1. Test Your Game
 
 Always test thoroughly before exporting:

docs/GAME_DEVELOPMENT.md

@@ -2,6 +2,9 @@
 
 This guide covers the core game development concepts and systems in AeThex Engine.
 
+> [!TIP]
+> New to game development? Start with the Scene System and Node Hierarchy sections. These are the foundation of everything in AeThex.
+
 ## Scene System
 
 ### What is a Scene?
@@ -13,6 +16,22 @@ A **scene** is a collection of nodes organized in a tree structure. Scenes are t
 - Items
 - Prefabs/templates
 
+```mermaid
+graph TD
+    Scene[🎬 Scene File<br/>.tscn] --> Root[Root Node]
+    Root --> Child1[Child Node 1]
+    Root --> Child2[Child Node 2]
+    Root --> Child3[Child Node 3]
+    Child2 --> GrandChild1[Grandchild 1]
+    Child2 --> GrandChild2[Grandchild 2]
+    
+    style Scene fill:#00ffff22,stroke:#00ffff
+    style Root fill:#ff00ff22,stroke:#ff00ff
+```
+
+> [!NOTE]
+> Scenes can be nested inside other scenes. This allows you to create reusable components and maintain a clean project structure.
+
 ### Working with Scenes
 
 **Creating Scenes:**
@@ -37,6 +56,9 @@ var packed_scene = load("res://levels/next_level.tscn")
 get_tree().change_scene_to_packed(packed_scene)
 ```
 
+> [!WARNING]
+> Always use `change_scene_to_file()` or `change_scene_to_packed()` to switch scenes. Manually removing and adding root nodes can cause issues with signal connections and autoloads.
+
 **Scene Lifecycle:**
 - `_enter_tree()` - Called when node enters the scene tree
 - `_ready()` - Called when node and children are ready
@@ -121,6 +143,33 @@ get_tree().call_group("enemies", "take_damage", 10)
 
 **Signals** are AeThex's implementation of the observer pattern. They allow nodes to communicate without tight coupling.
 
+```mermaid
+sequenceDiagram
+    participant Player
+    participant Enemy
+    participant UI
+    
+    Player->>Player: take_damage(10)
+    Player->>Player: emit_signal("health_changed", 90)
+    Player->>UI: health_changed(90)
+    UI->>UI: update_health_bar(90)
+    
+    Note over Player,UI: Signals enable loose coupling
+    
+    Player->>Player: health reaches 0
+    Player->>Player: emit_signal("player_died")
+    Player->>UI: player_died
+    Player->>Enemy: player_died
+    UI->>UI: show_game_over()
+    Enemy->>Enemy: celebrate()
+    
+    style Player fill:#00ffff22,stroke:#00ffff
+    style UI fill:#ff00ff22,stroke:#ff00ff
+```
+
+> [!TIP]
+> Signals are perfect for situations where you want multiple systems to react to an event without creating dependencies between them.
+
 ### Built-in Signals
 
 **Common Node Signals:**
@@ -133,6 +182,9 @@ get_tree().call_group("enemies", "take_damage", 10)
 - `Area2D.body_exited(body)` - Another body left the area
 - `Button.pressed()` - Button was clicked
 
+> [!NOTE]
+> Most built-in nodes come with useful signals. Check the documentation for each node type to see what signals are available.
+
 ### Creating Custom Signals
 
 ```gdscript

docs/_coverpage.md

@@ -0,0 +1,103 @@
+<!-- _coverpage.md -->
+
+<div class="cover-logo">
+  <h1 style="font-family: Electrolize; font-size: 4em; margin: 0; text-shadow: 0 0 20px var(--neon-cyan), 0 0 40px var(--neon-cyan);">
+    ⚡ AeThex
+  </h1>
+  <h2 style="font-family: Electrolize; font-size: 2em; margin: 10px 0; color: var(--neon-magenta);">
+    Engine Core
+  </h2>
+</div>
+
+<p style="font-size: 1.3em; margin: 30px 0;">
+  The <span style="color: var(--neon-cyan);">cloud-first</span> game engine that makes<br/>
+  <span style="color: var(--neon-magenta);">multiplayer</span>, <span style="color: var(--neon-cyan);">cloud saves</span>, and <span style="color: var(--neon-magenta);">AI features</span> trivial.
+</p>
+
+<div style="margin: 40px 0;">
+  <span style="display: inline-block; margin: 10px; padding: 8px 16px; background: rgba(0, 255, 255, 0.1); border: 1px solid var(--neon-cyan); border-radius: 4px;">
+    ☁️ Cloud-Native
+  </span>
+  <span style="display: inline-block; margin: 10px; padding: 8px 16px; background: rgba(255, 0, 255, 0.1); border: 1px solid var(--neon-magenta); border-radius: 4px;">
+    🎮 Game-Ready
+  </span>
+  <span style="display: inline-block; margin: 10px; padding: 8px 16px; background: rgba(0, 255, 255, 0.1); border: 1px solid var(--neon-cyan); border-radius: 4px;">
+    🤖 AI-Powered
+  </span>
+  <span style="display: inline-block; margin: 10px; padding: 8px 16px; background: rgba(255, 0, 255, 0.1); border: 1px solid var(--neon-magenta); border-radius: 4px;">
+    🚀 Open Source
+  </span>
+</div>
+
+[🚀 Get Started](GETTING_STARTED.md)
+[📚 Documentation](README.md)
+[💻 GitHub](https://github.com/AeThex-LABS/AeThex-Engine-Core)
+
+<!-- Background styling -->
+<style>
+  .cover-main {
+    background: linear-gradient(135deg, #000000 0%, #0a0a0a 50%, #000000 100%);
+    position: relative;
+  }
+  
+  .cover-main::before {
+    content: '';
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    background-image: 
+      linear-gradient(0deg, transparent 24%, rgba(0, 255, 255, 0.05) 25%, rgba(0, 255, 255, 0.05) 26%, transparent 27%, transparent 74%, rgba(255, 0, 255, 0.05) 75%, rgba(255, 0, 255, 0.05) 76%, transparent 77%, transparent),
+      linear-gradient(90deg, transparent 24%, rgba(0, 255, 255, 0.05) 25%, rgba(0, 255, 255, 0.05) 26%, transparent 27%, transparent 74%, rgba(255, 0, 255, 0.05) 75%, rgba(255, 0, 255, 0.05) 76%, transparent 77%, transparent);
+    background-size: 50px 50px;
+    animation: grid-scan 20s linear infinite;
+    pointer-events: none;
+  }
+  
+  @keyframes grid-scan {
+    0% {
+      background-position: 0 0;
+    }
+    100% {
+      background-position: 50px 50px;
+    }
+  }
+  
+  .cover-main > p:first-of-type {
+    margin-top: 0;
+  }
+  
+  .cover-main a {
+    color: var(--neon-cyan);
+    text-decoration: none;
+    border: 2px solid var(--neon-cyan);
+    padding: 12px 30px;
+    margin: 10px;
+    display: inline-block;
+    transition: all 0.3s ease;
+    font-family: Electrolize;
+    text-transform: uppercase;
+    letter-spacing: 2px;
+    background: rgba(0, 255, 255, 0.05);
+    box-shadow: 0 0 20px rgba(0, 255, 255, 0.3);
+  }
+  
+  .cover-main a:hover {
+    background: rgba(0, 255, 255, 0.2);
+    box-shadow: 0 0 30px rgba(0, 255, 255, 0.6), inset 0 0 20px rgba(0, 255, 255, 0.2);
+    transform: translateY(-2px);
+  }
+  
+  .cover-main a:nth-child(2) {
+    border-color: var(--neon-magenta);
+    color: var(--neon-magenta);
+    background: rgba(255, 0, 255, 0.05);
+    box-shadow: 0 0 20px rgba(255, 0, 255, 0.3);
+  }
+  
+  .cover-main a:nth-child(2):hover {
+    background: rgba(255, 0, 255, 0.2);
+    box-shadow: 0 0 30px rgba(255, 0, 255, 0.6), inset 0 0 20px rgba(255, 0, 255, 0.2);
+  }
+</style>

docs/index.html

@@ -14,49 +14,180 @@
   
   <!-- Custom Cyberpunk Theme -->
   <link rel="stylesheet" href="theme.css">
+  
+  <!-- Favicon -->
+  <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>⚡</text></svg>">
 </head>
 <body>
-  <div id="app">Loading...</div>
+  <div id="app">Loading AeThex Documentation...</div>
   <script>
     window.$docsify = {
-      name: 'AeThex Engine',
+      name: '<span style="font-family: Electrolize; font-size: 1.2em;">⚡ AeThex Engine</span>',
       repo: 'https://github.com/AeThex-LABS/AeThex-Engine-Core',
       loadSidebar: true,
       subMaxLevel: 3,
       auto2top: true,
       homepage: 'README.md',
+      relativePath: false,
+      
+      // Cover page
+      coverpage: true,
+      onlyCover: false,
+      
+      // Search
       search: {
         maxAge: 86400000,
         paths: 'auto',
-        placeholder: 'Search docs...',
+        placeholder: '🔍 Search docs...',
-        noData: 'No results found.',
+        noData: '❌ No results found.',
-        depth: 6
+        depth: 6,
+        hideOtherSidebarContent: false
       },
+      
+      // Pagination
       pagination: {
-        previousText: 'Previous',
+        previousText: '← Previous',
-        nextText: 'Next',
+        nextText: 'Next →',
-        crossChapter: true
+        crossChapter: true,
+        crossChapterText: true
       },
+      
+      // Tabs for code examples
+      tabs: {
+        persist: true,
+        sync: true,
+        theme: 'classic',
+        tabComments: true,
+        tabHeadings: true
+      },
+      
+      // Copy code button
+      copyCode: {
+        buttonText: '📋 Copy',
+        errorText: '❌ Error',
+        successText: '✅ Copied!'
+      },
+      
+      // Progress bar
+      progress: {
+        position: "top",
+        color: "var(--neon-cyan)",
+        height: "3px",
+      },
+      
+      // Flexible alerts
+      'flexible-alerts': {
+        style: 'flat',
+        note: {
+          label: "📝 Note"
+        },
+        tip: {
+          label: "💡 Tip"
+        },
+        warning: {
+          label: "⚠️ Warning"
+        },
+        danger: {
+          label: "🚨 Danger"
+        }
+      },
+      
+      // Count
+      count: {
+        countable: true,
+        fontsize: '0.9em',
+        color: 'var(--neon-cyan)',
+        language: 'english'
+      },
+      
       themeable: {
         readyTransition: true,
         responsiveTables: true
       },
+      
       alias: {
-        '/.*/_sidebar.md': '/_sidebar.md'
+        '/.*/_sidebar.md': '/_sidebar.md',
+        '/.*/_coverpage.md': '/_coverpage.md'
       },
-      notFoundPage: true
+      
+      notFoundPage: true,
+      
+      // Footer
+      loadFooter: true,
+      
+      // Edit on GitHub
+      plugins: [
+        function(hook, vm) {
+          hook.beforeEach(function(html) {
+            var url = 'https://github.com/AeThex-LABS/AeThex-Engine-Core/blob/main/docs/' + vm.route.file;
+            var editHtml = '<div style="text-align: right; padding: 10px 0;">';
+            editHtml += '<a href="' + url + '" target="_blank" style="color: var(--neon-cyan); text-decoration: none;">';
+            editHtml += '📝 Edit on GitHub</a></div>\n\n';
+            return editHtml + html;
+          });
+          
+          // Add last updated timestamp
+          hook.afterEach(function(html) {
+            var footer = '<hr style="border-color: var(--neon-cyan); opacity: 0.3;"/>';
+            footer += '<div style="text-align: center; padding: 20px 0; font-size: 0.9em; color: var(--neon-cyan); opacity: 0.7;">';
+            footer += '<p>Made with ⚡ by AeThex Labs</p>';
+            footer += '<p style="font-size: 0.8em;">Last updated: ' + new Date().toLocaleDateString() + '</p>';
+            footer += '</div>';
+            return html + footer;
+          });
+        }
+      ],
+      
+      // Mermaid config
+      mermaid: {
+        theme: 'dark',
+        themeVariables: {
+          primaryColor: '#00ffff',
+          primaryTextColor: '#fff',
+          primaryBorderColor: '#ff00ff',
+          lineColor: '#00ffff',
+          secondaryColor: '#ff00ff',
+          tertiaryColor: '#000'
+        }
+      }
     }
   </script>
+  
   <!-- Docsify core -->
   <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+  
   <!-- Search plugin -->
   <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
+  
   <!-- Pagination -->
   <script src="//cdn.jsdelivr.net/npm/docsify-pagination@2/dist/docsify-pagination.min.js"></script>
+  
   <!-- Copy code -->
   <script src="//cdn.jsdelivr.net/npm/docsify-copy-code@2"></script>
+  
   <!-- Zoom images -->
   <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/zoom-image.min.js"></script>
+  
+  <!-- Tabs -->
+  <script src="//cdn.jsdelivr.net/npm/docsify-tabs@1"></script>
+  
+  <!-- Progress bar -->
+  <script src="//cdn.jsdelivr.net/npm/docsify-progress@1/dist/progress.min.js"></script>
+  
+  <!-- Flexible alerts -->
+  <script src="//cdn.jsdelivr.net/npm/docsify-plugin-flexible-alerts"></script>
+  
+  <!-- Word count -->
+  <script src="//cdn.jsdelivr.net/npm/docsify-count@latest/dist/countable.min.js"></script>
+  
+  <!-- Mermaid diagrams -->
+  <script type="module">
+    import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
+    mermaid.initialize({ startOnLoad: true });
+    window.mermaid = mermaid;
+  </script>
+  <script src="//cdn.jsdelivr.net/npm/docsify-mermaid@2/dist/docsify-mermaid.js"></script>
+  
   <!-- Syntax highlighting -->
   <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-gdscript.min.js"></script>
@@ -64,5 +195,26 @@
   <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-cpp.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js"></script>
   <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-python.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-markdown.min.js"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-nginx.min.js"></script>
+  
+  <!-- Chart.js for diagrams -->
+  <script src="//cdn.jsdelivr.net/npm/chart.js@3"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify-charty/dist/docsify-charty.min.js"></script>
+  
+  <!-- Keyboard shortcuts hint -->
+  <script>
+    document.addEventListener('DOMContentLoaded', function() {
+      // Add keyboard shortcut listener
+      document.addEventListener('keydown', function(e) {
+        // Ctrl/Cmd + K for search
+        if ((e.ctrlKey || e.metaKey) && e.key === 'k') {
+          e.preventDefault();
+          document.querySelector('.search input[type="search"]')?.focus();
+        }
+      });
+    });
+  </script>
 </body>
 </html>

docs/tutorials/AI_ASSISTANT_TUTORIAL.md

@@ -2,6 +2,9 @@
 
 Learn how to integrate AeThex's AI assistant into your game to provide contextual help and coding assistance to players.
 
+> [!TIP]
+> The AI Assistant can understand your game's context, player actions, and current state to provide relevant and helpful responses.
+
 ---
 
 ## What You'll Build
@@ -16,6 +19,19 @@ A game with an in-game AI assistant that can:
 **Difficulty:** Beginner  
 **Prerequisites:** Basic GDScript knowledge
 
+```mermaid
+graph LR
+    Player[👤 Player] -->|Asks Question| UI[Chat UI]
+    UI -->|Send Message| AI[⚡ AI Service]
+    AI -->|Context| Game[Game State]
+    AI -->|Generate| Response[AI Response]
+    Response -->|Display| UI
+    
+    style Player fill:#00ffff22,stroke:#00ffff
+    style AI fill:#ff00ff22,stroke:#ff00ff
+    style Game fill:#00ffff22,stroke:#00ffff
+```
+
 ---
 
 ## Prerequisites
@@ -24,12 +40,18 @@ A game with an in-game AI assistant that can:
 - AeThex Cloud connection set up
 - Basic understanding of UI systems
 
+> [!WARNING]
+> AI features require an active AeThex Cloud connection. Make sure you're authenticated before using AI services.
+
 ---
 
 ## Step 1: Connect to AI Service
 
 First, ensure you're connected to AeThex Cloud with AI services enabled.
 
+> [!NOTE]
+> AeThex Cloud handles all AI infrastructure, rate limiting, and caching automatically.
+
 ```gdscript
 # main.gd
 extends Node

docs/tutorials/ANALYTICS_TUTORIAL.md

@@ -2,6 +2,9 @@
 
 Learn how to track player behavior, measure engagement, and make data-driven decisions with AeThex Analytics.
 
+> [!TIP]
+> Analytics is your window into player behavior. Use it to understand what players love, what confuses them, and where they get stuck.
+
 ---
 
 ## What You'll Build
@@ -17,6 +20,23 @@ A complete analytics system that tracks:
 **Difficulty:** Beginner  
 **Prerequisites:** Basic GDScript knowledge
 
+```mermaid
+graph LR
+    Game[🎮 Game Events] -->|Track| SDK[AeThex SDK]
+    SDK -->|Batch| Cloud[☁️ Cloud]
+    Cloud -->|Process| Pipeline[Data Pipeline]
+    Pipeline -->|Store| DB[(Database)]
+    DB -->|Query| Dashboard[📊 Dashboard]
+    Dashboard -->|Insights| You[👤 You]
+    
+    Events[Events<br/>• level_complete<br/>• item_collected<br/>• player_died]
+    Properties[User Props<br/>• level<br/>• skill<br/>• device]
+    
+    style Game fill:#00ffff22,stroke:#00ffff
+    style Cloud fill:#ff00ff22,stroke:#ff00ff
+    style Dashboard fill:#00ffff22,stroke:#00ffff
+```
+
 ---
 
 ## Why Use Analytics?
@@ -28,12 +48,18 @@ Analytics helps you:
 - **Fix bugs faster** - Get crash reports automatically
 - **Make data-driven decisions** - Know what features to build
 
+> [!NOTE]
+> AeThex Analytics automatically batches events to minimize network usage and battery drain. No need to worry about performance impact.
+
 ---
 
 ## Step 1: Connect to Analytics
 
 First, connect to AeThex Cloud and initialize analytics:
 
+> [!WARNING]
+> Don't track personally identifiable information (PII) like email addresses or real names in analytics events. Use anonymous user IDs instead.
+
 ```gdscript
 # main.gd
 extends Node

docs/tutorials/AUTH_TUTORIAL.md

@@ -2,6 +2,9 @@
 
 Learn how to add user authentication to your AeThex game with email/password, OAuth, and guest login support.
 
+> [!TIP]
+> Authentication is the foundation for cloud saves, multiplayer, and social features. Start here to unlock all AeThex Cloud capabilities.
+
 ---
 
 ## What You'll Build
@@ -17,6 +20,43 @@ A complete authentication system with:
 **Difficulty:** Beginner  
 **Prerequisites:** Basic GDScript knowledge
 
+```mermaid
+flowchart TD
+    Start[Game Launch] --> Check{Has Session?}
+    Check -->|Yes| Welcome[Welcome Back!]
+    Check -->|No| Login[Show Login Screen]
+    
+    Login --> Choice{Auth Method?}
+    
+    Choice -->|Email/Password| EmailAuth[Email Login]
+    Choice -->|OAuth| OAuthFlow[OAuth Flow]
+    Choice -->|Guest| GuestAuth[Guest Account]
+    
+    EmailAuth --> Validate{Valid?}
+    Validate -->|No| Error1[Show Error]
+    Error1 --> Login
+    Validate -->|Yes| Auth[Authenticate]
+    
+    OAuthFlow --> Provider[Select Provider]
+    Provider --> Browser[Open Browser]
+    Browser --> Auth
+    
+    GuestAuth --> Auth
+    
+    Auth --> Success{Success?}
+    Success -->|No| Error2[Show Error]
+    Error2 --> Login
+    Success -->|Yes| SaveSession[Save Session]
+    SaveSession --> Welcome
+    
+    Welcome --> MainMenu[Main Menu]
+    
+    style Start fill:#00ffff22,stroke:#00ffff
+    style Welcome fill:#00ff0022,stroke:#00ff00
+    style Auth fill:#ff00ff22,stroke:#ff00ff
+    style MainMenu fill:#00ffff22,stroke:#00ffff
+```
+
 ---
 
 ## Why Add Authentication?
@@ -28,12 +68,18 @@ Authentication enables:
 - **Analytics** - Track user behavior
 - **Monetization** - In-app purchases, subscriptions
 
+> [!WARNING]
+> Never store passwords in plaintext. AeThex Cloud handles all password hashing and security automatically.
+
 ---
 
 ## Step 1: Connect to AeThex Cloud
 
 First, ensure cloud services are connected:
 
+> [!NOTE]
+> Session tokens are stored securely and persist across game sessions. Users stay logged in automatically.
+
 ```gdscript
 # main.gd
 extends Node