agent-enderun 0.8.6 → 0.8.8

package/README.md

@@ -1,332 +1,467 @@
-# 🏛️ Agent Enderun (v0.8.6) — The Supreme AI Governance & Orchestration Framework
+# 🏛️ Agent Enderun — Supreme Enterprise AI Governance & Orchestration Framework
 
-**The Supreme AI Governance & Orchestration Framework for Enterprise Development**
+**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.
 
-**Author:** Yusuf BEKAR
-**Version:** 0.8.6
-**License:** MIT
-
-[English](#english) | [Türkçe](#türkçe)
+**Current Version:** `0.8.8`  
+**Author:** Yusuf BEKAR  
+**License:** MIT  
 
 ---
 
-# English
-
-## Executive Summary
-
-**Agent Enderun** is a production-grade constitutional governance and multi-agent orchestration framework designed for engineering teams that need to use AI assistants at scale while maintaining control, traceability, auditability, and professional discipline.
-
-Most AI coding tools optimize for speed and generation volume. Agent Enderun optimizes for **risk-aware, auditable, and continuously improving software development processes**. It converts chaotic AI output into structured, enterprise-ready work through mandatory rules, specialized agents, persistent memory, and a living risk management system.
-
-> [!NOTE]
-> **v0.7.0 Strategic Consolidation:**
-> The active runtime folder in user projects is `.enderun/`. The framework ships its templates from `.enderun/`. All specialist agent configurations live as strongly-typed `agent.json` under `.enderun/agents/{agent_name}.md`. Duplicate or staging structures have been retired.
+[English](#english) | [Türkçe](#türkçe)
 
 ---
 
-## 🎯 Core Philosophy & Key Concepts
-
-Agent Enderun is built on a set of non-negotiable principles enforced by its core components.
-
-### 1. The Constitution (`ENDERUN.md`)
-This is the supreme law of the framework, dictating mandatory rules and protocols for all agents. Key principles include:
-- **Single Point of Authority:** In enterprise projects, `@manager` is the only authorized entry point. No specialist agent may act without a formal briefing.
-- **Contract-First Development:** The `@backend` agent MUST define and document API contracts and types before the `@frontend` agent begins implementation.
-- **Zero UI Library & Zero Mock Policy:** The `@frontend` agent MUST build components from scratch using the project's design system (Panda CSS) and MUST NOT use mock data. This ensures originality and quality.
-- **Procedural Continuity:** All agents MUST adhere to the existing architectural and stylistic patterns of the project.
-
-### 2. Project Memory (`PROJECT_MEMORY.md`)
-This file, located in `.enderun/`, is the **Single Source of Truth (SSOT)** for the project's state. It is a human-readable Markdown file that all agents read at the start of a session and update at the end. Its key sections are:
-- **`CURRENT STATUS`:** Tracks the active phase, Trace ID, and any blockers.
-- **`CRITICAL DECISIONS`:** A log of important architectural choices to ensure consistency.
-- **`ACTIVE TASKS`:** A table of all ongoing tasks, their status, priority, and assigned agent.
-- **`HISTORY`:** A persistent log of all actions taken by agents.
+# English
 
-### 3. Traceability (Trace ID)
-Every task or logical unit of work is assigned a unique **Trace ID** (a 26-character ULID). This ID is used in commit messages, logs, and task tables, providing an unbroken chain of traceability from the initial request to the final code.
+## 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)
 
 ---
 
-## 🤖 The Agent Army & Core Folders
-
-Each agent in the Enderun Army is governed by a strongly-typed `agent.json` definition that defines their precise rules, permitted directories, and capability ratings.
+## 1. Introduction & Core Philosophy
 
-### Workspace Agent Path:
-👉 `[project-root]/.enderun/agents/{agent_name}.md`
+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.
 
-### Agent Army Overview (v1.0 - 12 Specialists):
-
-| Tier | Agent | Capability | Role & Domain | Primary Specialization |
-| :--- | :--- | :--- | :--- | :--- |
-| **Core** | **@orchestrator** | **9.8/10** | Task Pipeline Engine | Parallel execution, stateful queue controls, DAG execution. |
-| **Core** | **@manager** | **9.5/10** | Orchestration & Governance | Intent analysis, high-risk dynamic approval signing, escalation. |
-| **Analysis** | **@analyst** | **9.6/10** | Verification & QA Gate | Vitest/Cypress verification, API contract drift checking, Zero-UI enforcer. |
-| **Analysis** | **@explorer** | **9.4/10** | Research & Discovery | Pattern mapping, dependency graph discovery, onboarding analysis. |
-| **Engineering** | **@backend** | **9.2/10** | Domain Logic & Databases | Fastify, Kysely queries, branded types, DomainError hierarchy. |
-| **Engineering** | **@frontend** | **9.0/10** | Fluid Responsive UI | React 19, Panda CSS styling tokens, Zero-UI, WCAG 2.2 accessibility. |
-| **Engineering** | **@native** | **8.9/10** | Native Capabilities | Tauri/Electron shell guards, Rust bridges, secure IPC contracts. |
-| **Engineering** | **@mobile** | **8.8/10** | Cross-Platform Mobile | React Native/Expo fluid viewports, offline cache sync, safe areas. |
-| **Operations** | **@security** | **9.3/10** | Security & Compliance | OWASP threat detection, AST scans for secrets, CSP rules auditor. |
-| **Operations** | **@qa** | **9.1/10** | Quality Gate Enforcer | Unit/integration testing gates, coverage metrics check. |
-| **Operations** | **@git** | **9.1/10** | Version Control | Semantic commits formatting, atomic commit segregation, phase snapshots. |
-| **Operations** | **@devops** | **9.0/10** | Infrastructure | Deployment pipelines, container setups, environment variable validation. |
+### 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.
 
 ---
 
-### 📂 Core Directories Analysis & Operational Purposes
-
-The Agent Enderun framework organizes agent actions and runtime intelligence through highly structured directories remapped to `.enderun/` (or `.claude/` / `.cursor/`) inside user workspaces:
+## 2. Installation & Quickstart
 
-* **`skills/` (Dynamic Executables):** Serves as a folder for model-specific executable scripts and custom tools. Developers can inject project-specific helpers here, allowing agents to load and execute them dynamically on-demand during active briefs.
-* **`benchmarks/` (LLM Evaluation):** Dedicated folder for metrics, token consumption, and response accuracy logs comparing different LLM engines (e.g. Gemini 1.5 Pro vs Claude 3.5 Sonnet vs Codex). Helps evaluate the coding intelligence of the active army.
-* **`knowledge/` (Intelligence Database):** central knowledge hub of the framework containing 43 robust guidelines enforcing strict laws on Panda CSS coding, Fastify RCSR, Kysely schema creation, dynamic signature validations, and domain error hierarchies.
-* **`logs/` (Auditable Trails):** Active audit log repository. Every action performed by any agent is traceably logged in JSON format (`logs/{agent_name}.json`) with a specific timestamp and a unique 26-character Trace ID (ULID), satisfying enterprise compliance audits.
-* **`monitoring/` (Operational Telemetry):** Telemetry directory integrated with monitoring tools (`get_army_health_dashboard`, `calculate_agent_performance_score`) to analyze agent bottleneck states and QA rejection cycles.
-* **`queue/` (Asynchronous Task Engine):** File-based stateful task queue split into `pending/`, `processing/`, `completed/`, `failed/`, and `pipelines/` subdirectories. Feeds Orchestration MCP tools to schedule complex multi-agent assignments in parallel with complete rollback recovery.
+### Prerequisites
+- **Node.js** v20.0.0 or higher (LTS recommended).
+- **npm** v9+ or **pnpm** v8+ or **yarn** v3+.
+- **Git** initialized in the project directory.
 
----
-
-## ⚡ Quick Start & Workflow
-
-### 1. Installation
+### Step-by-Step Installation
 
-Install the package and initialize the framework inside your project folder:
+#### 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
-# 1. Initialize the framework for Gemini CLI
 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.*
 
-# 2. Install dependencies (as prompted)
+#### Step 3: Install Workspace Dependencies & Compile the MCP Server
+```bash
 npm install
-
-# 3. Build the framework's internal tools (as prompted)
 npm run enderun:build
-
-# 4. Verify installation and project health
-npx agent-enderun check
 ```
 
-### 2. Example Workflow: Adding a New Feature
-
-Here’s how to use Agent Enderun to develop a new feature:
-
-**Step 1: Define the Task**
-Create a new file in your project's `docs/` folder (e.g., `docs/new-feature-request.md`) describing the feature you want.
+---
 
-**Step 2: Create a New Trace**
-Use the CLI to create a new task in `PROJECT_MEMORY.md`. This generates a unique Trace ID.
+### Verification & Health Check
 
+Always run the built-in health diagnostic after installation or after making major project transitions:
 ```bash
-npx agent-enderun trace:new "Implement user profile page based on docs/new-feature-request.md" @manager P1
+npx agent-enderun check
 ```
 
-**Step 3: Agent Orchestration (Automatic)**
-The `@manager` agent (the default AI persona) will:
-1.  Read `PROJECT_MEMORY.md` and see the new task.
-2.  Analyze the request from `docs/new-feature-request.md`.
-3.  Create a plan and issue formal "briefings" to specialist agents like `@explorer`, `@backend`, and `@frontend`.
-
-**Step 4: Development & Verification (Automatic)**
-- The specialist agents execute their tasks according to the constitutional rules (e.g., `@backend` creates the API and types, then `@frontend` builds the UI).
-- `@analyst` automatically verifies the work against project standards.
-- `@git` creates atomic commits tagged with the Trace ID.
-
-**Step 5: Monitor Progress**
-You can check the progress at any time with the `status` command:
-
-```bash
-npx agent-enderun status
-```
-This will show the active phase, blockers, and the status of all active tasks.
+#### 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`.
 
 ---
 
-## 🛠️ CLI Commands
-
-Agent Enderun comes with a powerful set of CLI tools for managing the project.
+## 3. Adapters & Use Cases
 
-| Command | Description |
-| :--- | :--- |
-| `npx agent-enderun init [adapter]` | Initializes the framework in the current project. `gemini` is the default and recommended adapter. |
-| `npx agent-enderun check` | Runs a health check on the project to ensure all required files and configurations are present. |
-| `npx agent-enderun status` | Displays the current project status, active tasks, and blockers from `PROJECT_MEMORY.md`. |
-| `npx agent-enderun trace:new "<desc>" [agent] [priority]` | Creates a new task with a unique Trace ID and adds it to the `PROJECT_MEMORY.md`. |
-| `npx agent-enderun create-app "<desc>"` | (Aliases: `new`, `start`) Scaffolds a new full-stack application (backend + web) from a natural language description. |
-| `npx agent-enderun verify-contract` | Verifies the integrity of the shared backend types by comparing the current code against the stored hash in `contract.version.json`. |
-
----
-
-# Türkçe
+Agent Enderun is designed to support the specific AI adapter that matches your IDE or CLI environment.
 
-## Yönetici Özeti
-
-**Agent Enderun**, AI asistanlarını yüksek ölçekte kullanırken kontrolü, izlenebilirliği, denetlenebilirliği ve profesyonel disiplini korumak isteyen mühendislik ekipleri için tasarlanmış, **Anayasal Yönetişim** ve **Çoklu Ajan Orkestrasyonu** odaklı kurumsal düzeyde bir framework’tür.
+```text
+               ┌───────────────────────┐
+               │    agent-enderun      │
+               └───────────┬───────────┘
+                           │
+         ┌─────────────────┼─────────────────┐
+         ▼                 ▼                 ▼
+  .enderun/          .claude/           .cursor/
+(Gemini Adapter)   (Claude Code)     (Cursor IDE)
+```
 
-Çoğu yapay zeka kodlama aracı hız ve üretim hacmine odaklanırken, Agent Enderun **risk farkındalıklı, denetlenebilir ve sürekli iyileştirilen yazılım geliştirme süreçlerine** odaklanır. Kaotik yapay zeka çıktılarını; zorunlu kurallar, özel ajanlar, kalıcı bellek ve yaşayan bir risk yönetim sistemi aracılığıyla yapılandırılmış kurumsal standartlara dönüştürür.
+### 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"]
+    }
+  }
+}
+```
 
-> [!NOTE]
-> **v0.7.0 Stratejik Konsolidasyon:**
-> Çalışma zamanı klasörü kullanıcı projelerinde `.enderun/` olarak oluşturulur. Ajan yapılandırmaları `.enderun/agents/{agent_name}.md` altında yer alır. Eski veya mükerrer yapılar tamamen kaldırılmıştır.
+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)
 
 ---
 
-## 🎯 Temel Felsefe ve Anahtar Kavramlar
-
-Agent Enderun, temel bileşenleri tarafından uygulanan, tavizsiz ilkeler üzerine kurulmuştur.
-
-### 1. Anayasa (`ENDERUN.md`)
-Bu, tüm ajanlar için zorunlu kuralları ve protokolleri dikte eden, çerçevenin en üst yasasıdır. Temel ilkeler şunları içerir:
-- **Tek Yetki Noktası:** Kurumsal projelerde `@manager` tek yetkili giriş noktasıdır. Hiçbir uzman ajan, resmi bir brifing almadan kendi başına işlem yapamaz.
-- **Önce Sözleşme (Contract-First) ile Geliştirme:** `@backend` ajanı, `@frontend` ajanı uygulamaya başlamadan ÖNCE API sözleşmelerini ve tiplerini tanımlamak ve belgelemek ZORUNDADIR.
-- **Sıfır UI Kütüphanesi ve Sıfır Mock Veri Politikası:** `@frontend` ajanı, bileşenleri projenin tasarım sistemini (Panda CSS) kullanarak sıfırdan oluşturmalı ve mock (sahte) veri KULLANMAMALIDIR. Bu, özgünlüğü ve kaliteyi garanti eder.
-- **Prosedürel Devamlılık:** Tüm ajanlar, projenin mevcut mimari ve stilistik kalıplarına uymak ZORUNDADIR.
-
-### 2. Proje Hafızası (`PROJECT_MEMORY.md`)
-`.enderun/` içinde bulunan bu dosya, projenin durumu için **Tek Doğruluk Kaynağıdır (SSOT)**. Tüm ajanların bir oturumun başında okuduğu ve sonunda güncellediği, insan tarafından okunabilir bir Markdown dosyasıdır. Ana bölümleri şunlardır:
-- **`CURRENT STATUS`:** Aktif aşamayı, Trace ID'yi ve varsa engelleyicileri izler.
-- **`CRITICAL DECISIONS`:** Tutarlılığı sağlamak için önemli mimari seçimlerin bir kaydı.
-- **`ACTIVE TASKS`:** Devam eden tüm görevlerin, durumlarının, önceliklerinin ve atanan ajanın bir tablosu.
-- **`HISTORY`:** Ajanlar tarafından gerçekleştirilen tüm eylemlerin kalıcı bir kaydı.
-
-### 3. İzlenebilirlik (Trace ID)
-Her göreve veya mantıksal iş birimine benzersiz bir **Trace ID** (26 karakterlik bir ULID) atanır. Bu kimlik, commit mesajlarında, loglarda ve görev tablolarında kullanılarak ilk talepten nihai koda kadar kesintisiz bir izlenebilirlik zinciri sağlar.
+## 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/`.
 
 ---
 
-## 🤖 Ajan Ordusu
-
-Enderun Ordusu'ndaki her ajan, kendilerine ait kuralları, izin verilen dizinleri ve yetenek derecelendirmelerini tanımlayan güçlü tipli bir `agent.json` dosyası tarafından yönetilir.
-
-### Çalışma Alanı Ajan Yolu:
-👉 `[proje-kök-dizini]/.enderun/agents/{agent_name}.md`
-
-### Ajan Ordusuna Genel Bakış (v1.0 - 12 Uzman Ajan):
-
-| Katman | Ajan | Yetenek | Rol & Alan | Ana Uzmanlık Alanı |
-| :--- | :--- | :--- | :--- | :--- |
-| **Core** | **@orchestrator** | **9.8/10** | Görev Kuyruğu Motoru | Paralel yürütme, stateful kuyruk kontrolleri, DAG yönetimi. |
-| **Core** | **@manager** | **9.5/10** | Orkestrasyon & Yönetişim | Talep analizi, yüksek riskli dinamik imza kontrolü, onay mekanizması. |
-| **Analiz** | **@analyst** | **9.6/10** | Kalite & Sözleşme Kapısı | Vitest/Cypress test denetimi, API kontrat sapma kontrolü, Sıfır-UI denetçisi. |
-| **Analiz** | **@explorer** | **9.4/10** | Araştırma & Keşif | Kod yapısı desen eşleme, bağımlılık grafiği çıkarma, onboarding analizi. |
-| **Geliştirme** | **@backend** | **9.2/10** | Domain Mantığı & DB | Fastify, Kysely veri tabanı sorguları, branded tipler, DomainError hiyerarşisi. |
-| **Geliştirme** | **@frontend** | **9.0/10** | Akıcı Duyarlı Arayüz | React 19, Panda CSS stil token'ları, Sıfır-UI, WCAG 2.2 AA erişilebilirlik. |
-| **Geliştirme** | **@native** | **8.9/10** | Native Yetenekler | Tauri/Electron kabuk koruması, Rust köprüleri, güvenli IPC kontratları. |
-| **Geliştirme** | **@mobile** | **8.8/10** | Çoklu Platform Mobil | React Native/Expo akıcı görünümler, offline önbellek senkronizasyonu. |
-| **Operasyon** | **@security** | **9.3/10** | Güvenlik & Uyum | OWASP tehdit tespiti, AST tabanlı statik sır taraması, CSP denetimi. |
-| **Operasyon** | **@qa** | **9.1/10** | Kalite Güvence Kapısı | Birim/entegrasyon test kontrolü, kapsama metrikleri denetçisi. |
-| **Operasyon** | **@git** | **9.1/10** | Versiyon Kontrolü | Semantik commit formatlama, atomik commit ayırma, faz snapshot'ları. |
-| **Operasyon** | **@devops** | **9.0/10** | Altyapı & Deployment | Deployment boru hatları, konteyner kurulumları, ortam değişkenleri denetimi. |
+## 5. CLI Reference Manual
+
+| 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. |
 
 ---
 
-## 🏛️ Agent Enderun: Detaylı Kod Tabanı Denetim Raporu (v0.8.6)
-
-Çerçevenin (framework) çekirdek kod yapısı, operasyonel işleyişi, alt-üst ajan hiyerarşisi ve temizlenmiş mükerrer alanları en ince ayrıntısına kadar denetlenmiş ve belgelenmiştir:
-
-### 📂 1. Kapsamlı Klasör ve Dosya Yapısı Analizi
+## 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
+```
 
-* **🧠 Çekirdek Komuta Klasörü (`.enderun/`):** 
-  * Ajanların şablon kaynak dosyalarının yer aldığı ve hedef projede `.enderun/` (veya `.claude/` / `.cursor/`) olarak yeniden adlandırılan ana zeka merkezidir.
-  * **`agents/` (Ajan Tanımları & SOP'lar)**: 12 uzman ajanın davranış kurallarını barındırır. Her ajanın altında bir `agent.json` ve prompt/SOP dosyaları (`prompt.md`) bulunur. Durum makinesi şeması `schema/agent-lifecycle-schema.json` ile yönetilir.
-  * **`knowledge/` (Bilgi Bankası)**: Projenin anayasasını, sıfır UI kütüphanesi politikasını ve veri tabanı/kod standartlarını içeren 26 adet Markdown kılavuzunu barındırır. `corporate-governance/` alt klasöründe onay mekanizmaları, branded types hukuku ve audit loglama standartları gibi kurumsal düzeydeki 17 katı yönetişim kılavuzu yer alır.
-  * **`memory-graph/` (Bellek Grafiği)**: Ajanların etkileşim ağını (`graph.json`), ortak paylaştıkları doğruları (`shared-facts.json`) ve her bir ajanın yerel bağlam belleklerini (`agent-contexts/`) saklar.
-  * **`queue/` (Dosya Tabanlı Görev Kuyruğu)**: Asenkron ve paralel görevlerin yönetildiği dizindir. `pending/`, `processing/`, `completed/` ve `failed/` alt dizinleri sayesinde Trace ID üzerinden asenkron görev takibi yapılır.
-  * **`logs/` (Aksiyon Günlükleri)**: Ajanların gerçekleştirdiği tüm mutasyonları Trace ID (ULID) ile damgalayarak JSON formatında saklar (Örn: `backend.json`, `analyst.json`).
+---
+---
 
-* **🔌 Model Context Protocol (MCP) Katmanı (`framework-mcp/`):** 
-  * Ajanların IDE (Gemini, Claude, Cursor) ile konuşmasını ve yerel sistemdeki dosyaları güvenle manipüle etmesini sağlayan ana entegrasyon paketidir.
-  * **`src/tools/`**: 13 adet çekirdek MCP araç modülünü (kod tabanı aramaları, bellek kilit protokolleri, kontrat doğrulamaları, statik AST analizli güvenlik taramaları vb.) barındırır.
-  * **`src/schemas.ts`**: MCP araçlarına gönderilen parametrelerin tip güvenliğini Zod şemalarıyla denetler (Gereksiz/pasif şemalar temizlenmiştir).
-  * **`src/index.ts`**: MCP sunucusunun stdio üzerinden IDE ile bağlantısını kuran ana giriş kapısıdır.
+# Türkçe
 
-* **🚀 Çalıştırılabilir Dizin & CLI (`bin/` ve `src/cli/`):**
-  * **`bin/cli.js`**: `npx tsx src/cli/index.ts` komutunu sarmalayan çalıştırılabilir binary giriş noktasıdır.
-  * **`src/cli/index.ts`**: Projeyi platformlara göre (`gemini`, `claude`, `cursor`) scaffold eden ve sağlık kontrollerini (`check`, `status`) koordine eden çekirdek CLI motorudur.
-  * **`bin/hermes-sandbox.js`**: Ajanlar arası Yüksek Riskli İşlem ve dynamic onay (`managerApproval`) mesajlaşma akışını yerel olarak simüle eden test sandbox'ıdır.
+## İç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)
 
-### 🧹 2. Gerçekleştirilen v1.0 Kritik Temizlik ve Düzenlemeler
+---
 
-* **Ajan Promptlarındaki Çöp Veriler Temizlendi:** `analyst`, `backend`, `mobile` ve `native` promptlarının sonundaki bozuk mükerrer satırlar ve generic raporlama blokları tamamen kaldırılmıştır.
-* **Ölü MCP Kodları / Araçları Ayıklandı:** `schemas.ts` içindeki 8 adet pasif/unimplemented araç şeması ayıklanmış ve promptlardaki ölü araç referansları temizlenmiştir.
-* **Olmayan Klasör Referansları Onarıldı:** Olmayan `.enderun/blueprints/` klasör referansları, `.enderun/knowledge/` altındaki aktif rehberlerle başarılı şekilde değiştirilmiştir.
-* **Çoklu Platform ve Kök Senkronizasyonu Sağlandı:** `gemini.md`, `claude.md` ve `cursor.md` dosyaları şablon ve kök dizinde senkronize edilerek CLI dağıtımına hazır hale getirilmiştir.
+## 1. Giriş ve Temel Felsefe
 
-### 👑 3. Ajan Ordusu Hiyerarşisi ve Çalışma Akışı
+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**.
 
-* **Üst Ajan (Lead):** `@manager` her zaman varsayılan liderdir. Projedeki tüm alt görevler onun brifingi ile başlar.
-* **Alt Ajanlar (Specialists):** `@backend`, `@frontend`, `@security` vb. uzman ajanlar kendilerine atanan asenkron görevleri yapar.
-* **Kalite Kapısı:** `@analyst` ve `@security` yapılan geliştirmelerin anayasaya uygunluğunu denetlemeden hiçbir kod parçası staging/commit aşamasına geçemez.
+### 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.
 
 ---
 
+## 2. Kurulum ve Hızlı Başlangıç
 
-## ⚡ Hızlı Başlangıç ve İş Akışı
+### Ö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).
 
-### 1. Kurulum
+### Adım Adım Kurulum
 
-Framework'ü projenize kurmak ve başlatmak için aşağıdaki adımları takip edin:
+#### 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
-# 1. Framework'ü Gemini CLI için başlatın
 npx agent-enderun init gemini
+```
+*Not: Bir adaptör belirtilmezse standart olarak `gemini` kurulur ve framework çalışma ortamı `.enderun/` dizininde oluşturulur.*
 
-# 2. Bağımlılıkları yükleyin (istendiği gibi)
+#### Adım 3: Bağımlılıkları Yükleyin ve MCP Sunucusunu Derleyin
+```bash
 npm install
-
-# 3. Framework'ün dahili araçlarını derleyin (istendiği gibi)
 npm run enderun:build
+```
+
+---
 
-# 4. Kurulumu ve proje sağlığını doğrulayın
+### Sağlık ve Doğrulama Taraması
+
+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
 ```
 
-### 2. Örnek İş Akışı: Yeni Bir Özellik Ekleme
+#### 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 Enderun'u yeni bir özellik geliştirmek için nasıl kullanacağınız aşağıda açıklanmıştır:
+---
 
-**Adım 1: Görevi Tanımlayın**
-Projenizin `docs/` klasöründe yeni bir dosya oluşturun (örn. `docs/yeni-ozellik-isteği.md`) ve istediğiniz özelliği tanımlayın.
+## 3. Adaptörler ve Kullanım Senaryoları
 
-**Adım 2: Yeni Bir İz (Trace) Oluşturun**
-`PROJECT_MEMORY.md`'de yeni bir görev oluşturmak için CLI'yi kullanın. Bu, benzersiz bir Trace ID oluşturur.
+Agent Enderun, kullandığınız editör veya yapay zeka aracına uygun adaptörü dinamik olarak etkinleştirir.
 
-```bash
-npx agent-enderun trace:new "docs/yeni-ozellik-isteği.md'ye göre kullanıcı profili sayfasını uygula" @manager P1
-```
+### 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ı.
 
-**Adım 3: Ajan Orkestrasyonu (Otomatik)**
-`@manager` ajanı (varsayılan AI kişiliği) şunları yapacaktır:
-1.  `PROJECT_MEMORY.md`'yi okuyacak ve yeni görevi görecektir.
-2.  `docs/yeni-ozellik-isteği.md`'deki talebi analiz edecektir.
-3.  Bir plan oluşturacak ve `@explorer`, `@backend` ve `@frontend` gibi uzman ajanlara resmi "brifingler" verecektir.
+### 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.
 
-**Adım 4: Geliştirme ve Doğrulama (Otomatik)**
-- Uzman ajanlar, anayasal kurallara göre görevlerini yerine getirir (örneğin, `@backend` API'yi ve tipleri oluşturur, ardından `@frontend` kullanıcı arayüzünü oluşturur).
-- `@analyst`, yapılan işi proje standartlarına göre otomatik olarak doğrular.
-- `@git`, Trace ID ile etiketlenmiş atomik `commit`'ler oluşturur.
+### Claude Code / Claude Desktop Entegrasyonu
 
-**Adım 5: İlerlemeyi İzleyin**
-`status` komutuyla ilerlemeyi istediğiniz zaman kontrol edebilirsiniz:
+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:
 
-```bash
-npx agent-enderun status
+```json
+{
+  "mcpServers": {
+    "agent-enderun-mcp": {
+      "command": "node",
+      "args": ["/absolute/path/to/your/project/framework-mcp/dist/index.js"]
+    }
+  }
+}
 ```
-Bu, aktif aşamayı, engelleri ve tüm aktif görevlerin durumunu gösterecektir.
+
+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ı)
 
 ---
 
-## 🛠️ CLI Komutları
+## 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.
+
+---
 
-Agent Enderun, projeyi yönetmek için güçlü bir komut satırı araç seti ile birlikte gelir.
+## 5. CLI Referans Klavuzu
+
+| 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. |
 
-| Komut | Açıklama |
-| :--- | :--- |
-| `npx agent-enderun init [adapter]` | Framework'ü mevcut projede başlatır. `gemini` varsayılan ve önerilen adaptördür. |
-| `npx agent-enderun check` | Gerekli tüm dosyaların ve yapılandırmaların mevcut olduğundan emin olmak için projede bir sağlık kontrolü çalıştırır. |
-| `npx agent-enderun status` | `PROJECT_MEMORY.md`'den mevcut proje durumunu, aktif görevleri ve engelleri gösterir. |
-| `npx agent-enderun trace:new "<açıklama>" [ajan] [öncelik]` | Benzersiz bir Trace ID ile yeni bir görev oluşturur ve bunu `PROJECT_MEMORY.md`'ye ekler. |
-| `npx agent-enderun create-app "<açıklama>"` | (Takma adlar: `new`, `start`) Doğal dil tanımından yeni bir tam yığın uygulama (backend + web) oluşturur. |
-| `npx agent-enderun verify-contract` | `contract.version.json`'da saklanan `hash` ile mevcut kodu karşılaştırarak paylaşılan backend tiplerinin bütünlüğünü doğrular. |
 ---
 
-**Agent Enderun is not just a tool. It is a complete operating system for professional, risk-aware, AI-assisted software development.**
+## 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
+```