# Agents Rules

## Project Overview

TrainUs is a fitness tracking progressive web application built with:

- **Frontend**: Vue 3 (Composition API) + Vue Router
- **Database**: SQLite WASM (client-side, in-browser)
- **Build tool**: Vite 7
- **Styling**: Custom CSS + Bootstrap Icons
- **i18n**: i18next + i18next-vue (English, French & Danish)
- **Tests**: Playwright (Python) with pytest
- **Formatting**: Prettier

## Project Structure

```
src/                  # All application source code
  components/         # Reusable Vue components
  composables/        # Vue composables (shared logic)
  db/                 # SQLite WASM database layer
  i18n/               # Internationalization config and translations
  router/             # Vue Router configuration
  styles/             # CSS styles
  utils/              # Utility functions
  views/              # Page-level Vue components
  App.vue             # Root component
  main.js             # Application entry point
public/               # Static assets served as-is
tests/                # Playwright (Python) test suite
  conftest.py         # Pytest fixtures (Vite dev server, browser config)
  test_step*.py       # Test files per feature step
docs/                 # Non-website documentation
  tutorials/          # Step tutorials (EN & FR)
  tutorials/codelabs/ # Google Codelabs format (EN & FR)
  decisions-log.md    # Decision log
  plan.md             # Feature plan and progress tracking
  specification.md    # Project specification
website/              # Hugo project site (docs + blog), two separate sections
                       # by audience, each with its own nav entry
  content/docs/       # User docs ("Documentation" in nav). Diataxis split,
                       # both languages: demarrage-rapide/ (tutorial),
                       # guides-pratiques.{en,fr}.md (how-to), user-guide/
                       # (reference), comprendre.{en,fr}.md (explanation).
  content/developers/ # Contributor docs ("Developers"/"Développeurs" in nav):
                       # technical.en.md, technical.fr.md
  content/blog/       # Blog posts (news, release announcements)
```

## Build & Run Commands

- `npm run dev` -- Start Vite dev server
- `npm run build` -- Production build to `dist/`
- `npm run preview` -- Preview production build
- `npm run format` -- Format code with Prettier
- `npm run format:check` -- Check formatting

## Plan

- Prepare a step-by-step plan to implement one feature at a time (do not rush the full application in one shot)
- Validate the plan with me before doing anything
- Validation is required between each step

## Code

Respect these principles:

- KISS (Keep It Simple, Stupid)
- SOLID (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion)
- DRY (Don't Repeat Yourself)
- Minimal impact: prefer small, focused changes over large refactors
- All application source code goes in `src/`
- All new Vue components use Composition API with `<script setup>`
- Use existing composables and utilities before creating new ones

## Documentation

- Keep the decision log updated in `docs/decisions-log.md` with date, decision, and rationale
- Use Mermaid diagrams to illustrate architecture and flows (prefer: flowchart, sequence diagram, state diagram)
- `README.md` at project root presents an overview of the application and how to get started
- All documentation files go in `docs/`
- **Technical Documentation** (`website/content/developers/`, "Developers"/"Développeurs" nav entry):
  - Technical overview (`technical.en.md`): what the app does, tech stack, global architecture
  - Description of each feature with rationale (why this approach, what was considered and rejected)
- **User Documentation** (`website/content/docs/`, "Documentation" nav entry):
  - Diataxis-style split, in both English and French: `demarrage-rapide/`
    (tutorial), `guides-pratiques.{en,fr}.md` (how-to), `user-guide/`
    (reference — kept this name across languages so the bundle pairs as a
    Hugo translation), `comprendre.{en,fr}.md` (explanation). Text-based
    preferred, screenshots where they clarify a screen or flow.
- **Tutorials & Codelabs (for each step):**
  - A tutorial in `docs/tutorials/` explaining what was done (commands, key files, code snippets)
  - Both in English (`_en` suffix) and French (`_fr` suffix)
  - Tutorials and codelabs are optional — only generate when explicitly requested

## Tests

- Tests are written using Playwright in Python (see `tests/requirements.txt` for dependencies)
- The Vite dev server starts automatically via the `app_url` fixture in `tests/conftest.py` on port 5199
- Test files follow the naming convention `test_step<N>_<feature_name>.py`
- Tests are documented with a short description per test function
- **Browser targets**: Firefox (primary), Chromium (must also pass)
- Test both "green" paths (happy flow) and "red" paths (bad inputs, edge cases, error states)
- All test files go in `tests/`
- The dev server is stopped automatically by the pytest fixture after tests complete

## Schema Version

- **Do NOT increment `SCHEMA_VERSION` without asking first.**
- In-place schema changes (adding columns directly in `SCHEMA_SQL`) are acceptable as long as the app has not been released to users.
- A version bump is only needed once a schema has been deployed — at that point, a migration script must accompany the bump. Ask before doing either.

## Definition of Done

Before a step is considered complete, all of the following must be true:

- [ ] Code implemented in `src/`
- [ ] `docs/plan.md` updated to track what is done and what remains
- [ ] Documentation updated (`website/content/developers/technical.en.md`, `website/content/docs/user-guide/index.en.md`, `docs/decisions-log.md`)
- [ ] Tests written and passing on both Firefox and Chromium
- [ ] Manual validation by the user before moving to the next step