terminal: Instructions file for Codex

AGENTS.md - Repository Guide for Agentic Coding

This file contains essential information for agentic coding agents working in this repository.

Project Overview

• Framework: Svelte 4 + TypeScript + Vite
• Styling: Tailwind CSS
• Type Checking: TypeScript with svelte-check
• Node Version: >=18.17.0

Commands

Development

• npm run dev - Start dev server (port 3000)
• npm run build - Build for production
• npm run preview - Preview production build
• npm run check - Run Svelte type checking

Testing

• npm run test - Run unit/component tests once
• npm run test:ui - Run tests with Vitest UI
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Generate coverage report (85%+ target)
• npm run test:e2e - Run E2E tests (Playwright, headless)
• npm run test:e2e:ui - Run E2E tests with Playwright UI
• npm run test:e2e:headed - Run E2E tests in headed browser
• npm run test:all - Run all tests (unit + E2E)

Running Single Test

• Unit/component: vitest run [filename] or vitest run -t [test-name]
• E2E: npx playwright test [filename] or npx playwright test -g [test-name]

Pre-commit Hook

Tests run automatically on pre-commit for staged TypeScript/Svelte files using husky + lint-staged.

Coverage

Target: 85%+ across all files. View coverage report in coverage/index.html.

Code Style Guidelines

File Structure & Naming

• Components: PascalCase (src/components/History.svelte)
• Utilities: lowercase (src/utils/commands.ts)
• Stores: src/stores/[name].ts pattern
• Interfaces: src/interfaces/[name].ts pattern
• Entry point: src/main.ts

Imports

• Use single quotes for all import paths
• Svelte imports use named imports from specific packages:

  import { writable } from 'svelte/store';
  import { onMount, afterUpdate } from 'svelte';
  

• Relative imports use ./ or ../ notation
• JSON imports are supported: import themes from '../../themes.json';