# AGENTS.md

This document provides guidelines for agentic coding assistants working in this repository.

## Project Overview

This is a Laravel + Vue 3 authentication application using Inertia.js, TypeScript, and Tailwind CSS v4. The frontend lives in `resources/js/` and integrates with Laravel backend via Vite.

## Build Commands

### Frontend (npm)

```bash
# Development
npm run dev                    # Start Vite dev server
npm run build                 # Production build
npm run build:dev             # Development build
npm run build:ssr             # Build for SSR

# Code Quality
npm run format                # Format code with Prettier (resources/)
npm run format:check          # Check formatting without modifying
npm run lint                  # Run ESLint and auto-fix issues
```

### Backend (Laravel/Valet)

```bash
# Run on valet (https://coloid-auth.test)
valet php artisan migrate
valet php artisan config:clear

# Mailpit
# http://localhost:8025/
```

## Code Style Guidelines

### Laravel Conventions

- Follow Laravel naming conventions (PSR-12); run `vendor/bin/pint` before committing
- Controller methods return `Inertia::render(...)` or `back()->with(...)`
- Use Form Requests for validation, never inline `$request->validate()`
- Use route model binding where appropriate
- Controllers live in `app/Http/Controllers/` (`Auth/`, `Settings/`, `Api/`)
- Read config through `config('services.x.y')`, never `env()` outside `config/`

### Imports and Paths

- Use path aliases: `@/*` maps to `./resources/js/*`
- Put imports in this order: Vue, Inertia, UI components, layouts, other internal imports, utilities
- Example: `import { Head } from '@inertiajs/vue3';`
- Use named imports from component directories: `import { Button } from '@/components/ui/button';`

### TypeScript

- Enable strict mode in `tsconfig.json`
- Prefer explicit types over `any` (ESLint rule `@typescript-eslint/no-explicit-any` is disabled, but still prefer explicit types)
- Use `defineProps<{ ... }>()` for Vue component props
- Use TypeScript utility types when appropriate
- Custom types go in `resources/js/types/`

### Vue Components

- Use `<script setup lang="ts">` for all components
- Use Composition API with TypeScript
- Component file naming: PascalCase (e.g., `AuthLayout.vue`)
- Page components: `resources/js/pages/**/*.vue`
- Layout components: `resources/js/layouts/**/*.vue`
- UI components: `resources/js/components/ui/**/*.vue`
- Feature components: `resources/js/components/*.vue`

### Template and Styling

- Use Tailwind CSS classes for styling (v4)
- Component props in templates should be on separate lines for readability
- Use `class` prop for Tailwind classes, not `style`
- Component attributes should be sorted consistently (see existing components for pattern)

### Naming Conventions

- Files: PascalCase for Vue/TS files
- Variables/functions: camelCase
- Constants: UPPER_SNAKE_CASE
- Component props: camelCase
- CSS classes: kebab-case (Tailwind)

### Utility Functions

- Shared utilities in `resources/js/lib/utils.ts`
- Composables in `resources/js/composables/*.ts`
- Use named exports for utilities: `export function myUtil() { ... }`

### Error Handling

- Use Vue's `InputError` component for form validation errors
- Use `Alert` component for status/error messages
- Propagate backend errors via Inertia form errors object
- Show loading states during async operations (use `processing` from Inertia form)

### Form Handling

- Use Inertia's `Form` component with `v-slot="{ errors, processing }"`
- Use `AuthenticatedSessionController` and similar pattern for form actions
- Reset sensitive fields on success with `:reset-on-success="['password']"`

### Code Organization

- Keep components small and focused
- Extract reusable logic into composables
- Use layouts to share page structure (`resources/js/layouts/`)
- Put shadcn-vue style UI components in `resources/js/components/ui/`

### File Structure

```
resources/js/
├── app.ts                  # App entry point
├── pages/                  # Route pages
├── layouts/                # Layout components
├── components/             # Feature components
│   ├── ui/                 # Reusable UI components
│   └── *.vue               # Feature components
├── composables/            # Vue composables
├── lib/                    # Utility libraries
└── types/                  # TypeScript types

app/Http/Controllers/
├── Auth/                   # Authentication flows (Fortify)
├── Settings/               # Profile, password, 2FA, subscription
└── Api/                    # Sanctum-authenticated endpoints
```

## Changelog

Every user-visible change gets an entry in `CHANGELOG.md` under `## [Unreleased]`, written as part
of the change rather than afterwards. Sections follow Keep a Changelog (`Added` / `Changed` /
`Fixed` / `Removed`, plus `Known issues` for anything knowingly left broken). Releases rename
`Unreleased` to the version number and bump `version` in `package.json`. Refactors, formatting and
test-only work need no entry.

## IDE Configuration

- ESLint and Prettier are configured for this project
- VSCode: Use Vue-Official extension and ESLint extension
- Enable "format on save" for best experience