agent-enderun 0.8.8 → 0.9.1

package/README.md

@@ -1,467 +1,245 @@
-# 🏛️ Agent Enderun — Supreme Enterprise AI Governance & Orchestration Framework
+# 🏛️ Agent Enderun — Enterprise AI Governance & Autonomous Orchestration Framework
 
-**Agent Enderun** is a production-grade, highly-disciplined AI orchestration and process governance framework designed for building secure, scalable, and audit-ready enterprise software. It enforces contract-first development, zero-mock safety, static security scanning, and strict multi-agent coordination under a single source of truth.
-
-**Current Version:** `0.8.8`  
-**Author:** Yusuf BEKAR  
-**License:** MIT  
+> **Stable Release:** v0.9.1  
+> **Author:** Yusuf BEKAR  
+> **Trace ID:** `01HGT8J5E2N0W0W0W0W0W0W0W4`  
+> **System Status:** 🟢 All Systems Operational | Build Compile: Clean | Type-Safety: 100% Verified
 
 ---
 
-[English](#english) | [Türkçe](#türkçe)
+## 🇹🇷 TÜRKÇE — Proje Tanıtımı & Dokümantasyonu
 
----
+**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**.
 
-# English
-
-## Table of Contents
-- [1. Introduction & Core Philosophy](#1-introduction--core-philosophy)
-- [2. Installation & Quickstart](#2-installation--quickstart)
-  - [Prerequisites](#prerequisites)
-  - [Step-by-Step Installation](#step-by-step-installation)
-  - [Verification & Health Check](#verification--health-check)
-- [3. Adapters & Use Cases](#3-adapters--use-cases)
-  - [Gemini Adapter (Standard & Recommended)](#gemini-adapter-standard--recommended)
-  - [Claude & Cursor Adapters](#claude--cursor-adapters)
-  - [Integrating with Claude Code / Claude Desktop](#integrating-with-claude-code--claude-desktop)
-- [4. Project Development Workflow & Best Practices](#4-project-development-workflow--best-practices)
-  - [A. Phase-Based Lifecycle](#a-phase-based-lifecycle)
-  - [B. Trace ID Protocol](#b-trace-id-protocol)
-  - [C. Contract-First & Branded Types](#c-contract-first--branded-types)
-  - [D. Zero Mock & Zero UI-Library Policy](#d-zero-mock--zero-ui-library-policy)
-  - [E. Security & Compliance Scanning](#e-security--compliance-scanning)
-  - [F. Hermes Messaging & Task Queues](#f-hermes-messaging--task-queues)
-- [5. CLI Reference Manual](#5-cli-reference-manual)
-- [6. Project Layout Directory Structure](#6-project-layout-directory-structure)
+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.
 
 ---
 
-## 1. Introduction & Core Philosophy
-
-AI assistance in software development often introduces technical debt, code drift, and unstructured modifications. **Agent Enderun** solves this by establishing a **Structured Governance Framework**. Rather than acting as a loose code generator, AI assistants within this framework are treated as disciplined engineers under a unified command structure led by the `@manager` (Team-Lead) agent.
-
-### The Five Pillars of Enderun
-1. **Absolute Traceability:** Every action, commit, and state change is stamped with a unique ULID-based **Trace ID**.
-2. **Katalyst Contracts:** Zero code is written until API contracts and **Branded Types** are defined and verified.
-3. **Pristine Sandboxing:** Complete separation between the **User's Project** and the **Framework Internals**.
-4. **Permanent Memory:** The AI's context and status live persistently inside your project, not in transient chat logs or the OS `/tmp` directory.
-5. **Zero Mock Policy:** All analytical and operational screens must interact with actual, validated schemas and live endpoints.
+### 🚀 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. Installation & Quickstart
+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.
 
-### Prerequisites
-- **Node.js** v20.0.0 or higher (LTS recommended).
-- **npm** v9+ or **pnpm** v8+ or **yarn** v3+.
-- **Git** initialized in the project directory.
+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.
 
-### Step-by-Step Installation
+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ı.
 
-#### Step 1: Initialize Git in your directory
-```bash
-mkdir my-enterprise-app
-cd my-enterprise-app
-git init
-```
+---
 
-#### Step 2: Run the Framework Initializer
-To scaffold the entire governance structure, run the command below. By default, it will detect your package manager and environment.
-```bash
-npx agent-enderun init gemini
-```
-*Note: If you do not specify an adapter, it will default to `gemini` and build the runtime within the `.enderun/` directory.*
+### 💎 Stratejik Platform Sinerjisi (Dört Büyük Güç)
 
-#### Step 3: Install Workspace Dependencies & Compile the MCP Server
-```bash
-npm install
-npm run enderun:build
-```
+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.
 
 ---
 
-### Verification & Health Check
+### 🪖 Konsolide Edilmiş 10 Ajanlık Ordu Yapısı
 
-Always run the built-in health diagnostic after installation or after making major project transitions:
-```bash
-npx agent-enderun check
-```
+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:
 
-#### What does the Health Check validate?
-- **Constitution Integrity:** Verifies the existence and checksum of `ENDERUN.md`.
-- **Memory Connectivity:** Checks if `PROJECT_MEMORY.md` is active and writeable.
-- **Contract Parity:** Ensures `apps/backend/contract.version.json` exists.
-- **MCP compilation:** Confirms `framework-mcp/dist/index.js` is fully compiled and ready.
-- **Documentation Portals:** Ensures technical stack details are filled inside `docs/tech-stack.md`.
+| 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ı. |
 
 ---
 
-## 3. Adapters & Use Cases
+### 🛡️ Enderun Disiplininin 5 Temel Direği
 
-Agent Enderun is designed to support the specific AI adapter that matches your IDE or CLI environment.
+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.
 
-```text
-               ┌───────────────────────┐
-               │    agent-enderun      │
-               └───────────┬───────────┘
-                           │
-         ┌─────────────────┼─────────────────┐
-         ▼                 ▼                 ▼
-  .enderun/          .claude/           .cursor/
-(Gemini Adapter)   (Claude Code)     (Cursor IDE)
-```
+---
 
-### Gemini Adapter (Standard & Recommended)
-- **Folder:** `.enderun/`
-- **Target Use:** Gemini CLI, Google Vertex AI, and direct Gemini API environments.
-- **Shim File:** `gemini.md` (placed at the project root as the initial context instructions).
-- **Benefit:** Full Model Context Protocol (MCP) server hooks natively tuned for Gemini's large-context window.
-
-### Claude & Cursor Adapters
-- **Claude Adapter (`init claude`):** Creates the `.claude/` directory and shims. Configures automated MCP access for **Claude Code CLI** and **Claude Desktop**.
-- **Cursor Adapter (`init cursor`):** Creates `.cursor/` directory containing `.cursorrules` to immediately guide the Cursor IDE agent with Enderun's strict coding boundaries.
-
-### Integrating with Claude Code / Claude Desktop
-
-Agent Enderun provides a fully-functional **Model Context Protocol (MCP)** server. To connect it to your Claude environment, append the following block to your `claude_desktop_config.json` or global Claude CLI configuration:
-
-```json
-{
-  "mcpServers": {
-    "agent-enderun-mcp": {
-      "command": "node",
-      "args": ["/absolute/path/to/your/project/framework-mcp/dist/index.js"]
-    }
-  }
-}
-```
+### 🛠️ CLI Komut Referansı
 
-Once connected, your AI assistant will gain access to tools such as:
-- `search_codebase` (Surgical context parsing)
-- `read_project_memory` & `update_project_memory` (State machine updates)
-- `verify_api_contract` (TypeScript type validation)
-- `send_agent_message` (Hermes protocol queues)
+| 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. |
 
 ---
 
-## 4. Project Development Workflow & Best Practices
-
-To successfully develop a project within the Agent Enderun framework, follow this rigid workflow.
-
-### A. Phase-Based Lifecycle
-Development progresses sequentially through five states. Do not skip phases:
-1. **`PHASE_0` - Discovery & Setup:** Fill out `docs/tech-stack.md` and select the execution profile (Lightweight MVP vs. Full Enterprise).
-2. **`PHASE_1` - Architecture & Contracts:** Create your models and API definitions first. Establish contract hashes.
-3. **`PHASE_2` - Core Development:** Develop features inside `apps/backend/` and `apps/web/` in parallel.
-4. **`PHASE_3` - Integration & Testing:** Run end-to-end integration and reach the mandatory **80% test coverage gate** via `@qa`.
-5. **`PHASE_4` - Optimization & Deployment:** Perform a final performance audit and deploy.
-
-### B. Trace ID Protocol
-Never write code or commit files without an active task ULID. 
-1. Create a new task tracking chain:
-   ```bash
-   npx agent-enderun trace:new "Implement JWT Authentication" backend P1
-   ```
-2. This generates a ULID (e.g., `01H7G8K5TJ5S6MF9Z7H8N4C2P`) and appends it to the `ACTIVE TASKS` table in `PROJECT_MEMORY.md`.
-3. Use the Trace ID prefix in your git commit messages:
-   ```bash
-   git commit -m "[01H7G8K5TJ5S6MF9Z7H8N4C2P] feat(auth): add JWT fastify plugins"
-   ```
-
-### C. Contract-First & Branded Types
-Under Agent Enderun, all ID types must use strict **Branded Types** to avoid type confusion:
-```typescript
-// apps/backend/src/types/brands.ts
-export type Brand<T, K extends string> = T & { __brand: K };
-
-export type UserID = Brand<string, "UserID">;
-export type ProjectID = Brand<string, "ProjectID">;
-```
-Ensure `@backend` compiles all types into a shared folder BEFORE `@frontend` starts any page implementation. Update the contract version in `apps/backend/contract.version.json`.
-
-### D. Zero Mock & Zero UI-Library Policy
-- **No Mocking:** All developed user interfaces must pull data from actual verified backend endpoints or Kysely repositories (with exceptions only for 3rd-party platforms like Stripe or Twilio).
-- **Panda CSS & Custom UI:** External pre-styled components (e.g. TailwindCSS, MUI, Shadcn/UI) are forbidden in core workspaces unless explicitly authorized by `@manager`. Rely entirely on the type-safe token system of **Panda CSS** to construct custom, responsive interfaces.
-
-### E. Security & Compliance Scanning
-Run static scanning checks locally on your codebase:
-* **Security Audit:** Searches for unsafe database strings, hardcoded keys, innerHTML assignments, and `any` types.
-  ```bash
-  npx agent-enderun check:security
-  ```
-* **Constitution Compliance:** Inspects files for forbidden libraries, unbranded ID types, and missing error-handling parameters.
-  ```bash
-  npx agent-enderun check:compliance
-  ```
-
-### F. Hermes Messaging & Task Queues
-If working with multiple sub-agents in parallel, agents communicate via `messages/` under the Hermes Protocol. The files are locked via `.lock` tokens to ensure thread safety, and execution routes asynchronously through `.enderun/queue/`.
+### 📦 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.
 
-## 5. CLI Reference Manual
+Yerel projenizi test etmek veya npm link üzerinden kurmak için:
+```bash
+# Bağımlılıkları kurun ve MCP sunucusunu derleyin
+npm install
+npm run enderun:build
 
-| Command | Arguments | Description |
-| :--- | :--- | :--- |
-| `init` | `[adapter]` | Initializes the framework. Supported adapters: `gemini` (creates `.enderun/`), `claude` (`.claude/`), `cursor` (`.cursor/`). |
-| `check` | *None* | Performs full framework diagnostic and codebase health check. |
-| `status` | *None* | Displays current active Phase, Trace IDs, agent states, and blockers. |
-| `trace:new` | `<description> [agent] [priority]` | Generates a new ULID Trace ID and appends it to active tasks. |
-| `create-app` | `<idea>` | Generates a full-stack monorepo application template from natural language. |
-| `verify-contract` | *None* | Computes API hashes to verify type parity between backend and frontend. |
-| `check:security` | `[path]` | Runs static scan for SQL injections, secrets, and illegal variables. |
-| `check:compliance` | `[path]` | Audits compliance with Branded Types and forbidden UI libraries. |
-| `explorer:graph` | `[path]` | Generates a visual Mermaid TD dependency diagram of the local files. |
-| `explorer:audit` | `[path]` | Executes static analysis mapping files to corresponding agent owners. |
-| `git:commit` | `<trace-id>` | Inspects staged files and suggests a perfect semantic git commit message. |
-| `mcp` | *None* | Starts the Model Context Protocol stdio server. |
-| `version` | *None* | Prints the current framework release version. |
+# Paketi yerel NPM havuzunuza linkleyin
+npm link
 
----
+# 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
 
-## 6. Project Layout Directory Structure
-
-A fully-governed monorepo structured under Agent Enderun looks as follows:
-
-```text
-├── .enderun/               <-- Framework Runtime & Memory (v0.8.8)
-│   ├── agents/             <-- Specialist agent Blueprints & SOPs
-│   ├── knowledge/          <-- Rigid architecture patterns & rules
-│   ├── memory-graph/       <-- Global facts & private agent states
-│   ├── logs/               <-- Structured JSON audit trail
-│   ├── queue/              <-- Asynchronous task queues
-│   ├── PROJECT_MEMORY.md   <-- Unified state brain (SSOT)
-│   └── STATUS.md           <-- Agent army dashboard
-├── apps/
-│   ├── backend/            <-- Fastify & Kysely backend workspace
-│   │   └── contract.json   <-- API contract registry & hash metadata
-│   └── web/                <-- React & Panda CSS client workspace
-├── docs/                   <-- User's technical stack & requirements
-├── framework-mcp/          <-- MCP Server source code & tools
-├── bin/                    <-- Executable CLI entrypoint binaries
-├── ENDERUN.md              <-- System Constitution (Supreme Law)
-└── package.json            <-- Monorepo workspaces & shared actions
+# Adaptörü başlatın
+npx agent-enderun init gemini
 ```
 
 ---
 ---
 
-# Türkçe
-
-## İçindekiler
-- [1. Giriş ve Temel Felsefe](#1-giriş-ve-temel-felsefe)
-- [2. Kurulum ve Hızlı Başlangıç](#2-kurulum-ve-hızlı-başlangıç)
-  - [Ön Gereksinimler](#ön-gereksinimler)
-  - [Adım Adım Kurulum](#adım-adım-kurulum)
-  - [Sağlık ve Doğrulama Taraması](#sağlık-ve-doğrulama-taraması)
-- [3. Adaptörler ve Kullanım Senaryoları](#3-adaptörler-ve-kullanım-senaryoları)
-  - [Gemini Adaptörü (Standart & Önerilen)](#gemini-adaptörü-standart--önerilen)
-  - [Claude & Cursor Adaptörleri](#claude--cursor-adaptörleri)
-  - [Claude Code / Claude Desktop Entegrasyonu](#claude-code--claude-desktop-entegrasyonu)
-- [4. Proje Geliştirme Akışları ve En İyi Pratikler](#4-proje-geliştirme-akışları-ve-en-iyi-pratikler)
-  - [A. Aşama Tabanlı Yaşam Döngüsü](#a-aşama-tabanlı-yaşam-döngüsü)
-  - [B. Trace ID Protokolü](#b-trace-id-protokolü)
-  - [C. Kontrat Öncelikli Geliştirme & Branded Types](#c-kontrat-öncelikli-geliştirme--branded-types)
-  - [D. Sıfır Sahte Veri (Zero-Mock) & Sıfır UI Kütüphanesi Kanunu](#d-sıfır-sahte-veri-zero-mock--sıfır-ui-kütüphanesi-kanunu)
-  - [E. Güvenlik ve Uyumluluk Taramaları](#e-güvenlik-ve-uyumluluk-taramaları)
-  - [F. Hermes Mesajlaşması & Görev Kuyrukları](#f-hermes-mesajlaşması--görev-kuyrukları)
-- [5. CLI Referans Klavuzu](#5-cli-referans-klavuzu)
-- [6. Proje Klasör Dizilim Mimarisi](#6-proje-klasör-dizilim-mimarisi)
+## 🇺🇸 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.
 
-## 1. Giriş ve Temel Felsefe
+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.
 
-Yazılım geliştirme süreçlerindeki yapay zeka yardımı genellikle plansız değişikliklere, teknik borç birikimine ve kontrolsüz kod sapmalarına neden olur. **Agent Enderun**, yapay zekayı basit bir kod üreteci olarak konumlandırmak yerine, onu `@manager` (Takım Lideri) ajanı komutasında çalışan, kurallara bağlı disiplinli bir mühendislik ordusu haline getiren **Kurumsal Yapay Zeka Yönetişim Framework'üdür**.
+---
 
-### Enderun’un Beş Ana Sütunu
-1.  **Mutlak İzlenebilirlik:** Yapılan her işlem, commit ve durum değişikliği ULID tabanlı bir **Trace ID** ile damgalanır.
-2.  **Önce Sözleşme (Contract-First):** API rotaları ve veri tipleri (**Branded Types**) tanımlanıp onaylanmadan tek satır kod yazılamaz.
-3.  **Kalıcı Yerel Hafıza:** Yapay zekanın tüm bağlamı (context) ve projenin mevcut durumu, işletim sisteminin `/tmp` dizininde değil, doğrudan projenizin içinde saklanır.
-4.  **Sınırların Korunması (Pristine Sandboxing):** Framework çekirdeği ile sizin uygulama kodunuz arasında aşılmaz sınırlar çizilir.
-5.  **Gerçekçi Veri (Zero Mock Policy):** Tüm analiz ve operasyon ekranları sahte verilerle (mock) değil, onaylanmış canlı veritabanı şemalarıyla konuşur.
+### 🚀 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. Kurulum ve Hızlı Başlangıç
+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.
 
-### Ön Gereksinimler
-- **Node.js** v20.0.0 veya üzeri (LTS sürümü önerilir).
-- **npm** v9+ veya **pnpm** v8+ veya **yarn** v3+.
-- **Git** (proje dizininde başlatılmış olmalıdır).
+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.
 
-### Adım Adım Kurulum
+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.
 
-#### Adım 1: Proje dizininizi oluşturun ve Git'i başlatın
-```bash
-mkdir benim-kurumsal-uygulamam
-cd benim-kurumsal-uygulamam
-git init
-```
+---
 
-#### Adım 2: Framework'ü Başlatın
-Aşağıdaki komut, projenizi analiz ederek uygun adaptörü kurar ve yönetişim yapısını hazırlar:
-```bash
-npx agent-enderun init gemini
-```
-*Not: Bir adaptör belirtilmezse standart olarak `gemini` kurulur ve framework çalışma ortamı `.enderun/` dizininde oluşturulur.*
+### 💎 Strategic Platform Synergy (The Four Powers)
 
-#### Adım 3: Bağımlılıkları Yükleyin ve MCP Sunucusunu Derleyin
-```bash
-npm install
-npm run enderun:build
-```
+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.
 
 ---
 
-### Sağlık ve Doğrulama Taraması
+### 🪖 The Consolidated 10-Agent Army
 
-Kurulum sonrasında veya büyük aşama geçişlerinde projenizin sağlık durumunu denetlemek için yerleşik tarayıcıyı çalıştırın:
-```bash
-npx agent-enderun check
-```
+All workspace operations are divided among 10 specialized expert agents connected via the Hermes protocol:
 
-#### Bu tarama neleri doğrular?
-- **Anayasa Güvenliği:** `ENDERUN.md` dosyasının mevcudiyetini ve doğruluğunu kontrol eder.
-- **Bellek Erişimi:** `.enderun/PROJECT_MEMORY.md` dosyasının etkin ve yazılabilir olduğunu denetler.
-- **Sözleşme Bütünlüğü:** `apps/backend/contract.version.json` dosyasını denetler.
-- **MCP Derlemesi:** `framework-mcp/dist/index.js` dosyasının derlendiğini doğrular.
-- **Teknoloji Yığını:** Projenin mimari stack tanımının `docs/tech-stack.md` içine yazılıp yazılmadığını kontrol eder.
+| 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. |
 
 ---
 
-## 3. Adaptörler ve Kullanım Senaryoları
+### 🛡️ Five Pillars of Enderun Discipline
 
-Agent Enderun, kullandığınız editör veya yapay zeka aracına uygun adaptörü dinamik olarak etkinleştirir.
+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`.
 
-### Gemini Adaptörü (Standart & Önerilen)
-- **Dizin:** `.enderun/`
-- **Hedef:** Gemini CLI, Google Vertex AI ve doğrudan Gemini API ortamları.
-- **Tetikleyici:** Proje kökündeki `gemini.md` dosyası (yapay zeka ilk bu dosyayı okuyarak anayasayı yükler).
-- **Avantaj:** Gemini'ın devasa bağlam (context window) kapasitesine göre optimize edilmiş araç çağrıları.
-
-### Claude & Cursor Adaptörleri
-- **Claude Adaptörü (`init claude`):** `.claude/` çalışma dizinini hazırlar. **Claude Code CLI** ve **Claude Desktop** için otomatik MCP bağlantılarını yapılandırır.
-- **Cursor Adaptörü (`init cursor`):** `.cursor/` klasörünü ve `.cursorrules` dosyasını oluşturarak Cursor IDE'nin kendi kod üretim sınırlarını Enderun kurallarına kilitler.
+---
 
-### Claude Code / Claude Desktop Entegrasyonu
+### 🛠️ CLI Command Map
 
-Agent Enderun, tam teşekküllü bir **Model Context Protocol (MCP)** sunucusu içerir. Bunu Claude ortamınıza bağlamak için `claude_desktop_config.json` dosyanıza veya global Claude CLI ayarlarınıza şu bloğu eklemeniz yeterlidir:
+| 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. |
 
-```json
-{
-  "mcpServers": {
-    "agent-enderun-mcp": {
-      "command": "node",
-      "args": ["/absolute/path/to/your/project/framework-mcp/dist/index.js"]
-    }
-  }
-}
-```
+---
 
-Bağlantı kurulduğunda, yapay zekanız şu araçları (tools) kullanma yeteneği kazanır:
-- `search_codebase` (Cerrahi kod arama)
-- `read_project_memory` & `update_project_memory` (Hafıza güncelleme)
-- `verify_api_contract` (Tip uyumluluk kontrolü)
-- `send_agent_message` (Ajanlar arası Hermes mesajlaşması)
+### 📦 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.
 
-## 4. Proje Geliştirme Akışları ve En İyi Pratikler
-
-Agent Enderun framework'ü üzerinde başarılı bir geliştirme süreci yürütmek için aşağıdaki adımları takip etmeniz zorunludur:
-
-### A. Aşama Tabanlı Yaşam Döngüsü
-Geliştirme süreci asla atlanamayacak 5 ardışık fazdan oluşur:
-1.  **`PHASE_0` - Keşif ve Yapılandırma:** `docs/tech-stack.md` doldurulur ve Lightweight (MVP) veya Full (Kurumsal) yürütme profili seçilir.
-2.  **`PHASE_1` - Mimari ve Sözleşmeler:** Veri modelleri, API rotaları ve tip sözleşmeleri kilitlenir.
-3.  **`PHASE_2` - Çekirdek Geliştirme:** `apps/backend` ve `apps/web` paralel olarak kodlanır.
-4.  **`PHASE_3` - Entegrasyon ve Test:** `@qa` ajanı denetiminde **en az %80 birim/entegrasyon test kapsamı** zorunlu kapı olarak geçilir.
-5.  **`PHASE_4` - Optimizasyon ve Dağıtım:** Performans denetimleri tamamlanarak uygulama canlıya alınır.
-
-### B. Trace ID Protokolü
-Aktif bir iş ULID'si olmadan kod yazmak veya commit atmak yasaktır.
-1.  Yeni bir göreve başlarken terminalden yeni bir Trace oluşturun:
-    ```bash
-    npx agent-enderun trace:new "JWT Yetkilendirme Modülü" backend P1
-    ```
-2.  Bu komut benzersiz bir ULID üretir (örn: `01H7G8K5TJ5S6MF9Z7H8N4C2P`) ve bunu `.enderun/PROJECT_MEMORY.md` içindeki aktif görevler tablosuna yazar.
-3.  Tüm Git commit mesajlarınızda bu Trace ID'yi ön ek olarak kullanın:
-    ```bash
-    git commit -m "[01H7G8K5TJ5S6MF9Z7H8N4C2P] feat(auth): add JWT fastify plugins"
-    ```
-
-### C. Kontrat Öncelikli Geliştirme & Branded Types
-Hatalı kimlik atamalarını ve tip belirsizliklerini önlemek için projedeki tüm benzersiz kimlikler (ID) **Branded Types** formatında markalanmalıdır:
-```typescript
-// apps/backend/src/types/brands.ts
-export type Brand<T, K extends string> = T & { __brand: K };
-
-export type UserID = Brand<string, "UserID">;
-export type ProjectID = Brand<string, "ProjectID">;
-```
-`@backend` ajanı tüm bu tipleri ortak sözleşmeye yazıp `apps/backend/contract.version.json` dosyasını güncellemeden, `@frontend` ajanı kullanıcı arayüzü tasarlamaya başlayamaz.
-
-### D. Sıfır Sahte Veri (Zero-Mock) & Sıfır UI Kütüphanesi Kanunu
-*   **Sahte Veri Yasağı:** Arayüzler doğrudan doğrulanmış Fastify uç noktalarından ve Kysely veritabanı depolarından beslenmelidir (Stripe, Twilio gibi dış servis entegrasyonları hariç).
-*   **Panda CSS Kullanımı:** TailwindCSS, MUI veya Shadcn/UI gibi hazır stillendirilmiş kütüphaneler (aksine bir `@manager` izni yoksa) yasaktır. Tasarımlar tamamen tip-güvenli **Panda CSS** belirteçleri (tokens) ile el değerek oluşturulur.
-
-### E. Güvenlik ve Uyumluluk Taramaları
-Kaynak kodunuzu yerel olarak statik analizlerden geçirin:
-*   **Güvenlik Denetimi:** Güvensiz veritabanı sorgularını, açık parola tanımlarını ve `any` veri tipi ihlallerini yakalar:
-    ```bash
-    npx agent-enderun check:security
-    ```
-*   **Anayasa Uyumluluğu:** Markalanmamış kimlik kullanımlarını ve yasaklı harici UI kütüphane bağımlılıklarını denetler:
-    ```bash
-    npx agent-enderun check:compliance
-    ```
-
-### F. Hermes Mesajlaşması & Görev Kuyrukları
-Paralel çalışan alt ajanlar (sub-agents), birbirleriyle Hermes Protokolü (`messages/` klasörü) üzerinden asenkron olarak mesajlaşır. İşlemler `.lock` kilit dosyalarıyla güvenceye alınır ve asenkron kuyruklar `.enderun/queue/` altında güvenle sıraya konur.
+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
 
-## 5. CLI Referans Klavuzu
+# Create a test folder and link package
+mkdir test-project && cd test-project
+npm init -y
+npm link agent-enderun
 
-| Komut | Parametreler | Açıklama |
-| :--- | :--- | :--- |
-| `init` | `[adapter]` | Framework'ü başlatır. Desteklenen adaptörler: `gemini` (`.enderun/`), `claude` (`.claude/`), `cursor` (`.cursor/`). |
-| `check` | *Yok* | Projenin genel sağlık ve anayasal uyumluluk durumunu denetler. |
-| `status` | *Yok* | Aktif aşamayı, Trace ID'lerini, aktif ajan durumlarını ve engelleri (blockers) gösterir. |
-| `trace:new` | `<açıklama> [ajan] [öncelik]` | Yeni bir ULID Trace ID'si oluşturarak proje hafızasındaki aktif görevlere ekler. |
-| `create-app` | `<fikir>` | Doğal dil ile girilen gereksinimlerden sıfırdan kurumsal monorepo uygulaması üretir. |
-| `verify-contract` | *Yok* | Sözleşme karma değerlerini (hash) hesaplayarak backend-frontend tip uyumluluğunu doğrular. |
-| `check:security` | `[yol]` | Ham SQL, açık anahtarlar, innerHTML ve `any` tipi için güvenlik taraması yapar. |
-| `check:compliance` | `[yol]` | Branded Types uyumluluğunu ve yasaklı arayüz kütüphanelerini denetler. |
-| `explorer:graph` | `[yol]` | Dosyalar arası bağımlılıkları analiz ederek görsel Mermaid TD şeması üretir. |
-| `explorer:audit` | `[yol]` | Kod dosyalarının hangi uzman ajanın mülkiyetinde olduğunu listeleyen statik analiz yapar. |
-| `git:commit` | `<trace-id>` | Commit aşamasındaki staged dosyaları inceleyerek Trace ID uyumlu semantik commit mesajı önerir. |
-| `mcp` | *Yok* | Model Context Protocol stdio sunucusunu başlatır. |
-| `version` | *Yok* | Framework'ün mevcut sürüm numarasını yazdırır. |
+# Boot the adapter scaffolding
+npx agent-enderun init gemini
+```
 
 ---
 
-## 6. Proje Klasör Dizilim Mimarisi
-
-Agent Enderun altında yönetilen örnek bir kurumsal monorepo yapısı:
-
-```text
-├── .enderun/               <-- Çalışma Zamanı & Hafıza Klasörü (v0.8.8)
-│   ├── agents/             <-- Uzman Ajan Direktifleri ve SOP Belgeleri
-│   ├── knowledge/          <-- Mimari Desenler ve Kodlama Kuralları
-│   ├── memory-graph/       <-- Paylaşılan Gerçekler ve Ajan Durumları
-│   ├── logs/               <-- Denetlenebilir Yapılandırılmış JSON Logları
-│   ├── queue/              <-- Asenkron Görev Yönetim Kuyruğu
-│   ├── PROJECT_MEMORY.md   <-- Projenin Tek Güvenilir Ortak Beyni (SSOT)
-│   └── STATUS.md           <-- Ajan Ordusu Durum Gösterge Paneli
-├── apps/
-│   ├── backend/            <-- Fastify ve Kysely tabanlı Backend Çalışma Alanı
-│   │   └── contract.json   <-- API Sözleşmeleri ve Doğrulama Özetleri
-│   └── web/                <-- React ve Panda CSS tabanlı Client Çalışma Alanı
-├── docs/                   <-- Kullanıcının Mimari İstekleri ve Stack Bilgileri
-├── framework-mcp/          <-- MCP Sunucu Kaynak Kodları ve Araçlar
-├── bin/                    <-- Çalıştırılabilir CLI Giriş Noktası Binaries
-├── ENDERUN.md              <-- Sistem Anayasası (Supreme Law)
-└── package.json            <-- Monorepo Çalışma Alanı Tanımları & Betikler
-```
+Developed with absolute discipline | Developer **Yusuf BEKAR** | Framework Version **v0.9.1**