breedr/QUICKSTART.md

# BREEDR Quick Start Guide (v0.8.0)

Welcome to BREEDR! This guide will help you get up and running with the most powerful kennel management and pedigree mapping features.

---

## 🚀 Installation & Setup

### 1. The Easy Way (Docker)
Ensure you have Docker and Docker-Compose installed.
```bash
git clone https://git.alwisp.com/jason/breedr.git
cd breedr
docker-compose up -d --build
```
Open your browser to `http://localhost:3000`.

### 2. Manual Development Setup
```bash
# 1. Install project dependencies
npm install

# 2. Start the dev environment (Frontend @ 5173, Backend @ 3000)
npm run dev
```

> **Note:** The database initializes automatically on first boot. No manual migrations are required.

---

## 🐕 Managing Your Kennel

### Adding or Importing Dogs
1. Go to the **Dogs** page.
2. Click **Add New Dog**.
3. Fill in the core details (Name, Registration, Breed, Sex).
4. **Pedigree Mapping**: You can select a Sire and Dam from your existing dogs.
5. **External Dogs**: Check "External Dog" if you are adding an ancestor that isn't in your kennel.

### Champion Tracking
- Use the **Champion Toggle** in the Add/Edit form to mark titled dogs.
- They will appear with a `✪` star in dropdowns and display a gold badge on their profile.
- Their offspring will automatically display the "Champion Bloodline" badge.

---

## 🧬 Breeding Tools

### 1. Pedigree Visualization
- Click **Pedigree** on any dog detail page.
- **Ancestors View**: Default interactive 5-generation tree.
- **Descendants View**: Toggle the switch in the header to see the "Reverse Pedigree" (offspring lineage).
- Use the mouse wheel or on-screen buttons to zoom and pan.

### 2. Trial Pairing Simulator
- Go to the **Pairing Simulator** via the flask icon in the navbar.
- Select a potential Sire and Dam.
- **COI Calculation**: Instantly see the Wright's Inbreeding Coefficient.
- **Ancestry Check**: The system flags common ancestors and provides a risk badge (Low < 5%, Moderate 5-10%, High > 10%).

### 3. Heat Cycle Calendar
- Use the **Calendar** to track female heat cycles.
- **Phase Colors**: Automatically segments cycles into Proestrus, Optimal, Late, and Diestrus.
- **Projected Whelping**: Log a breeding date to see a indigo "Whelping Window" and expected due dates directly on the main calendar grid.

---

## ⚙️ Kennel Customization
- Visit the **Settings** page.
- Configure your Kennel Name, Tagline, Address, and Contact info.
- This information updates your site branding and navbar automatically.

---

## ❓ Troubleshooting
- **COI shows 0.00%?**: Ensure you have both parents mapped and that they have shared ancestors.
- **Image not loading?**: Ensure `br-logo.png` is in the `static/` folder for branding.
- **Database "No such column"?**: Simply restart the app; the auto-init logic will fix the schema.

---
**Happy Breeding! 🐶**