agent-enderun 0.1.9 → 0.2.0

package/README.md

@@ -1,4 +1,6 @@
-# Agent Enderun (v0.1.9)
+# 🏛️ Agent Enderun — v0.2.0
+
+**The Supreme AI Governance & Orchestration Framework for Enterprise Development**
 
 [English](#english) | [Türkçe](#türkçe)
 
@@ -6,288 +8,686 @@
 
 # English
 
-Agent Enderun is a purpose-built, enterprise-grade AI orchestration framework for software teams who want to use AI inside a repository without losing engineering discipline. It turns AI assistants into specialized collaborators by enforcing rules, preserving context, and coordinating multi-agent workflows.
+## Executive Summary
 
-## Why Agent Enderun exists
+Agent Enderun is a **production-grade AI governance framework** designed for engineering teams that must maintain control, traceability, and discipline when using AI assistants for code generation. It transforms chaotic AI output into structured, auditable, enterprise-ready deliverables through:
 
-Most AI assistants are powerful but inconsistent in code repositories. Agent Enderun solves this by making the repository itself the source of truth:
+- **Agent-Led Orchestration**: 8 specialized AI agent roles with defined responsibilities
+- **Contract-First Development**: Shared TypeScript types as the single source of truth
+- **Phase-Based Execution**: Strict workflow progression (PHASE_0 → PHASE_4)
+- **Enterprise Auditability**: Every decision, action, and commit is logged and traceable
+- **Modular MCP Intelligence**: 40+ tools across 12 categories for code analysis, security, and automation
 
-- Enforce a single architecture and style guide.
-- Keep every decision recorded in persistent project memory.
-- Separate AI guidance from production code with hidden adapter directories.
-- Prevent backend/frontend contract drift using shared types and API documentation.
-- Enable engineers to work with AI without giving up traceability, auditability, or quality.
+---
 
-## Core Concepts
+## ⚡ 5-Minute Quick Start
 
-### Constitution — `ENDERUN.md`
-A built-in lawbook for your AI helpers. Every agent must read it first and follow its rules, including phase gates, code style policies, and forbidden actions.
+### Prerequisites
+- **Node.js**: 20+ (LTS recommended)
+- **npm**: 9+
+- **Git**: Initialized in your project root
+- **Any AI Adapter**: Gemini, Claude, Cursor, or Codex (optional but recommended)
 
-### Project Memory — `PROJECT_MEMORY.md`
-A persistent project brain that records active phase, trace IDs, decisions, and history. It keeps the project state machine coherent across sessions and agents.
+### Installation Steps
 
-### Agent Academy
-A team of specialized agents, each with a strict SOP and a unique domain:
+#### Step 1: Clone or Initialize
+```bash
+# Option A: Clone this framework repository
+git clone https://github.com/ybekar/agent-enderun.git
+cd agent-enderun
 
-- `@manager`: orchestration, phase gating, trace IDs
-- `@analyst`: QA, documentation, memory auditing
-- `@backend`: backend architecture, contracts, security
-- `@frontend`: UI/UX, Panda CSS, frontend continuity
-- `@explorer`: codebase research, dependency mapping
-- `@mobile`: mobile strategy and performance
-- `@native`: desktop integration and OS constraints
-- `@git`: git hygiene, atomic commits, traceable history
+# Option B: Or use as npm package (when published)
+npx agent-enderun init gemini
+```
 
-### Clean Root Policy
-All AI-specific logic, agent instructions, and memory live in adapter directories such as `.gemini/`, `.claude/`, `.cursor/`, or `.codex/`. Your repository root stays clean for production assets, docs, and source code.
+#### Step 2: Install Dependencies
+```bash
+npm install
+```
 
-### Contract-First Architecture
-Backend and frontend communicate through `packages/shared-types` and documented API contracts in `{{FRAMEWORK_DIR}}/docs/api/`. This prevents mismatched expectations and ensures both sides implement the same contract.
+#### Step 3: Build Framework
+```bash
+npm run enderun:build
+```
 
-### Zero UI Library Policy
-The frontend must use Panda CSS and no third-party UI kits. This gives you original visuals, better performance, and zero runtime UI dependencies.
+#### Step 4: Verify Setup
+```bash
+agent-enderun check
+```
 
-## What makes Agent Enderun different
+Expected output:
+```
+✅ Framework active (v0.2.0)
+✅ MCP Server ready
+✅ Shared types compiled
+✅ Agent logs initialized
+✅ PROJECT_MEMORY.md found
+```
 
-- Persistent, audited project memory for every decision.
-- Multi-agent orchestration instead of a single general-purpose assistant.
-- Strict phase transitions from discovery to delivery.
-- Built-in contract verification and shared typed APIs.
-- Hidden adapter directories to keep CI-friendly repository roots.
-- Explicit package manager intelligence in the CLI.
+---
 
-## Project structure
+## 🎯 What You Can Do Right Now
 
-```
-/README.md
-/CHANGELOG.md
-/.enderun/
-/.gemini/ or /.claude/
-/apps/backend/
-/apps/web/
-/packages/framework-mcp/
-/packages/shared-types/
-/docs/
+### Initialize Your Project
+```bash
+# Creates .enderun/ directory with governance files
+npx agent-enderun init gemini
 ```
 
-### Key folders
+### Check Project Health
+```bash
+# Runs security audit, compliance check, and dependency analysis
+agent-enderun check
 
-- `apps/backend/` — server implementation and business logic.
-- `apps/web/` — frontend interface and Panda CSS UI.
-- `packages/shared-types/` — shared contract types for all agents.
-- `packages/framework-mcp/` — MCP server tools for AI-assisted workflows.
-- `.enderun/` — framework rules, memory, agent SOPs, and hidden configuration.
+# Just security
+agent-enderun check:security
 
-## Installation and setup
+# Just compliance
+agent-enderun check:compliance
+```
 
-Agent Enderun detects the package manager automatically, but you can also force it using an environment variable:
+### View Project Status
+```bash
+# Shows current phase, active agents, and blockers
+agent-enderun status
+```
+
+### Create a New Task
+```bash
+# Creates a ULID-based trace for a new feature
+agent-enderun trace:new "Implement User Authentication" backend P1
+```
 
+### Verify API Contracts
 ```bash
-AGENT_ENDERUN_PACKAGE_MANAGER=npm npx agent-enderun init gemini
-AGENT_ENDERUN_PACKAGE_MANAGER=yarn npx agent-enderun init gemini
-AGENT_ENDERUN_PACKAGE_MANAGER=pnpm npx agent-enderun init gemini
+# Ensures shared-types and API docs are synchronized
+agent-enderun verify-contract
 ```
 
-> Legacy environment variables `AI_ENDERUN_PACKAGE_MANAGER` and `AGENT_ENDERUN_PM` are still accepted for compatibility.
+---
 
-### Recommended install flow
+## 🏗️ Core Architecture
 
-```bash
-npx agent-enderun init gemini
-npm install && npm run enderun:build
-agent-enderun check
+Agent Enderun consists of **4 integrated layers**:
+
+### Layer 1: Governance (.enderun/)
+```
+.enderun/
+├── ENDERUN.md              ← The "Supreme Law" (read this first!)
+├── PROJECT_MEMORY.md       ← Single source of truth for state
+├── STATUS.md               ← Agent status dashboard
+├── cli-commands.json       ← CLI ownership mapping
+├── agents/                 ← 8 agent role definitions
+├── logs/                   ← Audit trail (agent.json files)
+├── knowledge/              ← 16+ technical knowledge articles
+└── docs/api/               ← API contract specifications
 ```
 
-> Agent Enderun is built and optimized for npm. If you prefer yarn, you can explicitly set `AGENT_ENDERUN_PACKAGE_MANAGER=yarn`.
+### Layer 2: Framework Core (bin/ + packages/)
+```
+bin/cli.js                 ← CLI bootstrapper
+packages/
+├── framework-mcp/         ← 40+ MCP tools (12 categories)
+└── shared-types/          ← Branded types (single source of truth)
+```
+
+### Layer 3: Documentation (docs/)
+```
+docs/
+├── tech-stack.md          ← Approved technology stack
+├── project-docs.md        ← Product requirements (template)
+└── [your project files]   ← Your documents (agents will read these)
+```
 
-## CLI Quick Reference
+### Layer 4: Application (apps/) — YOURS
+```
+apps/
+├── backend/               ← Your backend app (create this)
+├── web/                   ← Your frontend app (create this)
+└── [other apps]/          ← Mobile, desktop, etc.
+```
 
-| Command | Purpose |
-| --- | --- |
-| `npx agent-enderun init <adapter>` | Scaffold the framework and hidden adapter files |
-| `agent-enderun check` | Validate framework health, memory, contracts and build artifacts |
-| `agent-enderun trace:new "desc"` | Create a new task Trace ID |
-| `agent-enderun verify-contract` | Verify shared type contract hash |
-| `npm run enderun:build` | Build shared-types and framework-mcp packages |
+---
 
-## Typical workflow
+## 🎓 The Agent Academy — 8 Specialized Roles
 
-1. Initialize with `npx agent-enderun init gemini`.
-2. Add project requirements in `docs/project-docs.md`.
-3. Confirm stack and architecture in `docs/tech-stack.md`.
-4. Ask the `@manager` agent to start a new task (the agent will run `agent-enderun trace:new` automatically).
-5. Let the manager agent delegate work to specialized agents using trace IDs.
-6. Keep every change logged in `.enderun/PROJECT_MEMORY.md`.
+Each agent has a defined **Standard Operating Procedure (SOP)** and reads the constitution before every action.
 
-## Onboarding new engineers
+| Agent | Specialty | What They Do |
+|---|---|---|
+| **@manager** | Orchestration | Runs the phase machine, creates trace IDs, delegates tasks, updates PROJECT_MEMORY |
+| **@analyst** | Quality Control | Security audits, compliance checks, documentation debt, code review |
+| **@backend** | Data Architecture | Database schema, API contracts, shared-types integrity, Kysely standards |
+| **@frontend** | UI Development | React components, Panda CSS styling, Zero-UI Library enforcement, responsive design |
+| **@explorer** | Code Intelligence | Dependency graphs, complexity analysis, dead code detection, legacy code mapping |
+| **@git** | Repository Master | Semantic commits, branch management, conflict resolution, merge strategies |
+| **@mobile** | Mobile Apps | React Native, Expo, iOS/Android specifics, performance optimization |
+| **@native** | Native Apps | Tauri, Electron, native performance, IPC protocols, system integration |
 
-Share these project truths:
+---
 
-- Always read `ENDERUN.md` before editing.
-- Every task belongs to a trace ID.
-- Use `shared-types` instead of hand-writing API types.
-- No third-party UI libraries in the frontend.
-- Keep AI adapter config hidden under `.gemini/`, `.claude/`, `.cursor/`, or `.codex/`.
+## 🛠️ MCP Tools Reference
 
-## Troubleshooting
+The framework provides **40+ tools** organized in 12 categories. Agents use these automatically.
 
-- If `agent-enderun init` fails during install, rerun with the correct package manager override.
-- If `agent-enderun check` reports missing build artifacts, run `npm run enderun:build`.
-- If contract hashes drift, run `npm run verify-contract` and update `packages/shared-types/contract.version.json`.
+### Framework Tools
+- `get_framework_status` — Check framework health
+- `get_project_gaps` — Identify missing files/structure
+- `get_memory_insights` — Analyze PROJECT_MEMORY
+- `bootstrap_legacy_memory` — Auto-detect existing projects
 
-## Contribution and extension
+### Codebase Tools
+- `search_codebase` — Find code patterns
+- `analyze_dependencies` — Map imports/exports
+- `analyze_codebase_intelligence` — Find complexity & dead code
+- `generate_dependency_graph` — Mermaid diagrams
 
-Agent Enderun is designed to be extended through:
+### Security & Compliance
+- `security_audit_scan` — Check for secrets, SQL injection, console.log
+- `analyze_constitution_compliance` — Enforce ENDERUN.md rules
 
-- new adapter directories (`.gemini/`, `.claude/`, `.cursor/`, `.codex/`)
-- additional agent SOPs under `.enderun/agents`
-- new project-specific API contracts in `.enderun/docs/api/`
-- shared type expansions in `packages/shared-types/src`
+### Contract Management
+- `verify_api_contract` — Hash verification
+- `verify_contract_integrity` — Type synchronization
+- `update_contract_hash` — Sync shared-types
 
-If you add a new capability, document it in `CHANGELOG.md` and preserve the existing version header.
+### Git & Commits
+- `generate_semantic_commit_message` — Auto-generate commit messages
+
+### Academy Intelligence
+- `get_academy_performance` — Agent success rates
+- `generate_strategic_briefing` — High-level reports
+- `log_agent_action` — Structured logging
+
+### Repository Health
+- `validate_repository_health` — Run lint/test/build
+- `analyze_documentation_debt` — Find missing JSDoc/READMEs
+
+### Agent Collaboration
+- `send_agent_message` — Inter-agent communication
+- `read_agent_messages` — Check agent inbox
+
+### Database & Knowledge
+- `analyze_database_schema` — Extract ER diagrams
+- `search_knowledge_base` — Find technical guides
+- `update_knowledge_base` — Add knowledge entries
 
 ---
 
-# Türkçe
+## 📖 How Agents Read Your Project
 
-Agent Enderun, kod deposunda AI kullanırken mühendislik disiplini ve izlenebilirliği korumak isteyen ekipler için tasarlanmış bir AI orkestrasyon çerçevesidir. Yapay zeka yardımcılarını, profesyonel bir mühendis ekibinin parçası gibi çalışacak şekilde yapılandırır.
+When you add documentation to `docs/`, agents automatically discover and use it:
 
-## Neden Agent Enderun?
+```
+docs/
+├── project-docs.md        ← Agents read here for requirements
+├── tech-stack.md          ← Technology decisions
+├── design-system.md       ← (optional) UI patterns
+├── api-guide.md           ← (optional) API examples
+└── architecture.md        ← (optional) System design
+```
 
-Çoğu AI asistanı güçlü olsa da kod tabanlarında tutarlı davranmayabilir. Agent Enderun bu sorunu şu şekilde çözer:
+Agents use the `search_knowledge_base` tool to find answers to common questions.
 
-- Tek mimari ve stil rehberi uygular.
-- Her kararı kalıcı proje hafızasına kaydeder.
-- AI talimatlarını üretim kodundan gizli dizinlerde tutar.
-- Backend ve frontend sözleşmelerinin uyumunu `shared-types` ile sağlar.
-- AI ile çalışırken izlenebilirlik ve kalite kaybını engeller.
+---
 
-## Temel Kavramlar
+## ✅ Complete Installation Checklist
 
-### Anayasa — `ENDERUN.md`
-Tüm AI ajanlarının okumak ve uymak zorunda olduğu kural kitabı. Faz geçişleri, kod politikaları ve yasaklı hareketler burada tanımlanır.
+- [ ] **Node.js 20+** installed (`node --version`)
+- [ ] **npm 9+** installed (`npm --version`)
+- [ ] **Git** initialized (`git init`)
+- [ ] **Framework installed** (`npm install && npm run enderun:build`)
+- [ ] **Health check passed** (`agent-enderun check` shows ✅)
+- [ ] **First task created** (`agent-enderun trace:new "Your task" backend P1`)
+- [ ] **Docs created** (add files to `docs/` for agents to read)
+- [ ] **MCP connected** (agents can now use tools)
 
-### Proje Hafızası — `PROJECT_MEMORY.md`
-Aktif fazı, trace ID'leri, kararları ve tarihsel kayıtları saklayan kalıcı beyin.
+---
 
-### Ajan Akademisi
-Her biri kendi uzmanlık alanı ve SOP'u olan bir ajan takımı:
+## 🚀 First Real Task
 
-- `@manager`: orkestrasyon, faz kapıları, trace ID yönetimi
-- `@analyst`: kalite, dokümantasyon, hafıza denetimi
-- `@backend`: backend mimarisi, sözleşmeler, güvenlik
-- `@frontend`: UI/UX, Panda CSS, frontend sürekliliği
-- `@explorer`: kod tabanı araştırması, bağımlılık haritalama
-- `@mobile`: mobil strateji ve performans
-- `@native`: masaüstü entegrasyonu ve işletim sistemi kısıtları
-- `@git`: git hijyeni, atomik commit'ler, izlenebilir tarihçe
+Once everything is installed, try this:
 
-### Temiz Kök Politikası
-Tüm AI spesifik yapı `.gemini/`, `.claude/`, `.cursor/` veya `.codex/` gibi gizli dizinlerde saklanır. Depo kökü sadece üretim kodu, doküman ve yapılandırma için temiz kalır.
+```bash
+# Step 1: Create a real project requirement
+echo "# User Authentication
 
-### Sözleşme Öncelikli Mimari
-Backend ve frontend, `packages/shared-types` ve `{{FRAMEWORK_DIR}}/docs/api/` belgeleri üzerinden eşleşir. Bu, taraflar arasında yanlış anlaşılma ihtimalini azaltır.
+Implement JWT-based authentication with refresh tokens.
+- Email/password login
+- Logout endpoint
+- Token refresh mechanism
+" > docs/requirements.md
 
-### Sıfır UI Kütüphanesi Politikası
-Frontend, Panda CSS kullanmalı ve üçüncü taraf UI kitleri yasaklanmalıdır. Böylece performans, özgünlük ve sıfır runtime bağımlılığı sağlanır.
+# Step 2: Create a task
+agent-enderun trace:new "Implement Auth Module" backend P1
 
-## Agent Enderun’u Öne Çıkaranlar
+# Step 3: Agents read requirements and build
+# (They will automatically read docs/requirements.md)
+```
 
-- Kalıcı, denetlenebilir proje hafızası.
-- Tek bir genel asistan yerine uzman ajan orkestrasyonu.
-- Keşiften teslimata kadar sıkı faz geçişleri.
-- Paylaşılan tipler ve API sözleşme doğrulaması.
-- Gizli adaptör dizinleriyle temiz depo kökü.
-- CLI içinde paket yöneticisi akıllılığı.
+---
 
-## Proje Yapısı
+## 📁 Project Structure
 
 ```
-/README.md
-/CHANGELOG.md
-/.enderun/
-/.gemini/ veya /.claude/
-/apps/backend/
-/apps/web/
-/packages/framework-mcp/
-/packages/shared-types/
-/docs/
+agent-enderun/
+├── README.md                          ← This file
+├── package.json                       ← Root npm config
+├── bin/
+│   └── cli.js                         ← CLI entry point
+├── docs/                              ← Your project docs (agents read these)
+│   ├── tech-stack.md
+│   └── project-docs.md
+├── packages/
+│   ├── shared-types/                  ← Branded types (contract)
+│   │   ├── src/index.ts
+│   │   └── contract.version.json      ← SHA-256 integrity hash
+│   └── framework-mcp/                 ← MCP server (40+ tools)
+│       └── src/tools/
+│           ├── academy.ts
+│           ├── codebase.ts
+│           ├── security.ts
+│           ├── contract.ts
+│           ├── git.ts
+│           ├── knowledge.ts
+│           ├── database.ts
+│           ├── memory.ts
+│           ├── messages.ts
+│           ├── repository.ts
+│           └── framework.ts
+├── apps/                              ← Your applications (start here)
+│   ├── backend/                       ← (you create this)
+│   └── web/                           ← (you create this)
+└── .enderun/                          ← Framework governance
+    ├── ENDERUN.md                     ← Constitution (MANDATORY READ)
+    ├── PROJECT_MEMORY.md              ← State machine
+    ├── STATUS.md                      ← Agent dashboard
+    ├── cli-commands.json              ← Command ownership
+    ├── config.json                    ← Configuration
+    ├── agents/                        ← 8 agent role docs
+    │   ├── manager.md
+    │   ├── analyst.md
+    │   ├── backend.md
+    │   ├── frontend.md
+    │   ├── explorer.md
+    │   ├── git.md
+    │   ├── mobile.md
+    │   └── native.md
+    ├── logs/                          ← Audit trail
+    │   ├── manager.json
+    │   ├── backend.json
+    │   ├── frontend.json
+    │   ├── analyst.json
+    │   ├── explorer.json
+    │   ├── git.json
+    │   ├── mobile.json
+    │   └── native.json
+    ├── knowledge/                     ← 16+ technical guides
+    │   ├── branded_types_pattern.md
+    │   ├── async_error_handling.md
+    │   ├── security_scanning.md
+    │   ├── contract_versioning.md
+    │   ├── git_commit_strategy.md
+    │   ├── testing_standards.md
+    │   └── [12 more...]
+    ├── messages/                      ← Inter-agent communication
+    └── docs/
+        ├── api/                       ← API contracts
+        │   ├── auth.md
+        │   ├── errors.md
+        │   └── README.md
+        └── [other docs]
 ```
 
-### Ana klasörler
+---
+
+## 💡 Frequently Asked Questions
+
+### Q: What does "contract-first" mean?
+**A:** All API shapes and domain models are defined in `packages/shared-types/src/index.ts` **before** any code is written. Frontend and backend must both use these types, ensuring perfect alignment.
+
+### Q: Do agents actually understand all this?
+**A:** Yes. Before every action, agents read:
+1. `ENDERUN.md` (the constitution)
+2. `.enderun/PROJECT_MEMORY.md` (project state)
+3. `docs/` files (your requirements)
+4. `.enderun/knowledge/` (technical guidelines)
+
+### Q: What if I don't use an AI adapter?
+**A:** The framework still works as a **collaborative development platform**. You and your team use it to enforce:
+- Phase progression
+- Audit logging
+- Shared type discipline
+- API contract verification
+
+### Q: Can I extend the MCP tools?
+**A:** Yes. Add new tool files in `packages/framework-mcp/src/tools/`, define the schema, and export the handler. The CLI will automatically discover them.
+
+### Q: How do I add my own agents?
+**A:** Create a markdown file in `.enderun/agents/your-agent.md`, define the SOP, and add a CLI mapping in `.enderun/cli-commands.json`.
+
+### Q: Is this production-ready?
+**A:** The **framework** is production-ready. Individual features (like `apps/`) depend on what you build. Start with `apps/backend` or `apps/web`.
+
+---
+
+## 🔗 Key Files to Read First
+
+1. **`.enderun/ENDERUN.md`** — The constitution (rules all agents must follow)
+2. **`.enderun/PROJECT_MEMORY.md`** — Current project state and history
+3. **`docs/tech-stack.md`** — Technology decisions
+4. **`packages/shared-types/src/index.ts`** — The contract (types)
+5. **`README.md`** (this file) — How to use the framework
+
+---
+
+## 📞 Support & Contribution
+
+### Report Issues
+File issues with clear reproduction steps and framework version.
+
+### Contribute
+1. Read `.enderun/ENDERUN.md`
+2. Follow the agent role guidelines
+3. Submit PRs with semantic commit messages
+4. Ensure tests pass: `npm run enderun:build`
+
+### License
+MIT © 2026 Yusuf BEKAR
+
+---
+
+# Türkçe
+
+## Genel Özet
+
+Agent Enderun, **kurumsal-grade bir yapay zeka yönetim çerçevesidir** ve yapay zeka asistanlarını kontrol altında tutmanız, izlenebilir olmasını sağlamanız ve disiplinli kod üretimini garantilamanız için tasarlanmıştır.
+
+- **Ajan Orkestrasyonu**: 8 uzmanlaşmış yapay zeka rolü
+- **Sözleşme-İlk Geliştirme**: Paylaşılan TypeScript türleri
+- **Faz Tabanlı Yürütme**: Sıkı iş akışı (PHASE_0 → PHASE_4)
+- **Kurumsal Denetim**: Her karar, işlem ve commit kaydedilir
+- **Modüler MCP Zekası**: 40+ araç, 12 kategori
+
+---
+
+## ⚡ 5 Dakikalık Hızlı Başlangıç
 
-- `apps/backend/` — sunucu uygulaması ve iş mantığı.
-- `apps/web/` — frontend UI ve Panda CSS bileşenleri.
-- `packages/shared-types/` — ortak sözleşme tipleri.
-- `packages/framework-mcp/` — AI destekli MCP sunucu araçları.
-- `.enderun/` — çerçeve kuralları, hafıza, ajan SOP'ları ve gizli yapılandırma.
+### Gereksinimler
+- **Node.js**: 20+ (LTS önerilir)
+- **npm**: 9+
+- **Git**: Proje kökünde başlatılmış
+- **AI Adaptörü** (opsiyonel): Gemini, Claude, Cursor veya Codex
 
-## Kurulum ve Hazırlık
+### Kurulum Adımları
 
-Agent Enderun, paket yöneticisini otomatik algılar; ancak aşağıdaki değişken ile zorlayabilirsiniz:
+#### Adım 1: Clone veya İnit
+```bash
+# Seçenek A: Framework repository'sini klonla
+git clone https://github.com/ybekar/agent-enderun.git
+cd agent-enderun
+
+# Seçenek B: veya npm paketi olarak kullan
+npx agent-enderun init gemini
+```
 
+#### Adım 2: Bağımlılıkları Yükle
 ```bash
-AGENT_ENDERUN_PACKAGE_MANAGER=npm npx agent-enderun init gemini
-AGENT_ENDERUN_PACKAGE_MANAGER=yarn npx agent-enderun init gemini
-AGENT_ENDERUN_PACKAGE_MANAGER=pnpm npx agent-enderun init gemini
+npm install
 ```
 
-### Önerilen kurulum akışı
+#### Adım 3: Framework'ü Derle
+```bash
+npm run enderun:build
+```
 
+#### Adım 4: Kurulumu Doğrula
 ```bash
-npx agent-enderun init gemini
-npm install && npm run enderun:build
 agent-enderun check
 ```
 
-## CLI Hızlı Referans
+Beklenen çıktı:
+```
+✅ Framework aktif (v0.2.0)
+✅ MCP Sunucu hazır
+✅ Paylaşılan türler derlenmiş
+✅ Agent logları başlatılmış
+✅ PROJECT_MEMORY.md bulundu
+```
 
-| Komut | Amaç |
-| --- | --- |
-| `npx agent-enderun init <adapter>` | Çerçeveyi ve gizli adaptör dosyalarını kurar |
-| `agent-enderun check` | Çerçeve sağlığını, hafızayı, kontratları ve build çıktısını doğrular |
-| `agent-enderun trace:new "desc"` | Yeni bir görev Trace ID'si oluşturur |
-| `agent-enderun verify-contract` | paylaşılan tip hash'ini doğrular |
-| `npm run enderun:build` | shared-types ve framework-mcp paketlerini derler |
+---
 
-## Tipik iş akışı
+## 🎯 Şu Anda Yapabileceğiniz İşler
 
-1. `npx agent-enderun init gemini` ile başlatın.
-2. `docs/project-docs.md` içinde gereksinimleri yazın.
-3. `docs/tech-stack.md` içinde teknoloji ve mimariyi doğrulayın.
-4. `@manager` ajandan yeni bir görev başlatmasını isteyin (ajan `agent-enderun trace:new` komutunu otomatik çalıştıracaktır).
-5. `manager` ajanın işleri Trace ID kullanarak ilgili uzman ajanlara yönlendirmesini bekleyin.
-6. Her değişikliği `.enderun/PROJECT_MEMORY.md` içinde kaydedin.
+### Projeyi Başlat
+```bash
+npx agent-enderun init gemini
+```
 
-## Yeni gelenler için
+### Sağlık Durumunu Kontrol Et
+```bash
+agent-enderun check                 # Tam kontrol
+agent-enderun check:security        # Sadece güvenlik
+agent-enderun check:compliance      # Sadece uyum
+```
 
-Her yazılımcıya şunu iletin:
+### Proje Durumunu Görüntüle
+```bash
+agent-enderun status
+```
 
-- Önce `ENDERUN.md` okuyun.
-- Her görev bir Trace ID gerektirir.
-- API veri tiplerini elle yazmayın; `shared-types` kullanın.
-- Frontend’de üçüncü taraf UI kütüphaneleri kullanmayın.
-- AI adaptör yapılandırmaları gizli dizinlerde tutulur.
+### Yeni Görev Oluştur
+```bash
+agent-enderun trace:new "Kullanıcı Doğrulama Uygulaması" backend P1
+```
 
-## Sorun giderme
+### API Kontratlarını Doğrula
+```bash
+agent-enderun verify-contract
+```
 
-- `agent-enderun init` kurulum sırasında hata veriyorsa doğru paket yöneticisi ile yeniden çalıştırın.
-- `agent-enderun check` build artefaktları eksik diyorsa `npm run enderun:build` çalıştırın.
-- Kontrat hash'leri uyuşmuyorsa `npm run verify-contract` çalıştırın ve `packages/shared-types/contract.version.json` güncelleyin.
+---
+
+## 🏗️ Temel Mimari
+
+Agent Enderun **4 entegre katmandan** oluşur:
+
+### Katman 1: Yönetişim (.enderun/)
+- `ENDERUN.md` — Anayasa (bunu ilk oku!)
+- `PROJECT_MEMORY.md` — Proje durumu
+- `agents/` — 8 ajan rolü tanımları
+- `logs/` — Denetim kaydı
+- `knowledge/` — 16+ teknik rehberi
+- `docs/api/` — API sözleşmeleri
+
+### Katman 2: Framework Çekirdeği
+- `packages/framework-mcp/` — 40+ MCP aracı
+- `packages/shared-types/` — Paylaşılan türler (sözleşme)
+- `bin/cli.js` — CLI başlatıcısı
+
+### Katman 3: Dokümantasyon
+- `docs/tech-stack.md` — Teknoloji kararları
+- `docs/project-docs.md` — Ürün gereksinimleri
+- Ajanlar bu dosyaları okurlar
+
+### Katman 4: Uygulamalarınız
+- `apps/backend/` — Backend uygulaması (siz oluşturun)
+- `apps/web/` — Frontend uyguması (siz oluşturun)
+
+---
+
+## 🎓 Ajan Akademisi — 8 Uzman Rol
 
-## Katkıda bulunma ve genişletme
+| Ajan | Uzmanlık | Görev |
+|---|---|---|
+| **@manager** | Orkestrasyoun | Faz yönetimi, trace ID, görev delegasyonu |
+| **@analyst** | Kalite Kontrol | Güvenlik denetimi, uyum kontrolü, kod incelemesi |
+| **@backend** | Veri Mimarisi | Veritabanı, API kontratları, Kysely standartları |
+| **@frontend** | UI Geliştirme | React, Panda CSS, bileşen tasarımı |
+| **@explorer** | Kod Zekası | Bağımlılıklar, karmaşıklık, ölü kod |
+| **@git** | Repository Ustası | Semantik commit'ler, branch yönetimi |
+| **@mobile** | Mobil Uygulamalar | React Native, Expo, iOS/Android |
+| **@native** | Yerel Uygulamalar | Tauri, Electron, sistem entegrasyonu |
 
-Agent Enderun şu yollarla genişletilebilir:
+---
 
-- yeni adaptör dizinleri ekleyerek (`.gemini/`, `.claude/`, `.cursor/`, `.codex/`)
-- `.enderun/agents` altına yeni ajan SOP'ları ekleyerek
-- `.enderun/docs/api/` altına yeni API sözleşmeleri ekleyerek
-- `packages/shared-types/src` içindeki paylaşılan tipleri genişleterek
+## ✅ Komple Kurulum Kontrol Listesi
 
-Yeni bir özellik ekliyorsanız, bunu `CHANGELOG.md` içinde belgeleyin ve mevcut sürüm başlığını koruyun.
+- [ ] **Node.js 20+** yüklü (`node --version`)
+- [ ] **npm 9+** yüklü (`npm --version`)
+- [ ] **Git** başlatılmış (`git init`)
+- [ ] **Framework yüklü** (`npm install && npm run enderun:build`)
+- [ ] **Sağlık kontrolü geçti** (`agent-enderun check` ✅ gösteriyor)
+- [ ] **İlk görev oluşturuldu** (`agent-enderun trace:new "Görev" backend P1`)
+- [ ] **Doklar oluşturuldu** (`docs/` klasörüne dosya ekledim)
+- [ ] **MCP bağlandı** (ajanlar araçları kullanabiliyor)
 
 ---
 
-## License
+## 🚀 İlk Gerçek Görev
+
+Kurulum tamamlandıktan sonra bunu deneyin:
+
+```bash
+# Adım 1: Gerçek gereksinim yazın
+echo "# Kullanıcı Doğrulaması
+
+JWT tabanlı kimlik doğrulama sistemi kurun.
+- Email/şifre girişi
+- Oturumu kapat endpoint'i
+- Token yenileme mekanizması
+" > docs/requirements.md
+
+# Adım 2: Görev oluşturun
+agent-enderun trace:new "Auth Modülü Uygula" backend P1
+
+# Adım 3: Ajanlar sizin için çalışır
+# (Otomatik olarak docs/requirements.md okurlar)
+```
+
+---
+
+## 📁 Proje Yapısı
+
+```
+agent-enderun/
+├── docs/                 ← Ajanların okuyacağı dokümantasyon
+├── packages/
+│   ├── shared-types/     ← Paylaşılan türler (sözleşme)
+│   └── framework-mcp/    ← MCP sunucusu (40+ araç)
+├── apps/                 ← Uygulamalarınız (siz oluşturun)
+├── .enderun/             ← Yönetişim dosyaları
+│   ├── ENDERUN.md        ← Anayasa (OKUNMALI)
+│   ├── PROJECT_MEMORY.md ← Proje durumu
+│   ├── agents/           ← 8 ajan tanımı
+│   ├── logs/             ← Denetim kaydı
+│   ├── knowledge/        ← 16+ rehber
+│   └── docs/api/         ← API sözleşmeleri
+└── bin/
+    └── cli.js            ← CLI giriş noktası
+```
+
+---
+
+## 💡 Sıkça Sorulan Sorular
+
+### S: "Sözleşme-ilk" ne demek?
+**C:** Tüm API şekilleri ve alan modelleri `packages/shared-types` içinde **kod yazılmadan önce** tanımlanır. Frontend ve backend aynı türleri kullanır.
+
+### S: Ajanlar bütün bunları anlıyor mu?
+**C:** Evet. Her işlem öncesi şunları okurlar:
+1. `ENDERUN.md` (anayasa)
+2. `.enderun/PROJECT_MEMORY.md` (proje durumu)
+3. `docs/` dosyaları (gereksinimler)
+4. `.enderun/knowledge/` (teknik rehberler)
+
+### S: AI adaptörü kullanmak zorunlu mu?
+**C:** Hayır. Framework, AI'sız da işlev görür. Faz ilerleme, denetim kaydı ve tür disiplini zorunludur.
+
+### S: MCP araçlarını genişletebilir miyim?
+**C:** Evet. `packages/framework-mcp/src/tools/` klasörüne yeni dosya ekleyin.
+
+### S: Kendi ajanlarımı ekleyebilir miyim?
+**C:** Evet. `.enderun/agents/` klasörüne `.md` dosyası oluşturun ve CLI mapping'ini güncelleyin.
+
+### S: Üretim için hazır mı?
+**C:** Framework hazır. `apps/` klasörü tamamen sizin.
+
+---
+
+## 🔗 Önce Okumanız Gereken Dosyalar
+
+1. **`.enderun/ENDERUN.md`** — Anayasa
+2. **`.enderun/PROJECT_MEMORY.md`** — Proje durumu
+3. **`docs/tech-stack.md`** — Teknoloji kararları
+4. **`packages/shared-types/src/index.ts`** — Sözleşme (türler)
+5. **`README.md`** — Bu dosya
+
+---
+
+## 📞 Destek & Katkı
+
+### Sorun Bildir
+Net adımlarla ve versiyon numarası ile sorun bildir.
+
+### Katkıda Bulun
+1. `.enderun/ENDERUN.md` oku
+2. Agent rolü yönergelerine uyun
+3. Semantik commit'ler gönder
+4. Testleri geç: `npm run enderun:build`
+
+### Lisans
+MIT © 2026 Yusuf BEKAR
+```bash
+agent-enderun status
+```
+
+### 4. Advanced Intelligence Commands
+```bash
+# Run Security Audit
+agent-enderun check:security
+
+# Generate Dependency Graph
+agent-enderun explorer:graph
+
+# Get Commit Suggestion
+agent-enderun git:commit [TRACE-ID]
+```
+
+---
+
+## 📂 Consolidated Framework Structure (`.enderun/`)
+
+All governance and engineering assets are consolidated under the framework directory for a clean project root.
+
+```text
+.
+├── .enderun/
+│   ├── ENDERUN.md           # Supreme Law (Constitution)
+│   ├── PROJECT_MEMORY.md    # Working Memory & History
+│   ├── BRAIN_DASHBOARD.md   # Intelligence & Performance Stats
+│   ├── cli-commands.json    # Agent-to-CLI Mapping
+│   ├── agents/              # 8 Specialized Agent SOPs
+│   ├── knowledge/           # 17+ Enterprise Knowledge Articles
+│   ├── docs/                # API Contracts, Security, Privacy, Strategy
+│   ├── logs/                # Traceable structured JSON logs
+│   ├── benchmarks/          # Performance metrics
+│   └── monitoring/          # System health hooks
+├── bin/                     # CLI Entry Point
+├── packages/                # Shared Types & MCP Engine
+└── apps/                    # Production Modules (Backend, Web, Mobile)
+```
+
+---
+
+## 🛡️ Engineering Standards
+
+-   **Zero Mock Policy:** Placeholders are forbidden. Every line of code must be functional.
+-   **Branded Types:** IDs must be type-safe (e.g., `UserID` vs `string`).
+-   **Panda CSS Only:** Zero-runtime CSS-in-JS for high-performance UI.
+-   **Contract-First:** Schemas are defined in `shared-types` BEFORE implementation.
+
+---
 
-MIT - (c) 2026 Yusuf BEKAR
+## 📜 License
+MIT © 2026 Yusuf BEKAR — **Agent Enderun: The Future of AI Governance.**