agent-enderun 1.1.10 → 1.10.0

package/README.md

@@ -1,51 +1,326 @@
-# 🏛️ Agent Enderun — Enterprise AI Governance & Autonomous Orchestration Framework
+# 🏛️ Agent Enderun — The Supreme AI Governance & Autonomous Orchestration Framework
 
-> **Stable Release:** v1.1.10 (JSON-Native Architecture) — Build Compile: Clean | Type-Safety: 100% Verified | Compliance: 100% Passed
+> **Stable Release:** v1.10.0 (Enterprise Orchestration Ready) — Build Compile: Clean | Type-Safety: 100% Verified | AL Compliance: 13/13 Agents
 
 > **Author:** Yusuf BEKAR
+> **Trace ID:** `01HGT8J5E2N0W0W0W0W0W0W0W5`
 > **System Status:** 🟢 All Systems Operational | Build Compile: Clean | Type-Safety: 100% Verified
 
 ---
 
 ## 🇹🇷 TÜRKÇE — Proje Tanıtımı & Detaylı Kullanım Kılavuzu
 
-**Agent Enderun**, karmaşık, ölçeklenebilir ve kurumsal (enterprise) düzeydeki yazılım projeleri için özel olarak tasarlanmış bir **Yapay Zeka Yönetişimi ve Otonom Ordu Komuta Sistemidir**.
+**Agent Enderun**, Kurumsal Gelişim için En Üstün Yapay Zeka Yönetişimi ve Otonom Orkestrasyon Çerçevesidir. Kurumsal Yapay Zeka Yönetim Asistanı olarak görev yapar. Sıradan bir kod şablon üreteci veya basit bir AI asistanı değildir; karmaşık, ölçeklenebilir ve kurumsal (enterprise) düzeydeki yazılım projeleri için özel olarak tasarlanmış bir **Yapay Zeka Yönetişimi ve Otonom Ordu Komuta Sistemidir**.
 
-Güncel sürüm itibarıyla sistem; **JSON tabanlı DocumentStore mimarisi**, **Hermes protokolü**, **Otomatik Dokümantasyon (DocGen)**, **Compliance Scanner (Nizam Denetleyici)** ve **Contract-First (Sözleşme Odaklı)** geliştirme süreçleriyle güçlendirilmiştir.
+Güncel sürüm itibarıyla sistem; **@-mention delegasyon**, **doğal dil rotalama**, **Kurumsal CRUD Yönetişimi** ve **Hermes Kilit Protokolü** ile güçlendirilmiş; kendi hafızasını yönetebilen, monorepo proje yollarını dinamik olarak haritalayan, tüm ajan seanslarını güvenli şekilde günlükleyen, farklı yapay zeka ekosistemlerini anayasal bir disiplin altında birleştiren, **Agent Lifecycle (AL) tam uyumlu init ve ordu validasyonunu** (npm kurulumu sonrası dahil) otomatikleştiren, **harici IDE entegrasyonlarında (Claude Desktop/Cursor vb.) mutlak proje kök dizini (CWD) uyumluluğu sunan**, **scaffold adımlarında ajan klasörlerini adapter tipine göre dinamik olarak eşleyen** ve **macOS & Windows çapraz platform standartlarına tam uyum sağlayan** yaşayan bir mühendislik organizmasıdır. Karmaşık kurumsal projeler için optimize edilmiştir (corporate-governance SOP'ları ile).
 
 ---
 
 ### ❓ Neden Agent Enderun?
 
-1. **JSON-Native Bellek Yönetimi:** Geleneksel Markdown tabanlı hafıza sistemi yerine, tip güvenli ve doğrulanabilir JSON tabanlı bir `DocumentStore` mimarisiyle çalışır.
-2. **Contract-First Geliştirme:** Zod tabanlı kontratlar (`src/contracts/`) sayesinde, ajanlar arası iletişim runtime aşamasında doğrulanır.
-3. **Otomatik Dokümantasyon:** `npm run enderun:docs` komutuyla ajan tanımlarından güncel dokümanlar otomatik üretilir.
-4. **Nizam Denetimi (Compliance):** `npm run enderun:check` ile kodunuzdaki güvenlik ve kalite standartları (No 'any', No 'console.log', No hardcoded secrets) otonom olarak denetlenir.
+Yapay zeka kodlama yardımcıları (Claude Code, Gemini CLI, Grok Build vb.) geliştikçe, kurumsal projelerde kontrolü kaybetmek çok daha kolay hale gelmiştir. Agent Enderun, aşağıdaki kritik **kurumsal problemleri çözmek** amacıyla doğmuştur:
+
+1. **Kontrolsüz ve Hatalı Değişiklikler (Rogue AI):** Ajanların tüm kod dosyasını baştan yazmasını engelleyerek **milyonlarca satırlık kodları cerrahi hassasiyetle (`replace_text` / `patch_file` üzerinden)** değiştirmeye zorlar. Token tüketimini ve hata oranını %90 azaltır.
+2. **Kayıp Hafıza ve Bağlam Drifti:** Ajanlar oturum değiştirdikçe projenin geçmişini ve mimari kararlarını unutur. Enderun, **`.enderun/memory/PROJECT_MEMORY.md`** dosyasını projenin değişmez tek doğruluk kaynağı (SSOT) haline getirerek, seanslar arası bağlam kaybını tamamen engeller.
+3. **Akıllı Delegasyon ve Doğal Dil:** Artık karmaşık komutlar yerine `agent-enderun "Projemi denetle"` gibi doğal dildeki istekler veya `agent-enderun @backend "Tablo oluştur"` gibi doğrudan delegasyonlar kullanılabilir.
+4. **Çoklu Ajan Kaosu:** **12** farklı uzman yapay zeka ajanı, olay tabanlı asenkron bir haberleşme protokolü olan **Hermes Message Broker** üzerinden koordine edilir. Ajanlar birbirine rastgele müdahale edemez; tüm görevler bir İş Dağılım Grafiği (DAG) üzerinden komuta edilir.
+5. **Güvenli Haberleşme & Entegrasyon (Hermes Lock Protocol):** Ortak bellek dosyalarına veya kuyruklara yazarken olası dosya çakışmalarını işletim sistemi (OS) düzeyinde atomik dosya oluşturma (`flag: 'wx'`) yöntemiyle engeller. Kilit meşgulse otomatik olarak bekleyip (retry) sırayla kuyrukları işler.
+6. **Kurumsal Yetki ve CRUD Yönetişimi (Corporate CRUD Governance):** Ajanların doğrudan kritik/idari veri mutasyonları (kullanıcı/rol atama, şema değiştirme, veritabanı göçü, toplu silme) yapmasını engeller. Bu işlemler `@manager` ajanı üzerinden onay kuyruğuna alınır ve insan denetçinin `agent-enderun approve` komutunu çalıştırmasıyla aktif hale getirilir.
 
 ---
 
 ### 📦 Güncel Sürüm / Current Release
 
-**v1.1.10** — JSON Memory Migration & Compliance hardening.
-*   **TR:** Proje tamamen JSON tabanlı hafıza yapısına (`state.json`, `status.json`) geçirildi. Tüm testler (`101/101`) yeni mimariyle uyumlu hale getirildi. Compliance Scanner güçlendirildi.
-*   **EN:** Migrated the entire memory system to a robust JSON-based `DocumentStore` architecture. All tests (101/101) passed. Strengthened the Compliance Scanner for enterprise-grade enforcement.
+**v1.10.0** — Kararlı Sürüm (Dinamik Mobil Scaffolding & Performans).
+*   **TR:** Mobil (Expo/React Native) uygulama üretme desteği eklendi. Orkestrasyon döngüsü bellek içi önbellekleme (in-memory cache) ile optimize edildi. Nizam denetimi (`check`) ajan dökümantasyonunu kapsayacak şekilde genişletildi.
+*   **EN:** Added Mobile (Expo/React Native) scaffolding support. Optimized orchestration loop with in-memory caching. Expanded discipline check (`check`) to audit agent documentation.
+
+---
+
+### 💎 Stratejik Platform Sinerjisi (Dört Büyük Güç)
+
+Agent Enderun, sektörün öncüsü olan yapay zeka ekosistemlerini bir araya getirerek her birine stratejik bir rol atar:
+* **🚀 Claude Code (Operasyonel Cerrahi):** **Saha Mühendisi**. Kod tabanındaki otonom ve milimetrik cerrahi düzenlemeleri (Surgical Edits) gerçekleştirir.
+* **♊ Gemini & Vertex AI (Komuta İstihbaratı):** **Stratejik Karar Merkezi**. Proje geçmişini, mimari kararları analiz eder ve yüksek seviyeli stratejik yönlendirmeler yapar.
+* **🛸 Antigravity (İç Disiplin & Akademi):** **Askeri Akademi**. İç standartları, anayasal uyumu korumak amacıyla izole edilmiş, yüksek disiplinli geliştirme ve test ortamı sağlar.
+* **🤖 Grok / X.ai (Otonom Keşif Kanadı):** **Deneysel Keşif**. Gelecek vizyonlu otonom protokolleri test eder ve yapay zeka güdümlü geliştirme sınırlarını zorlar.
+
+---
+
+### 🪖 Konsolide Edilmiş 13 Ajanlık Ordu Yapısı
+
+Tüm operasyonlar, uzmanlık alanlarına göre ayrılmış ve Hermes protokolüyle birbirine bağlanmış 13 aktif ajan tarafından yönetilir:
+
+| Ajan | Uzmanlık Rolü | Temel Sorumluluğu |
+| :--- | :--- | :--- |
+| **`@manager`** | Orchestration & Governance | Görev dağılımı (DAG), hafıza yönetimi (`PROJECT_MEMORY.md`), anayasa koruyuculuğu. |
+| **`@architect`** | System Design & Architect | Çekirdek mimari, tip kontratları ve kilit yönetimi tasarımı. |
+| **`@quality`** | Automated Testing & Quality | AST zafiyet taramaları, anayasal uyum denetimi, kod inceleme checklistleri, test standartları kapısı. |
+| **`@database`** | Database Migrations & Tuning | Veritabanı şemaları, migration kuralları, index optimizasyonları ve veri tohumlama (seeding). |
+| **`@backend`** | Domain Logic & Databases | API tasarımı, branded types, katmanlı mimari (Route -> Controller -> Service -> Repository). |
+| **`@frontend`** | Fluid Responsive UI | Panda CSS tasarımı, responsive-first arayüzler, custom React kancaları, rollback disiplini yönetimi. |
+| **`@devops`** | Infrastructure & CI/CD | Native Node.js deploymentları, rollback planları, telemetri ve izleme (monitoring) kurulumları. |
+| **`@explorer`** | Codebase Discovery | Kod tabanı analizi, bağımlılık grafikleri, legacy onboarding stratejileri. |
+| **`@git`** | Version Control | Trace ID uyumlu commit yönetimi, sürüm etiketleme ve dal (branch) hijyeni. |
+| **`@mobile`** | Mobile App | Expo ve React Native tabanlı mobil arayüz geliştirme otomasyonları. |
+| **`@native`** | Native OS Integration | Tauri ve Electron tabanlı yerel masaüstü uygulama entegrasyonları. |
+| **`@security`** | Security & Cryptography | Kimlik doğrulamaları, CSP kuralları, API anahtarı rotasyonları ve RLS yetkilendirme kapısı. |
+| **`@analyst`** | Contract Verification | Veritabanı kontrat doğrulaması, anayasal uyum denetimi ve bağımsız kalite analizleri. |
+
+---
+
+### 🪙 Token Ekonomisi ve Bellek Mimarisi (Token Economy & Memory Design)
+
+Agent Enderun, otonom yazılım geliştirme süreçlerinde **bağlam driftini (context drift) engellemek** ve **API maliyetlerini %90 oranında düşürmek** amacıyla katmanlı bir bellek mimarisi ve token ekonomisi protokolü kullanır.
+
+#### A. Katmanlı Bellek Modeli (Tiered Memory Model)
+Sistem, projenin ortak aklını ve ajanların özel seans bağlamlarını 3 farklı katmanda saklar:
+1. **Ortak Proje Hafızası (`.enderun/memory/PROJECT_MEMORY.md`):** Aktif fazı, benzersiz Trace ID'yi, kritik mimari kararları ve ordu çapındaki aktif görevleri (DAG) tutan projenin ortak SSOT beynidir.
+2. **Paylaşılan Genel Gerçekler (`memory-graph/shared-facts.json`):** Teknolojik stack tercihleri, aktif kodlama politikaları ve kontrat hash adresleri gibi statik verileri barındırır.
+3. **Özel Ajan Bellekleri (`memory-graph/agent-contexts/{agent}.json`):** Her uzman ajanın kendi geçmiş seans özetlerini, üstlendiği kararları ve üzerinde çalıştığı aktif geliştirme detaylarını tutan yalıtılmış bellek hücreleridir.
+
+#### B. Seans İçi Bellek Akışı (Memory & Token Flow)
+Yapay zeka ajanları her oturumda veya görev atamasında şu akışı otonom olarak takip eder:
+* **Oturum Başlangıcı (Startup):** Ajan `read_project_memory` ile ortak faz ve Trace ID bilgisini geri yükler; ardından `get_agent_context` ile kendi özel bellek hücresini okuyarak seans geçmişini hatırlar.
+* **Çalışma Esnası (Work):** Ajan, kod tabanını bütünüyle okumak yerine `search_codebase` veya `get_project_gaps` araçlarıyla milimetrik hedef tespitleri yapar. Yalnızca ilgili kod parçacıkları bağlama eklenir.
+* **Oturum Kapanışı (Handoff):** Ajan eylemi tamamladığında `update_project_memory` ile durumunu kaydeder, `update_agent_context` ile kendi seans özetini günceller ve değişiklikleri günlüğe (`logs/[agent].json`) yazar.
+
+#### C. Token Verimliliği ve Aktif Arşivleme
+* **Bağlam Temizliği:** Ajanların sürekli tüm `PROJECT_MEMORY.md` dosyasını okuması yerine, yalnızca son 3-5 kritik kararı aktif bellekte tutan `get_memory_insights` aracı kullanılır.
+* **Otomatik Budama ve Arşivleme:** Paylaşılan proje geçmişi **10 kaydı aştığında**, sistem eski geçmiş girdilerini otonom olarak `.enderun/memory-graph/archive/` dizinine taşır. Böylece prompt boyutu her zaman optimum seviyede kalır.
 
 ---
 
-### 🛠️ Kurulum & Adaptör Entegrasyonu
+### 🛠️ Kurulum & Adaptör Entegrasyon Kılavuzu
+> [!IMPORTANT]
+> **Mimari Hatırlatma:** Model Context Protocol (MCP) araçları, **insan geliştirici (kullanıcı) tarafından manuel olarak çalıştırılmaz.** MCP sunucu araçları; yapay zeka ajanlarının (Claude Code, Gemini, Grok) projeniz üzerinde cerrahi kod yazma, durum sorgulama ve Hermes mesajlaşma gibi eylemleri **otonom olarak çalıştırabilmesi** için arka planda yapay zeka motorlarına bağlanır. İnsan geliştirici ise komuta sürecini CLI (`status`, `trace:new` vb.) üzerinden yönetir.
+
+#### 1. Gemini Adaptörü Kurulumu
+Gemini CLI veya Vertex AI entegrasyonu için proje dizininizde aşağıdaki komutu çalıştırın:
+```bash
+npx agent-enderun init gemini
+```
+*   **Birleşik Mimari (Önerilen):** Tüm adaptörleri tek klasörde birleştirip kalabalığı önlemek için `--unified` parametresini kullanın:
+    ```bash
+    npx agent-enderun init gemini --unified
+    ```
+
+#### 2. Claude Adaptörü Kurulumu (Claude Code & Desktop)
+Claude Desktop uygulamasında ve Claude Code CLI aracında otonom orduyu aktif etmek için:
+```bash
+npx agent-enderun init claude
+```
+
+#### 3. Grok Adaptörü Kurulumu
+xAI Grok Build veya topluluk CLI araçları için:
+```bash
+npx agent-enderun init grok
+```
 
+#### 4. Cursor Adaptörü Kurulumu
+Cursor IDE kuralları ve MCP entegrasyonu için:
 ```bash
-# Projeyi başlatın
+npx agent-enderun init cursor
+```
+
+#### 5. Codex (GitHub Copilot) Adaptörü Kurulumu
+VSCode ve GitHub Copilot özel talimatları için:
+```bash
+npx agent-enderun init codex
+```
+
+#### 6. Antigravity Adaptörü Kurulumu
+Antigravity IDE ve CLI entegrasyonlarını etkinleştirmek için:
+```bash
+npx agent-enderun init antigravity-cli
+```
+
+---
+
+### 🧠 Mimari Yapı: Beyin & Hafıza Merkezi (.enderun)
+
+Sistem artık tüm zekasını ve persistence verilerini projenin kök dizininde kalabalık yapmadan **`.enderun/`** klasörü altında toplar:
+
+*   **`.enderun/memory/`**: `state.json`, `status.json` ve aktif görevler (`tasks/`).
+*   **`.enderun/knowledge/`**: Kurumsal standartlar ve ESLint kuralları.
+*   **`.enderun/ENDERUN.md`**: Proje anayasası ve disiplin kuralları.
+
+### 🕹️ CLI Komut Referansı ve Parametreleri
+
+Enderun CLI, `agent-enderun` (veya `npx agent-enderun`) komutu ile yönetilir.
+
+*   **`init [adapter] [--unified]`**: Seçilen adaptörü kurar. `--unified` kullanılırsa tüm asistan şimleri doğrudan `.enderun` altında birleşir; klasör kalabalığı sıfırlanır. Init sonrası **otomatik AL (Agent Lifecycle) validation** çalıştırılır.
+*   **`status`**: Projenin aktif fazını (Phase 0 - 4), aktif Trace ID'sini ve uzman ajanların durumlarını listeler.
+*   **`check`**: Anayasal uyumluluk denetimlerini + **otomatik AL Army Validation** (stateMachine + tags) gerçekleştirir.
+*   **`validate` / `validate-army` / `check:al`**: Bağımsız Agent Lifecycle (AL) ordu validasyonu çalıştırır (paketli validator script; `node bin/...` yerine bu CLI komutlarını kullanın, npm kurulumunda da çalışır).
+*   **`trace:new [description]`**: Belirli bir geliştirme zinciri için yeni bir Trace ID (ULID) tetikler.
+*   **`orchestrate` / `loop`**: Hermes Message Broker asenkron event-driven ajanlar arası iletişim döngüsünü canlı olarak başlatır.
+*   **`verify-contract`**: Frontend ve backend katmanları arasındaki tip bütünlüğünü denetler.
+*   **`update-contract`**: Backend tiplerinde yapılan değişiklikleri tarayarak `contract.version.json` üzerindeki SHA-256 hash imzalarını günceller.
+*   **`create-app [idea]`**: Doğal dildeki açıklamalardan; kurumsal standartlarda **Web, Mobil (Expo/React Native) veya Backend** tabanlı kontrat-tabanlı monorepo uygulaması üretir.
+*   **`approve [traceId]`**: Ajanlar tarafından gönderilen idari veya yüksek riskli işlemleri (şema değişiklikleri, toplu silme vb.) doğrulamak ve onaylamak için insan denetçi (Human-in-the-Loop) onay komutudur.
+
+---
+
+### 📦 Geliştirici & npm Link Test Altyapısı
+
+Paketi npm'de yayınlamadan önce yerelinizde derlemek ve test etmek için:
+```bash
+# Proje bağımlılıklarını yükleyin
+npm install
+
+# framework-mcp (MCP Sunucusu) ve CLI derlemelerini tetikleyin
+npm run enderun:build
+
+# Paketi global NPM havuzunuza bağlayın
+npm link
+
+# Boş bir test dizini açıp aracı bağlayın
+mkdir enderun-test && cd enderun-test
+npm init -y
+npm link agent-enderun
+
+# Herhangi bir adaptör kurulumunu başlatın
 npx agent-enderun init gemini --unified
 ```
 
-### 📦 Geliştirici Komutları
+---
+---
+
+## 🇺🇸 ENGLISH — Detailed Product Guide & Documentation
+
+**Agent Enderun** is the Supreme AI Governance & Autonomous Orchestration Framework for Enterprise Development. It acts as a Corporate AI Management Assistant. It is not a generic boilerplate generator or a simple AI wrapper; it is an elite, state-of-the-art **AI Governance and Autonomous Army Command System** designed for complex, scalable, and highly auditable enterprise software projects.
+
+The framework operates as a **"Living Engineering Organism"** capable of managing its own persistent memory, dynamically mapping project directory scopes, secure-logging expert agent activities, **automatically enforcing Agent Lifecycle (AL) compliance on every init**, **resolving absolute project root paths (CWD) dynamically for external assistant tools (e.g. Claude Desktop/Cursor)**, **enforcing Corporate CRUD & Admin Governance rules**, **providing atomic concurrency safety via Hermes Lock Protocol**, **mapping agent scaffolding subdirectories to adapter-specific folders dynamically during init**, and **fully complying with cross-platform (macOS & Windows) scripting and standard setups**. Low-usage reference materials arranged (knowledge files, demo scripts, observability placeholders marked). Bloat removed. Optimized for complex corporate/enterprise projects via corporate-governance knowledge and SOPs.
+
+---
+
+### ❓ Why Agent Enderun?
+
+As AI coding assistants (Claude Code, Gemini CLI, Grok Build, etc.) become increasingly powerful, software projects are prone to rapid architectural drift and token wastage. Agent Enderun solves these critical **enterprise AI challenges**:
+
+1. **Rogue AI Prevention (Surgical Edits):** It strictly prohibits agents from rewriting entire files. Instead, it forces them to execute micro-targeted changes via **`replace_text` / `patch_file` tools**, reducing API token consumption by up to 90%.
+2. **Context Loss Prevention (SSOT Memory):** AI agents naturally lose project history across chats. Enderun seals all project milestones, decisions, and tasks into a self-pruning **`.enderun/memory/PROJECT_MEMORY.md`** file, ensuring absolute context continuity.
+3. **Contract-First Safety (Frontend-Backend Drift):** Before any user interface code is written, API models and branded types are sealed. The **autonomous** contract verification engine checks SHA-256 type definitions to prevent integration drifts.
+4. **Symmetric Orchestration (Hermes Protocol):** **12** specialized expert agents communicate via an asynchronous, event-driven message broker (**Hermes**), preventing chaotic, uncoordinated AI behavior.
+5. **Atomic Concurrency Safety (Hermes Lock Protocol):** Prevents concurrent file access and race conditions at the OS level using atomic lock file creation (`flag: 'wx'`). If a lock is active, writing agents wait and retry sequentially.
+6. **Corporate CRUD & Admin Governance:** Strictly forbids specialist agents from performing critical/admin mutations (user/role creation, schema modifications, database migrations, bulk deletions) autonomously. These are routed as `ALERT` approvals to `@manager` and require human sign-off via the `approve` command.
+
+---
+
+### 📦 Current Release / Güncel Sürüm
+
+**v1.10.0** — Stable Release (Dynamic Mobile Scaffolding & Performance).
+*   **EN:** Added Mobile (Expo/React Native) scaffolding support. Optimized orchestration loop with in-memory caching. Expanded discipline check (`check`) to audit agent documentation.
+*   **TR:** Mobil (Expo/React Native) uygulama üretme desteği eklendi. Orkestrasyon döngüsü bellek içi önbellekleme (in-memory cache) ile optimize edildi. Nizam denetimi (`check`) ajan dökümantasyonunu kapsayacak şekilde genişletildi.
+
+---
+
+### 💎 Strategic Platform Synergy (The Four Powers)
+
+Agent Enderun coordinates industry-leading AI environments by assigning each a specific strategic military role:
+* **🚀 Claude Code (Operational Surgery):** The **Field Engineer**. Excels in executing precise, surgical, and autonomous codebase edits.
+* **♊ Gemini & Vertex AI (Command Intelligence):** The **Command Center**. Analyzes project history, memory logs, and executes high-level strategic decisions.
+* **🛸 Antigravity (Internal Discipline):** The **Military Academy**. Provides an isolated, high-discipline sandbox to preserve internal framework coding standards.
+* **🤖 Grok / X.ai (Scouting Wing):** The **Scouting Specialist**. Explores futuristic agent behaviors and tests experimental protocols.
+
+---
+
+### 🪖 The Consolidated 13-Agent Army
+
+All workspace operations are divided among 13 specialized expert agents connected via the Hermes protocol:
+
+| Agent | Specialization Role | Core Responsibility |
+| :--- | :--- | :--- |
+| **`@manager`** | Orchestration & Governance | Task dependency graphs (DAG), memory pruning (`PROJECT_MEMORY.md`), constitution compliance. |
+| **`@architect`** | System Design & Architect | Core architecture, type contracts, and governance lock design. |
+| **`@quality`** | Automated Testing & Quality | AST vulnerability scanning, constitutional audits, code review checklists, test standard gates. |
+| **`@database`** | Database Migrations & Tuning | Database schemas, migration workflows, query optimization, and contract-aware seeding. |
+| **`@backend`** | Domain Logic & Databases | API route design, branded types, layered architecture (Route -> Controller -> Service -> Repository). |
+| **`@frontend`** | Fluid Responsive UI | Panda CSS design, responsive-first interfaces, customized React hooks, rollback discipline management. |
+| **`@devops`** | Infrastructure & CI/CD | Native Node.js deployments, rollback plans, monitoring & logging setups. |
+| **`@explorer`** | Codebase Intelligence | Project analysis, dependency graph generation, legacy conversion strategies. |
+| **`@git`** | Version Control | Semantic Trace-ID-aligned commits, branch hygiene. |
+| **`@mobile`** | Mobile App | React Native / Expo UI automation and native builds. |
+| **`@native`** | Native OS Integration | Tauri and Electron desktop app integrations. |
+| **`@security`** | Security & Cryptography | Security credentials, CSP configurations, API key rotations, and RLS authorization gate. |
+| **`@analyst`** | Contract Verification | Database contract verification, constitutional compliance audits, and independent quality analysis. |
+
+---
+
+### 🪙 Token Economy & Memory Architecture
+
+Agent Enderun utilizes a strongly-disciplined **Tiered Memory Model** and **Token Economy Protocol** to prevent context drift and reduce LLM prompt API consumption by up to **90%** during autonomous execution loops.
+
+#### A. The Tiered Memory Model
+The framework manages shared project knowledge and isolated specialist history across 3 robust layers:
+1. **Shared Project Memory (`.enderun/memory/PROJECT_MEMORY.md`):** The project's shared SSOT (Single Source of Truth) brain containing the active phase, unique Trace ID, critical architectural decisions, and the army's active DAG tasks.
+2. **Shared General Facts (`memory-graph/shared-facts.json`):** Holds static declarations including the active technology stack, core policies, and sealed contract version hashes.
+3. **Private Agent Contexts (`memory-graph/agent-contexts/{agent}.json`):** Sandboxed memory files storing the recent execution state, specific choices, and targeted tasks completed by each specialist.
+
+#### B. Dynamic Session Memory Flow
+Enderun specialists autonomously coordinate context loading using the following pipeline:
+* **Startup:** The agent retrieves active phase/trace context via `read_project_memory` and loads its private seans records using `get_agent_context` to instantly restore execution state.
+* **Execution:** Instead of loading full codebase contents, specialists utilize index-based codebase queries (`search_codebase`, `get_project_gaps`) to selectively mount only the impacted files/functions.
+* **Handoff & Shutdown:** Once a task is completed, the agent updates the shared history via `update_project_memory`, seals its private state via `update_agent_context`, and writes semantic action logs.
+
+#### C. Token Compaction & Active Archiving
+* **Context Compaction:** Instead of parsing the complete, extensive `PROJECT_MEMORY.md` in every prompt, agents call `get_memory_insights` to extract only the recent release-critical tasks and decisions.
+* **Self-Pruning History:** When the active history list **exceeds 10 entries**, the framework automatically prunes and archives older records into `.enderun/memory-graph/archive/`. This maintains an elite, high-performance prompt size.
+
+---
+
+### 🛠️ Adapter Scaffolding & Setup Guide
+> [!IMPORTANT]
+> **Architectural Note:** Model Context Protocol (MCP) tools are **not meant to be executed manually by the human developer (user).** Instead, the MCP server runs in the background, allowing AI Agents (Claude Code, Gemini, Grok) to **autonomously execute** our custom tools (like surgical editing, state reading, or Hermes messaging) on your codebase. The human developer controls and monitors this command loop using standard CLI commands (`status`, `trace:new`, etc.).
+
+#### 1. Gemini Adapter
+Initialize the Gemini CLI / Vertex AI environment:
+```bash
+npx agent-enderun init gemini
+```
+*   **Unified Architecture (Recommended):** Use `--unified` to merge all adapters into a single folder and prevent folder clutter:
+    ```bash
+    npx agent-enderun init gemini --unified
+    ```
+
+#### 2. Claude Adapter (Claude Code CLI & Desktop App)
+Bootstrap the framework for Anthropic's Claude:
+```bash
+npx agent-enderun init claude
+```
+
+#### 3. Grok Adapter
+Scaffold for xAI Grok Build:
+```bash
+npx agent-enderun init grok
+```
+
+#### 4. Antigravity Adapter
+Bootstrap the high-discipline sandbox for Antigravity IDE and CLI runtimes:
+```bash
+npx agent-enderun init antigravity
+```
+
+---
+
+### 🕹️ CLI Command Reference
+
+> **AL commands included:** `validate`, `validate-army`, `check:al` for dedicated Agent Lifecycle (AL) validation. `check` and `init` automatically enforce AL compliance (cross-adapter, npm installs supported).
+
+Execute commands via `agent-enderun` (or `npx agent-enderun`):
+
+*   **`init [adapter] [--unified]`**: Scaffold framework directories and register local/global MCP server instances.
+*   **`status`**: Output active Phase (0-4), current active Trace ID, and agent capability logs.
+*   **`check`**: Run a thorough framework integrity, folder alignment, and constitutional compliance check.
+*   **`trace:new [desc] [agent] [priority]`**: Launch a new traceable task chain stamped with a unique ULID.
+*   **`orchestrate` / `loop`**: Launch the Hermes live event-driven message-routing loop for asynchronous agent synchronization.
+*   **`verify-contract`**: Perform a contract audit to ensure frontend types match backend schemas.
+*   **`update-contract`**: Re-calculate type definitions and update `contract.version.json` with a new SHA-256 hash.
+*   **`create-app [idea]`**: Autonomously generate a full-stack monorepo, **Web, Mobile (Expo/React Native), or Backend** project starter based on natural language inputs.
+*   **`approve [traceId]`**: Human-in-the-Loop command to sign off and approve high-risk/administrative tasks requested by agents.
 
-*   **`npm run build`**: TypeScript derlemesini ve MCP paketlerini inşa eder.
-*   **`npm run enderun:test`**: Tüm birim ve entegrasyon testlerini çalıştırır.
-*   **`npm run enderun:check`**: Compliance Scanner ile kod disiplinini denetler.
-*   **`npm run enderun:docs`**: Ajan tanımlarından dokümantasyonu günceller.
 
 ---
 
-Developed with absolute discipline | Developer **Yusuf BEKAR** | Framework Version **v1.1.10 (Final Stable)** — Enterprise-ready.
+Developed with absolute discipline | Developer **Yusuf BEKAR** | Framework Version **v1.10.0 (Final Clean)** — Low-usage items arranged as reference-only. Bloat removed. Corporate-ready.

package/bin/cli.js

@@ -2,12 +2,19 @@
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import fs from "node:fs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 const cliPath = join(__dirname, "../dist/src/cli/index.js");
 
+if (!fs.existsSync(cliPath)) {
+    process.stderr.write("\n❌ Error: Compiled CLI not found at 'dist/src/cli/index.js'\n");
+    process.stderr.write("💡 Solution Tip: Run 'npm run build' to compile the project first.\n\n");
+    process.exit(1);
+}
+
 const cmd = "node";
 const child = spawn(cmd, [cliPath, ...process.argv.slice(2)], {
     stdio: "inherit",