agent-enderun 0.6.1 → 0.6.6

package/docs/getting-started.md

@@ -0,0 +1,271 @@
+# 🚀 Getting Started — Sıfırdan Agent Enderun ile Proje Kurma Rehberi / Quickstart Guide
+
+[English](#english) | [Türkçe](#türkçe)
+
+---
+
+# English
+
+This guide is prepared for developers and engineering teams who want to set up Agent Enderun **from scratch** on a new project. It provides a step-by-step, practical walkthrough.
+
+> **Primary recommended installation command from v0.6.6:** **`npx agent-enderun init` (generic framework setup)**
+
+---
+
+## 1. Introduction
+
+Agent Enderun is a yapay zeka/AI governance framework that provides **control, discipline, and traceability** in software development processes.
+
+By completing this guide, you will:
+- Install the framework in your project
+- Configure the basic components and environment
+- Create your first tracked task and start working with specialist agents
+
+---
+
+## 2. Prerequisites
+
+- **Node.js** 20+ (LTS recommended)
+- **npm** 9+
+- **Git** (must be initialized in the project directory)
+
+To check your local environment:
+
+```bash
+node --version
+npm --version
+git --version
+```
+
+---
+
+## 3. Step-by-Step Installation
+
+### Step 1: Create a New Project Directory
+
+```bash
+mkdir my-new-project
+cd my-new-project
+git init
+```
+
+### Step 2: Initialize the Framework
+
+To initialize the core framework cleanly (without hardcoding any AI/adapter-specific files before installation):
+
+```bash
+npx agent-enderun init
+```
+
+This command:
+- Creates the `.enderun/` directory by default
+- Installs all core governance files (`ENDERUN.md`, `PROJECT_MEMORY.md`, agents, knowledge, etc.)
+- Adds the default framework configuration files
+
+#### 💡 Optional: Installing with a Specific Adapter
+If you want to configure the framework for a specific AI assistant or editor environment (e.g. Antigravity, Claude, Cursor, Codex, Gemini), you can specify it as an option:
+
+```bash
+npx agent-enderun init antigravity
+# or
+npx agent-enderun init claude
+# or
+npx agent-enderun init cursor
+# or
+npx agent-enderun init codex
+# or
+npx agent-enderun init gemini
+```
+
+- If you run `init antigravity`, it will create `.antigravitycli/` instead of `.enderun/` and place `antigravity.md` at the project root.
+- If you run `init claude`, it will create `.claude/` and automatically configure the Claude Desktop MCP settings.
+- If you run `init cursor`, it will create `.cursor/` and copy the cursor rules configuration.
+- If you run `init gemini`, it will create `.gemini/` and place `gemini.md` at the project root.
+
+---
+
+### Step 3: Install Dependencies and Build
+
+```bash
+npm install
+npm run enderun:build
+```
+
+### Step 4: Verify the Installation
+
+```bash
+npx agent-enderun check
+```
+
+Expected output:
+
+```
+✅ Framework active (v0.6.6)
+✅ MCP Server ready
+✅ Shared types compiled
+✅ Agent logs initialized
+✅ PROJECT_MEMORY.md found
+```
+
+---
+
+## 4. Basic Configuration (Most Critical Step)
+
+Once initialized, you **must** update the following files to describe your project. Ajanlar (agents) learn your technology stack and target domain from here.
+
+### 4.1 `docs/tech-stack.md`
+
+This file is **mandatory**. Agents rely on it to make technical decisions.
+
+Example:
+
+```markdown
+# TECH STACK
+
+## Platform
+- Web (React + Vite)
+- Backend (Node.js + Fastify)
+
+## Database
+- PostgreSQL + Kysely
+
+## Auth
+- JWT + Refresh Token
+
+## Deployment
+- Vercel (Frontend) + Railway (Backend)
+```
+
+> **Warning:** If this file is empty, the agents will not be able to operate.
+
+### 4.2 `docs/project-docs.md`
+
+Write your project's goals, business requirements, and primary features here.
+
+### 4.3 `.enderun/PROJECT_MEMORY.md`
+
+Automatically created during initial setup. Review its content. *(Note: If you initialized with a custom adapter, this file will be located inside your adapter's folder, e.g., `.antigravitycli/PROJECT_MEMORY.md`)*.
+
+---
+
+## 5. Creating Your First Task
+
+You are now ready to create your first real task:
+
+```bash
+npx agent-enderun trace:new "User Registration and Login System" backend P1
+```
+
+This command:
+- Generates a unique Trace ID
+- Updates the **ACTIVE TASKS** section in `PROJECT_MEMORY.md`
+- Assigns the `@manager` agent to lead the task
+
+---
+
+## 6. Basics of Working with Agents
+
+### Automatic @manager Behavior
+
+At the start of every session (when a conversation begins), agents will automatically:
+
+1. Read `ENDERUN.md`
+2. Read `PROJECT_MEMORY.md`
+3. Load the active phase and current Trace ID
+
+### How to Direct Specialist Agents
+
+- Normally, **`@manager`** coordinates the process.
+- If you need to address a specialist agent directly, include their tag:
+
+```markdown
+@backend Implement the user model and auth services using Kysely.
+```
+
+### Critical Rules
+
+- Keep `docs/tech-stack.md` updated at all times.
+- When new key decisions are made, update the **CRITICAL DECISIONS** table in `PROJECT_MEMORY.md`.
+- Use a unique Trace ID for every task.
+
+---
+
+## 7. First Real-World Scenario Example
+
+Try this quick workflow:
+
+1. Populate `docs/tech-stack.md`
+2. Write a simple requirement in `docs/project-docs.md`
+3. Run the following command:
+
+```bash
+npx agent-enderun trace:new "User Registration and Login" backend P1
+```
+
+4. Then write to the assistant:
+
+> @manager Please analyze this requirement and propose the backend architecture.
+
+The agents will automatically:
+- Scan your codebase
+- Propose type contracts
+- Scaffold code using blueprints if necessary
+
+---
+
+## 8. Common Mistakes and Tips
+
+| Mistake | Consequence | Solution |
+| :--- | :--- | :--- |
+| Leaving `docs/tech-stack.md` empty | Agents will not know how to proceed | Ensure it is populated immediately |
+| Prompting for direct code generation | Messy and unmonitored code | Always have `@manager` plan first |
+| Not using Trace ID | Chaos and lost traceability | Use `trace:new` for every new feature |
+| Not updating `PROJECT_MEMORY.md` | Agents remember old state | Update memory with every key decision |
+
+---
+
+## 9. Next Steps
+
+After completing the guide, explore:
+
+- **Contract-First Development** → Check `apps/backend/src/types`
+- **Blueprint Scaffolding** → Look inside `.enderun/blueprints/`
+- **Security & Compliance** → Run `npx agent-enderun check:security`
+- **Inter-Agent Communication** → Hermes protocol (`messages/` directory)
+
+---
+
+## 10. Help and Support
+
+If you encounter issues:
+
+1. Run `npx agent-enderun status`
+2. Check `PROJECT_MEMORY.md`
+3. Inspect the error logs and the last 3 HISTORY entries
+
+---
+
+**Congratulations!** You can now develop software with discipline, structure, and governance using Agent Enderun.
+
+As a next step, we recommend defining **the core contracts of your first real project**.
+
+---
+
+# Türkçe
+
+Bu rehber, Agent Enderun'u **sıfırdan** yeni bir projeye kurmak isteyen geliştiriciler için hazırlanmıştır.
+
+> **v0.6.6 itibarıyla önerilen birincil başlatma komutu:** `npx agent-enderun init`
+
+Tüm teknik adımlar, ön gereksinimler, yapılandırma ve ajanlarla çalışma kuralları **İngilizce bölümde** detaylı olarak açıklanmıştır.
+
+Türkçe kısa özet:
+
+- `npx agent-enderun init` ile framework'ü kurun.
+- `docs/tech-stack.md` ve `docs/project-docs.md` dosyalarını doldurun.
+- `npx agent-enderun trace:new` ile ilk görevi oluşturun.
+- Her oturumda @manager otomatik olarak yönetir.
+
+Detaylı kurulum adımları, adaptör seçenekleri, hata önleme ipuçları ve örnek akışlar için lütfen İngilizce bölümü okuyun.
+
+**Tebrikler!** Artık Agent Enderun ile disiplinli yazılım geliştirmeye başlayabilirsiniz.

package/docs/roadmap.md

@@ -0,0 +1,142 @@
+# Agent Enderun — Development Roadmap (v0.6.6+) / Geliştirme Yol Haritası
+
+**Last Updated / Son Güncelleme:** 23 May 2026 / 23 May 2026  
+**Owner / Sorumlu:** @manager
+
+[English](#english) | [Türkçe](#türkçe)
+
+---
+
+# English
+
+This document outlines the development roadmap for the Agent Enderun framework **v0.6.6 and beyond**. All items are prioritized logically based on actual project needs and corporate governance principles.
+
+## Current Status (24 May 2026)
+
+- **Version:** v0.6.6 (ready for npm release)
+- **System Health:** 🟢 GREEN
+- **Key Accomplishments:**
+  - Full support for the Antigravity adapter (primary recommended adapter)
+  - Gemini adapter completely removed
+  - Lint technical debt resolved (reduced from 43 to 0 issues)
+  - Published `docs/getting-started.md` guide
+  - Updated memory structures and workspace hygiene
+
+- **Active Challenge:** Memory and task tracking need reinforcement (ACTIVE TASKS section is empty)
+
+---
+
+## Agent Maturity & Professionalization Program (Highest Strategic Initiative)
+
+To make Agent Enderun truly production-grade for enterprise use, agents must be professionalized to meet the standards of senior software engineers.
+
+This program systematically audits current agent maturity levels and runs structured improvements to elevate each agent to enterprise readiness.
+
+### Agent Maturity Targets
+
+| Agent Persona | Current Level | Target Level | Priority / Risk Status |
+| :--- | :--- | :--- | :--- |
+| **@manager** | 8.0 | 9.5 | High / Stable. Leadership and project management capabilities are excellent. |
+| **@backend** | 7.5 | 9.0 | High / Stable. Deeply understands Kysely and Fastify patterns; testing discipline needs reinforcement. |
+| **@frontend** | 6.5 | 9.0 | **Critical / High Risk**. Needs major reinforcement in component slots, composition patterns, WCAG 2.2 accessibility, and performance engineering. |
+| **@explorer** | 6.5 | 8.5 | High / Stable. Highly capable in dependency analysis and codebase intelligence. |
+| **@analyst** | 6.5 | 8.5 | Medium / Stable. Handles system health metrics and compliance audits. |
+| **@git** | 6.0 | 8.0 | Medium / Stable. Coordinates PRs, semantic commits, and version compliance. |
+| **@mobile & @native** | 2.0 | 7.5 | Low / Dormant. Foundational blueprints and Hermes safety rules added. |
+
+> **Note:** `@frontend` is currently the highest risk to enterprise onboarding and is the top priority.
+
+---
+
+## Roadmap Overview
+
+| Phase | Timeline | Focus | Priority |
+| :--- | :--- | :--- | :--- |
+| **Agent Maturity Program** | 1–4 Months | Elevate all agents to professional enterprise-grade | **Highest** |
+| **Phase 1** | 1–6 Weeks | Usability, automated configurations, and CLI tooling | High |
+| **Phase 2** | 1–3 Months | Hermes messaging stability & multi-agent intelligence | High |
+| **Phase 3** | 3+ Months | Scalability, performance benchmarks, and Reference Application | Medium |
+
+---
+
+## Agent Maturity Program — Phase 1 (Weeks 1–8)
+
+### 1. Professionalize @frontend Agent (Critical)
+- Component Architecture (Compound Components, Slots, Composition Patterns)
+- Accessibility (WCAG 2.2 AA compliance standards)
+- Performance Engineering (Core Web Vitals, virtualization, code splitting)
+- Testing Strategy (Hook + Component + Integration testing)
+- Error Boundaries & Resilience
+- Design System Governance
+
+### 2. Reinforce @backend Agent
+- Production Testing Culture (Unit + Integration + Contract + E2E)
+- Observability (Structured Logging + Metrics + Tracing)
+- Resilience Patterns (Idempotency, Retry, Circuit Breaker)
+- Query Optimization and Caching Strategy
+
+### 3. Elevate @manager Leadership
+- Technical Debt Auditing & Escalation Register
+- Risk Assessment Framework
+- Capacity Planning & Sustainable Delivery
+- Architecture Decision Records (ADR) Discipline
+
+---
+
+## Phase 1 — Short-Term (Weeks 1–6)
+
+### 1. Fully Automate Claude Configuration
+- **Description:** Remove the manual `claude config add` step after running `init claude`. Automatically patch the Claude Desktop configuration file.
+- **Complexity:** Medium
+- **Status:** Pending
+
+### 2. Frontend Blueprint System
+- **Description:** Carry the blueprint generator power of the backend over to the frontend. Establish structured React components, pages, and UI pattern blueprints.
+- **Complexity:** Medium-High
+- **Status:** Pending
+
+### 3. Expand Getting Started Documentation
+- **Description:** Enrich the new guide based on developer feedback. Add more real-world scenarios, troubleshooting tips, and best practices.
+- **Complexity:** Low-Medium
+- **Status:** In Progress (Getting started guide updated to v0.6.6)
+
+---
+
+## Phase 2 — Mid-Term (Months 1–3)
+
+### 4. Fully Implement Hermes Messaging Protocol
+- **Description:** Move inter-agent categorized, prioritized, and persistent messaging protocol from "defined on paper" to active code implementation.
+- **Complexity:** High
+- **Status:** Draft defined; implementation pending
+
+### 5. Reinforce Academy & Performance System
+- **Description:** Aggregate success metrics, failure tracking, and structured feedback for all agents to report via dashboard.
+- **Complexity:** Medium-High
+- **Status:** Basic tools available; scaling required
+
+---
+
+## Phase 3 — Long-Term (Months 3+)
+
+### 6. Production-Grade Reference Application
+- **Description:** Build a complete end-to-end reference application demonstrating normal CRUD + High-Risk Admin actions + Hermes messaging under Agent Enderun's governance.
+- **Complexity:** Very High
+- **Status:** Planned
+
+---
+
+# Türkçe
+
+Bu belge, Agent Enderun framework’ünün **v0.6.6 sonrası** geliştirme yol haritasını içerir.
+
+## Mevcut Durum (May 2026)
+
+- **Versiyon:** v0.6.6
+- **Sistem Sağlığı:** 🟢 GREEN (build ve test altyapısı onarım altında)
+- **v0.6.6 Odak:** Tüm framework’ün profesyonel İngilizceye dönüştürülmesi ve yönetişim boşluklarının dürüstçe analiz edilmesi.
+
+## Özet
+
+Ajan Olgunluk Programı devam etmektedir. @frontend en yüksek riskli ajan olmaya devam ediyor. Hermes protokolünün canlı test edilmesi ve referans uygulamanın üretilmesi önümüzdeki ana hedeflerdir.
+
+Detaylı plan ve risk takibi İngilizce bölümde yer almaktadır.

package/framework-mcp/README.md

@@ -1,4 +1,4 @@
-# AI-Enderun MCP Server (v0.3.4)
+# AI-Enderun MCP Server (v0.6.6)
 
 English | [Türkçe](#türkçe)
 

package/framework-mcp/dist/schemas.js

@@ -26,12 +26,18 @@ export const LOG_AGENT_ACTION_ARGS_SCHEMA = z.object({
     details: z.record(z.any()).default({}),
 });
 export const SEND_AGENT_MESSAGE_ARGS_SCHEMA = z.object({
+    from: z.string().min(1),
     to: z.string().min(1),
     message: z.string().min(1),
     traceId: z.string().min(1),
     category: z.enum(["ACTION", "DELEGATION", "INFO", "ALERT"]).default("INFO"),
     priority: z.enum(["LOW", "MEDIUM", "HIGH", "URGENT"]).default("MEDIUM"),
 });
+export const UPDATE_AGENT_MESSAGE_STATUS_ARGS_SCHEMA = z.object({
+    agent: z.string().min(1),
+    traceId: z.string().min(1),
+    newStatus: z.enum(["ACKNOWLEDGED", "COMPLETED", "REJECTED"]),
+});
 export const SEARCH_KNOWLEDGE_BASE_ARGS_SCHEMA = z.object({
     query: z.string().min(1),
 });

package/framework-mcp/dist/tools/academy.js

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { getFrameworkDir } from "../utils.js";
-import { GET_ACADEMY_PERFORMANCE_ARGS_SCHEMA, GENERATE_ACADEMY_PROGRESS_REPORT_ARGS_SCHEMA, GET_AGENT_AUDIT_REPORT_ARGS_SCHEMA, LOG_AGENT_ACTION_ARGS_SCHEMA } from "../schemas.js";
+import { GET_ACADEMY_PERFORMANCE_ARGS_SCHEMA, GET_AGENT_AUDIT_REPORT_ARGS_SCHEMA, LOG_AGENT_ACTION_ARGS_SCHEMA } from "../schemas.js";
 export const academyTools = [
     {
         name: "get_academy_performance",
@@ -101,7 +101,7 @@ export const academyHandlers = {
             }).filter(s => s.actions > 0);
             return { content: [{ type: "text", text: `### GLOBAL ACADEMY PERFORMANCE REPORT\n\n- **Analysis Period:** Last ${days} days\n- **Global Success Rate:** ${((totalSuccess / (totalActions || 1)) * 100).toFixed(1)}%\n\n**Agent Breakdown:**\n` + agentStats.map(s => `- **@${s.agent}:** ${s.actions} actions (${s.successRate.toFixed(1)}% success)`).join("\n") }] };
         }
-        catch (error) {
+        catch {
             return { content: [{ type: "text", text: "Failed to generate global performance report." }] };
         }
     },
@@ -120,13 +120,11 @@ export const academyHandlers = {
             const successRate = (successCount / (totalActions || 1)) * 100;
             return { content: [{ type: "text", text: `# 🏛️ ACADEMY STRATEGIC BRIEFING\n\n- **Academy Health:** ${successRate.toFixed(1)}% Success Rate over ${totalActions} actions.\n**Status:** READY FOR PHASE_1 COMPLETION.` }] };
         }
-        catch (error) {
+        catch {
             return { content: [{ type: "text", text: "Strategic briefing generation failed." }] };
         }
     },
     generate_academy_progress_report: async (args, projectRoot) => {
-        const parsed = GENERATE_ACADEMY_PROGRESS_REPORT_ARGS_SCHEMA.safeParse(args ?? {});
-        const days = parsed.success ? parsed.data.days : 7;
         try {
             const frameworkDir = getFrameworkDir(projectRoot);
             const memoryPath = path.join(projectRoot, frameworkDir, "PROJECT_MEMORY.md");
@@ -135,7 +133,7 @@ export const academyHandlers = {
             const milestones = Array.from(historySection.matchAll(/### (.*)\n\n- \*\*Agent:\*\* (.*)\n- \*\*Trace ID:\*\* (.*)\n- \*\*Action:\*\* (.*)/g)).slice(0, 5).map(m => `- [${m[1]}] **${m[2]}:** ${m[4]}`).join("\n");
             return { content: [{ type: "text", text: `# 🎓 AGENT ACADEMY PROGRESS REPORT\n\n## 🏆 Key Milestones Achieved\n${milestones}` }] };
         }
-        catch (error) {
+        catch {
             return { content: [{ type: "text", text: "Failed to generate progress report." }] };
         }
     },
@@ -153,7 +151,7 @@ export const academyHandlers = {
             const successCount = logs.filter((l) => l.status === "SUCCESS").length;
             return { content: [{ type: "text", text: `### AGENT AUDIT REPORT: ${parsed.data.agent.toUpperCase()}\n\n- **Total Actions:** ${logs.length}\n- **Success Rate:** ${((successCount / (logs.length || 1)) * 100).toFixed(1)}%` }] };
         }
-        catch (error) {
+        catch {
             return { content: [{ type: "text", text: "Failed to generate audit report." }] };
         }
     },
@@ -177,7 +175,7 @@ export const academyHandlers = {
             fs.writeFileSync(logPath, JSON.stringify(logs, null, 2));
             return { content: [{ type: "text", text: `SUCCESS: Logged action to ${parsed.data.agent}.json` }] };
         }
-        catch (error) {
+        catch {
             return { content: [{ type: "text", text: "Failed to log action." }] };
         }
     },

package/framework-mcp/dist/tools/codebase.js

@@ -135,7 +135,7 @@ export const codebaseHandlers = {
             try {
                 queryRegex = new RegExp(query, "i");
             }
-            catch (error) {
+            catch {
                 return { content: [{ type: "text", text: "Invalid regex pattern in query." }] };
             }
             const matches = [];
@@ -157,7 +157,7 @@ export const codebaseHandlers = {
             }
             return { content: [{ type: "text", text: matches.join("\n") || "No matches found." }] };
         }
-        catch (error) {
+        catch {
             return { content: [{ type: "text", text: "Search failed." }] };
         }
     },
@@ -223,7 +223,7 @@ export const codebaseHandlers = {
             }
             return { content: [{ type: "text", text: `### CODEBASE INTELLIGENCE REPORT\n\n**Complexity Spikes (>300 lines):**\n${complexitySpikes.length > 0 ? complexitySpikes.map(s => `- ${s}`).join("\n") : "- None detected"}\n\n**Potential Dead Code (Unused Exports):**\n${potentialDeadCode.length > 0 ? potentialDeadCode.map(d => `- ${d}`).join("\n") : "- None detected (within scanned scope)"}` }] };
         }
-        catch (error) {
+        catch {
             return { content: [{ type: "text", text: "Intelligence scan failed." }] };
         }
     },
@@ -253,8 +253,8 @@ export const codebaseHandlers = {
                 deviations.push("Reference uses 'get' prefix for functions, target does not.");
             return { content: [{ type: "text", text: deviations.length > 0 ? `### PROCEDURAL CONTINUITY DEVIATIONS\n\n${deviations.map(d => `- ${d}`).join("\n")}` : "No major structural or stylistic deviations detected based on reference." }] };
         }
-        catch (error) {
-            return { content: [{ type: "text", text: "Continuity analysis failed." }] };
+        catch {
+            return { content: [{ type: "text", text: "Dependency analysis failed." }] };
         }
     },
     generate_dependency_graph: async (args, projectRoot) => {
@@ -287,7 +287,7 @@ export const codebaseHandlers = {
             mermaid += uniqueEdges.join("\n");
             return { content: [{ type: "text", text: `### VISUAL ARCHITECTURE MAP: ${targetPath}\n\n\`\`\`mermaid\n${mermaid}\n\`\`\`\n\n**Total Nodes:** ${new Set(edges.flatMap(e => [e.from, e.to])).size} | **Total Edges:** ${uniqueEdges.length}` }] };
         }
-        catch (error) {
+        catch {
             return { content: [{ type: "text", text: "Dependency graph generation failed." }] };
         }
     },

package/framework-mcp/dist/tools/contract.js

@@ -40,6 +40,23 @@ export const contractTools = [
             required: ["domain"],
         },
     },
+    {
+        name: "validate_frontend_api_contract",
+        description: "Scans frontend hooks for API calls and compares them against backend API documentation and contracts. Returns mismatches (missing endpoints, type issues, etc.).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                frontendHooksPath: {
+                    type: "string",
+                    description: "Relative path to frontend hooks directory (default: apps/web/src/pages)",
+                },
+                backendApiDocsPath: {
+                    type: "string",
+                    description: "Relative path to backend API documentation (default: docs/api)",
+                },
+            },
+        },
+    },
 ];
 export const contractHandlers = {
     verify_api_contract: async (args, projectRoot) => {
@@ -52,8 +69,8 @@ export const contractHandlers = {
             const storedHash = JSON.parse(fs.readFileSync(contractJsonPath, "utf-8")).contract_hash;
             return { content: [{ type: "text", text: currentHash === storedHash ? "✅ MATCH: Contract is valid and synchronized." : `❌ MISMATCH: Current hash (${currentHash.slice(0, 8)}...) does not match stored hash (${storedHash.slice(0, 8)}...).` }] };
         }
-        catch (error) {
-            return { content: [{ type: "text", text: "Failed to verify contract." }] };
+        catch {
+            return { content: [{ type: "text", text: "Contract integrity check failed." }] };
         }
     },
     update_contract_hash: async (args, projectRoot) => {
@@ -72,7 +89,7 @@ export const contractHandlers = {
             fs.writeFileSync(contractJsonPath, JSON.stringify(contractJson, null, 2));
             return { content: [{ type: "text", text: `SUCCESS: Contract hash updated to ${currentHash}` }] };
         }
-        catch (error) {
+        catch {
             return { content: [{ type: "text", text: "Failed to update contract hash." }] };
         }
     },
@@ -100,8 +117,81 @@ export const contractHandlers = {
             });
             return { content: [{ type: "text", text: `### CONTRACT INTEGRITY SHIELD: ${parsed.data.domain.toUpperCase()}\n\n` + `- **Missing/Undefined Types:** ${missingTypes.length > 0 ? `⚠️ ${missingTypes.join(", ")}` : "✅ All types synchronized"}\n\n` + `**Result:** ${missingTypes.length === 0 ? "PASSED" : "FAILED"}` }] };
         }
-        catch (error) {
+        catch {
             return { content: [{ type: "text", text: "Contract verification failed." }] };
         }
     },
+    validate_frontend_api_contract: async (args, projectRoot) => {
+        const a = args;
+        const frontendPath = a?.frontendHooksPath || "apps/web/src/pages";
+        const backendDocsPath = a?.backendApiDocsPath || "docs/api";
+        try {
+            const fullFrontendPath = path.join(projectRoot, frontendPath);
+            const fullBackendDocsPath = path.join(projectRoot, backendDocsPath);
+            if (!fs.existsSync(fullFrontendPath)) {
+                return { content: [{ type: "text", text: `Frontend hooks path not found: ${frontendPath}` }] };
+            }
+            const hookFiles = collectFilesRecursively(fullFrontendPath, new Set(["ts", "tsx"]));
+            const apiCalls = [];
+            // Hook dosyalarındaki fetch çağrılarını ve response tiplerini çıkar
+            for (const file of hookFiles) {
+                const content = fs.readFileSync(file, "utf-8");
+                // Basit regex ile endpoint + response tipi yakala
+                const matches = content.matchAll(/(?:const\s+\w+\s*[:=]\s*await\s+)?fetch\(['"`](\/api\/[^'"`]+)['"`][^)]*\)\s*(?:\.then[^;]+)?(?:\s*as\s+([A-Z][a-zA-Z0-9]+)|:\s*([A-Z][a-zA-Z0-9]+))?/g);
+                for (const match of matches) {
+                    const endpoint = match[1];
+                    const responseType = match[2] || match[3];
+                    apiCalls.push({ endpoint, responseType });
+                }
+            }
+            const uniqueEndpoints = Array.from(new Set(apiCalls.map(c => c.endpoint)));
+            if (!fs.existsSync(fullBackendDocsPath)) {
+                return { content: [{ type: "text", text: `Backend API docs path not found: ${backendDocsPath}` }] };
+            }
+            const backendDocFiles = collectFilesRecursively(fullBackendDocsPath, new Set(["md"]));
+            const documentedEndpoints = [];
+            for (const file of backendDocFiles) {
+                const content = fs.readFileSync(file, "utf-8");
+                const matches = content.matchAll(/`?(\/api\/[a-zA-Z0-9/_-]+)`?/g);
+                for (const match of matches) {
+                    documentedEndpoints.push(match[1]);
+                }
+            }
+            const missingInDocs = uniqueEndpoints.filter(ep => !documentedEndpoints.some(d => ep.startsWith(d)));
+            const missingInHooks = documentedEndpoints.filter(d => !uniqueEndpoints.some(e => e.startsWith(d)));
+            let report = `### FRONTEND ↔ BACKEND CONTRACT VALIDATION REPORT\n\n`;
+            report += `**Scanned Frontend Hooks:** ${uniqueEndpoints.length} unique endpoints found\n`;
+            report += `**Scanned Backend API Docs:** ${documentedEndpoints.length} endpoints documented\n\n`;
+            if (missingInDocs.length > 0) {
+                report += `⚠️ **Endpoints called from frontend but NOT documented in backend:**\n${missingInDocs.map(e => `- ${e}`).join("\n")}\n\n`;
+            }
+            else {
+                report += `✅ All frontend-called endpoints are documented in backend.\n\n`;
+            }
+            if (missingInHooks.length > 0) {
+                report += `ℹ️ **Endpoints documented in backend but NOT used in scanned frontend hooks:**\n${missingInHooks.map(e => `- ${e}`).join("\n")}\n\n`;
+            }
+            // Basit tip karşılaştırması (eğer responseType varsa)
+            const typeMismatches = [];
+            for (const call of apiCalls) {
+                if (call.responseType) {
+                    const docContent = backendDocFiles
+                        .map(f => fs.readFileSync(f, "utf-8"))
+                        .join("\n");
+                    if (!docContent.includes(call.responseType)) {
+                        typeMismatches.push(`${call.endpoint} → expected type "${call.responseType}" not found in docs`);
+                    }
+                }
+            }
+            if (typeMismatches.length > 0) {
+                report += `⚠️ **Potential Type Mismatches:**\n${typeMismatches.map(m => `- ${m}`).join("\n")}\n\n`;
+            }
+            report += `**Result:** ${missingInDocs.length === 0 && typeMismatches.length === 0 ? "PASSED" : "FAILED (see mismatches above)"}`;
+            return { content: [{ type: "text", text: report }] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: "text", text: `Validation failed: ${message}` }] };
+        }
+    },
 };