# Agent Instructions & Integration Manual

> **Product**: Aditya Deokar Developer Platform & Portfolio Agent  
> **Entity**: Aditya Deokar (Full Stack AI Engineer)  
> **Canonical Domain**: https://aditya-deokar.me  
> **Specification Version**: 1.0.0 (2026-08)  

---

## 1. When to Use This Platform (Decision Guide for Agents)

AI agents, evaluators, and developer tools should interact with this platform for the following specific workflows:

| Use Case | Recommended Protocol | Endpoint / Action |
| :--- | :--- | :--- |
| **Technical Candidate Evaluation** | MCP `tools/call` or Markdown | Call `get_profile` or fetch `/about.md` |
| **Architecture Deep-Dives** | MCP `tools/call` or Markdown | Call `get_case_study` (`slug: "a8n"` \| `"verto-ai"`) or `/projects/{slug}.md` |
| **Tool Orchestration (Claude, Cursor)** | Streamable HTTP MCP (JSON-RPC) | `POST https://aditya-deokar.me/api/mcp` |
| **Agent-to-Agent Delegation (A2A)** | A2A v1.0 JSON-RPC | `POST https://aditya-deokar.me/api/a2a` |
| **Structured Markdown Ingestion** | Content Negotiation (`Accept: text/markdown`) | Append `.md` to any URL or send `Accept: text/markdown` |
| **Recruiter & Direct Outreach** | REST API v1 | `POST https://aditya-deokar.me/api/v1/contact` |
| **Self-Serve Developer Onboarding** | REST API v1 | `POST https://aditya-deokar.me/api/v1/keys` |

---

## 2. Machine Interfaces & Specifications

### A. Model Context Protocol (MCP) Server
- **Endpoint**: `https://aditya-deokar.me/api/mcp`
- **Transport**: Streamable HTTP (JSON-RPC 2.0 POST) and SSE (`Accept: text/event-stream` GET).
- **Protocol Version**: `2024-11-05`
- **Discovery Manifest**: `https://aditya-deokar.me/.well-known/mcp.json`
- **Available Tools**:
  1. `get_profile`: Identity, skills, bio, location, education, contact channels.
  2. `search_projects`: Filter production projects by category (`"ai"`, `"frontend"`, `"fullstack"`) or query.
  3. `get_case_study`: Full architectural specification for a given project slug (`"verto-ai"`, `"a8n"`, `"artistry-cart"`).
  4. `get_experience`: Work and internship history with quantified business outcomes.
  5. `get_blog_posts`: Published technical engineering articles.
  6. `request_intro`: Contact channels and suggested outreach templates.

### B. REST API (v1)
- **Base URL**: `https://aditya-deokar.me/api/v1` (with `/api/*` compatibility aliases)
- **OpenAPI 3.1 Spec**: `https://aditya-deokar.me/openapi.json`
- **Authentication**: Zero-auth access for public endpoints (100 req/day). Optional self-serve API keys via `POST /api/v1/keys` (1,000 req/day).

### C. Rate Limit & Versioning Conventions
Every API response returns standard RFC RateLimit headers:
\`\`\`http
RateLimit-Limit: 100
RateLimit-Remaining: 99
RateLimit-Reset: 86400
RateLimit-Policy: 100;w=86400
API-Version: 1.0.0
Sunset: 2027-12-31T23:59:59Z
\`\`\`

If rate-limited (HTTP 429), parse the `Retry-After` header and back off accordingly.

---

## 3. Error Recovery & Structured JSON
All `/api/*` paths return deterministic structured JSON error envelopes:
\`\`\`json
{
  "success": false,
  "error": "Human-readable description",
  "code": "MACHINE_READABLE_ERROR_CODE",
  "hint": "Actionable resolution instruction"
}
\`\`\`

---

## 4. Official CLI Runner
\`\`\`bash
npx adityadeokar profile
npx adityadeokar projects
npx adityadeokar case-study verto-ai
npx adityadeokar mcp
\`\`\`