portfolio/AGENTS.md

# AGENTS.md - Agent Coding Guidelines

This document provides guidelines for agents working on this codebase.

## Project Overview

- **Framework**: Nuxt 3 (Vue 3)
- **Styling**: Tailwind CSS
- **State Management**: Pinia
- **UI Components**: Headless UI + Nuxt Icon
- **Image Handling**: @nuxt/image
- **TypeScript**: Enabled (tsconfig extends .nuxt/tsconfig.json)
- **Storybook**: Available for component documentation

## Build Commands

```bash
# Development
npm run dev              # Start development server
npm run build            # Build for production
npm run generate         # Generate static site (SSG)
npm run preview          # Preview production build

# No test framework configured
```

## Code Style Guidelines

### General Conventions

- Use Vue 3 Composition API with `<script setup lang="ts">`
- TypeScript is preferred for new files; stores use JavaScript (.js)
- Follow Nuxt 3 auto-import conventions (no explicit imports for composables, components, etc.)

### File Organization

```
/pages/          - Page components (file-based routing)
/components/     - Vue components (auto-imported)
/layouts/        - Layout components
/server/api/     - Server API routes (Nitro)
/stores/         - Pinia stores (.js files)
/assets/         - Static assets
/public/         - Public static files
```

### Naming Conventions

- **Components**: PascalCase (e.g., `Modal.vue`, `IconButton.vue`)
- **Files**: kebab-case for pages, PascalCase for components
- **Stores**: CamelCase (e.g., `ModalStore.js`, `AudioPlayerStore.js`)
- **Props/Emits**: camelCase

### Component Patterns

```vue
<script setup lang="ts">
// Use withDefaults for optional props
const props = withDefaults(
  defineProps<{
    modelValue?: boolean
    persistent?: boolean
  }>(),
  {
    modelValue: false,
    persistent: false,
  },
)

// Use type-only emits
const emit = defineEmits<{
  (e: 'update:modelValue', value: boolean): void
}>()

// Use toRefs for reactive destructuring
const { modelValue } = toRefs(props)
</script>

<template>
  <!-- Template content -->
</template>
```

### Tailwind CSS

- Use Tailwind utility classes for all styling
- Common classes used: `flex`, `grid`, `fixed`, `relative`, `z-*`, `p-*`, `m-*`, `text-*`, etc.

### API Routes (Server)

```typescript
// server/api/example.ts
export default defineEventHandler((event) => {
  // Handle request and return data
})
```

### Store Patterns (Pinia)

```javascript
// stores/ExampleStore.js
import { defineStore } from "pinia"

export const useExampleStore = defineStore("ExampleStore", {
  state: () => ({ count: 0 }),
  actions: {
    increment() {
      this.count++
    }
  }
})
```

### Error Handling

- Use try/catch in API routes
- Return appropriate HTTP status codes
- Handle undefined/null values gracefully

### Imports

- Vue/composables: Use Nuxt auto-imports (no import needed)
- External modules: Explicit import
- Server-only: Place in `/server/` directory
- Path aliases: `@/` maps to project root

### Additional Notes

- Project uses Storybook (`.stories.ts` files) for component documentation
- Environment variables should use `.env` files (not committed)
- Image domains configured for `unboundedpress.org` in nuxt.config.ts