# Agent Guidelines

## Development Commands

```bash
# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Type checking
npm run check

# Type checking with watch mode
npm run check:watch

# Sync SvelteKit
npm run prepare
```

**Note:** No test framework is configured. Add Vitest or similar for testing.

## Code Style Guidelines

### File Structure
- `src/routes/` - Route pages and layouts
- `src/lib/` - Reusable components and utilities (importable via `$lib` alias)
- `src/app.d.ts` - Global TypeScript declarations for SvelteKit types
- `static/` - Static assets served at `/`

### Svelte Components

**Svelte 5 Runes Syntax:**
```svelte
<script lang="ts">
	let { children } = $props();
</script>
```

Use Svelte 5 runes API for reactivity:
- `$props()` for component props
- `$state()` for reactive state
- `$derived()` for derived values

**Imports:**
```svelte
<script lang="ts">
	import favicon from '$lib/assets/favicon.svg';
</script>
```

Use `$lib` alias for imports from `src/lib/`.

### TypeScript

**Configuration:**
- Strict mode enabled
- ES modules (`"type": "module"`)
- Module resolution: bundler

**Types:**
- Extend global `App` namespace in `app.d.ts` for custom interfaces:
  - `App.Error`
  - `App.Locals`
  - `App.PageData`
  - `App.PageState`
  - `App.Platform`

### Styling

- Use tabs for indentation
- Single quotes for string literals
- Semicolons at end of statements
- No ESLint/Prettier configured - follow SvelteKit conventions

### File Naming

- Routes: `+page.svelte`, `+layout.svelte`, `+error.svelte`
- Server endpoints: `+page.server.ts`, `+layout.server.ts`, `+server.ts`
- Load functions: `+page.ts`, `+layout.ts`

### SvelteKit File Types

**Page Files:**
- `+page.svelte` - The component for a route page, renders HTML and handles UI
- `+page.ts` - Universal load function that runs on server and client, returns data for the page
- `+page.server.ts` - Server-only load function with access to cookies, database, and server APIs

**Layout Files:**
- `+layout.svelte` - Wraps child routes with shared UI (navbar, footer, etc.)
- `+layout.ts` - Universal load function that provides data to all child routes
- `+layout.server.ts` - Server-only layout load for shared data (auth session, user info, etc.)

**Special Files:**
- `+error.svelte` - Custom error page component, renders when `error()` is thrown or page fails to load
- `+loading.svelte` - Loading indicator shown during navigation while data is loading
- `+not-found.svelte` - Custom 404 page when a route doesn't exist

**Server Endpoints:**
- `+server.ts` - API endpoint (GET, POST, PUT, DELETE, etc.) that creates RESTful routes
- Supports named export functions like `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`

**Root Files:**
- `src/app.html` - HTML template for the entire application, injected with rendered content
- `src/app.d.ts` - TypeScript declarations extending SvelteKit's global types
- `src/hooks.server.ts` - Server-side hooks (handle, handleError) for auth, cookies, middleware
- `src/hooks.client.ts` - Client-side hooks for browser-specific initialization

### Import Style

- Group imports: third-party, internal, relative
- Use absolute imports with `$lib` alias for library imports
- Use relative imports `./` and `../` for same-directory files

### Component Conventions

- Always specify `lang="ts"` in `<script>` tags
- Use `<svelte:head>` for document head elements
- Render slot content with `{@render children()}` for layouts

### Error Handling

Use SvelteKit's error handling:
- Throw `error(status, message)` from load functions
- Create `+error.svelte` pages for error UI
- Define `App.Error` interface for custom error types

### Development Workflow

1. Run `npm run dev` for hot-reload development
2. Run `npm run check` before committing to ensure type safety
3. Test with `npm run build` before deploying

### Adding Tests

No test framework is currently configured. To add testing:
1. Install Vitest: `npm install -D vitest @testing-library/svelte`
2. Create test files alongside source with `.test.ts` suffix
3. Update `package.json` with test scripts