# Merlin - The Complete AI Development Operating System
# Instructions for AI agents and LLMs to use this service

## About Merlin

Merlin is a complete AI development operating system with three integrated layers:

1. **Merlin Sights** - Instant codebase knowledge graph with discovery learning
2. **Merlin Agents** - 26+ specialist agents (spec, architect, implement, test, etc.)
3. **Merlin Loop** - Autonomous execution for hours of unattended development

### Core Capabilities

**Instant Context (Sights)**
- Complete codebase understanding from first query
- Impact analysis and similar code detection
- Enforceable coding rules and conventions
- Auto-sync on push — always current

**Endless Memory**
- Cross-session memory that never forgets
- Behavior learning from corrections
- Confidence scoring (auto-apply at 0.7+)
- One-command resume after weeks away

**26+ Specialist Agents**
- Core: product-spec, system-architect, implementation-dev, dry-refactor
- Core: hardening-guard, tests-qa, ops-railway, docs-keeper
- Platform: iOS, Android, desktop, web specialists
- Deep: debugger, performance, security, accessibility, more

**Autonomous Loop (Pro)**
- Fresh 200K context each iteration — no degradation
- Crash recovery with checkpoint persistence
- Circuit breaker after N consecutive errors
- Rate limiting and budget control

**Quality Gates**
- Auto-verification before every commit
- Build, types, lint, tests, security checks
- Fails? Fixes issues automatically, then commits

## Quick Start for AI Agents

### Option 1: MCP Integration (Recommended)

For Claude Code, Cursor, Windsurf, or any MCP-compatible tool:

```bash
# One install — everything included
npx create-merlin-brain
```

MCP tools available:
- `merlin_get_context` - Get task-specific codebase context
- `merlin_search` - Search documentation and code
- `merlin_find_files` - Locate files by purpose
- `merlin_get_brief` - Get project overview
- `merlin_get_rules` - Get coding conventions and enforceable rules
- `merlin_get_conventions` - Get patterns and anti-patterns
- `merlin_save_rule` - Save a learned coding rule
- `merlin_check_discovery` - Check for cached discoveries
- `merlin_teach_discovery` - Teach Sights what you discovered

### Option 2: CLI (Universal)

For AI tools without MCP (Copilot, Aider, etc.):

```bash
# Get context for a task
merlin context "add authentication"

# Search the codebase
merlin search "payment logic"

# Get coding rules
merlin rules
```

### Option 3: Public API

For external repository documentation:

```
GET https://merlin.build/api/public/wiki/{owner}/{repo}/agent
```

Returns structured JSON with:
- `overview`: Name, description, tech stack, key features
- `architecture`: System design, components, Mermaid diagrams
- `services`: Service-by-service breakdown with responsibilities
- `modules`: File organization and dependencies
- `apiReference`: Endpoints, functions, and types

## Merlin Workflows

Project lifecycle commands:

```bash
/merlin:new-project        # Initialize project with vision
/merlin:create-roadmap     # Create implementation phases
/merlin:plan-phase         # Create detailed execution plan
/merlin:execute-phase      # Execute with parallel agents
/merlin:verify-work        # Validate features (UAT)
/merlin:resume-work        # Resume from checkpoint
```

## API Endpoints

### Public Wiki API
```
GET /api/public/wiki/{owner}/{repo}       # Full documentation
GET /api/public/wiki/{owner}/{repo}/agent # AI-optimized format
GET /api/public/explore                   # Browse analyzed repos
```

### Sights Index API
```
GET /api/public/sights/search             # Search public Sights catalog
GET /api/public/sights/recommend          # Get recommendations for a task
GET /api/public/sights/context/{owner}/{repo}  # Get detailed Sight context
```

### Parameters
- `limit`: 1-100 (default: 20)
- `offset`: pagination offset
- `sort`: "stars" or "recent"
- `topic`: filter by GitHub topic

## Rate Limits
- Public endpoints: 100 requests/minute per IP
- Authenticated: 1000 requests/minute
- No auth required for public repositories

## AI Discovery Files

For automated agent integration:
- Agent Manifest: https://merlin.build/agents.json
- OpenAPI Spec: https://merlin.build/.well-known/openapi.json
- AI Plugin: https://merlin.build/.well-known/ai-plugin.json
- LLM Instructions: https://merlin.build/llms.txt (this file)
- Robots.txt: https://merlin.build/robots.txt

## Pricing (Token-Based)

- **Free**: 2 tokens for first repo (up to 5K lines), no credit card required
- **Subscription**: $20/user/month — Sights, MCP, API, dashboard access
- **Starter**: $50 for 50 tokens ($1.00/token)
- **Growth**: $150 for 200 tokens ($0.75/token, 25% off)
- **Scale**: $399 for 600 tokens ($0.665/token, 33% off)
- 1 token covers ~2,500 lines of code analysis
- Tokens never expire

## Links

- Website: https://merlin.build
- Sights Catalog: https://merlin.build/sights
- Install: https://merlin.build/install
- API Docs: https://merlin.build/.well-known/openapi.json
- GitHub: https://github.com/merlin-build/create-merlin-brain
- Contact: support@merlin.build