docs: add AGENTS.md file with instructions for AI coding agents

AGENTS.md

@@ -0,0 +1,200 @@
+# AGENT Instructions
+
+## Project Overview
+
+Vikunja is a comprehensive todo and task management application with a Vue.js frontend and Go backend. It supports multiple project views (List, Kanban, Gantt, Table), team collaboration, file attachments, and extensive integrations.
+
+The project consists of:
+- `pkg/` – Go code for the API service
+- `frontend/` – Vue.js based web client
+- `magefile.go` – Mage build script providing tasks for development and release
+- `desktop/` – Electron wrapper application
+- `docs/` – Documentation website
+
+## Development Commands
+
+### Backend (Go)
+- **Build**: `mage build` - Builds the Go binary
+- **Test**: `mage test:unit` - Runs unit tests 
+- **Test Integration**: `mage test:integration` - Runs integration tests
+- **Test All**: `mage test:all` - Runs all tests
+- **Lint**: `mage lint` - Runs golangci-lint
+- **Lint Fix**: `mage lint:fix` - Runs golangci-lint with auto-fix
+- **Generate Swagger Docs**: `mage generate:swagger-docs` - Updates API documentation (Generally you won't need to run this unless the user tells you to. It is updated automatically in the CI workflow)
+- **Check Swagger**: `mage check:got-swag` - Verifies swagger docs are up to date
+- **Generate Config**: `mage generate:config-yaml` - Generate sample config from `config-raw.json`
+- **Clean**: `mage build:clean` - Cleans build artifacts
+- **Format**: `mage fmt` - Format Go code before committing
+
+Development helpers under the `dev` namespace:
+- **Migration**: `mage dev:make-migration` - Creates new database migration
+- **Event**: `mage dev:make-event` - Create an event type
+- **Listener**: `mage dev:make-listener` - Create an event listener  
+- **Notification**: `mage dev:make-notification` - Create a notification skeleton
+
+### Frontend (Vue.js)
+Navigate to `frontend/` directory:
+- **Dev Server**: `pnpm dev` - Starts development server
+- **Build**: `pnpm build` - Production build
+- **Build Dev**: `pnpm build:dev` - Development build  
+- **Lint**: `pnpm lint` - ESLint check
+- **Lint Fix**: `pnpm lint:fix` - ESLint with auto-fix
+- **Type Check**: `pnpm typecheck` - Vue TypeScript checking
+- **Test Unit**: `pnpm test:unit` - Vitest unit tests
+- **Test E2E**: `pnpm test:e2e` - Cypress end-to-end tests
+- **Test E2E Dev**: `pnpm test:e2e-dev` - Interactive Cypress testing
+
+### Pre-commit Checks
+Always run both lint before committing:
+```bash
+# Backend
+mage lint:fix
+
+# Frontend  
+cd frontend && pnpm lint:fix
+```
+
+Fix any errors the lint commands report, then try comitting again.
+
+You only need to run the lint for the backend when changing backend code, and the lint for the frontend only when changing frontend code.
+
+## Architecture Overview
+
+### Backend Architecture (Go)
+The Go backend follows a layered architecture with clear separation of concerns:
+
+**Core Layers:**
+- **Models** (`pkg/models/`) - Domain entities with business logic and CRUD operations
+- **Services** (`pkg/services/`) - Business logic layer handling complex operations
+- **Routes** (`pkg/routes/`) - HTTP API endpoints and routing configuration
+- **Web** (`pkg/web/`) - Generic CRUD handlers and web framework abstractions
+
+**Key Patterns:**
+- **Generic CRUD**: Models implement `CRUDable` interface for standardized database operations
+- **Rights System**: Three-tier permissions (Read/Write/Admin) enforced across all operations
+- **Event-Driven**: Event system for notifications, webhooks, and cross-cutting concerns
+- **Modular Design**: Pluggable authentication, avatar providers, migration tools
+
+**Database:**
+- XORM ORM with support for MySQL, PostgreSQL, SQLite
+- Migration system in `pkg/migration/` with timestamped files
+- Database sessions with automatic transaction handling
+
+**Authentication:**
+- Multi-provider: Local, LDAP, OpenID Connect
+- JWT tokens for API access
+- API tokens with scoped permissions
+- TOTP/2FA support
+
+### Frontend Architecture (Vue.js)
+Modern Vue 3 composition API application with TypeScript:
+
+**State Management:**
+- **Pinia** stores in `src/stores/` for global state
+- Composables in `src/composables/` for reusable logic
+- Component-level state with Vue 3 Composition API
+
+**Key Directories:**
+- `src/components/` - Reusable Vue components organized by feature
+- `src/views/` - Page-level components and routing
+- `src/stores/` - Pinia state management
+- `src/services/` - API service layer matching backend models
+- `src/models/` - TypeScript interfaces matching backend models
+- `src/helpers/` - Utility functions and business logic
+
+**UI Framework:**
+- Bulma CSS framework with CSS variables for theming
+- FontAwesome icons with tree-shaking
+- TipTap rich text editor for task descriptions
+- Custom component library in `src/components/base/`
+
+## Development Workflows
+
+### Adding New Features
+
+**Backend Changes:**
+1. Create/modify models in `pkg/models/` with proper CRUD and Rights interfaces as required
+2. Add database migration if needed: `mage dev:make-migration`
+3. Create/update services in `pkg/services/` for complex business logic
+4. Add API routes in `pkg/routes/api/v1/` following existing patterns
+5. Update Swagger annotations
+
+**Frontend Changes:**
+1. Create TypeScript interfaces in `src/modelTypes/` matching backend models
+2. Add/update services in `src/services/` for API communication
+3. Create components in appropriate `src/components/` subdirectories
+4. Add views/pages in `src/views/` with proper routing
+5. Update Pinia stores if global state changes are needed
+
+### Database Changes
+1. Run `mage dev:make-migration` and enter the struct name
+2. Edit the generated migration file in `pkg/migration/`
+3. Update corresponding model in `pkg/models/`
+4. Update TypeScript interfaces in frontend `src/modelTypes/`
+
+### API Development
+- All API endpoints follow RESTful conventions under `/api/v1/`
+- Use generic web handlers in `pkg/web/handler/` for standard CRUD operations
+- Implement proper rights checking using the Rights interface
+- Add Swagger annotations for automatic documentation generation
+
+### Testing
+- Backend: Unit tests alongside source files, integration tests in `pkg/integrations/`
+- Frontend: Unit tests with Vitest, E2E tests with Cypress
+- Always test both positive and negative authorization scenarios
+- Use test fixtures in `pkg/db/fixtures/` for consistent test data
+
+## Swagger API Documentation
+
+Never touch the generated swagger api documentation under `pkg/swagger/`. These are automatically generated by CI after committing.
+
+## Commit Messages
+
+Use the **Conventional Commits** style when committing changes (for example, `feat: add foo` or `fix: correct bar`). This repository uses these messages to generate changelogs.
+
+## Frontend Development Guidelines
+
+The web client lives in `frontend/` and uses Vue.js 3 in combination with TypeScript.
+
+Check the `frontend/.editorconfig` file and obey the formatting rules outlined there.
+
+## Translations
+
+When adding or changing functionality which touches user-facing messages, these need to be translated.
+
+In the frontend, all translation strings live in `frontend/src/i18n/lang`. For the api (which mainly affects the localization of notifications), the strings live in `pkg/i18n/lang`.
+
+You only need to adjust the `en.json` file with the source string. The actual translation happens elsewhere.
+After adjusting the source string, you need to call the respective translation library with the key. Both are similar, check the existing code to figure it out.
+
+## Key Files and Conventions
+
+**Configuration:**
+- `config.yml.sample` - Example configuration (generated from `config-raw.json`)
+- Environment variables override config file settings
+- Use `pkg/config/` for configuration management
+
+**Code Style:**
+- Go: Standard Go formatting with golangci-lint
+- Vue: ESLint with TypeScript and Vue-specific rules
+- Follow existing patterns for consistency
+
+**Naming Conventions:**
+- Go: Standard Go conventions (PascalCase for exports, camelCase for private)
+- Vue: PascalCase for components, camelCase for composables
+- API endpoints: kebab-case in URLs, camelCase in JSON
+
+**Rights and Permissions:**
+- Always implement Rights interface for new models
+- Use `CanRead`, `CanWrite`, `CanCreate`, `CanDelete` methods
+- Rights are enforced at the model level, not just routes
+
+## Common Gotchas
+
+- Database migrations are irreversible in production - test thoroughly
+- Frontend services must match backend model structure exactly
+- Rights checking is mandatory for all CRUD operations
+- Event listeners in `pkg/*/listeners.go` must be registered properly
+- CORS settings in backend must allow frontend domain
+- API tokens have different scopes - check permissions carefully
+

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md