diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..7e591959
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Core Architecture
+
+This is a monorepo for the Agentic platform - a system that provides API gateway services for MCP (Model Context Protocol) and OpenAPI integrations. The platform consists of:
+
+- **API Service** (`apps/api/`) - Internal platform API with authentication, billing, and resource management
+- **Gateway Service** (`apps/gateway/`) - Cloudflare Worker that proxies requests to origin MCP/OpenAPI services
+- **E2E Tests** (`apps/e2e/`) - End-to-end test suite for HTTP and MCP interfaces
+- **Shared Packages** (`packages/`) - Common utilities, types, validators, and configuration
+
+The gateway accepts requests at `https://gateway.agentic.so/deploymentIdentifier/toolName` for REST or `https://gateway.agentic.so/deploymentIdentifier/mcp` for MCP.
+
+## Development Commands
+
+**Main development workflow:**
+
+- `pnpm dev` - Start all services in development mode
+- `pnpm build` - Build all packages and apps
+- `pnpm test` - Run all tests (format, lint, typecheck, unit)
+- `pnpm clean` - Clean all build artifacts
+
+**Individual test commands:**
+
+- `pnpm test:format` - Check code formatting with Prettier
+- `pnpm test:lint` - Run ESLint across all packages
+- `pnpm test:typecheck` - Run TypeScript type checking
+- `pnpm test:unit` - Run unit tests with Vitest
+
+**Code quality:**
+
+- `pnpm fix` - Auto-fix formatting and linting issues
+- `pnpm knip` - Check for unused dependencies
+
+**E2E testing:**
+
+- `cd apps/e2e && pnpm e2e` - Run all E2E tests
+- `cd apps/e2e && pnpm e2e-http` - Run HTTP edge E2E tests
+- `cd apps/e2e && pnpm e2e-mcp` - Run MCP edge E2E tests
+
+## Key Database Models
+
+The system uses Drizzle ORM with PostgreSQL. Core entities:
+
+- **User** - Platform users
+- **Team** - Organizations with members and billing
+- **Project** - Namespace API products comprised of immutable Deployments
+- **Deployment** - Immutable instances of MCP/OpenAPI services
+- **Consumer** - Customer subscription tracking usage and billing
+
+## Agentic Configuration
+
+Agentic projects use `agentic.config.{ts,js,json}` files to define:
+
+- Project name and metadata
+- Origin adapter (MCP server or OpenAPI spec)
+- Tool configurations and permissions
+- Pricing plans and rate limits
+- Authentication requirements
+
+The platform supports both MCP servers and OpenAPI specifications as origin adapters.
+
+## Gateway Request Flow
+
+1. Request hits gateway with deployment identifier
+2. Gateway validates consumer authentication/rate limits
+3. Request is transformed and forwarded to origin service
+4. Response is processed and returned with appropriate headers
+5. Usage is tracked for billing and analytics
+
+## Environment Setup
+
+Both `apps/api` and `apps/gateway` require environment variables for:
+
+- Database connections (`DATABASE_URL`)
+- External services (Stripe, GitHub, Resend, Sentry)
+- Authentication secrets
+- Admin API keys
diff --git a/readme.md b/readme.md
index 6e697740..84d0209d 100644
--- a/readme.md
+++ b/readme.md
@@ -7,15 +7,8 @@
 
 ## API Gateway
 
-- **REST**: `GET/POST gateway.agentic.so/deploymentIdentifier/toolName`
-  - => MCP: `MCPClient.callTool` with JSON body parameters
-  - => OpenAPI: `GET/POST/ETC originUrl/toolName` operation with transformed JSON body params
-- **MCP**: `mcp.agentic.so/deploymentIdentifier` MCP server?
-  - => MCP: `MCPClient.callTool` just proxying tool call
-  - => OpenAPI: `GET/POST/ETC originUrl/toolName` operation with transformed tool params
-- RAW: `METHOD gateway.agentic.so/deploymentIdentifier/<pathname>`
-  - => Raw HTTP: `METHOD originUrl/<pathname>` simple HTTP proxy request
-  - TODO: remove / disable `raw` support for now
+- **REST**: `GET/POST` `https://gateway.agentic.so/deploymentIdentifier/toolName`
+- **MCP**: `https://gateway.agentic.so/deploymentIdentifier/mcp`
 
 ## TODO
 
@@ -23,10 +16,6 @@
 - stripe
   - stripe checkout
   - stripe billing portal
-- end-to-end working examples
-  - openapi
-  - mcp
-  - raw
 - auth
   - custom auth pages for `openauth`
 - **API gateway**
@@ -37,7 +26,9 @@
   - mcp-kitchen-sink
   - how to handle binary bodies and responses?
   - improve logger vs console for non-hono path and util methods
-  - test usage tracking and reporting
+  - **test rate limiting**
+  - **test usage tracking and reporting**
+  - disallow `mcp` as a tool name or figure out another workaround
 - **Public MCP server interface**
   - how does oauth work with this flow?
   - pass requestId to DurableMcpServer somehow on a per-request basis