.cursorrules

# Cursor Rules for Diet Planner Project

## Changelog and Versioning

### Changelog Management

- **Changelog entries are user-facing**, not developer-facing. They describe what changed from the user's perspective.
- **Changelog entries do NOT have a 1:1 relationship with git commits**:
  - Some commits are chores/internal changes that don't need changelog entries
  - Some changelog entries may represent work spanning multiple commits
  - Update the changelog when a feature is "complete" from a user perspective, not after every commit
- After completing a major feature or set of related changes, **always ask the user** if they want to create a git commit and update the changelog
- When updating the changelog:
  - Use [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format
  - Follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
  - Add entries under appropriate sections: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`
  - Update the `[Unreleased]` section with new changes
  - When creating a release, move `[Unreleased]` changes to a new version section with date

### Versioning Rules

- **MAJOR** (x.0.0): Breaking changes, major feature additions
- **MINOR** (0.x.0): New features, backwards compatible
- **PATCH** (0.0.x): Bug fixes, small improvements

### Git Workflow

- **NEVER commit changes unless the user explicitly confirms the feature/fix implemented works correctly**. It is important to commit regularly with clear and descriptive messages, but you should only commit when the user confirmed the next unit of work works correctly, otherwise we run into risks of having mostly commits of broken versions of the codebase.
- Create a git tag using the version number (e.g., `v0.1.0`)
- Commit message format: `feat: description` or `fix: description` or `chore: description`
- Always update CHANGELOG.md before committing

### When to Update Changelog

- New features or major functionality additions (user-visible)
- Significant UI/UX changes
- Breaking changes
- Bug fixes that affect user experience
- Security updates
- Changes that users would notice or care about

### When NOT to Update Changelog

- Internal refactoring without user-visible changes
- Code style/formatting changes
- Development tooling changes (unless they affect users)
- Database schema changes that don't change user-facing behavior
- Bug fixes that users wouldn't notice
- Documentation-only updates (unless significant user-facing docs)
- Dependency updates (unless they introduce new features or fix user-facing bugs)

## Project-Specific Guidelines

### Documentation

- **Keep README.md updated:** After implementing new features, API endpoints, or significant changes, update the README.md to reflect these changes. This includes:
  - New features in the "Features" section
  - New API endpoints in the "API Endpoints" section
  - Updated development notes for new functionality
  - Changes to project structure or architecture
- README.md should always accurately reflect the current state of the project

### Database

- Always use idempotent operations for seed scripts
- Use Drizzle ORM relational queries for complex data fetching
- Remember: seed script only creates templates, not user-specific data

### Authentication

- Use Google OAuth as primary authentication method
- Email is the primary user identifier for account linking

### Design

- Follow modern design principles (Vercel/Cursor style)
- Use shadcn/ui components consistently
- Avoid old-fashioned UI patterns (no required/optional labels, clean forms)
- Week starts on Monday (not Sunday)

### Code Style

- Use TypeScript strictly
- Prefer functional components with hooks
- Keep components focused and reusable
- Use Astro for server-side rendering, React for interactive components