Skip to content

Latest commit

 

History

History
203 lines (156 loc) · 6.68 KB

CLAUDE.md

File metadata and controls

203 lines (156 loc) · 6.68 KB

CLAUDE.md

This document provides guidance for AI assistants working with the harbor-docs codebase.

Project Overview

This is the documentation website for Harbor, a framework for evaluating and optimizing agents and models in container environments. The site is built with Next.js 16, React 19, and Fumadocs.

Live site: https://harborframework.com

Main Harbor repository: https://github.com/laude-institute/harbor

Tech Stack

  • Framework: Next.js 16 (App Router)
  • React: v19
  • Documentation: Fumadocs (fumadocs-core, fumadocs-ui, fumadocs-mdx)
  • Styling: Tailwind CSS 4 with CSS variables
  • UI Components: shadcn/ui (new-york style)
  • Database: Supabase (for registry data)
  • Syntax Highlighting: Shiki (github-light/github-dark themes)
  • Fonts: Google Sans Code, Google Sans Flex, Instrument Sans/Serif, Geist Mono
  • Package Manager: bun

Directory Structure

harbor-docs/
├── content/
│   └── docs/           # MDX documentation files
│       ├── meta.json   # Navigation structure and page ordering
│       └── *.mdx       # Documentation pages
├── src/
│   ├── app/
│   │   ├── (home)/     # Landing page route group
│   │   │   ├── components/  # Home page components
│   │   │   ├── layout.tsx
│   │   │   └── page.tsx
│   │   ├── docs/       # Documentation pages
│   │   │   ├── layout.tsx
│   │   │   └── [[...slug]]/page.tsx
│   │   ├── registry/   # Dataset registry page
│   │   ├── api/search/ # Search API route
│   │   ├── og/         # OpenGraph image generation
│   │   ├── llms-full.txt/  # LLM-friendly text export
│   │   ├── layout.tsx  # Root layout
│   │   └── global.css  # Global styles
│   ├── components/
│   │   ├── ui/         # shadcn/ui components
│   │   └── code-block.tsx
│   ├── lib/
│   │   ├── source.ts   # Fumadocs source configuration
│   │   ├── layout.shared.tsx  # Shared layout options
│   │   ├── utils.ts    # Utility functions (cn helper)
│   │   └── supabase/   # Supabase client and types
│   └── mdx-components.tsx  # MDX component overrides
├── public/             # Static assets (favicon, OG images)
├── source.config.ts    # Fumadocs MDX configuration
├── next.config.mjs     # Next.js configuration
├── tsconfig.json       # TypeScript configuration
├── eslint.config.mjs   # ESLint configuration
├── postcss.config.mjs  # PostCSS configuration
├── components.json     # shadcn/ui configuration
└── package.json

Development Commands

# Install dependencies
bun install

# Run development server (http://localhost:3000)
bun dev

# Build for production
bun run build

# Start production server
bun start

# Run ESLint
bun lint

Key Files and Concepts

Documentation Content (content/docs/)

  • Documentation is written in MDX format
  • meta.json controls page ordering and navigation sections
  • Frontmatter fields: title, description, full (optional, for full-width pages)
  • Sections are created with ---SectionName--- separators in meta.json

Navigation Structure (content/docs/meta.json)

The documentation is organized into sections:

  • Harbor: Core concepts, getting started, migration
  • Agents: Agent documentation, terminus-2, trajectory format
  • Tasks: Task format, tutorials, differences
  • Datasets: Running benchmarks, adapters, metrics
  • Cloud: Cloud sandbox providers
  • Use Cases: Evals, RL, SFT
  • Contributing: Contribution guidelines

Source Configuration (src/lib/source.ts)

Configures Fumadocs loader with:

  • Base URL: /docs
  • Lucide icons plugin
  • Page image generation helpers
  • LLM text extraction for /llms-full.txt endpoint

Layout Configuration (src/lib/layout.shared.tsx)

Shared layout options including:

Supabase Integration (src/lib/supabase/)

  • server.ts: Server-side Supabase client (no auth, read-only)
  • types.ts: Generated TypeScript types for database schema
  • Tables: dataset, dataset_task, dataset_metric, dataset_access_log

Required environment variables:

NEXT_PUBLIC_SUPABASE_URL=<supabase-url>
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<supabase-anon-key>

Coding Conventions

TypeScript

  • Strict mode enabled
  • Path aliases: @/* → ./src/*, @/.source/* → .source/*
  • ESNext target with bundler module resolution

Styling

  • Use Tailwind CSS utility classes
  • Custom font variables: font-sans, font-serif, font-code, font-mono
  • CSS variables for theming (defined in src/app/global.css)
  • Use cn() helper from @/lib/utils for conditional classes

Components

  • shadcn/ui components in src/components/ui/
  • Use asChild pattern with Radix Slot for polymorphic components
  • Fumadocs MDX components available via getMDXComponents()

MDX Content

Use Fumadocs UI components in MDX files:

  • <Callout> for important notes
  • <TypeTable> for API documentation
  • <Accordions> and <Accordion> for collapsible content
  • <Files>, <Folder>, <File> for file tree visualization
  • Code blocks with tab="name" for tabbed code examples

Example:

import { Callout } from 'fumadocs-ui/components/callout';
import { TypeTable } from 'fumadocs-ui/components/type-table';

<Callout title="Note">
Important information here.
</Callout>

Adding New Documentation

  1. Create a new .mdx file in content/docs/
  2. Add frontmatter with title and description
  3. Add the filename (without extension) to content/docs/meta.json in the appropriate section
  4. Use relative links to reference other docs (e.g., [link](/docs/other-page))

Adding New UI Components

Use shadcn/ui CLI:

bunx shadcn@latest add <component-name>

Components are installed to src/components/ui/ following the new-york style variant.

Generated Files

The following are auto-generated and should not be edited manually:

  • .source/ - Fumadocs MDX compilation output
  • .next/ - Next.js build output
  • node_modules/ - Dependencies
  • next-env.d.ts - Next.js TypeScript declarations

Important Notes

  • The .source/ directory is generated by fumadocs-mdx during postinstall
  • Supabase types in src/lib/supabase/types.ts are generated from the database schema
  • The registry page (/registry) fetches live data from Supabase
  • The /llms-full.txt endpoint provides all documentation as plain text for LLM consumption