dsk-dev-ai · dsk-dev-ai · Apr 12, 2026 · Apr 12, 2026
@@ -0,0 +1,23 @@
+# DevOS AI Changelog
+
+## v3.0.0 - 2026-04-12
+
+### 🚀 Features
+- Added a new `core/v3` module with weighted context ranking and modern prompt templates.
+- Added advanced explain controls to the CLI: `--max-files`, `--max-chars`, `--include-tests`, and `--json`.
+- Added explain output metadata showing the selected files used as context.
+
+### 🔄 Replacements
+- Directly replaced the old simplistic context-building flow with the new v3 engine pipeline.
+- Replaced ad-hoc CLI argument handling with `argparse` for more reliable command parsing.
+
+### 🛠 Improvements
+- Expanded parser extension support and safer file reading behavior.
+- Added release notes under `VERSION/3.0.0/CHANGELOG.md`.
+
+## v2.0.0
+- CLI-based AI code analyzer
+- Code explanation
+- Code search
+- Debug assistant
+- Multi-LLM support
@@ -1,228 +1,73 @@
 # 🚀 DevOS AI
 
-CLI-based AI tool for analyzing and explaining codebases using structured context extraction and LLM reasoning.
+DevOS AI is a developer-first assistant for understanding codebases faster using structured context extraction and LLM reasoning.
 
----
+## ✅ Release Status
 
-## ✨ Introduction
+**Current release: v3.0.0**
 
-DevOS AI is a developer-first tool designed to help engineers quickly understand unfamiliar codebases.
+v3 introduces a direct replacement of the legacy context engine with a smarter ranking pipeline, advanced CLI controls, and better output structure for explain workflows.
 
-Instead of manually reading hundreds of files, DevOS intelligently extracts relevant parts of a repository, builds structured context, and uses Large Language Models (LLMs) to generate clear, high-level explanations of architecture and functionality.
+## 🔥 What’s New in v3
 
----
-
-## 📚 Table of Contents
-
-- Overview
-- Features
-- How It Works
-- Architecture
-- Project Structure
-- Installation
-- Usage
-- Example Output
-- Demo
-- Roadmap
-- Configuration
-- Dependencies
-- Contributing
-- Troubleshooting
-- License
-- Author
-
----
-
-## 🔍 Overview
-
-DevOS AI transforms codebases into understandable insights by combining:
-
-- Smart file selection
-- Context-aware prompt generation
-- LLM-powered reasoning
-
-👉 It acts like a **codebase explainer engine**, helping developers onboard faster and debug smarter.
-
----
-
-## 🔥 Features
-
-- 🔍 Analyze any codebase using AI  
-- 🧠 Structured context extraction  
-- 🏗 Architecture-level explanations  
-- ⚙️ Modular design (CLI + Core + LLM)  
-- 🌐 Multi-LLM support (OpenRouter + Google)  
-- 💻 CLI-first developer experience  
-
----
-
-## 🧠 How It Works
-
-### Pipeline
-
-
-CLI → Context Builder → Prompt Engine → LLM → Output
-
-
-### Step-by-Step
-
-1. Extract important files from the repository  
-2. Rank and filter relevant code  
-3. Build structured context  
-4. Generate optimized prompts  
-5. Send to LLM for reasoning  
-6. Output structured explanation  
-
----
-
-## 🏗 Architecture
-
-| Module | Description |
-|--------|------------|
-| `cli/` | Command-line interface |
-| `core/` | Context building + prompt generation |
-| `llm/` | LLM provider integration |
-
----
-
-## 📂 Project Structure
+- Advanced context ranking with weighted file scoring.
+- Direct replacement of the old prompt builder with a stricter “facts vs inference” response format.
+- New `core/v3/` module for maintainable architecture.
+- New CLI controls: `--max-files`, `--max-chars`, `--include-tests`, and `--json`.
+- Improved explain command output with selected file visibility.
 
+## 📦 Project Structure
 
+```text
 devos-ai/
 ├── cli/
 ├── core/
+│   └── v3/
 ├── llm/
 ├── agents/
 ├── apps/
 ├── frontend/
 ├── infrastructure/
 ├── docs/
-├── scripts/
-
-
----
+└── scripts/
+```
 
 ## ⚙️ Installation
 
-### Prerequisites
-
-- Python 3.9+
-- API key (OpenRouter or Google Gemini)
-
-### Setup
-
+```bash
 git clone https://github.com/dsk-dev-ai/devos-ai.git
 cd devos-ai
 pip install -r requirements.txt
+```
 
 ## ⚡ Usage
 
-🔍 Explain Codebase
-python3 -m cli.main explain .
+### Explain a repository
 
-🔎 Search Code
-python3 -m cli.main search . "engine"
-
-🐞 Debug Error
-python3 -m cli.main debug error.log
-
-🧠 Choose Model
-python3 -m cli.main explain . --model openrouter
-python3 -m cli.main explain . --model google
+```bash
 python3 -m cli.main explain . --model auto
+python3 -m cli.main explain . --max-files 12 --max-chars 2000
+python3 -m cli.main explain . --include-tests --json
+```
 
-## 🧠 Example Output
-
-1. Purpose
-CLI-based AI tool for analyzing codebases...
-
-2. Architecture Overview
-CLI → Core → LLM → Output
-
-3. Key Components
-- CLI
-- Core Engine
-- LLM Provider
-
-### Example:
-At (assets/images/) & (assets/videos/)
-
-## 🚀 Roadmap
-
-✅ V2 (Current)
-CLI-based code analyzer
-Context ranking system
-Multi-LLM support
-Search + Debug commands
-
-🔜 V3 (Upcoming)
-🔍 Advanced file-level search
-🐞 Smart stack trace debugging
-⚡ RAG (vector search)
-📦 Global CLI install (devos)
-🌐 Web dashboard
-
-## ⚙️ Configuration
-
-Create .env file:
-
-OPENROUTER_API_KEY=your_key
-GOOGLE_API_KEY=your_key
+### Search code
 
-## 📦 Dependencies
-
-Python standard library
-requests
-python-dotenv
-
-## 🤝 Contributing
-
-Contributions are welcome!
+```bash
+python3 -m cli.main search . "engine"
+```
 
-You can help with:
+### Debug an error file
 
-Improving context extraction
-Enhancing LLM prompts
-Adding new CLI features
-UI/UX improvements
+```bash
+python3 -m cli.main debug error.log
+```
 
-## 🛠 Troubleshooting
+## 🛣️ Roadmap
 
-1. LLM not working
-Check API keys in .env
-Verify internet connection
-2. No output
-Ensure valid project path
-Check file permissions
-3. Timeout / Slow response
-Reduce context size
-Check API limits
+- ✅ v3: advanced context engine and richer CLI controls.
+- 🔜 v3.x: smarter semantic retrieval and local embedding cache.
+- 🔜 v4: interactive web dashboard with collaborative review mode.
 
 ## 📜 License
 
-This project is licensed under the MIT License.
-
-## 👨‍💻 Author
-
-Darshan Kachare
-AI Developer • Open Source Contributor
-
-GitHub: https://github.com/dsk-dev-ai
-
-## ⭐ Support
-
-If you find this useful:
-
-⭐ Star the repository
-🐛 Report issues
-🤝 Contribute
-🚀 Project Status
-
-## 🚧 Project Status
-
-- Experimental CLI-based AI tool
-- Actively under development (v2)
-- Focused on improving context extraction and LLM reasoning
-- Suitable for learning and experimentation
-
----
+MIT License.
@@ -0,0 +1,15 @@
+# DevOS AI v3.0.0
+
+## Highlights
+- New `core/v3` architecture for advanced context construction.
+- Direct replacement of the previous engine internals with strongly typed v3 builders.
+- Explain command now supports:
+  - `--max-files`
+  - `--max-chars`
+  - `--include-tests`
+  - `--json`
+
+## Technical Notes
+- Legacy `core/engine.py` functions are kept as compatibility wrappers and now route to v3 internals.
+- File scoring has been upgraded to keyword + file-type weighting.
+- Prompt output now includes risks and gaps for practical code review.