@rynfar/meridian 1.21.1

package/README.md

@@ -0,0 +1,410 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="Meridian" width="800"/>
+</p>
+
+<p align="center">
+  <a href="https://github.com/rynfar/meridian/releases"><img src="https://img.shields.io/github/v/release/rynfar/@rynfar/meridian?style=flat-square&color=6366f1&label=release" alt="Release"></a>
+  <a href="https://www.npmjs.com/package/@rynfar/meridian"><img src="https://img.shields.io/npm/v/@rynfar/meridian?style=flat-square&color=8b5cf6&label=npm" alt="npm"></a>
+  <a href="#"><img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-a78bfa?style=flat-square" alt="Platform"></a>
+  <a href="#"><img src="https://img.shields.io/badge/license-MIT-c4b5fd?style=flat-square" alt="License"></a>
+</p>
+
+---
+
+Meridian turns your Claude Max subscription into a local Anthropic API. Any tool that speaks the Anthropic protocol — OpenCode, Crush, Cline, Continue, Aider — connects to Meridian and gets Claude, powered by your existing subscription through the official Claude Code SDK.
+
+Harness Claude, your way.
+
+> [!NOTE]
+> **Renamed from `opencode-claude-max-proxy`.** If you're upgrading, see [`MIGRATION.md`](MIGRATION.md) for the checklist. Your existing sessions, env vars, and agent configs all continue to work.
+
+## Quick Start
+
+```bash
+# Install
+npm install -g @rynfar/meridian
+
+# Authenticate (one time)
+claude login
+
+# Start
+meridian
+```
+
+Meridian starts on `http://127.0.0.1:3456`. Point any Anthropic-compatible tool at it:
+
+```bash
+ANTHROPIC_API_KEY=x ANTHROPIC_BASE_URL=http://127.0.0.1:3456 opencode
+```
+
+The API key value doesn't matter — Meridian authenticates through your Claude Max session, not API keys.
+
+## Why Meridian?
+
+You're paying for Claude Max. It includes programmatic access through the Claude Code SDK. But your favorite coding tools expect an Anthropic API endpoint and an API key.
+
+Meridian bridges that gap. It runs locally, accepts standard Anthropic API requests, and routes them through the SDK using your Max subscription. Claude does the work — Meridian just lets you pick the tool.
+
+<p align="center">
+  <img src="assets/how-it-works.svg" alt="How Meridian works" width="920"/>
+</p>
+
+## Features
+
+- **Standard Anthropic API** — drop-in compatible with any tool that supports custom `base_url`
+- **Session management** — conversations persist across requests, survive compaction and undo, resume after proxy restarts
+- **Streaming** — full SSE streaming with MCP tool filtering
+- **Concurrent sessions** — run parent + subagent requests in parallel
+- **Passthrough mode** — forward tool calls to the client instead of executing internally
+- **Multimodal** — images, documents, and file attachments pass through to Claude
+- **Telemetry dashboard** — real-time performance metrics at `/telemetry`
+- **Cross-proxy resume** — sessions persist to disk and survive restarts
+- **Agent adapter pattern** — extensible architecture for supporting new agent protocols
+
+## Agent Setup
+
+### OpenCode
+
+```bash
+ANTHROPIC_API_KEY=x ANTHROPIC_BASE_URL=http://127.0.0.1:3456 opencode
+```
+
+For automatic session tracking, use a plugin like [opencode-meridian](https://github.com/ianjwhite99/opencode-meridian), or see the [reference plugin](examples/opencode-plugin/claude-max-headers.ts) to build your own.
+
+### Crush
+
+Add a provider to `~/.config/crush/crush.json`:
+
+```json
+{
+  "providers": {
+    "claude-max": {
+      "id": "claude-max",
+      "name": "Claude Max (Meridian)",
+      "type": "anthropic",
+      "base_url": "http://127.0.0.1:3456",
+      "api_key": "dummy",
+      "models": [
+        { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6 (1M)", "context_window": 1000000, "default_max_tokens": 64000, "can_reason": true, "supports_attachments": true },
+        { "id": "claude-opus-4-6",   "name": "Claude Opus 4.6 (1M)",   "context_window": 1000000, "default_max_tokens": 32768, "can_reason": true, "supports_attachments": true },
+        { "id": "claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5", "context_window": 200000, "default_max_tokens": 16384, "can_reason": true, "supports_attachments": true }
+      ]
+    }
+  }
+}
+```
+
+Then use Meridian models in Crush:
+
+```bash
+crush run --model claude-max/claude-sonnet-4-6 "refactor this function"
+crush --model claude-max/claude-opus-4-6       # interactive TUI
+```
+
+Crush is automatically detected from its `Charm-Crush/` User-Agent — no extra configuration needed. In `crush run` headless mode all tool operations (read, write, bash) execute automatically without prompting.
+
+### Droid (Factory AI)
+
+Droid connects via its BYOK (Bring Your Own Key) feature. This is a one-time setup.
+
+**1. Add Meridian as a custom model provider** in `~/.factory/settings.json`:
+
+```json
+{
+  "customModels": [
+    {
+      "model": "claude-sonnet-4-6",
+      "name": "Sonnet 4.6 (1M — Claude Max)",
+      "provider": "anthropic",
+      "baseUrl": "http://127.0.0.1:3456",
+      "apiKey": "x"
+    },
+    {
+      "model": "claude-opus-4-6",
+      "name": "Opus 4.6 (1M — Claude Max)",
+      "provider": "anthropic",
+      "baseUrl": "http://127.0.0.1:3456",
+      "apiKey": "x"
+    },
+    {
+      "model": "claude-haiku-4-5-20251001",
+      "name": "Haiku 4.5 (Claude Max)",
+      "provider": "anthropic",
+      "baseUrl": "http://127.0.0.1:3456",
+      "apiKey": "x"
+    }
+  ]
+}
+```
+
+The `apiKey` value doesn't matter — Meridian authenticates through your Claude Max session.
+
+**2. In the Droid TUI**, open the model selector (`/model`) and choose any `custom:claude-*` model.
+
+**How models map to Claude Max tiers:**
+
+| Model name in config | Claude Max tier |
+|---|---|
+| `claude-sonnet-4-6` | `sonnet[1m]` — Sonnet 4.6 with 1M context |
+| `claude-opus-4-6` | `opus[1m]` — Opus 4.6 with 1M context |
+| `claude-haiku-4-5-20251001` | `haiku` — Haiku 4.5 |
+| `claude-sonnet-4-5-*` | `sonnet` — Sonnet 4.5, no extended context |
+
+> **Note:** Droid automatically uses Meridian's internal tool execution mode regardless of the global `CLAUDE_PROXY_PASSTHROUGH` setting. No extra configuration needed.
+
+### Cline
+
+Cline CLI connects by setting `anthropicBaseUrl` in its config. This is a one-time setup.
+
+**1. Authenticate Cline with the Anthropic provider:**
+
+```bash
+cline auth --provider anthropic --apikey "dummy" --modelid "claude-sonnet-4-6"
+```
+
+**2. Add the proxy base URL** to `~/.cline/data/globalState.json`:
+
+```json
+{
+  "anthropicBaseUrl": "http://127.0.0.1:3456",
+  "actModeApiProvider": "anthropic",
+  "actModeApiModelId": "claude-sonnet-4-6"
+}
+```
+
+**3. Run Cline:**
+
+```bash
+cline --yolo "refactor the login function"                       # interactive
+cline --yolo --model claude-opus-4-6 "review this codebase"      # opus
+cline --yolo --model claude-haiku-4-5-20251001 "quick question"  # haiku (fastest)
+```
+
+No adapter or plugin needed — Cline uses the standard Anthropic SDK and falls through to the default adapter. All models (Sonnet 4.6, Opus 4.6, Haiku 4.5) route to their correct Claude Max tiers automatically.
+
+### Any Anthropic-compatible tool
+
+```bash
+export ANTHROPIC_API_KEY=x
+export ANTHROPIC_BASE_URL=http://127.0.0.1:3456
+# Then start your tool normally
+```
+
+## Tested Agents
+
+| Agent | Status | Plugin | Notes |
+|-------|--------|--------|-------|
+| [OpenCode](https://github.com/anomalyco/opencode) | ✅ Verified | [opencode-meridian](https://github.com/ianjwhite99/opencode-meridian) | Full tool support, session resume, streaming, subagents |
+| [Droid (Factory AI)](https://factory.ai/product/ide) | ✅ Verified | BYOK config (see setup above) | Full tool support, session resume, streaming; one-time BYOK setup |
+| [Crush](https://github.com/charmbracelet/crush) | ✅ Verified | Provider config (see setup above) | Full tool support, session resume, streaming, headless `crush run` |
+| [Cline](https://github.com/cline/cline) | ✅ Verified | Config (see setup above) | Full tool support, file read/write/edit, bash, session resume, all models |
+| [Continue](https://github.com/continuedev/continue) | 🔲 Untested | — | Should work — standard Anthropic API |
+| [Aider](https://github.com/paul-gauthier/aider) | 🔲 Untested | — | Should work — standard Anthropic API |
+
+Tested an agent or built a plugin? [Open an issue](https://github.com/rynfar/meridian/issues) and we'll add it.
+
+## Architecture
+
+Meridian is built as a modular proxy with clean separation of concerns:
+
+```
+src/proxy/
+├── server.ts              ← HTTP orchestration (routes, SSE streaming, concurrency)
+├── adapter.ts             ← AgentAdapter interface (extensibility point)
+├── adapters/
+│   ├── detect.ts          ← Agent detection from request headers
+│   ├── opencode.ts        ← OpenCode adapter
+│   └── droid.ts           ← Droid (Factory AI) adapter
+├── query.ts               ← SDK query options builder
+├── errors.ts              ← Error classification
+├── models.ts              ← Model mapping (sonnet/opus/haiku)
+├── tools.ts               ← Tool blocking lists
+├── messages.ts            ← Content normalization
+├── session/
+│   ├── lineage.ts         ← Per-message hashing, mutation classification (pure)
+│   ├── fingerprint.ts     ← Conversation fingerprinting
+│   └── cache.ts           ← LRU session caches
+├── sessionStore.ts        ← Cross-proxy file-based session persistence
+├── agentDefs.ts           ← Subagent definition extraction
+└── passthroughTools.ts    ← Tool forwarding mode
+```
+
+### Session Management
+
+Sessions map agent conversations to Claude SDK sessions. Meridian classifies every incoming request:
+
+| Classification | What Happened | Action |
+|---------------|---------------|--------|
+| **Continuation** | New messages appended | Resume SDK session |
+| **Compaction** | Agent summarized old messages | Resume (suffix preserved) |
+| **Undo** | User rolled back messages | Fork at rollback point |
+| **Diverged** | Completely different conversation | Start fresh |
+
+Sessions are stored in-memory (LRU) and persisted to `~/.cache/@rynfar/meridian/sessions.json` for cross-proxy resume.
+
+### Adding a New Agent
+
+Implement the `AgentAdapter` interface in `src/proxy/adapters/`:
+
+```typescript
+interface AgentAdapter {
+  // Required
+  getSessionId(c: Context): string | undefined
+  extractWorkingDirectory(body: any): string | undefined
+  normalizeContent(content: any): string
+  getBlockedBuiltinTools(): readonly string[]
+  getAgentIncompatibleTools(): readonly string[]
+  getMcpServerName(): string
+  getAllowedMcpTools(): readonly string[]
+
+  // Optional
+  buildSdkAgents?(body: any, mcpToolNames: readonly string[]): Record<string, any>
+  buildSdkHooks?(body: any, sdkAgents: Record<string, any>): any
+  buildSystemContextAddendum?(body: any, sdkAgents: Record<string, any>): string
+  usesPassthrough?(): boolean  // overrides CLAUDE_PROXY_PASSTHROUGH per-agent
+}
+```
+
+Agent detection is automatic from the `User-Agent` header:
+
+| User-Agent prefix | Adapter |
+|---|---|
+| `Charm-Crush/` | Crush |
+| `factory-cli/` | Droid |
+| *(anything else)* | OpenCode (default) |
+
+See [`adapters/detect.ts`](src/proxy/adapters/detect.ts) and [`adapters/opencode.ts`](src/proxy/adapters/opencode.ts) for reference.
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_PROXY_PORT` | `3456` | Port to listen on |
+| `CLAUDE_PROXY_HOST` | `127.0.0.1` | Host to bind to |
+| `CLAUDE_PROXY_PASSTHROUGH` | unset | Forward tool calls to client instead of executing |
+| `CLAUDE_PROXY_MAX_CONCURRENT` | `10` | Maximum concurrent SDK sessions |
+| `CLAUDE_PROXY_MAX_SESSIONS` | `1000` | In-memory LRU session cache size |
+| `CLAUDE_PROXY_MAX_STORED_SESSIONS` | `10000` | File-based session store capacity |
+| `CLAUDE_PROXY_WORKDIR` | `cwd()` | Default working directory for SDK |
+| `CLAUDE_PROXY_IDLE_TIMEOUT_SECONDS` | `120` | HTTP keep-alive timeout |
+| `CLAUDE_PROXY_TELEMETRY_SIZE` | `1000` | Telemetry ring buffer size |
+
+## Programmatic API
+
+Meridian can be used as a library for building agent plugins and integrations.
+
+```typescript
+import { startProxyServer } from "@rynfar/meridian"
+
+// Start a proxy instance
+const instance = await startProxyServer({
+  port: 3456,
+  host: "127.0.0.1",
+  silent: true,  // suppress console output
+})
+
+// instance.config  — resolved ProxyConfig
+// instance.server  — underlying http.Server
+
+// Shut down cleanly
+await instance.close()
+```
+
+### Session Header Contract
+
+For reliable session tracking, agents should send a session identifier via HTTP header. Without it, the proxy falls back to fingerprint-based matching (hashing the first user message + working directory), which is less reliable.
+
+| Header | Purpose |
+|--------|---------|
+| `x-opencode-session` | Maps agent conversations to Claude SDK sessions for resume, undo, and compaction |
+
+The proxy uses this header to maintain conversation continuity across requests. Plugin authors should inject it on every request to `/v1/messages`.
+
+### Plugin Architecture
+
+Meridian is the proxy. Plugins live in the agent's ecosystem.
+
+```
+┌──────────────┐         ┌──────────────┐         ┌──────────────┐
+│  Agent        │  HTTP   │  Meridian    │   SDK   │  Claude Max  │
+│  (OpenCode,   │────────▶│  Proxy       │────────▶│              │
+│   Crush, etc) │◀────────│              │◀────────│              │
+└──────────────┘         └──────────────┘         └──────────────┘
+       │
+       │ plugin injects headers,
+       │ manages proxy lifecycle
+       │
+┌──────────────┐
+│  Agent Plugin │
+│  (optional)   │
+└──────────────┘
+```
+
+A plugin's job is to:
+1. Start/stop a Meridian instance (`startProxyServer` / `instance.close()`)
+2. Inject session headers into outgoing requests
+3. Check proxy health (`GET /health`)
+
+See [`examples/opencode-plugin/`](examples/opencode-plugin/) for a reference implementation.
+
+## Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /` | Landing page (HTML) or status JSON (`Accept: application/json`) |
+| `POST /v1/messages` | Anthropic Messages API |
+| `POST /messages` | Alias for `/v1/messages` |
+| `GET /health` | Auth status, subscription type, mode |
+| `GET /telemetry` | Performance dashboard |
+| `GET /telemetry/requests` | Recent request metrics (JSON) |
+| `GET /telemetry/summary` | Aggregate statistics (JSON) |
+| `GET /telemetry/logs` | Diagnostic logs (JSON) |
+
+## Docker
+
+```bash
+docker run -v ~/.claude:/home/claude/.claude -p 3456:3456 meridian
+```
+
+Or with docker-compose:
+
+```bash
+docker compose up -d
+```
+
+## Testing
+
+```bash
+npm test          # 339 unit/integration tests (bun test)
+npm run build     # Build with bun + tsc
+```
+
+Three test tiers:
+
+| Tier | What | Speed |
+|------|------|-------|
+| Unit | Pure functions, no mocks | Fast |
+| Integration | HTTP layer with mocked SDK | Fast |
+| E2E | Real proxy + real Claude Max ([`E2E.md`](E2E.md)) | Manual |
+
+## FAQ
+
+**Is this allowed by Anthropic's terms?**
+Meridian uses the official Claude Code SDK — the same SDK Anthropic publishes and maintains for programmatic access. It authenticates through your existing Claude Max session using OAuth, not API keys. Nothing is modified, reverse-engineered, or bypassed.
+
+**How is this different from using an API key?**
+API keys are billed per token. Your Max subscription is a flat monthly fee with higher rate limits. Meridian lets you use that subscription from any compatible tool.
+
+**Does it work with Claude Pro?**
+It works with any Claude subscription that supports the Claude Code SDK. Max is recommended for the best rate limits.
+
+**What happens if my session expires?**
+The SDK handles token refresh automatically. If it can't refresh, Meridian returns a clear error telling you to run `claude login`.
+
+## Contributing
+
+Issues and PRs welcome. See [`ARCHITECTURE.md`](ARCHITECTURE.md) for module structure and dependency rules, [`CLAUDE.md`](CLAUDE.md) for coding guidelines, and [`E2E.md`](E2E.md) for end-to-end test procedures.
+
+## License
+
+MIT

package/assets/banner.svg

@@ -0,0 +1,46 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 400" fill="none">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#0f0b1a"/>
+      <stop offset="100%" stop-color="#1a1030"/>
+    </linearGradient>
+  </defs>
+
+  <rect width="1200" height="400" rx="16" fill="url(#bg)"/>
+
+  <!-- Subtle dot grid -->
+  <g opacity="0.05" fill="#a78bfa">
+    <circle cx="100" cy="100" r="1.5"/><circle cx="200" cy="100" r="1.5"/><circle cx="300" cy="100" r="1.5"/>
+    <circle cx="100" cy="200" r="1.5"/><circle cx="200" cy="200" r="1.5"/><circle cx="300" cy="200" r="1.5"/>
+    <circle cx="100" cy="300" r="1.5"/><circle cx="200" cy="300" r="1.5"/><circle cx="300" cy="300" r="1.5"/>
+    <circle cx="900" cy="100" r="1.5"/><circle cx="1000" cy="100" r="1.5"/><circle cx="1100" cy="100" r="1.5"/>
+    <circle cx="900" cy="200" r="1.5"/><circle cx="1000" cy="200" r="1.5"/><circle cx="1100" cy="200" r="1.5"/>
+    <circle cx="900" cy="300" r="1.5"/><circle cx="1000" cy="300" r="1.5"/><circle cx="1100" cy="300" r="1.5"/>
+  </g>
+
+  <!-- Logo mark — V2 full globe -->
+  <g transform="translate(380, 90)">
+    <!-- Meridian axis -->
+    <line x1="80" y1="8" x2="80" y2="192" stroke="#8B7CF6" stroke-width="5" stroke-linecap="round"/>
+    <!-- Latitude arcs — outer -->
+    <path d="M28 50 A60 60 0 0 1 132 50" fill="none" stroke="#C4B5FD" stroke-width="2.5" opacity="0.4"/>
+    <path d="M28 150 A60 60 0 0 0 132 150" fill="none" stroke="#C4B5FD" stroke-width="2.5" opacity="0.4"/>
+    <!-- Latitude arcs — inner -->
+    <path d="M38 78 A46 46 0 0 1 122 78" fill="none" stroke="#C4B5FD" stroke-width="1.5" opacity="0.2"/>
+    <path d="M38 122 A46 46 0 0 0 122 122" fill="none" stroke="#C4B5FD" stroke-width="1.5" opacity="0.2"/>
+    <!-- Poles -->
+    <circle cx="80" cy="8" r="8" fill="#C4B5FD"/>
+    <circle cx="80" cy="192" r="8" fill="#C4B5FD"/>
+    <!-- Center node -->
+    <circle cx="80" cy="100" r="8" fill="#8B7CF6"/>
+  </g>
+
+  <!-- Wordmark -->
+  <text x="540" y="195" font-family="Inter, -apple-system, 'SF Pro Display', 'Segoe UI', Helvetica, Arial, sans-serif" font-size="72" font-weight="700" fill="#e0e7ff" letter-spacing="10">MERIDIAN</text>
+
+  <!-- Tagline -->
+  <text x="543" y="240" font-family="Inter, -apple-system, 'SF Pro Display', 'Segoe UI', Helvetica, Arial, sans-serif" font-size="17" font-weight="600" fill="#8B7CF6" letter-spacing="3">HARNESS CLAUDE, YOUR WAY.</text>
+
+  <!-- Subtitle -->
+  <text x="543" y="278" font-family="Inter, -apple-system, 'SF Pro Display', 'Segoe UI', Helvetica, Arial, sans-serif" font-size="14" font-weight="300" fill="rgba(255,255,255,0.35)">Local Anthropic API powered by the Claude Code SDK</text>
+</svg>

package/assets/how-it-works.svg

@@ -0,0 +1,87 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 920 310" fill="none">
+  <style>
+    .title { font-family: 'Inter', -apple-system, sans-serif; font-size: 20px; font-weight: 700; fill: #C4B5FD; }
+    .box-label { font-family: 'Inter', -apple-system, sans-serif; font-size: 13px; font-weight: 600; fill: #F5F5F7; }
+    .box-sub { font-family: 'JetBrains Mono', 'SF Mono', monospace; font-size: 10px; fill: #8B7CF6; }
+    .box-detail { font-family: 'Inter', -apple-system, sans-serif; font-size: 10px; fill: #9898B4; }
+    .tag { font-family: 'Inter', -apple-system, sans-serif; font-size: 9px; font-weight: 600; fill: #5E5B72; letter-spacing: 1px; }
+    .step-num { font-family: 'Inter', -apple-system, sans-serif; font-size: 10px; font-weight: 700; }
+    .footer { font-family: 'Inter', -apple-system, sans-serif; font-size: 11px; fill: #5E5B72; }
+    .arrow-label { font-family: 'Inter', -apple-system, sans-serif; font-size: 9px; fill: #5E5B72; text-anchor: middle; }
+  </style>
+
+  <rect width="920" height="310" rx="16" fill="#13111C"/>
+  <rect x="0.5" y="0.5" width="919" height="309" rx="15.5" stroke="#2A2740" stroke-width="1" fill="none"/>
+
+  <text class="title" x="460" y="38" text-anchor="middle">How it works</text>
+
+  <!-- ═══ STEP 1: YOUR TOOLS ═══ -->
+  <rect x="32" y="64" width="156" height="140" rx="12" fill="#1C1930" stroke="#2A2740" stroke-width="1"/>
+  <rect x="44" y="54" width="18" height="18" rx="9" fill="#8B7CF6"/>
+  <text class="step-num" x="53" y="67" text-anchor="middle" fill="#13111C">1</text>
+  <text class="box-label" x="110" y="100" text-anchor="middle">Your tools</text>
+  <text class="box-detail" x="110" y="122" text-anchor="middle">OpenCode, Cline</text>
+  <text class="box-detail" x="110" y="136" text-anchor="middle">Continue, Crush, aider</text>
+  <text class="box-detail" x="110" y="150" text-anchor="middle">or any Anthropic client</text>
+  <text class="tag" x="110" y="192" text-anchor="middle">ANTHROPIC API FORMAT</text>
+
+  <!-- ═══ ARROWS 1 ↔ 2 ═══ -->
+  <line x1="200" y1="122" x2="250" y2="122" stroke="#8B7CF6" stroke-width="1.5"/>
+  <polygon points="248,118 256,122 248,126" fill="#8B7CF6"/>
+  <text class="arrow-label" x="226" y="114">request</text>
+  <line x1="250" y1="142" x2="200" y2="142" stroke="#3D3858" stroke-width="1"/>
+  <polygon points="202,138 194,142 202,146" fill="#3D3858"/>
+  <text class="arrow-label" x="226" y="162">response</text>
+
+  <!-- ═══ STEP 2: MERIDIAN ═══ -->
+  <rect x="264" y="64" width="156" height="140" rx="12" fill="#1C1930" stroke="#8B7CF6" stroke-width="1.5"/>
+  <rect x="276" y="54" width="18" height="18" rx="9" fill="#8B7CF6"/>
+  <text class="step-num" x="285" y="67" text-anchor="middle" fill="#13111C">2</text>
+  <text class="box-label" x="342" y="100" text-anchor="middle">Meridian</text>
+  <text class="box-sub" x="342" y="118" text-anchor="middle">localhost:3456</text>
+  <text class="box-detail" x="342" y="140" text-anchor="middle">Local proxy server</text>
+  <text class="box-detail" x="342" y="154" text-anchor="middle">Translates API calls</text>
+  <text class="box-detail" x="342" y="168" text-anchor="middle">to Claude Code SDK</text>
+  <text class="tag" x="342" y="192" text-anchor="middle">BRIDGES THE GAP</text>
+
+  <!-- ═══ ARROWS 2 ↔ 3 ═══ -->
+  <line x1="432" y1="122" x2="482" y2="122" stroke="#8B7CF6" stroke-width="1.5"/>
+  <polygon points="480,118 488,122 480,126" fill="#8B7CF6"/>
+  <text class="arrow-label" x="458" y="114">SDK call</text>
+  <line x1="482" y1="142" x2="432" y2="142" stroke="#3D3858" stroke-width="1"/>
+  <polygon points="434,138 426,142 434,146" fill="#3D3858"/>
+  <text class="arrow-label" x="458" y="162">result</text>
+
+  <!-- ═══ STEP 3: CLAUDE CODE SDK ═══ -->
+  <rect x="496" y="64" width="172" height="140" rx="12" fill="#1C1930" stroke="#2A2740" stroke-width="1"/>
+  <rect x="508" y="54" width="18" height="18" rx="9" fill="#8B7CF6"/>
+  <text class="step-num" x="517" y="67" text-anchor="middle" fill="#13111C">3</text>
+  <text class="box-label" x="582" y="100" text-anchor="middle">Claude Code SDK</text>
+  <text class="box-sub" x="582" y="118" text-anchor="middle">@anthropic-ai/claude-code</text>
+  <text class="box-detail" x="582" y="140" text-anchor="middle">Official Anthropic SDK</text>
+  <text class="box-detail" x="582" y="154" text-anchor="middle">Handles auth + sessions</text>
+  <text class="tag" x="582" y="192" text-anchor="middle">ANTHROPIC'S OWN SDK</text>
+
+  <!-- ═══ ARROWS 3 ↔ 4 ═══ -->
+  <line x1="680" y1="122" x2="726" y2="122" stroke="#8B7CF6" stroke-width="1.5"/>
+  <polygon points="724,118 732,122 724,126" fill="#8B7CF6"/>
+  <text class="arrow-label" x="704" y="114">API call</text>
+  <line x1="726" y1="142" x2="680" y2="142" stroke="#3D3858" stroke-width="1"/>
+  <polygon points="682,138 674,142 682,146" fill="#3D3858"/>
+  <text class="arrow-label" x="704" y="162">stream</text>
+
+  <!-- ═══ STEP 4: CLAUDE ═══ -->
+  <rect x="740" y="64" width="140" height="140" rx="12" fill="#1C1930" stroke="#2A2740" stroke-width="1"/>
+  <rect x="752" y="54" width="18" height="18" rx="9" fill="#8B7CF6"/>
+  <text class="step-num" x="761" y="67" text-anchor="middle" fill="#13111C">4</text>
+  <text class="box-label" x="810" y="100" text-anchor="middle">Claude</text>
+  <text class="box-sub" x="810" y="118" text-anchor="middle">api.anthropic.com</text>
+  <text class="box-detail" x="810" y="140" text-anchor="middle">Opus, Sonnet, Haiku</text>
+  <text class="box-detail" x="810" y="154" text-anchor="middle">Extended thinking</text>
+  <text class="tag" x="810" y="192" text-anchor="middle">YOUR SUBSCRIPTION</text>
+
+  <!-- ═══ BOTTOM ═══ -->
+  <line x1="60" y1="246" x2="860" y2="246" stroke="#2A2740" stroke-width="1"/>
+  <text class="footer" x="460" y="274" text-anchor="middle">No API keys needed — authenticates through your existing Claude Code / Max subscription</text>
+
+</svg>

package/assets/icon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="none">
+  <rect width="64" height="64" rx="14" fill="#1C1830"/>
+  <!-- Meridian axis -->
+  <line x1="32" y1="10" x2="32" y2="54" stroke="#8B7CF6" stroke-width="2.5" stroke-linecap="round"/>
+  <!-- Latitude arcs — outer -->
+  <path d="M16 20 A18 18 0 0 1 48 20" fill="none" stroke="#C4B5FD" stroke-width="1.2" opacity="0.4"/>
+  <path d="M16 44 A18 18 0 0 0 48 44" fill="none" stroke="#C4B5FD" stroke-width="1.2" opacity="0.4"/>
+  <!-- Latitude arcs — inner -->
+  <path d="M20 30 A14 14 0 0 1 44 30" fill="none" stroke="#C4B5FD" stroke-width="0.8" opacity="0.2"/>
+  <path d="M20 34 A14 14 0 0 0 44 34" fill="none" stroke="#C4B5FD" stroke-width="0.8" opacity="0.2"/>
+  <!-- Poles -->
+  <circle cx="32" cy="10" r="3.5" fill="#C4B5FD"/>
+  <circle cx="32" cy="54" r="3.5" fill="#C4B5FD"/>
+  <!-- Center node -->
+  <circle cx="32" cy="32" r="3" fill="#8B7CF6"/>
+</svg>

package/assets/logo.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="none">
+  <!-- Meridian axis -->
+  <line x1="256" y1="40" x2="256" y2="472" stroke="#8B7CF6" stroke-width="12" stroke-linecap="round"/>
+  <!-- Latitude arcs — outer pair -->
+  <path d="M110 130 A166 166 0 0 1 402 130" fill="none" stroke="#C4B5FD" stroke-width="7" opacity="0.4"/>
+  <path d="M110 382 A166 166 0 0 0 402 382" fill="none" stroke="#C4B5FD" stroke-width="7" opacity="0.4"/>
+  <!-- Latitude arcs — inner pair -->
+  <path d="M132 210 A136 136 0 0 1 380 210" fill="none" stroke="#C4B5FD" stroke-width="5" opacity="0.25"/>
+  <path d="M132 302 A136 136 0 0 0 380 302" fill="none" stroke="#C4B5FD" stroke-width="5" opacity="0.25"/>
+  <!-- Poles -->
+  <circle cx="256" cy="40" r="22" fill="#C4B5FD"/>
+  <circle cx="256" cy="472" r="22" fill="#C4B5FD"/>
+  <!-- Center node -->
+  <circle cx="256" cy="256" r="20" fill="#8B7CF6"/>
+</svg>