palaryn 0.1.0 → 0.3.0

package/README.md

@@ -2,325 +2,167 @@
 
 **A model-agnostic infrastructure layer that gives AI agents safe, auditable, and cost-controlled access to the outside world.**
 
----
-
-## Overview
-
-As AI agents increasingly interact with external services -- sending HTTP requests, posting to Slack, committing to Git, querying databases -- the central challenge shifts from model intelligence to **execution control**. Without guardrails, agents can leak secrets, overspend budgets, trigger unintended writes, and leave no trace of what happened. Enterprise procurement teams will not approve agent deployments that lack policy enforcement, cost controls, and auditable logs.
-
-Palaryn solves this by sitting as a single choke point between AI agents and the external world. Every tool call -- whether it targets a SaaS API, a database, a Git provider, Slack, or a headless browser -- is intercepted, evaluated against security policies, checked for sensitive data, metered against budgets, and logged immutably. The gateway is completely model-agnostic: it works with Claude, OpenAI, LangGraph, n8n, or any custom orchestrator. Integration requires nothing more than swapping an endpoint or embedding the SDK.
-
-The product is built around three pillars: **Security and DLP** to prevent data exfiltration and enforce least-privilege access; **Cost and Budget Controls** to stop runaway spending from agent loops and retries; and **Audit and Observability** to provide full traceability, replay capability, and compliance-ready export to SIEM and GRC platforms.
+Palaryn sits as a single choke point between AI agents and external services. Every tool call is intercepted, evaluated against security policies, checked for sensitive data, metered against budgets, and logged immutably. Works with Claude, OpenAI, LangGraph, n8n, or any custom orchestrator.
 
 ---
 
-## Quick Start
-
-### Prerequisites
-
-- Node.js 20+
-- npm
-
-### Install, Build, and Run
+## Install
 
 ```bash
-# Clone the repository
-git clone <repo-url> && cd palaryn
-
-# Install dependencies
-npm install
+curl -fsSL https://app.palaryn.com/install.sh | sh
+```
 
-# Build the TypeScript project
-npm run build
+Or install directly via npm:
 
-# Start the gateway
-npm start
+```bash
+npm install -g palaryn
 ```
 
-The gateway starts on **port 3000** by default. Verify it is running:
+Verify:
 
 ```bash
-curl http://localhost:3000/health
+palaryn --version
+palaryn --help
 ```
 
-### Execute Your First Tool Call
+---
+
+## Quick Start
 
-Send a tool call through the gateway using the default API key (`dev-key-001`):
+The fastest way to try Palaryn is a single curl call against the hosted gateway:
 
 ```bash
-curl -X POST http://localhost:3000/v1/tool/execute \
+curl -X POST https://app.palaryn.com/v1/tool/execute \
   -H "Content-Type: application/json" \
-  -H "X-API-Key: dev-key-001" \
+  -H "X-API-Key: YOUR_API_KEY" \
   -d '{
-    "tool_call_id": "tc-001",
-    "task_id": "task-001",
-    "actor": { "type": "agent", "id": "agent-1" },
-    "source": { "platform": "custom" },
-    "tool": { "name": "http.request", "capability": "read" },
-    "args": { "method": "GET", "url": "https://httpbin.org/get" }
+    "tool": "http.get",
+    "input": { "url": "https://api.github.com/repos/octocat/Hello-World" },
+    "taskId": "demo-task-1",
+    "actorId": "my-agent"
   }'
 ```
 
-The response includes the policy decision, DLP scan results, budget report, and the tool output -- all in a single `ToolResult` envelope.
+The response includes the policy decision, DLP scan results, budget report, and the tool output:
 
----
-
-## Project Structure
-
-```
-/
-├── src/
-│   ├── types/              # Canonical schemas (ToolCall, ToolResult, Policy, Events, Budget, Config)
-│   ├── policy/             # Policy engine (YAML DSL evaluation)
-│   ├── dlp/                # DLP scanner (secrets + PII detection, redaction)
-│   ├── budget/             # Budget manager (per-task/user/org budgets, hard stops)
-│   ├── audit/              # Audit logger (immutable event log, trace reconstruction)
-│   ├── executor/           # HTTP executor (retries, backoff, caching)
-│   ├── approval/           # Approval manager (JWT tokens, time-bound approvals)
-│   ├── server/             # Express gateway server + request orchestration
-│   ├── middleware/         # Auth and validation middleware
-│   ├── config/             # Default configuration + startup validation
-│   └── index.ts            # Package exports
-├── sdk/typescript/         # TypeScript SDK client
-│   └── src/
-│       ├── client.ts       # PalarynClient class with full API coverage
-│       └── index.ts        # SDK exports
-├── policy-packs/           # Pre-built YAML policy configurations
-│   ├── default.yaml        # Default safe (reads allowed, writes need approval)
-│   ├── dev_fast.yaml       # Development (permissive reads + writes)
-│   └── prod_strict.yaml    # Production strict (minimal permissions)
-├── tests/
-│   ├── unit/               # 1551 unit tests across 37 suites
-│   └── integration/        # 123 integration tests (65 run + 58 auto-skip without Redis/Postgres)
-├── examples/               # Usage examples
-├── docs/                   # Product documentation (13 markdown files)
-├── Dockerfile              # Multi-stage production Docker build
-├── docker-compose.yaml     # Docker Compose with dev and prod services
-├── tsconfig.json           # TypeScript configuration
-└── package.json
+```json
+{
+  "status": "ok",
+  "policy": { "decision": "allow", "rule_id": "Allow read operations" },
+  "dlp": { "detected": ["email"], "severity": "medium" },
+  "budget": { "estimated_cost_usd": 0.001, "remaining_cost_usd_task": 1.999 },
+  "output": { "http_status": 200, "body": { "full_name": "octocat/Hello-World", ... } },
+  "timing": { "duration_ms": 142 }
+}
 ```
 
 ---
 
-## Development
-
-### Commands
+## Integration Methods
 
-| Command | Description |
-|---|---|
-| `npm install` | Install dependencies |
-| `npm run build` | Compile TypeScript to `dist/` |
-| `npm start` | Start the gateway in production mode (requires build) |
-| `npm run dev` | Start the gateway in development mode (ts-node, no build needed) |
-| `npm test` | Run all 1616 tests (40 suites) |
-| `npm run test:unit` | Run 1551 unit tests (37 suites) |
-| `npm run test:integration` | Run 123 integration tests (65 + 58 auto-skip without services) |
-| `npm run lint` | Run ESLint on `src/` and `tests/` |
-| `npm run clean` | Remove `dist/` build output |
+Palaryn has a single pipeline (auth → rate limit → policy → DLP → budget → execute → audit) with multiple entry points:
 
-### Environment Variables
+| Method | Protocol | Code Change | Best For |
+|---|---|---|---|
+| **MCP Remote (OAuth)** | Streamable HTTP | Zero — one command | Claude Code, Cursor, any MCP client |
+| **MCP Local (stdio)** | JSON-RPC stdio | Zero — config only | Local development, offline |
+| **REST API** | HTTP POST | Minimal — send JSON | Any HTTP-capable system |
+| **SDK** (TypeScript / Python) | HTTP (wrapped) | Import + wrapper | Custom agents, orchestrators |
+| **HTTP Proxy** (`:3128`) | `HTTP_PROXY` env var | Zero | Containers, K8s, sandbox |
 
-| Variable | Default | Description |
-|---|---|---|
-| `PORT` | `3000` | HTTP server port |
-| `HOST` | `0.0.0.0` | HTTP server bind address |
-| `NODE_ENV` | `development` | Environment (development / production) |
-| `AUTH_ENABLED` | `true` | Enable/disable API key authentication |
-| `POLICY_PACK_PATH` | `./policy-packs/default.yaml` | Path to the active policy pack |
-| `AUDIT_LOG_DIR` | `./logs` | Directory for immutable audit logs |
-| `JWT_SECRET` | -- | Secret for signing approval JWT tokens |
-| `APPROVAL_SECRET` | -- | Secret for signing approval workflow tokens |
-| `REDIS_URL` | -- | Redis connection URL (e.g. `redis://redis:6379`) |
-| `DATABASE_URL` | -- | PostgreSQL connection URL |
+### MCP Remote (OAuth) — Recommended
 
-### Running in Development
+One command, OAuth login in the browser, done:
 
 ```bash
-# Start with hot-reload via ts-node
-npm run dev
+# Claude Code
+claude mcp add --transport http palaryn https://app.palaryn.com/mcp
 
-# Run tests in watch mode
-npx jest --watch
+# Cursor — add to .cursor/mcp.json
+{ "mcpServers": { "palaryn": { "url": "https://app.palaryn.com/mcp" } } }
 ```
 
----
+Authentication is fully automatic via OAuth 2.0 (dynamic client registration → browser login → consent → token exchange).
 
-## Testing
+### MCP Local (stdio)
 
-The test suite covers all core components with 1616 tests across 40 suites (unit + integration).
+Run the gateway locally as an MCP stdio server — no hosted service needed:
 
 ```bash
-# Run everything
-npm test
-
-# Run unit tests only (1551 tests across 37 suites)
-npm run test:unit
-
-# Run integration tests only (123 tests, 65 run + 58 auto-skip without Redis/Postgres)
-npm run test:integration
-
-# Run a specific test file
-npx jest tests/unit/policy.test.ts
+# Install + register in one step
+npm install -g palaryn
+claude mcp add palaryn -- palaryn mcp
 ```
 
-Unit test suites cover the policy engine, DLP scanner (regex, TruffleHog, composite backends), budget manager, audit logger, executor registry (HTTP, Slack, no-op), approval manager, rate limiter, all storage backends (memory, PostgreSQL, Redis), Prometheus metrics, OpenTelemetry tracing, JWT/OIDC auth with RBAC, admin dashboard, MCP bridge, anomaly detector, OPA/Rego engine, TypeScript SDK, SaaS routes, and full gateway features. Integration tests exercise the full gateway server end-to-end through the HTTP API, plus Redis/Postgres storage integration tests that auto-skip without running services.
-
----
-
-## Docker
-
-### Production
+Tools exposed: `http_request`, `http_get`, `http_post` — all routed through the full pipeline.
 
-Build and run the gateway with the multi-stage Dockerfile (Node.js 20 Alpine, non-root user):
+### REST API
 
 ```bash
-# Build and start with Docker Compose
-docker compose up gateway
-
-# Or build the image directly
-docker build -t palaryn .
-docker run -p 3000:3000 palaryn
+curl -X POST https://app.palaryn.com/v1/tool/execute \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -d '{
+    "tool": "http.post",
+    "input": { "url": "https://httpbin.org/post", "body": { "key": "value" } },
+    "taskId": "my-task",
+    "actorId": "my-agent"
+  }'
 ```
 
-The production image runs as a non-root `palaryn` user, includes a health check, and ships with the compiled JavaScript and policy packs only (no source or dev dependencies).
+The API also accepts the full ToolCall schema for advanced use cases (explicit `tool_call_id`, `actor`, `source`, `tool`, `args`).
 
-### Development
+### HTTP Forward Proxy
 
-The Compose file includes a `gateway-dev` service that mounts the source directory for live editing:
+Zero-code integration — set an environment variable and all outbound HTTP flows through Palaryn:
 
 ```bash
-docker compose --profile dev up gateway-dev
-```
-
-### Docker Compose Environment
-
-The `docker-compose.yaml` configures both services with sensible defaults. Policy packs are mounted as a read-only volume so you can edit them on the host and restart the gateway to pick up changes.
+export HTTP_PROXY=http://WORKSPACE_ID:API_KEY@gateway:3128
+export HTTPS_PROXY=http://WORKSPACE_ID:API_KEY@gateway:3128
 
-```yaml
-# Key environment defaults (override as needed)
-NODE_ENV=production
-PORT=3000
-AUTH_ENABLED=true
-POLICY_PACK_PATH=./policy-packs/default.yaml
+# All HTTP traffic now goes through Palaryn automatically
+curl https://api.github.com/repos/octocat/Hello-World
 ```
 
----
-
-## SDK
-
-### TypeScript SDK
-
-The TypeScript SDK (`sdk/typescript/`) provides a `PalarynClient` class for programmatic access to the gateway from any Node.js application or agent orchestrator.
-
-```typescript
-import { PalarynClient } from './sdk/typescript/src';
-
-// Set defaults once -- no need to repeat actor/platform on every call
-const client = new PalarynClient({
-  gateway_url: 'http://localhost:3000',
-  api_key: 'dev-key-001',
-  timeout_ms: 30000,
-  defaults: {
-    actor: { type: 'agent', id: 'my-agent' },
-    platform: 'langgraph',
-  },
-});
-
-// Convenience methods use defaults automatically
-const getResult = await client.httpGet('task-001', 'https://httpbin.org/get');
-const postResult = await client.httpPost('task-002', 'https://httpbin.org/post', { key: 'value' });
-
-// Override defaults per-call when needed
-const customResult = await client.httpGet('task-003', 'https://httpbin.org/get',
-  { type: 'user', id: 'admin-1' }, 'custom');
-
-// Execute a full tool call
-const result = await client.executeTool({
-  task_id: 'task-004',
-  actor: { type: 'agent', id: 'my-agent' },
-  source: { platform: 'langgraph' },
-  tool: { name: 'http.request', capability: 'read' },
-  args: { method: 'GET', url: 'https://api.github.com/repos/owner/repo' },
-});
-
-// Approval workflows
-const pending = await client.getPendingApprovals();
-await client.approve(approvalToken, 'approver-1');
-await client.deny(approvalToken, 'approver-1', 'Not authorized');
-
-// Observability
-const trace = await client.getTaskTrace('task-001');
-const policy = await client.getCurrentPolicy();
-```
-
-The client covers all gateway endpoints: `executeTool`, `approve`, `deny`, `getTaskTrace`, `getCurrentPolicy`, `validatePolicy`, `getPendingApprovals`, and `health`.
+Requires `PROXY_ENABLED=true` on the gateway.
 
 ---
 
-## Policy Packs
+## Self-Hosted Setup
 
-Policy packs are YAML files that define security rules, domain allowlists, and approval requirements. Three pre-built packs are included (see [`policy-packs/README.md`](policy-packs/README.md) for a detailed comparison):
+### Prerequisites
 
-| Pack | File | Description |
-|---|---|---|
-| **Default Safe** | `policy-packs/default.yaml` | SSRF protection, reads allowed, writes need approval, deny delete/admin |
-| **Dev Fast** | `policy-packs/dev_fast.yaml` | Permissive reads and writes for development |
-| **Prod Strict** | `policy-packs/prod_strict.yaml` | Minimal permissions for production workloads |
+- Node.js 20+
+- npm
 
-### Example Policy Rule
+### From Source
 
-```yaml
-rules:
-  - name: "Require approval for write operations"
-    description: "All write/delete/admin operations require human approval"
-    effect: REQUIRE_APPROVAL
-    priority: 20
-    conditions:
-      capabilities:
-        - "write"
-        - "delete"
-        - "admin"
-    approval:
-      scope: "team_lead"
-      ttl_seconds: 3600
-      reason: "Write/delete/admin operations require approval"
+```bash
+git clone https://github.com/palaryn-ai/palaryn.git && cd palaryn
+npm install
+npm run build
+npm start
 ```
 
-Set the active policy pack with the `POLICY_PACK_PATH` environment variable or at startup.
-
----
-
-## API Endpoints
+The gateway starts on **port 3000**. Verify: `curl http://localhost:3000/health`
 
-| Method | Endpoint | Description |
-|---|---|---|
-| `GET` | `/health` | Health check (status, version, timestamp -- always returns 200) |
-| `GET` | `/ready` | Readiness probe (returns 503 when unhealthy, for K8s) |
-| `GET` | `/metrics` | Prometheus metrics (no auth required) |
-| `POST` | `/v1/tool/execute` | Execute a tool call through the gateway |
-| `POST` | `/v1/tool/approve` | Approve or deny a pending action |
-| `GET` | `/v1/tasks/{task_id}/trace` | Retrieve the full trace for a task |
-| `GET` | `/v1/policies/current` | Get the active policy configuration |
-| `POST` | `/v1/policies/validate` | Validate a policy configuration before deployment |
-| `GET` | `/v1/config/active` | Get active configuration (admin-only, secrets redacted) |
-| `GET` | `/v1/approvals/pending` | List pending approval requests |
+### Docker Compose (Full Stack)
 
-All endpoints (except `/health`, `/ready`, `/metrics`) require authentication via the `X-API-Key` header when `AUTH_ENABLED=true`.
-
-### Error Responses
-
-All error responses follow a standardized format with machine-readable error codes and actionable hints:
+```bash
+# Gateway + Redis + Postgres + Jaeger
+docker compose up
 
-```json
-{
-  "error": "Rate limit exceeded for actor agent-1",
-  "error_code": "RATE_LIMIT_EXCEEDED",
-  "details": { "retry_after_ms": 5000 },
-  "hint": "Retry after the reset time or increase rate_limit config"
-}
+# With dev hot-reload
+docker compose --profile dev up
 ```
 
-Error codes: `VALIDATION_FAILED`, `AUTH_REQUIRED`, `AUTH_INVALID_KEY`, `AUTH_KEY_EXPIRED`, `AUTH_KEY_REVOKED`, `AUTH_INSUFFICIENT_PERMS`, `RATE_LIMIT_EXCEEDED`, `POLICY_DENIED`, `BUDGET_EXCEEDED`, `APPROVAL_REQUIRED`, `TOOL_EXECUTION_ERROR`, `INTERNAL_ERROR`, `NOT_FOUND`, `REQUEST_TIMEOUT`.
+### CLI Commands
+
+| Command | Description |
+|---|---|
+| `palaryn start` | Start the gateway server |
+| `palaryn mcp` | Start MCP stdio server |
+| `palaryn --help` | Show all options |
 
 ---
 
@@ -328,388 +170,201 @@ Error codes: `VALIDATION_FAILED`, `AUTH_REQUIRED`, `AUTH_INVALID_KEY`, `AUTH_KEY
 
 ### Security & DLP
 
-- **Least-privilege enforcement** -- Tools declare capabilities (read/write/delete/admin); policies gate access by capability level, with write operations requiring approval by default
-- **Destination allowlists** -- Domain-level allowlisting with no wildcards by default; IP literals blocked; optional path-level control
-- **DLP scanning** -- Entropy-based and pattern-based detection of secrets (API keys, JWTs, OAuth tokens) and PII (emails, phone numbers, addresses) in both request arguments and response outputs
-- **Redaction strategies** -- Mask (preserve shape), hash (stable for correlation), drop (remove entirely), or tokenize (replace with placeholders)
-- **Incident handling** -- Severity scoring based on destination, data type, and capability; automatic notifications via Slack or webhook; auto-quarantine of keys on severe exfiltration attempts
-- **Approval workflows** -- Asynchronous, signed, time-bound approvals for risky actions; approver scopes include team lead, security, and admin roles
-- **Compliance posture** -- SOC2-friendly logging, configurable data retention, encryption at rest and in transit
+- **Policy engine** — YAML DSL with allow/deny/require-approval rules, domain allowlists, capability-level gating (read/write/delete/admin)
+- **DLP scanning** — Entropy-based and pattern-based detection of secrets (API keys, JWTs, tokens) and PII (emails, phone numbers) in both requests and responses
+- **Redaction** — Mask, hash, drop, or tokenize sensitive data before it leaves the gateway
+- **Approval workflows** — Asynchronous, signed, time-bound approvals for risky operations
+- **SSRF protection** — DNS validation, IP pinning, private address blocking
+- **RBAC** — Role-based access control with per-workspace API keys and scoped permissions
 
 ### Cost & Budget Controls
 
-- **Granular budgets** -- Set spending limits per task, per user/agent, per workspace, and per tool type (e.g., higher limits for HTTP, tighter limits for browserless)
-- **Hard stops** -- Maximum steps per task, maximum retries per tool call, and maximum wall-clock time per task
-- **Response caching** -- Optional TTL-based caching of GET responses and deduplication of idempotent calls to reduce costs
-- **Anomaly detection** -- Rolling baselines per workspace and tool; alerts triggered when costs or retry rates exceed configurable thresholds
-- **Cost reporting** -- Dashboards showing top spenders, noisiest tools, and blocked actions; CSV/JSON export for finance teams
+- **Granular budgets** — Per-task, per-user, per-workspace, and per-tool spending limits with hard stops
+- **Rate limiting** — Configurable per-actor and per-workspace request rate limits
+- **Response caching** — TTL-based caching of GET responses and idempotent call deduplication
+- **Anomaly detection** — Rolling baselines with z-score anomaly flagging
 
 ### Audit & Observability
 
-- **Append-only event log** -- Immutable storage with optional WORM (Write Once Read Many) support for compliance
-- **Structured event schema** -- Events for every stage: `TOOL_CALL_RECEIVED`, `POLICY_DECIDED`, `DLP_SCANNED`, `BUDGET_CHECKED`, `TOOL_EXECUTED`, `TOOL_RESULT_RETURNED`, `APPROVAL_REQUESTED`, `INCIDENT_RAISED`, and more
-- **Correlation IDs** -- Full traceability via `task_id` and `tool_call_id` across the entire tool call lifecycle
-- **Replayable traces** -- Reconstruct any task timeline; optionally re-run tool calls in a sandbox environment (enterprise feature)
-- **OpenTelemetry integration** -- Spans per tool call; metrics for latency, error rate, block rate, approvals, and cost
-- **SIEM/GRC export** -- Webhook sinks, Splunk/Elastic format templates, and daily digest reports
-
-## Architecture Summary
-
-```
-Agents / Orchestrators
-  (Claude Code, LangGraph, n8n, custom control rooms, vendor platforms)
-            |
-            |  ToolCall: toolName + args + context
-            v
-+------------------------------+
-|          Palaryn              |
-+------------------------------+
-  |   |     |      |      |
-  |   |     |      |      +--> Audit Store (immutable logs)
-  |   |     |      +---------> Metrics / Tracing (OpenTelemetry)
-  |   |     +----------------> Policy Engine (OPA / custom YAML DSL)
-  |   +----------------------> DLP Engine (PII / secrets detection)
-  +--------------------------> Tool Executors (HTTP, Slack, Git, DB, Browserless)
-            |
-            v
-External World / Internal Services
-  (SaaS APIs, databases, Git providers, Slack/Teams, microservices)
-```
-
-**Core principle: all agent I/O goes through a single choke point.** Even if an agent is highly capable, it never gets direct, unmediated access to external services.
-
-### Runtime Path (per tool call)
-
-1. **Authenticate** the request (API key, JWT, or mTLS)
-2. **Normalize** the ToolCall into a canonical schema
-3. **Evaluate policy** -- allow, deny, transform, or require approval
-4. **Scan for DLP** -- detect secrets and PII in arguments and outputs; apply redaction
-5. **Check budget** -- verify per-task/user/org limits; enforce rate limiting
-6. **Execute** the tool call (with retries and backoff)
-7. **Log** an immutable trace event
-8. **Return** the ToolResult with metadata (cost, policy decision, warnings)
-
-### Design Non-Negotiables
-
-- Deterministic behavior: policy decides, the model cannot override
-- No bypass path
-- Clear audit trail for every action
-- Safe defaults: deny-by-default for unknown tools and domains
-
-## Integration Patterns
-
-Palaryn has a single pipeline (auth → rate limit → policy → DLP → budget → execute → audit) with **4 entry points**. Each environment picks the one that requires the least change.
-
-### Entry Points
-
-| Entry Point | Protocol | Code Change | Best For |
-|---|---|---|---|
-| **Direct API** (`POST /v1/tool/execute`) | HTTP | Minimal — send JSON | Any HTTP-capable system |
-| **SDK** (TypeScript / Python) | HTTP (wrapped) | Import + wrapper | Custom agents, orchestrators |
-| **Forward Proxy** (`:3128`) | `HTTP_PROXY` env var | Zero | Containers, K8s, sandbox |
-| **MCP Bridge** | JSON-RPC over stdio | Zero — config only | Claude Code, Cursor, IDE agents |
-| **MCP HTTP** (`/mcp`) | Streamable HTTP | Zero — URL only | Hosted/remote MCP server |
-
-### Agent Frameworks (LangGraph, CrewAI, custom)
-
-Use the Python or TypeScript SDK as a wrapper around tool calls:
-
-```python
-from palaryn import PalarynClient, Actor
-
-palaryn = PalarynClient(
-    gateway_url="http://palaryn:3000",
-    api_key="key-001",
-    default_actor=Actor(type="agent", id="research-agent"),
-    default_platform="langgraph",
-)
-
-# Instead of direct requests.get():
-def safe_http_tool(url: str, task_id: str) -> dict:
-    result = palaryn.http_get(task_id, url)
-    if result.status == "blocked":
-        return {"error": result.error}
-    return result.output
-```
-
-### Workflow Engines (n8n, Temporal, Airflow)
+- **Immutable audit log** — Append-only event log for every stage of the pipeline
+- **Full traceability** — Correlation via `task_id` and `tool_call_id` across the tool call lifecycle
+- **OpenTelemetry** — Spans per tool call, Prometheus metrics (latency, error rate, cost, tokens)
+- **Dashboard** — React SPA with real-time pipeline visualization, traces, budget charts, and settings
 
-**Option A — HTTP Node:** Point the HTTP Request node at `http://palaryn:3000/v1/tool/execute` with a ToolCall JSON body. Route on the `status` field in the response.
-
-**Option B — Forward Proxy:** Set `HTTP_PROXY=http://palaryn:3128` on the workflow container. All outbound HTTP flows through Palaryn automatically — zero workflow changes.
-
-### LLM Gateways (LiteLLM, Portkey)
-
-Palaryn **complements** LLM gateways — it does not replace them:
-
-```
-Agent → LLM Gateway (model routing, token budget) → LLM returns tool_call
-  → Orchestrator catches tool_call → Palaryn (policy, DLP, budget) → External API
-```
-
-- **LLM Gateway** = control over models (routing, cost, rate limiting on tokens)
-- **Palaryn** = control over tools (policy, DLP, budget on real-world actions)
-
-### Mobile & Web Apps (Android, iOS, React, Next.js)
-
-Client apps **never connect to Palaryn directly** — the backend mediates. The Palaryn API key stays server-side.
-
-```
-┌──────────────┐   HTTPS    ┌─────────────────┐  Palaryn SDK  ┌──────────┐     ┌──────────────┐
-│ Mobile / Web │ ────────→  │  Your Backend   │ ────────────→ │ Palaryn  │ ──→ │ External API │
-│ Client       │ ←───────── │  (Node/Kotlin)  │ ←──────────── │          │ ←── │              │
-└──────────────┘            └─────────────────┘               └──────────┘     └──────────────┘
-```
-
-### IDE Agents (Claude Code, Cursor)
+---
 
-Use the MCP Bridge — zero code changes, just configure the MCP server:
+## Project Structure
 
 ```
-┌──────────────┐   stdio JSON-RPC   ┌────────────────┐    ┌──────────────┐
-│  Claude Code │ ──────────────────→ │ MCP Bridge     │ ──→│ External API │
-│  / Cursor    │ ←─────────────────  │ (Palaryn)      │ ←──│              │
-└──────────────┘                     └────────────────┘    └──────────────┘
-```
-
-**Hosted (remote MCP server — no local build required):**
-
-```bash
-claude mcp add palaryn --url https://palaryn.com/mcp
+/
+├── src/
+│   ├── server/            # Express gateway server + request orchestration
+│   ├── mcp/               # MCP bridge (stdio + HTTP Streamable + OAuth 2.0 provider)
+│   ├── policy/            # Policy engine (YAML DSL evaluation)
+│   ├── dlp/               # DLP scanner (secrets + PII detection, redaction)
+│   ├── budget/            # Budget manager (per-task/user/org budgets, hard stops)
+│   ├── audit/             # Audit logger (immutable event log, trace reconstruction)
+│   ├── executor/          # HTTP executor (retries, backoff, caching, SSRF protection)
+│   ├── approval/          # Approval manager (JWT tokens, time-bound approvals)
+│   ├── auth/              # Authentication (login, session, OAuth providers)
+│   ├── saas/              # SaaS routes (workspaces, API keys, dashboard, events)
+│   ├── admin/             # Admin routes (config, API keys, policy management)
+│   ├── billing/           # Stripe billing (subscriptions, plan enforcement)
+│   ├── proxy/             # HTTP forward proxy (CONNECT tunneling)
+│   ├── middleware/        # Auth, validation, rate limiting, RBAC middleware
+│   ├── storage/           # Storage backends (memory, PostgreSQL, Redis)
+│   ├── metrics/           # Prometheus metrics
+│   ├── tracing/           # OpenTelemetry tracing
+│   ├── config/            # Default configuration + startup validation
+│   ├── types/             # Canonical schemas (ToolCall, ToolResult, Policy, Config)
+│   └── index.ts           # Package exports
+├── web/                   # React SPA frontend (dashboard, docs, onboarding)
+├── sdk/typescript/        # TypeScript SDK client
+├── sdk/python/            # Python SDK (sync + async clients)
+├── policy-packs/          # Pre-built YAML policy configurations
+├── tests/
+│   ├── unit/              # 2600+ unit tests across 67 test suites
+│   └── integration/       # Integration tests (auto-skip without Redis/Postgres)
+├── Dockerfile             # Multi-stage production Docker build
+├── docker-compose.yaml    # Docker Compose (Gateway + Redis + Postgres + Jaeger)
+└── package.json
 ```
 
-**Local (stdio MCP server):**
-
-```bash
-# Build first
-npm run build
-
-# Add as MCP server
-claude mcp add palaryn -- node /absolute/path/to/dist/src/mcp/server.js
+---
 
-# Or with a custom policy pack
-claude mcp add palaryn -e POLICY_PACK_PATH=./policy-packs/prod_strict.yaml -- node /absolute/path/to/dist/src/mcp/server.js
-```
+## Development
 
-**Project-level config (`.mcp.json` in project root):**
+### Commands
 
-```json
-{
-  "mcpServers": {
-    "palaryn": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["dist/src/mcp/server.js"],
-      "env": {
-        "POLICY_PACK_PATH": "./policy-packs/default.yaml"
-      }
-    }
-  }
-}
-```
+| Command | Description |
+|---|---|
+| `npm install` | Install dependencies |
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm start` | Start in production mode (requires build) |
+| `npm run dev` | Start in development mode (ts-node, no build needed) |
+| `npm test` | Run all tests |
+| `npm run test:unit` | Run unit tests |
+| `npm run test:integration` | Run integration tests |
 
-**Environment variables for MCP mode:**
+### Environment Variables
 
 | Variable | Default | Description |
 |---|---|---|
-| `PALARYN_MCP_WORKSPACE` | `ws-claude-code` | Workspace ID |
-| `PALARYN_MCP_ACTOR` | `claude-code` | Actor ID |
-| `PALARYN_MCP_PLATFORM` | `claude_code` | Platform identifier |
-| `POLICY_PACK_PATH` | `./policy-packs/default.yaml` | Policy pack to enforce |
-
-Tools exposed: `http_request`, `http_get`, `http_post` — all routed through the full Palaryn pipeline (policy, DLP, budget, rate limiting).
-
-### Kubernetes
+| `PORT` | `3000` | Server listen port |
+| `NODE_ENV` | `development` | Environment (development / production) |
+| `AUTH_ENABLED` | `true` | Enable authentication |
+| `POLICY_PACK_PATH` | `./policy-packs/default.yaml` | Active policy pack |
+| `AUDIT_LOG_DIR` | `./logs` | Audit log directory |
+| `JWT_SECRET` | (required in prod) | JWT signing secret |
+| `APPROVAL_SECRET` | (required in prod) | Approval workflow secret |
+| `OAUTH_SESSION_SECRET` | (required in prod) | Session cookie secret |
+| `REDIS_URL` | -- | Redis connection URL |
+| `DATABASE_URL` | -- | PostgreSQL connection URL |
+| `PROXY_ENABLED` | `false` | Enable forward proxy on port 3128 |
+| `FRONTEND_ENABLED` | `false` | Serve React SPA frontend |
+| `MCP_OAUTH_ENABLED` | `false` | Enable MCP OAuth 2.0 provider |
+| `MCP_OAUTH_BASE_URL` | -- | Base URL for MCP OAuth |
+| `STRIPE_SECRET_KEY` | -- | Stripe API key for billing |
 
-Three deployment models:
+---
 
-**Sidecar proxy (per-pod):** One Palaryn container per agent pod. Agent sets `HTTP_PROXY=http://localhost:3128`. Implicit auth via `PALARYN_WORKSPACE_ID` / `PALARYN_ACTOR_ID` env vars. Zero code changes.
+## Policy Packs
 
-**Shared gateway (centralized):** One Palaryn instance, multiple agents with separate API keys and workspaces. Agents use the SDK or Direct API.
+Policy packs are YAML files that define security rules, domain allowlists, and approval requirements:
 
-**Network-enforced:** K8s NetworkPolicy blocks direct egress from agent pods, forcing all traffic through the Palaryn proxy. Agents **cannot** bypass policy enforcement.
+| Pack | File | Description |
+|---|---|---|
+| **Default Safe** | `policy-packs/default.yaml` | Reads allowed, writes need approval, deny delete/admin |
+| **Dev Fast** | `policy-packs/dev_fast.yaml` | Permissive reads and writes for development |
+| **Prod Strict** | `policy-packs/prod_strict.yaml` | Minimal permissions for production |
 
 ```yaml
-# Block direct egress — force proxy
-apiVersion: networking.k8s.io/v1
-kind: NetworkPolicy
-spec:
-  podSelector:
-    matchLabels: { role: agent }
-  policyTypes: [Egress]
-  egress:
-    - to:
-        - podSelector:
-            matchLabels: { app: palaryn }
-      ports:
-        - port: 3128
+rules:
+  - name: "Require approval for write operations"
+    effect: REQUIRE_APPROVAL
+    priority: 20
+    conditions:
+      capabilities: ["write", "delete", "admin"]
+    approval:
+      scope: "team_lead"
+      ttl_seconds: 3600
 ```
 
-### Quick Reference
-
-| Environment | Method | Code Change |
-|---|---|---|
-| **LangGraph / CrewAI / custom agent** | Python/TS SDK | Minimal — wrapper on tool calls |
-| **n8n / Temporal / Airflow** | HTTP Node → API or `HTTP_PROXY` | Zero (proxy) or URL change (API) |
-| **Claude Code / Cursor** | MCP Bridge | Zero — configure MCP server |
-| **Android / iOS app** | Backend → SDK | Backend mediates |
-| **Web app (React / Next.js)** | API Route → SDK | Backend mediates |
-| **K8s microservices** | Sidecar proxy + NetworkPolicy | Zero — env var + NetworkPolicy |
-| **LLM Gateway (LiteLLM / Portkey)** | SDK in orchestrator | Orchestrator delegates tool calls |
-| **Bare metal / VM** | `HTTP_PROXY` env var | Zero — global env var |
-| **Serverless (Lambda)** | SDK in handler | Minimal — import + wrapper |
-
-### Integration Kit
-
-| Component | Path | Status |
-|---|---|---|
-| TypeScript SDK | `sdk/typescript/` | Implemented |
-| Python SDK | `sdk/python/` | Implemented (sync + async clients, 102 tests) |
-| Policy Packs | `policy-packs/` | Implemented (3 packs: default, dev, prod) |
-| Usage Examples | `examples/` | Implemented |
-| MCP Bridge | `src/mcp/` | Implemented (stdio + HTTP Streamable transport) |
-| n8n Node | `n8n-node/` | Planned |
-
-## Canonical Schemas
-
-### ToolCall
+---
 
-Every tool call is normalized into a canonical format containing:
+## API Endpoints
 
-- **Actor** -- Agent, user, or system identity with display name
-- **Source** -- Platform identifier (e.g., `langgraph`, `claude_code`, `n8n`, `custom`) and session ID
-- **Tool** -- Name, version, and capability level (`read`, `write`, `delete`, `admin`)
-- **Args** -- Tool-specific arguments (method, URL, headers, body, query, etc.)
-- **Constraints** -- Per-call cost limit and timeout
-- **Context** -- Purpose description and classification labels
+| Method | Endpoint | Description |
+|---|---|---|
+| `POST` | `/v1/tool/execute` | Execute a tool call through the gateway |
+| `POST` | `/v1/tool/approve` | Approve or deny a pending action |
+| `GET` | `/v1/tasks/{id}/trace` | Retrieve the full trace for a task |
+| `GET` | `/v1/policies/current` | Get the active policy configuration |
+| `POST` | `/v1/policies/validate` | Validate a policy before deployment |
+| `GET` | `/v1/approvals/pending` | List pending approval requests |
+| `POST` | `/mcp` | MCP Streamable HTTP endpoint (OAuth 2.0) |
+| `GET` | `/health` | Health check |
+| `GET` | `/ready` | Readiness probe (for K8s) |
+| `GET` | `/metrics` | Prometheus metrics |
 
-### ToolResult
+All endpoints (except `/health`, `/ready`, `/metrics`) require authentication via `X-API-Key` header or Bearer token.
 
-Every response includes:
+---
 
-- **Policy decision** -- Allow/deny/transform/require_approval with the matched rule ID and reasons
-- **DLP report** -- Detected items, redactions applied, and severity
-- **Budget report** -- Estimated cost, spent-to-date for the task, and remaining budget
-- **Output** -- The actual tool response (with redactions applied)
-- **Timing** -- Start timestamp and duration in milliseconds
+## Architecture
 
-### Authentication
+```
+Agents / Orchestrators
+  (Claude Code, Cursor, LangGraph, n8n, custom)
+            │
+            │  MCP / REST API / HTTP Proxy
+            ▼
+┌──────────────────────────────────────┐
+│            Palaryn Gateway           │
+│  ┌──────┬───────┬─────┬──────┬─────┐│
+│  │ Auth │ Rate  │ DLP │Policy│Budgt││
+│  │      │ Limit │     │      │     ││
+│  └──┬───┴───┬───┴──┬──┴───┬──┴──┬──┘│
+│     │       │      │      │     │   │
+│     ▼       ▼      ▼      ▼     ▼   │
+│  Executor  Audit  Metrics Traces    │
+└──────────────┬───────────────────────┘
+               │
+               ▼
+  External World / Internal Services
+  (SaaS APIs, databases, Git, Slack)
+```
 
-- **API keys** for quick-start and development
-- **mTLS + JWT** for enterprise deployments
-- **Per-workspace keys** with scoped permissions
-- **Idempotency** via required `tool_call_id` (UUID) for safe retry deduplication
+Every tool call flows through: **Auth → Rate Limit → DLP (args) → Policy → Budget → Execute → DLP (output) → Audit → Return**.
 
-## Deployment
+---
 
-### Tech Stack
+## Tech Stack
 
 | Layer | Technology |
 |---|---|
-| **Gateway** | Node.js / TypeScript with Express 5 |
-| **Policy DSL** | YAML with JSON Schema validation + OPA/Rego engine (remote + local eval) |
-| **Immutable logs** | File-based append-only log + in-memory event store for trace queries |
-| **Storage** | In-memory (dev), PostgreSQL (production), Redis (rate limiting + caching) |
-| **Auth** | API keys + JWT/OIDC + RBAC with role-based permissions |
-| **Observability** | OpenTelemetry tracing (OTLP HTTP exporter) + Prometheus metrics (9 metric types) |
-| **Anomaly detection** | Rolling baseline statistics with z-score anomaly flagging |
-| **MCP** | JSON-RPC 2.0 over stdio bridge + HTTP Streamable transport (`/mcp`) |
-| **SDKs** | TypeScript SDK + Python SDK (sync + async) |
-| **Deployment** | Docker / Docker Compose (Gateway + Redis + Postgres + Jaeger) |
-
-### Deployment Models
-
-**SaaS (Multi-Tenant)**
-- Kubernetes-based with per-tenant keys and logical isolation
-- Optional dedicated clusters for large customers
-
-**Enterprise (Single-Tenant)**
-- Helm chart deployment
-- Bring-your-own storage (PostgreSQL, S3)
-- Private networking with mTLS
-
-### Security Hardening
-
-- Encryption at rest via KMS
-- mTLS for all executor communication
-- Secret-less deployments using OIDC federation to cloud providers
-- WAF and rate limiting at the edge
-- Configurable data retention policies
-- Non-root Docker container with minimal Alpine image
-
-### SLOs
-
-- **Latency overhead**: p95 < 50 ms for policy + DLP evaluation (excluding downstream tool latency)
-- **Availability**: 99.9%+
-
-### Rollout Strategy
+| **Gateway** | Node.js / TypeScript, Express |
+| **Frontend** | React SPA (Vite, Tailwind, Recharts) |
+| **Policy DSL** | YAML with OPA/Rego engine |
+| **Storage** | In-memory (dev), PostgreSQL (prod), Redis (rate limiting + caching) |
+| **Auth** | API keys, JWT/OIDC, OAuth 2.0 (MCP), RBAC |
+| **Observability** | OpenTelemetry (OTLP), Prometheus metrics |
+| **MCP** | JSON-RPC 2.0 over stdio + HTTP Streamable transport |
+| **SDKs** | TypeScript SDK, Python SDK (sync + async) |
+| **Billing** | Stripe (subscriptions, usage metering) |
+| **Deployment** | Docker Compose (Gateway + Redis + Postgres + Caddy) |
 
-1. **Shadow mode** -- Log-only with no blocking for the first week
-2. **Enforce mode** -- Start by denying only high-risk actions
-3. **Full mode** -- Enable approvals, budgets, and transformations
-
-## Pricing Tiers
-
-| | Free / Dev | Pro | Business | Enterprise |
-|---|---|---|---|---|
-| **Tool calls / month** | 50,000 | 1,000,000 | 10,000,000 | Unlimited / negotiated |
-| **Log retention** | 7 days | 30 days | 180 days | Custom + WORM |
-| **Security** | Basic allowlists + secrets scan | Approvals + budgets + basic anomaly | SIEM export + SSO (SAML/OIDC) + policy packs | Custom policy engine (OPA) + private deployment |
-| **Support** | Community | Standard | Priority | Dedicated + SLAs |
-| **Price** | Free | $99 -- $299 / mo | $999 -- $2,999 / mo | $25,000+ / year |
-
-### Add-ons
-
-- ClickHouse analytics for high-volume event querying
-- Sandbox replay runner for post-incident investigation
-- Advanced DLP with NER and custom dictionaries
-- Browserless executor for headless browser automation
-
-Pricing is usage-based (per tool call) rather than seat-based, directly mapping to the real work agents perform.
-
-## Roadmap Highlights
-
-### MVP (2-3 weeks)
-
-- HTTP executor with domain allowlists and secrets detection
-- Structured audit log with immutable storage
-- Task and workspace budgets
-- Simple web-based approval workflow
-- MCP router and SDK adapters
-
-### v1 (6-8 weeks)
-
-- PII detection with configurable redaction strategies
-- SIEM export (Splunk, Elastic)
-- Cost and governance dashboard (top spenders, blocked actions)
-- Pre-built policy packs for dev, prod, and ads workflows
-
-### v2 (3-6 months)
-
-- Anomaly detection v2 with advanced baselines
-- Replay sandbox for post-mortem analysis
-- Additional executors: Git, read-only database, browserless
-- Policy simulator with diff and dry-run capabilities
+---
 
 ## Documentation
 
-The full product documentation is available in the [`docs/`](docs/) directory:
+Full documentation is available at [app.palaryn.com/docs](https://app.palaryn.com/docs) and in the [`docs/`](docs/) directory.
 
 | Document | Description |
 |---|---|
-| [00_overview.md](docs/00_overview.md) | Product overview, value proposition, and adoption modes |
-| [01_market_problem.md](docs/01_market_problem.md) | Market problem analysis and target buyers |
-| [02_architecture.md](docs/02_architecture.md) | System architecture, runtime path, and deployment model |
-| [03_core_components.md](docs/03_core_components.md) | Core components: Policy Engine, DLP, Budgeting, Executors, Audit |
-| [04_api_contracts.md](docs/04_api_contracts.md) | Canonical ToolCall/ToolResult schemas and API endpoints |
-| [05_policy_engine.md](docs/05_policy_engine.md) | Policy engine design, decision model, and rule examples |
-| [06_security_dlp.md](docs/06_security_dlp.md) | Security threat model, DLP scanning, redaction, and compliance |
-| [07_cost_budgeting.md](docs/07_cost_budgeting.md) | Cost tracking, budgets, hard stops, and anomaly detection |
-| [08_audit_observability.md](docs/08_audit_observability.md) | Audit log schema, OpenTelemetry, replay, and SIEM export |
-| [09_adapters_integrations.md](docs/09_adapters_integrations.md) | Adapter types and integration kit deliverables |
-| [10_deployment_prod.md](docs/10_deployment_prod.md) | Tech stack, deployment models, security hardening, and SLOs |
-| [11_pricing_packaging.md](docs/11_pricing_packaging.md) | Pricing tiers, add-ons, and packaging strategy |
-| [12_roadmap_gtm.md](docs/12_roadmap_gtm.md) | Roadmap (MVP through v2), GTM strategy, and positioning |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Full technical architecture |
+| [INDEX.md](docs/INDEX.md) | Product documentation index |
+| [constraints.md](constraints.md) | Coding patterns and invariants |
 
 ---