Upload 26 files

First release about the engine's CLI for training AI.

.gitattributes

@@ -1,35 +1,8 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+# OktoScript Language Detection
+# This file tells GitHub to recognize .okt files as OktoScript language
+
+*.okt linguist-language=OktoScript
+
+assets/okto_logo.png filter=lfs diff=lfs merge=lfs -text
+assets/okto_logo2.png filter=lfs diff=lfs merge=lfs -text
+assets/terminal-debug.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,41 @@
+# OktoEngine GitHub Repository
+
+# OS files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Temporary files
+*.tmp
+*.log
+*.cache
+
+# Build artifacts (if any)
+target/
+build/
+dist/
+
+# Example project outputs
+examples/*/runs/
+examples/*/export/
+examples/*/checkpoints/
+
+# Documentation build
+docs/_build/
+site/
+
+# Environment files
+.env
+.env.local
+
+# Test files
+test_output/
+*.test
+

CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to OktoEngine will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+
+#### Core Features
+- **Initial release** of OktoEngine CLI
+- Complete OktoScript parser with full grammar support
+- Training pipeline execution
+- Model evaluation and export
+- System diagnostics and environment checking
+
+#### CLI Commands
+- `okto init` - Initialize new OktoScript projects
+- `okto validate` - Validate OktoScript files
+- `okto train` - Train models from OktoScript
+- `okto eval` - Evaluate trained models
+- `okto export` - Export models to multiple formats
+- `okto list` - List projects, models, and datasets
+- `okto doctor` - System diagnostics
+- `okto doctor --install` - Automatic dependency installation
+- `okto upgrade` - Automatic engine updates
+- `okto about` - Show engine information
+
+#### Features
+- **Debug mode** - Comprehensive debug logging via `--debug` flag
+- **Automatic dependency management** - Installs missing dependencies
+- **HuggingFace integration** - Automatic model downloading
+- **Multi-format export** - Support for OKM, ONNX, GGUF, SafeTensors
+- **Real-time metrics** - Training progress and metrics in terminal
+- **Error handling** - Detailed error messages with troubleshooting tips
+- **Cross-platform support** - Windows, Linux, macOS
+
+#### Training Capabilities
+- Full fine-tuning support
+- LoRA fine-tuning support
+- Automatic checkpoint management
+- Mixed precision training (FP16/BF16)
+- Automatic device selection (CPU/GPU)
+- Gradient accumulation
+- Memory optimization
+
+#### System Features
+- GPU detection and utilization
+- CUDA support detection
+- RAM and CPU monitoring
+- Runtime environment checking
+- Dependency verification
+- Automatic updates via GitHub Releases
+
+#### Documentation
+- Complete CLI reference
+- Getting started guide
+- Debug mode guide
+- FAQ with common questions
+- Example projects and configurations
+
+### Technical Details
+
+- Built with Rust for performance and reliability
+- Professional CLI interface with intuitive commands
+- Robust error handling and validation
+- Comprehensive logging system
+- Cross-platform binary releases
+
+---
+
+## [Unreleased]
+
+### Planned Features
+- Integration with OktoSeek IDE
+- Visual training dashboard
+- Advanced monitoring and telemetry
+- Multi-GPU training support
+- Distributed training support
+- Model serving capabilities
+- API server mode
+- Web dashboard interface
+
+---
+
+## Version History
+
+- **0.1.0** (2025-01-XX) - Initial release
+
+---
+
+**For detailed information about each version, see the [GitHub Releases](https://github.com/oktoseek/oktoengine/releases) page.**
+
+---
+
+Copyright © 2025 OktoSeek AI. All rights reserved.
+

CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing to OktoEngine
+
+Thank you for your interest in OktoEngine! 🐙
+
+**OktoEngine** is a proprietary CLI engine developed by **OktoSeek AI**. While the source code is not open source, we welcome feedback, bug reports, and feature requests from the community.
+
+---
+
+## How to Contribute
+
+### Reporting Bugs
+
+If you find a bug, please open an issue on GitHub with:
+
+- **Clear description** of the problem
+- **Steps to reproduce** the issue
+- **Expected vs actual behavior**
+- **OktoEngine version:** `okto --version`
+- **System information:** `okto doctor` output
+- **Debug output** (if applicable): `okto <command> --debug`
+
+**Example:**
+```
+Bug: Training fails with "Model not found" error
+
+Steps to reproduce:
+1. Run `okto init test-project`
+2. Edit scripts/train.okt with MODEL { base: "invalid-model" }
+3. Run `okto train`
+
+Expected: Clear error message about invalid model
+Actual: Generic "Model not found" error
+
+Version: okto 0.1.0
+System: Windows 10, GPU: RTX 4070
+```
+
+### Feature Requests
+
+Have an idea for a new feature? Open an issue with:
+
+- **Feature description** - What you'd like to see
+- **Use case** - Why this feature would be useful
+- **Proposed implementation** (optional) - How you think it could work
+
+### Documentation Improvements
+
+Found an error in the documentation? Want to add examples or clarify something?
+
+- Open an issue describing the improvement
+- Or submit a pull request with documentation changes (if applicable)
+
+### Examples
+
+Have a great example project? Share it!
+
+- Create an issue with your example
+- Include your `train.okt` file
+- Describe what your example demonstrates
+
+---
+
+## Code Contributions
+
+**Note:** OktoEngine source code is proprietary. However, we may accept contributions for:
+
+- Documentation improvements
+- Example projects
+- Test cases
+- Bug fixes (in specific cases)
+
+If you're interested in contributing code, please contact us first at **service@oktoseek.com**.
+
+---
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities publicly.**
+
+If you discover a security issue, please email **security@oktoseek.com** with:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+We will respond promptly and work with you to resolve the issue.
+
+---
+
+## Code of Conduct
+
+### Our Standards
+
+- Be respectful and inclusive
+- Welcome newcomers and help them learn
+- Focus on constructive feedback
+- Respect different viewpoints and experiences
+
+### Unacceptable Behavior
+
+- Harassment or discrimination
+- Trolling or inflammatory comments
+- Personal attacks
+- Publishing others' private information
+
+---
+
+## Questions?
+
+- **GitHub Issues:** https://github.com/oktoseek/oktoengine/issues
+- **Email:** service@oktoseek.com
+- **Website:** https://www.oktoseek.com
+
+---
+
+**OktoEngine** is developed and maintained by **OktoSeek AI**.
+
+Thank you for helping make OktoEngine better! 🚀
+

LICENSE

@@ -0,0 +1,76 @@
+END USER LICENSE AGREEMENT (EULA)
+
+FOR OKTOENGINE SOFTWARE
+
+IMPORTANT - READ CAREFULLY: This End User License Agreement ("EULA") is a legal agreement between you (either an individual or a single entity) and OktoSeek AI ("Licensor") for the OktoEngine software product, which includes computer software and may include associated media, printed materials, and "online" or electronic documentation ("Software").
+
+BY INSTALLING, COPYING, OR OTHERWISE USING THE SOFTWARE, YOU AGREE TO BE BOUND BY THE TERMS OF THIS EULA. IF YOU DO NOT AGREE TO THE TERMS OF THIS EULA, DO NOT INSTALL OR USE THE SOFTWARE.
+
+1. GRANT OF LICENSE
+
+Subject to the terms and conditions of this EULA, Licensor grants you a limited, non-exclusive, non-transferable license to:
+   a. Install and use the Software on computers under your control;
+   b. Use the Software solely for your internal business or personal purposes;
+   c. Make a reasonable number of backup copies of the Software for archival purposes.
+
+2. RESTRICTIONS
+
+You may NOT:
+   a. Copy, modify, adapt, alter, translate, or create derivative works of the Software;
+   b. Reverse engineer, decompile, disassemble, or otherwise attempt to derive the source code of the Software;
+   c. Remove, alter, or obscure any proprietary notices, labels, or marks on the Software;
+   d. Rent, lease, lend, sell, sublicense, assign, distribute, publish, transfer, or otherwise make available the Software or any portion thereof to any third party;
+   e. Use the Software in any manner that could damage, disable, overburden, or impair any Licensor server or network;
+   f. Use the Software for any illegal purpose or in violation of any laws;
+   g. Share your license or access credentials with others;
+   h. Use the Software to compete with Licensor or its products.
+
+3. INTELLECTUAL PROPERTY RIGHTS
+
+The Software is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The Software is licensed, not sold. All title and copyrights in and to the Software (including but not limited to any images, photographs, animations, video, audio, music, text, and "applets" incorporated into the Software), the accompanying printed materials, and any copies of the Software are owned by Licensor or its suppliers. The Software is protected by copyright laws and international treaty provisions. Therefore, you must treat the Software like any other copyrighted material.
+
+4. TERMINATION
+
+This EULA is effective until terminated. Your rights under this EULA will terminate automatically without notice from Licensor if you fail to comply with any term(s) of this EULA. Upon termination of the license, you shall cease all use of the Software and destroy all copies, full or partial, of the Software.
+
+5. NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL LICENSOR OR ITS SUPPLIERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+6. LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+7. EXPORT RESTRICTIONS
+
+You acknowledge that the Software may be subject to export restrictions. You agree to comply with all applicable international and national laws that apply to the Software, including the Export Administration Regulations, as well as end-user, end-use, and destination restrictions issued by governmental agencies.
+
+8. U.S. GOVERNMENT RESTRICTED RIGHTS
+
+The Software is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software - Restricted Rights at 48 CFR 52.227-19, as applicable.
+
+9. GOVERNING LAW
+
+This EULA shall be governed by and construed in accordance with the laws of the jurisdiction in which Licensor is located, without regard to its conflict of law provisions.
+
+10. ENTIRE AGREEMENT
+
+This EULA constitutes the entire agreement between you and Licensor relating to the Software and supersedes all prior or contemporaneous oral or written communications, proposals, and representations with respect to the Software or any other subject matter covered by this EULA.
+
+11. MODIFICATIONS
+
+Licensor reserves the right to modify this EULA at any time. Your continued use of the Software after any such modifications shall constitute your acceptance of the modified EULA.
+
+12. CONTACT INFORMATION
+
+If you have any questions about this EULA, please contact:
+   OktoSeek AI
+   Email: service@oktoseek.com
+   Website: https://www.oktoseek.com
+
+---
+
+Copyright © 2025 OktoSeek AI. All rights reserved.
+
+OktoEngine is a trademark of OktoSeek AI.
+

README.md

@@ -1,5 +1,670 @@
+<p align="center">
+  <img src="./assets/okto_logo.png" alt="OktoEngine Banner" width="50%" />
+</p>
+
+<h1 align="center">OktoEngine</h1>
+
+<p align="center">
+  <strong>Professional CLI Engine for Training AI Models with OktoScript</strong>
+</p>
+
+<p align="center">
+  Built by <strong>OktoSeek AI</strong> for the <strong>OktoSeek ecosystem</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.oktoseek.com/">OktoSeek Homepage</a> •
+  <a href="https://github.com/oktoseek/oktoscript">OktoScript Language</a> •
+  <a href="https://x.com/oktoseek">Twitter</a> •
+  <a href="https://www.youtube.com/@Oktoseek">YouTube</a>
+</p>
+
 ---
-license: other
-license_name: proprietary
-license_link: LICENSE
+
+## Table of Contents
+
+1. [What is OktoEngine?](#-what-is-oktoengine)
+2. [Quick Start](#-quick-start)
+3. [Key Features](#-key-features)
+4. [Installation](#-installation)
+5. [CLI Commands](#️-cli-commands)
+6. [Training Capabilities](#-training-capabilities)
+7. [Debug Mode](#-debug-mode)
+8. [Examples](#-examples)
+9. [System Requirements](#-system-requirements)
+10. [Documentation](#-documentation)
+11. [FAQ](#-frequently-asked-questions-faq)
+12. [License](#-license)
+13. [Contact](#-contact)
+
 ---
+
+## 🚀 Quick Start
+
+**Get started with OktoEngine in 3 steps:**
+
+1. **Download the latest release** from [GitHub Releases](https://github.com/oktoseek/oktoengine/releases)
+2. **Initialize a project:** `okto init my-project`
+3. **Train your model:** `okto train`
+
+```bash
+# Initialize a new project
+okto init my-ai-model
+
+# Navigate to project
+cd my-ai-model
+
+# Validate your OktoScript configuration
+okto validate
+
+# Train your model
+okto train
+```
+
+📚 **Full documentation:** [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)  
+🔍 **CLI Reference:** [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
+
+---
+
+## 🚀 What is OktoEngine?
+
+**OktoEngine** is the official execution engine for **OktoScript**—a powerful CLI tool that transforms declarative AI configurations into trained, production-ready models.
+
+### Built for Scale
+
+OktoEngine is engineered to handle:
+- ✅ **Models of any size** - From millions to billions of parameters
+- ✅ **Complex training pipelines** - Full fine-tuning, LoRA adapters, and more
+- ✅ **Production workloads** - Optimized for real-world AI development
+- ✅ **Enterprise-grade reliability** - Robust error handling and validation
+
+### Why OktoEngine?
+
+**Traditional Approach:**
+```python
+# Hundreds of lines of Python code
+# Complex configuration management
+# Error-prone manual setup
+# Difficult to reproduce
+```
+
+**With OktoEngine:**
+```okt
+PROJECT "MyModel"
+MODEL { base: "gpt2" }
+DATASET { train: "dataset/train.jsonl" }
+TRAIN { epochs: 5, batch_size: 32 }
+EXPORT { format: ["okm"] }
+```
+
+**One command:** `okto train` → **Trained model ready for deployment**
+
+---
+
+## ✨ Key Features
+
+### 🎯 **Complete CLI Interface**
+
+Professional command-line interface with intuitive commands:
+
+**Core Commands:**
+```bash
+okto init          # Initialize new projects
+okto validate      # Validate OktoScript files
+okto train         # Train models
+okto eval          # Evaluate models
+okto export        # Export to multiple formats
+okto convert       # Convert between formats (PyTorch, ONNX, GGUF, TFLite, OktoModel)
+```
+
+**Inference Commands:**
+```bash
+okto infer         # Direct inference (single input/output)
+okto chat          # Interactive chat mode with session context
+```
+
+**Analysis Commands:**
+```bash
+okto compare       # Compare two models (latency, accuracy, loss)
+okto logs          # View historical training logs and CONTROL decisions
+okto tune          # Auto-tune training using CONTROL block logic
+```
+
+**Utility Commands:**
+```bash
+okto list          # List projects, models, datasets, or exports
+okto doctor        # System diagnostics and dependency checking
+okto upgrade       # Auto-update engine to latest version
+okto about         # Engine and language information
+okto exit          # Exit interactive mode
+```
+
+**What you can do:**
+- 🚀 **Train** models with full fine-tuning or LoRA adapters
+- 🔄 **Convert** models between formats for different deployment targets
+- 💬 **Chat** interactively with trained models
+- 📊 **Compare** model versions to find the best one
+- 📈 **Monitor** training with real-time logs and metrics
+- 🎛️ **Auto-tune** training parameters intelligently
+- 🔍 **Validate** configurations before training
+- 📦 **Export** to production-ready formats
+
+### 🔧 **Advanced Training Capabilities**
+
+**Training Methods:**
+- **Full Fine-tuning** - Train entire models from scratch with complete parameter updates
+- **LoRA Fine-tuning** - Efficient adapter-based training (LoRA, QLoRA, PEFT) with minimal memory footprint
+- **Multi-dataset Training** - Combine multiple datasets with weighted sampling and custom mixing strategies
+- **Model Adapters** - Apply pre-trained adapters (LoRA/PEFT) to base models for rapid customization
+
+**Intelligent Training Control:**
+- **Automatic Checkpointing** - Never lose progress with smart checkpoint management
+- **Real-time Metrics** - Monitor training in the terminal with live updates
+- **CONTROL Block** - Define conditional logic (IF, WHEN, EVERY) for autonomous decision-making
+- **Auto-parameter Adjustment** - Automatically adjust learning rate, batch size, and other parameters based on metrics
+- **Early Stopping** - Intelligent stopping when model performance plateaus or diverges
+- **Memory-aware Training** - Automatically reduce batch size when GPU memory is low
+
+**Monitoring & Governance:**
+- **MONITOR Block** - Track any metric (loss, accuracy, GPU usage, throughput, latency, confidence, etc.)
+- **GUARD Block** - Safety and ethics protection (hallucination, toxicity, bias detection)
+- **BEHAVIOR Block** - Control model personality, verbosity, language, and response style
+- **STABILITY Block** - Training safety controls (NaN detection, divergence prevention)
+- **EXPLORER Block** - AutoML-style hyperparameter search and optimization
+
+**What makes it unique:**
+- 🧠 **Decision-driven** - Models can make autonomous decisions during training
+- 🔄 **Self-adapting** - Automatically adjusts parameters based on real-time metrics
+- 🛡️ **Safe by design** - Built-in safety guards and content filtering
+- 📊 **Fully observable** - Complete visibility into training process and decisions
+- ⚡ **Production-ready** - Export to multiple formats for deployment
+
+### 📊 **Detailed Metrics & Monitoring**
+
+Real-time training metrics displayed directly in your terminal:
+
+```
+🚀 Starting training pipeline...
+
+Epoch 1/5: 100%|████████████| 500/500 [02:15<00:00, 3.70it/s]
+  Loss: 2.345 → 1.892
+  Learning Rate: 5e-5
+  GPU Memory: 8.2GB / 12GB
+
+Epoch 2/5: 100%|████████████| 500/500 [02:14<00:00, 3.72it/s]
+  Loss: 1.892 → 1.654
+  ...
+```
+
+### 🐛 **Debug Mode**
+
+Comprehensive debug mode for troubleshooting:
+
+```bash
+okto train --debug
+okto validate --debug
+```
+
+Shows detailed parsing logs, execution flow, and error diagnostics.
+
+### 🔄 **Automatic Updates**
+
+Built-in upgrade system:
+
+```bash
+okto upgrade
+```
+
+Automatically downloads and installs the latest version from GitHub Releases.
+
+### 🏥 **System Diagnostics**
+
+Comprehensive environment checking:
+
+```bash
+okto doctor
+```
+
+Checks GPU, CUDA, RAM, dependencies, and provides recommendations.
+
+### 📦 **Dependency Management**
+
+Automatic dependency installation:
+
+```bash
+okto doctor --install
+```
+
+Installs missing dependencies automatically.
+
+---
+
+## 📥 Installation
+
+### Download Pre-built Binaries
+
+Download the latest release for your platform:
+
+- **Windows:** `okto-windows.exe`
+- **Linux:** `okto-linux`
+- **macOS:** `okto-macos`
+
+Available at: [GitHub Releases](https://github.com/oktoseek/oktoengine/releases)
+
+### Upgrade Existing Installation
+
+```bash
+okto upgrade
+```
+
+Automatically updates to the latest version.
+
+---
+
+## 🖥️ CLI Commands
+
+### Core Commands
+
+**Initialize Project:**
+```bash
+okto init my-project
+```
+Creates a new OktoScript project with proper folder structure.
+
+**Validate Configuration:**
+```bash
+okto validate
+okto validate --file scripts/train.okt
+```
+Validates OktoScript syntax and configuration.
+
+**Train Model:**
+```bash
+okto train
+okto train --file scripts/train.okt
+okto train --debug  # Enable debug mode
+```
+Executes the complete training pipeline.
+
+**Evaluate Model:**
+```bash
+okto eval --file scripts/train.okt
+```
+Evaluates a trained model against test datasets.
+
+**Export Model:**
+```bash
+okto export --format okm --file scripts/train.okt
+okto export --format onnx
+```
+Exports trained models to various formats.
+
+**Convert Model Formats:**
+```bash
+okto convert --input model.pt --from pt --to gguf --output model.gguf
+okto convert --input model.pt --from pt --to onnx --output model.onnx
+```
+Converts models between different formats (PyTorch, ONNX, GGUF, TFLite, OktoModel).
+
+**Direct Inference:**
+```bash
+okto infer --model models/chatbot.okm --text "Hello, how can I help?"
+```
+Runs single inference on a trained model. Automatically respects BEHAVIOR, GUARD, INFERENCE, and CONTROL blocks.
+
+**Interactive Chat:**
+```bash
+okto chat --model models/chatbot.okm
+```
+Starts an interactive chat session. Uses BEHAVIOR settings, enforces GUARD rules, and supports session context.
+
+**Compare Models:**
+```bash
+okto compare models/v1.okm models/v2.okm
+```
+Compares two models on latency, accuracy, loss, and resource usage.
+
+**View Logs:**
+```bash
+okto logs my-model
+```
+Views historical training logs, metrics, and CONTROL decisions.
+
+**Auto-tune Training:**
+```bash
+okto tune
+```
+Uses CONTROL block to auto-adjust training parameters (learning rate, batch size, early stopping).
+
+### Utility Commands
+
+**System Diagnostics:**
+```bash
+okto doctor              # Check system
+okto doctor --install    # Auto-install dependencies
+```
+
+**Upgrade Engine:**
+```bash
+okto upgrade
+```
+
+**List Resources:**
+```bash
+okto list projects
+okto list models
+okto list datasets
+okto list exports
+```
+
+**Other Commands:**
+```bash
+okto about      # Show information
+okto --version  # Show version
+okto exit       # Exit interactive mode
+```
+
+📚 **Complete CLI Reference:** [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
+Automatically updates to the latest version.
+
+**About:**
+```bash
+okto about
+```
+Shows information about OktoEngine and OktoScript.
+
+**List Resources:**
+```bash
+okto list projects
+okto list models
+okto list datasets
+```
+
+### Global Flags
+
+```bash
+--debug    # Enable debug mode (detailed logs)
+--help     # Show help
+--version  # Show version
+```
+
+📖 **Complete CLI Reference:** [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
+
+---
+
+## 🎓 Training Capabilities
+
+### Supported Model Sizes
+
+OktoEngine can train models of any size:
+
+- **Small Models** (1M - 100M parameters) - Fast training, minimal resources
+- **Medium Models** (100M - 1B parameters) - Balanced performance
+- **Large Models** (1B - 7B parameters) - Requires GPU, optimized training
+- **Very Large Models** (7B+ parameters) - Enterprise-grade, multi-GPU support
+
+### Training Methods
+
+**Full Fine-tuning:**
+```okt
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  device: "auto"
+}
+```
+
+**LoRA Fine-tuning:**
+```okt
+FT_LORA {
+  lora_rank: 8
+  lora_alpha: 32
+  epochs: 3
+}
+```
+
+### Automatic Optimizations
+
+- **Mixed Precision Training** - FP16/BF16 support
+- **Gradient Accumulation** - Train large models on smaller GPUs
+- **Automatic Device Selection** - CPU/GPU/CUDA detection
+- **Memory Optimization** - Efficient memory management
+- **Checkpoint Management** - Automatic saving and resuming
+
+---
+
+## 🐛 Debug Mode
+
+Debug mode provides detailed insights into the engine's operation:
+
+### Enable Debug Mode
+
+```bash
+# Via command flag
+okto train --debug
+okto validate --debug
+
+# Via environment variable
+OKTO_DEBUG=1 okto train
+```
+
+### What Debug Mode Shows
+
+**Parsing Details:**
+```
+DEBUG: Starting parse_oktoscript. Input preview: '# okto_version: "1.0" PROJECT...'
+DEBUG: Parsed version: Some("1.0")
+DEBUG: Parsed project: my-model
+DEBUG: After PROJECT, remaining input: 'ENV { accelerator: "gpu"...'
+```
+
+**Execution Flow:**
+```
+DEBUG: Attempting to parse ENV block...
+DEBUG: Parsed ENV field: accelerator = gpu
+DEBUG: Parsed ENV field: precision = fp16
+DEBUG: Successfully parsed ENV block with 5 fields
+```
+
+**Error Diagnostics:**
+```
+DEBUG: Failed to parse key in ENV block. Input: 'accelerator: "gpu"...'
+DEBUG: Failed to parse ':' after key 'accelerator'. Input: '"gpu"...'
+```
+
+### Use Cases
+
+- **Troubleshooting parsing errors** - See exactly where parsing fails
+- **Understanding execution flow** - Track how your configuration is processed
+- **Performance analysis** - Identify bottlenecks
+- **Configuration debugging** - Verify your OktoScript is parsed correctly
+
+📖 **Debug Guide:** [`docs/DEBUG_GUIDE.md`](./docs/DEBUG_GUIDE.md)
+
+---
+
+## 📚 Examples
+
+### Basic Training Example
+
+**scripts/train.okt:**
+```okt
+PROJECT "ChatBot"
+ENV {
+  accelerator: "gpu"
+  precision: "fp16"
+  install_missing: true
+}
+DATASET {
+  train: "dataset/train.jsonl"
+  validation: "dataset/val.jsonl"
+}
+MODEL {
+  base: "gpt2"
+}
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  device: "auto"
+}
+EXPORT {
+  format: ["okm"]
+  path: "export/"
+}
+```
+
+**Terminal Output:**
+```bash
+$ okto train
+
+🐙 OktoEngine v0.1
+📄 Reading: "scripts/train.okt"
+
+📊 Environment Check:
+  ✔ Runtime: Python 3.14.0
+  ✔ GPU: NVIDIA GeForce RTX 4070
+  ✔ RAM: 63GB (40GB available)
+  ✔ Platform: windows
+
+📦 Checking dependencies...
+  ✔ All dependencies available
+
+🚀 Starting training pipeline...
+
+Epoch 1/5: 100%|████████████| 500/500 [02:15<00:00, 3.70it/s]
+  Loss: 2.345 → 1.892
+  Learning Rate: 5e-5
+
+✅ Training completed successfully!
+📁 Output: runs/ChatBot/
+```
+
+### Advanced Example with LoRA
+
+See [`examples/lora-training.okt`](./examples/lora-training.okt) for a complete LoRA fine-tuning example.
+
+### Complete Project Examples
+
+- [`examples/basic-training/`](./examples/basic-training/) - Minimal working example
+- [`examples/chatbot/`](./examples/chatbot/) - Conversational AI training
+- [`examples/vision-model/`](./examples/vision-model/) - Computer vision pipeline
+
+📖 **More Examples:** [`examples/README.md`](./examples/README.md)
+
+---
+
+## 💻 System Requirements
+
+### Minimum Requirements
+
+- **OS:** Windows 10+, Linux (Ubuntu 20.04+), macOS 11+
+- **RAM:** 8GB (16GB recommended)
+- **Storage:** 10GB free space
+- **Runtime:** Compatible runtime environment
+
+### Recommended for Training
+
+- **GPU:** NVIDIA GPU with CUDA support (8GB+ VRAM)
+- **RAM:** 32GB+ for large models
+- **Storage:** SSD with 50GB+ free space
+- **CPU:** Multi-core processor (8+ cores)
+
+### Check Your System
+
+```bash
+okto doctor
+```
+
+Shows detailed system information and recommendations.
+
+---
+
+## 📚 Documentation
+
+Complete documentation for OktoEngine:
+
+- 📖 **[Getting Started Guide](./docs/GETTING_STARTED.md)** - Your first 5 minutes
+- 🖥️ **[CLI Reference](./docs/CLI_REFERENCE.md)** - Complete command reference
+- 🐛 **[Debug Guide](./docs/DEBUG_GUIDE.md)** - Debug mode usage
+- 💡 **[Examples](./examples/)** - Working examples
+- ❓ **[FAQ](./docs/FAQ.md)** - Frequently Asked Questions
+- 📋 **[Changelog](./CHANGELOG.md)** - Version history
+
+### Advanced Topics
+
+- **Training Optimization** - Best practices for efficient training
+- **Error Handling** - Troubleshooting common issues
+- **Performance Tuning** - Maximize training speed
+- **Integration** - Using OktoEngine in your workflow
+
+---
+
+## ❓ Frequently Asked Questions (FAQ)
+
+**Q: What models can I train with OktoEngine?**  
+A: OktoEngine supports any model compatible with modern AI frameworks. From small models (millions of parameters) to large language models (billions of parameters).
+
+**Q: Do I need to know Python to use OktoEngine?**  
+A: No! OktoEngine provides a complete CLI interface. You only need to write OktoScript configuration files.
+
+**Q: Can I train models without a GPU?**  
+A: Yes, OktoEngine automatically detects available hardware and uses CPU when GPU is not available. Training will be slower but fully functional.
+
+**Q: How do I update OktoEngine?**  
+A: Simply run `okto upgrade` to automatically download and install the latest version.
+
+**Q: What formats can I export to?**  
+A: OktoEngine supports multiple export formats: OKM (OktoSeek), ONNX, GGUF, SafeTensors, and more.
+
+**Q: Can I resume training from a checkpoint?**  
+A: Yes, OktoEngine automatically saves checkpoints and can resume training from any checkpoint.
+
+📖 **[Complete FAQ →](./docs/FAQ.md)**
+
+---
+
+## 🔮 Future Integration
+
+OktoEngine will be integrated into **OktoSeek IDE** for visual training workflows:
+
+- 🎯 **Visual Pipeline Builder** - Drag-and-drop training configuration
+- 📊 **Real-time Dashboard** - Live training metrics and visualization
+- 🔄 **One-click Training** - Train models directly from the IDE
+- 📁 **Project Management** - Organize and manage multiple training projects
+
+---
+
+## 🐙 Powered by OktoSeek AI
+
+**OktoEngine** is developed and maintained by **OktoSeek AI**.
+
+- **Official website:** https://www.oktoseek.com
+- **OktoScript Language:** https://github.com/oktoseek/oktoscript
+- **Twitter:** https://x.com/oktoseek
+- **YouTube:** https://www.youtube.com/@Oktoseek
+- **Repository:** https://github.com/oktoseek/oktoengine
+
+---
+
+## 📄 License
+
+This software is proprietary and licensed under the End User License Agreement (EULA). See [LICENSE](./LICENSE) file for details.
+
+**Important:** OktoEngine is not open source. Binary releases are available for download, but the source code is proprietary.
+
+---
+
+## 📧 Contact
+
+For questions, support, or licensing inquiries:
+
+- **Email:** service@oktoseek.com
+- **GitHub Issues:** https://github.com/oktoseek/oktoengine/issues
+- **Website:** https://www.oktoseek.com
+
+---
+
+<p align="center">
+  Made with ❤️ by the <strong>OktoSeek AI</strong> team
+</p>
+

assets/IMAGE_REQUIREMENTS.md

@@ -0,0 +1,319 @@
+# Requisitos de Imagens para OktoEngine GitHub
+
+Lista completa de imagens necessárias para a documentação do OktoEngine.
+
+---
+
+## 📸 Imagens Obrigatórias
+
+### 1. Logo Principal
+**Arquivo:** `okto_logo.png`  
+**Uso:** Logo principal do OktoEngine no README  
+**Tamanho recomendado:** 800x200px ou similar (proporção 4:1)  
+**Formato:** PNG com fundo transparente  
+**Onde é usado:** Topo do README.md
+
+---
+
+### 2. Logo Alternativo
+**Arquivo:** `okto_logo2.png`  
+**Uso:** Logo alternativo (opcional, pode ser o mesmo do OktoScript)  
+**Tamanho recomendado:** 800x200px  
+**Formato:** PNG  
+**Onde é usado:** README.md (seguindo padrão OktoScript)
+
+---
+
+### 3. Screenshot - Comando `okto validate`
+**Arquivo:** `terminal-validate.png`  
+**Descrição:** Screenshot do terminal mostrando `okto validate` sendo executado  
+**O que mostrar:**
+- Comando `okto validate` sendo executado
+- Saída de validação bem-sucedida
+- Mensagens de sucesso e resumo
+
+**Exemplo do que capturar:**
+```
+PS D:\projects\my-project> okto validate
+
+🐙 OktoEngine v0.1
+🔍 Validating OktoScript file: "scripts/train.okt"
+📄 File: "scripts/train.okt"
+📄 Size: 382 bytes
+📄 Lines: 31
+
+✔ File parsed successfully
+
+📋 Validation Results:
+✅ Validation passed! No errors or warnings.
+
+📊 Summary:
+  Project: my-project
+  ENV: Configured
+  Dataset: dataset/train.jsonl
+  Model: gpt2
+  Training: 5 epochs, batch size 32
+  Export: ["okm"]
+```
+
+---
+
+### 4. Screenshot - Comando `okto train`
+**Arquivo:** `terminal-train.png`  
+**Descrição:** Screenshot do terminal mostrando `okto train` em execução  
+**O que mostrar:**
+- Comando `okto train` sendo executado
+- Environment check
+- Progresso do treinamento (barra de progresso)
+- Métricas em tempo real
+- Mensagem de sucesso
+
+**Exemplo do que capturar:**
+```
+PS D:\projects\my-project> okto train
+
+🐙 OktoEngine v0.1
+📄 Reading: "scripts/train.okt"
+
+📊 Environment Check:
+  ✔ Runtime: Python 3.14.0
+  ✔ GPU: NVIDIA GeForce RTX 4070
+  ✔ RAM: 63GB (40GB available)
+  ✔ Platform: windows
+
+📦 Checking dependencies...
+  ✔ All dependencies available
+
+🚀 Starting training pipeline...
+
+Epoch 1/5: 100%|████████████| 500/500 [02:15<00:00, 3.70it/s]
+  Loss: 2.345 → 1.892
+  Learning Rate: 5e-5
+  GPU Memory: 8.2GB / 12GB
+
+✅ Training completed successfully!
+📁 Output: runs/my-project/
+```
+
+---
+
+### 5. Screenshot - Comando `okto doctor`
+**Arquivo:** `terminal-doctor.png`  
+**Descrição:** Screenshot do terminal mostrando `okto doctor`  
+**O que mostrar:**
+- Comando `okto doctor` sendo executado
+- Diagnóstico completo do sistema
+- Todas as verificações (GPU, CUDA, RAM, etc.)
+- Status de dependências
+
+**Exemplo do que capturar:**
+```
+PS D:\projects> okto doctor
+
+🐙 OktoEngine v0.1 - System Diagnostics
+
+🖥️  Platform: Windows
+💾 RAM: 63GB total, 40GB available
+⚙️  CPU: 32 cores
+🎮 GPU: Checking...
+  ✔ GPU found: NVIDIA GeForce RTX 4070 Laptop GPU
+🔧 CUDA: Checking...
+  ✔ CUDA available: 576.02
+🔧 Runtime: Checking...
+  ✔ Runtime available: Python 3.14.0
+📦 Dependencies: Checking...
+  ✔ All required packages installed
+
+✅ Diagnostics complete
+```
+
+---
+
+### 6. Screenshot - Modo Debug
+**Arquivo:** `terminal-debug.png`  
+**Descrição:** Screenshot do terminal mostrando `okto train --debug`  
+**O que mostrar:**
+- Comando `okto train --debug` sendo executado
+- Logs de debug detalhados
+- Parsing logs
+- Execution flow
+
+**Exemplo do que capturar:**
+```
+PS D:\projects\my-project> okto train --debug
+
+🐙 OktoEngine v0.1
+📄 Reading: "scripts/train.okt"
+
+DEBUG: Starting parse_oktoscript. Input preview: '# okto_version: "1.0" PROJECT...'
+DEBUG: Parsed version: Some("1.0")
+DEBUG: Parsed project: my-project
+DEBUG: After PROJECT, remaining input: 'ENV { accelerator: "gpu"...'
+DEBUG: Attempting to parse ENV block...
+DEBUG: Parsed ENV field: accelerator = gpu
+DEBUG: Parsed ENV field: precision = fp16
+DEBUG: Successfully parsed ENV block with 5 fields
+...
+```
+
+---
+
+### 7. Screenshot - Comando `okto upgrade`
+**Arquivo:** `terminal-upgrade.png`  
+**Descrição:** Screenshot do terminal mostrando `okto upgrade`  
+**O que mostrar:**
+- Comando `okto upgrade` sendo executado
+- Verificação de atualizações
+- Download em progresso (barra de progresso)
+- Mensagem de sucesso
+
+**Exemplo do que capturar:**
+```
+PS D:\projects> okto upgrade
+
+🐙 OktoEngine Upgrader
+Current version: 0.1.0
+🔍 Checking for updates...
+
+📦 Downloading OktoEngine v0.2.0...
+████████████████████ 100% [00:15<00:00]
+
+✅ Updated successfully to v0.2.0
+```
+
+---
+
+### 8. Screenshot - Comando `okto about`
+**Arquivo:** `terminal-about.png`  
+**Descrição:** Screenshot do terminal mostrando `okto about`  
+**O que mostrar:**
+- Comando `okto about` sendo executado
+- Informações sobre OktoScript e OktoEngine
+- Links e referências
+
+---
+
+### 9. Screenshot - Comando `okto init`
+**Arquivo:** `terminal-init.png`  
+**Descrição:** Screenshot do terminal mostrando `okto init`  
+**O que mostrar:**
+- Comando `okto init my-project` sendo executado
+- Mensagem de sucesso
+- Estrutura de pastas criada
+
+---
+
+### 10. Screenshot - Erro com Debug (Opcional)
+**Arquivo:** `terminal-error-debug.png`  
+**Descrição:** Screenshot mostrando erro com debug mode ativado  
+**O que mostrar:**
+- Erro ocorrendo
+- Debug logs mostrando onde falhou
+- Mensagens de erro detalhadas
+
+---
+
+## 📋 Checklist de Imagens
+
+Use esta checklist ao capturar as imagens:
+
+- [ ] `okto_logo.png` - Logo principal
+- [ ] `okto_logo2.png` - Logo alternativo (opcional)
+- [ ] `terminal-validate.png` - Validação
+- [ ] `terminal-train.png` - Treinamento
+- [ ] `terminal-doctor.png` - Diagnóstico
+- [ ] `terminal-debug.png` - Modo debug
+- [ ] `terminal-upgrade.png` - Atualização
+- [ ] `terminal-about.png` - Informações
+- [ ] `terminal-init.png` - Inicialização
+- [ ] `terminal-error-debug.png` - Erro com debug (opcional)
+
+---
+
+## 🎨 Especificações Técnicas
+
+### Formato
+- **Tipo:** PNG (preferido) ou JPEG
+- **Qualidade:** Alta resolução
+- **Tamanho máximo:** 2MB por imagem
+
+### Dimensões
+- **Screenshots de terminal:** 1920x1080 ou maior
+- **Logos:** Proporção 4:1 (ex: 800x200px)
+- **Banners:** Proporção 16:9 (ex: 1920x1080px)
+
+### Estilo
+- **Fundo:** Escuro (terminal) ou claro (dependendo do tema)
+- **Texto:** Legível e nítido
+- **Cores:** Manter cores originais do terminal
+- **Emojis:** Mostrar emojis se visíveis no terminal
+
+---
+
+## 📝 Como Capturar
+
+### Windows
+1. Abra o terminal (PowerShell ou CMD)
+2. Execute o comando
+3. Use `Win + Shift + S` para captura de tela
+4. Ou use ferramenta de screenshot
+5. Salve como PNG
+
+### Linux
+1. Use `gnome-screenshot` ou `scrot`
+2. Ou `Shift + Print Screen`
+3. Salve como PNG
+
+### macOS
+1. Use `Cmd + Shift + 4` para captura de área
+2. Ou `Cmd + Shift + 3` para tela inteira
+3. Salve como PNG
+
+---
+
+## 📍 Onde Usar Cada Imagem
+
+### README.md
+- `okto_logo.png` - Topo do README
+- `okto_logo2.png` - Logo alternativo (se usado)
+- `terminal-train.png` - Seção de exemplos
+- `terminal-validate.png` - Seção de validação
+
+### docs/GETTING_STARTED.md
+- `terminal-init.png` - Seção de inicialização
+- `terminal-validate.png` - Seção de validação
+- `terminal-train.png` - Seção de treinamento
+
+### docs/CLI_REFERENCE.md
+- Screenshots de cada comando nas respectivas seções
+
+### docs/DEBUG_GUIDE.md
+- `terminal-debug.png` - Exemplo de debug mode
+- `terminal-error-debug.png` - Exemplo de erro com debug
+
+---
+
+## ✅ Checklist Final
+
+Antes de enviar as imagens, verifique:
+
+- [ ] Todas as imagens têm os nomes corretos
+- [ ] Imagens estão em formato PNG ou JPEG
+- [ ] Texto está legível
+- [ ] Cores estão corretas
+- [ ] Tamanho está adequado (< 2MB)
+- [ ] Resolução é suficiente (1920x1080+)
+- [ ] Screenshots mostram comandos reais funcionando
+
+---
+
+## 📧 Envio
+
+Envie as imagens com os nomes exatos listados acima para:
+- **Email:** service@oktoseek.com
+- **Ou adicione diretamente na pasta `assets/`**
+
+---
+
+**Nota:** Se alguma imagem não estiver disponível, podemos usar placeholders temporários ou criar screenshots de exemplo.
+

docs/CLI_REFERENCE.md

@@ -0,0 +1,1173 @@
+# OktoEngine CLI Reference
+
+Complete reference for all OktoEngine CLI commands and options.
+
+---
+
+## Table of Contents
+
+1. [Command Overview](#command-overview)
+2. [Core Commands](#core-commands)
+3. [Utility Commands](#utility-commands)
+4. [Global Flags](#global-flags)
+5. [Examples](#examples)
+
+---
+
+## Command Overview
+
+```bash
+okto [FLAGS] <COMMAND>
+```
+
+### Available Commands
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `init` | Initialize new project | `okto init <name>` |
+| `validate` | Validate OktoScript file | `okto validate [--file <path>]` |
+| `train` | Train a model | `okto train [--file <path>]` |
+| `eval` | Evaluate a model | `okto eval [--file <path>]` |
+| `export` | Export a model | `okto export [--format <fmt>] [--file <path>]` |
+| `convert` | Convert model formats | `okto convert --input <path> --from <fmt> --to <fmt> --output <path>` |
+| `infer` | Direct inference (single input/output) | `okto infer --model <path> --text "<input>"` |
+| `chat` | Interactive chat mode | `okto chat --model <path>` |
+| `compare` | Compare two models | `okto compare <model1> <model2>` |
+| `logs` | View historical logs | `okto logs <model_or_run_id>` |
+| `tune` | Auto-tune training | `okto tune [--file <path>]` |
+| `list` | List resources | `okto list <projects|models|datasets|exports>` |
+| `doctor` | System diagnostics | `okto doctor [--install]` |
+| `about` | Show information | `okto about` |
+| `upgrade` | Upgrade engine | `okto upgrade` |
+| `exit` | Exit interactive mode | `okto exit` |
+
+---
+
+## Core Commands
+
+### `okto init`
+
+Initialize a new OktoScript project with proper folder structure.
+
+**Usage:**
+```bash
+okto init <project-name>
+```
+
+**Example:**
+```bash
+okto init my-ai-model
+```
+
+**Creates:**
+```
+my-ai-model/
+├── scripts/
+│   └── train.okt
+├── dataset/
+│   ├── train.jsonl
+│   └── val.jsonl
+└── export/
+```
+
+**Output:**
+```
+🚀 Initializing OktoScript project: my-ai-model
+✅ Project 'my-ai-model' initialized successfully!
+
+Next steps:
+  cd my-ai-model
+  okto validate
+  okto train
+```
+
+---
+
+### `okto validate`
+
+Validate an OktoScript file for syntax errors and configuration issues.
+
+**Usage:**
+```bash
+okto validate [--file <path>]
+okto validate -f scripts/train.okt
+```
+
+**Default:** Validates `scripts/train.okt` in current directory
+
+**Options:**
+- `-f, --file <PATH>` - Path to OktoScript file
+
+**Example:**
+```bash
+okto validate
+okto validate --file scripts/train.okt
+okto validate --debug  # Enable debug mode
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1
+🔍 Validating OktoScript file: "scripts/train.okt"
+📄 File: "scripts/train.okt"
+📄 Size: 382 bytes
+📄 Lines: 31
+
+✔ File parsed successfully
+
+📋 Validation Results:
+✅ Validation passed! No errors or warnings.
+
+📊 Summary:
+  Project: my-model
+  ENV: Configured
+  Dataset: dataset/train.jsonl
+  Model: gpt2
+  Training: 5 epochs, batch size 32
+  Export: ["okm"]
+```
+
+**Exit Codes:**
+- `0` - Validation passed
+- `1` - Validation failed
+
+---
+
+### `okto train`
+
+Train a model from an OktoScript configuration file.
+
+**Usage:**
+```bash
+okto train [--file <path>]
+okto train -f scripts/train.okt
+```
+
+**Default:** Uses `scripts/train.okt` in current directory
+
+**Options:**
+- `-f, --file <PATH>` - Path to OktoScript file
+- `--debug` - Enable debug mode
+
+**Example:**
+```bash
+okto train
+okto train --file scripts/train.okt
+okto train --debug  # Show detailed logs
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1
+📄 Reading: "scripts/train.okt"
+
+📊 Environment Check:
+  ✔ Runtime: Python 3.14.0
+  ✔ GPU: NVIDIA GeForce RTX 4070
+  ✔ RAM: 63GB (40GB available)
+  ✔ Platform: windows
+
+📦 Checking dependencies...
+  ✔ All dependencies available
+
+🚀 Starting training pipeline...
+
+Epoch 1/5: 100%|████████████| 500/500 [02:15<00:00, 3.70it/s]
+  Loss: 2.345 → 1.892
+  Learning Rate: 5e-5
+  GPU Memory: 8.2GB / 12GB
+
+✅ Training completed successfully!
+📁 Output: runs/my-model/
+```
+
+**What it does:**
+1. Parses and validates OktoScript file
+2. Checks system environment
+3. Verifies dependencies
+4. Loads dataset
+5. Initializes model
+6. Executes training loop
+7. Saves checkpoints
+8. Exports model (if configured)
+
+---
+
+### `okto eval`
+
+Evaluate a trained model against test datasets.
+
+**Usage:**
+```bash
+okto eval [--file <path>]
+okto eval -f scripts/train.okt
+```
+
+**Options:**
+- `-f, --file <PATH>` - Path to OktoScript file
+
+**Example:**
+```bash
+okto eval
+okto eval --file scripts/train.okt
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1
+📊 Evaluating model...
+
+📈 Evaluation Results:
+  Accuracy: 0.892
+  Loss: 1.234
+  Perplexity: 2.456
+  F1-Score: 0.876
+
+✅ Evaluation completed!
+```
+
+---
+
+### `okto export`
+
+Export a trained model to various formats.
+
+**Usage:**
+```bash
+okto export [--format <fmt>] [--file <path>]
+okto export --format okm
+okto export --format onnx --file scripts/train.okt
+```
+
+**Options:**
+- `-f, --format <FORMAT>` - Export format (okm, onnx, gguf, safetensors)
+- `--file <PATH>` - Path to OktoScript file
+
+**Supported Formats:**
+- `okm` - OktoSeek Model format (optimized)
+- `onnx` - ONNX format (universal)
+- `gguf` - GGUF format (local inference)
+- `safetensors` - SafeTensors format (HuggingFace)
+
+**Example:**
+```bash
+okto export --format okm
+okto export --format onnx
+okto export --format okm,onnx  # Multiple formats
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1
+📦 Exporting model...
+
+✅ Exported to: export/model.okm
+✅ Exported to: export/model.onnx
+
+📁 Export directory: export/
+```
+
+---
+
+### `okto list`
+
+List available projects, models, or datasets.
+
+**Usage:**
+```bash
+okto list <projects|models|datasets>
+```
+
+**Examples:**
+```bash
+okto list projects
+okto list models
+okto list datasets
+```
+
+**Output:**
+```
+📋 Available Projects:
+  • my-chatbot
+  • vision-model
+  • recommender-system
+
+📋 Available Models:
+  • runs/my-chatbot/checkpoint-500
+  • runs/vision-model/checkpoint-1000
+
+📋 Available Datasets:
+  • dataset/train.jsonl
+  • dataset/val.jsonl
+  • dataset/test.jsonl
+```
+
+---
+
+### `okto convert`
+
+Convert a trained model between different formats.
+
+**Usage:**
+```bash
+okto convert --input <model_path> --from <format> --to <format> --output <output_path>
+```
+
+**Options:**
+- `--input <PATH>` - Path to input model file
+- `--from <FORMAT>` - Source format (pt, bin, onnx, tflite, gguf, okm, safetensors)
+- `--to <FORMAT>` - Target format (onnx, tflite, gguf, okm, safetensors)
+- `--output <PATH>` - Path to output file
+
+**Supported Formats:**
+
+| Format | From | To | Usage |
+|--------|------|-----|-------|
+| `pt`, `bin` | ✅ | ❌ | PyTorch format |
+| `onnx` | ✅ | ✅ | Web / Interoperability |
+| `tflite` | ✅ | ✅ | Mobile (Android / iOS) |
+| `gguf` | ✅ | ✅ | Local LLMs (llama.cpp) |
+| `okm` | ✅ | ✅ | Okto Model Format |
+| `safetensors` | ✅ | ✅ | Safe and fast |
+
+**Examples:**
+
+```bash
+# PyTorch → GGUF (local inference)
+okto convert --input model.pt --from pt --to gguf --output model.gguf
+
+# PyTorch → TFLite (mobile)
+okto convert --input model.pt --from pt --to tflite --output model.tflite
+
+# PyTorch → ONNX (web)
+okto convert --input model.pt --from pt --to onnx --output model.onnx
+
+# ONNX → OktoModel (OktoSeek optimized)
+okto convert --input model.onnx --from onnx --to okm --output model.okm
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1
+🔄 Converting model...
+
+📦 Input: model.pt (PyTorch format)
+📦 Output: model.gguf (GGUF format)
+
+⏳ Converting...
+  ✓ Loading model: model.pt
+  ✓ Quantizing to GGUF...
+  ✓ Writing output: model.gguf
+
+✅ Conversion completed!
+📁 Output: model.gguf (245 MB)
+```
+
+---
+
+### `okto infer`
+
+Run direct inference on a trained model (single input/output).
+
+**Usage:**
+```bash
+okto infer --model <model_path> --text "<input>"
+```
+
+**Options:**
+- `--model <PATH>` - Path to trained model
+- `--text <STRING>` - Input text for inference
+
+**What it respects:**
+- `BEHAVIOR` block settings (personality, verbosity, language)
+- `GUARD` block rules (safety, content filtering)
+- `INFERENCE` block parameters (temperature, max_length, etc.)
+- `CONTROL` block logic (if defined)
+
+**Example:**
+```bash
+okto infer --model models/pizzabot.okm --text "Good evening, I want a pizza"
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1
+🤖 Loading model: models/pizzabot.okm
+
+📋 Model Configuration:
+  ✓ BEHAVIOR: friendly, medium verbosity, English
+  ✓ GUARD: toxicity, bias, hallucination protection enabled
+  ✓ INFERENCE: temperature=0.7, max_length=120
+
+💭 Input: "Good evening, I want a pizza"
+
+🤖 Processing...
+  ✓ Guard check passed
+  ✓ Inference parameters applied
+  ✓ CONTROL rules evaluated
+
+📤 Output: "Good evening! I'd be happy to help you order a pizza. What size and toppings would you like?"
+
+✅ Inference completed in 0.23s
+```
+
+**Advanced Example with Multiple Inputs:**
+```bash
+# Single inference
+okto infer --model models/chatbot.okm --text "What are your business hours?"
+
+# Batch inference (via file)
+echo "What are your business hours?" > input.txt
+echo "Do you deliver?" >> input.txt
+okto infer --model models/chatbot.okm --file input.txt
+```
+
+**Error Handling:**
+```
+⚠️  Guard violation detected: toxicity
+🛡️  Content blocked by GUARD rules
+📤 Output: "Sorry, this request is not allowed."
+```
+
+---
+
+### `okto chat`
+
+Start an interactive chat session with a trained model.
+
+**Usage:**
+```bash
+okto chat --model <model_path>
+```
+
+**Options:**
+- `--model <PATH>` - Path to trained model
+
+**Features:**
+- Uses `prompt_style` from BEHAVIOR block
+- Respects BEHAVIOR settings (personality, verbosity, language)
+- Enforces GUARD rules in real-time
+- Can use MEMORY in the future (session context)
+- Type `/exit` or `exit` to quit
+
+**Example:**
+```bash
+okto chat --model models/pizzabot.okm
+```
+
+**Interactive Session:**
+```
+🐙 OktoEngine v0.1
+🤖 Loading model: models/pizzabot.okm
+
+📋 Model Configuration:
+  ✓ BEHAVIOR: friendly, medium verbosity, English
+  ✓ GUARD: enabled
+  ✓ INFERENCE: chat mode
+  ✓ Exit command: /exit
+
+🟢 Okto Chat started (type '/exit' to quit)
+
+─────────────────────────────────────────
+
+You: hi
+Bot: Hello! How can I help you today?
+
+You: what flavors do you have?
+Bot: We have a great selection of pizza flavors! Here are some popular options:
+
+  • Margherita - Classic tomato, mozzarella, and basil
+  • Pepperoni - Spicy pepperoni with mozzarella
+  • Four Cheese - Mozzarella, gorgonzola, parmesan, and provolone
+  • Hawaiian - Ham and pineapple
+  • Vegetarian - Fresh vegetables and herbs
+
+  What sounds good to you?
+
+You: do you deliver?
+Bot: Yes, we offer delivery! Our delivery service is available in your area. 
+
+  Delivery time is typically 30-45 minutes, and we have a minimum order of $15 for delivery. 
+
+  Would you like to place an order?
+
+You: /exit
+🔴 Session ended
+
+📊 Session Summary:
+  Messages: 6 (3 user, 3 bot)
+  Duration: 2m 15s
+  Guard checks: 3 (all passed)
+```
+
+**Advanced Features:**
+```
+You: tell me a joke
+Bot: I'd love to share a joke! Here's a light one:
+
+  Why did the pizza maker go to art school?
+  Because they wanted to learn how to make a masterpiece!
+
+  🍕 Hope that made you smile! Is there anything else I can help you with?
+
+You: [tries to input toxic content]
+🛡️  Guard: Content violation detected
+Bot: I cannot assist with that request. How else can I help you?
+
+You: /exit
+🔴 Session ended
+```
+
+**Session Context (Future):**
+```
+You: my name is John
+Bot: Nice to meet you, John! How can I help you today?
+
+You: what's my name?
+Bot: Your name is John! Is there anything else you'd like to know?
+```
+
+---
+
+### `okto compare`
+
+Compare two trained models using the same test inputs.
+
+**Usage:**
+```bash
+okto compare <model1> <model2>
+```
+
+**Options:**
+- `<model1>` - Path to first model
+- `<model2>` - Path to second model
+
+**What it compares:**
+- Latency (inference speed)
+- Accuracy (if test dataset provided)
+- Loss values
+- Response quality
+- Resource usage
+
+**Example:**
+```bash
+okto compare models/pizza_v1.okm models/pizza_v2.okm
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1
+📊 Comparing models...
+
+📦 Model 1: models/pizza_v1.okm
+📦 Model 2: models/pizza_v2.okm
+
+⏳ Running comparison tests...
+  ✓ Loading models...
+  ✓ Running inference on 100 test samples...
+  ✓ Measuring metrics...
+
+📈 Comparison Results:
+
+┌─────────────────────┬──────────────┬──────────────┬─────────────┐
+│ Metric              │ Model 1 (V1) │ Model 2 (V2) │ Difference  │
+├─────────────────────┼──────────────┼──────────────┼─────────────┤
+│ Latency (avg)       │ 245ms        │ 189ms        │ V2 -23% ⚡  │
+│ Accuracy            │ 0.892        │ 0.856        │ V1 +4% 📈  │
+│ Loss                │ 1.234        │ 1.156        │ V2 -6% 📉  │
+│ GPU Memory          │ 2.1GB        │ 2.3GB        │ V2 +9%     │
+│ Response Quality    │ 8.5/10       │ 8.2/10       │ V1 +0.3    │
+└─────────────────────┴──────────────┴──────────────┴─────────────┘
+
+💡 Recommendation: V2
+   • 23% faster inference
+   • Lower loss
+   • Slightly lower accuracy (acceptable trade-off)
+
+✅ Comparison completed!
+```
+
+**With Test Dataset:**
+```bash
+okto compare models/v1.okm models/v2.okm --dataset dataset/test.jsonl
+```
+
+---
+
+### `okto logs`
+
+View historical training logs and metrics saved by CONTROL and MONITOR blocks.
+
+**Usage:**
+```bash
+okto logs <model_or_run_id>
+```
+
+**Options:**
+- `<model_or_run_id>` - Model name or run ID
+
+**What it shows:**
+- Loss per epoch
+- Validation loss
+- Accuracy metrics
+- CPU/GPU/RAM usage
+- Decisions made by CONTROL block
+- System metrics from MONITOR block
+
+**Example:**
+```bash
+okto logs pizzabot_v1
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1
+📊 Viewing logs for: pizzabot_v1
+
+📁 Log file: runs/pizzabot_v1/logs/training.log
+
+═══════════════════════════════════════════════════════════
+📈 Training Metrics
+═══════════════════════════════════════════════════════════
+
+Epoch 1:
+  Loss: 2.345 → 1.892
+  Val Loss: 2.123 → 1.756
+  Accuracy: 0.654 → 0.723
+  GPU Usage: 78% (9.2GB / 12GB)
+  RAM Usage: 12.3GB
+
+Epoch 2:
+  Loss: 1.892 → 1.654
+  Val Loss: 1.756 → 1.523
+  Accuracy: 0.723 → 0.789
+  GPU Usage: 82% (9.8GB / 12GB)
+  RAM Usage: 12.5GB
+
+Epoch 3:
+  Loss: 1.654 → 1.456
+  Val Loss: 1.523 → 1.312
+  Accuracy: 0.789 → 0.834
+  GPU Usage: 85% (10.1GB / 12GB)
+  RAM Usage: 12.7GB
+  ⚠️  CONTROL: High loss detected, reducing learning rate
+  ✓ CONTROL: Learning rate set to 0.00005
+
+Epoch 4:
+  Loss: 1.456 → 1.234
+  Val Loss: 1.312 → 1.156
+  Accuracy: 0.834 → 0.867
+  GPU Usage: 88% (10.5GB / 12GB)
+  RAM Usage: 12.9GB
+  ✓ CONTROL: Best model saved (accuracy > 0.85)
+
+Epoch 5:
+  Loss: 1.234 → 1.123
+  Val Loss: 1.156 → 1.089
+  Accuracy: 0.867 → 0.892
+  GPU Usage: 90% (10.8GB / 12GB)
+  RAM Usage: 13.1GB
+  ✓ CONTROL: Training completed successfully
+
+═══════════════════════════════════════════════════════════
+🎯 CONTROL Decisions
+═══════════════════════════════════════════════════════════
+
+Step 500:
+  ✓ LOG: loss = 1.892
+
+Step 1000:
+  ✓ SAVE: checkpoint saved
+
+Epoch 3, Step 1500:
+  ⚠️  IF loss > 2.0: SET LR = 0.00005
+  ✓ LOG: "High loss detected"
+
+Epoch 4, Step 2000:
+  ✓ IF accuracy > 0.85: SAVE "best_model"
+
+═══════════════════════════════════════════════════════════
+📊 System Metrics
+═══════════════════════════════════════════════════════════
+
+Average GPU Usage: 82.6%
+Peak GPU Usage: 92%
+Average RAM Usage: 12.7GB
+Peak RAM Usage: 13.5GB
+Average Temperature: 72°C
+Peak Temperature: 78°C
+
+Throughput: 3.7 samples/sec
+Average Latency: 270ms/step
+```
+
+**Filter by Metric:**
+```bash
+okto logs pizzabot_v1 --metric loss
+okto logs pizzabot_v1 --metric accuracy
+okto logs pizzabot_v1 --metric gpu_usage
+```
+
+---
+
+### `okto tune`
+
+Auto-tune training parameters using the CONTROL block for intelligent optimization.
+
+**Usage:**
+```bash
+okto tune [--file <path>]
+```
+
+**Options:**
+- `--file <PATH>` - Path to OktoScript file (default: `scripts/train.okt`)
+
+**What it does:**
+- Uses CONTROL block logic to auto-adjust training
+- Can adjust learning rate dynamically
+- Can change batch size based on memory
+- Can activate early stopping
+- Can balance classes automatically
+- This is unique in the market
+
+**Example:**
+```bash
+okto tune
+okto tune --file scripts/train.okt
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1
+🎛️  Auto-tuning training...
+
+📄 Reading: scripts/train.okt
+✓ CONTROL block detected
+✓ MONITOR block detected
+
+🚀 Starting tuned training...
+
+Epoch 1:
+  Loss: 2.345
+  ✓ CONTROL: Monitoring metrics...
+
+Epoch 2:
+  Loss: 1.892
+  ✓ CONTROL: Loss improving, continuing...
+
+Epoch 3:
+  Loss: 1.654
+  ⚠️  CONTROL: Loss plateau detected
+  ✓ CONTROL: Reducing learning rate from 0.0001 to 0.00005
+  ✓ CONTROL: Adjusting batch size from 32 to 16
+
+Epoch 4:
+  Loss: 1.456
+  ✓ CONTROL: Learning rate adjustment successful
+  ✓ CONTROL: Loss improving again
+
+Epoch 5:
+  Loss: 1.234
+  ✓ CONTROL: Best model saved (accuracy improved)
+
+✅ Auto-tuning completed!
+📊 Final metrics:
+  Loss: 1.234 (improved from 2.345)
+  Accuracy: 0.892 (improved from 0.654)
+  Optimizations applied: 3
+```
+
+**What makes it unique:**
+- Real-time parameter adjustment based on metrics
+- Uses CONTROL block logic for decision-making
+- No manual intervention needed
+- Adapts to training conditions automatically
+
+---
+
+### `okto exit`
+
+Exit interactive mode (chat, tune, or other interactive sessions).
+
+**Usage:**
+```bash
+okto exit
+```
+
+**When to use:**
+- Exiting chat mode (alternative to `/exit` command)
+- Exiting interactive tuning session
+- Exiting session context
+
+**Example:**
+```bash
+# In chat mode
+You: /exit
+# or
+okto exit
+
+# In interactive tuning
+okto tune --interactive
+# ... tuning session ...
+okto exit
+```
+
+---
+
+## Utility Commands
+
+### `okto doctor`
+
+System diagnostics and environment checking.
+
+**Usage:**
+```bash
+okto doctor
+okto doctor --install
+```
+
+**Options:**
+- `--install` - Automatically install missing dependencies
+
+**Example:**
+```bash
+okto doctor              # Check system
+okto doctor --install    # Check and install dependencies
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1 - System Diagnostics
+
+🖥️  Platform: Windows
+💾 RAM: 63GB total, 40GB available
+⚙️  CPU: 32 cores
+🎮 GPU: Checking...
+  ✔ GPU found: NVIDIA GeForce RTX 4070 Laptop GPU
+🔧 CUDA: Checking...
+  ✔ CUDA available: 576.02
+🔧 Runtime: Checking...
+  ✔ Runtime available: Python 3.14.0
+📦 Dependencies: Checking...
+  ✔ All required packages installed
+
+✅ Diagnostics complete
+```
+
+**With `--install`:**
+```
+📦 Dependencies: Checking...
+  ❌ Missing packages: torch, transformers
+
+💡 To install missing packages, run:
+   pip install torch transformers datasets safetensors
+
+🔧 Auto-installing missing packages...
+  ✔ Successfully installed all packages!
+```
+
+---
+
+### `okto upgrade`
+
+Upgrade OktoEngine to the latest version.
+
+**Usage:**
+```bash
+okto upgrade
+```
+
+**Example:**
+```bash
+okto upgrade
+```
+
+**Output:**
+```
+🐙 OktoEngine Upgrader
+Current version: 0.1.0
+🔍 Checking for updates...
+
+📦 Downloading OktoEngine v0.2.0...
+████████████████████ 100% [00:15<00:00]
+
+✅ Updated successfully to v0.2.0
+```
+
+**What it does:**
+1. Checks GitHub Releases for latest version
+2. Compares with current version
+3. Downloads appropriate binary for your OS
+4. Replaces current binary
+5. Makes it executable (Linux/Mac)
+
+**Requirements:**
+- Internet connection
+- Write permissions to OktoEngine directory
+
+---
+
+### `okto about`
+
+Show information about OktoEngine and OktoScript.
+
+**Usage:**
+```bash
+okto about
+```
+
+**Output:**
+```
+🐙 OktoScript & OktoEngine
+
+📚 Language: OktoScript
+📝 Description: Domain-specific programming language for building, training, evaluating and exporting AI models
+👤 Author: OktoSeek AI
+📦 Version: 1.1
+🌐 Website: https://www.oktoseek.com
+💻 GitHub: https://github.com/oktoseek/oktoscript
+
+🔧 OktoEngine:
+   Official execution engine for OktoScript
+   Repository: https://github.com/oktoseek/oktoengine
+   Version: 0.1.0
+
+📖 Learn more:
+   - Grammar: https://github.com/oktoseek/oktoscript/blob/main/docs/grammar.md
+   - Getting Started: https://github.com/oktoseek/oktoscript/blob/main/docs/GETTING_STARTED.md
+   - FAQ: https://github.com/oktoseek/oktoscript/blob/main/docs/FAQ.md
+```
+
+---
+
+## Global Flags
+
+### `--debug`
+
+Enable debug mode for detailed logging.
+
+**Usage:**
+```bash
+okto <command> --debug
+OKTO_DEBUG=1 okto <command>
+```
+
+**Example:**
+```bash
+okto validate --debug
+okto train --debug
+OKTO_DEBUG=1 okto train
+```
+
+**What it shows:**
+- Detailed parsing logs
+- Execution flow
+- Error diagnostics
+- Performance metrics
+
+**Use cases:**
+- Troubleshooting parsing errors
+- Understanding execution flow
+- Performance analysis
+- Configuration debugging
+
+---
+
+### `--help`
+
+Show help information for a command.
+
+**Usage:**
+```bash
+okto --help
+okto <command> --help
+```
+
+**Example:**
+```bash
+okto --help
+okto train --help
+```
+
+---
+
+### `--version`
+
+Show OktoEngine version.
+
+**Usage:**
+```bash
+okto --version
+```
+
+**Output:**
+```
+okto 0.1.0
+```
+
+---
+
+## Examples
+
+### Complete Workflow
+
+```bash
+# 1. Initialize project
+okto init my-chatbot
+cd my-chatbot
+
+# 2. Validate configuration
+okto validate
+
+# 3. Check system
+okto doctor
+
+# 4. Train model
+okto train
+
+# 5. Evaluate model
+okto eval
+
+# 6. Export model
+okto export --format okm
+
+# 7. Convert to different formats
+okto convert --input export/model.okm --from okm --to onnx --output export/model.onnx
+
+# 8. Test inference
+okto infer --model export/model.okm --text "Hello, how can I help?"
+
+# 9. Interactive chat
+okto chat --model export/model.okm
+
+# 10. View training logs
+okto logs my-chatbot
+```
+
+### Inference Workflow
+
+```bash
+# Direct inference
+okto infer --model models/chatbot.okm --text "What are your business hours?"
+
+# Interactive chat session
+okto chat --model models/chatbot.okm
+# ... chat interaction ...
+# Type '/exit' to quit
+
+# Compare two model versions
+okto compare models/v1.okm models/v2.okm
+```
+
+### Conversion Workflow
+
+```bash
+# Convert PyTorch to multiple formats
+okto convert --input model.pt --from pt --to gguf --output model.gguf
+okto convert --input model.pt --from pt --to onnx --output model.onnx
+okto convert --input model.pt --from pt --to tflite --output model.tflite
+
+# Convert for mobile deployment
+okto convert --input model.pt --from pt --to tflite --output model.tflite
+
+# Convert for web deployment
+okto convert --input model.pt --from pt --to onnx --output model.onnx
+```
+
+### Monitoring and Analysis Workflow
+
+```bash
+# View training logs
+okto logs my-model
+
+# View specific metrics
+okto logs my-model --metric loss
+okto logs my-model --metric gpu_usage
+
+# Auto-tune training
+okto tune
+
+# Compare model versions
+okto compare models/v1.okm models/v2.okm
+```
+
+### Debug Workflow
+
+```bash
+# Validate with debug
+okto validate --debug
+
+# Train with debug
+okto train --debug
+
+# Or use environment variable
+OKTO_DEBUG=1 okto train
+```
+
+### Update and Check
+
+```bash
+# Update engine
+okto upgrade
+
+# Check system
+okto doctor
+
+# Show information
+okto about
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Error (general) |
+| `2` | Validation error |
+| `3` | Training error |
+| `4` | System error |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `OKTO_DEBUG` | Enable debug mode (any value) |
+| `OKTO_LOG_LEVEL` | Set log level (debug, info, warn, error) |
+
+---
+
+## Tips & Best Practices
+
+1. **Always validate before training:**
+   ```bash
+   okto validate && okto train
+   ```
+
+2. **Use debug mode for troubleshooting:**
+   ```bash
+   okto train --debug
+   ```
+
+3. **Check system before training:**
+   ```bash
+   okto doctor
+   ```
+
+4. **Keep engine updated:**
+   ```bash
+   okto upgrade
+   ```
+
+5. **Use absolute paths for clarity:**
+   ```bash
+   okto train --file /path/to/scripts/train.okt
+   ```
+
+---
+
+**Need more help?** Check the [FAQ](./FAQ.md) or [Getting Started Guide](./GETTING_STARTED.md).
+

docs/DEBUG_GUIDE.md

@@ -0,0 +1,433 @@
+# OktoEngine Debug Guide
+
+Complete guide to using debug mode for troubleshooting and understanding OktoEngine's operation.
+
+---
+
+## Table of Contents
+
+1. [What is Debug Mode?](#what-is-debug-mode)
+2. [Enabling Debug Mode](#enabling-debug-mode)
+3. [What Debug Mode Shows](#what-debug-mode-shows)
+4. [Use Cases](#use-cases)
+5. [Interpreting Debug Output](#interpreting-debug-output)
+6. [Common Debug Scenarios](#common-debug-scenarios)
+
+---
+
+## What is Debug Mode?
+
+Debug mode provides detailed, real-time logging of OktoEngine's internal operations. It shows:
+
+- **Parsing details** - How your OktoScript is being parsed
+- **Execution flow** - Step-by-step execution of commands
+- **Error diagnostics** - Detailed error information
+- **Performance metrics** - Timing and resource usage
+
+**When to use:**
+- Troubleshooting parsing errors
+- Understanding execution flow
+- Performance analysis
+- Configuration debugging
+- Learning how OktoEngine works
+
+---
+
+## Enabling Debug Mode
+
+### Method 1: Command Flag
+
+```bash
+okto validate --debug
+okto train --debug
+okto export --debug
+```
+
+### Method 2: Environment Variable
+
+```bash
+# Linux/Mac
+OKTO_DEBUG=1 okto train
+
+# Windows PowerShell
+$env:OKTO_DEBUG=1; okto train
+
+# Windows CMD
+set OKTO_DEBUG=1 && okto train
+```
+
+### Method 3: Global Flag
+
+The `--debug` flag works with all commands:
+
+```bash
+okto <command> --debug
+```
+
+---
+
+## What Debug Mode Shows
+
+### Parsing Phase
+
+**Example output:**
+```
+DEBUG: Starting parse_oktoscript. Input preview: '# okto_version: "1.0" PROJECT "MyModel" ENV {'
+DEBUG: Parsed version: Some("1.0")
+DEBUG: Parsed project: MyModel
+DEBUG: After PROJECT, remaining input: 'ENV { accelerator: "gpu" min_memory: "8GB"...'
+DEBUG: Attempting to parse ENV block...
+DEBUG: Parsed ENV field: accelerator = gpu
+DEBUG: Parsed ENV field: min_memory = 8GB
+DEBUG: Parsed ENV field: precision = fp16
+DEBUG: Successfully parsed ENV block with 5 fields
+DEBUG: After ENV, remaining input: 'DATASET { train: "dataset/train.jsonl"...'
+```
+
+**What it shows:**
+- How the parser processes your OktoScript
+- Which blocks are being parsed
+- Field-by-field parsing
+- Remaining input after each step
+
+### Execution Phase
+
+**Example output:**
+```
+DEBUG: Parsed DATASET block
+DEBUG: Parsed MODEL block
+DEBUG: After MODEL, remaining input: 'TRAIN { epochs: 5 batch_size: 32...'
+DEBUG: Attempting to parse TRAIN block...
+DEBUG: Parsed TRAIN block
+DEBUG: After TRAIN, remaining input: 'EXPORT { format: ["okm"]...'
+DEBUG: Attempting to parse EXPORT block...
+DEBUG: Parsing EXPORT field: format
+DEBUG: parse_string_list - attempting to parse array. Input: '["okm"] path: "export/" }'
+DEBUG: parse_string_list - parsed 1 items: ["okm"]
+DEBUG: Parsed format: ["okm"]
+DEBUG: Parsed EXPORT block
+DEBUG: Final remaining input: ''
+```
+
+**What it shows:**
+- Block parsing order
+- Field extraction
+- Array/list parsing
+- Final state
+
+### Error Diagnostics
+
+**Example output:**
+```
+DEBUG: Failed to parse key in ENV block. Input: 'accelerator: "gpu"...'
+DEBUG: Failed to parse ':' after key 'accelerator'. Input: '"gpu"...'
+```
+
+**What it shows:**
+- Exact point of failure
+- Input context at failure
+- Parsing step that failed
+- Remaining input
+
+---
+
+## Use Cases
+
+### 1. Troubleshooting Parsing Errors
+
+**Problem:** Validation fails with unclear error
+
+**Solution:**
+```bash
+okto validate --debug
+```
+
+**Example:**
+```
+DEBUG: Failed to parse ':' after key 'accelerator:'. Input: '"gpu"'
+```
+
+**Interpretation:** The parser found `accelerator:` but couldn't find the colon separator. This suggests a syntax issue in the ENV block.
+
+**Fix:** Check your OktoScript syntax:
+```okt
+ENV {
+  accelerator: "gpu"  # ✅ Correct
+  # accelerator: "gpu"  # ❌ Wrong (colon in key)
+}
+```
+
+### 2. Understanding Execution Flow
+
+**Use case:** Want to see how OktoEngine processes your configuration
+
+**Solution:**
+```bash
+okto train --debug
+```
+
+**Shows:**
+- Order of block parsing
+- How fields are extracted
+- How arrays are parsed
+- Final parsed structure
+
+### 3. Performance Analysis
+
+**Use case:** Training is slow, want to see where time is spent
+
+**Solution:**
+```bash
+okto train --debug
+```
+
+**Look for:**
+- Time spent in parsing
+- Time spent loading datasets
+- Time spent initializing models
+- Training loop performance
+
+### 4. Configuration Debugging
+
+**Use case:** Configuration works but results are unexpected
+
+**Solution:**
+```bash
+okto validate --debug
+okto train --debug
+```
+
+**Check:**
+- Are all fields parsed correctly?
+- Are values what you expect?
+- Are arrays parsed correctly?
+- Are boolean values correct?
+
+---
+
+## Interpreting Debug Output
+
+### Parsing Flow
+
+**Normal flow:**
+```
+DEBUG: Starting parse_oktoscript...
+DEBUG: Parsed version: Some("1.0")
+DEBUG: Parsed project: MyModel
+DEBUG: After PROJECT, remaining input: 'ENV {...'
+DEBUG: Attempting to parse ENV block...
+DEBUG: Successfully parsed ENV block
+DEBUG: After ENV, remaining input: 'DATASET {...'
+...
+DEBUG: Final remaining input: ''
+```
+
+**What to look for:**
+- ✅ Each block parsed successfully
+- ✅ Remaining input decreases after each block
+- ✅ Final remaining input is empty
+
+**Error indicators:**
+- ❌ "Failed to parse" messages
+- ❌ Remaining input contains unexpected content
+- ❌ Blocks not parsed in expected order
+
+### Field Parsing
+
+**Normal:**
+```
+DEBUG: Parsed ENV field: accelerator = gpu
+DEBUG: Parsed ENV field: precision = fp16
+```
+
+**Error:**
+```
+DEBUG: Failed to parse value for key 'accelerator'. Input: 'gpu min_memory...'
+```
+
+**Interpretation:** The parser couldn't extract the value for `accelerator`. This might indicate:
+- Missing quotes around string values
+- Syntax error in value
+- Unexpected character
+
+### Array Parsing
+
+**Normal:**
+```
+DEBUG: parse_string_list - attempting to parse array. Input: '["okm"] path: "export/"'
+DEBUG: parse_string_list - parsed 1 items: ["okm"]
+```
+
+**Error:**
+```
+DEBUG: parse_string_list - failed to parse array. Input: '[okm] path: "export/"'
+```
+
+**Interpretation:** Array parsing failed. Common causes:
+- Missing quotes around array items
+- Invalid array syntax
+- Unexpected characters
+
+---
+
+## Common Debug Scenarios
+
+### Scenario 1: Validation Fails
+
+**Problem:**
+```bash
+$ okto validate
+❌ Parsing failed!
+```
+
+**Debug:**
+```bash
+$ okto validate --debug
+DEBUG: Starting parse_oktoscript...
+DEBUG: Failed to parse PROJECT block. Input: 'ENV { accelerator: "gpu"...'
+```
+
+**Solution:** Missing PROJECT block or syntax error before PROJECT.
+
+### Scenario 2: Training Fails
+
+**Problem:**
+```bash
+$ okto train
+❌ Training failed!
+```
+
+**Debug:**
+```bash
+$ okto train --debug
+DEBUG: Parsed ENV field: accelerator = gpu
+DEBUG: Parsed ENV field: precision = fp16
+DEBUG: After ENV, remaining input: 'DATASET { train: "dataset/train.jsonl"...'
+DEBUG: Parsed DATASET block
+DEBUG: After DATASET, remaining input: 'MODEL { base: "gpt2" } TRAIN...'
+DEBUG: Parsed MODEL block
+DEBUG: After MODEL, remaining input: 'TRAIN { epochs: 5...'
+...
+Training error: Dataset file not found
+```
+
+**Solution:** Dataset file path is incorrect. Check the path in DATASET block.
+
+### Scenario 3: Export Fails
+
+**Problem:**
+```bash
+$ okto export
+❌ Export failed!
+```
+
+**Debug:**
+```bash
+$ okto export --debug
+DEBUG: Parsing EXPORT field: format
+DEBUG: parse_string_list - attempting to parse array. Input: '["okm"] path: "export/"'
+DEBUG: parse_string_list - parsed 1 items: ["okm"]
+DEBUG: Parsed format: ["okm"]
+DEBUG: Parsed EXPORT block
+Export error: Model not found at runs/MyModel/
+```
+
+**Solution:** Model hasn't been trained yet. Run `okto train` first.
+
+---
+
+## Tips for Effective Debugging
+
+1. **Start with validation:**
+   ```bash
+   okto validate --debug
+   ```
+   Fix parsing errors before training.
+
+2. **Use debug for training:**
+   ```bash
+   okto train --debug
+   ```
+   See full execution flow.
+
+3. **Look for patterns:**
+   - Multiple "Failed to parse" messages indicate syntax issues
+   - "Remaining input" shows what wasn't parsed
+   - Field parsing shows exact values extracted
+
+4. **Compare working vs. broken:**
+   - Run debug on a working configuration
+   - Compare output with broken configuration
+   - Identify differences
+
+5. **Check final state:**
+   - Look for "Final remaining input: ''"
+   - Empty means successful parsing
+   - Non-empty means unparsed content
+
+---
+
+## Debug Output Examples
+
+### Successful Parsing
+
+```
+DEBUG: Starting parse_oktoscript. Input preview: '# okto_version: "1.0" PROJECT "MyModel"'
+DEBUG: Parsed version: Some("1.0")
+DEBUG: Parsed project: MyModel
+DEBUG: After PROJECT, remaining input: 'ENV { accelerator: "gpu"...'
+DEBUG: Attempting to parse ENV block...
+DEBUG: Parsed ENV field: accelerator = gpu
+DEBUG: Parsed ENV field: precision = fp16
+DEBUG: Successfully parsed ENV block with 2 fields
+DEBUG: After ENV, remaining input: 'DATASET { train: "dataset/train.jsonl"...'
+DEBUG: Parsed DATASET block
+DEBUG: Parsed MODEL block
+DEBUG: Parsed TRAIN block
+DEBUG: Parsed EXPORT block
+DEBUG: Final remaining input: ''
+```
+
+### Parsing Error
+
+```
+DEBUG: Starting parse_oktoscript...
+DEBUG: Parsed version: Some("1.0")
+DEBUG: Parsed project: MyModel
+DEBUG: After PROJECT, remaining input: 'ENV { accelerator: "gpu"...'
+DEBUG: Attempting to parse ENV block...
+DEBUG: Failed to parse key in ENV block. Input: 'accelerator: "gpu"...'
+```
+
+**Issue:** Key parsing failed. Check ENV block syntax.
+
+---
+
+## Best Practices
+
+1. **Use debug mode proactively:**
+   - Enable debug when first setting up
+   - Verify configuration is parsed correctly
+   - Understand execution flow
+
+2. **Disable when not needed:**
+   - Debug output can be verbose
+   - Disable for production runs
+   - Use only when troubleshooting
+
+3. **Save debug output:**
+   ```bash
+   okto train --debug > debug.log 2>&1
+   ```
+   Review later or share for support
+
+4. **Combine with validation:**
+   ```bash
+   okto validate --debug && okto train --debug
+   ```
+   Fix parsing issues before training
+
+---
+
+**Need more help?** Check the [FAQ](./FAQ.md) or open an issue on [GitHub](https://github.com/oktoseek/oktoengine/issues).
+

docs/FAQ.md

@@ -0,0 +1,347 @@
+# OktoEngine FAQ
+
+Frequently Asked Questions about OktoEngine CLI.
+
+---
+
+## General Questions
+
+### Q: What is OktoEngine?
+
+**A:** OktoEngine is the official execution engine for OktoScript—a professional CLI tool that transforms declarative AI configurations into trained, production-ready models. It provides a complete command-line interface for training, evaluating, and exporting AI models.
+
+### Q: Do I need to know Python to use OktoEngine?
+
+**A:** No! OktoEngine provides a complete CLI interface. You only need to write OktoScript configuration files. The engine handles all the complex operations behind the scenes.
+
+### Q: What models can I train with OktoEngine?
+
+**A:** OktoEngine supports any model compatible with modern AI frameworks. From small models (millions of parameters) to large language models (billions of parameters). The engine automatically handles model loading, training, and optimization.
+
+### Q: Is OktoEngine free?
+
+**A:** OktoEngine binary releases are available for download. See the [LICENSE](../LICENSE) file for licensing terms.
+
+---
+
+## Installation & Setup
+
+### Q: How do I install OktoEngine?
+
+**A:** Download the latest release from [GitHub Releases](https://github.com/oktoseek/oktoengine/releases) for your platform:
+- Windows: `okto-windows.exe`
+- Linux: `okto-linux`
+- macOS: `okto-macos`
+
+Make it executable (Linux/Mac) and optionally add to PATH.
+
+### Q: How do I update OktoEngine?
+
+**A:** Simply run:
+```bash
+okto upgrade
+```
+
+This automatically downloads and installs the latest version.
+
+### Q: What are the system requirements?
+
+**A:** 
+- **Minimum:** 8GB RAM, 10GB storage, compatible runtime
+- **Recommended for training:** GPU with CUDA, 32GB+ RAM, 50GB+ SSD storage
+
+Check your system:
+```bash
+okto doctor
+```
+
+---
+
+## Training
+
+### Q: Can I train models without a GPU?
+
+**A:** Yes! OktoEngine automatically detects available hardware and uses CPU when GPU is not available. Training will be slower but fully functional. Set `device: "auto"` in your TRAIN block for automatic detection.
+
+### Q: How long does training take?
+
+**A:** Training time depends on:
+- Model size (parameters)
+- Dataset size
+- Hardware (GPU/CPU)
+- Number of epochs
+
+**Rough estimates:**
+- Small models (100M params): 5-15 minutes
+- Medium models (1B params): 30-60 minutes
+- Large models (7B params): Several hours
+
+### Q: Can I resume training from a checkpoint?
+
+**A:** Yes! OktoEngine automatically saves checkpoints during training. You can resume from any checkpoint by configuring your OktoScript file.
+
+### Q: What if training fails?
+
+**A:** 
+1. Check system: `okto doctor`
+2. Validate configuration: `okto validate --debug`
+3. Check error messages for specific issues
+4. Common fixes:
+   - Reduce `batch_size` if out of memory
+   - Verify dataset paths exist
+   - Check model name is valid
+   - Install missing dependencies: `okto doctor --install`
+
+---
+
+## Configuration
+
+### Q: How do I validate my OktoScript file?
+
+**A:** 
+```bash
+okto validate
+```
+
+Or with debug mode:
+```bash
+okto validate --debug
+```
+
+### Q: What if validation fails?
+
+**A:** 
+1. Enable debug mode: `okto validate --debug`
+2. Check error messages
+3. Verify syntax matches OktoScript grammar
+4. Check file paths exist
+5. Verify values are within allowed ranges
+
+### Q: Can I use models from HuggingFace?
+
+**A:** Yes! OktoEngine automatically downloads models from HuggingFace. Just specify the model identifier in your MODEL block:
+
+```okt
+MODEL {
+  base: "gpt2"  # Downloads automatically
+}
+```
+
+### Q: What export formats are supported?
+
+**A:** OktoEngine supports multiple formats:
+- `okm` - OktoSeek Model format (optimized)
+- `onnx` - ONNX format (universal)
+- `gguf` - GGUF format (local inference)
+- `safetensors` - SafeTensors format (HuggingFace)
+
+---
+
+## Debug Mode
+
+### Q: What is debug mode?
+
+**A:** Debug mode provides detailed, real-time logging of OktoEngine's internal operations. It shows parsing details, execution flow, and error diagnostics.
+
+### Q: How do I enable debug mode?
+
+**A:** 
+```bash
+okto train --debug
+okto validate --debug
+```
+
+Or via environment variable:
+```bash
+OKTO_DEBUG=1 okto train
+```
+
+### Q: When should I use debug mode?
+
+**A:** Use debug mode when:
+- Troubleshooting parsing errors
+- Understanding execution flow
+- Performance analysis
+- Configuration debugging
+
+---
+
+## System & Dependencies
+
+### Q: How do I check my system?
+
+**A:** 
+```bash
+okto doctor
+```
+
+Shows GPU, CUDA, RAM, runtime, and dependencies.
+
+### Q: How do I install missing dependencies?
+
+**A:** 
+```bash
+okto doctor --install
+```
+
+Automatically installs missing dependencies.
+
+### Q: What dependencies are required?
+
+**A:** OktoEngine automatically manages dependencies. Required packages are installed automatically when needed. Check with:
+```bash
+okto doctor
+```
+
+---
+
+## Errors & Troubleshooting
+
+### Q: Training fails with "Model not found"
+
+**A:** 
+1. Check the model name in MODEL block is valid
+2. Verify it's a valid HuggingFace model identifier
+3. Check internet connection (for downloading)
+4. Try a different model: `gpt2`, `distilgpt2`, etc.
+
+### Q: Training fails with "Dataset not found"
+
+**A:** 
+1. Verify dataset paths in DATASET block
+2. Check files exist at specified paths
+3. Use absolute paths if relative paths fail
+4. Verify file format (JSONL, CSV, etc.)
+
+### Q: Training fails with "Out of memory"
+
+**A:** 
+1. Reduce `batch_size` in TRAIN block
+2. Use LoRA fine-tuning instead of full fine-tuning
+3. Reduce model size
+4. Close other applications
+5. Use CPU if GPU memory is insufficient
+
+### Q: Validation fails with syntax error
+
+**A:** 
+1. Enable debug mode: `okto validate --debug`
+2. Check OktoScript syntax matches grammar
+3. Verify all required blocks are present
+4. Check for typos in block names
+5. Verify quotes around string values
+
+---
+
+## Performance
+
+### Q: How can I speed up training?
+
+**A:** 
+1. Use GPU: Set `accelerator: "gpu"` in ENV block
+2. Use mixed precision: Set `precision: "fp16"` in ENV block
+3. Increase batch size (if memory allows)
+4. Use LoRA fine-tuning for large models
+5. Use SSD storage for datasets
+
+### Q: How do I monitor training progress?
+
+**A:** Training progress is shown in real-time in the terminal:
+- Progress bars
+- Loss values
+- Learning rate
+- GPU memory usage
+- Epoch progress
+
+### Q: Can I train multiple models simultaneously?
+
+**A:** Yes, but ensure you have sufficient resources (GPU memory, RAM). Run training in separate terminals or use different GPU devices.
+
+---
+
+## Integration
+
+### Q: Will OktoEngine be integrated into OktoSeek IDE?
+
+**A:** Yes! OktoEngine will be integrated into OktoSeek IDE for visual training workflows, including:
+- Visual pipeline builder
+- Real-time dashboard
+- One-click training
+- Project management
+
+### Q: Can I use OktoEngine in scripts?
+
+**A:** Yes! OktoEngine is designed for CLI usage and can be integrated into scripts, CI/CD pipelines, and automation workflows.
+
+---
+
+## Licensing
+
+### Q: Is OktoEngine open source?
+
+**A:** No. OktoEngine is proprietary software. Binary releases are available for download, but the source code is proprietary. See [LICENSE](../LICENSE) for details.
+
+### Q: Can I redistribute OktoEngine?
+
+**A:** See the [LICENSE](../LICENSE) file for redistribution terms.
+
+---
+
+## Support
+
+### Q: Where can I get help?
+
+**A:** 
+- **Documentation:** Check [docs/](./) folder
+- **GitHub Issues:** https://github.com/oktoseek/oktoengine/issues
+- **Email:** service@oktoseek.com
+- **Website:** https://www.oktoseek.com
+
+### Q: How do I report a bug?
+
+**A:** 
+1. Open an issue on [GitHub](https://github.com/oktoseek/oktoengine/issues)
+2. Include:
+   - OktoEngine version: `okto --version`
+   - System information: `okto doctor`
+   - Error messages
+   - Steps to reproduce
+   - Debug output (if applicable)
+
+---
+
+## Advanced
+
+### Q: Can I customize training behavior?
+
+**A:** Yes, through OktoScript configuration:
+- Training parameters (epochs, batch size, learning rate)
+- Optimizer settings
+- Scheduler configuration
+- Checkpoint settings
+- Export formats
+
+### Q: Can I use custom datasets?
+
+**A:** Yes! OktoEngine supports multiple dataset formats:
+- JSONL (recommended)
+- CSV
+- TXT
+- Parquet
+
+Just specify the path in your DATASET block.
+
+### Q: How do I export to multiple formats?
+
+**A:** 
+```okt
+EXPORT {
+  format: ["okm", "onnx", "gguf"]
+  path: "export/"
+}
+```
+
+---
+
+**Need more help?** Check the [Getting Started Guide](./GETTING_STARTED.md) or [CLI Reference](./CLI_REFERENCE.md).
+

docs/GETTING_STARTED.md

@@ -0,0 +1,430 @@
+# Getting Started with OktoEngine
+
+**Your first 5 minutes with OktoEngine** - A quick guide to get you up and running.
+
+---
+
+## Prerequisites
+
+- OktoEngine installed (download from [GitHub Releases](https://github.com/oktoseek/oktoengine/releases))
+- Basic understanding of AI/ML concepts
+- A dataset ready for training (optional for first run)
+
+---
+
+## Step 1: Install OktoEngine
+
+### Download Pre-built Binary
+
+1. Visit [GitHub Releases](https://github.com/oktoseek/oktoengine/releases)
+2. Download the binary for your platform:
+   - **Windows:** `okto-windows.exe`
+   - **Linux:** `okto-linux`
+   - **macOS:** `okto-macos`
+3. Make it executable (Linux/Mac):
+   ```bash
+   chmod +x okto-linux
+   ```
+4. Add to PATH (optional but recommended)
+
+### Verify Installation
+
+```bash
+okto --version
+```
+
+Should output: `okto 0.1.0`
+
+---
+
+## Step 2: Check Your System
+
+Before starting, check if your system is ready:
+
+```bash
+okto doctor
+```
+
+This will show:
+- ✅ Platform information
+- ✅ RAM and CPU
+- ✅ GPU detection
+- ✅ CUDA availability
+- ✅ Runtime environment
+- ✅ Dependencies status
+
+**If dependencies are missing:**
+```bash
+okto doctor --install
+```
+
+Automatically installs missing dependencies.
+
+---
+
+## Step 3: Create Your First Project
+
+Initialize a new OktoScript project:
+
+```bash
+okto init my-first-model
+cd my-first-model
+```
+
+This creates:
+```
+my-first-model/
+├── scripts/
+│   └── train.okt          # Your training configuration
+├── dataset/
+│   ├── train.jsonl        # Training data (sample)
+│   └── val.jsonl          # Validation data (sample)
+└── export/                # Where models will be exported
+```
+
+---
+
+## Step 4: Prepare Your Dataset
+
+Edit `dataset/train.jsonl` with your training data:
+
+**dataset/train.jsonl:**
+```json
+{"input":"Hello","output":"Hi! How can I help you?"}
+{"input":"What's the weather?","output":"I don't have access to weather data."}
+{"input":"Thank you","output":"You're welcome!"}
+```
+
+**Minimum requirements:**
+- At least 10 examples for basic training
+- Consistent format (JSONL recommended)
+- Valid JSON on each line
+
+**Supported formats:**
+- JSONL (recommended)
+- CSV
+- TXT
+- Parquet
+
+---
+
+## Step 5: Configure Your Training
+
+Edit `scripts/train.okt`:
+
+```okt
+PROJECT "MyFirstModel"
+DESCRIPTION "My first AI model with OktoEngine"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+  install_missing: true
+}
+
+DATASET {
+  train: "dataset/train.jsonl"
+  validation: "dataset/val.jsonl"
+}
+
+MODEL {
+  base: "gpt2"
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  device: "auto"
+}
+
+EXPORT {
+  format: ["okm"]
+  path: "export/"
+}
+```
+
+**Key settings:**
+- `PROJECT` - Your model name
+- `MODEL.base` - Base model (gpt2, distilgpt2, etc.)
+- `TRAIN.epochs` - Number of training epochs
+- `TRAIN.batch_size` - Batch size
+- `TRAIN.device` - "auto" detects GPU/CPU automatically
+- `EXPORT.format` - Output format
+
+---
+
+## Step 6: Validate Your Configuration
+
+Before training, validate your configuration:
+
+```bash
+okto validate
+```
+
+**What it checks:**
+- ✅ Syntax is correct
+- ✅ All required fields are present
+- ✅ Dataset files exist
+- ✅ Model paths are valid
+- ✅ Values are within allowed ranges
+
+**Example output:**
+```
+🐙 OktoEngine v0.1
+🔍 Validating OktoScript file: "scripts/train.okt"
+📄 File: "scripts/train.okt"
+📄 Size: 382 bytes
+📄 Lines: 31
+
+✔ File parsed successfully
+
+📋 Validation Results:
+✅ Validation passed! No errors or warnings.
+
+📊 Summary:
+  Project: MyFirstModel
+  ENV: Configured
+  Dataset: dataset/train.jsonl
+  Model: gpt2
+  Training: 5 epochs, batch size 32
+  Export: ["okm"]
+```
+
+**If validation fails:**
+- Check error messages
+- Fix syntax errors
+- Verify file paths
+- Run `okto validate --debug` for detailed logs
+
+---
+
+## Step 7: Train Your Model
+
+Start training:
+
+```bash
+okto train
+```
+
+**What happens:**
+1. ✅ Configuration is parsed and validated
+2. ✅ System environment is checked
+3. ✅ Dependencies are verified
+4. ✅ Dataset is loaded
+5. ✅ Model is initialized (downloads from HuggingFace if needed)
+6. ✅ Training loop starts
+7. ✅ Progress is shown in real-time
+8. ✅ Model is saved to `runs/MyFirstModel/`
+9. ✅ Exported models saved to `export/`
+
+**Example output:**
+```
+🐙 OktoEngine v0.1
+📄 Reading: "scripts/train.okt"
+
+📊 Environment Check:
+  ✔ Runtime: Python 3.14.0
+  ✔ GPU: NVIDIA GeForce RTX 4070
+  ✔ RAM: 63GB (40GB available)
+  ✔ Platform: windows
+
+📦 Checking dependencies...
+  ✔ All dependencies available
+
+🚀 Starting training pipeline...
+
+Epoch 1/5: 100%|████████████| 500/500 [02:15<00:00, 3.70it/s]
+  Loss: 2.345 → 1.892
+  Learning Rate: 5e-5
+  GPU Memory: 8.2GB / 12GB
+
+Epoch 2/5: 100%|████████████| 500/500 [02:14<00:00, 3.72it/s]
+  Loss: 1.892 → 1.654
+
+...
+
+✅ Training completed successfully!
+📁 Output: runs/MyFirstModel/
+```
+
+**Training time:**
+- Small models (100M params): 5-15 minutes
+- Medium models (1B params): 30-60 minutes
+- Large models (7B params): Several hours
+
+---
+
+## Step 8: Check Your Results
+
+After training completes:
+
+**Check training output:**
+```bash
+ls runs/MyFirstModel/
+```
+
+**Files created:**
+- `checkpoint-*/` - Training checkpoints
+- `training_logs.json` - Detailed training logs
+- `metrics.json` - Training metrics
+- `tokenizer.json` - Tokenizer configuration
+
+**Check exported models:**
+```bash
+ls export/
+```
+
+**Exported files:**
+- `model.okm` - OktoSeek Model format
+
+---
+
+## Step 9: Evaluate Your Model (Optional)
+
+Evaluate your trained model:
+
+```bash
+okto eval
+```
+
+**Output:**
+```
+🐙 OktoEngine v0.1
+📊 Evaluating model...
+
+📈 Evaluation Results:
+  Accuracy: 0.892
+  Loss: 1.234
+  Perplexity: 2.456
+  F1-Score: 0.876
+
+✅ Evaluation completed!
+```
+
+---
+
+## Common First Steps
+
+### Using GPU
+
+If you have a GPU, OktoEngine will automatically detect and use it. To ensure GPU usage:
+
+```okt
+ENV {
+  accelerator: "gpu"
+  precision: "fp16"
+}
+
+TRAIN {
+  device: "auto"  # or "cuda" for explicit GPU
+}
+```
+
+### Adding More Epochs
+
+```okt
+TRAIN {
+  epochs: 10  # Increase from 5
+  batch_size: 32
+}
+```
+
+### Exporting to Multiple Formats
+
+```okt
+EXPORT {
+  format: ["okm", "onnx", "gguf"]
+  path: "export/"
+}
+```
+
+### Using Debug Mode
+
+For detailed logs during training:
+
+```bash
+okto train --debug
+```
+
+Shows:
+- Parsing details
+- Execution flow
+- Error diagnostics
+- Performance metrics
+
+---
+
+## Troubleshooting
+
+### Training Fails
+
+**Check system:**
+```bash
+okto doctor
+```
+
+**Check configuration:**
+```bash
+okto validate --debug
+```
+
+**Common issues:**
+- **Out of memory:** Reduce `batch_size` in TRAIN block
+- **Model not found:** Check `MODEL.base` is a valid HuggingFace model
+- **Dataset not found:** Verify paths in DATASET block
+- **Dependencies missing:** Run `okto doctor --install`
+
+### Validation Fails
+
+**Enable debug mode:**
+```bash
+okto validate --debug
+```
+
+**Common errors:**
+- Syntax errors - Check OktoScript syntax
+- Missing fields - Add required blocks
+- Invalid paths - Verify file paths exist
+- Invalid values - Check value ranges
+
+### System Issues
+
+**Check system:**
+```bash
+okto doctor
+```
+
+**Install dependencies:**
+```bash
+okto doctor --install
+```
+
+---
+
+## Next Steps
+
+- 📚 Read the [Complete CLI Reference](./CLI_REFERENCE.md)
+- 🎯 Check out [Examples](../examples/) for advanced use cases
+- 🐛 Learn about [Debug Mode](./DEBUG_GUIDE.md)
+- 💡 Explore [FAQ](./FAQ.md) for common questions
+
+---
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Initialize project | `okto init <name>` |
+| Validate | `okto validate` |
+| Check system | `okto doctor` |
+| Train | `okto train` |
+| Evaluate | `okto eval` |
+| Export | `okto export --format okm` |
+| Debug mode | `okto train --debug` |
+| Upgrade | `okto upgrade` |
+
+---
+
+**Need help?** Check the [FAQ](./FAQ.md) or open an issue on [GitHub](https://github.com/oktoseek/oktoengine/issues).
+

examples/README.md

@@ -0,0 +1,154 @@
+# OktoEngine Examples
+
+Complete working examples demonstrating OktoEngine capabilities.
+
+---
+
+## Table of Contents
+
+1. [Basic Training](#basic-training)
+2. [LoRA Fine-tuning](#lora-fine-tuning)
+3. [Chatbot Training](#chatbot-training)
+4. [Multi-format Export](#multi-format-export)
+
+---
+
+## Basic Training
+
+**Location:** [`basic-training/`](./basic-training/)
+
+Minimal working example for training a simple model.
+
+**Files:**
+- `scripts/train.okt` - Training configuration
+- `dataset/train.jsonl` - Sample training data
+- `dataset/val.jsonl` - Sample validation data
+
+**Usage:**
+```bash
+cd basic-training
+okto validate
+okto train
+```
+
+---
+
+## LoRA Fine-tuning
+
+**Location:** [`lora-training/`](./lora-training/)
+
+Example of efficient LoRA fine-tuning for large models.
+
+**Files:**
+- `scripts/train.okt` - LoRA configuration
+- `dataset/train.jsonl` - Training data
+
+**Usage:**
+```bash
+cd lora-training
+okto validate
+okto train
+```
+
+---
+
+## Chatbot Training
+
+**Location:** [`chatbot/`](./chatbot/)
+
+Complete example for training a conversational AI model.
+
+**Files:**
+- `scripts/train.okt` - Chatbot configuration
+- `dataset/train.jsonl` - Conversation data
+- `dataset/val.jsonl` - Validation conversations
+
+**Usage:**
+```bash
+cd chatbot
+okto validate
+okto train
+okto eval
+```
+
+---
+
+## Multi-format Export
+
+**Location:** [`multi-export/`](./multi-export/)
+
+Example showing how to export models to multiple formats.
+
+**Files:**
+- `scripts/train.okt` - Configuration with multiple export formats
+
+**Usage:**
+```bash
+cd multi-export
+okto train
+okto export --format okm,onnx,gguf
+```
+
+---
+
+## Running Examples
+
+1. **Navigate to example directory:**
+   ```bash
+   cd examples/basic-training
+   ```
+
+2. **Validate configuration:**
+   ```bash
+   okto validate
+   ```
+
+3. **Train the model:**
+   ```bash
+   okto train
+   ```
+
+4. **Check results:**
+   ```bash
+   ls runs/
+   ls export/
+   ```
+
+---
+
+## Customizing Examples
+
+All examples can be customized:
+
+1. **Edit `scripts/train.okt`** - Modify training parameters
+2. **Replace `dataset/*.jsonl`** - Use your own data
+3. **Adjust `MODEL.base`** - Use different base models
+4. **Modify `EXPORT.format`** - Change export formats
+
+---
+
+## Example Output
+
+**Training output:**
+```
+🐙 OktoEngine v0.1
+📄 Reading: "scripts/train.okt"
+
+📊 Environment Check:
+  ✔ Runtime: Python 3.14.0
+  ✔ GPU: NVIDIA GeForce RTX 4070
+  ✔ RAM: 63GB (40GB available)
+
+🚀 Starting training pipeline...
+
+Epoch 1/5: 100%|████████████| 500/500 [02:15<00:00, 3.70it/s]
+  Loss: 2.345 → 1.892
+
+✅ Training completed successfully!
+📁 Output: runs/MyModel/
+```
+
+---
+
+**Need help?** Check the [Getting Started Guide](../docs/GETTING_STARTED.md) or [FAQ](../docs/FAQ.md).
+

examples/basic-training/dataset/train.jsonl

@@ -0,0 +1,6 @@
+{"input":"Hello","output":"Hi! How can I help you?"}
+{"input":"What's the weather?","output":"I don't have access to weather data."}
+{"input":"Thank you","output":"You're welcome!"}
+{"input":"What can you do?","output":"I can help answer questions and have conversations."}
+{"input":"Tell me a joke","output":"Why did the AI go to school? To improve its learning!"}
+

examples/basic-training/dataset/val.jsonl

@@ -0,0 +1,3 @@
+{"input":"Hello there","output":"Hello! How can I assist you?"}
+{"input":"Thanks","output":"You're welcome!"}
+

examples/basic-training/scripts/train.okt

@@ -0,0 +1,33 @@
+# okto_version: "1.0"
+
+PROJECT "BasicModel"
+DESCRIPTION "Basic training example for OktoEngine"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+  backend: "oktoseek"
+  install_missing: true
+}
+
+DATASET {
+  train: "dataset/train.jsonl"
+  validation: "dataset/val.jsonl"
+}
+
+MODEL {
+  base: "gpt2"
+}
+
+TRAIN {
+  epochs: 5
+  batch_size: 32
+  device: "auto"
+}
+
+EXPORT {
+  format: ["okm"]
+  path: "export/"
+}
+

examples/lora-training/dataset/train.jsonl

@@ -0,0 +1,4 @@
+{"input":"What is AI?","output":"AI, or Artificial Intelligence, is the simulation of human intelligence by machines."}
+{"input":"Explain machine learning","output":"Machine learning is a subset of AI that enables systems to learn from data."}
+{"input":"What is deep learning?","output":"Deep learning uses neural networks with multiple layers to learn complex patterns."}
+

examples/lora-training/dataset/val.jsonl

@@ -0,0 +1,2 @@
+{"input":"What is neural network?","output":"A neural network is a computing system inspired by biological neural networks."}
+

examples/lora-training/scripts/train.okt

@@ -0,0 +1,39 @@
+# okto_version: "1.0"
+
+PROJECT "LoRAModel"
+DESCRIPTION "LoRA fine-tuning example for efficient training"
+
+ENV {
+  accelerator: "gpu"
+  min_memory: "8GB"
+  precision: "fp16"
+  install_missing: true
+}
+
+DATASET {
+  train: "dataset/train.jsonl"
+  validation: "dataset/val.jsonl"
+}
+
+MODEL {
+  base: "gpt2"
+}
+
+TRAIN {
+  epochs: 3
+  batch_size: 16
+  device: "auto"
+  learning_rate: 0.00003
+}
+
+FT_LORA {
+  lora_rank: 8
+  lora_alpha: 32
+  target_modules: ["q_proj", "v_proj"]
+}
+
+EXPORT {
+  format: ["safetensors", "okm"]
+  path: "export/"
+}
+