# ShiftPlanner

A single-file employee shift scheduling application for a small team
(a hotel/spa-style operation: the UI references "Therme"). It runs entirely in
the browser — no server, no build step, no install, no account.

Version: **1.0.0** (see `VERSION`)
Canonical source: `src/index.html` (2,789 lines, 136,212 bytes, md5 `37207b2227899603f90c42e59ff1875a`)

## What it does

- **Staff register** — add, edit and delete workers, each with role and
  contracted hours per week.
- **Shift templates** — define reusable shifts with name, start/end time,
  colour and required headcount, then apply a template to a day.
- **Month calendar** — one month at a time, with per-day shift blocks, assigned
  workers, headcount limits (min/max) and free-text day notes.
- **Absence tracking** — record vacation, sick days and days off per worker;
  availability checks respect them.
- **Automatic plan generation** — a step-through generator that fills the month
  for selected workers, honouring:
  - fairness priority (equal number of shifts / equal total hours / equal
    weekend shifts),
  - maximum consecutive working days,
  - minimum rest hours between shifts,
  - maximum workers per shift.
- **Conflict detection** — flags double-booking, rest-period violations and
  consecutive-day overruns, with a conflict badge, "Fix conflicts" and
  "Clear Day" actions.
- **Exports** — CSV of the month's roster, and JSON backup of the whole plan.
- **Import** — restore a previously exported JSON backup.
- **Light/dark theme**.

## What the buyer gets

```
shiftplanner/
├── VERSION                 1.0.0
├── README.md               this file
├── CHANGELOG.md
├── LICENSE
├── src/
│   └── index.html          the complete application (open this)
├── docs/
│   ├── CANONICAL.md        measurement record: why this file is canonical
│   └── USAGE.md            non-technical, step-by-step instructions
└── archive/                four earlier/variant copies, kept for reference
    ├── mindtech__shiftplanner.html
    ├── mindtech__downloads__shiftplanner.html
    ├── mindtech__shiftplanner_v1.3.html
    └── agando__shiftplanner_v1.3.html
```

One file is the whole product. There is nothing to compile and nothing to
deploy beyond copying `src/index.html` somewhere and opening it.

## How to run it offline

1. Copy `src/index.html` to the machine that will use it — a laptop, a USB
   stick, a shared folder, anything.
2. Double-click it, or drag it into any modern browser (Chrome, Edge, Firefox,
   Safari).
3. That's it. The app is fully self-contained.

Verified: the file contains **0** `<script src=…>` tags, **0** `<link>` tags and
**0** `url(…)` asset references. All CSS and JavaScript are inline. Nothing is
fetched from a CDN, so it works with the network cable unplugged and from a
`file://` path.

The optional AI advisor is the only part that talks to anything, and it talks
only to a server you run yourself (see below). With no AI server running, the
panel shows "Not connected (start Ollama)" and every scheduling feature still
works.

### Optional: the AI advisor

The right-hand panel answers questions about the current schedule and can
suggest changes. It uses a local [Ollama](https://ollama.com) instance:

- Default endpoint: `http://localhost:11434`, editable in Settings and stored
  in `localStorage['sp_ai_endpoint']`.
- Calls `GET {endpoint}/api/tags` to check the connection and list models, and
  `POST {endpoint}/api/generate` to answer a question.
- Default model `llama3.2`; the UI also offers `mistral`, `llama3.1`, `phi3`,
  `gemma2` and `minimax-m3:cloud`. The choice is stored in
  `localStorage['sp_ai_model']`.
- No cloud AI service is contacted — there is no OpenAI, Anthropic or Google
  endpoint anywhere in the file.

If you do not want AI at all, ignore the panel; it is inert without a server.

## Where the data lives

**In the browser's `localStorage`, on that machine and in that browser profile.
Nowhere else.** There is no backend, no sync and no telemetry.

| Key | Contents |
|---|---|
| `shiftplanner_v2` | the full application state: workers, shifts, assignments, custom shifts, templates, settings |
| `sp_ai_endpoint` | the AI server URL |
| `sp_ai_model` | the selected AI model |

Consequences worth knowing:

- Clearing site data / "clear browsing history including site data" for this
  file **erases the schedule**. Use **Export JSON** regularly.
- The data does not follow the user to another browser or another computer.
  Move it with **Export JSON** → **Import JSON**.
- Opening the file from a different path or a different browser profile gives a
  different, empty store.

## Archive

`archive/` holds four older or variant copies of the same app, preserved
unmodified for reference. They are **not** part of the product and are not
maintained. Two of them contain a real drag-and-drop scheduler and a
multi-provider AI layer that the canonical build does not have — see
`docs/CANONICAL.md` §3 if you want to port those features forward.