Skill: seed-inventory

# Skill: seed-inventory

## Purpose

Track seed lots, record germination tests, log plantings, manage variety library, and identify which seeds need reordering or disposal. Understand viability calculations and germination thresholds.

## Data Model Quick Reference

### Viability status calculation

```
age_years = (today - purchase_date) / 365.25
fresh:   age_years <= viability_years / 2
aging:   age_years > viability_years / 2 AND age_years <= viability_years
expired: age_years > viability_years
```

### Germination thresholds (category defaults)

| Category | Minimum % |
|----------|-----------|
| vegetables | 75 |
| herbs | 70 |
| flowers | 65 |
| grains | 80 |
| cover_crops | 75 |
| other | 70 |

A variety can have a custom `min_germination_pct` that overrides the category default.

### Lot status values

| Status | Meaning |
|--------|---------|
| active | Normal, plantable |
| depleted | quantity_grams = 0 |
| expired | Past viability date |
| quarantine | Manual hold, do not plant |

### Reorder trigger conditions

A lot appears in the reorder list if:
- `quantity_grams <= variety.reorder_threshold_grams`, OR
- `status = 'expired'`

## API Quick Reference

### Seed Varieties

```
GET    /api/varieties               list; filter: category, subcategory, search
GET    /api/varieties/:id           detail with lot summary
POST   /api/varieties               create: { name, category, ... }
PUT    /api/varieties/:id           update
DELETE /api/varieties/:id           delete (blocked if lots exist - returns 409)
```

#### Variety create body

```json
{
  "name": "Roma Tomato",
  "scientific_name": "Solanum lycopersicum",
  "category": "vegetables",
  "subcategory": "tomato",
  "supplier": "Seeds of Change",
  "viability_years": 3,
  "reorder_threshold_grams": 50,
  "min_germination_pct": null,
  "days_to_germination": 8,
  "days_to_maturity": 75,
  "planting_depth_mm": 6,
  "spacing_cm": 45,
  "notes": "Determinate paste type..."
}
```

### Seed Lots

```
GET    /api/lots                    list; filter: variety_id, status, low_stock=1, expiring_soon=:days
GET    /api/lots/:id                detail with germination tests and planting records
POST   /api/lots                    create lot
PUT    /api/lots/:id                update lot
DELETE /api/lots/:id                delete (blocked if planting records exist - returns 409)
POST   /api/lots/:id/photo          upload photo (multipart/form-data, field: photo, max 5MB)
```

#### Lot create body

```json
{
  "variety_id": "uuid",
  "lot_number": "TOM-2025-01",
  "purchase_date": "2025-07-20",
  "source": "Baker Creek",
  "quantity_grams": 100,
  "price_paid": 8.95,
  "storage_location": "Cool room shelf 1",
  "notes": ""
}
```

#### GET /api/lots response includes computed fields

```json
{
  "id": "uuid",
  "lot_number": "TOM-2025-01",
  "quantity_grams": 84,
  "status": "active",
  "age_days": 127,
  "viability_status": "fresh",
  "germination_rate": 89,
  "germination_flag": "ok",
  "is_low_stock": false
}
```

### Germination Tests

```
GET    /api/germination             list; filter: lot_id, variety_id
GET    /api/germination/:id         single test
POST   /api/germination             record test
DELETE /api/germination/:id         delete test
```

#### Germination test create body

```json
{
  "lot_id": "uuid",
  "test_date": "2025-07-18",
  "seeds_tested": 35,
  "seeds_germinated": 31,
  "days_to_germinate": 8,
  "temperature_c": 22,
  "notes": "Germination paper method"
}
```

Computed rate: `31 / 35 * 100 = 88.57%`. After saving, if this is the most recent test for the lot, the lot's `germination_flag` is updated.

### Planting Records

```
GET    /api/plantings               list; filter: lot_id, field_or_bed, date_from, date_to
GET    /api/plantings/:id           single record
POST   /api/plantings               record planting (subtracts quantity from lot)
DELETE /api/plantings/:id           delete (adds quantity back to lot)
```

#### Planting create body

```json
{
  "lot_id": "uuid",
  "planting_date": "2025-07-20",
  "field_or_bed": "Greenhouse bed 2",
  "quantity_used_grams": 15,
  "area_sqm": 10,
  "transplanted": 1,
  "notes": "Fall crop start"
}
```

Validation: `quantity_used_grams` must not exceed `lot.quantity_grams`. Returns 400 if quantity is insufficient.

After saving: lot `quantity_grams` decreases by `quantity_used_grams`. If resulting quantity = 0, lot `status` becomes `depleted`.

### Analytics

```
GET    /api/analytics/reorder-list            lots needing reorder
GET    /api/analytics/expiring-soon?days=90   lots expiring within N days
GET    /api/analytics/stock-summary           grams per category and variety
GET    /api/analytics/germination-rates       avg rate per variety, flagged if below threshold
GET    /api/analytics/planting-history        grams used per variety per month
```

## Common Workflows

### Check if a lot is safe to plant

1. `GET /api/lots/:id`
2. Verify: `status = 'active'` (not expired, depleted, or quarantine)
3. Verify: `viability_status` is `fresh` or `aging` (not `expired`)
4. Check: `germination_flag` is `ok` (not `poor`)
5. Check: `quantity_grams >= quantity_you_plan_to_use`

### Find all lots that need attention

```
GET /api/analytics/reorder-list
GET /api/analytics/expiring-soon?days=90
GET /api/lots?low_stock=1
```

### Record a complete planting workflow

1. `GET /api/lots/:id` - confirm quantity available
2. `POST /api/plantings` - log the planting with quantity
3. `GET /api/lots/:id` - confirm updated quantity

### Identify poor germination lots

```
GET /api/germination?lot_id=:id
```

If most recent test's rate < variety category minimum, the lot is poor. Consider:
- Re-testing with fresh sample
- Increasing seeding rate by 1.5x as compensation
- Marking lot for disposal if expired and poor

### Calculate days until a lot expires

```
expiry_date = purchase_date + viability_years * 365.25
days_remaining = expiry_date - today
```

Use `GET /api/analytics/expiring-soon?days=90` for a pre-calculated list.