{"owner":"Helicone","repo":"helicone","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"skills":{"AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\n- Monorepo managed by Yarn workspaces (Node >= 20).\n- Apps: `web/` (Next.js app), `valhalla/jawn/` (TypeScript API), `worker/` (Cloudflare Worker), `bifrost/` (site/docs).\n- Shared code: `packages/*` (cost, filters, llm-mapper, prompts), `shared/`, `sdk/`.\n- Infra & data: `supabase/`, `clickhouse/`, `docker/`, `env/`, `examples/`.\n- Tests: `packages/**/__tests__/`, `worker` (Vitest), `valhalla/jawn` (Jest), Python integration in `tests/`.\n- Autogenerated types (do not manually edit these files):\n - valhalla/jawn/src/tsoa-build/\n - web/lib/clients/jawnTypes/\n - bifrost/lib/clients/jawnTypes/\n - worker/supabase/database.types.ts\n - web/db/database.types.ts\n - helicone-cron/src/db/database.types.ts\n - valhalla/jawn/src/lib/db/database.types.ts\n\n## Build, Test, and Development Commands\n- Install deps: `yarn`\n- Lint all: `yarn lint` • Fix: `yarn lint:fix`\n- Web app: `yarn workspace helicone dev:local` | build: `yarn workspace helicone build`\n- Bifrost: `yarn workspace bifrost dev`\n- API (Valhalla/Jawn): `yarn workspace helicone-api dev` | build: `yarn workspace helicone-api build`\n- Worker: `yarn workspace helicone-worker dev` | test: `yarn workspace helicone-worker test`\n- Packages tests: run Jest in `packages/` (e.g., `npx jest` or `npx jest __tests__/cost/registrySnapshots.test.ts`)\n- Python integration: `python tests/python_integration_tests.py`\n\n## Coding Style & Naming Conventions\n- TypeScript/React, 2‑space indent, semicolons default; format with Prettier.\n- ESLint required; fix warnings before PRs.\n- React components `PascalCase.tsx`; utilities `camelCase.ts`; tests `*.test.ts` in `__tests__/`.\n- TailwindCSS in `web/`; rely on `prettier-plugin-tailwindcss` for class ordering.\n\n## Testing Guidelines\n- Frameworks: Jest (web, packages, API), Vitest (worker), Python integration tests.\n- Add unit tests with meaningful assertions; snapshot tests where appropriate (packages/cost).\n- Run affected workspace tests locally before opening a PR.\n\n## Commit & Pull Request Guidelines\n- Use Conventional Commits where possible: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`. Example: `feat(web): add usage chart (#1234)`.\n- PRs include: clear description, linked issues, screenshots for UI changes, and notes on migrations or env updates.\n- Checks must pass: lint, build for touched workspaces, and relevant tests.\n\n## Security & Configuration Tips\n- Never commit secrets. Use `.env.example` as a template.\n- Web envs: `vercel env pull` or maintain `.env.local` locally.\n- Worker secrets: `wrangler secret put `.\n- Database/config: see `supabase/`, `clickhouse/`, and `docker/` for local setup.\n\n## Agent-Specific Notes\n- Scope changes to the smallest relevant workspace.\n- Prefer `yarn workspace `; avoid modifying unrelated packages.\n- Keep code style consistent; run `yarn lint` and add targeted tests.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nHelicone is an open-source LLM observability platform that provides monitoring, analytics, and management tools for Large Language Model applications. The project is structured as a monorepo with multiple services.\n\n## Core Architecture\n\n### Services\n\n- **Web (Frontend)**: Next.js dashboard app at `/web`\n- **Jawn (Backend)**: Express.js API server at `/valhalla/jawn`\n- **Worker (Proxy)**: Cloudflare Workers for LLM request interception at `/worker`\n- **AI Gateway**: Rust-based LLM proxy/router at `/aigateway`\n- **Bifrost**: Marketing/landing page at `/bifrost`\n\n### Data Flow\n\n1. Client → Helicone Proxy → LLM Provider\n2. Proxy sends logs to Upstash queue → Jawn processes → Databases\n3. PostgreSQL for app data, ClickHouse for analytics, MinIO for object storage\n\n## Development Commands\n\n### Main Development\n\n```bash\n# Start local development (requires Docker)\n./helicone-compose.sh helicone up\n\n# Web development\ncd web && yarn dev:better-auth # With better-auth\ncd web && yarn dev:local # Local development\n\n# Backend development\ncd valhalla/jawn && yarn dev\n\n# AI Gateway (Rust)\ncd aigateway && cargo run\n\n# Worker development (different types)\ncd worker && npx wrangler dev --local --var WORKER_TYPE:OPENAI_PROXY --port 8787\n```\n\n### Build & Test\n\n```bash\n# Web\ncd web && yarn build && yarn test && yarn lint\n\n# Backend\ncd valhalla/jawn && yarn build && yarn test:jawn\n\n# AI Gateway\ncd aigateway && cargo build && cargo test --tests --all-features && cargo clippy\n```\n\n## Code Style Guidelines\n\n### Frontend (Web)\n\n- Use TypeScript with strict typing\n- Follow design system with semantic components from `/web/components/ui/typography`\n- Use Tailwind utility classes for styling with semantic color tokens\n- Icons from `lucide-react` with consistent sizing via `size` prop\n- Layout with flexbox + gap, avoid margins for spacing\n\n### Component Patterns\n\n```tsx\n// Typography components\nimport { H1, H2, P, Small, Muted } from \"@/components/ui/typography\"\n\n// Colors - use semantic tokens\nclassName=\"bg-background text-foreground border-border\"\n\n// Layout - use flex + gap\n
\n
\n```\n\n### Backend (Jawn)\n\n- Controllers in `/valhalla/jawn/src/controllers/` use TSOA decorators\n- Managers in `/valhalla/jawn/src/managers/` extend `BaseManager`\n- Use `JawnAuthenticatedRequest` and return `Result`\n- Frontend hooks use TanStack Query with `useJawnClient()`\n\n### Database\n\n- PostgreSQL with snake_case naming\n- ClickHouse for analytics\n- Proper RLS policies for security\n\n## Tech Stack\n\n### Frontend\n\n- Next.js 14 with React 18.3.1\n- TypeScript, Tailwind CSS, Radix UI\n- Zustand for state management\n- TanStack Query for server state\n\n### Backend\n\n- Express.js with TSOA\n- Supabase (PostgreSQL) + ClickHouse\n- Upstash Redis for queuing\n- Better Auth for authentication\n\n### Infrastructure\n\n- Cloudflare Workers for proxying\n- Docker for local development\n- MinIO for object storage\n\n## Key Directories\n\n```\n/web/ # Next.js frontend\n/valhalla/jawn/ # Express.js backend\n/worker/ # Cloudflare Workers\n/aigateway/ # Rust LLM proxy\n/bifrost/ # Marketing site\n/packages/ # Shared packages\n ├── cost/ # Cost calculations\n ├── llm-mapper/ # Provider mappings\n └── prompts/ # Prompt management\n/supabase/ # Database migrations\n/clickhouse/ # Analytics DB setup\n```\n\n## Development Workflow\n\n1. Start infrastructure with Docker: `./helicone-compose.sh helicone up`\n2. Start web: `cd web && yarn dev:better-auth`\n3. Start backend: `cd valhalla/jawn && yarn dev`\n4. Access at `http://localhost:3000`\n\n## Testing\n\n- Web: `yarn test` (Jest)\n- Backend: `yarn test:jawn`\n- AI Gateway: `cargo test --tests --all-features`\n- E2E tests available in Python\n\n## Common Tasks\n\n### Adding New Features\n\n1. Design API in Jawn controller with TSOA\n2. Implement manager with database operations\n3. Create frontend hooks with TanStack Query\n4. Follow design system for UI components\n\n### Database Changes\n\n1. Add migrations in `/supabase/migrations/`\n2. Update types and managers accordingly\n3. Test with proper RLS policies\n\n### Style Changes\n\n- Use semantic color tokens, never raw colors\n- Follow typography component system\n- Use flexbox + gap for layouts\n- Test in both light and dark modes\n- when making changes to /packages run the tests npx jest **tests**/ in /packages to make sure nothing else is broken\n\n### TypeScript Type Changes\n\nWhen modifying TypeScript types (interfaces, type aliases, union types):\n\n1. **Run type checking before committing**: `npx tsc --noEmit` in the relevant package to catch type errors (Jest tests alone won't catch all type mismatches)\n2. **Search for related types**: When updating union types (e.g., `\"low\" | \"medium\" | \"high\"`), grep for similar patterns to ensure all related types are updated:\n ```bash\n grep -r \"thinkingLevel\" packages/ # Find all usages of similar type\n ```\n3. **Check cross-package dependencies**: Types in `/packages/` are often used across multiple packages (llm-mapper, prompts, cost). Verify changes don't break consumers.\n4. **Run the full build**: For `/packages/` changes, run `cd web && yarn build` or check Vercel preview to catch type errors across the monorepo.\n\n# Helicone Design System Guidelines\n\n## Core Principles\n\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n

Page Title

\n

Regular paragraph

\nHelper text\nSecondary text\n\n// ❌ Don't do this\n

Raw Styles

\n

Overriding Typography

\n

Wrong Size

\n```\n\n### Available Components\n\n```tsx\n// Headings\n

// Main page titles\n // Hero sections\n

// Section headers\n

// Subsection headers\n

// Card titles\n\n// Body Text\n

// Regular paragraphs\n // Introduction text\n // Emphasized body text\n // Helper text\n // Secondary text\n\n// Special Elements\n

// Quotations\n // Inline code\n // Unordered lists\n\n// Table Elements\n // Table headers\n // Table cells\n```\n\n### Typography Scale\n\n| Component | Size | Line Height | Weight | Usage |\n| --------- | ------------------------------------ | ----------------- | --------- | ------------------ |\n| H1 | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold | Main page titles |\n| H1Large | text-5xl (48px) | leading-10 (40px) | extrabold | Hero sections |\n| H2 | text-3xl (30px) | leading-9 (36px) | semibold | Section headers |\n| H3 | text-2xl (24px) | leading-8 (32px) | semibold | Subsection headers |\n| H4 | text-xl (20px) | leading-7 (28px) | semibold | Card titles |\n| Lead | text-xl (20px) | leading-7 (28px) | normal | Introduction text |\n| P | text-base (16px) | leading-7 (28px) | normal | Body text |\n| Small | text-sm (14px) | leading-4 (16px) | medium | Helper text |\n| Muted | text-sm (14px) | leading-none | normal | Secondary text |\n\n## Color System\n\n### Usage Patterns\n\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n\n```tsx\n/* Text Colors */\ntext - foreground; // Primary text\ntext - muted - foreground; // Secondary text\ntext - accent - foreground; // Accent text\n\n/* Background Colors */\nbg - background; // Page background\nbg - card; // Card background\nbg - muted; // Muted background\n\n/* Border Colors */\nborder - border; // Default borders\nborder - input; // Form inputs\nring - ring; // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n\n```tsx\n/* Light Mode */\nbg - primary; // #0EA5E9 (sky-500)\ntext - primary - foreground; // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg - primary; // #0284C7 (sky-600)\ntext - primary - foreground; // #083344 (sky-950)\n```\n\n### Background Colors\n\n```tsx\n/* Light Mode */\nbg - background; // #FFFFFF (white)\ntext - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - background; // #020617 (slate-950)\ntext - foreground; // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n\n```tsx\n/* Light Mode */\nbg - accent; // #F1F5F9 (slate-100)\ntext - accent - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - accent; // #1E293B (slate-800)\ntext - accent - foreground; // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n\n```tsx\n/* Light Mode */\nbg - card; // #FFFFFF (white)\ntext - card - foreground; // #020617 (slate-950)\nbg - popover; // #FFFFFF (white)\ntext - popover - foreground; // #020617 (slate-950)\nborder - border; // #E2E8F0 (slate-200)\nborder - input; // #E2E8F0 (slate-200)\nring - ring; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - card; // #020617 (slate-950)\ntext - card - foreground; // #F8FAFC (slate-50)\nbg - popover; // #020617 (slate-950)\ntext - popover - foreground; // #F8FAFC (slate-50)\nborder - border; // #1E293B (slate-800)\nborder - input; // #1E293B (slate-800)\nring - ring; // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n\n```tsx\n/* Light Mode */\nbg - muted; // #F1F5F9 (slate-100)\ntext - muted - foreground; // #64748B (slate-500)\nbg - secondary; // #F1F5F9 (slate-100)\ntext - secondary - foreground; // #0F172A (slate-900)\nbg - destructive; // #DC2626 (red-600)\ntext - destructive - foreground; // #450A0A (red-950)\nbg - confirmative; // #16A34A (green-600)\ntext - confirmative - foreground; // #052E16 (green-950)\n\n/* Dark Mode */\nbg - muted; // #1E293B (slate-800)\ntext - muted - foreground; // #94A3B8 (slate-400)\nbg - secondary; // #1E293B (slate-800)\ntext - secondary - foreground; // #F8FAFC (slate-50)\nbg - destructive; // #7F1D1D (red-900)\ntext - destructive - foreground; // #FEF2F2 (red-50)\nbg - confirmative; // #14532D (green-900)\ntext - confirmative - foreground; // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n\n```tsx\n/* Light Mode */\nbg - sidebar - background; // #F8FAFC (slate-50)\ntext - sidebar - foreground; // #334155 (slate-700)\nborder - sidebar - border; // #E2E8F0 (slate-200)\nbg - sidebar - primary; // #0C4A6E (sky-900)\ntext - sidebar - primary - foreground; // #F0F9FF (sky-50)\nbg - sidebar - accent; // #F1F5F9 (slate-100)\ntext - sidebar - accent - foreground; // #0F172A (slate-900)\nring - sidebar - ring; // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg - sidebar - background; // #0F172A (slate-900)\ntext - sidebar - foreground; // #F1F5F9 (slate-100)\nborder - sidebar - border; // #1E293B (slate-800)\nbg - sidebar - primary; // #0369A1 (sky-700)\ntext - sidebar - primary - foreground; // #FFFFFF (white)\nbg - sidebar - accent; // #1E293B (slate-800)\ntext - sidebar - accent - foreground; // #F1F5F9 (slate-100)\nring - sidebar - ring; // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n\n```tsx\n/* Light Mode */\nbg - chart - 1; // #2A9D90\nbg - chart - 2; // #E76E50\nbg - chart - 3; // #274754\nbg - chart - 4; // #E8C468\nbg - chart - 5; // #F4A462\n\n/* Dark Mode */\nbg - chart - 1; // #2662D9\nbg - chart - 2; // #E23670\nbg - chart - 3; // #E88C30\nbg - chart - 4; // #AF57DB\nbg - chart - 5; // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅
// Related items (0.5rem)\n✅
// Content blocks (1rem)\n✅
// Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅
\n✅
\n\n// ❌ Don't use space-y or margins for spacing\n❌
\n❌
*+*]:ml-4\">\n❌
\n```\n\n### Flexbox & Grid\n\n```tsx\n// 1. Use flex + gap\n✅
\n✅
\n\n// 2. Use grid + gap\n✅
\n\n// ❌ Don't use margins for spacing\n❌
*+*]:ml-4\">\n❌
\n```\n\n### Container Patterns\n\n```tsx\n// Page Container\n✅
\n\n// Card Container\n✅
\n\n// Form Groups\n✅
\n```\n\n### Icons\n\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ // Default size\n✅ // Large size\n✅ // Small size\n\n// ❌ Don't use className for sizing\n❌ // Use size prop instead\n❌ // Use size prop instead\n\n```\n\n### Component Variants\n\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ \n✅ \n\n// ❌ Don't wrap components unnecessarily\n❌
\n \n
\n❌
\n \n
\n\n// 2. Use size variants for consistent sizing\n✅ \n✅ \n✅ \n\n// 3. Use asPill for rounded buttons\n✅ \n\n// 4. Combine variants appropriately\n✅ \n```\n\n### Page Layout\n\n```tsx\n
\n

Welcome to Helicone

\n Monitor and analyze your LLM usage\n\n
\n

Features

\n

Detailed explanation of features...

\n\n
\n {features.map((feature) => (\n
\n

{feature.title}

\n {feature.description}\n
\n ))}\n
\n
\n
\n```\n\n### Card Pattern\n\n```tsx\n\n \n

Usage Statistics

\n Last 30 days\n \n \n

Card content...

\n \n\n```\n"},"files":{"AGENTS.md":"# Repository Guidelines\n\n## Project Structure & Module Organization\n- Monorepo managed by Yarn workspaces (Node >= 20).\n- Apps: `web/` (Next.js app), `valhalla/jawn/` (TypeScript API), `worker/` (Cloudflare Worker), `bifrost/` (site/docs).\n- Shared code: `packages/*` (cost, filters, llm-mapper, prompts), `shared/`, `sdk/`.\n- Infra & data: `supabase/`, `clickhouse/`, `docker/`, `env/`, `examples/`.\n- Tests: `packages/**/__tests__/`, `worker` (Vitest), `valhalla/jawn` (Jest), Python integration in `tests/`.\n- Autogenerated types (do not manually edit these files):\n - valhalla/jawn/src/tsoa-build/\n - web/lib/clients/jawnTypes/\n - bifrost/lib/clients/jawnTypes/\n - worker/supabase/database.types.ts\n - web/db/database.types.ts\n - helicone-cron/src/db/database.types.ts\n - valhalla/jawn/src/lib/db/database.types.ts\n\n## Build, Test, and Development Commands\n- Install deps: `yarn`\n- Lint all: `yarn lint` • Fix: `yarn lint:fix`\n- Web app: `yarn workspace helicone dev:local` | build: `yarn workspace helicone build`\n- Bifrost: `yarn workspace bifrost dev`\n- API (Valhalla/Jawn): `yarn workspace helicone-api dev` | build: `yarn workspace helicone-api build`\n- Worker: `yarn workspace helicone-worker dev` | test: `yarn workspace helicone-worker test`\n- Packages tests: run Jest in `packages/` (e.g., `npx jest` or `npx jest __tests__/cost/registrySnapshots.test.ts`)\n- Python integration: `python tests/python_integration_tests.py`\n\n## Coding Style & Naming Conventions\n- TypeScript/React, 2‑space indent, semicolons default; format with Prettier.\n- ESLint required; fix warnings before PRs.\n- React components `PascalCase.tsx`; utilities `camelCase.ts`; tests `*.test.ts` in `__tests__/`.\n- TailwindCSS in `web/`; rely on `prettier-plugin-tailwindcss` for class ordering.\n\n## Testing Guidelines\n- Frameworks: Jest (web, packages, API), Vitest (worker), Python integration tests.\n- Add unit tests with meaningful assertions; snapshot tests where appropriate (packages/cost).\n- Run affected workspace tests locally before opening a PR.\n\n## Commit & Pull Request Guidelines\n- Use Conventional Commits where possible: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`. Example: `feat(web): add usage chart (#1234)`.\n- PRs include: clear description, linked issues, screenshots for UI changes, and notes on migrations or env updates.\n- Checks must pass: lint, build for touched workspaces, and relevant tests.\n\n## Security & Configuration Tips\n- Never commit secrets. Use `.env.example` as a template.\n- Web envs: `vercel env pull` or maintain `.env.local` locally.\n- Worker secrets: `wrangler secret put `.\n- Database/config: see `supabase/`, `clickhouse/`, and `docker/` for local setup.\n\n## Agent-Specific Notes\n- Scope changes to the smallest relevant workspace.\n- Prefer `yarn workspace `; avoid modifying unrelated packages.\n- Keep code style consistent; run `yarn lint` and add targeted tests.\n","CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nHelicone is an open-source LLM observability platform that provides monitoring, analytics, and management tools for Large Language Model applications. The project is structured as a monorepo with multiple services.\n\n## Core Architecture\n\n### Services\n\n- **Web (Frontend)**: Next.js dashboard app at `/web`\n- **Jawn (Backend)**: Express.js API server at `/valhalla/jawn`\n- **Worker (Proxy)**: Cloudflare Workers for LLM request interception at `/worker`\n- **AI Gateway**: Rust-based LLM proxy/router at `/aigateway`\n- **Bifrost**: Marketing/landing page at `/bifrost`\n\n### Data Flow\n\n1. Client → Helicone Proxy → LLM Provider\n2. Proxy sends logs to Upstash queue → Jawn processes → Databases\n3. PostgreSQL for app data, ClickHouse for analytics, MinIO for object storage\n\n## Development Commands\n\n### Main Development\n\n```bash\n# Start local development (requires Docker)\n./helicone-compose.sh helicone up\n\n# Web development\ncd web && yarn dev:better-auth # With better-auth\ncd web && yarn dev:local # Local development\n\n# Backend development\ncd valhalla/jawn && yarn dev\n\n# AI Gateway (Rust)\ncd aigateway && cargo run\n\n# Worker development (different types)\ncd worker && npx wrangler dev --local --var WORKER_TYPE:OPENAI_PROXY --port 8787\n```\n\n### Build & Test\n\n```bash\n# Web\ncd web && yarn build && yarn test && yarn lint\n\n# Backend\ncd valhalla/jawn && yarn build && yarn test:jawn\n\n# AI Gateway\ncd aigateway && cargo build && cargo test --tests --all-features && cargo clippy\n```\n\n## Code Style Guidelines\n\n### Frontend (Web)\n\n- Use TypeScript with strict typing\n- Follow design system with semantic components from `/web/components/ui/typography`\n- Use Tailwind utility classes for styling with semantic color tokens\n- Icons from `lucide-react` with consistent sizing via `size` prop\n- Layout with flexbox + gap, avoid margins for spacing\n\n### Component Patterns\n\n```tsx\n// Typography components\nimport { H1, H2, P, Small, Muted } from \"@/components/ui/typography\"\n\n// Colors - use semantic tokens\nclassName=\"bg-background text-foreground border-border\"\n\n// Layout - use flex + gap\n
\n
\n```\n\n### Backend (Jawn)\n\n- Controllers in `/valhalla/jawn/src/controllers/` use TSOA decorators\n- Managers in `/valhalla/jawn/src/managers/` extend `BaseManager`\n- Use `JawnAuthenticatedRequest` and return `Result`\n- Frontend hooks use TanStack Query with `useJawnClient()`\n\n### Database\n\n- PostgreSQL with snake_case naming\n- ClickHouse for analytics\n- Proper RLS policies for security\n\n## Tech Stack\n\n### Frontend\n\n- Next.js 14 with React 18.3.1\n- TypeScript, Tailwind CSS, Radix UI\n- Zustand for state management\n- TanStack Query for server state\n\n### Backend\n\n- Express.js with TSOA\n- Supabase (PostgreSQL) + ClickHouse\n- Upstash Redis for queuing\n- Better Auth for authentication\n\n### Infrastructure\n\n- Cloudflare Workers for proxying\n- Docker for local development\n- MinIO for object storage\n\n## Key Directories\n\n```\n/web/ # Next.js frontend\n/valhalla/jawn/ # Express.js backend\n/worker/ # Cloudflare Workers\n/aigateway/ # Rust LLM proxy\n/bifrost/ # Marketing site\n/packages/ # Shared packages\n ├── cost/ # Cost calculations\n ├── llm-mapper/ # Provider mappings\n └── prompts/ # Prompt management\n/supabase/ # Database migrations\n/clickhouse/ # Analytics DB setup\n```\n\n## Development Workflow\n\n1. Start infrastructure with Docker: `./helicone-compose.sh helicone up`\n2. Start web: `cd web && yarn dev:better-auth`\n3. Start backend: `cd valhalla/jawn && yarn dev`\n4. Access at `http://localhost:3000`\n\n## Testing\n\n- Web: `yarn test` (Jest)\n- Backend: `yarn test:jawn`\n- AI Gateway: `cargo test --tests --all-features`\n- E2E tests available in Python\n\n## Common Tasks\n\n### Adding New Features\n\n1. Design API in Jawn controller with TSOA\n2. Implement manager with database operations\n3. Create frontend hooks with TanStack Query\n4. Follow design system for UI components\n\n### Database Changes\n\n1. Add migrations in `/supabase/migrations/`\n2. Update types and managers accordingly\n3. Test with proper RLS policies\n\n### Style Changes\n\n- Use semantic color tokens, never raw colors\n- Follow typography component system\n- Use flexbox + gap for layouts\n- Test in both light and dark modes\n- when making changes to /packages run the tests npx jest **tests**/ in /packages to make sure nothing else is broken\n\n### TypeScript Type Changes\n\nWhen modifying TypeScript types (interfaces, type aliases, union types):\n\n1. **Run type checking before committing**: `npx tsc --noEmit` in the relevant package to catch type errors (Jest tests alone won't catch all type mismatches)\n2. **Search for related types**: When updating union types (e.g., `\"low\" | \"medium\" | \"high\"`), grep for similar patterns to ensure all related types are updated:\n ```bash\n grep -r \"thinkingLevel\" packages/ # Find all usages of similar type\n ```\n3. **Check cross-package dependencies**: Types in `/packages/` are often used across multiple packages (llm-mapper, prompts, cost). Verify changes don't break consumers.\n4. **Run the full build**: For `/packages/` changes, run `cd web && yarn build` or check Vercel preview to catch type errors across the monorepo.\n\n# Helicone Design System Guidelines\n\n## Core Principles\n\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n

Page Title

\n

Regular paragraph

\nHelper text\nSecondary text\n\n// ❌ Don't do this\n

Raw Styles

\n

Overriding Typography

\n

Wrong Size

\n```\n\n### Available Components\n\n```tsx\n// Headings\n

// Main page titles\n // Hero sections\n

// Section headers\n

// Subsection headers\n

// Card titles\n\n// Body Text\n

// Regular paragraphs\n // Introduction text\n // Emphasized body text\n // Helper text\n // Secondary text\n\n// Special Elements\n

// Quotations\n // Inline code\n // Unordered lists\n\n// Table Elements\n // Table headers\n // Table cells\n```\n\n### Typography Scale\n\n| Component | Size | Line Height | Weight | Usage |\n| --------- | ------------------------------------ | ----------------- | --------- | ------------------ |\n| H1 | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold | Main page titles |\n| H1Large | text-5xl (48px) | leading-10 (40px) | extrabold | Hero sections |\n| H2 | text-3xl (30px) | leading-9 (36px) | semibold | Section headers |\n| H3 | text-2xl (24px) | leading-8 (32px) | semibold | Subsection headers |\n| H4 | text-xl (20px) | leading-7 (28px) | semibold | Card titles |\n| Lead | text-xl (20px) | leading-7 (28px) | normal | Introduction text |\n| P | text-base (16px) | leading-7 (28px) | normal | Body text |\n| Small | text-sm (14px) | leading-4 (16px) | medium | Helper text |\n| Muted | text-sm (14px) | leading-none | normal | Secondary text |\n\n## Color System\n\n### Usage Patterns\n\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n\n```tsx\n/* Text Colors */\ntext - foreground; // Primary text\ntext - muted - foreground; // Secondary text\ntext - accent - foreground; // Accent text\n\n/* Background Colors */\nbg - background; // Page background\nbg - card; // Card background\nbg - muted; // Muted background\n\n/* Border Colors */\nborder - border; // Default borders\nborder - input; // Form inputs\nring - ring; // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n\n```tsx\n/* Light Mode */\nbg - primary; // #0EA5E9 (sky-500)\ntext - primary - foreground; // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg - primary; // #0284C7 (sky-600)\ntext - primary - foreground; // #083344 (sky-950)\n```\n\n### Background Colors\n\n```tsx\n/* Light Mode */\nbg - background; // #FFFFFF (white)\ntext - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - background; // #020617 (slate-950)\ntext - foreground; // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n\n```tsx\n/* Light Mode */\nbg - accent; // #F1F5F9 (slate-100)\ntext - accent - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - accent; // #1E293B (slate-800)\ntext - accent - foreground; // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n\n```tsx\n/* Light Mode */\nbg - card; // #FFFFFF (white)\ntext - card - foreground; // #020617 (slate-950)\nbg - popover; // #FFFFFF (white)\ntext - popover - foreground; // #020617 (slate-950)\nborder - border; // #E2E8F0 (slate-200)\nborder - input; // #E2E8F0 (slate-200)\nring - ring; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - card; // #020617 (slate-950)\ntext - card - foreground; // #F8FAFC (slate-50)\nbg - popover; // #020617 (slate-950)\ntext - popover - foreground; // #F8FAFC (slate-50)\nborder - border; // #1E293B (slate-800)\nborder - input; // #1E293B (slate-800)\nring - ring; // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n\n```tsx\n/* Light Mode */\nbg - muted; // #F1F5F9 (slate-100)\ntext - muted - foreground; // #64748B (slate-500)\nbg - secondary; // #F1F5F9 (slate-100)\ntext - secondary - foreground; // #0F172A (slate-900)\nbg - destructive; // #DC2626 (red-600)\ntext - destructive - foreground; // #450A0A (red-950)\nbg - confirmative; // #16A34A (green-600)\ntext - confirmative - foreground; // #052E16 (green-950)\n\n/* Dark Mode */\nbg - muted; // #1E293B (slate-800)\ntext - muted - foreground; // #94A3B8 (slate-400)\nbg - secondary; // #1E293B (slate-800)\ntext - secondary - foreground; // #F8FAFC (slate-50)\nbg - destructive; // #7F1D1D (red-900)\ntext - destructive - foreground; // #FEF2F2 (red-50)\nbg - confirmative; // #14532D (green-900)\ntext - confirmative - foreground; // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n\n```tsx\n/* Light Mode */\nbg - sidebar - background; // #F8FAFC (slate-50)\ntext - sidebar - foreground; // #334155 (slate-700)\nborder - sidebar - border; // #E2E8F0 (slate-200)\nbg - sidebar - primary; // #0C4A6E (sky-900)\ntext - sidebar - primary - foreground; // #F0F9FF (sky-50)\nbg - sidebar - accent; // #F1F5F9 (slate-100)\ntext - sidebar - accent - foreground; // #0F172A (slate-900)\nring - sidebar - ring; // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg - sidebar - background; // #0F172A (slate-900)\ntext - sidebar - foreground; // #F1F5F9 (slate-100)\nborder - sidebar - border; // #1E293B (slate-800)\nbg - sidebar - primary; // #0369A1 (sky-700)\ntext - sidebar - primary - foreground; // #FFFFFF (white)\nbg - sidebar - accent; // #1E293B (slate-800)\ntext - sidebar - accent - foreground; // #F1F5F9 (slate-100)\nring - sidebar - ring; // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n\n```tsx\n/* Light Mode */\nbg - chart - 1; // #2A9D90\nbg - chart - 2; // #E76E50\nbg - chart - 3; // #274754\nbg - chart - 4; // #E8C468\nbg - chart - 5; // #F4A462\n\n/* Dark Mode */\nbg - chart - 1; // #2662D9\nbg - chart - 2; // #E23670\nbg - chart - 3; // #E88C30\nbg - chart - 4; // #AF57DB\nbg - chart - 5; // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅
// Related items (0.5rem)\n✅
// Content blocks (1rem)\n✅
// Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅
\n✅
\n\n// ❌ Don't use space-y or margins for spacing\n❌
\n❌
*+*]:ml-4\">\n❌
\n```\n\n### Flexbox & Grid\n\n```tsx\n// 1. Use flex + gap\n✅
\n✅
\n\n// 2. Use grid + gap\n✅
\n\n// ❌ Don't use margins for spacing\n❌
*+*]:ml-4\">\n❌
\n```\n\n### Container Patterns\n\n```tsx\n// Page Container\n✅
\n\n// Card Container\n✅
\n\n// Form Groups\n✅
\n```\n\n### Icons\n\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ // Default size\n✅ // Large size\n✅ // Small size\n\n// ❌ Don't use className for sizing\n❌ // Use size prop instead\n❌ // Use size prop instead\n\n```\n\n### Component Variants\n\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ \n✅ \n\n// ❌ Don't wrap components unnecessarily\n❌
\n \n
\n❌
\n \n
\n\n// 2. Use size variants for consistent sizing\n✅ \n✅ \n✅ \n\n// 3. Use asPill for rounded buttons\n✅ \n\n// 4. Combine variants appropriately\n✅ \n```\n\n### Page Layout\n\n```tsx\n
\n

Welcome to Helicone

\n Monitor and analyze your LLM usage\n\n
\n

Features

\n

Detailed explanation of features...

\n\n
\n {features.map((feature) => (\n
\n

{feature.title}

\n {feature.description}\n
\n ))}\n
\n
\n
\n```\n\n### Card Pattern\n\n```tsx\n\n \n

Usage Statistics

\n Last 30 days\n \n \n

Card content...

\n \n\n```\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Repository Guidelines\n\n## Project Structure & Module Organization\n- Monorepo managed by Yarn workspaces (Node >= 20).\n- Apps: `web/` (Next.js app), `valhalla/jawn/` (TypeScript API), `worker/` (Cloudflare Worker), `bifrost/` (site/docs).\n- Shared code: `packages/*` (cost, filters, llm-mapper, prompts), `shared/`, `sdk/`.\n- Infra & data: `supabase/`, `clickhouse/`, `docker/`, `env/`, `examples/`.\n- Tests: `packages/**/__tests__/`, `worker` (Vitest), `valhalla/jawn` (Jest), Python integration in `tests/`.\n- Autogenerated types (do not manually edit these files):\n - valhalla/jawn/src/tsoa-build/\n - web/lib/clients/jawnTypes/\n - bifrost/lib/clients/jawnTypes/\n - worker/supabase/database.types.ts\n - web/db/database.types.ts\n - helicone-cron/src/db/database.types.ts\n - valhalla/jawn/src/lib/db/database.types.ts\n\n## Build, Test, and Development Commands\n- Install deps: `yarn`\n- Lint all: `yarn lint` • Fix: `yarn lint:fix`\n- Web app: `yarn workspace helicone dev:local` | build: `yarn workspace helicone build`\n- Bifrost: `yarn workspace bifrost dev`\n- API (Valhalla/Jawn): `yarn workspace helicone-api dev` | build: `yarn workspace helicone-api build`\n- Worker: `yarn workspace helicone-worker dev` | test: `yarn workspace helicone-worker test`\n- Packages tests: run Jest in `packages/` (e.g., `npx jest` or `npx jest __tests__/cost/registrySnapshots.test.ts`)\n- Python integration: `python tests/python_integration_tests.py`\n\n## Coding Style & Naming Conventions\n- TypeScript/React, 2‑space indent, semicolons default; format with Prettier.\n- ESLint required; fix warnings before PRs.\n- React components `PascalCase.tsx`; utilities `camelCase.ts`; tests `*.test.ts` in `__tests__/`.\n- TailwindCSS in `web/`; rely on `prettier-plugin-tailwindcss` for class ordering.\n\n## Testing Guidelines\n- Frameworks: Jest (web, packages, API), Vitest (worker), Python integration tests.\n- Add unit tests with meaningful assertions; snapshot tests where appropriate (packages/cost).\n- Run affected workspace tests locally before opening a PR.\n\n## Commit & Pull Request Guidelines\n- Use Conventional Commits where possible: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`. Example: `feat(web): add usage chart (#1234)`.\n- PRs include: clear description, linked issues, screenshots for UI changes, and notes on migrations or env updates.\n- Checks must pass: lint, build for touched workspaces, and relevant tests.\n\n## Security & Configuration Tips\n- Never commit secrets. Use `.env.example` as a template.\n- Web envs: `vercel env pull` or maintain `.env.local` locally.\n- Worker secrets: `wrangler secret put `.\n- Database/config: see `supabase/`, `clickhouse/`, and `docker/` for local setup.\n\n## Agent-Specific Notes\n- Scope changes to the smallest relevant workspace.\n- Prefer `yarn workspace `; avoid modifying unrelated packages.\n- Keep code style consistent; run `yarn lint` and add targeted tests.\n","category":"root","tokens":731},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nHelicone is an open-source LLM observability platform that provides monitoring, analytics, and management tools for Large Language Model applications. The project is structured as a monorepo with multiple services.\n\n## Core Architecture\n\n### Services\n\n- **Web (Frontend)**: Next.js dashboard app at `/web`\n- **Jawn (Backend)**: Express.js API server at `/valhalla/jawn`\n- **Worker (Proxy)**: Cloudflare Workers for LLM request interception at `/worker`\n- **AI Gateway**: Rust-based LLM proxy/router at `/aigateway`\n- **Bifrost**: Marketing/landing page at `/bifrost`\n\n### Data Flow\n\n1. Client → Helicone Proxy → LLM Provider\n2. Proxy sends logs to Upstash queue → Jawn processes → Databases\n3. PostgreSQL for app data, ClickHouse for analytics, MinIO for object storage\n\n## Development Commands\n\n### Main Development\n\n```bash\n# Start local development (requires Docker)\n./helicone-compose.sh helicone up\n\n# Web development\ncd web && yarn dev:better-auth # With better-auth\ncd web && yarn dev:local # Local development\n\n# Backend development\ncd valhalla/jawn && yarn dev\n\n# AI Gateway (Rust)\ncd aigateway && cargo run\n\n# Worker development (different types)\ncd worker && npx wrangler dev --local --var WORKER_TYPE:OPENAI_PROXY --port 8787\n```\n\n### Build & Test\n\n```bash\n# Web\ncd web && yarn build && yarn test && yarn lint\n\n# Backend\ncd valhalla/jawn && yarn build && yarn test:jawn\n\n# AI Gateway\ncd aigateway && cargo build && cargo test --tests --all-features && cargo clippy\n```\n\n## Code Style Guidelines\n\n### Frontend (Web)\n\n- Use TypeScript with strict typing\n- Follow design system with semantic components from `/web/components/ui/typography`\n- Use Tailwind utility classes for styling with semantic color tokens\n- Icons from `lucide-react` with consistent sizing via `size` prop\n- Layout with flexbox + gap, avoid margins for spacing\n\n### Component Patterns\n\n```tsx\n// Typography components\nimport { H1, H2, P, Small, Muted } from \"@/components/ui/typography\"\n\n// Colors - use semantic tokens\nclassName=\"bg-background text-foreground border-border\"\n\n// Layout - use flex + gap\n
\n
\n```\n\n### Backend (Jawn)\n\n- Controllers in `/valhalla/jawn/src/controllers/` use TSOA decorators\n- Managers in `/valhalla/jawn/src/managers/` extend `BaseManager`\n- Use `JawnAuthenticatedRequest` and return `Result`\n- Frontend hooks use TanStack Query with `useJawnClient()`\n\n### Database\n\n- PostgreSQL with snake_case naming\n- ClickHouse for analytics\n- Proper RLS policies for security\n\n## Tech Stack\n\n### Frontend\n\n- Next.js 14 with React 18.3.1\n- TypeScript, Tailwind CSS, Radix UI\n- Zustand for state management\n- TanStack Query for server state\n\n### Backend\n\n- Express.js with TSOA\n- Supabase (PostgreSQL) + ClickHouse\n- Upstash Redis for queuing\n- Better Auth for authentication\n\n### Infrastructure\n\n- Cloudflare Workers for proxying\n- Docker for local development\n- MinIO for object storage\n\n## Key Directories\n\n```\n/web/ # Next.js frontend\n/valhalla/jawn/ # Express.js backend\n/worker/ # Cloudflare Workers\n/aigateway/ # Rust LLM proxy\n/bifrost/ # Marketing site\n/packages/ # Shared packages\n ├── cost/ # Cost calculations\n ├── llm-mapper/ # Provider mappings\n └── prompts/ # Prompt management\n/supabase/ # Database migrations\n/clickhouse/ # Analytics DB setup\n```\n\n## Development Workflow\n\n1. Start infrastructure with Docker: `./helicone-compose.sh helicone up`\n2. Start web: `cd web && yarn dev:better-auth`\n3. Start backend: `cd valhalla/jawn && yarn dev`\n4. Access at `http://localhost:3000`\n\n## Testing\n\n- Web: `yarn test` (Jest)\n- Backend: `yarn test:jawn`\n- AI Gateway: `cargo test --tests --all-features`\n- E2E tests available in Python\n\n## Common Tasks\n\n### Adding New Features\n\n1. Design API in Jawn controller with TSOA\n2. Implement manager with database operations\n3. Create frontend hooks with TanStack Query\n4. Follow design system for UI components\n\n### Database Changes\n\n1. Add migrations in `/supabase/migrations/`\n2. Update types and managers accordingly\n3. Test with proper RLS policies\n\n### Style Changes\n\n- Use semantic color tokens, never raw colors\n- Follow typography component system\n- Use flexbox + gap for layouts\n- Test in both light and dark modes\n- when making changes to /packages run the tests npx jest **tests**/ in /packages to make sure nothing else is broken\n\n### TypeScript Type Changes\n\nWhen modifying TypeScript types (interfaces, type aliases, union types):\n\n1. **Run type checking before committing**: `npx tsc --noEmit` in the relevant package to catch type errors (Jest tests alone won't catch all type mismatches)\n2. **Search for related types**: When updating union types (e.g., `\"low\" | \"medium\" | \"high\"`), grep for similar patterns to ensure all related types are updated:\n ```bash\n grep -r \"thinkingLevel\" packages/ # Find all usages of similar type\n ```\n3. **Check cross-package dependencies**: Types in `/packages/` are often used across multiple packages (llm-mapper, prompts, cost). Verify changes don't break consumers.\n4. **Run the full build**: For `/packages/` changes, run `cd web && yarn build` or check Vercel preview to catch type errors across the monorepo.\n\n# Helicone Design System Guidelines\n\n## Core Principles\n\n1. Use semantic HTML elements\n2. Use Tailwind utility classes for colors\n3. Use typography components for consistent text styling\n4. Use Tailwind's spacing scale\n5. Use lucide-react for icons\n\n## Typography System\n\n### Usage Patterns\n\n```tsx\n// ✅ Do this\nimport { H1, P, Small, Muted } from \"@/components/ui/typography\"\n\n

Page Title

\n

Regular paragraph

\nHelper text\nSecondary text\n\n// ❌ Don't do this\n

Raw Styles

\n

Overriding Typography

\n

Wrong Size

\n```\n\n### Available Components\n\n```tsx\n// Headings\n

// Main page titles\n // Hero sections\n

// Section headers\n

// Subsection headers\n

// Card titles\n\n// Body Text\n

// Regular paragraphs\n // Introduction text\n // Emphasized body text\n // Helper text\n // Secondary text\n\n// Special Elements\n

// Quotations\n // Inline code\n // Unordered lists\n\n// Table Elements\n // Table headers\n // Table cells\n```\n\n### Typography Scale\n\n| Component | Size | Line Height | Weight | Usage |\n| --------- | ------------------------------------ | ----------------- | --------- | ------------------ |\n| H1 | text-3xl (30px) / lg:text-4xl (36px) | leading-10 (40px) | semibold | Main page titles |\n| H1Large | text-5xl (48px) | leading-10 (40px) | extrabold | Hero sections |\n| H2 | text-3xl (30px) | leading-9 (36px) | semibold | Section headers |\n| H3 | text-2xl (24px) | leading-8 (32px) | semibold | Subsection headers |\n| H4 | text-xl (20px) | leading-7 (28px) | semibold | Card titles |\n| Lead | text-xl (20px) | leading-7 (28px) | normal | Introduction text |\n| P | text-base (16px) | leading-7 (28px) | normal | Body text |\n| Small | text-sm (14px) | leading-4 (16px) | medium | Helper text |\n| Muted | text-sm (14px) | leading-none | normal | Secondary text |\n\n## Color System\n\n### Usage Patterns\n\n```tsx\n// 1. Use Tailwind utility classes for colors\n✅ text-foreground\n✅ bg-background\n✅ border-border\n\n// 2. Use foreground variants for text on colored backgrounds\n✅ bg-primary text-primary-foreground\n✅ bg-destructive text-destructive-foreground\n\n// ❌ Don't use CSS variables directly\n❌ text-[hsl(var(--foreground))]\n❌ bg-[hsl(var(--background))]\n\n// ❌ Don't use raw colors\n❌ text-slate-900\n❌ bg-white\n```\n\n### Color Utility Classes\n\n```tsx\n/* Text Colors */\ntext - foreground; // Primary text\ntext - muted - foreground; // Secondary text\ntext - accent - foreground; // Accent text\n\n/* Background Colors */\nbg - background; // Page background\nbg - card; // Card background\nbg - muted; // Muted background\n\n/* Border Colors */\nborder - border; // Default borders\nborder - input; // Form inputs\nring - ring; // Focus rings\n```\n\n## Color Reference Values\n\n### Primary Colors\n\n```tsx\n/* Light Mode */\nbg - primary; // #0EA5E9 (sky-500)\ntext - primary - foreground; // #F0F9FF (sky-50)\n\n/* Dark Mode */\nbg - primary; // #0284C7 (sky-600)\ntext - primary - foreground; // #083344 (sky-950)\n```\n\n### Background Colors\n\n```tsx\n/* Light Mode */\nbg - background; // #FFFFFF (white)\ntext - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - background; // #020617 (slate-950)\ntext - foreground; // #F8FAFC (slate-50)\n```\n\n### Accent Colors\n\n```tsx\n/* Light Mode */\nbg - accent; // #F1F5F9 (slate-100)\ntext - accent - foreground; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - accent; // #1E293B (slate-800)\ntext - accent - foreground; // #F8FAFC (slate-50)\n```\n\n### UI Component Colors\n\n```tsx\n/* Light Mode */\nbg - card; // #FFFFFF (white)\ntext - card - foreground; // #020617 (slate-950)\nbg - popover; // #FFFFFF (white)\ntext - popover - foreground; // #020617 (slate-950)\nborder - border; // #E2E8F0 (slate-200)\nborder - input; // #E2E8F0 (slate-200)\nring - ring; // #0F172A (slate-900)\n\n/* Dark Mode */\nbg - card; // #020617 (slate-950)\ntext - card - foreground; // #F8FAFC (slate-50)\nbg - popover; // #020617 (slate-950)\ntext - popover - foreground; // #F8FAFC (slate-50)\nborder - border; // #1E293B (slate-800)\nborder - input; // #1E293B (slate-800)\nring - ring; // #CBD5E1 (slate-300)\n```\n\n### Semantic Colors\n\n```tsx\n/* Light Mode */\nbg - muted; // #F1F5F9 (slate-100)\ntext - muted - foreground; // #64748B (slate-500)\nbg - secondary; // #F1F5F9 (slate-100)\ntext - secondary - foreground; // #0F172A (slate-900)\nbg - destructive; // #DC2626 (red-600)\ntext - destructive - foreground; // #450A0A (red-950)\nbg - confirmative; // #16A34A (green-600)\ntext - confirmative - foreground; // #052E16 (green-950)\n\n/* Dark Mode */\nbg - muted; // #1E293B (slate-800)\ntext - muted - foreground; // #94A3B8 (slate-400)\nbg - secondary; // #1E293B (slate-800)\ntext - secondary - foreground; // #F8FAFC (slate-50)\nbg - destructive; // #7F1D1D (red-900)\ntext - destructive - foreground; // #FEF2F2 (red-50)\nbg - confirmative; // #14532D (green-900)\ntext - confirmative - foreground; // #F0FDF4 (green-50)\n```\n\n### Sidebar Colors\n\n```tsx\n/* Light Mode */\nbg - sidebar - background; // #F8FAFC (slate-50)\ntext - sidebar - foreground; // #334155 (slate-700)\nborder - sidebar - border; // #E2E8F0 (slate-200)\nbg - sidebar - primary; // #0C4A6E (sky-900)\ntext - sidebar - primary - foreground; // #F0F9FF (sky-50)\nbg - sidebar - accent; // #F1F5F9 (slate-100)\ntext - sidebar - accent - foreground; // #0F172A (slate-900)\nring - sidebar - ring; // #94A3B8 (slate-400)\n\n/* Dark Mode */\nbg - sidebar - background; // #0F172A (slate-900)\ntext - sidebar - foreground; // #F1F5F9 (slate-100)\nborder - sidebar - border; // #1E293B (slate-800)\nbg - sidebar - primary; // #0369A1 (sky-700)\ntext - sidebar - primary - foreground; // #FFFFFF (white)\nbg - sidebar - accent; // #1E293B (slate-800)\ntext - sidebar - accent - foreground; // #F1F5F9 (slate-100)\nring - sidebar - ring; // #CBD5E1 (slate-300)\n```\n\n### Chart Colors\n\n```tsx\n/* Light Mode */\nbg - chart - 1; // #2A9D90\nbg - chart - 2; // #E76E50\nbg - chart - 3; // #274754\nbg - chart - 4; // #E8C468\nbg - chart - 5; // #F4A462\n\n/* Dark Mode */\nbg - chart - 1; // #2662D9\nbg - chart - 2; // #E23670\nbg - chart - 3; // #E88C30\nbg - chart - 4; // #AF57DB\nbg - chart - 5; // #2EB88A\n```\n\n## Layout Best Practices\n\n### Spacing\n\n```tsx\n// 1. Use Tailwind's spacing scale with flex + gap\n✅
// Related items (0.5rem)\n✅
// Content blocks (1rem)\n✅
// Sections (1.5rem)\n\n// 2. Use flex + gap for horizontal layouts\n✅
\n✅
\n\n// ❌ Don't use space-y or margins for spacing\n❌
\n❌
*+*]:ml-4\">\n❌
\n```\n\n### Flexbox & Grid\n\n```tsx\n// 1. Use flex + gap\n✅
\n✅
\n\n// 2. Use grid + gap\n✅
\n\n// ❌ Don't use margins for spacing\n❌
*+*]:ml-4\">\n❌
\n```\n\n### Container Patterns\n\n```tsx\n// Page Container\n✅
\n\n// Card Container\n✅
\n\n// Form Groups\n✅
\n```\n\n### Icons\n\n```tsx\n// 1. Import from lucide-react\nimport { ChevronRight, Settings, Info } from \"lucide-react\"\n\n// 2. Standard Icon Sizes\n// xs: 12px - For very small icons in dense UI\n// sm: 14px - For small icons in buttons and forms\n// default: 16px - Default size for most icons\n// lg: 20px - For larger icons in headers or cards\n// xl: 24px - For hero sections or large UI elements\n\n// 3. Use Lucide size prop consistently\n✅ // Default size\n✅ // Large size\n✅ // Small size\n\n// ❌ Don't use className for sizing\n❌ // Use size prop instead\n❌ // Use size prop instead\n\n```\n\n### Component Variants\n\n```tsx\n// 1. Use built-in variants instead of custom wrappers\n✅ \n✅ \n\n// ❌ Don't wrap components unnecessarily\n❌
\n \n
\n❌
\n \n
\n\n// 2. Use size variants for consistent sizing\n✅ \n✅ \n✅ \n\n// 3. Use asPill for rounded buttons\n✅ \n\n// 4. Combine variants appropriately\n✅ \n```\n\n### Page Layout\n\n```tsx\n
\n

Welcome to Helicone

\n Monitor and analyze your LLM usage\n\n
\n

Features

\n

Detailed explanation of features...

\n\n
\n {features.map((feature) => (\n
\n

{feature.title}

\n {feature.description}\n
\n ))}\n
\n
\n
\n```\n\n### Card Pattern\n\n```tsx\n\n \n

Usage Statistics

\n Last 30 days\n \n \n

Card content...

\n \n\n```\n","category":"root","tokens":3905}]}