# Population Management

Every citizen is assigned to one of three categories: building worker, tile worker, or construction worker. The player controls building assignments manually. Everything else is auto-optimized.

---

## Three Worker Categories (assignment axis)

| Category | Assignment | Expertise | Notes |
|----------|-----------|-----------|-------|
| **Building workers** | Manual (player sets count per building) | 5 tiers, tech-gated | Produce units, research, culture, equipment |
| **Tile workers** | Auto-assigned from remaining population | 3 tiers, no tech gate | Work terrain for food/production/gold |
| **Construction workers** | Manual (player sets count for build queue) | Masonry track | Build/upgrade buildings and wonders |

### Output-Domain Taxonomy (`mc_core::WorkerCategory`)

Orthogonal to the assignment axis above, every Specialist (and, downstream,
every building-worker slot) is also tagged with one of three **output domains**.
Per-category aggregation, expertise ladders (`p2-56b`), and aura propagation
(`p2-56c`) all key off this taxonomy.

| Domain | Yields | Examples |
|--------|--------|----------|
| **Sustenance**   | food, healing                 | (no Game-1 specialists yet — content gap) |
| **Construction** | production, engineering       | Forge Engineer |
| **Wealth**       | commerce, research, culture   | Tradeswright, Runescribe, Saga Writer, Forge-Chanter, Rune Artisan, Stonewright |

Canonical enum: `mc_core::WorkerCategory { Sustenance, Construction, Wealth }`
serialized as snake_case. JSON values authored on every entry under
`public/resources/specialists/`; missing or unknown variants fail
`tools/validate-game-data.py`.

---

## Building Worker Expertise

Workers assigned to a building gain experience over time. Experience is tracked per building category (military, production, research, etc.) — not per individual.

| Tier | Efficiency | Tech unlock (culture tree) |
|------|-----------|--------------------------|
| Novice | 60% | Default |
| Apprentice | 80% | Default |
| Journeyman | 100% | Apprenticeship |
| Master | 120% + same-tile aura | Guilds |
| Grandmaster | 140% + adjacent-tile aura | Academies |

Without Apprenticeship, all buildings are capped at Apprentice (80%) no matter how long workers have been assigned.

Canonical enum: `mc_core::ExpertiseTier { Novice, Apprentice, Journeyman, Master, Grandmaster }` (snake_case serde, `Ord`-derived for ladder progression). Per-worker XP state lives in `mc_city::expertise::WorkerExpertise`; per-tier `xp_to_next` thresholds and `idle_decay_per_turn` are loaded from `public/games/age-of-dwarves/data/balance/expertise.json`. Per-turn XP earn / idle-decay tick wired into `mc_turn::processor::process_city_production` (p2-56b).

### Aura Effects

Masters boost all same-category buildings on the **same tile**:
- Own building: 120%
- Other same-category buildings on same tile: +10%

Grandmasters boost same-category buildings on the **same tile and all adjacent tiles**:
- Own building: 140%
- Other buildings on same tile: +15%
- Buildings on adjacent tiles: +10%

Auras do not stack. If a building is in range of two Grandmasters, it receives +10% (best wins, not combined).

### Decay Rates

Workers who are idle (building has no active queue) lose experience over time.

| Tier | Base decay (per turn idle) | Turns to drop one tier |
|------|--------------------------|----------------------|
| Novice | None (clamps at 0) | Never |
| Apprentice | 2 XP/turn | ~10 turns |
| Journeyman | 2 XP/turn | ~20 turns |
| Master | 2 XP/turn | ~40 turns |
| Grandmaster | 2 XP/turn | ~80 turns |

The constant `idle_decay_per_turn` lives in `data/balance/expertise.json` (currently `2`); per-tier overrides can be added there without code changes. Utilization-based scaling (next section) is layered on top.

### Utilization-Based Decay

Decay is not binary. It scales with how much of a Master or Grandmaster's aura range is actively producing.

```
effective_decay = base_decay × (1 - utilization)
utilization = active same-category buildings in aura range / total same-category buildings in aura range
```

A Grandmaster covering 6 Barracks where 5 are producing has 83% utilization — decay is nearly zero. The same Grandmaster with all 6 idle decays at full rate.

### Reassignment

Moving workers between buildings resets experience:
- Building worker moved to a different building: **full reset to Novice**

The auto-assignment system always removes the **least experienced** worker when a building needs to shed a slot.

---

## Tile Worker Expertise

Tile workers learn the specific land they work. There are no tech gates — this expertise comes purely from time in place.

| Tier | Yield bonus | Turns on same tile |
|------|------------|-------------------|
| Novice | 0% | 0–5 |
| Experienced | +15% | 6–12 |
| Veteran | +30% | 13+ |

### Terrain Category Rules

Knowledge transfers within terrain categories, not across them.

| Move | Result |
|------|--------|
| Same tile | No loss |
| Different tile, same terrain category | Drop 1 tier |
| Different tile, different terrain category | Full reset to Novice |

**Terrain categories:**

| Category | Terrains |
|----------|---------|
| Farming | Grassland, Plains, Forest |
| Mining | Hills, Mountains, Volcano |
| Aquatic | Lake, Coastal Waters, Inland Sea |
| Specialist | Tundra, Desert, Swamp, Enchanted Forest |

A Veteran miner moved to a different Hill tile drops to Experienced. The same miner moved to a farm resets to Novice.

### Auto-Assignment Priority

When the system assigns tile workers, it:
1. Places the most experienced worker on the tile they have tenure on
2. Fills remaining tiles with best available workers
3. When pulling a tile worker to staff a building, removes the least experienced tile worker first

---

## Construction Workers

Construction workers form a separate pool that builds the city's physical structures. They are manually assigned from the total population.

- More workers = faster construction (diminishing returns beyond 3)
- Expert construction workers build significantly faster than Novices
- Construction expertise decays when no build queue is active
- When a building is upgrading, construction workers do the physical work while the building's assigned workers stay in place (maintaining their experience but producing nothing)

---

## Worker Capacity by Building Level

| Building Level | Max workers |
|---------------|------------|
| Lv1 | 1 |
| Lv2 | 2 |
| Lv3 | 3 (requires Guilds tech) |
| Lv4 | 4 (requires Academies tech) |

---

## Idle Population

Citizens without assignment auto-assign to the best available unworked tile. Unassigned citizens with no viable tiles incur a **happiness penalty** — idle Dwarves are unhappy Dwarves.

Growth that outpaces infrastructure results in wasted citizens. The player who upgrades buildings before population arrives never wastes a turn.

---

## Population Summary UI

The city screen shows three sections:

1. **Building workers** — each building with [-][+] controls, current tier, efficiency bar, queue status
2. **Tile workers** — auto-assigned list showing terrain, tier, and yield
3. **Available** — unassigned citizens and where auto-assign would place them

Hovering [-] on a building shows an impact preview: which worker would leave, their category, where auto-assign would place them, what experience they'd lose, and how it affects aura utilization.