agent-enderun 0.9.0 → 0.9.1

package/README.md

@@ -1,143 +1,245 @@
-# 🏛️ Agent Enderun — Supreme Enterprise AI Governance Framework (v0.9.0)
+# 🏛️ Agent Enderun — Enterprise AI Governance & Autonomous Orchestration Framework
 
-[English](#english) | [Türkçe](#türkçe)
+> **Stable Release:** v0.9.1  
+> **Author:** Yusuf BEKAR  
+> **Trace ID:** `01HGT8J5E2N0W0W0W0W0W0W0W4`  
+> **System Status:** 🟢 All Systems Operational | Build Compile: Clean | Type-Safety: 100% Verified
 
 ---
 
-# English
+## 🇹🇷 TÜRKÇE — Proje Tanıtımı & Dokümantasyonu
 
-**Agent Enderun** is not just a code generator; it is a high-discipline **AI Governance & Autonomous Command System** designed for complex, scalable, and fully auditable enterprise software projects. 
+**Agent Enderun**, 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**.
 
-With v0.9.0, the framework has evolved into a **"Living Engineering Organism"** that manages its own memory, performs surgical codebase modifications, and unifies diverse AI ecosystems under a single constitutional discipline.
+Sürüm **v0.9.1** itibarıyla sistem; kendi hafızasını yönetebilen, monorepo proje yollarını dinamik olarak haritalayan ve farklı yapay zeka ekosistemlerini anayasal bir disiplin altında birleştiren **"Yaşayan Bir Mühendislik Organizması"** haline getirilmiştir.
 
-## 💎 Strategic Platform Synergy (The Core Four)
+---
+
+### 🚀 Sürüm v0.9.1 İle Gelen Devrimsel Yenilikler
+
+1. **Dinamik Framework Klasör Keşfi (Multi-Adapter Engine):**
+   * Artık `.enderun` klasörü sistemde katı olarak kodlanmış (hardcoded) tek dizin değildir.
+   * CLI aracı; çalışma anında projede aktif olan framework klasörünü `[.gemini, .claude, .agent, .enderun]` adayları arasından otomatik olarak keşfeder. Bu sayede her IDE veya yapay zeka ajanı (Claude Code, Gemini CLI, Grok) kendi izole klasöründe çakışma yaşamadan çalışabilir.
+
+2. **Yapılandırılabilir Klasör Haritalaması (Dynamic Paths Map):**
+   * Projede kullanılan `backend`, `frontend`, `docs` ve `tests` dizin yolları artık dinamik olarak yönetilir.
+   * Keşfedilen aktif framework klasöründeki `config.json` içerisinde yer alan `paths` bloğu projenin Single Source of Truth (SSOT) yol haritasıdır:
+     ```json
+     "paths": {
+       "backend": "apps/backend",
+       "frontend": "apps/web",
+       "docs": "docs",
+       "tests": "tests"
+     }
+     ```
+   * Tüm sözleşme doğrulama (`verify-contract`), sistem bütünlük denetimi (`check`) ve kod üreticileri bu yapılandırmayı tüketir.
+
+3. **Hermes Otonom Orkestrasyon Döngüsü (`orchestrate` / `loop`):**
+   * Yapay zeka ajanlarının asenkron olay tabanlı (event-driven) haberleşme kanalı olan **Hermes Message Broker** devreye alındı.
+   * `agent-enderun orchestrate` komutu, kuyruktaki asenkron delege görevleri tarar, hedef ajanın durumunu ordu paneli üzerinde (`STATUS.md`) anlık olarak `EXECUTING` yapar ve görevi otonom olarak yönlendirir.
+
+4. **Mükemmel Tip Güvenliği & Linter Uyumluluğu:**
+   * Tüm CLI ve yardımcı betikler (`update-contract.js`, `init-check.js`) dinamik yol mimarisine entegre edildi.
+   * `npx tsc --noEmit` tip kontrolü sıfır hata ile %100 temiz çalışır.
+   * `eslint.config.js` kuralları, izole edilmiş çalışma anı ortamlarında (sandbox) oluşabilecek EPERM (erişim engellendi) hatalarını önlemek amacıyla gizli framework dizinlerini tamamen yoksayacak şekilde kusursuzlaştırıldı.
+
+---
+
+### 💎 Stratejik Platform Sinerjisi (Dört Büyük Güç)
 
-Agent Enderun integrates the world's most powerful AI ecosystems, mapping each to a specific strategic role within the project:
+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.
 
-1.  **🚀 Claude Code (Operational Surgery):** The project's **Field Engineer**. With unrivaled file-system speed and the `patch_file` tool, it manages autonomous code edits with surgical precision.
-2.  **♊ Gemini & Vertex AI (Strategic Brain):** The **Command Center**. Utilizing a 2M+ token context window, it analyzes the entire project history and architectural map simultaneously to make high-level decisions.
-3.  **🛸 Antigravity (Internal Discipline):** The **Military Academy**. A high-discipline, isolated environment designed to enforce internal project standards and rigorous AI training.
-4.  **🤖 Grok / X.ai (Reconnaissance Unit):** The **Autonomous Vision**. Used for testing futuristic agent protocols and pushing the boundaries of AI-native development.
+---
+
+### 🪖 Konsolide Edilmiş 10 Ajanlık Ordu Yapısı
 
-## 🛡️ The Five Pillars of Enderun Discipline
+Tüm operasyonlar, uzmanlık alanlarına göre ayrılmış ve Hermes protokolüyle birbirine bağlanmış 10 aktif ajan tarafından yönetilir:
 
-1.  **Absolute Traceability (Trace ID):** Every decision, commit, and line of code is stamped with a ULID-based Trace ID. Full enterprise auditability is achieved in seconds.
-2.  **Contract-First Law:** No implementation is permitted without verified type contracts. Type safety between `@backend` and `@frontend` is the project's supreme law.
-3.  **Surgical Edit Standard:** Overwriting entire files is prohibited. The system mandates `replace_text` and `patch_file` via MCP for precise, non-destructive modifications.
-4.  **Autonomous Memory Pruning:** `PROJECT_MEMORY.md` never bloats. Histories exceeding 10 entries are auto-archived to keep the context window fresh and cost-efficient.
-5.  **Constitutional SSOT:** All platforms (Claude, Gemini, etc.) are 100% loyal to a single source of truth: the `.enderun/ENDERUN.md` constitution.
+| Ajan | Uzmanlık Rolü | Temel Sorumluluğu |
+| :--- | :--- | :--- |
+| **`@manager`** | Komuta & Strateji | Görev dağılımı (DAG), hafıza yönetimi (`PROJECT_MEMORY.md`), anayasa koruyuculuğu. |
+| **`@quality`** | Kalite, Güvenlik & Analiz | AST zafiyet taramaları, anayasal uyum denetimi, kod inceleme checklistleri, test standartları kapısı. |
+| **`@database`** | Veritabanı Mimarisi | Veritabanı şemaları, migration kuralları, index optimizasyonları ve veri tohumlama (seeding). |
+| **`@backend`** | İş Mantığı (Domain Logic) | API tasarımı, branded types, katmanlı mimari (Route -> Controller -> Service -> Repository). |
+| **`@frontend`** | Akıcı Responsive UI | Panda CSS tasarımı, responsive-first (mobil-öncelikli) arayüzler, custom React kancaları. |
+| **`@devops`** | Altyapı & Canlı Dağıtım | Native Node.js deploymentları, rollback planları, telemetri ve izleme (monitoring) kurulumları. |
+| **`@explorer`** | Kod Analizi & Keşif | Kod tabanı analizi, bağımlılık grafikleri, legacy onboarding stratejileri. |
+| **`@git`** | Sürüm Kontrolü | Trace ID uyumlu commit yönetimi, sürüm etiketleme ve dal (branch) hijyeni. |
+| **`@mobile`** | Mobil Geliştirme | Expo ve React Native tabanlı mobil arayüz geliştirme otomasyonları. |
+| **`@native`** | Native Masaüstü | Tauri ve Electron tabanlı yerel masaüstü uygulama entegrasyonları. |
 
-## 🛠️ Installation & Deployment
+---
 
-Initialize the framework for your preferred platform with a single command:
+### 🛡️ Enderun Disiplininin 5 Temel Direği
 
+1. **Mutlak İzlenebilirlik (Trace ID):** Her karar, işlem ve commit, denetlenebilir olması adına 26 karakterli benzersiz bir ULID (Trace ID) ile mühürlenir.
+2. **Önce Kontrat (Contract-First):** Backend ve frontend arasındaki veri kontratları ve tipler, herhangi bir arayüz kodu yazılmadan önce kesin olarak kilitlenir.
+3. **Cerrahi Düzenleme Standardı:** Tüm dosyayı baştan yazmak yasaktır. Sadece değişmesi gereken satırlar `replace_text` / `patch_file` araçlarıyla milimetrik olarak değiştirilir.
+4. **Otonom Bellek Arşivleme:** `PROJECT_MEMORY.md` kendi kendini temizleyen ve en güncel durumu koruyan bir SSOT (Single Source of Truth) olarak çalışır.
+5. **Anayasal Otorite:** Tüm ajanlar `.enderun/ENDERUN.md` içinde tanımlanan Supreme Law (Yüce Yasa) kurallarına kayıtsız şartsız uymak zorundadır.
+
+---
+
+### 🛠️ CLI Komut Referansı
+
+| Komut | Yetkili Ajan | Açıklama |
+| :--- | :--- | :--- |
+| `init [adapter]` | `@manager` | Seçilen IDE/Agent adaptörünü (`gemini`, `claude`, `grok`, `antigravity`) yerel projenize kurar. |
+| `status` | `@manager` | Aktif aşamayı, aktif Trace ID'yi ve ajanların anlık ordu durumlarını listeler. |
+| `check` | `@quality` | Anayasal sağlık kontrolü, dosya bütünlüğü ve dizin doğrulaması yapar. |
+| `trace:new [desc]` | `@manager` | Yeni bir Trace ID başlatarak görev zincirini ve izlenebilirliği tetikler. |
+| `orchestrate` / `loop` | `@manager` | Canlı Hermes mesaj yönlendirici döngüsünü başlatarak asenkron ajan görevlerini yönlendirir. |
+| `verify-contract` | `@backend` | Backend ile frontend arasındaki tip uyumluluğunu kilitler ve doğrular. |
+| `create-app [idea]` | `@manager` | Doğal dildeki talep ve gereksinimlerden kurumsal monorepo uygulaması oluşturur. |
+
+---
+
+### 📦 npmjs Yayınlama & Prepublish Otomasyonu
+
+Agent Enderun, npmjs üzerinde paketlenmeye kusursuz şekilde hazırdır:
+* **Hazır Derleme Otomasyonu (`prepublishOnly`):** Paket yayına gönderilmeden önce `"prepublishOnly"` kancası tetiklenir ve `framework-mcp` (MCP Server) en güncel haliyle derlenerek dağıtıma hazır hale getirilir.
+* **CLI Kaynak Bütünlüğü:** Tüm TypeScript derleme kaynakları (`src/`) paket içeriğine dahil edilmiştir, böylece son kullanıcı yüklemelerinde çalışma anı çalışma çökmeleri önlenmiştir.
+
+Yerel projenizi test etmek veya npm link üzerinden kurmak için:
 ```bash
-# For Gemini CLI and Antigravity (Standard)
-agent-enderun init gemini
+# Bağımlılıkları kurun ve MCP sunucusunu derleyin
+npm install
+npm run enderun:build
 
-# For Claude Code (CLI & Desktop) — Optimized for Surgery
-agent-enderun init claude
+# Paketi yerel NPM havuzunuza linkleyin
+npm link
 
-# For Antigravity IDE/CLI Independent Setup
-agent-enderun init antigravity
+# Test etmek istediğiniz boş bir klasöre gidin ve aracı bağlayın
+mkdir test-projem && cd test-projem
+npm init -y
+npm link agent-enderun
 
-# For Grok Build / X.ai Autonomous Agents
-agent-enderun init grok
+# Adaptörü başlatın
+npx agent-enderun init gemini
 ```
 
-## 📋 CLI Command Registry
-
-| Command | Description |
-| :--- | :--- |
-| `status` | Shows the active phase, Trace ID, and real-time agent health scores. |
-| `check` | Audits system health, MCP connectivity, and constitutional integrity. |
-| `trace:new` | Starts a new task chain with a unique ID and briefs the Army. |
-| `create-app` | Generates an enterprise monorepo (Fastify/React) from natural language. |
-| `verify-contract` | Seals the type alignment between backend and frontend modules. |
-
-## 📂 Architecture Map
-
-```text
-├── .enderun/               <-- The Framework Brain
-│   ├── agents/             <-- 12 Specialist Directives (Manager, Architect, QA...)
-│   ├── knowledge/          <-- Enterprise Standards (ESLint, API, Security)
-│   ├── memory-graph/       <-- Shared Facts & Agent Private Contexts
-│   ├── queue/              <-- Hermes Messaging & Task Queue
-│   └── ENDERUN.md          <-- The Supreme Constitution
-├── apps/                   <-- Enterprise Application Space
-├── docs/                   <-- Project Architectural Portal (ADRs, Tech-Stack)
-└── framework-mcp/          <-- Autonomous Operations Server
-```
+---
+---
+
+## 🇺🇸 ENGLISH — Project Showcase & Documentation
+
+**Agent Enderun** is not just a boilerplate code generator or a simple AI assistant; it is a state-of-the-art **AI Governance and Autonomous Army Command System** designed for highly complex, scalable, and fully auditable enterprise software projects.
+
+As of **v0.9.1**, the system operates as a **"Living Engineering Organism"** capable of managing its own memory, dynamically mapping monorepo project subfolders, and uniting disparate AI ecosystems under a single constitutional discipline.
 
 ---
 
-# Türkçe
+### 🚀 Key Improvements in Version v0.9.1
+
+1. **Dynamic Framework Directory Discovery (Multi-Adapter Engine):**
+   * The `.enderun` folder is no longer hardcoded as the sole runtime path.
+   * The CLI dynamically discovers the active framework folder from a candidate list `[.gemini, .claude, .agent, .enderun]`. This allows different AI agents or adapters (Claude Code, Gemini CLI, Grok) to operate in isolated workspaces without folder conflicts.
+
+2. **Configurable Path Mapping (Dynamic Paths Map):**
+   * Directories for `backend`, `frontend`, `docs`, and `tests` are fully dynamic and configurable.
+   * Path settings are read from the `paths` block inside the active framework's `config.json` as the Single Source of Truth (SSOT):
+     ```json
+     "paths": {
+       "backend": "apps/backend",
+       "frontend": "apps/web",
+       "docs": "docs",
+       "tests": "tests"
+     }
+     ```
+   * All validations (`verify-contract`), integrity checks (`check`), and scaffolding engines utilize this mapping.
+
+3. **Hermes Autonomous Orchestration Loop (`orchestrate` / `loop`):**
+   * Enabled the **Hermes Message Broker**—an event-driven asynchronous communication channel between expert AI agents.
+   * The `agent-enderun orchestrate` command scans pending message queues, dynamically locks the target agent's state to `EXECUTING` on the dashboard (`STATUS.md`), and routes tasks autonomously.
+
+4. **Flawless Type-Safety & Linter Optimization:**
+   * All CLI commands and auxiliary binaries (`update-contract.js`, `init-check.js`) have been migrated to the dynamic paths registry.
+   * The type-checking command `npx tsc --noEmit` runs with **zero errors**.
+   * Upgraded `eslint.config.js` to completely ignore hidden framework files, preventing potential OS-level permission conflicts (`EPERM`) in sandboxed terminal environments.
 
-**Agent Enderun**, sıradan bir kod üreticisi değil; karmaşık, ölçeklenebilir ve mutlak denetlenebilir kurumsal yazılım projeleri için tasarlanmış bir **Yapay Zeka Yönetişim ve Otonom Ordu Komuta Sistemidir**.
+---
 
-v0.9.0 sürümüyle birlikte sistem; kendi hafızasını yönetebilen, kod tabanına cerrahi müdahaleler yapabilen ve farklı YZ ekosistemlerini tek bir anayasal disiplin altında birleştiren **"Yaşayan bir Mühendislik Organizması"** haline gelmiştir.
+### 💎 Strategic Platform Synergy (The Four Powers)
 
-## 💎 Stratejik Platform Sinerjisi (Dörtlü Güç)
+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 (Exploration Wing):** The **Autonomous Scouting**. Testing futuristic agent behaviors and pushing AI-driven developer limits.
 
-Agent Enderun, sektördeki en güçlü YZ ekosistemlerini bir araya getirerek her birini proje içinde stratejik bir rolle görevlendirir:
+---
+
+### 🪖 The Consolidated 10-Agent Army
 
-1.  **🚀 Claude Code (Operasyonel Cerrahi):** Projenin **Saha Mühendisi**dir. Dosya sistemi üzerindeki rakipsiz hızı ve `patch_file` aracıyla otonom kod düzenlemelerini cerrahi hassasiyetle yönetir.
-2.  **♊ Gemini & Vertex AI (Stratejik Akıl):** Sistemin **Komuta Merkezi**dir. 2M+ token bağlam kapasitesiyle projenin tüm geçmişini ve mimari yapısını aynı anda analiz ederek üst düzey kararlar alır.
-3.  **🛸 Antigravity (İç Disiplin):** Projenin **Askeri Akademisi**dir. İç standartlarımızı korumak için tasarlanmış, dış dünyadan izole ve yüksek disiplinli geliştirme ortamıdır.
-4.  **🤖 Grok / X.ai (Keşif Birliği):** Projenin **Otonom Vizyonu**dur. Gelecek odaklı ajan protokollerini test etmek ve YZ tabanlı geliştirme sınırlarını zorlamak için kullanılır.
+All workspace operations are divided among 10 specialized expert agents connected via the Hermes protocol:
 
-## 🛡️ Enderun Disiplininin Beş Sarsılmaz Sütunu
+| Agent | Specialization Role | Core Responsibility |
+| :--- | :--- | :--- |
+| **`@manager`** | Command & Strategy | Task dependency graphs (DAG), memory pruning (`PROJECT_MEMORY.md`), constitution compliance. |
+| **`@quality`** | Quality, Security & Analysis | AST vulnerability scanning, constitutional audits, code review checklists, test standard gates. |
+| **`@database`** | Database Architecture | Database schemas, migration workflows, query optimization, and contract-aware seeding. |
+| **`@backend`** | Domain Logic Specialist | API route design, branded types, layered architecture (Route -> Controller -> Service -> Repository). |
+| **`@frontend`** | Fluid Responsive UI | Panda CSS design, responsive-first interfaces, customized React hooks. |
+| **`@devops`** | Infrastructure Specialist | 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, release tagging, branch hygiene. |
+| **`@mobile`** | Mobile Development | React Native / Expo UI automation and native builds. |
+| **`@native`** | Desktop Engineering | Tauri and Electron desktop app integrations. |
 
-1.  **Mutlak İzlenebilirlik (Trace ID):** Her karar, her commit ve her kod satırı ULID tabanlı bir Trace ID ile damgalanır. Kurumsal denetim (audit) saniyeler içinde yapılabilir.
-2.  **Önce Sözleşme (Contract-First):** Backend ve Frontend arasındaki veri kontratları mühürlenmeden kod yazılamaz. Tip güvenliği projenin kutsal yasasıdır.
-3.  **Cerrahi Düzenleme Standardı:** Dosyaların tamamını üzerine yazmak yasaktır. Sistem, sadece değişen satırları güncelleyen `replace_text` ve `patch_file` araçlarını zorunlu kılar.
-4.  **Otonom Hafıza Arşivleme (Auto-Prune):** `PROJECT_MEMORY.md` asla şişmez. 10 kayıt sınırını geçen tarihçeler otomatik arşivlenir; sistem her zaman taze ve ekonomik kalır.
-5.  **Anayasal SSOT:** Tüm platformlar (Claude, Gemini vb.) tek bir üst otoriteye, `.enderun/ENDERUN.md` anayasasına %100 sadakatle bağlıdır.
+---
 
-## 🛠️ Kurulum ve Dağıtım
+### 🛡️ Five Pillars of Enderun Discipline
 
-Kullandığınız platforma göre tek komutla Agent Enderun'u başlatın:
+1. **Absolute Traceability (Trace ID):** Every single decision is stamped with a unique 26-character ULID (Trace ID) for thorough auditing.
+2. **Contract-First:** Backend-frontend data contracts are defined and sealed before any user interface code is written.
+3. **Surgical Edit Standard:** Rewriting entire files is strictly prohibited. Only modified lines are changed using `replace_text` / `patch_file`.
+4. **Autonomous Memory Archiving:** `PROJECT_MEMORY.md` functions as a self-pruning Single Source of Truth (SSOT).
+5. **Constitutional SSOT:** All agents must adhere to the supreme constitutional law defined in `.enderun/ENDERUN.md`.
 
-```bash
-# Gemini CLI ve Antigravity için (Standart)
-agent-enderun init gemini
+---
 
-# Claude Code (CLI & Desktop) için — Cerrahi Odaklı
-agent-enderun init claude
+### 🛠️ CLI Command Map
 
-# Antigravity IDE/CLI Bağımsız Kurulumu
-agent-enderun init antigravity
+| Command | Authoritative Agent | Description |
+| :--- | :--- | :--- |
+| `init [adapter]` | `@manager` | Initialize the framework for a selected adapter (`gemini`, `claude`, `grok`, `antigravity`). |
+| `status` | `@manager` | Display active phase, Trace ID, and agent health scores. |
+| `check` | `@quality` | Perform a constitutional health check, folder structure, and file integrity scan. |
+| `trace:new [desc]` | `@manager` | Start a new task chain with a unique Trace ID. |
+| `orchestrate` / `loop` | `@manager` | Spin up the live Hermes message-broker loop to route asynchronous agent actions. |
+| `verify-contract` | `@backend` | Verify and seal type alignment between backend and frontend contracts. |
+| `create-app [idea]` | `@manager` | Generate a corporate monorepo application from natural language requirements. |
 
-# Grok Build / X.ai Otonom Ajanları İçin
-agent-enderun init grok
-```
+---
+
+### 📦 npmjs Publication & Prepublish Automation
+
+Agent Enderun is fully optimized for immediate publication to npmjs:
+* **Prepublish Build Automation Hook (`prepublishOnly`):** Triggers `npm run enderun:build` before publishing, ensuring compiled Model Context Protocol (MCP) server binaries are always built and up-to-date.
+* **CLI Source Bundle Inclusion:** Bundles the `"src"` folder in the published package, preventing downstream execution crashes on typescript-enabled runtime environments.
+
+To test the package locally via npm link:
+```bash
+# Install root dependencies and build MCP
+npm install
+npm run enderun:build
+
+# Create a global npm link
+npm link
+
+# Create a test folder and link package
+mkdir test-project && cd test-project
+npm init -y
+npm link agent-enderun
 
-## 📋 CLI Komut Rehberi
-
-| Komut | Açıklama |
-| :--- | :--- |
-| `status` | Aktif fazı, Trace ID'yi ve ajanların anlık sağlık skorlarını gösterir. |
-| `check` | Sistemin anayasal sağlığını ve dosya bütünlüğünü denetler. |
-| `trace:new` | Yeni bir görev zinciri başlatır ve orduyu görevlendirir. |
-| `create-app` | Doğal dilden kurumsal monorepo (Fastify/React) üretir. |
-| `verify-contract` | Backend ve Frontend arasındaki tip uyumluluğunu mühürler. |
-
-## 📂 Sistem Mimarisi
-
-```text
-├── .enderun/               <-- Sistemin Beyni
-│   ├── agents/             <-- 12 Uzman Ajan Direktifi (Manager, Architect, QA...)
-│   ├── knowledge/          <-- Kurumsal Akıl (ESLint, API, Güvenlik Standartları)
-│   ├── memory-graph/       <-- Ortak Hafıza ve Ajan Bağlamları
-│   ├── queue/              <-- Hermes Mesajlaşma ve Görev Kuyruğu
-│   └── ENDERUN.md          <-- Proje Anayasası (Üst Yasa)
-├── apps/                   <-- Kurumsal Uygulama Alanı
-├── docs/                   <-- Proje Mimari Portalı (ADRs, Tech-Stack)
-└── framework-mcp/          <-- Otonom Operasyon Sunucusu
+# Boot the adapter scaffolding
+npx agent-enderun init gemini
 ```
 
 ---
 
-**Geliştiren / Developed by:** Yusuf BEKAR  
-**Sürüm / Version:** v0.9.0  
-**Lisans / License:** MIT
+Developed with absolute discipline | Developer **Yusuf BEKAR** | Framework Version **v0.9.1**

package/bin/cli.js

@@ -8,7 +8,7 @@ const __dirname = dirname(__filename);
 
 const cliPath = join(__dirname, "../src/cli/index.ts");
 
-// shell: false kullanarak argümanların (tırnakların) bozulmasını önle
+// use shell: false to prevent argument (quote) corruption
 const child = spawn("npx", ["tsx", cliPath, ...process.argv.slice(2)], {
     stdio: "inherit",
     shell: false 

package/bin/init-check.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+
+const targetDir = process.cwd();
+
+const candidates = [".gemini", ".claude", ".agent", ".enderun"];
+let frameworkDir = ".enderun";
+for (const dir of candidates) {
+    if (fs.existsSync(path.join(targetDir, dir))) {
+        frameworkDir = dir;
+        break;
+    }
+}
+
+let backend = "apps/backend";
+let docs = "docs";
+
+try {
+    const configPath = path.join(targetDir, frameworkDir, "config.json");
+    if (fs.existsSync(configPath)) {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        if (config.paths) {
+            if (config.paths.backend) backend = config.paths.backend;
+            if (config.paths.docs) docs = config.paths.docs;
+        }
+    }
+} catch (e) {
+    // ignore
+}
+
+const CRITICAL_STRUCTURE = [
+    `${frameworkDir}/agents`,
+    `${frameworkDir}/knowledge`,
+    `${frameworkDir}/memory-graph/agent-contexts`,
+    `${frameworkDir}/logs`,
+    `${frameworkDir}/queue`,
+    `${frameworkDir}/PROJECT_MEMORY.md`,
+    `${docs}/architecture/standards`,
+    `${backend}/src/database`,
+    `${backend}/src/seeds`,
+    `${backend}/migrations`
+];
+
+function checkIntegrity() {
+    console.warn("🔍 Running Agent Enderun Framework Integrity Check...");
+    let isHealthy = true;
+
+    for (const item of CRITICAL_STRUCTURE) {
+        const fullPath = path.join(targetDir, item);
+        if (!fs.existsSync(fullPath)) {
+            console.error(`❌ Missing critical component: ${item}`);
+            isHealthy = false;
+        } else {
+            console.warn(`✅ Verified: ${item}`);
+        }
+    }
+
+    if (isHealthy) {
+        console.warn("\n✨ Framework integrity verified. System is healthy.");
+        process.exit(0);
+    } else {
+        console.error("\n❌ Framework integrity check FAILED. Some components are missing.");
+        process.exit(1);
+    }
+}
+
+checkIntegrity();

package/bin/update-contract.js

@@ -9,8 +9,30 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const projectRoot = path.join(__dirname, "..");
 
-const contractPath = path.join(projectRoot, "apps/backend/contract.version.json");
-const sharedTypesDir = path.join(projectRoot, "apps/backend/src/types");
+const candidates = [".gemini", ".claude", ".agent", ".enderun"];
+let frameworkDir = ".enderun";
+for (const dir of candidates) {
+    if (fs.existsSync(path.join(projectRoot, dir))) {
+        frameworkDir = dir;
+        break;
+    }
+}
+
+let backend = "apps/backend";
+try {
+    const configPath = path.join(projectRoot, frameworkDir, "config.json");
+    if (fs.existsSync(configPath)) {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        if (config.paths && config.paths.backend) {
+            backend = config.paths.backend;
+        }
+    }
+} catch (e) {
+    // ignore
+}
+
+const contractPath = path.join(projectRoot, backend, "contract.version.json");
+const sharedTypesDir = path.join(projectRoot, backend, "src/types");
 
 function collectTypeFiles(dir) {
     const entries = fs.readdirSync(dir, { withFileTypes: true });

package/docs/README.md

@@ -1,45 +1,34 @@
-# 🏛️ Agent Enderun — Kurumsal Mimari ve Yönetişim Portalı
+# Agent Enderun — Governance and Architecture Portal
 
-Bu portal, Agent Enderun framework'ü altında geliştirilen kurumsal projelerin **Merkezi Bilgi Kaynağıdır**. Projenin mimari kararları, standartları ve yönetişim protokolleri burada mühürlenmiştir.
+This portal is the **Central Knowledge Source** for enterprise projects developed under the Agent Enderun framework. The project's architectural decisions, standards, and governance protocols are sealed here.
 
----
-
-## 🏗️ Mimari Felsefemiz: "Disiplinli Otonomi"
+Unlike ordinary projects, Agent Enderun projects are built on a structure where AI agents operate autonomously but are bound by a rigid, human-authored constitution. This documentation is the **Immutable Guide** for both AI agents (Army) and human developers.
 
-Sıradan projelerin aksine, Agent Enderun projeleri yapay zeka ajanlarının otonom çalıştığı ancak insan eliyle yazılmış katı bir anayasaya bağlı kaldığı bir yapıdır. Bu dökümantasyon, hem AI ajanları (Army) hem de insan geliştiriciler için **Değişmez Rehberdir**.
+---
 
-### 📋 Dokümantasyon Rehberi
+### 📋 Documentation Guide
 
-#### [1. Mimari ve Yönetişim (Architecture & Governance)](architecture/)
-*   **[Mimari Karar Kayıtları (ADRs)](architecture/decisions/)**: Projenin kritik dönüm noktalarında alınan kararların "Neden" ve "Nasıl" sorularına verilen cevaplardır.
-*   **[Onay ve Yüksek Riskli İş akışları](architecture/approval-flows.md)**: `managerApproval` token'larının nasıl üretildiği, denetlendiği ve yüksek riskli işlemlerin (örn: veritabanı silme, yetki yükseltme) nasıl mühürlendiği anlatılır.
-*   **[Bildirim Stratejisi](architecture/notification-strategy.md)**: Kullanıcı deneyimini kesintiye uğratmayan, dinamik ve kurumsal bildirim desenleri.
+#### [1. Architecture & Governance](architecture/)
+*   **[Approval & High-Risk Workflows](architecture/approval-flows.md)**: Explains how tokens are generated, audited, and how high-risk actions (e.g., database deletion, privilege escalation) are sealed.
 
-#### [2. Frontend Standartları (Frontend)](frontend/)
-*   **[Bileşen Desenleri (Component Patterns)](frontend/component-patterns.md)**: **Zero-UI-Library** politikamız gereği, tüm bileşenlerin Panda CSS ile nasıl "el yapımı" ve tip-güvenli olarak inşa edileceği rehberi.
-*   **[Form Doğrulamaları](frontend/forms.md)**: Zod ve React hooks ile yönetilen, hata payı sıfır form yönetim sistemleri.
-*   **[Toaster Yapılandırması](frontend/notifications.md)**: Sonner ve benzeri araçların kurumsal tema ile entegrasyonu.
+#### [2. Frontend Standards](frontend/)
+*   **[Component Patterns](frontend/component-patterns.md)**: Zero-UI-Library policy, guide on how all components are hand-crafted and type-safe using Panda CSS.
 
-#### [3. Backend Standartları (Backend)](backend/)
-*   **[Hata Yönetimi (Error Handling)](backend/error-handling.md)**: `DomainError` sınıfları üzerinden, front-end'e sızmayan ve loglarda izlenebilen profesyonel hata yönetim hiyerarşisi.
-*   **[Denetim Günlükleri (Audit Logging)](backend/audit-logging.md)**: Her işlemin bir `Trace ID` ile veritabanına kalıcı olarak nasıl işleneceğinin kontratları.
+#### [3. Backend Standards](backend/)
+*   **[Error Handling](backend/error-handling.md)**: Professional error management hierarchy that does not leak to the front-end and is traceable in logs.
 
 ---
 
-## 🛰️ Faz Bazlı Geliştirme Döngüsü (Life Cycle)
+## 🛰️ Phase-Based Development Life Cycle
+All projects must pass the following 5 phases sequentially and completely:
 
-Tüm projeler aşağıdaki 5 fazı sırasıyla ve eksiksiz geçmek zorundadır:
-
-1.  **PHASE_0 (Keşif):** Teknoloji yığını (`tech-stack.md`) mühürlenir, risk analizi yapılır.
-2.  **PHASE_1 (Mimari & Kontrat):** Önce tipler ve API sözleşmeleri yazılır. Tek satır uygulama kodu yazılmadan kontratlar onaylanmalıdır.
-3.  **PHASE_2 (Çekirdek Geliştirme):** Backend ve Frontend paralel olarak inşa edilir. `Branded Types` kullanımı zorunludur.
-4.  **PHASE_3 (Entegrasyon & Test):** `@qa` ajanı devreye girer. **%80 Test Coverage** barajı geçilmeden bir sonraki faza geçilemez.
-5.  **PHASE_4 (Optimizasyon & Dağıtım):** Güvenlik taramaları (`check:security`) ve performans testleri tamamlanır.
-
----
+1.  **PHASE_0 (Discovery):** Tech-stack (`tech-stack.md`) sealed, risk analysis performed.
+2.  **PHASE_1 (Architecture & Contract):** First, types and API contracts are written. Contracts must be approved before a single line of application code is written.
+3.  **PHASE_2 (Core Development):** Backend and Frontend are built in parallel. Branded Types usage is mandatory.
+4.  **PHASE_3 (Integration & Test):** @quality agent takes over. 80% Test Coverage threshold must be met before proceeding to the next phase.
+5.  **PHASE_4 (Optimization & Deployment):** Security scans and performance tests are completed.
 
-> [!IMPORTANT]
-> **Ajan Talimatı:** Bu klasör altındaki dökümanlar, ajanların operasyonel sınırlarını çizer. Bir ajan, burada tanımlanan bir kuralın dışına çıkamaz. Eğer bir kuralın güncellenmesi gerekiyorsa, bu ancak `@manager` onayıyla ve ADR kaydıyla yapılabilir.
+> **Agent Directive:** The documents under this folder define the operational boundaries of the agents. An agent cannot deviate from a rule defined here. If a rule needs to be updated, this can only be done with @manager approval and ADR registration.
 
-**Sürüm:** v0.8.8  
-**Durum:** Aktif Yönetişim
+**Version:** v0.9.1  
+**Status:** Active Governance

package/docs/architecture/README.md

@@ -0,0 +1,9 @@
+# Architecture Patterns — Agent Enderun
+
+This directory contains the non-negotiable technical standards and architectural patterns for the Agent Enderun framework.
+
+## Directory Structure
+- `standards/`: Technical SOPs, design systems, and compliance mandates.
+
+## Core Mandate
+All agents MUST read and adhere to these documents before initiating any implementation task.

package/docs/architecture/standards/data-fetching-patterns.md

@@ -0,0 +1,13 @@
+# Architecture Patterns & Data Fetching
+
+## 1. UI Layout & Component Structure
+- **Shared UI:** All atomic components (Button, Input, etc.) must be created in `apps/web/src/components/ui/` using **Panda CSS**.
+- **Layouts:** Use wrapper layouts (`Shell`, `Workspace`) in `apps/web/src/components/layout/`. Every page must utilize these layouts to maintain consistency.
+- **Procedural Continuity:** Never re-create an existing component. Search the `components/ui/` directory first.
+
+## 2. Data Fetching & API (CRUD) Patterns
+- **Repository Pattern:** Backend logic must be separated into service/repository layers. No direct DB calls in controllers.
+- **Contract-First:** All API endpoints must use types imported from `apps/backend/src/types/`.
+- **API Layer:** Frontend must use typed fetcher functions located in `apps/web/src/api/`.
+- **Validation:** Use `zod` for request validation on the backend and response validation on the frontend.
+- **Audit Logging:** Every mutation (POST/PUT/PATCH/DELETE) MUST trigger an audit log service call with the current Trace ID.

package/docs/architecture/standards/design-system.md

@@ -0,0 +1,31 @@
+# Design System — Agent Enderun (Enterprise)
+
+## 1. Design Philosophy
+The Agent Enderun Design System focuses on **"Enterprise Clarity"**. Our interfaces are professional, minimalist tools designed to maximize data comprehension and operational speed. 
+
+- **Clarity:** Every pixel must serve a purpose. If it doesn't aid understanding or action, remove it.
+- **Consistency:** Uniform visual language across all applications.
+- **Responsiveness:** Fluid adaptation to any screen size, from mobile to ultra-wide monitors.
+
+## 2. Technical Requirements
+- **Styling:** Panda CSS is MANDATORY. Tailwind, CSS-in-JS, and raw CSS modules are FORBIDDEN.
+- **Zero UI Library:** No external components (MUI, AntD, Shadcn). All UI components must be built from scratch in `apps/web/src/components/ui/`.
+- **Tokenization:** All values (colors, spacing, typography) MUST use `panda.config.ts` tokens. NO hardcoded pixels.
+- **Responsiveness:** Mobile-First design is MANDATORY.
+
+## 3. Responsive Mandate (Mobile-First)
+- **Design Strategy:** Design for 320px width first.
+- **Breakpoints:**
+  - `sm`: 640px
+  - `md`: 768px
+  - `lg`: 1024px
+  - `xl`: 1280px
+  - `2xl`: 1536px
+- **Layouts:** Use Flexbox and Grid. Fixed widths are FORBIDDEN. Use `clamp()` for fluid typography and spacing where applicable.
+- **Reflow:** Content MUST gracefully wrap, stack, or collapse based on screen width without horizontal scrollbars.
+
+## 4. UI/UX Interaction Standards
+- **Interactions:** Hover, Active, and Disabled states are MANDATORY for all interactive elements.
+- **Feedback:** Async operations MUST show Loading states and Toast notifications on completion/error.
+- **Blocking Dialogues:** Native `alert()` and `confirm()` functions are **FORBIDDEN**. Use project-integrated `Modal` components for blocking user interactions and `Toaster` for non-blocking feedback.
+- **Focus:** All interactive elements must have a visible `focus` state for accessibility.

package/docs/architecture/standards/logging.md

@@ -0,0 +1,7 @@
+# Logging & Audit Standard
+
+- **No Console.log:** Production code MUST NOT use `console.log`, `console.warn`, or `console.error`. These are FORBIDDEN in the codebase.
+- **Structured Logging:** All logging MUST go through the centralized `Logger` service (`apps/backend/src/services/logger.ts`). Logs must be produced in JSON format.
+- **Traceability:** Every log entry MUST include the active `traceId` context to ensure cross-agent and cross-service traceability.
+- **Audit Logging:** Every state-mutating operation (POST, PUT, PATCH, DELETE) MUST trigger an `AuditService.log()` call, linking the action to the responsible agent, Trace ID, and entity ID.
+- **Log Persistence:** Logs must be persisted in an structured manner suitable for downstream ingestion by log management systems.

package/docs/architecture/standards/tech-stack.md

@@ -0,0 +1,9 @@
+# Tech Stack — Agent Enderun (Enterprise)
+
+- **Execution Profile:** Full (Enterprise)
+- **Frontend:** React (Vite), Panda CSS (Zero UI Library)
+- **Backend:** Fastify API, Kysely (Query Builder)
+- **Database:** PostgreSQL
+- **Testing:** Vitest (Integration + Unit)
+- **Auth:** Contract-first (Type definitions)
+- **Versioning:** API-path versioning (/api/v1/...)