## ADDED Requirements

### Requirement: Toggle Expert Mode
The system SHALL provide a toggle switch on the Capacity Planning page that enables or disables Expert Mode. The toggle SHALL be persisted in `localStorage` under the key `headroom.capacity.expertMode` so the user's preference survives page reloads.

#### Scenario: Toggle defaults to off
- **WHEN** a user visits the Capacity Planning page for the first time
- **THEN** Expert Mode is off and the standard calendar view is shown

#### Scenario: Toggle persists across reloads
- **WHEN** a user enables Expert Mode and reloads the page
- **THEN** Expert Mode is still enabled and the grid view is shown

#### Scenario: Toggle is right-aligned on the tabs row
- **WHEN** the Capacity Planning page is rendered
- **THEN** the Expert Mode toggle appears right-aligned on the same row as the Calendar, Summary, Holidays, and PTO tabs

#### Scenario: Switching mode with unsaved changes warns user
- **WHEN** a user has dirty (unsaved) cells in the Expert Mode grid
- **AND** the user toggles Expert Mode off
- **THEN** the system shows a confirmation dialog: "You have unsaved changes. Discard and switch?"
- **AND** if confirmed, changes are discarded and the calendar view is shown

---

### Requirement: Display Expert Mode planning grid
The system SHALL render a dense planning grid when Expert Mode is enabled. The grid SHALL show all active team members as rows and all days of the selected month as columns.

#### Scenario: Grid shows all active team members
- **WHEN** Expert Mode is enabled for a given month
- **THEN** each active team member appears as a row in the grid
- **AND** inactive team members are excluded

#### Scenario: Grid shows all days of the month as columns
- **WHEN** Expert Mode is enabled for February 2026
- **THEN** the grid has 28 columns (one per calendar day)
- **AND** each column header shows the day number

#### Scenario: Weekend columns are visually distinct
- **WHEN** the grid is rendered
- **THEN** weekend columns (Saturday, Sunday) are visually distinguished (e.g. muted background)

#### Scenario: Holiday columns are visually distinct
- **WHEN** a day in the month is a company holiday
- **THEN** that column header is visually marked as a holiday

#### Scenario: Grid loads existing availability data
- **WHEN** Expert Mode grid is opened for a month where availability overrides exist
- **THEN** each cell pre-populates with the stored token matching the saved availability value

---

### Requirement: Cell token input and validation
The system SHALL accept exactly the following tokens in each grid cell: `H`, `O`, `0`, `.5`, `0.5`, `1`. Any other value SHALL be treated as invalid.

#### Scenario: Valid token accepted on blur
- **WHEN** a user types `1` into a cell and moves focus away
- **THEN** the cell displays `1` and is marked valid

#### Scenario: Valid token `.5` normalized on blur
- **WHEN** a user types `.5` into a cell and moves focus away
- **THEN** the cell displays `0.5` and is marked valid with numeric value `0.5`

#### Scenario: `H` and `O` accepted on any date
- **WHEN** a user types `H` or `O` into any cell (weekend, holiday, or working day)
- **THEN** the cell is marked valid with numeric value `0`
- **AND** the display shows the typed token (`H` or `O`)

#### Scenario: Invalid token marked red on blur
- **WHEN** a user types `2` or `abc` or any value not in the allowed set into a cell and moves focus away
- **THEN** the cell border turns red
- **AND** the raw text is preserved so the user can correct it

#### Scenario: Submit disabled while invalid cell exists
- **WHEN** any cell in the grid has an invalid token
- **THEN** the Submit button is disabled

#### Scenario: `0` auto-renders as `O` on weekend column
- **WHEN** a user types `0` into a cell whose column is a weekend day and moves focus away
- **THEN** the cell displays `O` (not `0`)
- **AND** the numeric value is `0`

#### Scenario: `0` auto-renders as `H` on holiday column
- **WHEN** a user types `0` into a cell whose column is a company holiday and moves focus away
- **THEN** the cell displays `H` (not `0`)
- **AND** the numeric value is `0`

---

### Requirement: Live KPI bar in Expert Mode
The system SHALL display a live KPI bar above the grid showing team-level Capacity (person-days) and Projected Revenue, updating in real time as cell values change.

#### Scenario: KPI bar shows correct capacity on load
- **WHEN** Expert Mode grid loads for a month
- **THEN** the KPI bar shows total team capacity in person-days matching the sum of all members' numeric cell values

#### Scenario: KPI bar updates when a cell changes
- **WHEN** a user changes a valid cell from `1` to `0.5`
- **THEN** the KPI bar immediately reflects the reduced capacity and revenue without a page reload

#### Scenario: Invalid cells excluded from KPI totals
- **WHEN** a cell contains an invalid token
- **THEN** that cell contributes `0` to the KPI totals (not `null` or an error)

#### Scenario: Projected Revenue uses hourly rate and hours per day
- **WHEN** the KPI bar calculates projected revenue
- **THEN** revenue = SUM(member capacity in person-days × hourly_rate × 8 hours/day) for all active members

---

### Requirement: Batch save availability from Expert Mode
The system SHALL allow saving all pending cell changes in a single batch operation via a Submit button.

#### Scenario: Submit saves all dirty valid cells
- **WHEN** a user has changed multiple cells and clicks Submit
- **THEN** the system sends a single batch request with all dirty cell values
- **AND** on success, all dirty flags are cleared and a success toast is shown

#### Scenario: Submit is disabled when no dirty cells exist
- **WHEN** no cells have been changed since the last save (or since load)
- **THEN** the Submit button is disabled

#### Scenario: Submit is disabled when any invalid cell exists
- **WHEN** at least one cell contains an invalid token
- **THEN** the Submit button is disabled regardless of other valid dirty cells

#### Scenario: Submit failure shows error
- **WHEN** the batch save API call fails
- **THEN** the system shows an error alert
- **AND** dirty flags are preserved so the user can retry

#### Scenario: Batch endpoint validates each availability value
- **WHEN** the batch endpoint receives an availability value not in `[0, 0.5, 1]`
- **THEN** the system returns HTTP 422 with a validation error message

---

### Requirement: Batch availability API endpoint
The system SHALL expose `POST /api/capacity/availability/batch` accepting an array of availability updates for a given month.

#### Scenario: Batch endpoint saves multiple updates
- **WHEN** a POST request is made to `/api/capacity/availability/batch` with a valid month and array of updates
- **THEN** the system upserts each `{team_member_id, date, availability}` entry
- **AND** returns HTTP 200 with `{ "data": { "saved": <count>, "month": "<YYYY-MM>" } }`

#### Scenario: Batch endpoint invalidates cache once
- **WHEN** a batch save completes for a given month
- **THEN** the month-level capacity cache is flushed exactly once (not once per row)

#### Scenario: Batch endpoint rejects invalid team_member_id
- **WHEN** a batch request contains a `team_member_id` that does not exist
- **THEN** the system returns HTTP 422 with a validation error

#### Scenario: Batch endpoint rejects invalid availability value
- **WHEN** a batch request contains an `availability` value not in `[0, 0.5, 1]`
- **THEN** the system returns HTTP 422 with a validation error

#### Scenario: Empty batch is a no-op
- **WHEN** a POST request is made with an empty `updates` array
- **THEN** the system returns HTTP 200 with `{ "data": { "saved": 0, "month": "<YYYY-MM>" } }`
