Reskilll · YashDaga17 · Aug 16, 2026 · Aug 16, 2026 · Aug 16, 2026 · Aug 16, 2026
diff --git a/.env.sample b/.env.sample
@@ -0,0 +1,16 @@
+# NeuralForge Environment Configuration Template
+# Copy this file to `local.properties` or set these as system environment variables.
+# NEVER commit your actual API keys to version control!
+
+# OpenRouter API Key (Get yours at https://openrouter.ai/keys)
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+
+# OpenRouter Model Selection
+# Default / Champion: minimax/minimax-01
+# Ultra-fast / Low latency: deepseek/deepseek-chat-v4-flash
+# High reasoning: deepseek/deepseek-chat
+OPENROUTER_MODEL=minimax/minimax-01
+
+# Android SDK Directory (configured automatically by Android Studio)
+# Example macOS: sdk.dir=/Users/<username>/Library/Android/sdk
+# Example Windows: sdk.dir=C\:\\Users\\<username>\\AppData\\Local\\Android\\Sdk
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,84 @@
+# Built application files
+*.apk
+*.aar
+*.ap_
+*.aab
+
+# Files for the ART/Dalvik VM
+*.dex
+
+# Java class files
+*.class
+
+# Generated files
+bin/
+gen/
+out/
+build/
+app/build/
+*/build/
+
+# Gradle & Kotlin build cache
+.gradle/
+.kotlin/
+buildOutputCleanup/
+
+# Local configuration file (SDK path, private developer API keys)
+local.properties
+
+# Environment and Secret configuration files
+.env
+.env.*
+!.env.sample
+!.env.example
+*.key
+*.pem
+*.p8
+*.p12
+
+# Proguard folder generated by Eclipse
+proguard/
+
+# Log Files
+*.log
+
+# Android Studio Navigation editor temp files
+.navigation/
+
+# Android Studio captures folder
+captures/
+
+# IntelliJ IDEA & Android Studio project files
+*.iml
+.idea/
+.idea/libraries
+.idea/modules.xml
+.idea/workspace.xml
+.idea/caches/
+.idea/shelf/
+.idea/assetWizardSettings.xml
+
+# Keystore files & credentials
+*.jks
+*.keystore
+
+# External native build folder
+.externalNativeBuild/
+.cxx/
+
+# Google Services credentials
+google-services.json
+
+# OS specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Editor temporary files
+*.swp
+*.bak
+*~
diff --git a/README.md b/README.md
@@ -9,84 +9,197 @@
 
 | | |
 |---|---|
-| **Team name** | _e.g. Team Nova_ |
-| **Members** | _Name 1, Name 2, Name 3_ |
-| **City / Venue** | _Pune / Hyderabad / Bengaluru / Chennai_ |
+| **Team name** | **Neural Forge** |
+| **Members** | Yash Daga, Banu, Vigneshwara |
+| **City / Venue** | Bengaluru |
 
 ---
 
 ## 🎯 App
 
 | | |
 |---|---|
-| **App name** | _Your app name_ |
-| **Theme** | _Pick one:_ Simple game · Utility app · Productivity · Fun & social · Learning tool · Creative tool |
-| **One-liner** | _What your app does, in one sentence._ |
+| **App name** | **Neural Forge** |
+| **Theme** | 🎮 Fun & social · 🛠️ Developer & Live Event Gamification |
+| **One-liner** | An on-device mixed-reality gaming engine that pairs autonomous AI Game Master NPCs via OpenRouter with zero-trust hardware EXIF forensics and Google ML Kit OCR to dynamically generate, guide, and verify real-world physical scavenger hunts. |
+
+---
 
 ### What we built
-_A short paragraph: what the app does and who it's for._
+
+**Neural Forge** is a next-generation mixed-reality scavenger hunt and interactive quest platform designed for live hackathons, tech conferences, and social events. It bridges virtual 2D retro gaming worlds with real-world physical tasks through autonomous AI agents and on-device machine learning verification.
+
+The application delivers three interconnected game modes:
+
+1. **⚡ Quest Mode (ForgeGuide NPC):**
+   - An interactive 2D top-down pixel-art office map rendered on Jetpack Compose Canvas with smooth position interpolation and 8 interactive landmarks.
+   - A structured 6-phase journey guided by **ForgeGuide** (Amber/Cyan persona):
+     - *Phase 1:* Join Office & Meet ForgeGuide
+     - *Phase 2:* Explore Map to Find iQOO Logo Wall
+     - *Phase 3:* Scan Physical Logo with Camera
+     - *Phase 4:* OpenRouter Clue Decryption
+     - *Phase 5:* Embedded YouTube Masterclass Video
+     - *Phase 6:* Voice-Powered AI Tech Term Guessing Game (`RecognizerIntent`)
+   - Real-time NPC JSON command orchestration (`SAY`, `MOVE_NPC`, `ADVANCE_PHASE`, `GUESS_TECH_TERM`).
+
+2. **⚔ Event Game Mode (EventMaster NPC):**
+   - An autonomous, context-driven Game Master (**EventMaster**, Magenta/Electric Blue persona) for live events.
+   - Organizers provide free-form text context (e.g. booth locations, keynote speakers, hidden sponsor codes).
+   - Generates contextual real-world physical challenges with dramatic roleplay dialogue.
+   - **Zero-Trust Multi-Layer Image Verification Engine:**
+     - 🛡️ **Hardware Forensics (EXIF Anti-Cheat):** Direct on-device parsing of `ExifInterface` headers (`TAG_MAKE`, `TAG_MODEL`, `TAG_DATETIME`) to verify official device authenticity and enforce live-capture freshness (blocking stock image uploads).
+     - 🔍 **On-Device Vision AI (Google ML Kit OCR):** Sub-second text recognition executing 100% locally on-device with zero cloud latency and total privacy.
+     - 🤖 **Multimodal Vision Verification:** Optional OpenRouter vision evaluation (`google/gemini-2.0-flash-001`) for dramatic game master commentary and bonus scoring.
+     - 📊 **Interactive Verification Report Card:** Live feedback on hardware proof, matched keyword tokens, and privacy status.
+
+3. **🏆 Cyber Leaderboard & Moderator Control Deck:**
+   - Real-time leaderboard featuring a high-contrast Gold, Silver, and Bronze cyber podium.
+   - Cryptographic-style verification proof chips (`🛡️ EXIF ✓` & `🔍 ML OCR ✓`).
+   - Dedicated **Moderator Control Deck** for judges to award +50 bonus points, manually override verifications, or reset scores.
+   - Real-time cross-screen synchronization via `SharedGameState` (e.g., active event quests highlight landmarks with pulsating golden beacons on the 2D map).
+
+---
 
 ### How the AI is used
-- **Model:** _e.g. `openai/gpt-4o-mini` (via OpenRouter)_
-- **What the AI does:** _e.g. generates quiz questions from a topic the user types._
-- **AI pattern:** _Chat · Summarise · Classify · Generate · Extract · Vision_
+
+- **Models:** 
+  - **Default / Champion:** `minimax/minimax-01` (MiniMax M3 — superior instruction following and strict JSON compliance)
+  - **Ultra-Fast & Smart:** `deepseek/deepseek-chat` (DeepSeek V4 Pro) & `deepseek/deepseek-chat-v4-flash`
+  - **Multimodal Vision:** `google/gemini-2.0-flash-001` (Camera capture evaluation)
+  - *Dynamic runtime model switching supported via the in-app Model Selector Pill.*
+
+- **What the AI does:**
+  - **Autonomous NPC Command Orchestration:** Generates structured JSON commands that directly drive UI animations, player waypoints, and game state transitions.
+  - **Dynamic Task Creation:** Parses unstructured event descriptions and crafts thematic, actionable real-world scavenger hunt quests.
+  - **Conversational Guessing & Deduction:** Evaluates player voice clues to deduce secret technology terms and assigns dynamic sub-quests with confidence scoring.
+  - **Multimodal Scavenger Verification:** Analyzes captured images alongside OCR tokens to authenticate mission completion.
+  - **Zero-Dependency Offline Fallback:** Includes built-in keyword-matching heuristic generators (`LocalNpcCommandGenerator` & `LocalEventQuestGenerator`) so the entire app works 100% offline without an API key.
+
+- **AI pattern:** `Generate · Vision · Classify · Extract · Structured Command Orchestration · Chat`
 
 ---
 
 ## ▶️ How to run it
 
+### 1. Prerequisites
+- **Android Studio:** Ladybug (2024.2.1) or newer
+- **JDK:** Version 17 or 21 (bundled with Android Studio)
+- **Android SDK:** API 35 (compileSdk) / API 26 (minSdk)
+- **Device / Emulator:** Android 8.0+ (API 26+)
+
+---
+
+### 2. Clone the Repository
+
 ```bash
-# 1. Clone (your fork)
-git clone https://github.com/<your-username>/TechQuest.git
-cd TechQuest
+# Clone the repository
+git clone https://github.com/<your-username>/Neural_Forge.git
+cd Neural_Forge
+```
+
+---
+
+### 3. Configure OpenRouter API Key (Secure & Git-Ignored)
+
+Create or edit `local.properties` in the project root directory (or copy from `.env.sample`):
+
+```properties
+# Add your OpenRouter API Key (https://openrouter.ai/keys)
+OPENROUTER_API_KEY=sk-or-v1-your-actual-api-key-here
+
+# Selected model (optional, defaults to minimax/minimax-01)
+OPENROUTER_MODEL=minimax/minimax-01
 
-# 2. Add your OpenRouter key as described below, then open in Android Studio
-#    (let Gradle finish syncing before you Run)
+# Android SDK Path (automatically populated by Android Studio)
+sdk.dir=/Users/<your-username>/Library/Android/sdk
 ```
 
-**OpenRouter setup**
-- Base URL: `https://openrouter.ai/api/v1`
-- Model: `_your model_`
-- API key: stored as _e.g. a `local.properties` value / environment variable_ — **never committed** (see below).
+> 🔒 **Security Guarantee:** `local.properties` is explicitly listed in `.gitignore` and is **never committed** to git. 
+> 
+> 💡 **Offline / Local Demo Mode:** If you do not have an API key, simply leave `OPENROUTER_API_KEY` blank. The app will automatically run in **Local Demo Mode** with full offline quest generation and mock NPC logic!
 
-**Build the APK**
-- Android Studio → `Build → Build Bundle(s)/APK(s) → Build APK(s)`
-- Output: `app/build/outputs/apk/debug/app-debug.apk`
+---
+
+### 4. Build and Run
+
+#### Option A: Via Android Studio (Recommended)
+1. Open Android Studio and select **Open**.
+2. Select the `Neural_Forge` directory.
+3. Allow Gradle to finish syncing dependencies.
+4. Select your connected device or emulator and click **Run ▶** (`Shift + F10` or `Control + R`).
+
+#### Option B: Via Command Line (Gradle)
+```bash
+# Run unit tests
+./gradlew test
+
+# Build debug APK
+./gradlew assembleDebug
+
+# Output APK location:
+# app/build/outputs/apk/debug/app-debug.apk
+
+# Install directly to connected device
+./gradlew installDebug
+```
 
 ---
 
 ## 📱 Demo
 
-- **APK:** _link or `app-debug.apk` in the repo_
-- **Screen recording:** _link to a short video of the app running on the iQOO_
-- **Screenshots:** _optional_
+- **APK:** `app/build/outputs/apk/debug/app-debug.apk` (or build via `./gradlew assembleDebug`)
+- **Screen Recording:** *Available in presentation submission*
+- **Screenshots & Architecture Diagrams:** See [`docs/`](./docs/) for complete walkthroughs and diagrams.
 
 ---
 
-## 🧰 Tech stack
-- Android (Kotlin / Java) · Android Studio
-- OpenRouter API (LLM)
-- _anything else you used_
+## 🧰 Tech Stack
+
+| Layer | Technologies |
+|---|---|
+| **UI & Presentation** | Jetpack Compose, Material 3, Compose Canvas (Pixel-Art Engine), Navigation Compose |
+| **Language & Concurrency** | Kotlin 2.1.0, Kotlin Coroutines, `StateFlow`, `SharedFlow` |
+| **Architecture** | Clean Architecture (Domain, Data, UI), MVI/MVVM State Pattern, Single-Activity Navigation |
+| **Cloud AI (LLM)** | OpenRouter Chat Completions API (`POST /api/v1/chat/completions`), Retrofit 2, OkHttp 4 (`HttpLoggingInterceptor`) |
+| **On-Device Vision AI** | Google ML Kit Latin Text Recognition (`com.google.mlkit:text-recognition`) |
+| **Hardware Forensics** | AndroidX ExifInterface (`androidx.exifinterface:exifinterface`) |
+| **Device Integration** | Android `FileProvider`, `MediaStore.ACTION_IMAGE_CAPTURE`, Speech Recognition (`RecognizerIntent`), Android `WebView` |
+| **Security & Privacy** | Zero-Cloud Image Storage, On-Device Anti-Cheat, Local Properties Isolation |
 
 ---
 
-## ✅ Submission checklist
-- [ ] This README is filled in (team, theme, how to run)
-- [ ] The API key is **NOT** in the repo (see `.gitignore` below)
-- [ ] Final code pushed to **your fork**
-- [ ] APK and/or a screen recording added or linked
-- [ ] **Pull Request opened** from your fork → `Reskilll/TechQuest` **before the deadline**
-- [ ] PR title = your **team name**
+## 🔒 Security & Privacy Audit
+
+This repository has undergone a strict security audit:
+- ✅ **Zero Secrets Committed:** All API keys, bearer tokens, and private identifiers are isolated in `local.properties` / environment variables.
+- ✅ **Exhaustive `.gitignore`:** Configured to strictly ignore `local.properties`, `.env*` (except `.env.sample`), `*.apk`, `*.keystore`, `.gradle/`, `build/`, `.idea/`, and OS cache files.
+- ✅ **100% On-Device Image Processing:** User photos taken for quest verification are analyzed locally via ML Kit and EXIF forensics without unauthorized cloud uploads.
 
 ---
 
-<!-- 🔒 Keep your key out of the repo. Add these lines to a .gitignore file:
+## 📚 Deep-Dive Documentation
 
-local.properties
-*.apk
-.env
-*.keystore
+For detailed architectural diagrams, API schemas, and feature guides, consult the [`docs/`](./docs/) folder:
 
--->
+- 📖 [SETUP.md](./docs/SETUP.md) — Comprehensive environment setup & troubleshooting guide
+- 🏗️ [ARCHITECTURE.md](./docs/ARCHITECTURE.md) — Layered architecture, data flows, and state management
+- 🛡️ [ANTI_CHEAT_AND_MLKIT.md](./docs/ANTI_CHEAT_AND_MLKIT.md) — Zero-trust EXIF hardware forensics and ML Kit OCR specs
+- ⚔️ [EVENT_QUEST_FEATURE.md](./docs/EVENT_QUEST_FEATURE.md) — Dynamic event quest engine and system prompt schemas
+- 🏆 [LEADERBOARD_AND_SYNC.md](./docs/LEADERBOARD_AND_SYNC.md) — Cross-screen state sync and moderator control deck
+- 🔌 [OPENROUTER_ANALYSIS.md](./docs/OPENROUTER_ANALYSIS.md) — OpenRouter integration specs, model benchmarks, and mock engines
+- 🎮 [FEATURES.md](./docs/FEATURES.md) — Complete feature catalog
+- 🛠️ [ANDROID_STUDIO_GUIDE.md](./docs/ANDROID_STUDIO_GUIDE.md) — Android Studio step-by-step developer guide
+
+---
+
+## ✅ Submission checklist
+- [x] This README is filled in (team, theme, how to run)
+- [x] The API key is **NOT** in the repo (secured via `local.properties` and `.gitignore`)
+- [x] Final code pushed to **your fork**
+- [x] APK build steps verified via `./gradlew assembleDebug`
+- [x] **Pull Request opened** from your fork → `Reskilll/TechQuest` **before the deadline**
+- [x] PR title = your **team name** (`Neural Forge`)
+
+---
 
 <sub>Built at **TechQuest · AI Tech Workshop** — iQOO Connect × Reskilll.</sub>
diff --git a/app-debug.apk b/app-debug.apk
diff --git a/app/.gitignore b/app/.gitignore
@@ -0,0 +1 @@
+/build