Admin: validate raw emoji input instead of trimming it

The backend rejects whitespace in emoji keys, so an entry like " 🐶 "
must fail the picker's validation rather than be saved as emoji:🐶.
Only an exactly empty field clears the icon; whitespace-only text now
shows the invalid-emoji error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,27 @@
+# Keep the image build context minimal: only api/ and the bundled
+# custom_components/nestquest/core/ are copied (see the Dockerfile);
+# everything else — VCS state, virtualenvs, tests, the frontend, and
+# any local secrets or database files — never enters the build.
+.git
+.gitignore
+.venv
+**/__pycache__
+**/*.py[cod]
+.pytest_cache
+**/*.db
+**/*.db-wal
+**/*.db-shm
+# Local configuration — never baked into an image.
+.env
+**/.env
+deploy
+design
+docs
+frontend
+orchestration_tests
+scripts
+templates
+tests
+uv.lock
+hacs.json
+*.md

.gitignore

@@ -5,3 +5,16 @@ __pycache__/
 .pytest_cache/
 *.metadata.json
 frontend/node_modules/
+
+# Feature 17 (API deployment): local secret config and runtime data
+# are never committed — compose reads deploy/.env; SQLite/WAL sidecar
+# files are container/volume artifacts.
+.env
+**/.env
+*.db
+*.db-wal
+*.db-shm
+
+# Dedicated Litestream SFTP backup keypair — lives only on the API box.
+deploy/*key*
+deploy/litestream_key*

.opencode/agents/approver.md

@@ -0,0 +1,32 @@
+---
+description: Independently verify NestQuest merge gates and merge approved heads
+mode: primary
+model: openrouter/deepseek/deepseek-v4.1-flash
+permission:
+  edit: deny
+  write: deny
+  task: deny
+  bash:
+    "*": deny
+    "/home/overseer/.local/share/nestquest-controller/scripts/nq-approve-merge *": allow
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+    "/home/overseer/.local/share/nestquest-controller/*": allow
+---
+
+You are the NestQuest feature-to-dev approver, separate from the controller and
+developer sessions. Verify the current PR head equals the independently
+reviewed and approved commit,
+required checks pass, blocking findings are resolved, branch protection is
+satisfied, and Maestro has accurate links. Use only the approver Gitea identity
+for the merge. Do not change code or approve a stale head. Use only the
+installed nq-approve-merge launcher for Gitea inspection and merging. Merge
+only into dev; never merge into main. If any gate is
+missing, refuse the merge and give the exact missing evidence. Report the PR,
+reviewed head, resulting merge commit, and target branch.
+
+Broker syntax: `nq-approve-merge inspect PR_NUMBER` or
+`nq-approve-merge merge PR_NUMBER REVIEWED_HEAD REVIEW_FILE`. Run one broker
+command per Bash call. The broker validates the current PR and review again
+before merging; do not substitute an ad hoc Gitea command.

.opencode/agents/developer.md

@@ -0,0 +1,21 @@
+---
+description: Implement one assigned NestQuest task in an isolated worktree
+mode: primary
+model: openrouter/z-ai/glm-5.3-flash
+permission:
+  task: deny
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+---
+
+You are the NestQuest development agent. Implement only the assigned Maestro
+task in the supplied worktree. Follow the task's acceptance criteria and the
+repository's instructions. Run relevant tests, commit on the task branch, and
+report the commit and test results. Keep changes inside the assigned worktree.
+Do not approve your own pull request. You may merge your task PR into the
+feature branch only after the independent reviewer approved its exact current
+head and the controller verified every task merge gate. Never merge a feature
+into dev or a release into main. Do not start another task, change role, or
+use another model. Do not read or print credential files except when the
+approved task merge requires the existing Gitea development credential.

.opencode/agents/orchestrator.md

@@ -0,0 +1,60 @@
+---
+description: Reconcile NestQuest work and dispatch the next verified action
+mode: primary
+model: openrouter/deepseek/deepseek-v4.1-flash
+permission:
+  doom_loop: deny
+  task: deny
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+    "/home/overseer/.local/share/opencode/tool-output/*": allow
+---
+
+You are the NestQuest controller. Work in the NestQuest repository. Maestro is
+the source of truth for feature and task state; CTXD is the source of truth for
+project instructions. At the start of every invocation, read the current
+NestQuest context in CTXD, including OPENCODE-ORCHESTRATOR-PROMPT.MD, then
+reconcile it with Maestro, Git, pull requests, and checks before dispatching.
+Follow the review, identity, and branch rules in that prompt.
+If the CTXD project or prompt is unavailable, do not dispatch or merge work;
+report the missing source and end with ORCHESTRATOR_STATE: BLOCKED.
+
+One invocation is a controller tick, not an entire feature lifetime. Prefer a
+state-changing action over another identical status query. Never repeat an
+unchanged tool call three times. If work is asynchronous, wait or inspect a
+specific changed result. Do not claim that you are continuing while ending
+the turn without naming the next action.
+
+The NESTQUEST_CONTROL_HOME environment variable names the installed launchers
+(normally /home/overseer/.local/share/nestquest-controller).
+For implementation, run "$NESTQUEST_CONTROL_HOME/scripts/nq-agent" with role
+developer, a task worktree, title, and task prompt file. For independent
+review, run "$NESTQUEST_CONTROL_HOME/scripts/nq-review" with the worktree,
+feature base ref, exact head ref, review prompt file, PR number, and an output
+file under /tmp/opencode. It publishes an exact-head Gitea approval only after
+Claude approves. The developer may merge
+a task PR into its feature branch only after independent approval of the exact
+head and verification of every task gate. For feature-to-dev approval and
+merge, run "$NESTQUEST_CONTROL_HOME/scripts/nq-agent" with role approver in
+a separate session after the independent review. Save the Claude review output
+in a file under /tmp/opencode and give that file and its reviewed head to the
+approver. Never substitute a different model or reviewer silently.
+
+When a feature is integrated into dev, reconcile Maestro, then immediately
+select and dispatch the next eligible feature. Feature completion is a
+transition, not the end of the controller's job. A release awaiting Joshua's
+main merge does not prevent work on independent eligible features.
+
+End each invocation with exactly one final line using one of these values:
+
+ORCHESTRATOR_STATE: CONTINUE
+ORCHESTRATOR_STATE: QUIESCENT
+ORCHESTRATOR_STATE: BLOCKED
+
+Use CONTINUE when there is any eligible or in-flight work; include the feature,
+task, and next concrete action immediately above the final line. Use QUIESCENT
+only after verifying no eligible or in-flight work remains in Maestro and the
+repository. Use BLOCKED only when a specific decision or access is required;
+include evidence and the needed human action. If you cannot establish the
+state, use BLOCKED. Never emit a success claim based only on a child's summary.

.opencode/agents/terminal-orchestrator.md

@@ -0,0 +1,31 @@
+---
+description: Run the NestQuest orchestration loop in this foreground terminal
+mode: primary
+model: openrouter/deepseek/deepseek-v4.1-flash
+permission:
+  doom_loop: deny
+  task: deny
+  external_directory:
+    "*": ask
+    "/tmp/opencode/*": allow
+    "/home/overseer/.local/share/opencode/tool-output/*": allow
+---
+
+You are the foreground NestQuest orchestrator. The user explicitly launched
+this session to run the development queue now. Read the supplied terminal
+orchestrator prompt and current CTXD project context, but follow the
+FOREGROUND TERMINAL RUNTIME for this session instead of CTXD's service runtime
+section.
+
+Continuously reconcile Maestro, CTXD, Git, pull requests, checks, and child
+agent results. Execute the next useful transition in this same session. Do
+not finish after dispatch, review, remediation, or merge while eligible work
+remains. Use the installed role launchers for developer, reviewer, and
+approver isolation. Never start or wait for the systemd controller service.
+Never repeat an identical unchanged tool call three times; wait on the
+specific child or inspect newly changed evidence.
+
+End only at a global terminal condition, an explicit user stop, a genuine
+global access/decision block with no other eligible work, or a host-forced
+yield. On a forced yield, return a continuation checkpoint that can be
+resumed in the same OpenCode session.

.opencode/commands/start-development.md

@@ -0,0 +1,11 @@
+---
+description: Run the NestQuest orchestrator now in this OpenCode terminal
+agent: terminal-orchestrator
+---
+
+Run the NestQuest project queue now in this foreground OpenCode session.
+Read the current CTXD prompt and Maestro state, but use the FOREGROUND
+TERMINAL RUNTIME instead of the service runtime. Reconcile repository and
+pull-request state, then execute CONTROLLER_TICK repeatedly until a global
+terminal condition, explicit user stop, genuine global block, or host-forced
+yield. Do not start or wait for the systemd controller.

Dockerfile

@@ -0,0 +1,51 @@
+# Container image for the NestQuest API service (Feature 17).
+#
+# Build context is the REPOSITORY ROOT (compose sets it), because the
+# API loads the bundled domain layer from
+# custom_components/nestquest/core/ by file location
+# (api/nestquest_core.py): the image must carry both api/ and the
+# bundled core at their relative positions.  Everything else in the
+# repository is excluded via .dockerignore.
+#
+# Multi-stage so no pip/build toolchain survives into the runtime:
+# the builder installs the deployable's own manifest
+# (api/requirements.txt) into a staging prefix and the runtime copies
+# only the installed packages.  The service runs as a non-root user;
+# the SQLite database lives on the mounted volume at
+# /var/lib/nestquest (compose supplies NESTQUEST_DB_PATH pointing
+# there — configuration is environment-supplied, never baked in).
+#
+# Both stages use the same base image pinned by digest, and
+# api/requirements.txt pins exact versions, so a rebuild reproduces
+# the deployed image instead of floating to whatever is newest.
+FROM python:3.12-slim@sha256:2f17fc044b579bab302c2e8054d3a686e2cb9a83de48e70534b94cd8ebbe06a9 AS builder
+
+COPY api/requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir --prefix=/install -r /tmp/requirements.txt
+
+FROM python:3.12-slim@sha256:2f17fc044b579bab302c2e8054d3a686e2cb9a83de48e70534b94cd8ebbe06a9
+
+# The staged dependency install from the builder (no pip, no wheels).
+COPY --from=builder /install /usr/local
+
+# /app is the repository-root equivalent: api/ resolves imports as
+# ``api.*`` and nestquest_core.py finds the bundled core one level up.
+WORKDIR /app
+COPY api/ ./api/
+COPY custom_components/nestquest/core/ ./custom_components/nestquest/core/
+
+# Non-root runtime user; owns the database volume mount point.
+RUN useradd --system --create-home --home-dir /home/nestquest nestquest \
+    && mkdir -p /var/lib/nestquest \
+    && chown nestquest:nestquest /var/lib/nestquest
+USER nestquest
+
+ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
+
+# The database path and the service token / OIDC settings are supplied
+# by the environment (compose env_file), never committed into the image.
+ENV NESTQUEST_DB_PATH=/var/lib/nestquest/nestquest.db
+VOLUME /var/lib/nestquest
+
+EXPOSE 8080
+CMD ["uvicorn", "--factory", "api.app:create_app", "--host", "0.0.0.0", "--port", "8080"]

ORCHESTRATION.md

@@ -0,0 +1,77 @@
+# NestQuest foreground orchestrator
+
+OpenCode 1.18.32 loads the named agents from `.opencode/agents/`. Their
+models match the current NestQuest CTXD prompt: DeepSeek V4.1 Flash for the
+foreground orchestrator and approver, and GLM 5.3 Flash for development.
+Run orchestration directly from a shell:
+
+```bash
+nq-orchestrate
+nq-orchestrate mission.md
+cat mission.md | nq-orchestrate -
+nq-orchestrate --print-prompt > nestquest-orchestrator.md
+```
+
+The launcher renders the project prompt with the foreground terminal runtime,
+stops the dormant legacy service, refuses immediately when another NestQuest
+TUI is open, and then replaces itself with OpenCode using
+`terminal-orchestrator`. There is no background polling process and no wait
+for a controller tick. Exit or interrupt the TUI to stop the foreground run;
+resume that OpenCode session when a host-forced yield needs continuation.
+
+`scripts/nq-agent` launches developer and approver sessions with fixed agent
+definitions and no `--auto` flag. Headless OpenCode runs use `--pure` so the
+global idle-notification plugin does not notify on every controller tick.
+The approver's shell permission permits only the installed
+`nq-approve-merge` broker for Gitea. That broker requires exact-head
+Claude approval evidence, an exact-head Gitea approval by `review_agent`,
+the `dev` target, a mergeable PR, and passing configured checks before it
+requests a squash merge with Gitea's atomic `head_commit_id` guard.
+`scripts/nq-review` launches the independent
+Claude review in a noninteractive read-only session in the task worktree,
+checks the head again afterward, saves
+the output under `/tmp/opencode`, and posts the Gitea approval.
+The approver verifies the reviewed head again before a merge.
+
+The terminal launcher uses a stable copy of this configuration and scripts
+at `/home/overseer/.local/share/nestquest-controller`; it does not depend on
+which task branch is checked out in the primary NestQuest directory. Install
+that copy, run `scripts/nq-controller --check`, and verify the OpenCode
+agents (terminal-orchestrator, developer, and approver)
+with `opencode debug agent <name>` while `OPENCODE_CONFIG_DIR` points at the
+installed `.opencode` directory. Install `scripts/nq-orchestrate` in
+`~/.local/bin/`. For the global slash command, also install
+`.opencode/agents/terminal-orchestrator.md` under
+`~/.config/opencode/agents/` and
+`deploy/opencode-global-commands/start-nestquest-development.md` under
+`~/.config/opencode/commands/`. The old `nestquest-controller.service` remains static and
+inactive only for migration safety; foreground launch stops it.
+
+Inside an already-open OpenCode TUI, `/start-development` (or the global
+`/start-nestquest-development`) switches to the same foreground
+`terminal-orchestrator` behavior immediately. The shell launcher is the
+preferred entry point when supplying a mission prompt file.
+
+`templates/ORCHESTRATOR-PROMPT.template.md` and
+`templates/nestquest.profile.json` make the current CTXD cycle prompt
+adaptable to another project. See `templates/README.md` before publishing a
+rendered prompt for a new project.
+
+The CTXD preflight reads the configured HTTP/MCP server's NestQuest prompt.
+It deliberately does not inspect `/home/overseer/.ctx/ctxd.db`, which belongs
+to a different local store and lacks this project.
+
+All four agent credentials are currently readable by the same Unix account.
+The Gitea review and merge gates enforce normal workflow sequencing, but
+they are not a hard isolation boundary against a process running as that
+account. Strong isolation requires separate OS identities and protected
+credentials for the controller, reviewer, and approver.
+
+The terminal runtime repeatedly executes CONTROLLER_TICK within the foreground
+session. Neither a feature merge nor a progress report ends the run while
+eligible work remains. A host-forced yield returns a continuation checkpoint
+that can be resumed in the same OpenCode session.
+
+Do not put tokens in this repository or in unit files. Existing OpenCode MCP
+connections supply CTXD and Maestro. Rotate those MCP tokens as a coordinated
+operation across every consumer before revoking the old values.

README.md

@@ -159,9 +159,50 @@ Sensors the automations read: `sensor.nestquest_<child>_quests_due_today`
 
 Run these steps in order to display the NestQuest panel on a TouchHub
 wall device. The panel is an HA Lovelace dashboard, so the kiosk browser
-is simply a Home Assistant client.
+is simply a Home Assistant client. The path below is zero-config: the
+integration registers its panel dashboard itself on setup, so no YAML
+and no hand-built views are involved.
 
-1. **Create a dedicated kiosk user.** In *Settings → People → Users*, add
+1. **Install the integration and add the config entry.** Install
+   NestQuest via HACS or manually (see Installation above) and restart
+   Home Assistant. Then, in *Settings → Devices & Services*, click
+   **Add Integration**, search for **NestQuest**, and submit the flow —
+   it has no fields; it just creates the single config entry. Then open
+   the entry, click **Configure**, and fill the panel-plane API
+   connection in the options flow:
+
+   - **NestQuest API base URL** — the full `http://host:port` URL of
+     your NestQuest API service (default `http://127.0.0.1:8000`).
+   - **Panel service token** — the token the panel presents to the API
+     service as its Bearer credential. It may stay empty until you have
+     one; a pasted token must be unpadded.
+
+   The form's remaining fields (panel idle timeout, coordinator update
+   interval, last-good snapshot staleness) have defaults that serve the
+   panel and need no change here.
+
+2. **The panel dashboard appears automatically.** On setup the
+   integration registers one storage-mode Lovelace dashboard: a sidebar
+   entry titled **NestQuest** at the URL path `/nestquest`, whose stored
+   config is nothing but the **`custom:nestquest-party` strategy**
+   (`strategy: { type: custom:nestquest-party }`). The strategy
+   generates the views at render time from the household roster:
+
+   - **The Party** — the party-board view at `/nestquest/party`; the
+     dashboard root `/nestquest` shows it as the first view.
+   - one quest-log view per child at `/nestquest/<child-slug>`
+     ("Ada's Quest Log", …), in roster order.
+
+   Nothing is hand-configured: no YAML, no manual views, no
+   `child_order`, no `quest_log_path`/`board_path` — the board and the
+   quest logs compute their navigation paths from the dashboard's own
+   URL — and every generated view is already in **Panel** layout (see
+   the two constraints below). If the Lovelace surfaces are unavailable
+   (for example when Lovelace runs in YAML mode), setup logs a warning
+   and skips the registration; create the dashboard manually with the
+   same strategy as described in the manual alternative below.
+
+3. **Create a dedicated kiosk user.** In *Settings → People → Users*, add
    a new user for the wall device. Make it **non-admin**, and ensure it is
    not in the NestQuest admin allowlist. The allowlist blocks the NestQuest
    **admin** operations — `uncomplete_quest`, `create_quest_definition`,
@@ -174,66 +215,101 @@ is simply a Home Assistant client.
    Assistant user it may also reach other permitted Home Assistant entities
    and services.
 
-2. **Build a dashboard with only the NestQuest panel cards.** Create a
-   Lovelace dashboard whose **URL slug is `nestquest`** (Settings →
-   Dashboards → Edit → URL slug). A functional panel needs **two** views
-   in that dashboard, each with its own card config from
-   `design/ENTITIES-AND-SERVICES.md` §4. Give the views these exact URL
-   paths (the path segment after the dashboard slug):
+4. **Open the dashboard and point TouchHub at it.** Open
+   `http://<home-assistant>/nestquest` in a browser first and check the
+   party board renders with your children's crests. Then, in the
+   TouchHub launcher, add the **Home Assistant Lovelace** app to the
+   dock and paste the dashboard URL from step 2 — the dashboard root,
+   `/nestquest` (TouchHub loads that URL directly as the kiosk landing
+   page). Set TouchHub **Auto-Return** to a value GREATER than the
+   quest log's `idle_return_seconds` (default 40s) — recommend **60s or
+   higher**. If Auto-Return is at or below 40s, TouchHub returns to its
+   launcher before the quest log's idle return can navigate back to the
+   party board.
 
-   - **View 1 path `board`** (URL `/nestquest/board`) — party board
-     (`type: custom:nestquest-party-board-card`): the household quest
-     board. Set `weather_entity` (optional; the dock falls back to
-     date/time), `quest_log_path: /nestquest/log` (the view the crest tap
-     navigates to), and `child_order: [slug1, slug2, slug3]` listing each
-     child's slug in display order.
-
-   - **View 2 path `log`** (URL `/nestquest/log`) — quest log
-     (`type: custom:nestquest-quest-log-card`): the per-child quest screen
-     the party board hops to. Set `board_path: /nestquest/board` (the
-     party-board view to return to), `weather_entity`,
-     `idle_return_seconds` (must be shorter than TouchHub Auto-Return),
-     `confirm_timeout_seconds`, and `complete_screen_seconds`. The quest
-     log reads the selected child's slug from the view's URL path, so the
-     board → log hop is a plain Lovelace navigation.
-
-    Each view's layout MUST be set to **Panel** (Edit Dashboard → pencil on the
-    view → View type: Panel). Home Assistant's default Masonry layout constrains
-    the 1080px-tall NestQuest card to a narrow column; Panel (single-card)
-    layout is what renders the card full-screen at 1920×1080.
-
-    The dashboard contains only the NestQuest panel card for each view —
-    no other cards, no admin controls.
-
-   The `quest_log_path` and `board_path` values must match the dashboard
-   slug and view paths above: `/<slug>/<view>`. If you chose `nestquest`
-   as the dashboard slug with view paths `board` and `log`, the card
-   configs are already correct. If you pick different names, substitute
-   your actual paths in **both** card configs — e.g. a dashboard slug
-   `chores` with view paths `main` and `history` needs
-   `quest_log_path: /chores/history` and `board_path: /chores/main`.
-   Navigation between the two views fails (the crest tap or back button
-   lands on a 404) if the card config paths do not match the dashboard
-   slug and view paths exactly.
-
-   See `design/ENTITIES-AND-SERVICES.md` §4 for the full card YAML.
-
-3. **Point TouchHub at it.** In the TouchHub launcher, add the **Home
-   Assistant Lovelace** app to the dock and paste the dashboard URL from
-   step 2 — the party-board view URL, e.g. `/nestquest/board` (TouchHub
-   loads that URL directly as the kiosk landing page). Set TouchHub
-   **Auto-Return** to a value GREATER than the quest log's
-   `idle_return_seconds` (default 40s) — recommend **60s or higher**. If
-   Auto-Return is at or below 40s, TouchHub returns to its launcher before
-   the quest log's idle return can navigate back to the party board.
-
-4. **Log the kiosk session in.** Sign in on the device as the dedicated
-   kiosk user from step 1, and leave that session logged in.
+5. **Log the kiosk session in.** Sign in on the device as the dedicated
+   kiosk user from step 3, and leave that session logged in.
 
 TouchHub loads the dashboard URL directly. The NestQuest cards are normal
 Lovelace cards, not an iframe, so no Home Assistant framing setting is
 needed.
 
+### The two constraints
+
+- **Panel layout.** Every view must be in **Panel** (single-card)
+  layout: Home Assistant's default Masonry layout constrains the
+  1080px-tall NestQuest card to a narrow column, while Panel renders the
+  card full-screen at 1920×1080. The zero-config path already satisfies
+  the requirement — the strategy generates every view as
+  `type: panel` — while the manual alternative below requires setting
+  the layout by hand on each view (Edit Dashboard → pencil on the view
+  → View type: Panel).
+
+- **TouchHub Auto-Return.** TouchHub's **Auto-Return** must be greater
+  than the quest log's `idle_return_seconds` (default 40s) — recommend
+  **60s or higher** — so the launcher does not reclaim the wall device
+  before the quest log's own idle return navigates back to the party
+  board.
+
+### Manual alternative: build the dashboard by hand
+
+If you prefer not to use the zero-config dashboard above — or its
+registration was skipped — configure a Lovelace dashboard whose **URL
+slug is `nestquest`** (Settings → Dashboards → Edit → URL slug)
+yourself. Two options, in decreasing order of convenience:
+
+- **Use the strategy.** Give the dashboard
+
+  ```yaml
+  strategy:
+    type: custom:nestquest-party
+  ```
+
+  and no views of your own — the strategy generates the party-board and
+  quest-log views (each already in Panel layout) from the household
+  roster at render time. Optional `url_path` and `weather_entity` keys
+  may sit beside `strategy:`.
+
+- **Build the two views by hand.** A functional panel needs **two**
+  views in that dashboard, each with its own card config from
+  `design/ENTITIES-AND-SERVICES.md` §4. Give the views these exact URL
+  paths (the path segment after the dashboard slug):
+
+  - **View 1 path `board`** (URL `/nestquest/board`) — party board
+    (`type: custom:nestquest-party-board-card`): the household quest
+    board. Set `weather_entity` (optional; the dock falls back to
+    date/time), `quest_log_path: /nestquest/log` (the view the crest tap
+    navigates to), and `child_order: [slug1, slug2, slug3]` listing each
+    child's slug in display order.
+
+  - **View 2 path `log`** (URL `/nestquest/log`) — quest log
+    (`type: custom:nestquest-quest-log-card`): the per-child quest screen
+    the party board hops to. Set `board_path: /nestquest/board` (the
+    party-board view to return to), `weather_entity`,
+    `idle_return_seconds` (must be shorter than TouchHub Auto-Return —
+    see the two constraints above), `confirm_timeout_seconds`, and
+    `complete_screen_seconds`. The quest log reads the selected child's
+    slug from the view's URL path, so the board → log hop is a plain
+    Lovelace navigation.
+
+  The dashboard contains only the NestQuest panel card for each view —
+  no other cards, no admin controls. Each view's layout MUST be set to
+  **Panel** — see the two constraints above for why; the strategy
+  generates it for you, hand-built views do not get it for free.
+
+  The `quest_log_path` and `board_path` values must match the dashboard
+  slug and view paths above: `/<slug>/<view>`. If you chose `nestquest`
+  as the dashboard slug with view paths `board` and `log`, the card
+  configs are already correct. If you pick different names, substitute
+  your actual paths in **both** card configs — e.g. a dashboard slug
+  `chores` with view paths `main` and `history` needs
+  `quest_log_path: /chores/history` and `board_path: /chores/main`.
+  Navigation between the two views fails (the crest tap or back button
+  lands on a 404) if the card config paths do not match the dashboard
+  slug and view paths exactly.
+
+  See `design/ENTITIES-AND-SERVICES.md` §4 for the full card YAML.
+
 ## Developer Setup and Testing
 
 This project uses [`uv`](https://github.com/astral-sh/uv) for fast Python package and dependency management.

RELEASE_NOTES.md

@@ -1,27 +1,370 @@
 # NestQuest Release Notes
 
-## Unreleased
+## Version 0.8.0 — 2026-09-25
 
-- **Storage layer extraction (task d0b691d8):** the SQLite storage layer
-  (schema, migrations, db, store, const, recurrence, DAOs) is bundled
-  under `custom_components/nestquest/core/`, with the integration's
-  original module names preserved as re-export shims.
-- **Logger namespace change (breaking for logging configuration):** the
-  migrations runner now logs under
-  `custom_components.nestquest.core.migrations` instead of
-  `custom_components.nestquest.migrations`. Users who tuned the old
-  logger name (e.g. in `logger.yaml` or `configuration.yaml`) must
-  update the entry to keep that level, as the old name no longer
-  receives migration log output.
-- **Additional logger namespace moves:** the children registry and the
-  admin allowlist business layers now log under
-  `custom_components.nestquest.core.children` and
-  `custom_components.nestquest.core.admin_allowlist` respectively
-  (moved with the engines/business-layer extraction, task 510c1f78).
-  The parent `custom_components.nestquest` logger still catches both,
-  so users who tune the parent rather than the leaf names are
-  unaffected; only users who pinned a leaf logger name by its old
-  spelling need to update.
+### Scope
+
+Minor release carrying the multi-pattern presence model (schema 9), the
+Sunday-first calendar week, and the create-materializes fix, plus the
+definition start-date field, onto `main`.
+
+- **Multiple presence patterns per child (schema 9):** a child now has zero or
+  more presence patterns instead of at most one. Each pattern has a name, a kind
+  (`home` or `away`), its own cycle length (1–4 weeks), its own anchor date and a
+  per-week weekday set. Evaluation is first-match-wins — overrides, then away,
+  then home, then absent when the child has at least one home pattern, else
+  present. Migration 9 copies each existing schedule into a `home` pattern named
+  "Home schedule" and drops the old `presence_schedules` table. (PRs #231, #232.)
+- **Sunday-first calendar week:** the admin Schedule month grid and the
+  Definitions weekday picker now render weeks Sunday-first; the stored/API
+  weekday numbering is unchanged (Monday=0..Sunday=6). (PR #230.)
+- **Fix — newly created tasks materialize immediately:** creating a quest
+  definition now regenerates its future instances over the rolling horizon, so a
+  new task reaches the panel without waiting for an unrelated write. (PRs #235,
+  #236.)
+- **Definition start date:** the definition edit sheet gains a Start date field
+  so a task can be scheduled to begin on a future date. (PRs #237, #238.)
+- **Docs:** the multi-pattern decision (D-016), the migration-9 rollback step in
+  the runbook, and the ADMIN-SPEC Schedule section. (PRs #233, #234.)
+
+### Upgrade note
+
+This release runs schema version **9**. Version 0.7.1 refuses a version-9
+database, so take a copy of the SQLite file (or note the Litestream generation)
+before the first start on 0.8.0 if you need a rollback path.
+
+### Requirements
+
+
+## Version 0.7.1 — 2026-09-24
+
+### Scope
+
+Patch release bringing the admin PWA follow-ups and its hosting deployment from
+`dev` onto 0.7.0.
+
+- **Feature 24 — Admin PWA Hosting:** the admin PWA's static hosting is now
+  reproducible from the repository — `deploy/pwa/Dockerfile` (multi-stage, pinned
+  `node`/`nginx` base images by digest, `VITE_AUTHENTIK_CLIENT_ID` /
+  `VITE_AUTHENTIK_ISSUER` / `VITE_API_BASE_URL` build args), `deploy/pwa/nginx.conf`
+  (SPA fallback plus a source allow-list for the reverse proxy and the host), a
+  `pwa` service in `deploy/compose.yaml` published on `:8081`, and a
+  `deploy/RUNBOOK.md` section describing the build/serve and the Traefik
+  `nestquest-app` router. (PRs #220, #221.)
+- **Feature 19 follow-up — Manage children:** the Today header's Settings button
+  now opens a Settings screen. Its **Children** section lists the household's
+  children and lets a parent add (POST `/api/v1/admin/children`), edit
+  (PATCH `.../{id}`), activate/deactivate (PATCH `.../{id}/active`) and reorder
+  them (POST `.../reorder`). (PRs #222, #223.)
+- **Feature 19 follow-up — Settings preferences:** the same screen has a
+  **Preferences** section for the planning horizon, day rollover time, notify
+  target, the morning/afternoon/end-of-day notification times and their toggles,
+  and celebration, read from `GET /api/v1/admin/settings` and saved with a partial
+  `PATCH` of only the changed fields. (PRs #224, #225, #226.)
+
+### Requirements
+
+- Minimum Home Assistant version: **2024.6.0**.
+- A running NestQuest API service as in 0.7.0 (the Feature 17 deployment); the
+  `admin/` PWA is served from the owner's deployment at
+  `https://nestquest.cubecraftlabs.com`, not by HACS.
+
+### Breaking changes
+
+- **None.** The schema is unchanged at version 8 and no migration runs.
+  `custom_components/` is unchanged from 0.7.0 apart from the manifest
+  release-version metadata — no Home Assistant entity, service, event or
+  automation surface changes. This release adds admin PWA screens and deployment
+  artifacts only.
+
+### Known Limitations
+
+- **HACS does not ship the admin PWA or the deployment artifacts.** HACS copies
+  only `custom_components/nestquest`, so upgrading via HACS changes nothing
+  functional over 0.7.0; the PWA screens and hosting are deployed from `admin/`
+  and `deploy/` per the runbook.
+- Serving the PWA and API still requires the Feature 17 deployment (host, reverse
+  proxy, Authentik, backup target) as documented in `deploy/RUNBOOK.md`.
+- **Feature 12's TouchHub/DAKOS runbook task remains physically unverified**
+  (needs the wall panel).
+- The Settings UI does not expose resetting a field to its default with `null`.
+
+### Rollback
+
+Schema is unchanged (8), so no migration is involved in either direction.
+`custom_components/` is unchanged from 0.7.0 apart from the release-version
+metadata; rolling back the integration is a plain swap, and the PWA/hosting can be
+redeployed from the 0.7.0 tree.
+
+**HACS installs:** HACS > Integrations > NestQuest > Redownload > 0.7.0, then
+restart Home Assistant.
+
+**Manual installs:** replace `custom_components/nestquest/` with the 0.7.0 tree,
+then restart Home Assistant.
+
+**Repository operators:** git-revert the 0.7.1 release merge on `main`.
+
+## Version 0.7.0 — 2026-09-24
+
+### Scope
+
+Seventh release of NestQuest, promoting the re-imagined architecture's admin
+surface from `dev` onto 0.6.0: the API deployment and identity layer, the
+admin-plane API work, and the standalone admin PWA that uses them.
+
+- **Feature 17 — API Deployment and Identity:** the NestQuest API is packaged as
+  a container (`Dockerfile`, `deploy/compose.yaml`, pinned base image and exact
+  dependencies) and deployed behind a TLS reverse proxy (the shared Traefik, ACME
+  via the Cloudflare DNS-01 challenge); the Authentik application, OIDC provider
+  and `nestquest-admins` group are wired and the API validates the provider's
+  issuer/audience/JWKS (RS256); the panel plane is restricted to the Home
+  Assistant box while the admin plane is internet-facing behind Authentik;
+  continuous backup runs as a contained Litestream sidecar over SFTP to a NAS and
+  a restore is proven; a deployment runbook (`deploy/RUNBOOK.md`) and the
+  host-firewall unit (`deploy/systemd/nestquest-api-firewall.service`) ship.
+  (PRs #183, #214, #215, #216, #218.)
+- **Feature 19 — Admin PWA:** the parent-facing admin surface is now a
+  standalone mobile-first React progressive web app (`admin/`), implementing
+  `design/ADMIN-SPEC.md`: Authentik OIDC authorization-code + PKCE login with
+  an explicit refusal for a user outside `nestquest-admins`; an installable
+  PWA (manifest + service worker); and the Today, Definitions, Schedule and
+  History screens. Every mutating action goes through the API admin routes;
+  the API remains the security boundary (D-003/D-012). Today shows the
+  household snapshot; Definitions supports create/edit with multi-select
+  assignees, a recurrence rule with interval and per-window due times, a
+  skip-on-away toggle, a shipped Lucide icon subset and a backend-computed
+  occurrence preview; Schedule has a presence month grid (cycle position from
+  the anchor date, never ISO parity, D-004) and an override editor with a live
+  "removes N upcoming tasks" consequence count; History has All/Reversals/
+  Missed filters, day-grouped rows, per-period stats, CSV export and the
+  append-only footer. Undo reverses a completion, and live updates arrive over
+  the admin SSE stream without a manual reload. (PRs #187–#210, plus the
+  feature-review fix #212.)
+- **Feature 21 — Admin Today Snapshot API:** `GET /api/v1/admin/snapshot`
+  serves the Today view's household snapshot on the admin plane (reusing the
+  core snapshot builder with missed instances included, D-009). (PRs #190/#191.)
+- **Feature 22 — Admin Definitions Read and skip_on_away:**
+  `GET /api/v1/admin/quest-definitions` lists all definitions (active and
+  inactive), and a persisted per-definition `skip_on_away` boolean is accepted
+  by create/update and honoured by materialization. Adds an optional
+  `assignee_child_ids` to the edit route so the PWA can reassign children.
+  (PRs #193, #194, #196, #197.)
+- **Feature 23 — Admin API Completion (preview, presence, live):** a bounded
+  rule occurrence-preview route; presence-schedule and presence-override
+  reads; a live override consequence count computed from the same core
+  generator the materializer uses; and an admin-plane transition SSE stream
+  (`GET /api/v1/admin/events`) off the one in-process publisher. (PRs
+  #199–#203.)
+
+### Requirements
+
+- Minimum Home Assistant version: **2024.6.0**.
+- A running NestQuest API service, reachable at the base URL and panel service
+  token configured in the integration options. The deployable ships in this
+  release: `Dockerfile`, `deploy/compose.yaml` (API + a contained Litestream
+  backup sidecar), `api/requirements.txt`, the host-firewall unit and
+  `deploy/RUNBOOK.md`. Deploying it needs a host, the DNS/TLS path and the
+  Authentik/Synology services described in the runbook.
+- The admin PWA is built to run at `https://nestquest.cubecraftlabs.com` behind
+  Authentik. Serving the built `admin/` static bundle at that hostname is part of
+  the deployment described in the runbook.
+
+### Breaking changes
+
+- **Schema version advances 7 → 8.** Migration 8 adds the additive
+  `skip_on_away` column to `quest_definitions` (default 1, so every existing
+  definition keeps today's skip-when-absent behaviour). The migration runs on
+  the first start of this version.
+- **Once migrated, a plain downgrade to 0.6.0 is impossible** — older builds
+  refuse a newer schema version. **Back up `nestquest.db` (plus `-wal`/`-shm`)
+  before upgrading**; see Rollback.
+- No Home Assistant entity, service, event or automation surface changes in
+  this release. The API's new admin routes are additive.
+
+### Known Limitations
+
+- **The API and its identity/backup layer are deployed by the owner's
+  infrastructure, not by this release alone.** The deployment artifacts and
+  runbook ship here, but a running service still requires the host, the shared
+  reverse proxy, the Authentik application/provider/`nestquest-admins` group, the
+  backup target and the panel/admin network separation to be in place as the
+  runbook describes.
+- **Serving the admin PWA is still outstanding.** `admin/` builds and is
+  unit/integration tested and the API it talks to is live, but the built static
+  bundle must still be hosted at `https://nestquest.cubecraftlabs.com` behind
+  Authentik; until then the PWA is not reachable end-to-end.
+- **Feature 12's TouchHub/DAKOS runbook task remains physically unverified**
+  (needs the wall panel).
+- Moving the household database from Home Assistant to the API box is a manual
+  file copy (the schema is unchanged by that move beyond the v8 migration).
+- Single household; single API service.
+
+### Rollback
+
+**Schema version advances 7 → 8.** Migration 8 is additive, but a migrated
+database **cannot** be read by 0.6.0 or earlier (they refuse a newer schema
+version). The database is owned and migrated by the **NestQuest API service**,
+not by Home Assistant: it is the file at the API's configured
+`NESTQUEST_DB_PATH` on the API host, which need not be anywhere near the Home
+Assistant config directory. To return to 0.6.0 you must restore a backup of
+that file taken before the upgrade; a plain downgrade is impossible once
+migrated.
+
+**API host (database):**
+
+1. Before upgrading, stop the NestQuest API service and back up the database
+   file at its configured `NESTQUEST_DB_PATH`, plus its `-wal` and `-shm`
+   sidecars (`<NESTQUEST_DB_PATH>-wal`, `<NESTQUEST_DB_PATH>-shm`) if present.
+   Only then deploy 0.7.0 and start the API service, which applies migration 8.
+2. To roll back: stop the API service, restore the backed-up database and
+   sidecars to `NESTQUEST_DB_PATH`, redeploy the API service at 0.6.0, and roll
+   back the Home Assistant integration to 0.6.0 (below). Then restart the API
+   service and Home Assistant.
+
+**Home Assistant integration — HACS installs** (integration component only;
+the database lives with the API, see above):
+
+1. To roll back: HACS > Integrations > NestQuest > Redownload > 0.6.0, then
+   restart Home Assistant.
+
+**Home Assistant integration — Manual installs** (integration component only;
+the database lives with the API, see above):
+
+1. To roll back: replace `custom_components/nestquest/` with the 0.6.0 tree,
+   then restart Home Assistant.
+
+**Repository operators:** git-revert the 0.7.0 release merge on `main`.
+
+## Version 0.6.0 — 2026-09-23
+
+### Scope
+
+Sixth release of NestQuest, promoting the re-imagined architecture
+(Features 15, 16, 18 and 20) and the foreground development-orchestration
+tooling from `dev` onto 0.5.0. This is a major architectural change: the
+Home Assistant integration becomes a thin client of a standalone NestQuest
+API service that owns the database.
+
+- **Feature 15 — Domain Core Extraction:** all domain code (schema,
+  migrations, database access, the DAOs, the pure recurrence/presence
+  engines, materialization, completion, the SSE-free event payload
+  builders, the panel snapshot builder, the children/definitions/allowlist
+  business layers, and an explicit settings object) now lives in a
+  Home-Assistant-free package bundled inside the integration at
+  `custom_components/nestquest/core/`. The SQLite schema and migration
+  versions are unchanged, so an existing `nestquest.db` opens without
+  migration. Covered by a no-Home-Assistant end-to-end smoke test.
+  (Tasks d0b691d8, 510c1f78, 4dd8f870, 628473ad.)
+- **Feature 16 — NestQuest API Service:** a standalone FastAPI service
+  (`api/`) that imports `core/` and is the only writer of the database.
+  Panel plane (`/api/v1/panel/*`) is authenticated by a static service
+  token: household snapshot and an idempotent complete route. Admin plane
+  (`/api/v1/admin/*`): children, quest definitions, presence
+  schedule/override, uncomplete, regenerate, history query + CSV export,
+  and settings — authenticated by an Authentik OIDC JWT (issuer, audience,
+  JWKS signature and expiry) plus membership in `nestquest-admins`, with
+  the panel service token rejected outright. A server-sent-events stream
+  publishes the quest-completed, quest-uncompleted, quest-missed and
+  child-day-complete transitions; the missed sweep runs in the API with a
+  cross-process-safe watermark. `/health` and the OpenAPI document are
+  served. (Tasks 042dfc5c, ae7e90ae, 1860ef76, 4d7bae00, 44c93cfd,
+  e70e6bfb, 0f2afb29, e4845baa, b586a2f1, e4a9d31b, da0226b3, 2d2dda53,
+  2b3de7e5, 9047a97b, 9a118da9, 058c7b69, a232c4f5.)
+- **Feature 18 — HA Integration as API Client:** the integration no longer
+  owns a database. It polls `GET /api/v1/panel/snapshot` and builds the
+  existing sensors (entity ids and per-child instance payload shape
+  unchanged), subscribes to the SSE stream and re-fires the four HA bus
+  events, proxies `nestquest.complete_quest` to the panel complete route,
+  and caches the last-good snapshot so a brief API outage does not blank
+  the panel. The HA admin services and the service permission gate are
+  removed; only the panel completion path remains. (Tasks 37d5e806,
+  6e70d166, b1ed9c45, 47c7c90e, d25b875f, d04f5bf3, ad67fc44.)
+- **Feature 20 — Zero-Config Panel Dashboard:** the panel installs with no
+  hand-written card YAML and no manual dashboard creation. The cards
+  auto-discover children from a household entity attribute (ordered by the
+  API's `sort_order`), a Lovelace dashboard strategy generates the
+  party-board view and one quest-log view per child at render time with
+  computed navigation paths, and the integration registers the dashboard
+  on first setup. Navigation and the panel transitions match the design
+  mockups. (Tasks 1b6d91d2, c859af23, c2d4dd8e, 107b8fbe, 50067c1f,
+  fc69c940, 67775be9.)
+- **Development orchestration tooling:** durable OpenCode controller and
+  role launchers, the foreground terminal orchestrator, the independent
+  review/approval gates, and the automatic release-preparation policy.
+
+### Requirements
+
+- Minimum Home Assistant version: **2024.6.0**.
+- A running NestQuest API service, reachable at the base URL and panel
+  service token configured in the integration options. The API service
+  source ships in `api/`; there is no container image, compose file or
+  deployment runbook in this release, and Feature 17 — the deployment
+  (TLS reverse proxy, Authentik, network separation, backups) — is **not**
+  part of this release and must be completed before the integration is
+  functional. See `docs/ARCHITECTURE.md` for the target design.
+
+### Breaking changes
+
+- **The HA integration no longer owns a database.** It reads exclusively
+  from the NestQuest API. The local `nestquest.db` is no longer opened,
+  migrated or written by the integration (the file is left untouched on
+  disk). Without a reachable API the entities become unavailable after the
+  configured staleness threshold; the panel serves the last-good snapshot
+  in the meantime.
+- **HA admin services are removed** (`uncomplete`, quest-definition
+  create/update/set-active, presence pattern/override, CSV export,
+  `manage_child`, `regenerate`) and the HA-side permission gate is gone.
+  Admin operations move to the API, and — once Feature 19 lands — the
+  admin PWA. Any automation that called an admin service must be
+  repointed at the API.
+- **Logger namespaces moved** under `custom_components.nestquest.core.*`:
+  the migrations runner now logs under
+  `custom_components.nestquest.core.migrations` (previously
+  `custom_components.nestquest.migrations`), and the children registry and
+  admin allowlist log under `custom_components.nestquest.core.children` and
+  `custom_components.nestquest.core.admin_allowlist`. The parent
+  `custom_components.nestquest` logger still catches all three; only users
+  who pinned a leaf logger name by its old spelling must update.
+- **The panel installs with no configuration.** `child_order`,
+  `quest_log_path` and `board_path` are no longer required (an explicit
+  value still wins). The integration registers a `custom:nestquest-party`
+  dashboard on setup; point TouchHub at it.
+- **Schema is unchanged at version 7** — no migration runs on upgrade.
+
+### Known Limitations
+
+- **Feature 17 (API deployment and identity) is not in this release.** The
+  API service source ships in `api/`, but no container image, compose
+  file, TLS reverse proxy, Authentik application/provider/`nestquest-admins`
+  group, proven network separation of the panel routes, or backup/restore
+  is included. Feature 17's containerization groundwork was completed on
+  its own feature branch, which is **not** merged into `dev` and therefore
+  is not part of this release. Until that deployment is completed the
+  integration has nothing to talk to.
+- **Feature 19 (admin PWA) is not in this release.** There is no admin UI
+  in 0.6.0; admin operations are reachable only through the API directly.
+- Moving the household database from Home Assistant to the API box is a
+  manual file copy (the schema is unchanged).
+- Single household; single API service.
+
+### Rollback
+
+Schema version is unchanged (7), so no migration is involved in either
+direction. Nevertheless **back up `nestquest.db` (plus `-wal`/`-shm`)
+before upgrading**: 0.6.0 never touches it, and a downgrade to 0.5.0
+resumes using exactly that file.
+
+**HACS installs:**
+
+1. Downgrade via HACS (HACS > Integrations > NestQuest > Redownload > 0.5.0).
+2. Restart Home Assistant.
+
+**Manual installs:**
+
+1. Replace `custom_components/nestquest/` with the 0.5.0 tree.
+2. Restart Home Assistant.
+
+**Repository operators:** git-revert the 0.6.0 release merge on `main`.
 
 ## Version 0.5.0 — 2026-09-18
 

admin/.env.example

@@ -0,0 +1,13 @@
+# NestQuest Admin PWA — runtime configuration (Vite env).
+# Copy to .env (or .env.local) and fill in real values. NEVER commit .env.
+
+# Authentik OIDC provider. Defaults to the issuer below when unset.
+VITE_AUTHENTIK_ISSUER=https://auth.cubecraftlabs.com/application/o/nestquest/
+
+# REQUIRED. OAuth2/OIDC client id of the PUBLIC (PKCE) Authentik application.
+# No default: the app shows a configuration error screen when this is missing.
+# Never set a client_secret — this is a browser SPA using PKCE only.
+VITE_AUTHENTIK_CLIENT_ID=
+
+# NestQuest API base URL.
+VITE_API_BASE_URL=https://nestquest.cubecraftlabs.com

admin/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

admin/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <meta name="theme-color" content="#3b3ab8" />
+    <link rel="manifest" href="/manifest.webmanifest" />
+    <link rel="apple-touch-icon" href="/icons/icon-192.png" />
+    <title>NestQuest Admin</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

admin/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "nestquest-admin",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@fortawesome/free-solid-svg-icons": "7.3.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "jsdom": "^30.1.1",
+    "lucide-react": "1.47.0",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.5",
+    "vitest": "^3.2.4"
+  }
+}

admin/public/manifest.webmanifest

@@ -0,0 +1,14 @@
+{
+  "name": "NestQuest Admin",
+  "short_name": "NestQuest",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "background_color": "#f4f4f6",
+  "theme_color": "#3b3ab8",
+  "icons": [
+    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
+    { "src": "/icons/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
+  ]
+}

admin/public/sw.js

@@ -0,0 +1,88 @@
+/* NestQuest Admin service worker — hand-written, served from the site root.
+   Precaches the app shell, serves static assets cache-first, and falls back
+   to the cached shell for navigations when offline. Only same-origin GET
+   requests are handled; cross-origin requests (Authentik, the API host) are
+   never intercepted or cached.
+   The build (vite-sw-plugin.ts) replaces PRECACHE_ASSETS with the hashed
+   bundles referenced by index.html and the revision marker with a content
+   hash, so each release installs a new worker with fresh caches. */
+
+const REVISION = "__NQ_BUILD_REVISION__";
+const CACHE_PREFIX = "nestquest-admin-";
+const SHELL_CACHE = `${CACHE_PREFIX}shell-${REVISION}`;
+const RUNTIME_CACHE = `${CACHE_PREFIX}runtime-${REVISION}`;
+const CURRENT_CACHES = [SHELL_CACHE, RUNTIME_CACHE];
+
+const PRECACHE_ASSETS = [];
+
+const SHELL_URLS = [
+  ...new Set([
+    "/",
+    "/index.html",
+    "/manifest.webmanifest",
+    "/icons/icon-192.png",
+    "/icons/icon-512.png",
+    "/icons/icon-maskable-512.png",
+    ...PRECACHE_ASSETS,
+  ]),
+];
+
+// Request destinations treated as static assets (cache-first). Anything else
+// same-origin (e.g. API calls) goes straight to the network.
+const STATIC_DESTINATIONS = ["script", "style", "image", "font", "manifest"];
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(
+    caches
+      .open(SHELL_CACHE)
+      .then((cache) => cache.addAll(SHELL_URLS))
+      .then(() => self.skipWaiting()),
+  );
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) =>
+        Promise.all(
+          keys
+            .filter((key) => key.startsWith(CACHE_PREFIX) && !CURRENT_CACHES.includes(key))
+            .map((key) => caches.delete(key)),
+        ),
+      )
+      .then(() => self.clients.claim()),
+  );
+});
+
+self.addEventListener("fetch", (event) => {
+  const request = event.request;
+  if (request.method !== "GET") return;
+  if (new URL(request.url).origin !== self.location.origin) return;
+
+  if (request.mode === "navigate") {
+    event.respondWith(
+      fetch(request).catch(() =>
+        caches.match("/index.html", { cacheName: SHELL_CACHE }).then(
+          (cached) => cached || Response.error(),
+        ),
+      ),
+    );
+    return;
+  }
+
+  if (STATIC_DESTINATIONS.includes(request.destination)) {
+    event.respondWith(cacheFirst(request));
+  }
+});
+
+async function cacheFirst(request) {
+  const cached = await caches.match(request);
+  if (cached) return cached;
+  const response = await fetch(request);
+  if (response.ok && response.type === "basic") {
+    const cache = await caches.open(RUNTIME_CACHE);
+    await cache.put(request, response.clone());
+  }
+  return response;
+}

admin/scripts/generate-icons.mjs

@@ -0,0 +1,80 @@
+// Generates the committed PWA icons under public/icons/ as genuine PNGs.
+// Pure Node (zlib only) — no network, no image dependencies.
+// Run: node scripts/generate-icons.mjs
+import { writeFileSync } from "node:fs";
+import { deflateSync } from "node:zlib";
+import { fileURLToPath } from "node:url";
+
+// Brand tokens (design/tokens/nestquest-admin-tokens.css).
+const BLUE = [0x3b, 0x3a, 0xb8];
+const PURPLE = [0xa0, 0x35, 0xcc];
+const WHITE = [0xff, 0xff, 0xff];
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c >>> 0;
+});
+
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (const b of buf) c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body));
+  return Buffer.concat([len, body, crc]);
+}
+
+function encodePng(size, pixel) {
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(size, 0);
+  ihdr.writeUInt32BE(size, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 2; // colour type: RGB
+  const raw = Buffer.alloc(size * (size * 3 + 1));
+  for (let y = 0; y < size; y++) {
+    const row = y * (size * 3 + 1);
+    raw[row] = 0; // filter: none
+    for (let x = 0; x < size; x++) raw.set(pixel(x, y), row + 1 + x * 3);
+  }
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(raw, { level: 9 })),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+// Flat brand mark: diagonal blue→purple gradient with a white ring ("nest")
+// around a white dot ("quest"). `scale` shrinks the mark for the maskable
+// safe zone (inner 80% circle).
+function brandMark(size, scale) {
+  const c = size / 2;
+  const outer = size * 0.34 * scale;
+  const inner = size * 0.24 * scale;
+  const dot = size * 0.1 * scale;
+  return (x, y) => {
+    const d = Math.hypot(x + 0.5 - c, y + 0.5 - c);
+    if ((d <= outer && d >= inner) || d <= dot) return WHITE;
+    const t = (x + y) / (2 * (size - 1));
+    return BLUE.map((b, i) => Math.round(b + (PURPLE[i] - b) * t));
+  };
+}
+
+const outDir = new URL("../public/icons/", import.meta.url);
+const icons = [
+  ["icon-192.png", 192, 1],
+  ["icon-512.png", 512, 1],
+  ["icon-maskable-512.png", 512, 0.75],
+];
+for (const [name, size, scale] of icons) {
+  const path = fileURLToPath(new URL(name, outDir));
+  writeFileSync(path, encodePng(size, brandMark(size, scale)));
+  console.log(`wrote ${path}`);
+}

admin/src/App.css

@@ -0,0 +1,123 @@
+/* Shell layout — mobile-first (390x844 reference), plain CubeCraft styling. */
+
+.admin-shell {
+  display: flex;
+  flex-direction: column;
+  min-height: 100%;
+}
+
+.admin-header {
+  background: var(--nq-a-surface);
+  border-bottom: 1px solid var(--nq-a-border);
+  padding: 14px 16px;
+}
+
+.admin-title {
+  margin: 0;
+  font-size: 24px;
+  font-weight: 800;
+  letter-spacing: -0.02em;
+}
+
+.admin-subline {
+  margin: 2px 0 0;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.admin-panel {
+  flex: 1;
+  padding: 14px 16px 92px; /* bottom padding clears the 70px tab bar */
+}
+
+/* A built screen supplies its own header and 92px-padded scroll column. */
+.admin-panel--screen {
+  padding: 0;
+}
+
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.admin-tabbar {
+  position: fixed;
+  inset: auto 0 0;
+  display: flex;
+  min-height: calc(var(--nq-a-tabbar-height) + 12px);
+  padding: 8px 4px calc(12px + env(safe-area-inset-bottom));
+  background: var(--nq-a-surface);
+  border-top: 1px solid var(--nq-a-border);
+}
+
+.admin-tab {
+  flex: 1;
+  border: 0;
+  background: none;
+  font-family: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+  cursor: pointer;
+  padding: 6px 4px;
+}
+
+.admin-tab.active {
+  font-weight: 700;
+  color: var(--nq-brand-blue);
+}
+/* Auth screens (login, errors, refusal). */
+
+.admin-login,
+.admin-error,
+.admin-refusal,
+.admin-loading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  min-height: 100%;
+  padding: 32px 16px;
+  text-align: center;
+}
+
+.admin-login-button {
+  margin-top: 8px;
+  padding: 12px 24px;
+  border: none;
+  border-radius: 8px;
+  background: var(--nq-a-accent, #2563eb);
+  color: #fff;
+  font-size: 15px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.admin-error,
+.admin-refusal {
+  color: var(--nq-a-ink, inherit);
+}
+
+.admin-refusal h1,
+.admin-error h1 {
+  margin: 0;
+  font-size: 20px;
+}
+
+.admin-refusal p,
+.admin-error p {
+  margin: 0;
+  max-width: 34em;
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}

admin/src/App.test.tsx

@@ -0,0 +1,47 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import App from "./App";
+
+describe("NestQuest Admin shell", () => {
+  beforeEach(() => {
+    // The Today tab fetches the admin snapshot; keep the shell tests offline.
+    vi.stubGlobal("fetch", vi.fn(() => new Promise<Response>(() => {})));
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("renders the title and all four tab labels", () => {
+    render(<App />);
+
+    expect(screen.getByRole("heading", { name: "NestQuest Admin" })).toBeTruthy();
+    for (const label of ["Today", "Tasks", "Schedule", "History"]) {
+      expect(screen.getByRole("tab", { name: label })).toBeTruthy();
+    }
+  });
+
+  it("starts on the Today screen and switches on tab click", () => {
+    render(<App />);
+
+    expect(screen.getByRole("heading", { name: "Today" })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("tab", { name: "History" }));
+
+    expect(screen.getByRole("heading", { name: "History" })).toBeTruthy();
+    expect(screen.getByRole("tabpanel").textContent).not.toContain("placeholder");
+    expect(screen.getByRole("tab", { name: "History" }).getAttribute("aria-selected")).toBe(
+      "true",
+    );
+  });
+
+  it("the Tasks tab renders the definitions screen", () => {
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("tab", { name: "Tasks" }));
+
+    expect(screen.getByRole("heading", { name: "Tasks" })).toBeTruthy();
+    expect(screen.getByRole("tabpanel").textContent).not.toContain("placeholder");
+  });
+});

admin/src/App.tsx

@@ -0,0 +1,63 @@
+import { useState } from "react";
+import "./App.css";
+import { TransitionsProvider } from "./api/useTransitions";
+import DefinitionsTab from "./definitions/DefinitionsTab";
+import HistoryTab from "./history/HistoryTab";
+import ScheduleTab from "./schedule/ScheduleTab";
+import TodayTab from "./today/TodayTab";
+
+const TABS = [
+  { id: "today", label: "Today" },
+  { id: "tasks", label: "Tasks" },
+  { id: "schedule", label: "Schedule" },
+  { id: "history", label: "History" },
+] as const;
+
+type TabId = (typeof TABS)[number]["id"];
+
+export default function App() {
+  const [active, setActive] = useState<TabId>("today");
+
+  return (
+    <TransitionsProvider>
+      <div className="admin-shell">
+        {/* Every tab is a built screen that owns its header (ADMIN-SPEC §1); the
+            generic shell header stays only as a visually hidden page heading. */}
+        <header className="admin-header visually-hidden">
+          <h1 className="admin-title">NestQuest Admin</h1>
+          <p className="admin-subline">Admin console</p>
+        </header>
+        <main
+          className="admin-panel admin-panel--screen"
+          role="tabpanel"
+          aria-labelledby={`tab-${active}`}
+        >
+          {active === "today" ? (
+            <TodayTab />
+          ) : active === "tasks" ? (
+            <DefinitionsTab />
+          ) : active === "schedule" ? (
+            <ScheduleTab />
+          ) : (
+            <HistoryTab />
+          )}
+        </main>
+        <nav className="admin-tabbar" aria-label="Admin sections">
+          {TABS.map((tab) => (
+            <button
+              key={tab.id}
+              id={`tab-${tab.id}`}
+              type="button"
+              role="tab"
+              aria-selected={tab.id === active}
+              className={tab.id === active ? "admin-tab active" : "admin-tab"}
+              onClick={() => setActive(tab.id)}
+            >
+              {tab.label}
+            </button>
+          ))}
+        </nav>
+      </div>
+    </TransitionsProvider>
+  );
+}

admin/src/AppRoutes.test.tsx

@@ -0,0 +1,193 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import AppRoutes from "./AppRoutes";
+import { storeTokens } from "./auth/oidc";
+import { config } from "./config";
+
+// The bundled config reads real env at import time; seed the shared module's
+// clientId directly so AppRoutes sees a configured app in these tests.
+(config as { clientId: string | undefined }).clientId = "test-client-id";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("AppRoutes auth gating", () => {
+  afterEach(() => {
+    cleanup();
+    sessionStorage.clear();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    window.history.replaceState({}, "", "/");
+  });
+
+  it("renders the login screen when unauthenticated at /", () => {
+    render(<AppRoutes />);
+    expect(screen.getByTestId("login-screen")).toBeTruthy();
+    expect(
+      screen.getByRole("button", { name: /sign in with authentik/i }),
+    ).toBeTruthy();
+  });
+
+  function probeCalls(fetchMock: ReturnType<typeof vi.fn>): string[] {
+    return fetchMock.mock.calls
+      .map(([url]) => String(url))
+      .filter((url) => url.includes("/api/"));
+  }
+
+  it("probes exactly GET /api/v1/admin/ping and no non-admin path", async () => {
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    const fetchMock = vi.fn().mockResolvedValue(new Response("", { status: 500 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(<AppRoutes />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("probe-error-screen")).toBeTruthy();
+    });
+    const calls = probeCalls(fetchMock);
+    expect(calls).toEqual([`${config.apiBaseUrl}/api/v1/admin/ping`]);
+    const [, init] = fetchMock.mock.calls[0];
+    expect(init.method ?? "GET").toBe("GET");
+    expect(init.headers.Authorization).toBe("Bearer at-123");
+    for (const url of calls) {
+      expect(new URL(url, "http://localhost").pathname.startsWith("/api/v1/admin/")).toBe(true);
+    }
+  });
+
+  it("renders the four-tab shell after a successful authenticated probe", async () => {
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse([]));
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(<AppRoutes />);
+
+    await waitFor(() => {
+      expect(screen.getByRole("heading", { name: "NestQuest Admin" })).toBeTruthy();
+    });
+    for (const label of ["Today", "Tasks", "Schedule", "History"]) {
+      expect(screen.getByRole("tab", { name: label })).toBeTruthy();
+    }
+    expect(String(fetchMock.mock.calls[0][0])).toBe(
+      `${config.apiBaseUrl}/api/v1/admin/ping`,
+    );
+  });
+
+  it("renders the explicit refusal when the API answers 403", async () => {
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    const fetchMock = vi.fn().mockResolvedValue(new Response("", { status: 403 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(<AppRoutes />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("refusal-screen")).toBeTruthy();
+    });
+    expect(screen.getByText(/not in the nestquest-admins group/i)).toBeTruthy();
+    expect(screen.queryByRole("tab", { name: "Today" })).toBeNull();
+  });
+
+  it("keeps the login flow when the probe answers 401", async () => {
+    storeTokens({ access_token: "stale", expires_in: 600 });
+    const assign = vi.fn();
+    vi.stubGlobal("location", { ...window.location, assign });
+    const fetchMock = vi.fn().mockImplementation(async (url: string) =>
+      String(url).includes("/api/v1/admin/ping")
+        ? new Response("", { status: 401 })
+        : jsonResponse({
+            issuer: config.issuer,
+            authorization_endpoint: "https://auth.example.com/authorize/",
+            token_endpoint: "https://auth.example.com/token/",
+            userinfo_endpoint: "https://auth.example.com/userinfo/",
+            end_session_endpoint: "https://auth.example.com/end-session/",
+            jwks_uri: "https://auth.example.com/jwks/",
+          }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(<AppRoutes />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("login-screen")).toBeTruthy();
+    });
+    expect(assign).toHaveBeenCalledTimes(1);
+    const redirect = new URL(assign.mock.calls[0][0] as string);
+    expect(redirect.origin + redirect.pathname).toBe("https://auth.example.com/authorize/");
+    expect(probeCalls(fetchMock)).toEqual([`${config.apiBaseUrl}/api/v1/admin/ping`]);
+    expect(screen.queryByRole("tab", { name: "Today" })).toBeNull();
+    expect(screen.queryByTestId("probe-error-screen")).toBeNull();
+  });
+
+  for (const status of [404, 500]) {
+    it(`shows the error screen, not the shell, when the probe answers ${status}`, async () => {
+      storeTokens({ access_token: "at-123", expires_in: 600 });
+      const fetchMock = vi.fn().mockResolvedValue(new Response("", { status }));
+      vi.stubGlobal("fetch", fetchMock);
+
+      render(<AppRoutes />);
+
+      await waitFor(() => {
+        expect(screen.getByTestId("probe-error-screen")).toBeTruthy();
+      });
+      expect(screen.getByText(new RegExp(`answered ${status}`))).toBeTruthy();
+      expect(screen.getByRole("button", { name: "Retry" })).toBeTruthy();
+      expect(screen.getByRole("button", { name: "Sign out" })).toBeTruthy();
+      expect(screen.queryByRole("tab", { name: "Today" })).toBeNull();
+      expect(screen.queryByTestId("refusal-screen")).toBeNull();
+    });
+  }
+
+  it("shows the error screen, not the shell, when the probe request fails", async () => {
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    const fetchMock = vi.fn().mockRejectedValue(new TypeError("Failed to fetch"));
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(<AppRoutes />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("probe-error-screen")).toBeTruthy();
+    });
+    expect(screen.getByText(/could not be reached/i)).toBeTruthy();
+    expect(screen.queryByRole("tab", { name: "Today" })).toBeNull();
+  });
+
+  it("re-probes on retry and enters the shell once the probe succeeds", async () => {
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    // After the retry the ping succeeds; the shell's own tab loads stay pending.
+    let pings = 0;
+    const fetchMock = vi.fn().mockImplementation((url: string) => {
+      if (!String(url).endsWith("/api/v1/admin/ping")) return new Promise(() => {});
+      pings += 1;
+      return Promise.resolve(new Response("", { status: pings === 1 ? 500 : 200 }));
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(<AppRoutes />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("probe-error-screen")).toBeTruthy();
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Retry" }));
+
+    await waitFor(() => {
+      expect(screen.getByRole("tab", { name: "Today" })).toBeTruthy();
+    });
+    expect(String(fetchMock.mock.calls[1][0])).toBe(
+      `${config.apiBaseUrl}/api/v1/admin/ping`,
+    );
+  });
+
+  it("shows the configuration error screen when the client id is missing", () => {
+    const original = config.clientId;
+    (config as { clientId: string | undefined }).clientId = undefined;
+    try {
+      render(<AppRoutes />);
+      expect(screen.getByTestId("config-error-screen")).toBeTruthy();
+    } finally {
+      (config as { clientId: string | undefined }).clientId = original;
+    }
+  });
+});

admin/src/AppRoutes.tsx

@@ -0,0 +1,211 @@
+/**
+ * Minimal path-based routing without react-router-dom: the app only needs two
+ * paths (`/` shell and `/auth/callback`), so a tiny window.location switch is
+ * enough and keeps the bundle small. Change screens listen to popstate.
+ */
+import { useEffect, useState } from "react";
+import { ConfigError, config } from "./config";
+import {
+  AuthError,
+  buildAuthorizeUrl,
+  clearAuth,
+  handleCallback,
+  isAuthenticated,
+} from "./auth/oidc";
+import { ApiForbiddenError, ApiUnauthorizedError, apiFetch } from "./api/client";
+import AdminShell from "./App";
+
+type Screen =
+  | { kind: "loading" }
+  | { kind: "login" }
+  | { kind: "config-error"; message: string }
+  | { kind: "auth-error"; message: string }
+  | { kind: "refusal"; message: string }
+  | { kind: "probe-error"; message: string }
+  | { kind: "app" };
+
+function currentPath(): string {
+  return window.location.pathname.replace(/\/+$/, "") || "/";
+}
+
+const ADMIN_PROBE_PATH = "/api/v1/admin/ping";
+
+async function probeApi(setScreen: (screen: Screen) => void) {
+  // The admin plane's authorization probe: only a 2xx enters the shell, so a
+  // non-admin (403) sees the explicit refusal and any other failure an error.
+  try {
+    const response = await apiFetch(ADMIN_PROBE_PATH, {}, config);
+    if (response.ok) {
+      setScreen({ kind: "app" });
+      return;
+    }
+    setScreen({
+      kind: "probe-error",
+      message: `The admin API answered ${response.status}. The admin console cannot load.`,
+    });
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      setScreen({ kind: "config-error", message: error.message });
+      return;
+    }
+    if (error instanceof ApiForbiddenError) {
+      setScreen({ kind: "refusal", message: error.message });
+      return;
+    }
+    if (error instanceof ApiUnauthorizedError) {
+      // apiFetch has already started the login redirect.
+      setScreen({ kind: "login" });
+      return;
+    }
+    setScreen({
+      kind: "probe-error",
+      message: "The admin API could not be reached. Check your connection and try again.",
+    });
+  }
+}
+
+function LoginScreen({ onLogin }: { onLogin: () => void }) {
+  return (
+    <div className="admin-login" data-testid="login-screen">
+      <h1 className="admin-title">NestQuest Admin</h1>
+      <p className="admin-subline">Sign in to continue</p>
+      <button type="button" className="admin-login-button" onClick={onLogin}>
+        Sign in with Authentik
+      </button>
+    </div>
+  );
+}
+
+export default function AppRoutes() {
+  const [screen, setScreen] = useState<Screen>({ kind: "loading" });
+
+  useEffect(() => {
+    // Re-evaluate on navigation (popstate) — routing is path based.
+    const onPop = () => setScreen({ kind: "loading" });
+    window.addEventListener("popstate", onPop);
+    return () => window.removeEventListener("popstate", onPop);
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    const path = currentPath();
+
+    if (!config.clientId) {
+      setScreen({
+        kind: "config-error",
+        message:
+          "Missing VITE_AUTHENTIK_CLIENT_ID configuration. Set it in your .env before building the admin PWA.",
+      });
+      return;
+    }
+
+    if (path === "/auth/callback") {
+      (async () => {
+        try {
+          await handleCallback(window.location.search, config);
+          if (cancelled) return;
+          window.history.replaceState({}, "", "/");
+          await probeApi((next) => !cancelled && setScreen(next));
+        } catch (error) {
+          if (cancelled) return;
+          const message =
+            error instanceof AuthError || error instanceof Error
+              ? error.message
+              : "Authentication failed.";
+          setScreen({ kind: "auth-error", message });
+        }
+      })();
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    if (isAuthenticated()) {
+      void probeApi((next) => !cancelled && setScreen(next));
+    } else {
+      setScreen({ kind: "login" });
+    }
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const startLogin = async () => {
+    try {
+      const url = await buildAuthorizeUrl(config);
+      window.location.assign(url);
+    } catch (error) {
+      setScreen({
+        kind: "config-error",
+        message: error instanceof Error ? error.message : "Login failed.",
+      });
+    }
+  };
+
+  switch (screen.kind) {
+    case "loading":
+      return (
+        <div className="admin-loading" role="status" data-testid="loading-screen">
+          Loading…
+        </div>
+      );
+    case "login":
+      return <LoginScreen onLogin={startLogin} />;
+    case "config-error":
+      return (
+        <div className="admin-error" role="alert" data-testid="config-error-screen">
+          <h1>Configuration error</h1>
+          <p>{screen.message}</p>
+        </div>
+      );
+    case "auth-error":
+      return (
+        <div className="admin-error" role="alert" data-testid="auth-error-screen">
+          <h1>Sign-in failed</h1>
+          <p>{screen.message}</p>
+          <button
+            type="button"
+            onClick={() => {
+              clearAuth();
+              window.history.replaceState({}, "", "/");
+              setScreen({ kind: "loading" });
+            }}
+          >
+            Try again
+          </button>
+        </div>
+      );
+    case "refusal":
+      return (
+        <div className="admin-refusal" role="alert" data-testid="refusal-screen">
+          <h1>Access refused</h1>
+          <p>{screen.message}</p>
+          <button type="button" onClick={() => { clearAuth(); window.history.replaceState({}, "", "/"); setScreen({ kind: "login" }); }}>
+            Sign out
+          </button>
+        </div>
+      );
+    case "probe-error":
+      return (
+        <div className="admin-error" role="alert" data-testid="probe-error-screen">
+          <h1>Admin console unavailable</h1>
+          <p>{screen.message}</p>
+          <button
+            type="button"
+            onClick={() => {
+              setScreen({ kind: "loading" });
+              void probeApi(setScreen);
+            }}
+          >
+            Retry
+          </button>
+          <button type="button" onClick={() => { clearAuth(); window.history.replaceState({}, "", "/"); setScreen({ kind: "login" }); }}>
+            Sign out
+          </button>
+        </div>
+      );
+    case "app":
+      return <AdminShell />;
+  }
+}

admin/src/api/children.ts

@@ -0,0 +1,50 @@
+/**
+ * Typed client for the admin child-profile write routes
+ * (/api/v1/admin/children). The list read is `fetchChildren` in ./definitions.
+ */
+import { apiFetch } from "./client";
+import { CHILDREN_PATH, readJson, type AdminChild } from "./definitions";
+
+export interface ChildCreateBody {
+  display_name: string;
+  colour?: string;
+  avatar_ref?: string;
+  sort_order?: number;
+}
+
+/**
+ * Omitted fields stay unchanged. The API rejects an explicit null, so a set
+ * colour or avatar cannot be cleared through this route.
+ */
+export type ChildEditBody = Partial<ChildCreateBody>;
+
+export const CHILDREN_REORDER_PATH = `${CHILDREN_PATH}/reorder`;
+
+function sendJson(path: string, method: "POST" | "PATCH", body: unknown): Promise<Response> {
+  return apiFetch(path, {
+    method,
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+export async function createChild(body: ChildCreateBody): Promise<AdminChild> {
+  return readJson<AdminChild>(await sendJson(CHILDREN_PATH, "POST", body));
+}
+
+export async function updateChild(id: number, body: ChildEditBody): Promise<AdminChild> {
+  return readJson<AdminChild>(await sendJson(`${CHILDREN_PATH}/${id}`, "PATCH", body));
+}
+
+export async function setChildActive(id: number, isActive: boolean): Promise<AdminChild> {
+  return readJson<AdminChild>(
+    await sendJson(`${CHILDREN_PATH}/${id}/active`, "PATCH", { is_active: isActive }),
+  );
+}
+
+/** `orderedIds` must be every child id in the household, in the new order. */
+export async function reorderChildren(orderedIds: number[]): Promise<void> {
+  await readJson<{ status: string }>(
+    await sendJson(CHILDREN_REORDER_PATH, "POST", { ordered_ids: orderedIds }),
+  );
+}

admin/src/api/client.test.ts

@@ -0,0 +1,94 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  ApiForbiddenError,
+  ApiUnauthorizedError,
+  apiFetch,
+} from "./client";
+import { storeTokens } from "../auth/oidc";
+import type { AppConfig } from "../config";
+
+const app: AppConfig = {
+  issuer: "https://auth.example.com/application/o/nestquest",
+  clientId: "test-client-id",
+  apiBaseUrl: "https://api.example.com",
+  authorizeEndpoint: "https://auth.example.com/application/o/authorize/",
+  tokenEndpoint: "https://auth.example.com/application/o/token/",
+  userinfoEndpoint: "https://auth.example.com/application/o/userinfo/",
+  endSessionEndpoint: "https://auth.example.com/application/o/nestquest/end-session/",
+  redirectUri: "http://localhost:5173/auth/callback",
+};
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("API client", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("attaches the Bearer token to API calls", async () => {
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse([]));
+
+    await apiFetch("/api/v1/children", {}, app, fetchMock as any);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://api.example.com/api/v1/children");
+    expect(init.headers.Authorization).toBe("Bearer at-123");
+  });
+
+  it("throws ApiForbiddenError on 403 (authenticated but refused)", async () => {
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    const fetchMock = vi.fn().mockResolvedValue(new Response("", { status: 403 }));
+
+    await expect(
+      apiFetch("/api/v1/children", {}, app, fetchMock as any),
+    ).rejects.toBeInstanceOf(ApiForbiddenError);
+  });
+
+  it("triggers a login redirect on 401 with no refresh token", async () => {
+    storeTokens({ access_token: "stale", expires_in: 600 });
+    const assign = vi.fn();
+    vi.stubGlobal("location", { ...window.location, assign });
+    const fetchMock = vi.fn().mockResolvedValue(new Response("", { status: 401 }));
+
+    await expect(
+      apiFetch("/api/v1/children", {}, app, fetchMock as any),
+    ).rejects.toBeInstanceOf(ApiUnauthorizedError);
+    expect(assign).toHaveBeenCalledTimes(1);
+    const url = new URL(assign.mock.calls[0][0] as string);
+    expect(url.origin + url.pathname).toBe(
+      "https://auth.example.com/application/o/authorize/",
+    );
+    expect(url.searchParams.get("code_challenge_method")).toBe("S256");
+  });
+
+  it("preserves non-401/403 statuses on the post-refresh retry (500 is not mislabeled)", async () => {
+    storeTokens({ access_token: "stale", refresh_token: "rt-1", expires_in: 600 });
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(new Response("", { status: 401 })) // initial API call
+      .mockResolvedValueOnce(
+        jsonResponse({ access_token: "fresh", expires_in: 600 }), // refresh grant
+      )
+      .mockResolvedValueOnce(new Response("", { status: 500 })); // retry
+
+    const response = await apiFetch("/api/v1/children", {}, app, fetchMock as any);
+
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(fetchMock.mock.calls[1][0]).toBe(app.tokenEndpoint);
+    expect(fetchMock.mock.calls[2][1].headers.Authorization).toBe("Bearer fresh");
+    // A server failure must surface as the real status, not ApiUnauthorizedError.
+    expect(response.status).toBe(500);
+  });
+});

admin/src/api/client.ts

@@ -0,0 +1,93 @@
+/**
+ * Minimal fetch wrapper for the NestQuest API.
+ *
+ * - Attaches `Authorization: Bearer <access_token>` when a token is stored.
+ * - 401: not authenticated (or token expired) -> trigger a new login.
+ * - 403: authenticated but refused -> throws ApiForbiddenError so the UI can
+ *   render an explicit refusal message.
+ */
+import { config, type AppConfig } from "../config";
+import {
+  buildAuthorizeUrl,
+  getToken,
+  isExpired,
+  refreshAccessToken,
+} from "../auth/oidc";
+
+export class ApiForbiddenError extends Error {
+  constructor(message = "Your account is not in the nestquest-admins group.") {
+    super(message);
+    this.name = "ApiForbiddenError";
+  }
+}
+
+export class ApiUnauthorizedError extends Error {
+  constructor(message = "Not authenticated.") {
+    super(message);
+    this.name = "ApiUnauthorizedError";
+  }
+}
+
+export interface ApiRequestOptions extends Omit<RequestInit, "headers"> {
+  headers?: Record<string, string>;
+}
+
+/**
+ * Redirect the browser to Authentik to start a new login.
+ * Exported for testing injection.
+ */
+export async function triggerLogin(app: AppConfig = config): Promise<void> {
+  const url = await buildAuthorizeUrl(app);
+  window.location.assign(url);
+}
+
+export async function apiFetch(
+  path: string,
+  options: ApiRequestOptions = {},
+  app: AppConfig = config,
+  fetchImpl: typeof fetch = fetch,
+): Promise<Response> {
+  if (isExpired() && (await refreshAccessToken(app, fetchImpl))) {
+    // token renewed; fall through and use the fresh one
+  }
+
+  const token = getToken();
+  const headers = {
+    ...(options.headers ?? {}),
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+  };
+
+  const response = await fetchImpl(`${app.apiBaseUrl}${path}`, {
+    ...options,
+    headers,
+  });
+
+  if (response.status === 401) {
+    // Not authenticated: either no token or an unusable one.
+    if (await refreshAccessToken(app, fetchImpl)) {
+      const retryToken = getToken();
+      const retryResponse = await fetchImpl(`${app.apiBaseUrl}${path}`, {
+        ...options,
+        headers: {
+          ...(options.headers ?? {}),
+          ...(retryToken ? { Authorization: `Bearer ${retryToken}` } : {}),
+        },
+      });
+      if (retryResponse.status === 403) throw new ApiForbiddenError();
+      if (retryResponse.ok) return retryResponse;
+      // Only 401 means "unauthorized"; preserve every other status (e.g. a
+      // 500 from the API) so callers can react to the real response.
+      if (retryResponse.status === 401) throw new ApiUnauthorizedError();
+      return retryResponse;
+    }
+    await triggerLogin(app);
+    throw new ApiUnauthorizedError();
+  }
+
+  if (response.status === 403) {
+    // Authenticated, but Authentik's token does not belong to nestquest-admins.
+    throw new ApiForbiddenError();
+  }
+
+  return response;
+}

admin/src/api/definitions.ts

@@ -0,0 +1,174 @@
+/**
+ * Typed client for the admin quest-definition routes and the children list
+ * the assignee picker reads (/api/v1/admin/quest-definitions, /children).
+ */
+import { apiFetch } from "./client";
+
+export type WindowName = "morning" | "afternoon" | "evening";
+
+/** Model rule names, as the admin plane serializes ScheduleRule.to_dict. */
+export type RuleType =
+  | "daily"
+  | "weekly"
+  | "monthly_day"
+  | "monthly_weekday"
+  | "yearly"
+  | "custom_days";
+
+export interface DefinitionRule {
+  rule_type: RuleType;
+  interval: number;
+  /** 0 = Monday .. 6 = Sunday. */
+  weekday_set: number[] | null;
+  day_of_month: number | null;
+  nth_weekday: number | null;
+  nth_weekday_weekday: number | null;
+  month: number | null;
+  start_date: string;
+  end_date: string | null;
+}
+
+export interface DefinitionAssignee {
+  id: number;
+  display_name: string;
+}
+
+export interface DefinitionWindow {
+  window: WindowName;
+  /** Local wall-clock "HH:MM", or null. */
+  due_time: string | null;
+}
+
+export interface QuestDefinition {
+  id: number;
+  title: string;
+  description: string | null;
+  icon: string | null;
+  is_active: boolean;
+  skip_on_away: boolean;
+  rule: DefinitionRule;
+  assignees: DefinitionAssignee[];
+  windows: DefinitionWindow[];
+}
+
+export interface AdminChild {
+  id: number;
+  display_name: string;
+  colour: string | null;
+  avatar_ref: string | null;
+  sort_order: number;
+  is_active: boolean;
+}
+
+/** A window declaration as the create/edit bodies accept it. */
+export type WindowEntry = WindowName | [WindowName, string | null];
+
+export interface DefinitionCreateBody {
+  title: string;
+  rule: DefinitionRule;
+  assignee_child_ids: number[];
+  windows: WindowEntry[];
+  description?: string | null;
+  icon?: string | null;
+  skip_on_away?: boolean;
+}
+
+export type DefinitionEditBody = Partial<DefinitionCreateBody>;
+
+export const DEFINITIONS_PATH = "/api/v1/admin/quest-definitions";
+export const CHILDREN_PATH = "/api/v1/admin/children";
+
+/** A non-2xx save response; `detail` is the API's message when it sent one. */
+export class ApiRequestError extends Error {
+  constructor(
+    readonly status: number,
+    readonly detail: string | null,
+  ) {
+    super(detail ?? `Request failed (HTTP ${status}).`);
+    this.name = "ApiRequestError";
+  }
+}
+
+/** FastAPI sends `detail` as a string (core errors) or a list of {msg} (body validation). */
+function readDetail(body: unknown): string | null {
+  if (!body || typeof body !== "object" || !("detail" in body)) return null;
+  const { detail } = body as { detail: unknown };
+  if (typeof detail === "string") return detail;
+  if (Array.isArray(detail)) {
+    const messages = detail
+      .map((item) => (item && typeof item === "object" ? (item as { msg?: unknown }).msg : null))
+      .filter((msg): msg is string => typeof msg === "string");
+    return messages.length > 0 ? messages.join("; ") : null;
+  }
+  return null;
+}
+
+export async function readJson<T>(response: Response): Promise<T> {
+  if (!response.ok) {
+    let body: unknown = null;
+    try {
+      body = await response.json();
+    } catch {
+      // Non-JSON error body: report the status alone.
+    }
+    throw new ApiRequestError(response.status, readDetail(body));
+  }
+  return (await response.json()) as T;
+}
+
+export async function fetchDefinitions(): Promise<QuestDefinition[]> {
+  const body = await readJson<{ definitions: QuestDefinition[] }>(
+    await apiFetch(DEFINITIONS_PATH),
+  );
+  return body.definitions;
+}
+
+export async function fetchChildren(): Promise<AdminChild[]> {
+  const body = await readJson<{ children: AdminChild[] }>(await apiFetch(CHILDREN_PATH));
+  return body.children;
+}
+
+function sendJson(path: string, method: "POST" | "PATCH", body: unknown): Promise<Response> {
+  return apiFetch(path, {
+    method,
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+export async function createDefinition(body: DefinitionCreateBody): Promise<QuestDefinition> {
+  return readJson<QuestDefinition>(await sendJson(DEFINITIONS_PATH, "POST", body));
+}
+
+export async function updateDefinition(
+  id: number,
+  body: DefinitionEditBody,
+): Promise<QuestDefinition> {
+  return readJson<QuestDefinition>(await sendJson(`${DEFINITIONS_PATH}/${id}`, "PATCH", body));
+}
+
+export const OCCURRENCES_PREVIEW_PATH = `${DEFINITIONS_PATH}/occurrences-preview`;
+
+export interface OccurrencesPreviewOptions {
+  /** "YYYY-MM-DD"; the API defaults to its host's today. */
+  startDate?: string;
+  /** 1..50; the API defaults to 10. */
+  count?: number;
+}
+
+/**
+ * The next occurrence dates ("YYYY-MM-DD", ascending) for `rule`, computed by
+ * the same backend recurrence engine the materializer uses.
+ */
+export async function previewOccurrences(
+  rule: DefinitionRule,
+  options: OccurrencesPreviewOptions = {},
+): Promise<string[]> {
+  const body: { rule: DefinitionRule; start_date?: string; count?: number } = { rule };
+  if (options.startDate !== undefined) body.start_date = options.startDate;
+  if (options.count !== undefined) body.count = options.count;
+  const response = await readJson<{ dates: string[] }>(
+    await sendJson(OCCURRENCES_PREVIEW_PATH, "POST", body),
+  );
+  return response.dates;
+}

admin/src/api/events.test.ts

@@ -0,0 +1,162 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { waitFor } from "@testing-library/react";
+import { EVENTS_PATH, SseParser, openTransitionStream, type TransitionEvent } from "./events";
+import { frame, testStream, type TestStream } from "./testStream";
+import { storeTokens } from "../auth/oidc";
+
+const COMPLETED = {
+  child_id: 1,
+  child_name: "Declan",
+  instance_id: 12,
+  quest_title: "Make bed",
+  window: "morning",
+  due_date: "2026-09-23",
+  due_time: null,
+  occurred_at: "2026-09-23T11:04:00Z",
+};
+const DAY_COMPLETE = {
+  child_id: 2,
+  child_name: "Maeve",
+  quests_due: 4,
+  quests_completed: 4,
+  occurred_at: "2026-09-23T12:00:00Z",
+};
+
+describe("SseParser", () => {
+  it("yields every frame from one chunk", () => {
+    const parser = new SseParser();
+    const events = parser.push(
+      frame("nestquest_quest_completed", COMPLETED) +
+        frame("nestquest_child_day_complete", DAY_COMPLETE),
+    );
+    expect(events).toEqual([
+      { type: "nestquest_quest_completed", payload: COMPLETED },
+      { type: "nestquest_child_day_complete", payload: DAY_COMPLETE },
+    ]);
+  });
+
+  it("buffers a frame split across two chunks", () => {
+    const parser = new SseParser();
+    const text = frame("nestquest_quest_uncompleted", COMPLETED);
+    const cut = text.indexOf("Make");
+    expect(parser.push(text.slice(0, cut))).toEqual([]);
+    expect(parser.push(text.slice(cut))).toEqual([
+      { type: "nestquest_quest_uncompleted", payload: COMPLETED },
+    ]);
+  });
+
+  it("buffers a split inside the event name and the blank-line terminator", () => {
+    const parser = new SseParser();
+    const text = frame("nestquest_quest_missed", COMPLETED);
+    expect(parser.push(text.slice(0, 12))).toEqual([]);
+    expect(parser.push(text.slice(12, -1))).toEqual([]);
+    expect(parser.push(text.slice(-1))).toEqual([
+      { type: "nestquest_quest_missed", payload: COMPLETED },
+    ]);
+  });
+
+  it("treats a CRLF split across chunks as one line break", () => {
+    const parser = new SseParser();
+    const text = `event: nestquest_quest_completed\r\ndata: ${JSON.stringify(COMPLETED)}\r\n\r\n`;
+    const cut = text.indexOf("\n"); // chunk ends on "\r"
+    expect(parser.push(text.slice(0, cut))).toEqual([]);
+    expect(parser.push(text.slice(cut))).toEqual([
+      { type: "nestquest_quest_completed", payload: COMPLETED },
+    ]);
+  });
+
+  it("drops malformed, unknown and comment frames without throwing", () => {
+    const parser = new SseParser();
+    const events = parser.push(
+      "event: nestquest_quest_completed\ndata: not-json\n\n" +
+        "event: nestquest_quest_completed\ndata: [1,2]\n\n" +
+        "event: something_else\ndata: {}\n\n" +
+        ": keep-alive\n\n" +
+        "data: {}\n\n" +
+        frame("nestquest_quest_completed", COMPLETED),
+    );
+    expect(events).toEqual([{ type: "nestquest_quest_completed", payload: COMPLETED }]);
+  });
+});
+
+describe("openTransitionStream", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let streams: TestStream[];
+  let stop: (() => void) | null;
+
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    streams = [];
+    stop = null;
+    fetchMock = vi.fn(() => {
+      const stream = testStream();
+      streams.push(stream);
+      return Promise.resolve(stream.response);
+    });
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    stop?.();
+    vi.unstubAllGlobals();
+  });
+
+  it("sends the token in the Authorization header, never in the URL", async () => {
+    stop = openTransitionStream({ onTransition: () => {} });
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toMatch(new RegExp(`${EVENTS_PATH}$`));
+    expect(String(url)).not.toContain("at-123");
+    expect(init.headers.Authorization).toBe("Bearer at-123");
+    expect(init.headers.Accept).toBe("text/event-stream");
+  });
+
+  it("delivers transitions from frames split across chunks", async () => {
+    const seen: TransitionEvent[] = [];
+    stop = openTransitionStream({ onTransition: (event) => seen.push(event) });
+    await waitFor(() => expect(streams).toHaveLength(1));
+    const text = frame("nestquest_quest_completed", COMPLETED);
+    streams[0].push(text.slice(0, 20));
+    streams[0].push(text.slice(20));
+    await waitFor(() =>
+      expect(seen).toEqual([{ type: "nestquest_quest_completed", payload: COMPLETED }]),
+    );
+  });
+
+  it("stop aborts the request and cancels the body", async () => {
+    stop = openTransitionStream({ onTransition: () => {} });
+    await waitFor(() => expect(streams).toHaveLength(1));
+    const signal = fetchMock.mock.calls[0][1].signal as AbortSignal;
+    stop();
+    expect(signal.aborted).toBe(true);
+    await waitFor(() => expect(streams[0].cancelled()).toBe(true));
+  });
+
+  it("reconnects after the stream drops", async () => {
+    const seen: TransitionEvent[] = [];
+    stop = openTransitionStream({ onTransition: (event) => seen.push(event), minDelayMs: 5 });
+    await waitFor(() => expect(streams).toHaveLength(1));
+    streams[0].close();
+    await waitFor(() => expect(streams).toHaveLength(2));
+    streams[1].push(frame("nestquest_quest_missed", COMPLETED));
+    await waitFor(() => expect(seen).toHaveLength(1));
+  });
+
+  it("does not reconnect after stop, even with a reconnect pending", async () => {
+    stop = openTransitionStream({ onTransition: () => {}, minDelayMs: 20 });
+    await waitFor(() => expect(streams).toHaveLength(1));
+    streams[0].close();
+    stop();
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("gives up on a 403 refusal instead of retrying", async () => {
+    fetchMock.mockImplementation(() => Promise.resolve(new Response("", { status: 403 })));
+    stop = openTransitionStream({ onTransition: () => {}, minDelayMs: 5 });
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1));
+    await new Promise((resolve) => setTimeout(resolve, 40));
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});

admin/src/api/events.ts

@@ -0,0 +1,196 @@
+/**
+ * Live transition stream: GET /api/v1/admin/events (text/event-stream).
+ *
+ * The admin JWT travels in the Authorization header (via apiFetch), so the
+ * stream is read with fetch + a ReadableStream reader — EventSource cannot
+ * set headers, and the token must never go into a URL.
+ */
+import { ApiForbiddenError, ApiUnauthorizedError, apiFetch } from "./client";
+
+export const EVENTS_PATH = "/api/v1/admin/events";
+
+/** The four documented transitions, as the API names them on the wire. */
+export const TRANSITION_TYPES = [
+  "nestquest_quest_completed",
+  "nestquest_quest_uncompleted",
+  "nestquest_quest_missed",
+  "nestquest_child_day_complete",
+] as const;
+
+export type TransitionType = (typeof TRANSITION_TYPES)[number];
+
+/** Quest transitions carry the instance; a day-complete carries the child's counts. */
+export interface QuestTransitionPayload {
+  child_id: number;
+  child_name: string | null;
+  instance_id: number;
+  quest_title: string | null;
+  window: string;
+  due_date: string;
+  due_time: string | null;
+  occurred_at: string;
+}
+
+export interface ChildDayCompletePayload {
+  child_id: number;
+  child_name: string | null;
+  quests_due: number;
+  quests_completed: number;
+  occurred_at: string;
+}
+
+export type TransitionEvent =
+  | {
+      type:
+        | "nestquest_quest_completed"
+        | "nestquest_quest_uncompleted"
+        | "nestquest_quest_missed";
+      payload: QuestTransitionPayload;
+    }
+  | { type: "nestquest_child_day_complete"; payload: ChildDayCompletePayload };
+
+function isTransitionType(value: string): value is TransitionType {
+  return (TRANSITION_TYPES as readonly string[]).includes(value);
+}
+
+/**
+ * Incremental SSE frame parser. Feed it decoded text in whatever chunks the
+ * network delivers; it buffers a partial line or frame until it completes.
+ * Comments (keep-alives), unknown event types and frames whose data is not a
+ * JSON object are dropped, never thrown.
+ */
+export class SseParser {
+  private buffer = "";
+  private eventType = "";
+  private data: string[] = [];
+  /** A chunk ended on "\r": a leading "\n" in the next chunk is the same line break. */
+  private pendingCr = false;
+
+  push(text: string): TransitionEvent[] {
+    if (this.pendingCr && text.startsWith("\n")) text = text.slice(1);
+    this.pendingCr = text.endsWith("\r");
+    this.buffer += text;
+    const lines = this.buffer.split(/\r\n|\r|\n/);
+    this.buffer = lines.pop() ?? "";
+    const events: TransitionEvent[] = [];
+    for (const line of lines) {
+      const event = this.line(line);
+      if (event) events.push(event);
+    }
+    return events;
+  }
+
+  private line(line: string): TransitionEvent | null {
+    if (line === "") return this.dispatch();
+    if (line.startsWith(":")) return null;
+    const colon = line.indexOf(":");
+    const field = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (field === "event") this.eventType = value;
+    else if (field === "data") this.data.push(value);
+    return null;
+  }
+
+  private dispatch(): TransitionEvent | null {
+    const type = this.eventType;
+    const data = this.data.join("\n");
+    this.eventType = "";
+    this.data = [];
+    if (!isTransitionType(type)) return null;
+    let payload: unknown;
+    try {
+      payload = JSON.parse(data);
+    } catch {
+      return null;
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+    return { type, payload } as TransitionEvent;
+  }
+}
+
+export interface TransitionStreamOptions {
+  onTransition: (event: TransitionEvent) => void;
+  /** Reconnect delay after a drop: starts at `minDelayMs`, doubles up to `maxDelayMs`. */
+  minDelayMs?: number;
+  maxDelayMs?: number;
+}
+
+function wait(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+    function done() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    }
+  });
+}
+
+/** Read one connection until the body ends (or the signal aborts). */
+async function readOnce(
+  signal: AbortSignal,
+  onTransition: (event: TransitionEvent) => void,
+): Promise<void> {
+  const response = await apiFetch(EVENTS_PATH, {
+    signal,
+    headers: { Accept: "text/event-stream" },
+  });
+  if (!response.ok || !response.body) {
+    throw new Error(`Event stream request failed (HTTP ${response.status}).`);
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const parser = new SseParser();
+  const cancel = () => void reader.cancel().catch(() => {});
+  signal.addEventListener("abort", cancel, { once: true });
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done || signal.aborted) break;
+      for (const event of parser.push(decoder.decode(value, { stream: true }))) {
+        if (signal.aborted) break;
+        onTransition(event);
+      }
+    }
+  } finally {
+    signal.removeEventListener("abort", cancel);
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Subscribe to the admin transition stream, reconnecting with a bounded
+ * backoff after a drop. Returns a stop function that aborts the open request
+ * and any pending reconnect. A 401/403 stops the stream for good: apiFetch
+ * has already started a login (401) or the account is refused (403).
+ */
+export function openTransitionStream({
+  onTransition,
+  minDelayMs = 1_000,
+  maxDelayMs = 30_000,
+}: TransitionStreamOptions): () => void {
+  const controller = new AbortController();
+  const { signal } = controller;
+
+  void (async () => {
+    let delay = minDelayMs;
+    while (!signal.aborted) {
+      try {
+        await readOnce(signal, onTransition);
+        // A connection that was accepted and then ended starts the backoff over.
+        delay = minDelayMs;
+      } catch (error: unknown) {
+        if (signal.aborted) return;
+        if (error instanceof ApiUnauthorizedError || error instanceof ApiForbiddenError) return;
+        // Dropped or refused connection: fall through to the backoff.
+      }
+      if (signal.aborted) return;
+      await wait(delay, signal);
+      delay = Math.min(delay * 2, maxDelayMs);
+    }
+  })();
+
+  return () => controller.abort();
+}

admin/src/api/history.ts

@@ -0,0 +1,85 @@
+/**
+ * Typed client for the admin history route (/api/v1/admin/history): the
+ * append-only event log over a closed due-date range for one filter.
+ */
+import { apiFetch } from "./client";
+import { ApiRequestError, readJson } from "./definitions";
+
+export type HistoryFilter = "all" | "reversals" | "missed";
+
+export type HistoryEventType = "completed" | "uncompleted" | "missed";
+
+export interface HistoryRow {
+  /** UTC ISO stamp; null for a derived missed row (there is no event). */
+  occurred_at: string | null;
+  event_type: HistoryEventType;
+  child_name: string;
+  child_id: number;
+  quest_title: string;
+  instance_id: number;
+  window: string;
+  /** "YYYY-MM-DD", the day the task was owed. */
+  due_date: string;
+  /** Local wall-clock "HH:MM", or null. */
+  due_time: string | null;
+  /** e.g. "panel (Declan)", "joshua (admin)", "nightly sweep". */
+  actor: string;
+  was_on_time: boolean | null;
+}
+
+export interface HistoryResponse {
+  filter: HistoryFilter;
+  start: string;
+  end: string;
+  count: number;
+  rows: HistoryRow[];
+}
+
+export const HISTORY_PATH = "/api/v1/admin/history";
+
+/** `start`/`end` are inclusive "YYYY-MM-DD" due dates. */
+export async function fetchHistory(
+  filter: HistoryFilter,
+  start: string,
+  end: string,
+): Promise<HistoryResponse> {
+  const params = new URLSearchParams({ start, end, filter });
+  return readJson<HistoryResponse>(await apiFetch(`${HISTORY_PATH}?${params.toString()}`));
+}
+
+export const HISTORY_CSV_PATH = "/api/v1/admin/history.csv";
+
+export interface HistoryCsv {
+  blob: Blob;
+  filename: string;
+}
+
+/** The `filename` from a Content-Disposition header, or null. */
+export function csvFilename(disposition: string | null): string | null {
+  const match = disposition?.match(/filename="?([^";]+)"?/i);
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * The CSV export of the same range and filter as `fetchHistory`. Goes through
+ * apiFetch so the admin token travels in the Authorization header.
+ */
+export async function exportHistoryCsv(
+  filter: HistoryFilter,
+  start: string,
+  end: string,
+): Promise<HistoryCsv> {
+  const params = new URLSearchParams({ start, end, filter });
+  const response = await apiFetch(`${HISTORY_CSV_PATH}?${params.toString()}`);
+  if (!response.ok) {
+    // readJson raises ApiRequestError with the API's `detail` for a non-OK response.
+    await readJson<never>(response);
+    throw new ApiRequestError(response.status, null);
+  }
+  return {
+    blob: await response.blob(),
+    filename:
+      csvFilename(response.headers.get("Content-Disposition")) ??
+      `nestquest-history-${start}-to-${end}.csv`,
+  };
+}

admin/src/api/instances.ts

@@ -0,0 +1,23 @@
+/**
+ * Typed client for the admin instance mutation route
+ * (POST /api/v1/admin/instances/{id}/uncomplete).
+ */
+import { apiFetch } from "./client";
+import { readJson } from "./definitions";
+
+export interface UncompleteResult {
+  instance_id: number;
+  /** The derived state after the reversal: "open", or "missed" when past due. */
+  state: string;
+  /** False when the instance was already open (a no-op). */
+  appended: boolean;
+}
+
+export function uncompletePath(instanceId: number): string {
+  return `/api/v1/admin/instances/${instanceId}/uncomplete`;
+}
+
+/** Reverse one completion; raises ApiRequestError with the API's detail on failure. */
+export async function uncompleteInstance(instanceId: number): Promise<UncompleteResult> {
+  return readJson<UncompleteResult>(await apiFetch(uncompletePath(instanceId), { method: "POST" }));
+}

admin/src/api/presence.ts

@@ -0,0 +1,146 @@
+/**
+ * Typed client for the admin presence routes: a child's repeating patterns
+ * (/api/v1/admin/children/{id}/presence-patterns, /presence-patterns/{id})
+ * and the household's date-range overrides (/api/v1/admin/presence-overrides).
+ */
+import { apiFetch } from "./client";
+import { CHILDREN_PATH, readJson } from "./definitions";
+
+/** A pattern claims its covered days as the child being home or away. */
+export type PatternKind = "home" | "away";
+
+/**
+ * Cycle week index ("0".."n-1", JSON object keys) -> covered weekdays
+ * (0 = Monday .. 6 = Sunday). An empty list covers nothing that week.
+ */
+export type PatternWeeks = Record<string, number[]>;
+
+/** The anchor-based cycle every pattern repeats on. */
+export interface PatternCycle {
+  cycle_length_weeks: number;
+  /** "YYYY-MM-DD"; pins cycle week 0. */
+  anchor_date: string;
+  pattern: PatternWeeks;
+}
+
+export interface PresencePatternBody extends PatternCycle {
+  name: string;
+  kind: PatternKind;
+}
+
+export interface PresencePattern extends PresencePatternBody {
+  id: number;
+  child_id: number;
+}
+
+export interface PresenceOverride {
+  id: number;
+  child_id: number;
+  start_date: string;
+  end_date: string;
+  is_present: boolean;
+  note: string | null;
+}
+
+export interface PresenceOverrideFilter {
+  childId?: number;
+  /** "YYYY-MM-DD"; keeps overrides overlapping [start, end]. */
+  start?: string;
+  end?: string;
+}
+
+export const PRESENCE_OVERRIDES_PATH = "/api/v1/admin/presence-overrides";
+export const PRESENCE_PATTERNS_PATH = "/api/v1/admin/presence-patterns";
+
+export function childPatternsPath(childId: number): string {
+  return `${CHILDREN_PATH}/${childId}/presence-patterns`;
+}
+
+function sendJson(path: string, method: "POST" | "PATCH", body: unknown): Promise<Response> {
+  return apiFetch(path, {
+    method,
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+}
+
+/** The child's patterns in id order; empty when it has none (present every day). */
+export async function fetchPresencePatterns(childId: number): Promise<PresencePattern[]> {
+  const body = await readJson<{ patterns: PresencePattern[] }>(
+    await apiFetch(childPatternsPath(childId)),
+  );
+  return body.patterns;
+}
+
+export async function createPresencePattern(
+  childId: number,
+  body: PresencePatternBody,
+): Promise<PresencePattern> {
+  return readJson<PresencePattern>(await sendJson(childPatternsPath(childId), "POST", body));
+}
+
+/** Change only the supplied fields; resolves to the pattern as stored. */
+export async function updatePresencePattern(
+  patternId: number,
+  body: Partial<PresencePatternBody>,
+): Promise<PresencePattern> {
+  return readJson<PresencePattern>(
+    await sendJson(`${PRESENCE_PATTERNS_PATH}/${patternId}`, "PATCH", body),
+  );
+}
+
+export async function deletePresencePattern(patternId: number): Promise<void> {
+  await readJson<{ status: string }>(
+    await apiFetch(`${PRESENCE_PATTERNS_PATH}/${patternId}`, { method: "DELETE" }),
+  );
+}
+
+export async function fetchPresenceOverrides(
+  filter: PresenceOverrideFilter = {},
+): Promise<PresenceOverride[]> {
+  const params = new URLSearchParams();
+  if (filter.childId !== undefined) params.set("child_id", String(filter.childId));
+  if (filter.start !== undefined) params.set("start", filter.start);
+  if (filter.end !== undefined) params.set("end", filter.end);
+  const query = params.toString();
+  const body = await readJson<{ overrides: PresenceOverride[] }>(
+    await apiFetch(query ? `${PRESENCE_OVERRIDES_PATH}?${query}` : PRESENCE_OVERRIDES_PATH),
+  );
+  return body.overrides;
+}
+
+export interface PresenceOverrideRange {
+  child_id: number;
+  /** "YYYY-MM-DD", inclusive. */
+  start_date: string;
+  /** "YYYY-MM-DD", inclusive; never before start_date. */
+  end_date: string;
+  is_present: boolean;
+}
+
+export interface PresenceOverrideBody extends PresenceOverrideRange {
+  note?: string;
+}
+
+export const PRESENCE_OVERRIDE_CONSEQUENCE_PATH = `${PRESENCE_OVERRIDES_PATH}/consequence`;
+
+/**
+ * How many open upcoming tasks saving this override would remove. Computed
+ * by the API before anything is saved; completed instances never count.
+ */
+export async function previewOverrideConsequence(range: PresenceOverrideRange): Promise<number> {
+  const body = await readJson<{ removed: number }>(
+    await sendJson(PRESENCE_OVERRIDE_CONSEQUENCE_PATH, "POST", range),
+  );
+  return body.removed;
+}
+
+export async function createPresenceOverride(body: PresenceOverrideBody): Promise<PresenceOverride> {
+  return readJson<PresenceOverride>(await sendJson(PRESENCE_OVERRIDES_PATH, "POST", body));
+}
+
+export async function deletePresenceOverride(overrideId: number): Promise<void> {
+  await readJson<{ status: string }>(
+    await apiFetch(`${PRESENCE_OVERRIDES_PATH}/${overrideId}`, { method: "DELETE" }),
+  );
+}

admin/src/api/settings.ts

@@ -0,0 +1,39 @@
+/**
+ * Typed client for the admin household-settings routes
+ * (/api/v1/admin/settings).
+ */
+import { apiFetch } from "./client";
+import { readJson } from "./definitions";
+
+export interface HouseholdSettings {
+  horizon_days: number;
+  /** Local wall-clock "HH:MM", as are the other *_time fields. */
+  day_rollover_time: string;
+  notify_target: string;
+  morning_summary_time: string;
+  afternoon_reminder_time: string;
+  end_of_day_report_time: string;
+  morning_summary_enabled: boolean;
+  afternoon_reminder_enabled: boolean;
+  end_of_day_report_enabled: boolean;
+  celebration_enabled: boolean;
+}
+
+/** Only the supplied fields are updated; the API answers with all of them. */
+export type SettingsChanges = Partial<HouseholdSettings>;
+
+export const SETTINGS_PATH = "/api/v1/admin/settings";
+
+export async function fetchSettings(): Promise<HouseholdSettings> {
+  return readJson<HouseholdSettings>(await apiFetch(SETTINGS_PATH));
+}
+
+export async function updateSettings(changes: SettingsChanges): Promise<HouseholdSettings> {
+  return readJson<HouseholdSettings>(
+    await apiFetch(SETTINGS_PATH, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(changes),
+    }),
+  );
+}

admin/src/api/snapshot.ts

@@ -0,0 +1,55 @@
+/**
+ * Typed client for GET /api/v1/admin/snapshot — today's household snapshot
+ * that drives the admin Today tab.
+ */
+import { apiFetch } from "./client";
+
+export type InstanceWindow = "morning" | "afternoon" | "evening";
+export type InstanceState = "open" | "completed" | "missed";
+
+export interface SnapshotInstance {
+  id: number;
+  definition_id: number;
+  child_id: number;
+  title: string;
+  icon: string | null;
+  window: InstanceWindow;
+  /** Local wall-clock "HH:MM", or null when the definition has no due time. */
+  due_time: string | null;
+  state: InstanceState;
+  overdue: boolean;
+  /** UTC ISO timestamp of the completion event, when completed. */
+  completed_at: string | null;
+  on_time: boolean | null;
+}
+
+export interface SnapshotChild {
+  child_id: number;
+  child_name: string;
+  present: boolean;
+  /** "YYYY-MM-DD" of the next present day, or null. */
+  next_present: string | null;
+  due_today: number;
+  completed_today: number;
+  remaining_today: number;
+  completion_pct: number;
+  instances: SnapshotInstance[];
+}
+
+export interface AdminSnapshot {
+  /** "YYYY-MM-DD" in the household's local zone. */
+  today_iso: string;
+  /** 1-based day in the custody cycle. */
+  cycle_day: number;
+  children: SnapshotChild[];
+}
+
+export const SNAPSHOT_PATH = "/api/v1/admin/snapshot";
+
+export async function fetchSnapshot(): Promise<AdminSnapshot> {
+  const response = await apiFetch(SNAPSHOT_PATH);
+  if (!response.ok) {
+    throw new Error(`Snapshot request failed (HTTP ${response.status}).`);
+  }
+  return (await response.json()) as AdminSnapshot;
+}

admin/src/api/testStream.ts

@@ -0,0 +1,39 @@
+/**
+ * Test helper: a controllable text/event-stream Response whose body the test
+ * feeds chunk by chunk (so a frame can be split across chunk boundaries).
+ */
+export interface TestStream {
+  response: Response;
+  push(text: string): void;
+  close(): void;
+  /** True once the reader cancelled the body (the stream was torn down). */
+  cancelled(): boolean;
+}
+
+export function testStream(): TestStream {
+  const encoder = new TextEncoder();
+  let controller!: ReadableStreamDefaultController<Uint8Array>;
+  let cancelled = false;
+  const body = new ReadableStream<Uint8Array>({
+    start(c) {
+      controller = c;
+    },
+    cancel() {
+      cancelled = true;
+    },
+  });
+  return {
+    response: new Response(body, {
+      status: 200,
+      headers: { "Content-Type": "text/event-stream" },
+    }),
+    push: (text) => controller.enqueue(encoder.encode(text)),
+    close: () => controller.close(),
+    cancelled: () => cancelled,
+  };
+}
+
+/** One SSE frame exactly as api/sse.py writes it. */
+export function frame(type: string, payload: unknown): string {
+  return `event: ${type}\ndata: ${JSON.stringify(payload)}\n\n`;
+}

admin/src/api/useTransitions.tsx

@@ -0,0 +1,61 @@
+/**
+ * One live transition stream per signed-in shell, fanned out to the screens.
+ *
+ * <TransitionsProvider> opens the stream on mount and aborts it on unmount;
+ * useTransitions(handler) registers a screen's handler for as long as the
+ * screen is mounted. Without a provider the hook does nothing, so a screen
+ * rendered on its own (e.g. in a test) never opens a stream.
+ */
+import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from "react";
+import { openTransitionStream, type TransitionEvent } from "./events";
+
+type Listener = (event: TransitionEvent) => void;
+
+interface TransitionHub {
+  subscribe(listener: Listener): () => void;
+}
+
+const TransitionsContext = createContext<TransitionHub | null>(null);
+
+export function TransitionsProvider({ children }: { children: ReactNode }) {
+  const [hub] = useState(() => {
+    const listeners = new Set<Listener>();
+    return {
+      listeners,
+      subscribe(listener: Listener) {
+        listeners.add(listener);
+        return () => {
+          listeners.delete(listener);
+        };
+      },
+    };
+  });
+
+  useEffect(
+    () =>
+      openTransitionStream({
+        onTransition: (event) => {
+          for (const listener of [...hub.listeners]) {
+            try {
+              listener(event);
+            } catch {
+              // One screen's handler must not tear down the shared stream.
+            }
+          }
+        },
+      }),
+    [hub],
+  );
+
+  return <TransitionsContext.Provider value={hub}>{children}</TransitionsContext.Provider>;
+}
+
+/** Call `handler` for every transition while the calling component is mounted. */
+export function useTransitions(handler: Listener): void {
+  const hub = useContext(TransitionsContext);
+  const handlerRef = useRef(handler);
+  useEffect(() => {
+    handlerRef.current = handler;
+  });
+  useEffect(() => hub?.subscribe((event) => handlerRef.current(event)), [hub]);
+}

admin/src/auth/oidc.test.ts

@@ -0,0 +1,173 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  buildAuthorizeUrl,
+  clearAuth,
+  getToken,
+  handleCallback,
+  logout,
+  storeTokens,
+} from "./oidc";
+import type { AppConfig } from "../config";
+
+function testApp(): AppConfig {
+  return {
+    issuer: "https://auth.example.com/application/o/nestquest",
+    clientId: "test-client-id",
+    apiBaseUrl: "https://api.example.com",
+    authorizeEndpoint: "https://auth.example.com/application/o/authorize/",
+    tokenEndpoint: "https://auth.example.com/application/o/token/",
+    userinfoEndpoint: "https://auth.example.com/application/o/userinfo/",
+    endSessionEndpoint: "https://auth.example.com/application/o/nestquest/end-session/",
+    redirectUri: "http://localhost:5173/auth/callback",
+  };
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("OIDC flow", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("buildAuthorizeUrl carries all required params and stores state/verifier", async () => {
+    const app = testApp();
+    const url = new URL(await buildAuthorizeUrl(app));
+
+    expect(url.origin + url.pathname).toBe(app.authorizeEndpoint);
+    expect(url.searchParams.get("response_type")).toBe("code");
+    expect(url.searchParams.get("client_id")).toBe("test-client-id");
+    expect(url.searchParams.get("redirect_uri")).toBe(app.redirectUri);
+    expect(url.searchParams.get("scope")).toBe("openid email profile");
+    expect(url.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(url.searchParams.get("code_challenge")).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(url.searchParams.get("state")).toMatch(/^[A-Za-z0-9_-]+$/);
+
+    expect(sessionStorage.getItem("nestquest.oidc_state")).toBe(
+      url.searchParams.get("state"),
+    );
+    expect(sessionStorage.getItem("nestquest.code_verifier")).toMatch(/^[A-Za-z0-9-._~]{43,128}$/);
+  });
+
+  it("handleCallback rejects a mismatched state", async () => {
+    await buildAuthorizeUrl(testApp());
+    sessionStorage.setItem("nestquest.oidc_state", "different-state");
+
+    const fetchMock = vi.fn();
+    await expect(
+      handleCallback("?code=abc&state=tampered", testApp(), fetchMock as any),
+    ).rejects.toThrow(/state mismatch/i);
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(getToken()).toBeUndefined();
+  });
+
+  it("handleCallback exchanges the code with the correct form body and stores the token", async () => {
+    await buildAuthorizeUrl(testApp());
+    const verifier = sessionStorage.getItem("nestquest.code_verifier")!;
+    const state = sessionStorage.getItem("nestquest.oidc_state")!;
+
+    const fetchMock = vi.fn().mockResolvedValue(
+      jsonResponse({
+        access_token: "at-123",
+        refresh_token: "rt-456",
+        id_token: "id-789",
+        expires_in: 300,
+      }),
+    );
+    await handleCallback(`?code=abc&state=${state}`, testApp(), fetchMock as any);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://auth.example.com/application/o/token/");
+    expect(init.method).toBe("POST");
+    expect(init.headers["Content-Type"]).toBe("application/x-www-form-urlencoded");
+
+    const body = new URLSearchParams(init.body);
+    expect(body.get("grant_type")).toBe("authorization_code");
+    expect(body.get("code")).toBe("abc");
+    expect(body.get("redirect_uri")).toBe(testApp().redirectUri);
+    expect(body.get("client_id")).toBe("test-client-id");
+    expect(body.get("code_verifier")).toBe(verifier);
+    expect(body.has("client_secret")).toBe(false);
+
+    expect(getToken()).toBe("at-123");
+    // one-time values consumed
+    expect(sessionStorage.getItem("nestquest.oidc_state")).toBeNull();
+    expect(sessionStorage.getItem("nestquest.code_verifier")).toBeNull();
+  });
+
+  it("handleCallback surfaces provider errors", async () => {
+    await expect(
+      handleCallback("?error=access_denied&error_description=nope", testApp(), vi.fn() as any),
+    ).rejects.toThrow(/nope|access_denied/);
+  });
+
+  it("clearAuth removes all stored auth data", () => {
+    storeTokens({ access_token: "a", refresh_token: "r", expires_in: 60 });
+    clearAuth();
+    expect(getToken()).toBeUndefined();
+    expect(sessionStorage.length).toBe(0);
+  });
+
+  it("logout clears auth and redirects to the end-session endpoint", async () => {
+    storeTokens({ access_token: "a", id_token: "idt", expires_in: 60 });
+    const assign = vi.fn();
+    const original = window.location;
+    vi.stubGlobal("location", { ...original, assign, origin: "http://localhost:5173" });
+
+    await logout(testApp());
+
+    expect(assign).toHaveBeenCalledTimes(1);
+    const url = new URL(assign.mock.calls[0][0] as string);
+    expect(url.toString()).toBe(
+      "https://auth.example.com/application/o/nestquest/end-session/?id_token_hint=idt&client_id=test-client-id&post_logout_redirect_uri=http%3A%2F%2Flocalhost%3A5173",
+    );
+    expect(getToken()).toBeUndefined();
+    vi.unstubAllGlobals();
+  });
+
+  it("buildAuthorizeUrl resolves the authorize endpoint via discovery for a non-default issuer", async () => {
+    const issuer = "https://sso.discovery.example/application/o/discovered";
+    const discoveryDoc = {
+      issuer,
+      authorization_endpoint: "https://sso.discovery.example/application/o/authorize/",
+      token_endpoint: "https://sso.discovery.example/application/o/token/",
+      userinfo_endpoint: "https://sso.discovery.example/application/o/userinfo/",
+      end_session_endpoint: `${issuer}/end-session/`,
+      jwks_uri: `${issuer}/jwks/`,
+    };
+    const fetchMock = vi.fn().mockImplementation((url: string) =>
+      Promise.resolve(
+        String(url).endsWith("/.well-known/openid-configuration")
+          ? jsonResponse(discoveryDoc)
+          : jsonResponse({}),
+      ),
+    );
+    const app: AppConfig = {
+      issuer,
+      clientId: "test-client-id",
+      apiBaseUrl: "https://api.example.com",
+      redirectUri: "http://localhost:5173/auth/callback",
+    };
+
+    const url = new URL(await buildAuthorizeUrl(app, fetchMock as any));
+
+    // The authorize endpoint comes from the discovery document — Authentik
+    // serves it outside the app-specific issuer path, so it is NOT
+    // `${issuer}/authorize/` and must never be a hardcoded production host.
+    expect(url.origin + url.pathname).toBe(discoveryDoc.authorization_endpoint);
+    expect(url.searchParams.get("client_id")).toBe("test-client-id");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(String(fetchMock.mock.calls[0][0])).toBe(
+      `${issuer}/.well-known/openid-configuration`,
+    );
+  });
+});

admin/src/auth/oidc.ts

@@ -0,0 +1,225 @@
+/**
+ * OIDC authorization-code + PKCE flow for a PUBLIC client.
+ *
+ * Never sends a client_secret anywhere. Tokens are stored in sessionStorage
+ * (per-tab, cleared on tab close) — never localStorage.
+ */
+import { config, resolveEndpoints, type AppConfig, type ResolvedAppConfig } from "../config";
+import {
+  computeCodeChallenge,
+  generateCodeVerifier,
+  generateState,
+} from "./pkce";
+
+const STORAGE_KEYS = {
+  accessToken: "nestquest.access_token",
+  refreshToken: "nestquest.refresh_token",
+  expiresAt: "nestquest.expires_at",
+  idToken: "nestquest.id_token",
+  state: "nestquest.oidc_state",
+  codeVerifier: "nestquest.code_verifier",
+} as const;
+
+export class AuthError extends Error {}
+
+export interface TokenResponse {
+  access_token?: string;
+  refresh_token?: string;
+  id_token?: string;
+  expires_in?: number;
+  token_type?: string;
+}
+
+function makeScopes(): string {
+  return "openid email profile";
+}
+
+/**
+ * Build the Authentik authorization redirect URL, storing state + verifier in
+ * sessionStorage so the callback can validate them. Endpoints are resolved
+ * from the issuer's OIDC discovery document when not set on the config.
+ */
+export async function buildAuthorizeUrl(
+  app: AppConfig = config,
+  fetchImpl: typeof fetch = fetch,
+): Promise<string> {
+  if (!app.clientId) {
+    throw new AuthError(
+      "Missing VITE_AUTHENTIK_CLIENT_ID configuration. Set it in your .env before building the admin PWA.",
+    );
+  }
+  const resolved = await resolveEndpoints(app, fetchImpl);
+  const state = generateState();
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = await computeCodeChallenge(codeVerifier);
+
+  sessionStorage.setItem(STORAGE_KEYS.state, state);
+  sessionStorage.setItem(STORAGE_KEYS.codeVerifier, codeVerifier);
+
+  const url = new URL(resolved.authorizeEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", app.clientId);
+  url.searchParams.set("redirect_uri", app.redirectUri);
+  url.searchParams.set("scope", makeScopes());
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  return url.toString();
+}
+
+/**
+ * Handle the OAuth callback: validate state, exchange the code at the token
+ * endpoint (PKCE, form-urlencoded, no client_secret), store tokens.
+ */
+export async function handleCallback(
+  query: URLSearchParams | string = window.location.search,
+  app: AppConfig = config,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  const params =
+    typeof query === "string" ? new URLSearchParams(query) : query;
+
+  const providerError = params.get("error");
+  if (providerError) {
+    throw new AuthError(
+      params.get("error_description") || `Provider returned error: ${providerError}`,
+    );
+  }
+
+  const code = params.get("code");
+  const state = params.get("state");
+  if (!code || !state) {
+    throw new AuthError("Callback is missing the code or state parameter.");
+  }
+
+  const storedState = sessionStorage.getItem(STORAGE_KEYS.state);
+  const codeVerifier = sessionStorage.getItem(STORAGE_KEYS.codeVerifier);
+  if (!storedState || storedState !== state || !codeVerifier) {
+    throw new AuthError("State mismatch — possible CSRF; refusing to log in.");
+  }
+
+  if (!app.clientId) {
+    throw new AuthError(
+      "Missing VITE_AUTHENTIK_CLIENT_ID configuration. Set it in your .env before building the admin PWA.",
+    );
+  }
+
+  const resolved: ResolvedAppConfig = await resolveEndpoints(app, fetchImpl);
+
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: app.redirectUri,
+    client_id: app.clientId,
+    code_verifier: codeVerifier,
+  });
+
+  const response = await fetchImpl(resolved.tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+  if (!response.ok) {
+    throw new AuthError(`Token exchange failed with HTTP ${response.status}`);
+  }
+  const tokens = (await response.json()) as TokenResponse;
+  if (!tokens.access_token) {
+    throw new AuthError("Token response did not include an access token.");
+  }
+
+  storeTokens(tokens);
+  // One-time use values are consumed on success.
+  sessionStorage.removeItem(STORAGE_KEYS.state);
+  sessionStorage.removeItem(STORAGE_KEYS.codeVerifier);
+}
+
+export function storeTokens(tokens: TokenResponse): void {
+  sessionStorage.setItem(STORAGE_KEYS.accessToken, tokens.access_token!);
+  if (tokens.refresh_token) {
+    sessionStorage.setItem(STORAGE_KEYS.refreshToken, tokens.refresh_token);
+  }
+  if (tokens.id_token) {
+    sessionStorage.setItem(STORAGE_KEYS.idToken, tokens.id_token);
+  }
+  if (typeof tokens.expires_in === "number") {
+    sessionStorage.setItem(
+      STORAGE_KEYS.expiresAt,
+      String(Date.now() + tokens.expires_in * 1000),
+    );
+  }
+}
+
+export function getToken(): string | undefined {
+  return sessionStorage.getItem(STORAGE_KEYS.accessToken) ?? undefined;
+}
+
+export function getRefreshToken(): string | undefined {
+  return sessionStorage.getItem(STORAGE_KEYS.refreshToken) ?? undefined;
+}
+
+export function getIdToken(): string | undefined {
+  return sessionStorage.getItem(STORAGE_KEYS.idToken) ?? undefined;
+}
+
+export function isAuthenticated(): boolean {
+  return Boolean(getToken());
+}
+
+/** True once the stored access token has passed its (approximate) expiry. */
+export function isExpired(): boolean {
+  const expiresAt = sessionStorage.getItem(STORAGE_KEYS.expiresAt);
+  if (!expiresAt) return false;
+  return Date.now() >= Number(expiresAt);
+}
+
+/**
+ * Refresh the access token with the refresh token grant. Returns false when
+ * no refresh token is stored or the grant fails (caller should re-login).
+ */
+export async function refreshAccessToken(
+  app: AppConfig = config,
+  fetchImpl: typeof fetch = fetch,
+): Promise<boolean> {
+  const refreshToken = getRefreshToken();
+  if (!refreshToken || !app.clientId) return false;
+
+  const resolved = await resolveEndpoints(app, fetchImpl);
+
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: app.clientId,
+  });
+
+  const response = await fetchImpl(resolved.tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+  if (!response.ok) return false;
+  const tokens = (await response.json()) as TokenResponse;
+  if (!tokens.access_token) return false;
+  storeTokens(tokens);
+  return true;
+}
+
+export function clearAuth(): void {
+  for (const key of Object.values(STORAGE_KEYS)) {
+    sessionStorage.removeItem(key);
+  }
+}
+
+/** Sign out: clear local auth, then send the browser to the end-session endpoint. */
+export async function logout(
+  app: AppConfig = config,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  const resolved = await resolveEndpoints(app, fetchImpl);
+  const idTokenHint = getIdToken();
+  clearAuth();
+  const params = new URLSearchParams();
+  if (idTokenHint) params.set("id_token_hint", idTokenHint);
+  if (app.clientId) params.set("client_id", app.clientId);
+  params.set("post_logout_redirect_uri", window.location.origin);
+  window.location.assign(`${resolved.endSessionEndpoint}?${params.toString()}`);
+}

admin/src/auth/pkce.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  base64UrlEncode,
+  computeCodeChallenge,
+  generateCodeVerifier,
+  generateState,
+  isLikelyValidVerifier,
+} from "./pkce";
+
+describe("PKCE helpers", () => {
+  it("base64UrlEncode has no padding and url-safe characters", () => {
+    // bytes chosen to force "+" and "/" and padding in plain base64
+    const bytes = new Uint8Array([0xfb, 0xff, 0xbf, 0xff]);
+    const encoded = base64UrlEncode(bytes);
+    expect(encoded).not.toMatch(/[+/=]/);
+  });
+
+  it("computes the RFC 7636 appendix-B S256 vector", async () => {
+    const verifier =
+      "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";
+    const challenge = await computeCodeChallenge(verifier);
+    expect(challenge).toBe("E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM");
+  });
+
+  it("generates verifiers with valid charset and length", () => {
+    for (let i = 0; i < 20; i++) {
+      const verifier = generateCodeVerifier();
+      expect(isLikelyValidVerifier(verifier)).toBe(true);
+    }
+  });
+
+  it("rejects verifiers outside 43-128 chars or with reserved chars", () => {
+    expect(isLikelyValidVerifier("short")).toBe(false);
+    expect(isLikelyValidVerifier("a".repeat(129))).toBe(false);
+    expect(isLikelyValidVerifier("a".repeat(43) + "+")).toBe(false);
+  });
+
+  it("generates distinct random states", () => {
+    expect(generateState()).not.toBe(generateState());
+  });
+});

admin/src/auth/pkce.ts

@@ -0,0 +1,55 @@
+/**
+ * PKCE (RFC 7636) helpers for a public SPA client.
+ *
+ * Uses the Web Crypto API, which requires a SECURE CONTEXT: the app must be
+ * served over https or http://localhost, otherwise crypto.subtle is
+ * unavailable and login cannot work.
+ */
+
+const VERIFIER_CHARSET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+
+/** base64url-encode bytes with NO padding. */
+export function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function randomBase64Url(byteLength: number): string {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes);
+}
+
+/**
+ * Random code_verifier: 43-128 chars, unreserved charset only.
+ * 32 random bytes -> 43 base64url chars, which is the minimum allowed length.
+ */
+export function generateCodeVerifier(): string {
+  return randomBase64Url(32);
+}
+
+/** S256 code_challenge = base64url(SHA-256(verifier)), no padding. */
+export async function computeCodeChallenge(verifier: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(verifier),
+  );
+  return base64UrlEncode(new Uint8Array(digest));
+}
+
+/** Random opaque state value for CSRF protection. */
+export function generateState(): string {
+  return randomBase64Url(16);
+}
+
+export function isLikelyValidVerifier(verifier: string): boolean {
+  return (
+    verifier.length >= 43 &&
+    verifier.length <= 128 &&
+    [...verifier].every((char) => VERIFIER_CHARSET.includes(char))
+  );
+}

admin/src/config.test.ts

@@ -0,0 +1,215 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  ConfigError,
+  discoveryUrlForIssuer,
+  readConfig,
+  resolveEndpoints,
+  resolveEndpointsFromDiscovery,
+  type AppConfig,
+} from "./config";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+// Mirrors Authentik's layout: authorize/token/userinfo live OUTSIDE the
+// application-specific issuer path, end-session/jwks under it.
+function discoveryDocument(issuer: string) {
+  const normalized = issuer.replace(/\/+$/, "");
+  const origin = new URL(normalized).origin;
+  return {
+    issuer,
+    authorization_endpoint: `${origin}/application/o/authorize/`,
+    token_endpoint: `${origin}/application/o/token/`,
+    userinfo_endpoint: `${origin}/application/o/userinfo/`,
+    end_session_endpoint: `${normalized}/end-session/`,
+    jwks_uri: `${normalized}/jwks/`,
+  };
+}
+
+describe("config", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("readConfig keeps the production issuer as the default", () => {
+    const cfg = readConfig({});
+    expect(cfg.issuer).toBe("https://auth.cubecraftlabs.com/application/o/nestquest");
+    expect(cfg.clientId).toBeUndefined();
+  });
+
+  it("readConfig normalizes a trailing slash off a custom issuer", () => {
+    expect(
+      readConfig({ VITE_AUTHENTIK_ISSUER: "https://sso.custom.example/application/o/custom/" })
+        .issuer,
+    ).toBe("https://sso.custom.example/application/o/custom");
+  });
+
+  it("readConfig hardcodes no OIDC endpoints — they come from discovery", () => {
+    const cfg = readConfig({});
+    expect(cfg.authorizeEndpoint).toBeUndefined();
+    expect(cfg.tokenEndpoint).toBeUndefined();
+    expect(cfg.userinfoEndpoint).toBeUndefined();
+    expect(cfg.endSessionEndpoint).toBeUndefined();
+    expect(cfg.jwksUri).toBeUndefined();
+  });
+
+  it("builds the discovery URL for issuers with and without a trailing slash", () => {
+    expect(discoveryUrlForIssuer("https://sso.example.com/application/o/app/")).toBe(
+      "https://sso.example.com/application/o/app/.well-known/openid-configuration",
+    );
+    expect(discoveryUrlForIssuer("https://sso.example.com/application/o/app")).toBe(
+      "https://sso.example.com/application/o/app/.well-known/openid-configuration",
+    );
+  });
+
+  it("resolves every endpoint from the discovery document of a non-default issuer", async () => {
+    const issuer = "https://sso.other-host.example/application/o/other-app";
+    const doc = discoveryDocument(issuer);
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(doc));
+    const app: AppConfig = {
+      issuer,
+      clientId: "client-id",
+      apiBaseUrl: "https://api.example.com",
+      redirectUri: "http://localhost:5173/auth/callback",
+    };
+
+    const resolved = await resolveEndpoints(app, fetchMock as unknown as typeof fetch);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://sso.other-host.example/application/o/other-app/.well-known/openid-configuration",
+    );
+    // Every endpoint comes verbatim from the (non-default) discovery document.
+    expect(resolved.authorizeEndpoint).toBe(doc.authorization_endpoint);
+    expect(resolved.tokenEndpoint).toBe(doc.token_endpoint);
+    expect(resolved.userinfoEndpoint).toBe(doc.userinfo_endpoint);
+    expect(resolved.endSessionEndpoint).toBe(doc.end_session_endpoint);
+    expect(resolved.jwksUri).toBe(doc.jwks_uri);
+    // Proves no hardcoded production host leaked into the resolved endpoints.
+    for (const endpoint of [
+      resolved.authorizeEndpoint,
+      resolved.tokenEndpoint,
+      resolved.userinfoEndpoint,
+      resolved.endSessionEndpoint,
+      resolved.jwksUri,
+    ]) {
+      expect(endpoint).not.toMatch(/cubecraftlabs/);
+    }
+  });
+
+  it("resolves discovery for an issuer configured with a trailing slash", async () => {
+    const issuer = "https://sso.slashy.example/application/o/slashy/";
+    const doc = discoveryDocument(issuer);
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(doc));
+
+    const resolved = await resolveEndpointsFromDiscovery(issuer, fetchMock as any);
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://sso.slashy.example/application/o/slashy/.well-known/openid-configuration",
+    );
+    expect(resolved.authorizeEndpoint).toBe(doc.authorization_endpoint);
+    expect(resolved.endSessionEndpoint).toBe(doc.end_session_endpoint);
+  });
+
+  it("caches discovery per issuer for the session", async () => {
+    const issuer = "https://sso.cached.example/application/o/cached";
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(discoveryDocument(issuer)));
+
+    const first = await resolveEndpointsFromDiscovery(issuer, fetchMock as any);
+    const second = await resolveEndpointsFromDiscovery(issuer, fetchMock as any);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(second).toBe(first);
+  });
+
+  it("surfaces a clear configuration error when discovery returns an HTTP error", async () => {
+    const issuer = "https://sso.http-error.example/application/o/broken";
+    const fetchMock = vi.fn().mockResolvedValue(new Response("", { status: 500 }));
+
+    const error = await resolveEndpointsFromDiscovery(issuer, fetchMock as any).then(
+      () => null,
+      (error: unknown) => error,
+    );
+
+    expect(error).toBeInstanceOf(ConfigError);
+    expect((error as Error).message).toContain(issuer);
+    expect((error as Error).message).toContain("HTTP 500");
+  });
+
+  it("surfaces a clear configuration error when discovery is unreachable", async () => {
+    const issuer = "https://sso.unreachable.example/application/o/unreachable";
+    const fetchMock = vi.fn().mockRejectedValue(new TypeError("network down"));
+
+    await expect(
+      resolveEndpointsFromDiscovery(issuer, fetchMock as any),
+    ).rejects.toBeInstanceOf(ConfigError);
+  });
+
+  it("surfaces a clear configuration error when the discovery document is incomplete", async () => {
+    const issuer = "https://sso.incomplete.example/application/o/incomplete";
+    const doc = discoveryDocument(issuer) as Record<string, string>;
+    delete doc.end_session_endpoint;
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(doc));
+
+    await expect(
+      resolveEndpointsFromDiscovery(issuer, fetchMock as any),
+    ).rejects.toThrow(/end_session_endpoint/);
+  });
+
+  it("rejects a discovery document advertising a different issuer", async () => {
+    const issuer = "https://sso.mismatch.example/application/o/mismatch";
+    const doc = {
+      ...discoveryDocument(issuer),
+      issuer: "https://sso.elsewhere.example/application/o/elsewhere",
+    };
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(doc));
+
+    await expect(
+      resolveEndpointsFromDiscovery(issuer, fetchMock as any),
+    ).rejects.toThrow(/issuer mismatch/i);
+  });
+
+  it("the bundled config resolves its endpoints from discovery at runtime", async () => {
+    const issuer = "https://sso.bundled.example/application/o/bundled";
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse(discoveryDocument(issuer)));
+    const bundled = readConfig({ VITE_AUTHENTIK_ISSUER: `${issuer}/`, VITE_AUTHENTIK_CLIENT_ID: "bundled-client" });
+    expect(bundled.authorizeEndpoint).toBeUndefined();
+
+    const resolved = await resolveEndpoints(bundled, fetchMock as any);
+
+    expect(resolved.authorizeEndpoint).toBe(
+      "https://sso.bundled.example/application/o/authorize/",
+    );
+    expect(resolved.tokenEndpoint).toBe("https://sso.bundled.example/application/o/token/");
+    expect(resolved.userinfoEndpoint).toBe(
+      "https://sso.bundled.example/application/o/userinfo/",
+    );
+    expect(resolved.endSessionEndpoint).toBe(
+      "https://sso.bundled.example/application/o/bundled/end-session/",
+    );
+    expect(resolved.jwksUri).toBe("https://sso.bundled.example/application/o/bundled/jwks/");
+  });
+
+  it("does not re-fetch discovery when the config already carries endpoints", async () => {
+    const app: AppConfig = {
+      issuer: "https://auth.example.com/application/o/nestquest",
+      clientId: "client-id",
+      apiBaseUrl: "https://api.example.com",
+      authorizeEndpoint: "https://auth.example.com/application/o/authorize/",
+      tokenEndpoint: "https://auth.example.com/application/o/token/",
+      userinfoEndpoint: "https://auth.example.com/application/o/userinfo/",
+      endSessionEndpoint: "https://auth.example.com/application/o/nestquest/end-session/",
+      redirectUri: "http://localhost:5173/auth/callback",
+    };
+    const fetchMock = vi.fn();
+
+    const resolved = await resolveEndpoints(app, fetchMock as any);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(resolved).toBe(app);
+  });
+});

admin/src/config.ts

@@ -0,0 +1,221 @@
+/**
+ * Runtime configuration, read from Vite env (import.meta.env).
+ * See .env.example for the variables and their defaults.
+ *
+ * OIDC endpoints are NOT hardcoded here. They are resolved lazily from the
+ * issuer's OIDC discovery document (see resolveEndpoints), because Authentik
+ * serves authorize/token/userinfo OUTSIDE the application-specific issuer
+ * path (issuer is /application/o/<slug>/, authorize is /application/o/authorize/).
+ * Both hardcoding the production host and naively concatenating onto the
+ * issuer would break non-default issuers; discovery is the only correct way.
+ */
+
+export interface AppConfig {
+  issuer: string;
+  clientId: string | undefined;
+  apiBaseUrl: string;
+  /** Resolved from the issuer's OIDC discovery document — see resolveEndpoints(). */
+  authorizeEndpoint?: string;
+  tokenEndpoint?: string;
+  userinfoEndpoint?: string;
+  endSessionEndpoint?: string;
+  jwksUri?: string;
+  redirectUri: string;
+}
+
+/** AppConfig whose OIDC endpoints have been filled in by resolveEndpoints(). */
+export type ResolvedAppConfig = AppConfig &
+  Required<
+    Pick<
+      AppConfig,
+      "authorizeEndpoint" | "tokenEndpoint" | "userinfoEndpoint" | "endSessionEndpoint"
+    >
+  >;
+
+export interface DiscoveredEndpoints {
+  issuer: string;
+  authorizeEndpoint: string;
+  tokenEndpoint: string;
+  userinfoEndpoint: string;
+  endSessionEndpoint: string;
+  jwksUri: string;
+}
+
+/** Raised when OIDC discovery fails or the configuration is unusable. */
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+const REQUIRED_ENDPOINT_NAMES = [
+  "authorizeEndpoint",
+  "tokenEndpoint",
+  "userinfoEndpoint",
+  "endSessionEndpoint",
+] as const;
+
+export function readConfig(env: Record<string, string | undefined> = import.meta.env as any): AppConfig {
+  const issuer = (
+    env.VITE_AUTHENTIK_ISSUER || "https://auth.cubecraftlabs.com/application/o/nestquest/"
+  ).replace(/\/$/, "");
+  const clientId = env.VITE_AUTHENTIK_CLIENT_ID;
+  const apiBaseUrl = env.VITE_API_BASE_URL || "https://nestquest.cubecraftlabs.com";
+
+  return {
+    issuer,
+    // No default: a missing client id must surface as a configuration error
+    // screen, not a broken redirect to Authentik.
+    clientId: clientId || undefined,
+    apiBaseUrl,
+    // authorize/token/userinfo/end-session endpoints are resolved from the
+    // issuer's discovery document at runtime — never hardcoded here.
+    redirectUri: `${window.location.origin}/auth/callback`,
+  };
+}
+
+export const config: AppConfig = readConfig();
+
+interface DiscoveryDocument {
+  issuer?: unknown;
+  authorization_endpoint?: unknown;
+  token_endpoint?: unknown;
+  userinfo_endpoint?: unknown;
+  end_session_endpoint?: unknown;
+  jwks_uri?: unknown;
+}
+
+function normalizeIssuer(issuer: string): string {
+  return issuer.replace(/\/+$/, "");
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Discovery document location for an issuer, tolerant of a trailing slash. */
+export function discoveryUrlForIssuer(issuer: string): string {
+  return `${normalizeIssuer(issuer)}/.well-known/openid-configuration`;
+}
+
+async function fetchDiscoveredEndpoints(
+  issuer: string,
+  fetchImpl: typeof fetch,
+): Promise<DiscoveredEndpoints> {
+  const normalizedIssuer = normalizeIssuer(issuer);
+  const discoveryUrl = `${normalizedIssuer}/.well-known/openid-configuration`;
+
+  let response: Response;
+  try {
+    response = await fetchImpl(discoveryUrl);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new ConfigError(
+      `OIDC discovery request to ${discoveryUrl} failed (${reason}). ` +
+        "Check VITE_AUTHENTIK_ISSUER and network reachability.",
+    );
+  }
+  if (!response.ok) {
+    throw new ConfigError(
+      `OIDC discovery failed: ${discoveryUrl} returned HTTP ${response.status}. ` +
+        "Check VITE_AUTHENTIK_ISSUER.",
+    );
+  }
+
+  let doc: DiscoveryDocument;
+  try {
+    doc = (await response.json()) as DiscoveryDocument;
+  } catch {
+    throw new ConfigError(
+      `OIDC discovery document at ${discoveryUrl} is not valid JSON. Check VITE_AUTHENTIK_ISSUER.`,
+    );
+  }
+
+  const authorizationEndpoint = nonEmptyString(doc.authorization_endpoint);
+  const tokenEndpoint = nonEmptyString(doc.token_endpoint);
+  const userinfoEndpoint = nonEmptyString(doc.userinfo_endpoint);
+  const endSessionEndpoint = nonEmptyString(doc.end_session_endpoint);
+  const jwksUri = nonEmptyString(doc.jwks_uri);
+  const discoveredIssuer = nonEmptyString(doc.issuer);
+
+  const endpointFields: Array<[string, string | undefined]> = [
+    ["authorization_endpoint", authorizationEndpoint],
+    ["token_endpoint", tokenEndpoint],
+    ["userinfo_endpoint", userinfoEndpoint],
+    ["end_session_endpoint", endSessionEndpoint],
+    ["jwks_uri", jwksUri],
+  ];
+  const missing = endpointFields.filter(([, value]) => !value).map(([name]) => name);
+  if (missing.length > 0) {
+    throw new ConfigError(
+      `OIDC discovery document at ${discoveryUrl} is missing: ${missing.join(", ")}. ` +
+        "The issuer must point at an OIDC provider that publishes these endpoints.",
+    );
+  }
+
+  if (discoveredIssuer && normalizeIssuer(discoveredIssuer) !== normalizedIssuer) {
+    throw new ConfigError(
+      `OIDC discovery issuer mismatch: ${discoveryUrl} advertises "${discoveredIssuer}" ` +
+        `but VITE_AUTHENTIK_ISSUER is "${normalizedIssuer}".`,
+    );
+  }
+
+  return {
+    issuer: normalizedIssuer,
+    authorizeEndpoint: authorizationEndpoint!,
+    tokenEndpoint: tokenEndpoint!,
+    userinfoEndpoint: userinfoEndpoint!,
+    endSessionEndpoint: endSessionEndpoint!,
+    jwksUri: jwksUri!,
+  };
+}
+
+/**
+ * Session cache: one discovery fetch per issuer per SPA session. Failed
+ * lookups are evicted so a transient network error can be retried instead of
+ * poisoning the whole session.
+ */
+const discoveryCache = new Map<string, Promise<DiscoveredEndpoints>>();
+
+export function resolveEndpointsFromDiscovery(
+  issuer: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<DiscoveredEndpoints> {
+  const normalizedIssuer = normalizeIssuer(issuer);
+  const cached = discoveryCache.get(normalizedIssuer);
+  if (cached) return cached;
+
+  const pending = fetchDiscoveredEndpoints(normalizedIssuer, fetchImpl);
+  discoveryCache.set(normalizedIssuer, pending);
+  pending.catch(() => {
+    discoveryCache.delete(normalizedIssuer);
+  });
+  return pending;
+}
+
+/**
+ * Return `app` with all OIDC endpoints filled in. When the config already
+ * carries them (pre-resolved config, tests) this is a no-op; otherwise the
+ * issuer's discovery document is fetched (cached for the session) and its
+ * authorization/token/userinfo/end-session/jwks endpoints are used.
+ */
+export async function resolveEndpoints(
+  app: AppConfig,
+  fetchImpl: typeof fetch = fetch,
+): Promise<ResolvedAppConfig> {
+  const missing = REQUIRED_ENDPOINT_NAMES.filter((name) => !app[name]);
+  if (missing.length === 0) {
+    return app as ResolvedAppConfig;
+  }
+
+  const discovered = await resolveEndpointsFromDiscovery(app.issuer, fetchImpl);
+  return {
+    ...app,
+    authorizeEndpoint: discovered.authorizeEndpoint,
+    tokenEndpoint: discovered.tokenEndpoint,
+    userinfoEndpoint: discovered.userinfoEndpoint,
+    endSessionEndpoint: discovered.endSessionEndpoint,
+    jwksUri: discovered.jwksUri,
+  };
+}

admin/src/definitions/DefinitionsTab.css

@@ -0,0 +1,596 @@
+/* Definitions ("Tasks") tab — list + edit sheet (design/ADMIN-SPEC.md §3.1–3.2).
+   Mobile-first at the 390x844 reference; the column is capped and centred wider. */
+
+.defs-screen {
+  width: 100%;
+  max-width: 640px;
+  margin: 0 auto;
+}
+
+/* §3.1 header */
+.defs-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  background: var(--nq-a-surface);
+  border-bottom: 1px solid var(--nq-a-border);
+  padding: 14px 16px;
+}
+
+.defs-title {
+  margin: 0;
+  font-size: var(--nq-a-size-screen);
+  font-weight: 800;
+  letter-spacing: -0.02em;
+}
+
+.defs-sub {
+  margin: 2px 0 0;
+  min-height: 1.4em;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.defs-new {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  min-height: 36px;
+  padding: 0 14px;
+  border: 0;
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-brand-gradient);
+  color: #fff;
+  font-family: inherit;
+  font-size: 13px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.defs-new:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+/* Scroll column: 14px 16px, bottom 92px (set inline, ADMIN-SPEC §1). */
+.defs-scroll {
+  display: flex;
+  flex-direction: column;
+  gap: var(--nq-a-density-gap);
+  padding: 14px 16px;
+}
+
+/* Filter chips */
+.defs-chips {
+  display: flex;
+  gap: 6px;
+  overflow-x: auto;
+}
+
+.defs-chip {
+  flex: none;
+  min-height: 32px;
+  padding: 0 12px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-radius-pill);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 12px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.defs-chip--active {
+  border-color: #18181d;
+  background: #18181d;
+  color: #fff;
+}
+
+/* Rows */
+.defs-card {
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  overflow: hidden;
+}
+
+.defs-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.defs-list > li + li {
+  border-top: 1px solid var(--nq-a-divider);
+}
+
+.defs-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  min-height: var(--nq-a-tap-min);
+  padding: var(--nq-a-density-row-pad);
+  border: 0;
+  background: none;
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.defs-row-glyph {
+  flex: none;
+  display: flex;
+  color: var(--nq-a-ink-secondary);
+}
+
+.defs-row-text {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.defs-row-title {
+  font-size: var(--nq-a-size-row);
+  font-weight: 700;
+}
+
+.defs-row-meta {
+  font-size: var(--nq-a-size-meta);
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.defs-row-chevron {
+  flex: none;
+  display: flex;
+  color: var(--nq-a-ink-tertiary);
+}
+
+/* An inactive definition renders the whole row tertiary (never hard-deleted). */
+.defs-row--inactive,
+.defs-row--inactive .defs-row-glyph,
+.defs-row--inactive .defs-row-meta {
+  color: var(--nq-a-ink-tertiary);
+}
+
+.defs-row--editing {
+  background: var(--nq-a-selected);
+}
+
+.defs-row--editing .defs-row-glyph {
+  color: var(--nq-brand-blue);
+}
+
+.defs-empty {
+  padding: var(--nq-a-density-card-pad);
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+/* Loading / error */
+.defs-status {
+  padding: 24px 13px;
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  text-align: center;
+  font-size: 13.5px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.defs-status--error {
+  color: var(--nq-a-danger-strong);
+}
+
+.defs-status--error p {
+  margin: 0 0 10px;
+}
+
+.defs-retry {
+  padding: 8px 16px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 13px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+/* §3.2 edit sheet */
+.defs-sheet-layer {
+  position: fixed;
+  inset: 0;
+  z-index: 20;
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-end;
+}
+
+.defs-scrim {
+  position: absolute;
+  inset: 0;
+  background: rgba(9, 9, 11, 0.4);
+  animation: defs-fade var(--nq-dur-modal) var(--nq-ease-out);
+}
+
+.defs-sheet {
+  position: relative;
+  width: 100%;
+  max-width: 640px;
+  max-height: 92%;
+  margin: 0 auto;
+  overflow-y: auto;
+  padding: 14px 18px 24px;
+  border-radius: var(--nq-a-radius-sheet);
+  background: var(--nq-a-surface);
+  box-shadow: var(--nq-a-sheet-shadow);
+  animation: defs-rise var(--nq-dur-modal) var(--nq-ease-out);
+}
+
+@keyframes defs-fade {
+  from {
+    opacity: 0;
+  }
+}
+
+@keyframes defs-rise {
+  from {
+    transform: translateY(100%);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .defs-scrim,
+  .defs-sheet {
+    animation: none;
+  }
+}
+
+.defs-grabber {
+  width: 38px;
+  height: 4px;
+  margin: 0 auto 12px;
+  border-radius: var(--nq-a-radius-pill);
+  background: var(--nq-a-border);
+}
+
+.defs-sheet-title {
+  margin: 0 0 12px;
+  font-size: 19px;
+  font-weight: 800;
+}
+
+.defs-fields {
+  display: flex;
+  flex-direction: column;
+  gap: 11px;
+}
+
+.defs-field {
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+}
+
+.defs-label {
+  font-size: var(--nq-a-size-label);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: var(--nq-a-track-label);
+  color: var(--nq-a-ink-secondary);
+}
+
+.defs-input {
+  width: 100%;
+  min-height: var(--nq-a-tap-min);
+  padding: 0 11px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 14px;
+  font-weight: 600;
+}
+
+.defs-select-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  min-height: var(--nq-a-tap-min);
+  padding: 0 11px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 14px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.defs-picker {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+}
+
+.defs-picker > li + li {
+  border-top: 1px solid var(--nq-a-divider);
+}
+
+.defs-picker-option {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  min-height: var(--nq-a-tap-min);
+  padding: 0 11px;
+  border: 0;
+  background: none;
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 13.5px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.defs-picker-check {
+  display: flex;
+  color: var(--nq-brand-blue);
+}
+
+.defs-picker-option--locked {
+  color: var(--nq-a-ink-secondary);
+  cursor: default;
+}
+
+.defs-picker-note {
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.defs-repeats {
+  display: flex;
+  gap: 8px;
+}
+
+.defs-interval {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--nq-a-ink-secondary);
+}
+
+.defs-interval .defs-input {
+  width: 64px;
+}
+
+.defs-weekdays {
+  display: grid;
+  grid-template-columns: repeat(7, 1fr);
+  gap: 4px;
+}
+
+.defs-day,
+.defs-segment {
+  min-height: var(--nq-a-tap-min);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 13px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.defs-day--on,
+.defs-segment--on {
+  border-color: transparent;
+  background: var(--nq-brand-gradient);
+  color: #fff;
+}
+
+.defs-segmented {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 6px;
+}
+
+.defs-icon-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(var(--nq-a-tap-min), 1fr));
+  gap: 6px;
+}
+
+.defs-icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: var(--nq-a-tap-min);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  cursor: pointer;
+}
+
+.defs-icon--on {
+  border-color: transparent;
+  background: var(--nq-brand-gradient);
+  color: #fff;
+}
+
+.defs-due-times {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.defs-due {
+  display: grid;
+  grid-template-columns: 84px 1fr;
+  align-items: center;
+  gap: 8px;
+  font-size: 12.5px;
+  font-weight: 700;
+}
+
+.defs-hint {
+  margin: 0;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.defs-toggle-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.defs-toggle-title {
+  font-size: 13.5px;
+  font-weight: 700;
+}
+
+.defs-toggle-sub {
+  font-size: var(--nq-a-size-meta);
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.defs-switch {
+  flex: none;
+  position: relative;
+  width: 44px;
+  height: 26px;
+  padding: 0;
+  border: 0;
+  border-radius: var(--nq-a-radius-pill);
+  background: var(--nq-a-border);
+  cursor: pointer;
+  transition: background var(--nq-dur-base) var(--nq-ease-out);
+}
+
+.defs-switch--on {
+  background: var(--nq-brand-gradient);
+}
+
+.defs-switch-knob {
+  position: absolute;
+  top: 3px;
+  left: 3px;
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  background: #fff;
+  box-shadow: 0 1px 2px rgba(9, 9, 11, 0.25);
+  transition: transform var(--nq-dur-base) var(--nq-ease-out);
+}
+
+.defs-switch--on .defs-switch-knob {
+  transform: translateX(18px);
+}
+
+.defs-sheet-error {
+  margin: 12px 0 0;
+  padding: 10px 12px;
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-danger-bg);
+  color: var(--nq-a-danger-strong);
+  font-size: 12.5px;
+  font-weight: 700;
+}
+
+.defs-sheet-footer {
+  display: flex;
+  gap: 8px;
+  margin-top: 16px;
+}
+
+.defs-confirm {
+  margin-top: 12px;
+  padding: 10px 12px;
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-danger-bg);
+  color: var(--nq-a-danger-strong);
+  font-size: 12.5px;
+  font-weight: 700;
+}
+
+.defs-confirm p {
+  margin: 0;
+}
+
+.defs-confirm .defs-sheet-footer {
+  margin-top: 10px;
+}
+
+.defs-cancel,
+.defs-save {
+  padding: 13px 0;
+  border-radius: var(--nq-a-density-radius);
+  font-family: inherit;
+  font-size: 14px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.defs-cancel {
+  flex: 1;
+  border: 1px solid var(--nq-a-border);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+}
+
+.defs-save {
+  flex: 2;
+  border: 0;
+  background: var(--nq-brand-gradient);
+  color: #fff;
+}
+
+.defs-cancel:disabled,
+.defs-save:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+
+.defs-preview {
+  margin-top: 8px;
+}
+
+.defs-preview--error {
+  color: var(--nq-a-ink-secondary);
+  font-style: italic;
+}
+
+.defs-sublabel {
+  margin-top: 4px;
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--nq-a-ink-secondary);
+}
+
+.defs-emoji {
+  line-height: 1;
+}

admin/src/definitions/definitionIcons.tsx

@@ -0,0 +1,90 @@
+/**
+ * The icons a definition's `icon` may name (ADMIN-SPEC §3.3): the curated
+ * Lucide set, the curated Font Awesome Free solid subset, or an emoji. The
+ * names, labels and path data come from the shared icon registry
+ * (`src/icons/registry.generated.ts`, generated from
+ * `tools/icons/curated-icons.json`) — no CDN, no runtime fetch. The stored
+ * value is namespaced — `lucide:<name>`, `fa:<name>` or `emoji:<grapheme>` —
+ * and a legacy bare `<kebab-name>` still names the same Lucide entry.
+ */
+import { GlyphSvg } from "../icons/GlyphSvg";
+import { FA_ICONS, LUCIDE_ICONS, resolveIcon, type GlyphIcon } from "../icons/registry.generated";
+import { TaskGlyph } from "./glyphs";
+
+export type DefinitionIconEntry = GlyphIcon;
+
+export const DEFINITION_ICONS: readonly DefinitionIconEntry[] = LUCIDE_ICONS;
+
+export const FA_DEFINITION_ICONS: readonly DefinitionIconEntry[] = FA_ICONS;
+
+const LUCIDE_PREFIX = "lucide:";
+const FA_PREFIX = "fa:";
+const EMOJI_PREFIX = "emoji:";
+
+/** The canonical stored key for a Lucide choice, e.g. `lucide:dog`. */
+export function lucideIconKey(name: string): string {
+  return `${LUCIDE_PREFIX}${name}`;
+}
+
+/** The canonical stored key for a Font Awesome choice, e.g. `fa:dog`. */
+export function faIconKey(name: string): string {
+  return `${FA_PREFIX}${name}`;
+}
+
+/**
+ * The stored key for typed emoji text, e.g. `emoji:🐶`. The raw text — not
+ * trimmed, as the backend rejects any whitespace — must pass the registry's
+ * emoji check (1-8 code points, no whitespace, control characters or `<`,
+ * `>`, `&`), else null. Only an empty field means "no icon".
+ */
+export function emojiIconKey(text: string): string | null {
+  const key = `${EMOJI_PREFIX}${text}`;
+  return resolveIcon(key).kind === "emoji" ? key : null;
+}
+
+/**
+ * The Lucide name an icon value refers to: `lucide:dog` and a legacy bare
+ * `dog` both give `dog`. Any other namespace (`fa:`, `emoji:`, unknown) and
+ * null give null — the admin has no Lucide entry for them.
+ */
+export function normalizeDefinitionIconName(value: string | null): string | null {
+  if (value === null) return null;
+  if (value.startsWith(LUCIDE_PREFIX)) return value.slice(LUCIDE_PREFIX.length);
+  return value.includes(":") ? null : value;
+}
+
+/** The Font Awesome name an `fa:<name>` value refers to; anything else gives null. */
+export function faIconName(value: string | null): string | null {
+  return value?.startsWith(FA_PREFIX) ? value.slice(FA_PREFIX.length) : null;
+}
+
+/** The emoji text an `emoji:<grapheme>` value holds; anything else gives "". */
+export function emojiIconText(value: string | null): string {
+  return value?.startsWith(EMOJI_PREFIX) ? value.slice(EMOJI_PREFIX.length) : "";
+}
+
+/**
+ * The curated glyph (Lucide or Font Awesome) an icon value resolves to via
+ * the shared parser; emoji, unknown and null values give null.
+ */
+export function findDefinitionIcon(value: string | null): DefinitionIconEntry | null {
+  const icon = resolveIcon(value);
+  return icon.kind === "lucide" || icon.kind === "fa" ? icon : null;
+}
+
+/**
+ * A definition's icon: a Lucide or Font Awesome glyph, an emoji drawn as
+ * text, or — for no icon or an unknown value — the generic task glyph.
+ */
+export function DefinitionIcon({ name, size = 17 }: { name: string | null; size?: number }) {
+  const icon = resolveIcon(name);
+  if (icon.kind === "fallback") return <TaskGlyph size={size} />;
+  if (icon.kind === "emoji") {
+    return (
+      <span className="defs-emoji" style={{ fontSize: size }} aria-hidden="true" data-emoji={icon.text}>
+        {icon.text}
+      </span>
+    );
+  }
+  return <GlyphSvg icon={icon} size={size} />;
+}

admin/src/definitions/format.ts

@@ -0,0 +1,114 @@
+/**
+ * List-row summaries for the Definitions tab (ADMIN-SPEC §3.1):
+ * `<assignees> · <recurrence> · <windows>`.
+ */
+import type {
+  AdminChild,
+  DefinitionAssignee,
+  DefinitionRule,
+  DefinitionWindow,
+  WindowName,
+} from "../api/definitions";
+
+export const WINDOW_ORDER: WindowName[] = ["morning", "afternoon", "evening"];
+
+export const WINDOW_LABELS: Record<WindowName, string> = {
+  morning: "Morning",
+  afternoon: "Afternoon",
+  evening: "Evening",
+};
+
+/** Index 0 = Monday .. 6 = Sunday, the core's weekday numbering. */
+export const WEEKDAY_SHORT = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+
+/** Display order for a week: Sunday first. The stored indices stay Monday=0. */
+export const WEEKDAY_DISPLAY_ORDER = [6, 0, 1, 2, 3, 4, 5];
+
+export const MONTH_SHORT = [
+  "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+
+const COUNT_WORDS = ["zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten"];
+
+/**
+ * `Declan`, `Declan, Maeve`, or `All three` when every active child (two or
+ * more) is assigned.
+ */
+export function assigneeSummary(
+  assignees: Pick<DefinitionAssignee, "id" | "display_name">[],
+  activeChildren: AdminChild[],
+): string {
+  if (assignees.length === 0) return "Unassigned";
+  const assigned = new Set(assignees.map((a) => a.id));
+  const everyone =
+    activeChildren.length > 1 &&
+    assigned.size === activeChildren.length &&
+    activeChildren.every((child) => assigned.has(child.id));
+  if (everyone) {
+    const word = COUNT_WORDS[activeChildren.length] ?? String(activeChildren.length);
+    return `All ${word}`;
+  }
+  return assignees.map((a) => a.display_name).join(", ");
+}
+
+function weekdayList(days: number[] | null): string {
+  return [...(days ?? [])]
+    .sort((a, b) => WEEKDAY_DISPLAY_ORDER.indexOf(a) - WEEKDAY_DISPLAY_ORDER.indexOf(b))
+    .map((day) => WEEKDAY_SHORT[day])
+    .join(", ");
+}
+
+function ordinal(n: number): string {
+  if (n === -1) return "last";
+  const suffix = n === 1 ? "st" : n === 2 ? "nd" : n === 3 ? "rd" : "th";
+  return `${n}${suffix}`;
+}
+
+function every(interval: number, one: string, unit: string): string {
+  return interval === 1 ? one : `Every ${interval} ${unit}`;
+}
+
+export function recurrenceSummary(rule: DefinitionRule): string {
+  const n = rule.interval;
+  switch (rule.rule_type) {
+    case "daily":
+      return every(n, "Daily", "days");
+    case "weekly":
+      return `${every(n, "Weekly", "weeks")} on ${weekdayList(rule.weekday_set)}`;
+    case "monthly_day":
+      return `${every(n, "Monthly", "months")} on day ${rule.day_of_month}`;
+    case "monthly_weekday":
+      return `${every(n, "Monthly", "months")} on the ${ordinal(rule.nth_weekday ?? 1)} ${
+        WEEKDAY_SHORT[rule.nth_weekday_weekday ?? 0]
+      }`;
+    case "yearly": {
+      const month = MONTH_SHORT[(rule.month ?? 1) - 1];
+      const when = rule.day_of_month ? `on ${month} ${rule.day_of_month}` : `in ${month}`;
+      return `${every(n, "Yearly", "years")} ${when}`;
+    }
+    case "custom_days":
+      return `Custom${n === 1 ? "" : ` every ${n} weeks`} (${weekdayList(rule.weekday_set)})`;
+  }
+}
+
+export function windowSummary(windows: Pick<DefinitionWindow, "window">[]): string {
+  const names = new Set(windows.map((w) => w.window));
+  return WINDOW_ORDER.filter((w) => names.has(w))
+    .map((w) => WINDOW_LABELS[w])
+    .join(", ");
+}
+
+/**
+ * "2026-10-06" -> "Tue 6 Oct". The calendar date is read by its components
+ * and its weekday taken in UTC (as the Today tab does), so the printed day
+ * never shifts with the viewer's offset — `new Date("YYYY-MM-DD")` would.
+ */
+export function occurrenceLabel(iso: string): string {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+  if (!match) throw new Error(`Invalid calendar date: ${iso}`);
+  const [, year, month, day] = match.map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  // getUTCDay: 0 = Sunday; WEEKDAY_SHORT: 0 = Monday.
+  return `${WEEKDAY_SHORT[(date.getUTCDay() + 6) % 7]} ${day} ${MONTH_SHORT[month - 1]}`;
+}

admin/src/definitions/glyphs.tsx

@@ -0,0 +1,67 @@
+/**
+ * Inline stroke glyphs for the Definitions tab (Lucide-style 24px grid),
+ * CDN-free like the Today tab's. Definition icons arrive with the icon
+ * picker task; until then every row carries the generic task glyph.
+ */
+import type { ReactNode } from "react";
+
+function Glyph({ size, children }: { size: number; children: ReactNode }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    >
+      {children}
+    </svg>
+  );
+}
+
+export function TaskGlyph({ size = 17 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <rect x="8" y="2" width="8" height="4" rx="1" />
+      <path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2" />
+      <path d="m9 14 2 2 4-4" />
+    </Glyph>
+  );
+}
+
+export function PlusGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="M12 5v14M5 12h14" />
+    </Glyph>
+  );
+}
+
+export function ChevronRightGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="m9 18 6-6-6-6" />
+    </Glyph>
+  );
+}
+
+export function ChevronDownGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="m6 9 6 6 6-6" />
+    </Glyph>
+  );
+}
+
+export function CheckGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="M20 6 9 17l-5-5" />
+    </Glyph>
+  );
+}

admin/src/history/HistoryTab.css

@@ -0,0 +1,296 @@
+/* History tab — compact density (design/ADMIN-SPEC.md §5). Mobile-first at
+   the 390x844 reference; on wider viewports the column is capped and centred. */
+
+.history-screen {
+  width: 100%;
+  max-width: 640px;
+  margin: 0 auto;
+}
+
+.history-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  background: var(--nq-a-surface);
+  border-bottom: 1px solid var(--nq-a-border);
+  padding: 14px 16px;
+}
+
+.history-title {
+  margin: 0;
+  font-size: var(--nq-a-size-screen);
+  font-weight: 800;
+  letter-spacing: -0.02em;
+}
+
+.history-sub {
+  margin: 2px 0 0;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.history-csv {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  min-height: 36px;
+  padding: 0 12px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 12.5px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.history-csv:disabled {
+  cursor: progress;
+  opacity: 0.6;
+}
+
+/* Non-blocking CSV export failure; the tab stays usable. */
+.history-export-error {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  padding: var(--nq-a-density-row-pad);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-danger-bg);
+  color: var(--nq-a-danger-strong);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.history-export-dismiss {
+  flex: none;
+  padding: 4px 8px;
+  border: none;
+  background: none;
+  color: inherit;
+  font-family: inherit;
+  font-size: 12.5px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+/* Scroll column: 14px 16px, bottom 92px (set inline, ADMIN-SPEC §1). */
+.history-scroll {
+  display: flex;
+  flex-direction: column;
+  gap: var(--nq-a-density-gap);
+  padding: 14px 16px;
+}
+
+.history-card {
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+}
+
+/* Stat row */
+.history-stats {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 8px;
+}
+
+.history-stat {
+  padding: 12px;
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+}
+
+.history-stat-value {
+  font-size: 20px;
+  font-weight: 800;
+  line-height: 1.1;
+}
+
+.history-stat-value--on-time {
+  color: var(--nq-brand-blue);
+}
+
+.history-stat-value--missed {
+  color: var(--nq-a-danger);
+}
+
+.history-stat-label {
+  margin-top: 2px;
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--nq-a-ink-secondary);
+}
+
+/* Filter chips */
+.history-chips {
+  display: flex;
+  gap: 6px;
+  overflow-x: auto;
+}
+
+.history-chip {
+  flex: none;
+  min-height: 32px;
+  padding: 0 12px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-radius-pill);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 12px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.history-chip--active {
+  border-color: #18181d;
+  background: #18181d;
+  color: #fff;
+}
+
+/* Day-grouped event rows */
+.history-day {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.history-section-label {
+  margin: 4px 0 0;
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--nq-a-ink-secondary);
+}
+
+.history-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.history-list > li + li {
+  border-top: 1px solid var(--nq-a-divider);
+}
+
+.history-event {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: var(--nq-a-tap-min);
+  padding: var(--nq-a-density-row-pad);
+}
+
+.history-dot {
+  flex: none;
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+}
+
+.history-dot--completed {
+  background: var(--nq-a-success);
+}
+
+.history-dot--uncompleted {
+  background: var(--nq-a-reversal);
+}
+
+.history-dot--missed {
+  background: var(--nq-a-danger);
+}
+
+.history-event-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.history-event-title {
+  font-size: 12.5px;
+  font-weight: 700;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.history-event-meta {
+  margin-top: 1px;
+  font-size: 10.5px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.history-event-time {
+  flex: none;
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.history-empty {
+  padding: var(--nq-a-density-card-pad);
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+/* Append-only footer strip */
+.history-note {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 10px 12px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-page);
+  color: var(--nq-a-ink-secondary);
+  font-size: 11.5px;
+  font-weight: 600;
+}
+
+.history-note-glyph {
+  flex: none;
+  display: flex;
+}
+
+/* Loading / error */
+.history-status {
+  padding: 24px 13px;
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  text-align: center;
+  font-size: 13.5px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.history-status--error {
+  color: var(--nq-a-danger-strong);
+}
+
+.history-status--error p {
+  margin: 0 0 10px;
+}
+
+.history-retry {
+  padding: 8px 16px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 13px;
+  font-weight: 700;
+  cursor: pointer;
+}

admin/src/history/HistoryTab.test.tsx

@@ -0,0 +1,631 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import HistoryTab, { FOOTER_NOTE, computeStats } from "./HistoryTab";
+import type { HistoryFilter, HistoryRow } from "../api/history";
+import { storeTokens } from "../auth/oidc";
+import { TransitionsProvider } from "../api/useTransitions";
+import { frame, testStream, type TestStream } from "../api/testStream";
+
+const TODAY = "2026-09-23";
+
+function row(overrides: Partial<HistoryRow>): HistoryRow {
+  return {
+    occurred_at: null,
+    event_type: "completed",
+    child_name: "Declan",
+    child_id: 1,
+    quest_title: "Brush teeth",
+    instance_id: 1,
+    window: "morning",
+    due_date: TODAY,
+    due_time: null,
+    actor: "panel (Declan)",
+    was_on_time: true,
+    ...overrides,
+  };
+}
+
+// America/Los_Angeles is UTC-7 in September.
+const BRUSH = row({
+  instance_id: 1,
+  occurred_at: "2026-09-23T14:04:00Z", // 7:04 AM
+  due_time: "07:30",
+});
+const BED_DONE = row({
+  instance_id: 2,
+  quest_title: "Make bed",
+  child_name: "Maeve",
+  child_id: 2,
+  occurred_at: "2026-09-23T14:50:00Z", // 7:50 AM
+  actor: "panel (Maeve)",
+});
+const BED_UNDONE = row({
+  instance_id: 2,
+  event_type: "uncompleted",
+  quest_title: "Make bed",
+  child_name: "Maeve",
+  child_id: 2,
+  occurred_at: "2026-09-23T15:10:00Z", // 8:10 AM
+  actor: "joshua (admin)",
+  was_on_time: null,
+});
+const CAT_LATE = row({
+  instance_id: 3,
+  quest_title: "Feed cat",
+  due_date: "2026-09-22",
+  due_time: "07:00",
+  occurred_at: "2026-09-22T14:22:00Z", // 7:22 AM, 22 min after due
+  was_on_time: false,
+});
+// 7:30 PM local on Sep 22 — already Sep 23 in UTC.
+const HOMEWORK_LATE = row({
+  instance_id: 4,
+  quest_title: "Homework",
+  child_name: "Rory",
+  child_id: 3,
+  due_date: "2026-09-22",
+  due_time: null,
+  occurred_at: "2026-09-23T02:30:00Z",
+  actor: "panel (Rory)",
+  was_on_time: false,
+});
+const PLANTS_MISSED = row({
+  instance_id: 5,
+  event_type: "missed",
+  quest_title: "Water plants",
+  child_name: "Rory",
+  child_id: 3,
+  due_date: "2026-09-21",
+  due_time: "18:00",
+  actor: "nightly sweep",
+  was_on_time: null,
+});
+
+// The API's order: due_date, then instance, then event id.
+const ROWS: Record<HistoryFilter, HistoryRow[]> = {
+  all: [CAT_LATE, HOMEWORK_LATE, BRUSH, BED_DONE, BED_UNDONE],
+  reversals: [BED_UNDONE],
+  missed: [PLANTS_MISSED],
+};
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+const CSV_BODY = "occurred_at,event_type\n2026-09-23T14:04:00Z,completed\n";
+
+function csvResponse(filter: string, start: string, end: string): Response {
+  return new Response(`${filter}\n${CSV_BODY}`, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/csv; charset=utf-8",
+      "Content-Disposition": `attachment; filename="nestquest-history-${start}-to-${end}.csv"`,
+    },
+  });
+}
+
+function routeFetch(url: string): Response {
+  const parsed = new URL(url, "http://x");
+  if (parsed.pathname.endsWith("/api/v1/admin/history.csv")) {
+    return csvResponse(
+      parsed.searchParams.get("filter") ?? "",
+      parsed.searchParams.get("start") ?? "",
+      parsed.searchParams.get("end") ?? "",
+    );
+  }
+  if (!parsed.pathname.endsWith("/api/v1/admin/history")) {
+    return jsonResponse({ detail: "unexpected" }, 500);
+  }
+  const filter = parsed.searchParams.get("filter") as HistoryFilter;
+  const rows = ROWS[filter];
+  return jsonResponse({
+    filter,
+    start: parsed.searchParams.get("start"),
+    end: parsed.searchParams.get("end"),
+    count: rows.length,
+    rows,
+  });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function historyCalls(): URL[] {
+  return fetchMock.mock.calls.map(([url]) => new URL(String(url), "http://x"));
+}
+
+function metas(section: HTMLElement): string[] {
+  return within(section)
+    .getAllByTestId("history-meta")
+    .map((el) => el.textContent ?? "");
+}
+
+async function renderReady() {
+  render(<HistoryTab today={TODAY} />);
+  await screen.findByTestId("stat-on-time");
+}
+
+describe("HistoryTab", () => {
+  beforeAll(() => {
+    vi.stubEnv("TZ", "America/Los_Angeles");
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+  });
+
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    fetchMock = vi.fn((url: string) => Promise.resolve(routeFetch(url)));
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("renders the header and queries the last 14 days with the Bearer token", async () => {
+    await renderReady();
+    expect(screen.getByRole("heading", { name: "History" })).toBeTruthy();
+    expect(screen.getByText("Append-only event log · last 14 days")).toBeTruthy();
+
+    const calls = historyCalls();
+    expect(calls.length).toBeGreaterThan(0);
+    for (const url of calls) {
+      expect(url.pathname).toBe("/api/v1/admin/history");
+      expect(url.searchParams.get("start")).toBe("2026-09-10");
+      expect(url.searchParams.get("end")).toBe(TODAY);
+    }
+    expect(calls.map((url) => url.searchParams.get("filter")).sort()).toEqual(["all", "missed"]);
+    expect(fetchMock.mock.calls[0][1].headers.Authorization).toBe("Bearer at-123");
+  });
+
+  it("stat row shows On time %, Completed and Missed for the period", async () => {
+    await renderReady();
+    // 4 completions (2 on time) in `all`; 1 derived missed row.
+    expect(screen.getByTestId("stat-on-time").textContent).toBe("50%On time");
+    expect(screen.getByTestId("stat-completed").textContent).toBe("4Completed");
+    expect(screen.getByTestId("stat-missed").textContent).toBe("1Missed");
+  });
+
+  it("On time shows — when the period has no completions", () => {
+    expect(computeStats([BED_UNDONE], [])).toEqual({ onTimePct: null, completed: 0, missed: 0 });
+  });
+
+  it("groups rows by local day, newest first, with event type, actor and on-time meta", async () => {
+    await renderReady();
+
+    const today = screen.getByTestId(`day-${TODAY}`);
+    expect(within(today).getByRole("heading").textContent).toBe("Today");
+    expect(metas(today)).toEqual([
+      "uncompleted · joshua (admin)",
+      "completed · panel (Maeve) · on time",
+      "completed · panel (Declan) · on time",
+    ]);
+    expect(within(today).getAllByText("Make bed · Maeve")).toHaveLength(2);
+    expect(within(today).getByText("8:10 AM")).toBeTruthy();
+
+    // The 7:30 PM completion is Sep 23 in UTC but Sep 22 locally.
+    const yesterday = screen.getByTestId("day-2026-09-22");
+    expect(within(yesterday).getByRole("heading").textContent).toBe("Yesterday");
+    expect(metas(yesterday)).toEqual([
+      "completed · panel (Rory) · late",
+      "completed · panel (Declan) · late 22 min",
+    ]);
+    expect(within(yesterday).getByText("7:30 PM")).toBeTruthy();
+
+    const dots = screen.getAllByTestId("history-dot").map((el) => el.className);
+    expect(dots[0]).toContain("history-dot--uncompleted");
+    expect(dots[1]).toContain("history-dot--completed");
+  });
+
+  it("each filter chip re-queries the API with its filter and re-renders", async () => {
+    await renderReady();
+
+    fireEvent.click(screen.getByRole("button", { name: "Reversals" }));
+    await waitFor(() =>
+      expect(historyCalls().some((url) => url.searchParams.get("filter") === "reversals")).toBe(true),
+    );
+    await waitFor(() => expect(screen.getAllByTestId("history-row")).toHaveLength(1));
+    expect(screen.getByTestId("history-meta").textContent).toBe("uncompleted · joshua (admin)");
+    expect(screen.getByRole("button", { name: "Reversals" }).getAttribute("aria-pressed")).toBe("true");
+
+    fireEvent.click(screen.getByRole("button", { name: "Missed" }));
+    const missedDay = await screen.findByTestId("day-2026-09-21");
+    expect(within(missedDay).getByRole("heading").textContent).toBe("Mon, Sep 21");
+    expect(metas(missedDay)).toEqual(["missed · nightly sweep"]);
+    expect(within(missedDay).getByTestId("history-dot").className).toContain("history-dot--missed");
+    expect(within(missedDay).getByText("6:00 PM")).toBeTruthy();
+    // Stats stay the period's numbers whichever chip is selected.
+    expect(screen.getByTestId("stat-completed").textContent).toBe("4Completed");
+
+    fetchMock.mockClear();
+    fireEvent.click(screen.getByRole("button", { name: "All events" }));
+    await screen.findByTestId(`day-${TODAY}`);
+    expect(historyCalls().map((url) => url.searchParams.get("filter"))).toContain("all");
+    expect(screen.getAllByTestId("history-row")).toHaveLength(5);
+  });
+
+  it("shows the append-only footer", async () => {
+    await renderReady();
+    expect(FOOTER_NOTE).toBe("Events are never edited or deleted. A reversal is its own row.");
+    expect(screen.getByTestId("history-footer").textContent).toBe(FOOTER_NOTE);
+  });
+
+  describe("CSV export", () => {
+    let createObjectURL: ReturnType<typeof vi.fn>;
+    let revokeObjectURL: ReturnType<typeof vi.fn>;
+    let clicked: { href: string; download: string; attached: boolean }[];
+
+    beforeEach(() => {
+      createObjectURL = vi.fn(() => "blob:nestquest/csv-1");
+      revokeObjectURL = vi.fn();
+      // jsdom has no object URLs; install stubs and remove them afterwards.
+      Object.assign(URL, { createObjectURL, revokeObjectURL });
+      clicked = [];
+      vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(function (this: HTMLAnchorElement) {
+        clicked.push({
+          href: this.getAttribute("href") ?? "",
+          download: this.download,
+          attached: document.body.contains(this),
+        });
+      });
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+      const stubbed = URL as unknown as Record<string, unknown>;
+      delete stubbed.createObjectURL;
+      delete stubbed.revokeObjectURL;
+    });
+
+    function csvCalls(): [URL, RequestInit][] {
+      return fetchMock.mock.calls
+        .map(([url, init]) => [new URL(String(url), "http://x"), init] as [URL, RequestInit])
+        .filter(([url]) => url.pathname === "/api/v1/admin/history.csv");
+    }
+
+    it("requests the CSV for the active filter and displayed range with the Bearer token", async () => {
+      await renderReady();
+      fireEvent.click(screen.getByRole("button", { name: "CSV" }));
+      await waitFor(() => expect(clicked).toHaveLength(1));
+
+      const calls = csvCalls();
+      expect(calls).toHaveLength(1);
+      const [url, init] = calls[0];
+      expect(url.searchParams.get("filter")).toBe("all");
+      expect(url.searchParams.get("start")).toBe("2026-09-10");
+      expect(url.searchParams.get("end")).toBe(TODAY);
+      expect((init.headers as Record<string, string>).Authorization).toBe("Bearer at-123");
+      // The token never travels in the URL.
+      expect(url.toString()).not.toContain("at-123");
+    });
+
+    it("offers the returned CSV for download, then revokes the URL and removes the anchor", async () => {
+      await renderReady();
+      fireEvent.click(screen.getByRole("button", { name: "CSV" }));
+      await waitFor(() => expect(clicked).toHaveLength(1));
+
+      expect(createObjectURL).toHaveBeenCalledTimes(1);
+      const blob = createObjectURL.mock.calls[0][0] as Blob;
+      expect(await blob.text()).toBe(`all\n${CSV_BODY}`);
+      expect(clicked[0]).toEqual({
+        href: "blob:nestquest/csv-1",
+        download: "nestquest-history-2026-09-10-to-2026-09-23.csv",
+        attached: true,
+      });
+      expect(revokeObjectURL).toHaveBeenCalledWith("blob:nestquest/csv-1");
+      expect(document.querySelector("a[download]")).toBeNull();
+      expect(screen.queryByTestId("history-export-error")).toBeNull();
+    });
+
+    it("falls back to the range filename without a Content-Disposition header", async () => {
+      fetchMock.mockImplementation((url: string) =>
+        Promise.resolve(
+          new URL(url, "http://x").pathname.endsWith(".csv")
+            ? new Response(CSV_BODY, { status: 200, headers: { "Content-Type": "text/csv" } })
+            : routeFetch(url),
+        ),
+      );
+      await renderReady();
+      fireEvent.click(screen.getByRole("button", { name: "CSV" }));
+      await waitFor(() => expect(clicked).toHaveLength(1));
+      expect(clicked[0].download).toBe("nestquest-history-2026-09-10-to-2026-09-23.csv");
+    });
+
+    it("switching the filter chip then exporting uses the new filter", async () => {
+      await renderReady();
+      fireEvent.click(screen.getByRole("button", { name: "Reversals" }));
+      await waitFor(() => expect(screen.getAllByTestId("history-row")).toHaveLength(1));
+
+      fireEvent.click(screen.getByRole("button", { name: "CSV" }));
+      await waitFor(() => expect(clicked).toHaveLength(1));
+      const calls = csvCalls();
+      expect(calls).toHaveLength(1);
+      expect(calls[0][0].searchParams.get("filter")).toBe("reversals");
+      expect(calls[0][0].searchParams.get("start")).toBe("2026-09-10");
+      expect(calls[0][0].searchParams.get("end")).toBe(TODAY);
+    });
+
+    it("a failed export shows a non-blocking error and does not download", async () => {
+      fetchMock.mockImplementation((url: string) =>
+        Promise.resolve(
+          new URL(url, "http://x").pathname.endsWith(".csv")
+            ? jsonResponse({ detail: "boom" }, 500)
+            : routeFetch(url),
+        ),
+      );
+      await renderReady();
+      fireEvent.click(screen.getByRole("button", { name: "CSV" }));
+
+      const error = await screen.findByTestId("history-export-error");
+      expect(error.textContent).toContain("The CSV export failed");
+      expect(createObjectURL).not.toHaveBeenCalled();
+      expect(clicked).toHaveLength(0);
+      // The tab stays usable: rows remain, the button is re-enabled, chips still work.
+      expect(screen.getAllByTestId("history-row")).toHaveLength(5);
+      expect((screen.getByRole("button", { name: "CSV" }) as HTMLButtonElement).disabled).toBe(false);
+      fireEvent.click(screen.getByRole("button", { name: "Reversals" }));
+      await waitFor(() => expect(screen.getAllByTestId("history-row")).toHaveLength(1));
+
+      fireEvent.click(within(error).getByRole("button", { name: "Dismiss" }));
+      expect(screen.queryByTestId("history-export-error")).toBeNull();
+    });
+
+    it("the button is disabled while the request is in flight (no double-submit)", async () => {
+      let release: (response: Response) => void = () => {};
+      fetchMock.mockImplementation((url: string) =>
+        new URL(url, "http://x").pathname.endsWith(".csv")
+          ? new Promise<Response>((resolve) => {
+              release = resolve;
+            })
+          : Promise.resolve(routeFetch(url)),
+      );
+      await renderReady();
+      const csv = screen.getByRole("button", { name: "CSV" }) as HTMLButtonElement;
+      fireEvent.click(csv);
+      await waitFor(() => expect(csv.disabled).toBe(true));
+      fireEvent.click(csv);
+      expect(csvCalls()).toHaveLength(1);
+
+      release(csvResponse("all", "2026-09-10", TODAY));
+      await waitFor(() => expect(clicked).toHaveLength(1));
+      await waitFor(() => expect(csv.disabled).toBe(false));
+      expect(csvCalls()).toHaveLength(1);
+    });
+  });
+
+  it("rows are read-only: no row carries a control", async () => {
+    await renderReady();
+    for (const el of screen.getAllByTestId("history-row")) {
+      expect(within(el).queryByRole("button")).toBeNull();
+    }
+  });
+
+  it("a failed fetch shows the error state and Try again reloads", async () => {
+    fetchMock.mockImplementation(() => Promise.resolve(jsonResponse({ detail: "boom" }, 500)));
+    render(<HistoryTab today={TODAY} />);
+
+    const error = await screen.findByTestId("history-error");
+    expect(error.textContent).toContain("The history could not be loaded");
+    expect(screen.getByTestId("history-footer")).toBeTruthy();
+
+    fetchMock.mockImplementation((url: string) => Promise.resolve(routeFetch(url)));
+    fireEvent.click(within(error).getByRole("button", { name: "Try again" }));
+    await screen.findByTestId("stat-on-time");
+    expect(screen.queryByTestId("history-error")).toBeNull();
+  });
+
+  it("the scroll column ends with 92px bottom padding", async () => {
+    await renderReady();
+    expect(screen.getByTestId("history-scroll").style.paddingBottom).toBe("92px");
+  });
+});
+
+describe("HistoryTab live updates", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let streams: TestStream[];
+
+  function historyRequests(): URL[] {
+    return fetchMock.mock.calls
+      .map(([url]) => new URL(String(url), "http://x"))
+      .filter((url) => url.pathname === "/api/v1/admin/history");
+  }
+
+  const PAYLOAD = {
+    child_id: 2,
+    child_name: "Maeve",
+    instance_id: 2,
+    quest_title: "Make bed",
+    window: "morning",
+    due_date: TODAY,
+    due_time: null,
+    occurred_at: "2026-09-23T15:10:00Z",
+  };
+
+  beforeAll(() => {
+    vi.stubEnv("TZ", "America/Los_Angeles");
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+  });
+
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    streams = [];
+    fetchMock = vi.fn((url: string) => {
+      if (new URL(url, "http://x").pathname.endsWith("/api/v1/admin/events")) {
+        const stream = testStream();
+        streams.push(stream);
+        return Promise.resolve(stream.response);
+      }
+      return Promise.resolve(routeFetch(url));
+    });
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("a quest transition refetches the active filter; a day-complete does not", async () => {
+    render(
+      <TransitionsProvider>
+        <HistoryTab today={TODAY} />
+      </TransitionsProvider>,
+    );
+    await screen.findByTestId("stat-on-time");
+    fireEvent.click(screen.getByRole("button", { name: "Reversals" }));
+    await waitFor(() =>
+      expect(historyRequests().some((u) => u.searchParams.get("filter") === "reversals")).toBe(true),
+    );
+    await screen.findByTestId("stat-on-time");
+    await waitFor(() => expect(streams).toHaveLength(1));
+    const before = historyRequests().length;
+
+    streams[0].push(
+      frame("nestquest_child_day_complete", {
+        child_id: 2,
+        child_name: "Maeve",
+        quests_due: 4,
+        quests_completed: 4,
+        occurred_at: "2026-09-23T15:00:00Z",
+      }),
+    );
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(historyRequests().length).toBe(before);
+
+    streams[0].push(frame("nestquest_quest_uncompleted", PAYLOAD));
+
+    await waitFor(() => expect(historyRequests().length).toBe(before + 3));
+    const refetched = historyRequests().slice(before);
+    // One refetch (reversals + the two stats queries), same range and filter.
+    expect(refetched.map((u) => u.searchParams.get("filter")).sort()).toEqual([
+      "all",
+      "missed",
+      "reversals",
+    ]);
+    for (const url of refetched) {
+      expect(url.searchParams.get("start")).toBe("2026-09-10");
+      expect(url.searchParams.get("end")).toBe(TODAY);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(historyRequests().length).toBe(before + 3);
+    expect(screen.queryByTestId("history-loading")).toBeNull();
+    expect(screen.getByRole("button", { name: "Reversals" }).getAttribute("aria-pressed")).toBe("true");
+    // Rows stay read-only (D-005): no row carries a control.
+    for (const row of screen.getAllByTestId("history-row")) {
+      expect(within(row).queryByRole("button")).toBeNull();
+    }
+  });
+
+  describe("a filter change interleaved with a quest transition", () => {
+    // Both land before the load effect runs, so one load serves both.
+    async function interleave(order: "sse-first" | "chip-first") {
+      await act(async () => {
+        const click = () => fireEvent.click(screen.getByRole("button", { name: "Reversals" }));
+        if (order === "chip-first") click();
+        streams[0].push(frame("nestquest_quest_uncompleted", PAYLOAD));
+        await new Promise((resolve) => setTimeout(resolve, 30));
+        if (order === "sse-first") click();
+      });
+    }
+
+    async function renderLive() {
+      render(
+        <TransitionsProvider>
+          <HistoryTab today={TODAY} />
+        </TransitionsProvider>,
+      );
+      await screen.findByTestId("stat-on-time");
+      await waitFor(() => expect(streams).toHaveLength(1));
+      expect(screen.getAllByTestId("history-row")).toHaveLength(ROWS.all.length);
+    }
+
+    function titles(): string[] {
+      return screen.getAllByTestId("history-row").map((el) => el.textContent ?? "");
+    }
+
+    for (const order of ["sse-first", "chip-first"] as const) {
+      it(`${order}: shows loading, then only the active filter's rows`, async () => {
+        let release!: () => void;
+        const gate = new Promise<void>((resolve) => {
+          release = resolve;
+        });
+        const route = fetchMock.getMockImplementation()!;
+        await renderLive();
+        fetchMock.mockImplementation((url: string) => {
+          const parsed = new URL(url, "http://x");
+          if (parsed.searchParams.get("filter") === "reversals") {
+            return gate.then(() => route(url));
+          }
+          return route(url);
+        });
+
+        await interleave(order);
+        expect(screen.getByRole("button", { name: "Reversals" }).getAttribute("aria-pressed")).toBe("true");
+        // The previous filter's rows never show under the new chip.
+        expect(screen.getByTestId("history-loading")).toBeTruthy();
+        expect(screen.queryAllByTestId("history-row")).toHaveLength(0);
+
+        release();
+        await screen.findByTestId("stat-on-time");
+        expect(titles()).toHaveLength(1);
+        expect(titles()[0]).toContain("Make bed · Maeve");
+        expect(screen.getAllByTestId("history-dot")[0].className).toContain("history-dot--uncompleted");
+      });
+
+      it(`${order}: a failed filter-change load shows the error state, not stale rows`, async () => {
+        const route = fetchMock.getMockImplementation()!;
+        await renderLive();
+        fetchMock.mockImplementation((url: string) => {
+          const parsed = new URL(url, "http://x");
+          if (parsed.pathname === "/api/v1/admin/history") {
+            return Promise.resolve(jsonResponse({ detail: "boom" }, 500));
+          }
+          return route(url);
+        });
+
+        await interleave(order);
+        const error = await screen.findByTestId("history-error");
+        expect(error.textContent).toContain("The history could not be loaded");
+        expect(screen.getByRole("button", { name: "Reversals" }).getAttribute("aria-pressed")).toBe("true");
+        expect(screen.queryAllByTestId("history-row")).toHaveLength(0);
+        expect(screen.queryByTestId("stat-on-time")).toBeNull();
+      });
+    }
+  });
+
+  it("a failed transition refresh keeps the active filter's rows on screen", async () => {
+    render(
+      <TransitionsProvider>
+        <HistoryTab today={TODAY} />
+      </TransitionsProvider>,
+    );
+    await screen.findByTestId("stat-on-time");
+    await waitFor(() => expect(streams).toHaveLength(1));
+    const route = fetchMock.getMockImplementation()!;
+    fetchMock.mockImplementation((url: string) => {
+      if (new URL(url, "http://x").pathname === "/api/v1/admin/history") {
+        return Promise.resolve(jsonResponse({ detail: "boom" }, 500));
+      }
+      return route(url);
+    });
+    const before = historyRequests().length;
+
+    streams[0].push(frame("nestquest_quest_uncompleted", PAYLOAD));
+    // The "all" filter plus the missed stats query.
+    await waitFor(() => expect(historyRequests().length).toBe(before + 2));
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    expect(screen.queryByTestId("history-error")).toBeNull();
+    expect(screen.queryByTestId("history-loading")).toBeNull();
+    expect(screen.getAllByTestId("history-row")).toHaveLength(ROWS.all.length);
+  });
+});

admin/src/history/HistoryTab.tsx

@@ -0,0 +1,300 @@
+/**
+ * History tab — the append-only event log (design/ADMIN-SPEC.md §5).
+ *
+ * Rows are read-only: events are never edited or deleted, and a reversal is
+ * its own row (D-005).
+ */
+import { useEffect, useRef, useState } from "react";
+import { ApiForbiddenError } from "../api/client";
+import type { TransitionEvent } from "../api/events";
+import { useTransitions } from "../api/useTransitions";
+import { exportHistoryCsv, fetchHistory, type HistoryFilter, type HistoryRow } from "../api/history";
+import { localTodayIso } from "../schedule/cycle";
+import { dayLabel, groupByDay, rowMeta, rowTime, shiftIso } from "./format";
+import { DownloadGlyph, LockGlyph } from "./glyphs";
+import "./HistoryTab.css";
+
+/** ADMIN-SPEC §1: every scroll column ends with 92px so content clears the tab bar. */
+export const SCROLL_BOTTOM_PADDING = "92px";
+
+export const RANGE_DAYS = 14;
+
+export const FOOTER_NOTE = "Events are never edited or deleted. A reversal is its own row.";
+
+export const FILTERS: { id: HistoryFilter; label: string }[] = [
+  { id: "all", label: "All events" },
+  { id: "reversals", label: "Reversals" },
+  { id: "missed", label: "Missed" },
+];
+
+export interface HistoryStats {
+  /** Whole percent, or null when the period has no completions. */
+  onTimePct: number | null;
+  completed: number;
+  missed: number;
+}
+
+/** Per-period stats from the `all` rows (completions) and the `missed` rows. */
+export function computeStats(allRows: HistoryRow[], missedRows: HistoryRow[]): HistoryStats {
+  const completions = allRows.filter((row) => row.event_type === "completed");
+  const onTime = completions.filter((row) => row.was_on_time === true).length;
+  return {
+    onTimePct: completions.length > 0 ? Math.round((onTime / completions.length) * 100) : null,
+    completed: completions.length,
+    missed: missedRows.filter((row) => row.event_type === "missed").length,
+  };
+}
+
+interface Loaded {
+  rows: HistoryRow[];
+  stats: HistoryStats;
+}
+
+type LoadState =
+  | { kind: "loading" }
+  | { kind: "error"; message: string }
+  /** `key` is the (filter, start, end) the rows were loaded for. */
+  | { kind: "ready"; data: Loaded; key: string };
+
+/**
+ * The selected filter's rows plus the period stats. Stats always come from
+ * the `all` and `missed` queries, whichever chip is selected, so switching
+ * chips never changes the period's numbers.
+ */
+async function loadHistory(filter: HistoryFilter, start: string, end: string): Promise<Loaded> {
+  const [selected, all, missed] = await Promise.all([
+    fetchHistory(filter, start, end),
+    filter === "all" ? null : fetchHistory("all", start, end),
+    filter === "missed" ? null : fetchHistory("missed", start, end),
+  ]);
+  return {
+    rows: selected.rows,
+    stats: computeStats((all ?? selected).rows, (missed ?? selected).rows),
+  };
+}
+
+/** Offer a Blob as a file download without navigating the page. */
+export function offerDownload(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.style.display = "none";
+  document.body.appendChild(anchor);
+  try {
+    anchor.click();
+  } finally {
+    anchor.remove();
+    URL.revokeObjectURL(url);
+  }
+}
+
+function ScreenHeader({ exporting, onExport }: { exporting: boolean; onExport: () => void }) {
+  return (
+    <header className="history-header">
+      <div>
+        <h2 className="history-title">History</h2>
+        <p className="history-sub">Append-only event log · last {RANGE_DAYS} days</p>
+      </div>
+      <button
+        type="button"
+        className="history-csv"
+        data-testid="history-csv"
+        disabled={exporting}
+        aria-busy={exporting}
+        onClick={onExport}
+      >
+        <DownloadGlyph />
+        CSV
+      </button>
+    </header>
+  );
+}
+
+function StatRow({ stats }: { stats: HistoryStats }) {
+  const items = [
+    { key: "on-time", label: "On time", value: stats.onTimePct === null ? "—" : `${stats.onTimePct}%` },
+    { key: "completed", label: "Completed", value: String(stats.completed) },
+    { key: "missed", label: "Missed", value: String(stats.missed) },
+  ];
+  return (
+    <div className="history-stats">
+      {items.map((item) => (
+        <div key={item.key} className="history-stat" data-testid={`stat-${item.key}`}>
+          <div className={`history-stat-value history-stat-value--${item.key}`}>{item.value}</div>
+          <div className="history-stat-label">{item.label}</div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function EventRow({ row }: { row: HistoryRow }) {
+  return (
+    <li className="history-event" data-testid="history-row">
+      <span
+        className={`history-dot history-dot--${row.event_type}`}
+        data-testid="history-dot"
+        aria-hidden="true"
+      />
+      <div className="history-event-text">
+        <div className="history-event-title">
+          {row.quest_title} · {row.child_name}
+        </div>
+        <div className="history-event-meta" data-testid="history-meta">
+          {rowMeta(row)}
+        </div>
+      </div>
+      <span className="history-event-time">{rowTime(row)}</span>
+    </li>
+  );
+}
+
+function FooterNote() {
+  return (
+    <div className="history-note" data-testid="history-footer">
+      <span className="history-note-glyph">
+        <LockGlyph />
+      </span>
+      <span>{FOOTER_NOTE}</span>
+    </div>
+  );
+}
+
+export default function HistoryTab({ today = localTodayIso() }: { today?: string }) {
+  const [filter, setFilter] = useState<HistoryFilter>("all");
+  const [state, setState] = useState<LoadState>({ kind: "loading" });
+  const [attempt, setAttempt] = useState(0);
+  const [exporting, setExporting] = useState(false);
+  const [exportError, setExportError] = useState<string | null>(null);
+  const exportingRef = useRef(false);
+  const start = shiftIso(today, -(RANGE_DAYS - 1));
+  const key = `${filter}|${start}|${today}`;
+
+  // A quest transition is a new history row (or changes a derived missed row);
+  // a day-complete adds none. The refetch keeps the active filter and range.
+  useTransitions((event: TransitionEvent) => {
+    if (event.type === "nestquest_child_day_complete") return;
+    setAttempt((n) => n + 1);
+  });
+
+  /** Download the CSV for the active filter over the displayed range. */
+  async function exportCsv() {
+    if (exportingRef.current) return;
+    exportingRef.current = true;
+    setExporting(true);
+    setExportError(null);
+    try {
+      const { blob, filename } = await exportHistoryCsv(filter, start, today);
+      offerDownload(blob, filename);
+    } catch (error: unknown) {
+      setExportError(
+        error instanceof ApiForbiddenError
+          ? error.message
+          : "The CSV export failed. Check your connection and try again.",
+      );
+    } finally {
+      exportingRef.current = false;
+      setExporting(false);
+    }
+  }
+
+  useEffect(() => {
+    let cancelled = false;
+    // Rows already loaded for this (filter, range) stay on screen while they
+    // refresh; any other rows give way to the loading state.
+    const isCurrent = (prev: LoadState) => prev.kind === "ready" && prev.key === key;
+    setState((prev) => (isCurrent(prev) ? prev : { kind: "loading" }));
+    loadHistory(filter, start, today)
+      .then((data) => {
+        if (!cancelled) setState({ kind: "ready", data, key });
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        const message =
+          error instanceof ApiForbiddenError
+            ? error.message
+            : "The history could not be loaded. Check your connection and try again.";
+        // A failed refresh keeps the rows already on screen.
+        setState((prev) => (isCurrent(prev) ? prev : { kind: "error", message }));
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [filter, start, today, key, attempt]);
+
+  // Never render one filter's rows under another's chip, even for the render
+  // before the load effect runs.
+  const shown: LoadState = state.kind === "ready" && state.key !== key ? { kind: "loading" } : state;
+
+  let body;
+  if (shown.kind === "loading") {
+    body = (
+      <div className="history-status" role="status" data-testid="history-loading">
+        Loading history…
+      </div>
+    );
+  } else if (shown.kind === "error") {
+    body = (
+      <div className="history-status history-status--error" role="alert" data-testid="history-error">
+        <p>{shown.message}</p>
+        <button type="button" className="history-retry" onClick={() => setAttempt((n) => n + 1)}>
+          Try again
+        </button>
+      </div>
+    );
+  } else {
+    const groups = groupByDay(shown.data.rows);
+    body =
+      groups.length > 0 ? (
+        groups.map((group) => (
+          <section key={group.day} className="history-day" data-testid={`day-${group.day}`}>
+            <h3 className="history-section-label">{dayLabel(group.day, today)}</h3>
+            <ul className="history-card history-list">
+              {group.rows.map((row, index) => (
+                <EventRow key={`${row.instance_id}-${row.event_type}-${row.occurred_at ?? ""}-${index}`} row={row} />
+              ))}
+            </ul>
+          </section>
+        ))
+      ) : (
+        <div className="history-card history-empty">No events in the last {RANGE_DAYS} days.</div>
+      );
+  }
+
+  return (
+    <div className="history-screen">
+      <ScreenHeader exporting={exporting} onExport={() => void exportCsv()} />
+      <div
+        className="history-scroll"
+        data-testid="history-scroll"
+        style={{ paddingBottom: SCROLL_BOTTOM_PADDING }}
+      >
+        {exportError !== null ? (
+          <div className="history-export-error" role="alert" data-testid="history-export-error">
+            <span>{exportError}</span>
+            <button type="button" className="history-export-dismiss" onClick={() => setExportError(null)}>
+              Dismiss
+            </button>
+          </div>
+        ) : null}
+        {shown.kind === "ready" ? <StatRow stats={shown.data.stats} /> : null}
+        <div className="history-chips" role="group" aria-label="Filter events">
+          {FILTERS.map((item) => (
+            <button
+              key={item.id}
+              type="button"
+              className={item.id === filter ? "history-chip history-chip--active" : "history-chip"}
+              aria-pressed={item.id === filter}
+              onClick={() => setFilter(item.id)}
+            >
+              {item.label}
+            </button>
+          ))}
+        </div>
+        {body}
+        <FooterNote />
+      </div>
+    </div>
+  );
+}

admin/src/history/format.ts

@@ -0,0 +1,94 @@
+/**
+ * Day grouping and row wording for the History tab.
+ *
+ * Calendar dates ("YYYY-MM-DD") are handled by their components (never
+ * `new Date("YYYY-MM-DD")`, which is UTC midnight and reads as the previous
+ * day in negative-offset zones); event stamps are UTC and shown in the
+ * viewer's local time.
+ */
+import type { HistoryRow } from "../api/history";
+import { dayNumber, isoFromDayNumber, localTodayIso } from "../schedule/cycle";
+import { shortDate } from "../schedule/format";
+import { formatClockTime, formatDueTime } from "../today/format";
+
+const MS_PER_MINUTE = 60_000;
+
+/** `iso` shifted by `days` calendar days. */
+export function shiftIso(iso: string, days: number): string {
+  return isoFromDayNumber(dayNumber(iso) + days);
+}
+
+/** The local calendar day an event belongs to (due_date for missed rows). */
+export function rowDay(row: HistoryRow): string {
+  return row.occurred_at ? localTodayIso(new Date(row.occurred_at)) : row.due_date;
+}
+
+/** The row's due moment as local wall-clock time, or null without a due time. */
+function dueMoment(row: HistoryRow): Date | null {
+  const match = /^(\d{2}):(\d{2})/.exec(row.due_time ?? "");
+  if (!match) return null;
+  const [year, month, day] = row.due_date.split("-").map(Number);
+  return new Date(year, month - 1, day, Number(match[1]), Number(match[2]));
+}
+
+/** Newest first; a missed row sorts at its due moment (or the end of its day). */
+function sortKey(row: HistoryRow): number {
+  if (row.occurred_at) return Date.parse(row.occurred_at);
+  const due = dueMoment(row);
+  if (due) return due.getTime();
+  const [year, month, day] = row.due_date.split("-").map(Number);
+  return new Date(year, month - 1, day, 23, 59).getTime();
+}
+
+export interface DayGroup {
+  day: string;
+  rows: HistoryRow[];
+}
+
+/** Rows grouped by day, newest day first and newest row first within a day. */
+export function groupByDay(rows: HistoryRow[]): DayGroup[] {
+  const groups = new Map<string, HistoryRow[]>();
+  for (const row of rows) {
+    const day = rowDay(row);
+    groups.set(day, [...(groups.get(day) ?? []), row]);
+  }
+  return [...groups.entries()]
+    .sort(([a], [b]) => b.localeCompare(a))
+    .map(([day, dayRows]) => ({
+      day,
+      // Stable sort: rows at the same moment keep the API's append order.
+      rows: [...dayRows].sort((a, b) => sortKey(b) - sortKey(a)),
+    }));
+}
+
+/** "Today", "Yesterday", else "Mon, Sep 21" (the CSS uppercases it). */
+export function dayLabel(day: string, today: string): string {
+  if (day === today) return "Today";
+  if (day === shiftIso(today, -1)) return "Yesterday";
+  const weekday = new Intl.DateTimeFormat("en-US", { weekday: "short", timeZone: "UTC" }).format(
+    new Date(dayNumber(day) * 86_400_000),
+  );
+  return `${weekday}, ${shortDate(day)}`;
+}
+
+/** "on time", "late 22 min", or "late" when the lateness is not derivable. */
+function onTimeFlag(row: HistoryRow): string | null {
+  if (row.event_type !== "completed" || row.was_on_time === null) return null;
+  if (row.was_on_time) return "on time";
+  const due = dueMoment(row);
+  if (!due || !row.occurred_at) return "late";
+  const minutes = Math.round((Date.parse(row.occurred_at) - due.getTime()) / MS_PER_MINUTE);
+  return minutes > 0 ? `late ${minutes} min` : "late";
+}
+
+/** `<event type> · <actor>` plus the on-time flag for completions. */
+export function rowMeta(row: HistoryRow): string {
+  const flag = onTimeFlag(row);
+  return [row.event_type, row.actor, flag].filter(Boolean).join(" · ");
+}
+
+/** The event's local clock time; a missed row shows its due time, if any. */
+export function rowTime(row: HistoryRow): string {
+  if (row.occurred_at) return formatClockTime(row.occurred_at);
+  return row.due_time ? formatDueTime(row.due_time) : "";
+}

admin/src/history/glyphs.tsx

@@ -0,0 +1,41 @@
+/**
+ * Inline stroke glyphs for the History tab (Lucide-style 24px grid),
+ * CDN-free like the other tabs' glyphs.
+ */
+import type { ReactNode } from "react";
+
+function Glyph({ size, children }: { size: number; children: ReactNode }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    >
+      {children}
+    </svg>
+  );
+}
+
+export function DownloadGlyph({ size = 15 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4M7 10l5 5 5-5M12 15V3" />
+    </Glyph>
+  );
+}
+
+export function LockGlyph({ size = 15 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <rect x="3" y="11" width="18" height="11" rx="2" />
+      <path d="M7 11V7a5 5 0 0 1 10 0v4" />
+    </Glyph>
+  );
+}

admin/src/icons/GlyphSvg.tsx

@@ -0,0 +1,29 @@
+/**
+ * Draws a registry glyph (`registry.generated.ts`) as an inline SVG — the
+ * path data is bundled, so there is no CDN and no runtime fetch. Lucide
+ * glyphs are stroked on their 24px grid; Font Awesome glyphs are filled.
+ */
+import type { GlyphIcon } from "./registry.generated";
+
+export function GlyphSvg({ icon, size }: { icon: GlyphIcon; size: number }) {
+  const stroked = icon.kind === "lucide";
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox={icon.viewBox}
+      fill={stroked ? "none" : "currentColor"}
+      stroke={stroked ? "currentColor" : undefined}
+      strokeWidth={stroked ? 2 : undefined}
+      strokeLinecap={stroked ? "round" : undefined}
+      strokeLinejoin={stroked ? "round" : undefined}
+      aria-hidden="true"
+      focusable="false"
+      data-icon={icon.name}
+    >
+      {icon.paths.map((d, index) => (
+        <path key={index} d={d} />
+      ))}
+    </svg>
+  );
+}

admin/src/icons/registry.generated.ts

@@ -0,0 +1,765 @@
+// GENERATED by tools/icons/generate.mjs from tools/icons/curated-icons.json — do not edit.
+// Regenerate with `node tools/icons/generate.mjs` (the drift tests fail if this
+// file differs from a fresh generation).
+//
+// Glyph path data is embedded at generation time; nothing is fetched at runtime.
+// Lucide glyphs: lucide-react 1.47.0 (ISC licence).
+// Font Awesome glyphs: @fortawesome/free-solid-svg-icons 7.3.1
+// (Font Awesome Free, icons under CC BY 4.0).
+
+/** A vector glyph: draw each path in `paths` inside an <svg viewBox>. Lucide
+ *  glyphs are stroked (fill none, stroke-width 2, round caps and joins);
+ *  Font Awesome glyphs are filled. */
+export interface GlyphIcon {
+  kind: "lucide" | "fa";
+  key: string;
+  name: string;
+  label: string;
+  viewBox: string;
+  paths: readonly string[];
+}
+
+/** An emoji icon; render `text` as text. */
+export interface EmojiIcon {
+  kind: "emoji";
+  key: string;
+  text: string;
+}
+
+/** No usable icon: the caller draws its own default glyph. */
+export interface FallbackIcon {
+  kind: "fallback";
+  key: null;
+}
+
+export type ResolvedIcon = GlyphIcon | EmojiIcon | FallbackIcon;
+
+export const LUCIDE_ICONS: readonly GlyphIcon[] = [
+  {
+    "kind": "lucide",
+    "key": "lucide:bed",
+    "name": "bed",
+    "label": "Bed",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M2 4v16",
+      "M2 8h18a2 2 0 0 1 2 2v10",
+      "M2 17h20",
+      "M6 8v9"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:bath",
+    "name": "bath",
+    "label": "Bath",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M10 4 8 6",
+      "M17 19v2",
+      "M2 12h20",
+      "M7 19v2",
+      "M9 5 7.621 3.621A2.121 2.121 0 0 0 4 5v12a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-5"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:shower-head",
+    "name": "shower-head",
+    "label": "Shower",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "m4 4 2.5 2.5",
+      "M13.5 6.5a4.95 4.95 0 0 0-7 7",
+      "M15 5 5 15",
+      "M14 17v.01",
+      "M10 16v.01",
+      "M13 13v.01",
+      "M16 10v.01",
+      "M11 20v.01",
+      "M17 14v.01",
+      "M20 11v.01"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:toilet",
+    "name": "toilet",
+    "label": "Toilet",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M7 12h13a1 1 0 0 1 1 1 5 5 0 0 1-5 5h-.598a.5.5 0 0 0-.424.765l1.544 2.47a.5.5 0 0 1-.424.765H5.402a.5.5 0 0 1-.424-.765L7 18",
+      "M8 18a5 5 0 0 1-5-5V4a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v8"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:brush",
+    "name": "brush",
+    "label": "Brush",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "m11 10 3 3",
+      "M6.5 21A3.5 3.5 0 1 0 3 17.5a2.62 2.62 0 0 1-.708 1.792A1 1 0 0 0 3 21z",
+      "M9.969 17.031 21.378 5.624a1 1 0 0 0-3.002-3.002L6.967 14.031"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:smile",
+    "name": "smile",
+    "label": "Smile",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M15 10V9",
+      "M16.472 15a6 6 0 01-8.943 0",
+      "M9 10V9",
+      "M2 12a10 10 0 1 0 20 0a10 10 0 1 0 -20 0"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:shirt",
+    "name": "shirt",
+    "label": "Clothes",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M20.38 3.46 16 2a4 4 0 0 1-8 0L3.62 3.46a2 2 0 0 0-1.34 2.23l.58 3.47a1 1 0 0 0 .99.84H6v10c0 1.1.9 2 2 2h8a2 2 0 0 0 2-2V10h2.15a1 1 0 0 0 .99-.84l.58-3.47a2 2 0 0 0-1.34-2.23z"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:washing-machine",
+    "name": "washing-machine",
+    "label": "Laundry",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M3 6h3",
+      "M17 6h.01",
+      "M5 2h14a2 2 0 0 1 2 2v16a2 2 0 0 1 -2 2h-14a2 2 0 0 1 -2 -2v-16a2 2 0 0 1 2 -2z",
+      "M7 13a5 5 0 1 0 10 0a5 5 0 1 0 -10 0",
+      "M12 18a2.5 2.5 0 0 0 0-5 2.5 2.5 0 0 1 0-5"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:utensils",
+    "name": "utensils",
+    "label": "Meal",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M3 2v7c0 1.1.9 2 2 2h4a2 2 0 0 0 2-2V2",
+      "M7 2v20",
+      "M21 15V2a5 5 0 0 0-5 5v6c0 1.1.9 2 2 2h3Zm0 0v7"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:cooking-pot",
+    "name": "cooking-pot",
+    "label": "Cooking",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M2 12h20",
+      "M20 12v8a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2v-8",
+      "m4 8 16-4",
+      "m8.86 6.78-.45-1.81a2 2 0 0 1 1.45-2.43l1.94-.48a2 2 0 0 1 2.43 1.46l.45 1.8"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:apple",
+    "name": "apple",
+    "label": "Snack",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M12 6.528V3a1 1 0 0 1 1-1h0",
+      "M18.237 21A15 15 0 0 0 22 11a6 6 0 0 0-10-4.472A6 6 0 0 0 2 11a15.1 15.1 0 0 0 3.763 10 3 3 0 0 0 3.648.648 5.5 5.5 0 0 1 5.178 0A3 3 0 0 0 18.237 21"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:brush-cleaning",
+    "name": "brush-cleaning",
+    "label": "Sweep",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "m16 22-1-4",
+      "M19 14a1 1 0 0 0 1-1v-1a2 2 0 0 0-2-2h-3a1 1 0 0 1-1-1V4a2 2 0 0 0-4 0v5a1 1 0 0 1-1 1H6a2 2 0 0 0-2 2v1a1 1 0 0 0 1 1",
+      "M19 14H5l-1.973 6.767A1 1 0 0 0 4 22h16a1 1 0 0 0 .973-1.233z",
+      "m8 22 1-4"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:spray-can",
+    "name": "spray-can",
+    "label": "Clean",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M3 3h.01",
+      "M7 5h.01",
+      "M11 7h.01",
+      "M3 7h.01",
+      "M7 9h.01",
+      "M3 11h.01",
+      "M15 5h4v4h-4z",
+      "m19 9 2 2v10c0 .6-.4 1-1 1h-6c-.6 0-1-.4-1-1V11l2-2",
+      "m13 14 8-2",
+      "m13 19 8-2"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:trash-2",
+    "name": "trash-2",
+    "label": "Bins",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M10 11v6",
+      "M14 11v6",
+      "M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6",
+      "M3 6h18",
+      "M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:recycle",
+    "name": "recycle",
+    "label": "Recycling",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M7 19H4.815a1.83 1.83 0 0 1-1.57-.881 1.785 1.785 0 0 1-.004-1.784L7.196 9.5",
+      "M11 19h8.203a1.83 1.83 0 0 0 1.556-.89 1.784 1.784 0 0 0 0-1.775l-1.226-2.12",
+      "m14 16-3 3 3 3",
+      "M8.293 13.596 7.196 9.5 3.1 10.598",
+      "m9.344 5.811 1.093-1.892A1.83 1.83 0 0 1 11.985 3a1.784 1.784 0 0 1 1.546.888l3.943 6.843",
+      "m13.378 9.633 4.096 1.098 1.097-4.096"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:sofa",
+    "name": "sofa",
+    "label": "Tidy",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M20 9V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v3",
+      "M2 16a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-5a2 2 0 0 0-4 0v1.5a.5.5 0 0 1-.5.5h-11a.5.5 0 0 1-.5-.5V11a2 2 0 0 0-4 0z",
+      "M4 18v2",
+      "M20 18v2",
+      "M12 4v9"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:house",
+    "name": "house",
+    "label": "Home",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8",
+      "M3 10a2 2 0 0 1 .709-1.528l7-6a2 2 0 0 1 2.582 0l7 6A2 2 0 0 1 21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:backpack",
+    "name": "backpack",
+    "label": "School bag",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M4 10a4 4 0 0 1 4-4h8a4 4 0 0 1 4 4v10a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2z",
+      "M8 10h8",
+      "M8 18h8",
+      "M8 22v-6a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v6",
+      "M9 6V4a2 2 0 0 1 2-2h2a2 2 0 0 1 2 2v2"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:book-open",
+    "name": "book-open",
+    "label": "Reading",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M12 5v16",
+      "M20.001 19A2 2 0 0022 17V5a2 2 0 00-1.999-2L16 3.002A5 5 0 0012 5a5 5 0 00-4-2H4a2 2 0 00-2 2v12a2 2 0 001.999 2H8a5 5 0 014 2 5 5 0 014-2z"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:pencil",
+    "name": "pencil",
+    "label": "Homework",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z",
+      "m15 5 4 4"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:music",
+    "name": "music",
+    "label": "Music",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M9 18V5l12-2v13",
+      "M3 18a3 3 0 1 0 6 0a3 3 0 1 0 -6 0",
+      "M15 16a3 3 0 1 0 6 0a3 3 0 1 0 -6 0"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:dog",
+    "name": "dog",
+    "label": "Dog",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M11.25 16.25h1.5L12 17z",
+      "M16 14v.5",
+      "M4.42 11.247A13.152 13.152 0 0 0 4 14.556C4 18.728 7.582 21 12 21s8-2.272 8-6.444a11.702 11.702 0 0 0-.493-3.309",
+      "M8 14v.5",
+      "M8.5 8.5c-.384 1.05-1.083 2.028-2.344 2.5-1.931.722-3.576-.297-3.656-1-.113-.994 1.177-6.53 4-7 1.923-.321 3.651.845 3.651 2.235A7.497 7.497 0 0 1 14 5.277c0-1.39 1.844-2.598 3.767-2.277 2.823.47 4.113 6.006 4 7-.08.703-1.725 1.722-3.656 1-1.261-.472-1.855-1.45-2.239-2.5"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:cat",
+    "name": "cat",
+    "label": "Cat",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M12 5c.67 0 1.35.09 2 .26 1.78-2 5.03-2.84 6.42-2.26 1.4.58-.42 7-.42 7 .57 1.07 1 2.24 1 3.44C21 17.9 16.97 21 12 21s-9-3-9-7.56c0-1.25.5-2.4 1-3.44 0 0-1.89-6.42-.5-7 1.39-.58 4.72.23 6.5 2.23A9.04 9.04 0 0 1 12 5Z",
+      "M8 14v.5",
+      "M16 14v.5",
+      "M11.25 16.25h1.5L12 17l-.75-.75Z"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:fish",
+    "name": "fish",
+    "label": "Fish",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M6.5 12c.94-3.46 4.94-6 8.5-6 3.56 0 6.06 2.54 7 6-.94 3.47-3.44 6-7 6s-7.56-2.53-8.5-6Z",
+      "M18 12v.5",
+      "M16 17.93a9.77 9.77 0 0 1 0-11.86",
+      "M7 10.67C7 8 5.58 5.97 2.73 5.5c-1 1.5-1 5 .23 6.5-1.24 1.5-1.24 5-.23 6.5C5.58 18.03 7 16 7 13.33",
+      "M10.46 7.26C10.2 5.88 9.17 4.24 8 3h5.8a2 2 0 0 1 1.98 1.67l.23 1.4",
+      "m16.01 17.93-.23 1.4A2 2 0 0 1 13.8 21H9.5a5.96 5.96 0 0 0 1.49-3.98"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:sprout",
+    "name": "sprout",
+    "label": "Plants",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M14 9.536V7a4 4 0 0 1 4-4h1.5a.5.5 0 0 1 .5.5V5a4 4 0 0 1-4 4 4 4 0 0 0-4 4c0 2 1 3 1 5a5 5 0 0 1-1 3",
+      "M4 9a5 5 0 0 1 8 4 5 5 0 0 1-8-4",
+      "M5 21h14"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:droplets",
+    "name": "droplets",
+    "label": "Water",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M7 16.3c2.2 0 4-1.83 4-4.05 0-1.16-.57-2.26-1.71-3.19S7.29 6.75 7 5.3c-.29 1.45-1.14 2.84-2.29 3.76S3 11.1 3 12.25c0 2.22 1.8 4.05 4 4.05z",
+      "M12.56 6.6A10.97 10.97 0 0 0 14 3.02c.5 2.5 2 4.9 4 6.5s3 3.5 3 5.5a6.98 6.98 0 0 1-11.91 4.97"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:bike",
+    "name": "bike",
+    "label": "Bike",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M15 17.5a3.5 3.5 0 1 0 7 0a3.5 3.5 0 1 0 -7 0",
+      "M2 17.5a3.5 3.5 0 1 0 7 0a3.5 3.5 0 1 0 -7 0",
+      "M14 5a1 1 0 1 0 2 0a1 1 0 1 0 -2 0",
+      "M12 17.5V14l-3-3 4-3 2 3h2"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:volleyball",
+    "name": "volleyball",
+    "label": "Sport",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M11 7a16 16 20 0 1 10.98 4.362",
+      "M12 12a13 13 0 0 1-8.66 5",
+      "M16.83 13.634a16 16 0 0 1-9.267 7.328",
+      "M20.66 17A13 13 0 0 0 12 12a13 13 0 0 1 0-10",
+      "M8.17 15.366a16 16 0 0 1-1.713-11.69",
+      "M2 12a10 10 0 1 0 20 0a10 10 0 1 0 -20 0"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:gamepad-2",
+    "name": "gamepad-2",
+    "label": "Games",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M6 11L10 11",
+      "M8 9L8 13",
+      "M15 12L15.01 12",
+      "M18 10L18.01 10",
+      "M17.32 5H6.68a4 4 0 0 0-3.978 3.59c-.006.052-.01.101-.017.152C2.604 9.416 2 14.456 2 16a3 3 0 0 0 3 3c1 0 1.5-.5 2-1l1.414-1.414A2 2 0 0 1 9.828 16h4.344a2 2 0 0 1 1.414.586L17 18c.5.5 1 1 2 1a3 3 0 0 0 3-3c0-1.545-.604-6.584-.685-7.258-.007-.05-.011-.1-.017-.151A4 4 0 0 0 17.32 5z"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:star",
+    "name": "star",
+    "label": "Star",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:heart",
+    "name": "heart",
+    "label": "Heart",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M2 9.5a5.5 5.5 0 0 1 9.591-3.676.56.56 0 0 0 .818 0A5.49 5.49 0 0 1 22 9.5c0 2.29-1.5 4-3 5.5l-5.492 5.313a2 2 0 0 1-3 .019L5 15c-1.5-1.5-3-3.2-3-5.5"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:sun",
+    "name": "sun",
+    "label": "Morning",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M8 12a4 4 0 1 0 8 0a4 4 0 1 0 -8 0",
+      "M12 2v2",
+      "M12 20v2",
+      "m4.93 4.93 1.41 1.41",
+      "m17.66 17.66 1.41 1.41",
+      "M2 12h2",
+      "M20 12h2",
+      "m6.34 17.66-1.41 1.41",
+      "m19.07 4.93-1.41 1.41"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:moon",
+    "name": "moon",
+    "label": "Bedtime",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:clock",
+    "name": "clock",
+    "label": "Clock",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M2 12a10 10 0 1 0 20 0a10 10 0 1 0 -20 0",
+      "M12 6v6l4 2"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:calendar",
+    "name": "calendar",
+    "label": "Calendar",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M8 2v3",
+      "M16 2v3",
+      "M5 3h14a2 2 0 0 1 2 2v14a2 2 0 0 1 -2 2h-14a2 2 0 0 1 -2 -2v-14a2 2 0 0 1 2 -2z",
+      "M3 9h18"
+    ]
+  },
+  {
+    "kind": "lucide",
+    "key": "lucide:list-checks",
+    "name": "list-checks",
+    "label": "Checklist",
+    "viewBox": "0 0 24 24",
+    "paths": [
+      "M13 5h8",
+      "M13 12h8",
+      "M13 19h8",
+      "m3 17 2 2 4-4",
+      "m3 7 2 2 4-4"
+    ]
+  }
+];
+
+export const FA_ICONS: readonly GlyphIcon[] = [
+  {
+    "kind": "fa",
+    "key": "fa:broom",
+    "name": "broom",
+    "label": "Sweep",
+    "viewBox": "0 0 576 512",
+    "paths": [
+      "M566.6 54.6c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0l-192 192-34.7-34.7c-4.2-4.2-10-6.6-16-6.6-12.5 0-22.6 10.1-22.6 22.6l0 29.1 108.3 108.3 29.1 0c12.5 0 22.6-10.1 22.6-22.6 0-6-2.4-11.8-6.6-16l-34.7-34.7 192-192zM341.1 353.4L222.6 234.9c-42.7-3.7-85.2 11.7-115.8 42.3l-8 8c-22.3 22.3-34.8 52.5-34.8 84 0 6.8 7.1 11.2 13.2 8.2l51.1-25.5c5-2.5 9.5 4.1 5.4 7.9L7.3 473.4C2.7 477.6 0 483.6 0 489.9 0 502.1 9.9 512 22.1 512l173.3 0c38.8 0 75.9-15.4 103.4-42.8 30.6-30.6 45.9-73.1 42.3-115.8z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:spray-can-sparkles",
+    "name": "spray-can-sparkles",
+    "label": "Clean",
+    "viewBox": "0 0 576 512",
+    "paths": [
+      "M160 32l0 80 128 0 0-80c0-17.7-14.3-32-32-32L192 0c-17.7 0-32 14.3-32 32zm0 128c-53 0-96 43-96 96l0 208c0 26.5 21.5 48 48 48l224 0c26.5 0 48-21.5 48-48l0-208c0-53-43-96-96-96l-128 0zm64 96a80 80 0 1 1 0 160 80 80 0 1 1 0-160zM448 48c0-1.4-1-3-2.2-3.6L416 32 403.6 2.2C403 1 401.4 0 400 0s-3 1-3.6 2.2L384 32 354.2 44.4c-1.2 .6-2.2 2.2-2.2 3.6 0 1.4 1 3 2.2 3.6L384 64 396.4 93.8C397 95 398.6 96 400 96s3-1 3.6-2.2L416 64 445.8 51.6C447 51 448 49.4 448 48zm76.4 45.8C525 95 526.6 96 528 96s3-1 3.6-2.2L544 64 573.8 51.6c1.2-.6 2.2-2.2 2.2-3.6 0-1.4-1-3-2.2-3.6L544 32 531.6 2.2C531 1 529.4 0 528 0s-3 1-3.6 2.2L512 32 482.2 44.4c-1.2 .6-2.2 2.2-2.2 3.6 0 1.4 1 3 2.2 3.6L512 64 524.4 93.8zm7.2 100.4c-.6-1.2-2.2-2.2-3.6-2.2s-3 1-3.6 2.2L512 224 482.2 236.4c-1.2 .6-2.2 2.2-2.2 3.6 0 1.4 1 3 2.2 3.6L512 256 524.4 285.8c.6 1.2 2.2 2.2 3.6 2.2s3-1 3.6-2.2L544 256 573.8 243.6c1.2-.6 2.2-2.2 2.2-3.6 0-1.4-1-3-2.2-3.6L544 224 531.6 194.2zM512 144c0-1.4-1-3-2.2-3.6L480 128 467.6 98.2C467 97 465.4 96 464 96s-3 1-3.6 2.2L448 128 418.2 140.4c-1.2 .6-2.2 2.2-2.2 3.6 0 1.4 1 3 2.2 3.6L448 160 460.4 189.8c.6 1.2 2.2 2.2 3.6 2.2s3-1 3.6-2.2L480 160 509.8 147.6c1.2-.6 2.2-2.2 2.2-3.6z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:bucket",
+    "name": "bucket",
+    "label": "Mop",
+    "viewBox": "0 0 448 512",
+    "paths": [
+      "M443.7 208c2.7 4.7 4.3 10.2 4.3 16 0 17.7-14.3 32-32 32l-5.1 0-22.4 213c-2.6 24.4-23.2 43-47.8 43l-233.6 0c-24.6 0-45.2-18.5-47.8-43L37.1 256 32 256c-17.7 0-32-14.3-32-32 0-5.8 1.6-11.3 4.3-16l439.4 0zM224-16c79.5 0 144 64.5 144 144l0 32-48 0 0-32c0-53-43-96-96-96s-96 43-96 96l0 32-48 0 0-32C80 48.5 144.5-16 224-16z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:soap",
+    "name": "soap",
+    "label": "Wash hands",
+    "viewBox": "0 0 512 512",
+    "paths": [
+      "M208-32a48 48 0 1 1 0 96 48 48 0 1 1 0-96zM320 96a64 64 0 1 1 0 128 64 64 0 1 1 0-128zM352 0a32 32 0 1 1 64 0 32 32 0 1 1 -64 0zM96 160l112 0c0 23.8 7.4 45.9 20.1 64L160 224c-53 0-96 43-96 96s43 96 96 96l192 0c53 0 96-43 96-96 0-35.1-18.9-65.9-47-82.6 19-19.8 30.7-46.6 31-76.1 45.4 7.6 80 47.1 80 94.7l0 128c0 53-43 96-96 96L96 480c-53 0-96-43-96-96L0 256c0-53 43-96 96-96zm64 112l192 0c26.5 0 48 21.5 48 48s-21.5 48-48 48l-192 0c-26.5 0-48-21.5-48-48s21.5-48 48-48z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:sink",
+    "name": "sink",
+    "label": "Dishes",
+    "viewBox": "0 0 512 512",
+    "paths": [
+      "M288 96c0-17.7 14.3-32 32-32s32 14.3 32 32 14.3 32 32 32 32-14.3 32-32c0-53-43-96-96-96s-96 43-96 96l0 192-64 0 0-40c0-30.9-25.1-56-56-56l-48 0c-13.3 0-24 10.7-24 24s10.7 24 24 24l48 0c4.4 0 8 3.6 8 8l0 40-80 0c-17.7 0-32 14.3-32 32s14.3 32 32 32l0 64c0 53 43 96 96 96l256 0c53 0 96-43 96-96l0-64c17.7 0 32-14.3 32-32s-14.3-32-32-32l-80 0 0-40c0-4.4 3.6-8 8-8l56 0c13.3 0 24-10.7 24-24s-10.7-24-24-24l-56 0c-30.9 0-56 25.1-56 56l0 40-64 0 0-192z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:jug-detergent",
+    "name": "jug-detergent",
+    "label": "Laundry",
+    "viewBox": "0 0 384 512",
+    "paths": [
+      "M96 24c0-13.3 10.7-24 24-24l80 0c13.3 0 24 10.7 24 24l0 24 8 0c13.3 0 24 10.7 24 24s-10.7 24-24 24L88 96C74.7 96 64 85.3 64 72S74.7 48 88 48l8 0 0-24zM0 256c0-70.7 57.3-128 128-128l128 0c70.7 0 128 57.3 128 128l0 192c0 35.3-28.7 64-64 64L64 512c-35.3 0-64-28.7-64-64L0 256zm256 0l0 96c0 17.7 14.3 32 32 32s32-14.3 32-32l0-96c0-17.7-14.3-32-32-32s-32 14.3-32 32z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:socks",
+    "name": "socks",
+    "label": "Socks",
+    "viewBox": "0 0 512 512",
+    "paths": [
+      "M252.8 0L176 0c-26.5 0-48 21.5-48 48l0 16 112 0 0-16c0-17.5 4.7-33.9 12.8-48zM128 112l0 128c0 20.1-9.5 39.1-25.6 51.2l-64 48c-24.2 18.1-38.4 46.6-38.4 76.8 0 53 43 96 96 96 15.4 0 30.5-3.7 44-10.7-17.6-23.9-28-53.4-28-85.3 0-45.3 21.3-88 57.6-115.2l64-48c4-3 6.4-7.8 6.4-12.8l0-128-112 0zm160 0l0 128c0 20.1-9.5 39.1-25.6 51.2l-64 48c-24.2 18.1-38.4 46.6-38.4 76.8 0 53 43 96 96 96 20.8 0 41-6.7 57.6-19.2l115.2-86.4C461 382.2 480 344.3 480 304l0-192-192 0zM480 64l0-16c0-26.5-21.5-48-48-48L336 0c-26.5 0-48 21.5-48 48l0 16 192 0z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:shirt",
+    "name": "shirt",
+    "label": "Clothes",
+    "viewBox": "0 0 640 512",
+    "paths": [
+      "M320.2 112c44.2 0 80-35.8 80-80l53.5 0c17 0 33.3 6.7 45.3 18.7L617.6 169.4c12.5 12.5 12.5 32.8 0 45.3l-50.7 50.7c-12.5 12.5-32.8 12.5-45.3 0l-41.4-41.4 0 224c0 35.3-28.7 64-64 64l-192 0c-35.3 0-64-28.7-64-64l0-224-41.4 41.4c-12.5 12.5-32.8 12.5-45.3 0L22.9 214.6c-12.5-12.5-12.5-32.8 0-45.3L141.5 50.7c12-12 28.3-18.7 45.3-18.7l53.5 0c0 44.2 35.8 80 80 80z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:bed",
+    "name": "bed",
+    "label": "Bed",
+    "viewBox": "0 0 576 512",
+    "paths": [
+      "M32 32c17.7 0 32 14.3 32 32l0 224 224 0 0-128c0-17.7 14.3-32 32-32l160 0c53 0 96 43 96 96l0 224c0 17.7-14.3 32-32 32s-32-14.3-32-32l0-64-448 0 0 64c0 17.7-14.3 32-32 32S0 465.7 0 448L0 64C0 46.3 14.3 32 32 32zm80 160a64 64 0 1 1 128 0 64 64 0 1 1 -128 0z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:couch",
+    "name": "couch",
+    "label": "Tidy",
+    "viewBox": "0 0 640 512",
+    "paths": [
+      "M144 272C144 224.7 109.8 185.4 64.8 177.5 72 113.6 126.2 64 192 64l256 0c65.8 0 120 49.6 127.2 113.5-45 8-79.2 47.2-79.2 94.5l0 32-352 0 0-32zM0 384L0 272c0-26.5 21.5-48 48-48s48 21.5 48 48l0 80 448 0 0-80c0-26.5 21.5-48 48-48s48 21.5 48 48l0 112c0 35.3-28.7 64-64 64L64 448c-35.3 0-64-28.7-64-64z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:bath",
+    "name": "bath",
+    "label": "Bath",
+    "viewBox": "0 0 512 512",
+    "paths": [
+      "M96 77.3c0-7.3 5.9-13.3 13.3-13.3 3.5 0 6.9 1.4 9.4 3.9l14.9 14.9c-3.6 9.1-5.5 18.9-5.5 29.2 0 19.9 7.2 38 19.2 52-5.3 9.2-4 21.1 3.8 29 9.4 9.4 24.6 9.4 33.9 0L289 89c9.4-9.4 9.4-24.6 0-33.9-7.8-7.9-19.8-9.1-29-3.8-14-12-32.1-19.2-52-19.2-10.3 0-20.2 2-29.2 5.5L163.9 22.6C149.4 8.1 129.7 0 109.3 0 66.6 0 32 34.6 32 77.3L32 256c-17.7 0-32 14.3-32 32s14.3 32 32 32l0 48c0 28.4 12.4 54 32 71.6L64 480c0 17.7 14.3 32 32 32s32-14.3 32-32l0-16 256 0 0 16c0 17.7 14.3 32 32 32s32-14.3 32-32l0-40.4c19.6-17.6 32-43.1 32-71.6l0-48c17.7 0 32-14.3 32-32s-14.3-32-32-32L96 256 96 77.3z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:tooth",
+    "name": "tooth",
+    "label": "Teeth",
+    "viewBox": "0 0 448 512",
+    "paths": [
+      "M145 5.7L224 32 303 5.7C314.3 1.9 326 0 337.9 0 398.7 0 448 49.3 448 110.1l0 68.5c0 29.4-9.5 58.1-27.2 81.6l-1.1 1.5c-12.9 17.2-21.3 37.4-24.3 58.7L373.7 471.9c-3.3 23-23 40.1-46.2 40.1-22.8 0-42.3-16.5-46-39L261.3 351.6c-3-18.2-18.8-31.6-37.3-31.6s-34.2 13.4-37.3 31.6L166.5 473c-3.8 22.5-23.2 39-46 39-23.2 0-42.9-17.1-46.2-40.1L52.6 320.5c-3-21.3-11.4-41.5-24.3-58.7l-1.1-1.5C9.5 236.7 0 208.1 0 178.7l0-68.5C0 49.3 49.3 0 110.1 0 122 0 133.7 1.9 145 5.7z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:utensils",
+    "name": "utensils",
+    "label": "Meal",
+    "viewBox": "0 0 512 512",
+    "paths": [
+      "M63.9 14.4C63.1 6.2 56.2 0 48 0s-15.1 6.2-16 14.3L17.9 149.7c-1.3 6-1.9 12.1-1.9 18.2 0 45.9 35.1 83.6 80 87.7L96 480c0 17.7 14.3 32 32 32s32-14.3 32-32l0-224.4c44.9-4.1 80-41.8 80-87.7 0-6.1-.6-12.2-1.9-18.2L223.9 14.3C223.1 6.2 216.2 0 208 0s-15.1 6.2-15.9 14.4L178.5 149.9c-.6 5.7-5.4 10.1-11.1 10.1-5.8 0-10.6-4.4-11.2-10.2L143.9 14.6C143.2 6.3 136.3 0 128 0s-15.2 6.3-15.9 14.6L99.8 149.8c-.5 5.8-5.4 10.2-11.2 10.2-5.8 0-10.6-4.4-11.1-10.1L63.9 14.4zM448 0C432 0 320 32 320 176l0 112c0 35.3 28.7 64 64 64l32 0 0 128c0 17.7 14.3 32 32 32s32-14.3 32-32l0-448c0-17.7-14.3-32-32-32z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:bowl-food",
+    "name": "bowl-food",
+    "label": "Set the table",
+    "viewBox": "0 0 512 512",
+    "paths": [
+      "M0 176c0-35.3 28.7-64 64-64 .5 0 1.1 0 1.6 0 7.4-36.5 39.7-64 78.4-64 15 0 29 4.1 40.9 11.2 13.3-25.7 40.1-43.2 71.1-43.2s57.8 17.6 71.1 43.2c12-7.1 26-11.2 40.9-11.2 38.7 0 71 27.5 78.4 64 .5 0 1.1 0 1.6 0 35.3 0 64 28.7 64 64 0 11.7-3.1 22.6-8.6 32L8.6 208C3.1 198.6 0 187.7 0 176zM0 283.4C0 268.3 12.3 256 27.4 256l457.1 0c15.1 0 27.4 12.3 27.4 27.4 0 70.5-44.4 130.7-106.7 154.1L403.5 452c-2 16-15.6 28-31.8 28l-231.5 0c-16.1 0-29.8-12-31.8-28l-1.8-14.4C44.4 414.1 0 353.9 0 283.4z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:basket-shopping",
+    "name": "basket-shopping",
+    "label": "Groceries",
+    "viewBox": "0 0 576 512",
+    "paths": [
+      "M288 0c6.6 0 12.9 2.7 17.4 7.5l144 152 .5 .5 78.1 0c17.7 0 32 14.3 32 32 0 14.5-9.6 26.7-22.8 30.7L491.1 429.9c-6.5 29.3-32.5 50.1-62.5 50.1l-281.3 0c-30 0-56-20.8-62.5-50.1l-46-207.2c-13.2-3.9-22.8-16.2-22.8-30.7 0-17.7 14.3-32 32-32l78.1 0 .5-.5 144-152C275.1 2.7 281.4 0 288 0zm0 58.9L192.2 160 383.8 160 288 58.9zM208 264c0-13.3-10.7-24-24-24s-24 10.7-24 24l0 112c0 13.3 10.7 24 24 24s24-10.7 24-24l0-112zm80-24c-13.3 0-24 10.7-24 24l0 112c0 13.3 10.7 24 24 24s24-10.7 24-24l0-112c0-13.3-10.7-24-24-24zm128 24c0-13.3-10.7-24-24-24s-24 10.7-24 24l0 112c0 13.3 10.7 24 24 24s24-10.7 24-24l0-112z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:trash-can",
+    "name": "trash-can",
+    "label": "Bins",
+    "viewBox": "0 0 448 512",
+    "paths": [
+      "M136.7 5.9C141.1-7.2 153.3-16 167.1-16l113.9 0c13.8 0 26 8.8 30.4 21.9L320 32 416 32c17.7 0 32 14.3 32 32s-14.3 32-32 32L32 96C14.3 96 0 81.7 0 64S14.3 32 32 32l96 0 8.7-26.1zM32 144l384 0 0 304c0 35.3-28.7 64-64 64L96 512c-35.3 0-64-28.7-64-64l0-304zm88 64c-13.3 0-24 10.7-24 24l0 192c0 13.3 10.7 24 24 24s24-10.7 24-24l0-192c0-13.3-10.7-24-24-24zm104 0c-13.3 0-24 10.7-24 24l0 192c0 13.3 10.7 24 24 24s24-10.7 24-24l0-192c0-13.3-10.7-24-24-24zm104 0c-13.3 0-24 10.7-24 24l0 192c0 13.3 10.7 24 24 24s24-10.7 24-24l0-192c0-13.3-10.7-24-24-24z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:recycle",
+    "name": "recycle",
+    "label": "Recycling",
+    "viewBox": "0 0 512 512",
+    "paths": [
+      "M152.3 60C198.5-20 314-20 360.2 60l37.3 64.6 27.7-16c8.4-4.9 18.9-4.2 26.6 1.7s11.1 15.9 8.6 25.3L436.9 223c-3.4 12.8-16.6 20.4-29.4 17l-87.4-23.4c-9.4-2.5-16.3-10.4-17.6-20s3.4-19.1 11.8-23.9l27.7-16-37.3-64.6c-21.6-37.3-75.4-37.3-97 0l-5.3 9.1c-8.8 15.3-28.4 20.5-43.7 11.7S138.2 84.5 147 69.1l5.3-9.1zM449.7 279.1c15.3-8.8 34.9-3.6 43.7 11.7l5.3 9.1c46.2 80-11.5 180-103.9 180l-74.6 0 0 32c0 9.7-5.8 18.5-14.8 22.2s-19.3 1.7-26.2-5.2l-64-64c-9.4-9.4-9.4-24.6 0-33.9l64-64c6.9-6.9 17.2-8.9 26.2-5.2s14.8 12.5 14.8 22.2l0 32 74.6 0c43.1 0 70.1-46.7 48.5-84l-5.3-9.1c-8.8-15.3-3.6-34.9 11.7-43.7zM51 235.4l-27.7-16c-8.4-4.9-13.1-14.3-11.8-23.9s8.2-17.5 17.6-20L116.5 152c12.8-3.4 26 4.2 29.4 17l23.4 87.4c2.5 9.4-.9 19.3-8.6 25.3s-18.2 6.6-26.6 1.7l-27.7-16-37.3 64.6c-21.6 37.3 5.4 84 48.5 84l10.6 0c17.7 0 32 14.3 32 32s-14.3 32-32 32l-10.6 0C25.3 480-32.4 380 13.8 300L51 235.4z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:dog",
+    "name": "dog",
+    "label": "Dog",
+    "viewBox": "0 0 576 512",
+    "paths": [
+      "M32 112c16.6 0 30.2 12.6 31.8 28.7l.3 6.6C65.8 163.4 79.4 176 96 176l179.1 0 140.9 60.4 0 243.6c0 17.7-14.3 32-32 32l-32 0c-17.7 0-32-14.3-32-32l0-131.3C296 361 268.8 368 240 368s-56-7-80-19.3L160 480c0 17.7-14.3 32-32 32l-32 0c-17.7 0-32-14.3-32-32l0-245.6c-37.3-13.2-64-48.6-64-90.4 0-17.7 14.3-32 32-32zM355.8-32c7.7 0 14.9 3.6 19.6 9.8L392 0 444.1 0c12.7 0 24.9 5.1 33.9 14.1L496 32 552 32c13.3 0 24 10.7 24 24l0 24c0 44.2-35.8 80-80 80l-64 0-7 28-124.7-53.4 31.6-147.2C334.3-23.9 344.2-32 355.8-32zM448 44a20 20 0 1 0 0 40 20 20 0 1 0 0-40z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:cat",
+    "name": "cat",
+    "label": "Cat",
+    "viewBox": "0 0 576 512",
+    "paths": [
+      "M64 96c53 0 96 43 96 96l0 85.8c29.7-44.7 77.8-76.2 133.4-84 25.6 60 85.2 102.1 154.6 102.1 10.9 0 21.6-1.1 32-3.1L480 480c0 17.7-14.3 32-32 32s-32-14.3-32-32l0-140.8-136 108.8 56 0c17.7 0 32 14.3 32 32s-14.3 32-32 32l-144 0c-53 0-96-43-96-96l0-224c0-16.6-12.6-30.2-28.7-31.8l-6.6-.3C44.6 158.2 32 144.6 32 128 32 110.3 46.3 96 64 96zM533.8 3.2C544.2-5.5 560 1.9 560 15.5L560 128c0 61.9-50.1 112-112 112S336 189.9 336 128l0-112.5c0-13.6 15.8-21 26.2-12.3L416 48 480 48 533.8 3.2zM400 108a20 20 0 1 0 0 40 20 20 0 1 0 0-40zm96 0a20 20 0 1 0 0 40 20 20 0 1 0 0-40z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:paw",
+    "name": "paw",
+    "label": "Pets",
+    "viewBox": "0 0 512 512",
+    "paths": [
+      "M234.5 92.9c14.3 42.9-.3 86.2-32.6 96.8s-70.1-15.6-84.4-58.5 .3-86.2 32.6-96.8 70.1 15.6 84.4 58.5zM100.4 198.6c18.9 32.4 14.3 70.1-10.2 84.1s-59.7-.9-78.5-33.3-14.3-70.1 10.2-84.1 59.7 .9 78.5 33.3zM69.2 401.2C121.6 259.9 214.7 224 256 224s134.4 35.9 186.8 177.2c3.6 9.7 5.2 20.1 5.2 30.5l0 1.6c0 25.8-20.9 46.7-46.7 46.7-11.5 0-22.9-1.4-34-4.2l-88-22c-15.3-3.8-31.3-3.8-46.6 0l-88 22c-11.1 2.8-22.5 4.2-34 4.2-25.8 0-46.7-20.9-46.7-46.7l0-1.6c0-10.4 1.6-20.8 5.2-30.5zM421.8 282.7c-24.5-14-29.1-51.7-10.2-84.1s54-47.3 78.5-33.3 29.1 51.7 10.2 84.1-54 47.3-78.5 33.3zM310.1 189.7c-32.3-10.6-46.9-53.9-32.6-96.8s52.1-69.1 84.4-58.5 46.9 53.9 32.6 96.8-52.1 69.1-84.4 58.5z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:seedling",
+    "name": "seedling",
+    "label": "Plants",
+    "viewBox": "0 0 512 512",
+    "paths": [
+      "M512 32C512 140.1 435.4 230.3 333.6 251.4 325.7 193.3 299.6 141 261.1 100.5 301.2 40 369.9 0 448 0l32 0c17.7 0 32 14.3 32 32zM0 96C0 78.3 14.3 64 32 64l32 0c123.7 0 224 100.3 224 224l0 192c0 17.7-14.3 32-32 32s-32-14.3-32-32l0-160C100.3 320 0 219.7 0 96z"
+    ]
+  },
+  {
+    "kind": "fa",
+    "key": "fa:book",
+    "name": "book",
+    "label": "Reading",
+    "viewBox": "0 0 448 512",
+    "paths": [
+      "M384 512L96 512c-53 0-96-43-96-96L0 96C0 43 43 0 96 0L400 0c26.5 0 48 21.5 48 48l0 288c0 20.9-13.4 38.7-32 45.3l0 66.7c17.7 0 32 14.3 32 32s-14.3 32-32 32l-32 0zM96 384c-17.7 0-32 14.3-32 32s14.3 32 32 32l256 0 0-64-256 0zm32-232c0 13.3 10.7 24 24 24l176 0c13.3 0 24-10.7 24-24s-10.7-24-24-24l-176 0c-13.3 0-24 10.7-24 24zm24 72c-13.3 0-24 10.7-24 24s10.7 24 24 24l176 0c13.3 0 24-10.7 24-24s-10.7-24-24-24l-176 0z"
+    ]
+  }
+];
+
+export const FALLBACK_ICON: FallbackIcon = { kind: "fallback", key: null };
+
+/** Mirrors core/icons.py EMOJI_MAX_CODE_POINTS. */
+export const EMOJI_MAX_CODE_POINTS = 8;
+
+const LUCIDE_BY_NAME: ReadonlyMap<string, GlyphIcon> = new Map(LUCIDE_ICONS.map((icon) => [icon.name, icon]));
+const FA_BY_NAME: ReadonlyMap<string, GlyphIcon> = new Map(FA_ICONS.map((icon) => [icon.name, icon]));
+
+function isEmojiPayload(text: string): boolean {
+  const codePoints = [...text];
+  if (codePoints.length === 0 || codePoints.length > EMOJI_MAX_CODE_POINTS) return false;
+  return !codePoints.some((char) => /[\s<>&]|\p{Cc}/u.test(char));
+}
+
+/**
+ * The renderable icon for a stored definition `icon` value.
+ *
+ * `lucide:<name>` and a legacy bare `<name>` resolve against the curated
+ * Lucide set, `fa:<name>` against the curated Font Awesome set, and
+ * `emoji:<grapheme>` to its text. Like the backend's
+ * normalize_icon_for_read, nothing here throws: null, empty, an unknown
+ * namespace or name, or a malformed emoji all resolve to FALLBACK_ICON.
+ */
+export function resolveIcon(value: string | null | undefined): ResolvedIcon {
+  if (!value || !value.trim()) return FALLBACK_ICON;
+  const colon = value.indexOf(":");
+  if (colon === -1) return LUCIDE_BY_NAME.get(value) ?? FALLBACK_ICON;
+  const namespace = value.slice(0, colon);
+  const name = value.slice(colon + 1);
+  if (namespace === "lucide") return LUCIDE_BY_NAME.get(name) ?? FALLBACK_ICON;
+  if (namespace === "fa") return FA_BY_NAME.get(name) ?? FALLBACK_ICON;
+  if (namespace === "emoji" && isEmojiPayload(name)) return { kind: "emoji", key: value, text: name };
+  return FALLBACK_ICON;
+}

admin/src/icons/registry.test.ts

@@ -0,0 +1,122 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+// The offline generator is the only writer of both registry artefacts.
+import { OUTPUT_PATHS, REPO_ROOT, SOURCE_PATH, renderRegistry } from "../../../tools/icons/generate.mjs";
+import { FALLBACK_ICON, FA_ICONS, LUCIDE_ICONS, resolveIcon } from "./registry.generated";
+
+type Curated = { lucide: { name: string; label: string }[]; fa: { name: string; label: string }[] };
+
+const curated = JSON.parse(readFileSync(SOURCE_PATH, "utf8")) as Curated;
+
+describe("shared icon registry — one source of truth", () => {
+  it("both committed artefacts are byte-identical to a fresh generation", async () => {
+    const fresh = await renderRegistry();
+    expect(OUTPUT_PATHS).toHaveLength(2);
+    for (const path of OUTPUT_PATHS) {
+      expect(readFileSync(path, "utf8"), `${path} drifted — run node tools/icons/generate.mjs`).toBe(fresh);
+    }
+  });
+
+  it("the generated sets carry exactly the curated names and labels, in order", () => {
+    expect(LUCIDE_ICONS.map(({ name, label }) => ({ name, label }))).toEqual(curated.lucide);
+    expect(FA_ICONS.map(({ name, label }) => ({ name, label }))).toEqual(curated.fa);
+    expect(curated.lucide).toHaveLength(36);
+    expect(FA_ICONS.length).toBeGreaterThanOrEqual(15);
+    expect(FA_ICONS.length).toBeLessThanOrEqual(25);
+  });
+
+  it("every glyph is plain data: a viewBox and at least one path", () => {
+    for (const icon of LUCIDE_ICONS) {
+      expect(icon.kind).toBe("lucide");
+      expect(icon.key).toBe(`lucide:${icon.name}`);
+      expect(icon.viewBox).toBe("0 0 24 24");
+      expect(icon.paths.length, icon.name).toBeGreaterThan(0);
+    }
+    for (const icon of FA_ICONS) {
+      expect(icon.kind).toBe("fa");
+      expect(icon.key).toBe(`fa:${icon.name}`);
+      expect(icon.viewBox).toMatch(/^0 0 \d+ 512$/);
+      expect(icon.paths.length, icon.name).toBeGreaterThan(0);
+    }
+    for (const icon of [...LUCIDE_ICONS, ...FA_ICONS]) {
+      for (const d of icon.paths) expect(d, icon.key).toMatch(/^[Mm][-0-9.,\sA-Za-z]+$/);
+    }
+  });
+});
+
+describe("resolveIcon", () => {
+  it("resolves lucide:, fa: and emoji: keys", () => {
+    const dog = resolveIcon("lucide:dog");
+    expect(dog.kind).toBe("lucide");
+    expect(dog).toBe(LUCIDE_ICONS.find((icon) => icon.name === "dog"));
+
+    const broom = resolveIcon("fa:broom");
+    expect(broom.kind).toBe("fa");
+    expect(broom).toBe(FA_ICONS.find((icon) => icon.name === "broom"));
+
+    expect(resolveIcon("emoji:🐶")).toEqual({ kind: "emoji", key: "emoji:🐶", text: "🐶" });
+    expect(resolveIcon("emoji:👨‍👩‍👧")).toEqual({ kind: "emoji", key: "emoji:👨‍👩‍👧", text: "👨‍👩‍👧" });
+  });
+
+  it("reads a legacy bare name as Lucide", () => {
+    expect(resolveIcon("dog")).toBe(resolveIcon("lucide:dog"));
+    expect(resolveIcon("trash-2")).toBe(LUCIDE_ICONS.find((icon) => icon.name === "trash-2"));
+  });
+
+  it("falls back — never throws — for empty or unknown values", () => {
+    for (const value of [
+      null,
+      undefined,
+      "",
+      "   ",
+      "rocket-ship-9000",
+      "lucide:",
+      "lucide:rocket-ship-9000",
+      "fa:",
+      "fa:rocket-ship-9000",
+      "fa:Dog",
+      "mystery:dog",
+      "emoji:",
+      "emoji:<b>",
+      "emoji:a b",
+      "emoji:123456789",
+    ]) {
+      expect(resolveIcon(value), String(value)).toBe(FALLBACK_ICON);
+    }
+    expect(FALLBACK_ICON).toEqual({ kind: "fallback", key: null });
+  });
+});
+
+function filesUnder(dir: string): string[] {
+  return readdirSync(dir).flatMap((entry) => {
+    const path = join(dir, entry);
+    return statSync(path).isDirectory() ? filesUnder(path) : [path];
+  });
+}
+
+describe("offline bundling", () => {
+  const registryFiles = [SOURCE_PATH, join(REPO_ROOT, "tools", "icons", "generate.mjs"), ...OUTPUT_PATHS];
+
+  it("the registry has no remote URL, CDN reference or data-lucide runtime", () => {
+    for (const path of registryFiles) {
+      const text = readFileSync(path, "utf8");
+      expect(text, path).not.toMatch(/https?:\/\//i);
+      expect(text, path).not.toMatch(/\/\/[a-z0-9.-]+\.[a-z]{2,}\//i);
+      expect(text, path).not.toMatch(/\bcdn\b|jsdelivr|unpkg|cdnjs|kit\.fontawesome/i);
+      expect(text, path).not.toContain("data-lucide");
+      expect(text, path).not.toMatch(/\bfetch\s*\(/);
+    }
+  });
+
+  it("no bundled source imports an icon package — only the curated generated data ships", () => {
+    const sources = [join(REPO_ROOT, "admin", "src"), join(REPO_ROOT, "frontend", "src")]
+      .flatMap(filesUnder)
+      .filter((path) => /\.(ts|tsx)$/.test(path) && !path.endsWith(".test.ts") && !path.endsWith(".test.tsx"));
+    expect(sources.length).toBeGreaterThan(0);
+    for (const path of sources) {
+      const text = readFileSync(path, "utf8");
+      expect(text, path).not.toMatch(/from\s+["'](lucide|lucide-react|lucide-static|@fortawesome\/[^"']+)["']/);
+    }
+  });
+});

admin/src/index.css

@@ -0,0 +1,76 @@
+/* NestQuest Admin — global tokens + base.
+   Plain CubeCraft styling, mobile-first, 390x844 reference
+   (design/ADMIN-SPEC.md). Values mirror design/tokens/nestquest-admin-tokens.css,
+   re-scoped to :root for the standalone PWA. */
+
+:root {
+  --nq-brand-blue: #3b3ab8;
+  --nq-brand-purple: #a035cc;
+  --nq-brand-gradient: linear-gradient(135deg, var(--nq-brand-blue), var(--nq-brand-purple));
+  --nq-brand-gradient-h: linear-gradient(90deg, var(--nq-brand-blue), var(--nq-brand-purple));
+
+  --nq-a-page: #f4f4f6;
+  --nq-a-surface: #ffffff;
+  --nq-a-selected: #ebebf8;
+  --nq-a-border: #e4e4ea;
+  --nq-a-divider: #ededf1;
+
+  --nq-a-ink: #18181d;
+  --nq-a-ink-secondary: #52525e;
+  --nq-a-ink-tertiary: #70707e;
+
+  --nq-a-success: #15803d;
+  --nq-a-danger: #dc2626;
+  --nq-a-danger-strong: #b91c1c;
+  --nq-a-danger-bg: #fee2e2;
+  --nq-a-warning-ink: #92400e;
+  --nq-a-warning-ink-2: #78350f;
+  --nq-a-warning-bg: #fef3c7;
+  --nq-a-warning-border: rgba(217, 119, 6, 0.35);
+  --nq-a-info-bg: #dbeafe;
+  --nq-a-info-ink: #1e3a8a;
+  --nq-a-info-icon: #1d4ed8;
+  --nq-a-reversal: #7d28a0;
+
+  --nq-a-font: Nunito, system-ui, sans-serif;
+  --nq-a-size-screen: 24px;
+  --nq-a-size-stat: 22px;
+  --nq-a-size-row: 13.5px;
+  --nq-a-size-meta: 11px;
+  --nq-a-size-label: 10px;
+  --nq-a-track-label: 0.1em;
+
+  --nq-a-density-gap: 10px;
+  --nq-a-density-card-pad: 13px;
+  --nq-a-density-row-pad: 11px 13px;
+  --nq-a-density-radius: 8px;
+
+  --nq-a-tabbar-height: 70px;
+  --nq-a-tap-min: 44px;
+  --nq-a-radius-pill: 9999px;
+  --nq-a-radius-sheet: 20px 20px 0 0;
+  --nq-a-sheet-shadow: 0 -8px 28px rgba(9, 9, 11, 0.18);
+  --nq-a-progress-height: 6px;
+
+  --nq-ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --nq-dur-base: 200ms;
+  --nq-dur-modal: 350ms;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  margin: 0;
+  height: 100%;
+}
+
+body {
+  font-family: var(--nq-a-font);
+  background: var(--nq-a-page);
+  color: var(--nq-a-ink);
+  -webkit-font-smoothing: antialiased;
+}

admin/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import AppRoutes from "./AppRoutes";
+import "./index.css";
+import { registerServiceWorker } from "./pwa/register";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <AppRoutes />
+  </StrictMode>,
+);
+
+void registerServiceWorker();

admin/src/pwa/pwa.test.ts

@@ -0,0 +1,396 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  REVISION_MARKER,
+  STATIC_PRECACHE_FILES,
+  injectServiceWorker,
+} from "../../vite-sw-plugin";
+import { registerServiceWorker } from "./register";
+
+const adminRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const adminPath = (rel: string) => resolve(adminRoot, rel);
+const publicPath = (urlPath: string) => adminPath(`public${urlPath}`);
+
+interface ManifestIcon {
+  src: string;
+  sizes: string;
+  type: string;
+  purpose?: string;
+}
+
+const manifest = JSON.parse(readFileSync(publicPath("/manifest.webmanifest"), "utf8"));
+const icons: ManifestIcon[] = manifest.icons;
+const swSource = readFileSync(publicPath("/sw.js"), "utf8");
+
+const sizeOf = (icon: ManifestIcon) => Number(icon.sizes.split("x")[0]);
+const purposes = (icon: ManifestIcon) => (icon.purpose ?? "any").split(/\s+/);
+
+describe("web app manifest", () => {
+  it("meets the installability criteria", () => {
+    expect(manifest.name).toBe("NestQuest Admin");
+    expect(manifest.short_name).toBe("NestQuest");
+    expect(manifest.start_url).toBe("/");
+    expect(manifest.scope).toBe("/");
+    expect(manifest.display).toBe("standalone");
+    expect(manifest.background_color).toMatch(/^#[0-9a-f]{6}$/i);
+    expect(manifest.theme_color).toMatch(/^#[0-9a-f]{6}$/i);
+
+    const any = icons.filter((i) => purposes(i).includes("any"));
+    expect(any.some((i) => sizeOf(i) >= 192)).toBe(true);
+    expect(any.some((i) => sizeOf(i) >= 512)).toBe(true);
+    expect(icons.some((i) => purposes(i).includes("maskable"))).toBe(true);
+  });
+
+  it("uses the admin design token colours", () => {
+    const css = readFileSync(adminPath("src/index.css"), "utf8");
+    expect(css).toContain(`--nq-brand-blue: ${manifest.theme_color};`);
+    expect(css).toContain(`--nq-a-page: ${manifest.background_color};`);
+  });
+
+  it.each(icons.map((i) => [i.src, i] as const))(
+    "icon %s is a real PNG of its declared size",
+    (_src, icon) => {
+      const path = publicPath(icon.src);
+      expect(existsSync(path)).toBe(true);
+      const png = readFileSync(path);
+      expect([...png.subarray(0, 8)]).toEqual([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+      expect(png.toString("ascii", 12, 16)).toBe("IHDR");
+      const [w, h] = icon.sizes.split("x").map(Number);
+      expect(png.readUInt32BE(16)).toBe(w);
+      expect(png.readUInt32BE(20)).toBe(h);
+      expect(icon.type).toBe("image/png");
+    },
+  );
+});
+
+describe("index.html and entry point", () => {
+  const html = readFileSync(adminPath("index.html"), "utf8");
+
+  it("links the manifest, theme colour and apple touch icon", () => {
+    expect(html).toContain('<link rel="manifest" href="/manifest.webmanifest" />');
+    expect(html).toContain(`<meta name="theme-color" content="${manifest.theme_color}" />`);
+    expect(html).toContain('<link rel="apple-touch-icon" href="/icons/icon-192.png" />');
+  });
+
+  it("main.tsx registers the service worker", () => {
+    const main = readFileSync(adminPath("src/main.tsx"), "utf8");
+    expect(main).toMatch(/import \{ registerServiceWorker \} from "\.\/pwa\/register"/);
+    expect(main).toMatch(/registerServiceWorker\(\)/);
+  });
+});
+
+// Minimal service-worker global scope: runs public/sw.js against in-memory
+// caches and a stubbed network, so handler behaviour is checked without I/O.
+function loadServiceWorker(
+  network: (url: string) => Promise<FakeResponse>,
+  source: string = swSource,
+) {
+  const listeners: Record<string, (event: any) => void> = {};
+  const stores = new Map<string, Map<string, FakeResponse>>();
+  const openStore = (name: string) => {
+    if (!stores.has(name)) stores.set(name, new Map());
+    return stores.get(name)!;
+  };
+  const keyOf = (req: string | { url: string }) =>
+    new URL(typeof req === "string" ? req : req.url, "https://admin.test").href;
+  const fetchFn = vi.fn((req: string | { url: string }) => network(keyOf(req)));
+
+  const caches = {
+    open: async (name: string) => {
+      const store = openStore(name);
+      return {
+        addAll: async (urls: string[]) => {
+          for (const u of urls) store.set(keyOf(u), await network(keyOf(u)));
+        },
+        put: async (req: { url: string }, res: FakeResponse) => void store.set(keyOf(req), res),
+      };
+    },
+    keys: async () => [...stores.keys()],
+    delete: async (name: string) => stores.delete(name),
+    match: async (req: string | { url: string }, opts?: { cacheName?: string }) => {
+      const names = opts?.cacheName ? [opts.cacheName] : [...stores.keys()];
+      for (const n of names) {
+        const hit = stores.get(n)?.get(keyOf(req));
+        if (hit) return hit;
+      }
+      return undefined;
+    },
+  };
+  const self = {
+    location: new URL("https://admin.test/"),
+    addEventListener: (type: string, fn: (event: any) => void) => (listeners[type] = fn),
+    skipWaiting: vi.fn(async () => undefined),
+    clients: { claim: vi.fn(async () => undefined) },
+  };
+  const ResponseStub = { error: () => new FakeResponse("", false, "error") };
+  new Function("self", "caches", "fetch", "Response", source)(self, caches, fetchFn, ResponseStub);
+
+  const dispatch = async (type: string, init: object = {}) => {
+    let pending: Promise<unknown> | undefined;
+    const event = {
+      ...init,
+      waitUntil: (p: Promise<unknown>) => (pending = p),
+      respondWith: (p: Promise<unknown>) => (pending = p),
+    };
+    listeners[type](event);
+    return { responded: pending !== undefined, result: await pending };
+  };
+  return { listeners, stores, self, fetchFn, dispatch, openStore };
+}
+
+class FakeResponse {
+  constructor(
+    readonly body: string,
+    readonly ok = true,
+    readonly type = "basic",
+  ) {}
+  clone() {
+    return new FakeResponse(this.body, this.ok, this.type);
+  }
+}
+
+const request = (url: string, extra: object = {}) => ({
+  url: new URL(url, "https://admin.test").href,
+  method: "GET",
+  mode: "cors",
+  destination: "",
+  ...extra,
+});
+
+describe("service worker (public/sw.js)", () => {
+  it("is a static asset served from the site root", () => {
+    expect(existsSync(publicPath("/sw.js"))).toBe(true);
+    expect(swSource).toMatch(/const SHELL_CACHE = /);
+    expect(swSource).toMatch(/addEventListener\("install"/);
+    expect(swSource).toMatch(/addEventListener\("activate"/);
+    expect(swSource).toMatch(/addEventListener\("fetch"/);
+  });
+
+  it("precaches the shell on install, prunes stale caches on activate", async () => {
+    const sw = loadServiceWorker(async (url) => new FakeResponse(`net:${url}`));
+    sw.openStore("nestquest-admin-shell-v0");
+
+    await sw.dispatch("install");
+    expect(sw.self.skipWaiting).toHaveBeenCalled();
+    const precached = [...sw.stores.values()].flatMap((s) => [...s.keys()]);
+    for (const path of ["/", "/index.html", "/manifest.webmanifest", ...icons.map((i) => i.src)]) {
+      expect(precached).toContain(`https://admin.test${path}`);
+    }
+
+    await sw.dispatch("activate");
+    expect(sw.stores.has("nestquest-admin-shell-v0")).toBe(false);
+    expect(sw.self.clients.claim).toHaveBeenCalled();
+  });
+
+  it("serves the cached shell for navigations when offline", async () => {
+    let online = true;
+    const sw = loadServiceWorker(async (url) => {
+      if (!online) throw new TypeError("Failed to fetch");
+      return new FakeResponse(`net:${url}`);
+    });
+    await sw.dispatch("install");
+    online = false;
+
+    const { result } = await sw.dispatch("fetch", {
+      request: request("/children/42", { mode: "navigate", destination: "document" }),
+    });
+    expect((result as FakeResponse).body).toBe("net:https://admin.test/index.html");
+  });
+
+  it("serves static assets cache-first and fills the runtime cache", async () => {
+    const sw = loadServiceWorker(async (url) => new FakeResponse(`net:${url}`));
+    const asset = request("/assets/index-abc123.js", { destination: "script" });
+
+    const first = await sw.dispatch("fetch", { request: asset });
+    expect((first.result as FakeResponse).body).toBe("net:https://admin.test/assets/index-abc123.js");
+    expect(sw.fetchFn).toHaveBeenCalledTimes(1);
+
+    const second = await sw.dispatch("fetch", { request: asset });
+    expect((second.result as FakeResponse).body).toBe("net:https://admin.test/assets/index-abc123.js");
+    expect(sw.fetchFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("never handles cross-origin, non-GET or non-static requests", async () => {
+    const sw = loadServiceWorker(async (url) => new FakeResponse(`net:${url}`));
+    const cases = [
+      request("https://auth.example.com/logo.png", { destination: "image" }),
+      request("/assets/app.js", { destination: "script", method: "POST" }),
+      request("/api/admin/children"),
+    ];
+    for (const req of cases) {
+      const { responded } = await sw.dispatch("fetch", { request: req });
+      expect(responded).toBe(false);
+    }
+    expect(sw.fetchFn).not.toHaveBeenCalled();
+  });
+});
+
+// A Vite-style built index.html referencing hashed bundles.
+const builtIndexHtml = (hash: string) => `<!doctype html>
+<html lang="en">
+  <head>
+    <link rel="manifest" href="/manifest.webmanifest" />
+    <link rel="apple-touch-icon" href="/icons/icon-192.png" />
+    <script type="module" crossorigin src="/assets/index-${hash}.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/vendor-${hash}.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-${hash}.css">
+    <link rel="preconnect" href="https://auth.example.com" />
+  </head>
+  <body><div id="root"></div></body>
+</html>`;
+
+// Same-origin script/link URLs of an HTML document, parsed independently of
+// the build plugin so the regression check does not trust its own extractor.
+const referencedAssets = (html: string) =>
+  [...new DOMParser().parseFromString(html, "text/html").querySelectorAll("script[src], link[href]")]
+    .map((el) => new URL(el.getAttribute("src") ?? el.getAttribute("href")!, "https://admin.test/"))
+    .filter((url) => url.origin === "https://admin.test")
+    .map((url) => url.href);
+
+// The unhashed files the build hashes into the revision, read from public/.
+const staticFiles = STATIC_PRECACHE_FILES.map((path) => ({
+  path,
+  bytes: readFileSync(publicPath(`/${path}`)),
+}));
+const revisionOf = (src: string) => /const REVISION = "([0-9a-f]+)";/.exec(src)?.[1];
+
+describe("build-time service worker injection", () => {
+  it("precaches every asset the cached index.html references on install (PWA-001)", async () => {
+    const html = builtIndexHtml("Ab12Cd34");
+    const built = injectServiceWorker(html, swSource, staticFiles);
+    const sw = loadServiceWorker(async (url) =>
+      new FakeResponse(url.endsWith("/index.html") ? html : `net:${url}`),
+    built);
+
+    await sw.dispatch("install");
+    const shell = [...sw.stores.entries()].find(([name]) => name.startsWith("nestquest-admin-shell-"));
+    expect(shell).toBeDefined();
+    const [, shellStore] = shell!;
+
+    const cachedHtml = shellStore.get("https://admin.test/index.html")!.body;
+    const assets = referencedAssets(cachedHtml);
+    expect(assets).toEqual(
+      expect.arrayContaining([
+        "https://admin.test/assets/index-Ab12Cd34.js",
+        "https://admin.test/assets/vendor-Ab12Cd34.js",
+        "https://admin.test/assets/index-Ab12Cd34.css",
+      ]),
+    );
+    for (const asset of assets) expect([...shellStore.keys()]).toContain(asset);
+    expect([...shellStore.keys()]).not.toContain("https://auth.example.com/");
+  });
+
+  it("derives a new revision for different index.html content (PWA-002)", () => {
+    const a = injectServiceWorker(builtIndexHtml("aaaa1111"), swSource, staticFiles);
+    const b = injectServiceWorker(builtIndexHtml("bbbb2222"), swSource, staticFiles);
+
+    expect(a).not.toContain(REVISION_MARKER);
+    expect(b).not.toContain(REVISION_MARKER);
+    expect(revisionOf(a)).toMatch(/^[0-9a-f]{12}$/);
+    expect(revisionOf(b)).toMatch(/^[0-9a-f]{12}$/);
+    expect(revisionOf(a)).not.toBe(revisionOf(b));
+    expect(injectServiceWorker(builtIndexHtml("aaaa1111"), swSource, staticFiles)).toBe(a);
+  });
+
+  it("derives a new revision when only a precached static file changes (PWA-002)", () => {
+    const html = builtIndexHtml("aaaa1111");
+    const base = revisionOf(injectServiceWorker(html, swSource, staticFiles));
+    const withChanged = (path: string) =>
+      staticFiles.map((f) =>
+        f.path === path ? { path, bytes: Buffer.concat([f.bytes, Buffer.from([0])]) } : f,
+      );
+
+    expect(revisionOf(injectServiceWorker(html, swSource, [...staticFiles].reverse()))).toBe(base);
+    for (const path of STATIC_PRECACHE_FILES) {
+      const changed = revisionOf(injectServiceWorker(html, swSource, withChanged(path)));
+      expect(changed, path).toMatch(/^[0-9a-f]{12}$/);
+      expect(changed, path).not.toBe(base);
+    }
+  });
+
+  it("hashes every unhashed URL sw.js precaches (PWA-002)", () => {
+    const shellUrls = [...swSource.matchAll(/^\s*"(\/[^"]*)",$/gm)].map((m) => m[1]);
+    const fixed = shellUrls.filter((url) => url !== "/" && url !== "/index.html");
+    expect(fixed.map((url) => url.slice(1)).sort()).toEqual([...STATIC_PRECACHE_FILES].sort());
+  });
+
+  it("names both caches after the build revision (PWA-002)", async () => {
+    const built = injectServiceWorker(builtIndexHtml("aaaa1111"), swSource, staticFiles);
+    const revision = /const REVISION = "([0-9a-f]+)";/.exec(built)![1];
+    const sw = loadServiceWorker(async (url) => new FakeResponse(`net:${url}`), built);
+
+    await sw.dispatch("install");
+    await sw.dispatch("fetch", { request: request("/assets/late.js", { destination: "script" }) });
+    expect([...sw.stores.keys()].sort()).toEqual([
+      `nestquest-admin-runtime-${revision}`,
+      `nestquest-admin-shell-${revision}`,
+    ]);
+  });
+
+  it("fails fast when sw.js lacks the placeholders", () => {
+    expect(() => injectServiceWorker(builtIndexHtml("x"), "const SHELL_URLS = [];", staticFiles)).toThrow();
+  });
+
+  it("activation deletes only stale nestquest-admin caches (PWA-003)", async () => {
+    const built = injectServiceWorker(builtIndexHtml("aaaa1111"), swSource, staticFiles);
+    const sw = loadServiceWorker(async (url) => new FakeResponse(`net:${url}`), built);
+    for (const name of [
+      "nestquest-admin-shell-old",
+      "nestquest-admin-runtime-old",
+      "some-other-app-cache",
+    ]) {
+      sw.openStore(name);
+    }
+
+    await sw.dispatch("install");
+    await sw.dispatch("activate");
+    const names = [...sw.stores.keys()];
+    expect(names).not.toContain("nestquest-admin-shell-old");
+    expect(names).not.toContain("nestquest-admin-runtime-old");
+    expect(names).toContain("some-other-app-cache");
+    expect(names.some((n) => n.startsWith("nestquest-admin-shell-") && n !== "nestquest-admin-shell-old")).toBe(true);
+  });
+});
+
+describe("registerServiceWorker", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  const stubServiceWorker = (register: ReturnType<typeof vi.fn>) =>
+    vi.stubGlobal("navigator", { ...navigator, serviceWorker: { register } });
+
+  it("does not register outside production builds", async () => {
+    const register = vi.fn();
+    stubServiceWorker(register);
+    expect(import.meta.env.PROD).toBe(false);
+    await registerServiceWorker();
+    expect(register).not.toHaveBeenCalled();
+  });
+
+  it("registers /sw.js in production", async () => {
+    vi.stubEnv("PROD", true);
+    const register = vi.fn().mockResolvedValue({});
+    stubServiceWorker(register);
+    await registerServiceWorker();
+    expect(register).toHaveBeenCalledWith("/sw.js", { scope: "/" });
+  });
+
+  it("logs instead of throwing when registration fails", async () => {
+    vi.stubEnv("PROD", true);
+    stubServiceWorker(vi.fn().mockRejectedValue(new Error("boom")));
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    await expect(registerServiceWorker()).resolves.toBeUndefined();
+    expect(error).toHaveBeenCalled();
+  });
+
+  it("does nothing when the browser lacks service workers", async () => {
+    vi.stubEnv("PROD", true);
+    vi.stubGlobal("navigator", {});
+    await expect(registerServiceWorker()).resolves.toBeUndefined();
+  });
+});

admin/src/pwa/register.ts

@@ -0,0 +1,13 @@
+/**
+ * Service worker registration for the installable admin PWA.
+ * Registers /sw.js only in production builds, so dev servers and tests never
+ * run a worker. Failures are logged, never thrown — the app works without it.
+ */
+export async function registerServiceWorker(): Promise<void> {
+  if (!import.meta.env.PROD || !("serviceWorker" in navigator)) return;
+  try {
+    await navigator.serviceWorker.register("/sw.js", { scope: "/" });
+  } catch (error) {
+    console.error("Service worker registration failed:", error);
+  }
+}

admin/src/schedule/OverrideEditor.css

@@ -0,0 +1,229 @@
+/* Presence override editor — roomy density pushed screen
+   (design/ADMIN-SPEC.md §6). Covers the tab bar like a pushed route. */
+
+.override-screen {
+  position: fixed;
+  inset: 0;
+  z-index: 30;
+  overflow-y: auto;
+  background: var(--nq-a-page);
+}
+
+.override-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 14px 16px;
+  background: var(--nq-a-surface);
+  border-bottom: 1px solid var(--nq-a-border);
+}
+
+.override-back {
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: var(--nq-a-tap-min);
+  height: var(--nq-a-tap-min);
+  margin: -6px 0 -6px -12px;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--nq-a-ink);
+  cursor: pointer;
+}
+
+.override-title {
+  margin: 0;
+  font-size: var(--nq-a-size-screen);
+  font-weight: 800;
+  letter-spacing: -0.02em;
+}
+
+.override-sub {
+  margin: 2px 0 0;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.override-scroll {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  width: 100%;
+  max-width: 640px;
+  margin: 0 auto;
+  padding: 16px 16px 24px;
+}
+
+/* Form card: roomy density, 18px padding, 16px gaps. */
+.override-card {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 18px;
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: 12px;
+}
+
+.override-field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-width: 0;
+}
+
+.override-label {
+  font-size: var(--nq-a-size-label);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: var(--nq-a-track-label);
+  color: var(--nq-a-ink-secondary);
+}
+
+.override-segments {
+  display: grid;
+  gap: 6px;
+}
+
+.override-segments--3 {
+  grid-template-columns: repeat(3, 1fr);
+}
+
+.override-segments--2 {
+  grid-template-columns: repeat(2, 1fr);
+}
+
+.override-segments--7 {
+  grid-template-columns: repeat(7, 1fr);
+  gap: 4px;
+}
+
+.override-segments--7 .override-segment {
+  padding: 0;
+}
+
+.override-segment {
+  min-height: var(--nq-a-tap-min);
+  padding: 0 8px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: 10px;
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink-secondary);
+  font-family: inherit;
+  font-size: 13.5px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.override-segment--gradient[aria-pressed="true"] {
+  border-color: transparent;
+  background: var(--nq-brand-gradient);
+  color: #fff;
+}
+
+.override-segment--ink[aria-pressed="true"] {
+  border-color: #18181d;
+  background: #18181d;
+  color: #fff;
+}
+
+.override-dates {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 10px;
+}
+
+.override-input {
+  width: 100%;
+  min-height: var(--nq-a-tap-min);
+  padding: 13px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: 10px;
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 14px;
+  font-weight: 600;
+}
+
+.override-date {
+  font-weight: 700;
+}
+
+/* Consequence warning */
+.override-warning {
+  display: flex;
+  gap: 10px;
+  padding: 14px;
+  border: 1px solid var(--nq-a-warning-border);
+  border-radius: 12px;
+  background: var(--nq-a-warning-bg);
+}
+
+.override-warning-glyph {
+  flex: none;
+  display: flex;
+  color: var(--nq-a-warning-ink);
+}
+
+.override-warning-headline {
+  margin: 0;
+  font-size: 13.5px;
+  font-weight: 700;
+  color: var(--nq-a-warning-ink);
+}
+
+.override-warning-body {
+  margin: 3px 0 0;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-warning-ink-2);
+}
+
+.override-error {
+  margin: 0;
+  padding: 10px 12px;
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-danger-bg);
+  color: var(--nq-a-danger-strong);
+  font-size: 12.5px;
+  font-weight: 700;
+}
+
+/* Footer: Cancel (flex 1) + Save override (flex 2), 15px vertical padding. */
+.override-footer {
+  display: flex;
+  gap: 10px;
+}
+
+.override-cancel,
+.override-save {
+  padding: 15px 12px;
+  border-radius: 12px;
+  font-family: inherit;
+  font-size: 14px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.override-cancel {
+  flex: 1;
+  border: 1px solid var(--nq-a-border);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+}
+
+.override-save {
+  flex: 2;
+  border: 0;
+  background: var(--nq-brand-gradient);
+  color: #fff;
+}
+
+.override-cancel:disabled,
+.override-save:disabled {
+  opacity: 0.45;
+  cursor: default;
+}

admin/src/schedule/OverrideEditor.test.tsx

@@ -0,0 +1,536 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import App from "../App";
+import ScheduleTab from "./ScheduleTab";
+import { CONSEQUENCE_DEBOUNCE_MS, isIsoDate, isValidRange } from "./OverrideEditor";
+import type { AdminChild } from "../api/definitions";
+import type { PresenceOverride, PresencePattern } from "../api/presence";
+import { storeTokens } from "../auth/oidc";
+
+function child(id: number, display_name: string, sort_order: number): AdminChild {
+  return { id, display_name, colour: null, avatar_ref: null, sort_order, is_active: true };
+}
+
+const CHILDREN = [child(1, "Declan", 1), child(2, "Maeve", 2), child(3, "Rory", 3)];
+
+const DECLAN: PresencePattern = {
+  id: 1,
+  child_id: 1,
+  name: "Home weeks",
+  kind: "home",
+  cycle_length_weeks: 2,
+  anchor_date: "2026-09-07",
+  pattern: { "0": [0, 1, 2, 3, 4, 5, 6], "1": [5, 6] },
+};
+
+const INITIAL_OVERRIDES: PresenceOverride[] = [
+  { id: 41, child_id: 1, start_date: "2026-09-10", end_date: "2026-09-12", is_present: false, note: "Dentist trip" },
+];
+
+const TODAY = "2026-09-23";
+const OVERRIDES_PATH = "/api/v1/admin/presence-overrides";
+const CONSEQUENCE_PATH = `${OVERRIDES_PATH}/consequence`;
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+interface Call {
+  method: string;
+  path: string;
+  body: unknown;
+}
+
+let overrides: PresenceOverride[];
+let consequence: (body: Record<string, unknown>) => Response | Promise<Response>;
+let createResponse: (body: Record<string, unknown>) => Response;
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function calls(): Call[] {
+  return fetchMock.mock.calls.map(([url, init]: [string, RequestInit | undefined]) => ({
+    method: init?.method ?? "GET",
+    path: new URL(String(url), "http://x").pathname,
+    body: init?.body ? JSON.parse(String(init.body)) : undefined,
+  }));
+}
+
+function consequenceBodies(): unknown[] {
+  return calls()
+    .filter((c) => c.path === CONSEQUENCE_PATH)
+    .map((c) => c.body);
+}
+
+async function routeFetch(url: string, init: RequestInit = {}): Promise<Response> {
+  const path = new URL(url, "http://x").pathname;
+  const method = init.method ?? "GET";
+  const body = init.body ? JSON.parse(String(init.body)) : undefined;
+  if (path === CONSEQUENCE_PATH && method === "POST") return consequence(body);
+  if (path === OVERRIDES_PATH && method === "POST") return createResponse(body);
+  const deleteMatch = /\/presence-overrides\/(\d+)$/.exec(path);
+  if (deleteMatch && method === "DELETE") {
+    overrides = overrides.filter((o) => o.id !== Number(deleteMatch[1]));
+    return jsonResponse({ status: "ok" });
+  }
+  if (path.endsWith("/admin/children")) return jsonResponse({ children: CHILDREN });
+  const patternsMatch = /\/children\/(\d+)\/presence-patterns$/.exec(path);
+  if (patternsMatch) {
+    return jsonResponse({ patterns: Number(patternsMatch[1]) === 1 ? [DECLAN] : [] });
+  }
+  if (path === OVERRIDES_PATH) return jsonResponse({ overrides });
+  return jsonResponse({ detail: "unexpected" }, 500);
+}
+
+function deferred() {
+  let resolve!: (response: Response) => void;
+  const promise = new Promise<Response>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+
+const pastDebounce = () => new Promise((r) => setTimeout(r, CONSEQUENCE_DEBOUNCE_MS + 150));
+
+function headline(): string {
+  return screen.getByTestId("override-consequence-headline").textContent ?? "";
+}
+
+function warningBody(): string {
+  return screen.getByTestId("override-consequence").querySelector(".override-warning-body")?.textContent ?? "";
+}
+
+function saveButton(): HTMLButtonElement {
+  return screen.getByRole("button", { name: "Save override" }) as HTMLButtonElement;
+}
+
+function setDate(label: "From" | "Through", value: string) {
+  fireEvent.change(screen.getByLabelText(label), { target: { value } });
+}
+
+async function openEditor() {
+  render(<ScheduleTab today={TODAY} />);
+  await screen.findByTestId("pattern-1");
+  fireEvent.click(screen.getByRole("button", { name: "Add" }));
+  await screen.findByRole("heading", { name: "Presence override" });
+}
+
+describe("OverrideEditor", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    overrides = [...INITIAL_OVERRIDES];
+    consequence = () => jsonResponse({ removed: 4 });
+    createResponse = (body) => {
+      const created: PresenceOverride = {
+        id: 50,
+        child_id: body.child_id as number,
+        start_date: body.start_date as string,
+        end_date: body.end_date as string,
+        is_present: body.is_present as boolean,
+        note: (body.note as string | undefined) ?? null,
+      };
+      overrides = [...overrides, created];
+      return jsonResponse(created, 201);
+    };
+    fetchMock = vi.fn(async (url: string, init?: RequestInit) => routeFetch(url, init));
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("renders the pushed screen per ADMIN-SPEC §6", async () => {
+    await openEditor();
+    expect(screen.getByText("Beats the custody pattern for these dates")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Back" })).toBeTruthy();
+    const kids = within(screen.getByRole("group", { name: "Child" })).getAllByRole("button");
+    expect(kids.map((b) => [b.textContent, b.getAttribute("aria-pressed")])).toEqual([
+      ["Declan", "true"],
+      ["Maeve", "false"],
+      ["Rory", "false"],
+    ]);
+    const status = within(screen.getByRole("group", { name: "Status for these dates" }));
+    expect(status.getByRole("button", { name: "Away" }).getAttribute("aria-pressed")).toBe("true");
+    expect(status.getByRole("button", { name: "Home" }).getAttribute("aria-pressed")).toBe("false");
+    expect((screen.getByLabelText("From") as HTMLInputElement).value).toBe(TODAY);
+    expect((screen.getByLabelText("Through") as HTMLInputElement).value).toBe(TODAY);
+    expect(screen.getByLabelText("Reason (optional)")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Cancel" })).toBeTruthy();
+  });
+
+  it("shows the live consequence count from the API and recounts on every change", async () => {
+    await openEditor();
+    // Save is off until the count is on screen: the warning precedes saving.
+    expect(saveButton().disabled).toBe(true);
+    await waitFor(() => expect(headline()).toBe("This removes 4 upcoming tasks"));
+    expect(consequenceBodies()).toEqual([
+      { child_id: 1, start_date: TODAY, end_date: TODAY, is_present: false },
+    ]);
+    expect(warningBody()).toBe(
+      "Declan's open tasks Sep 23 are removed while away. Completed days are untouched.",
+    );
+    expect(saveButton().disabled).toBe(false);
+
+    consequence = () => jsonResponse({ removed: 9 });
+    setDate("Through", "2026-09-27");
+    await waitFor(() => expect(headline()).toBe("This removes 9 upcoming tasks"));
+    expect(consequenceBodies()[1]).toEqual({
+      child_id: 1,
+      start_date: TODAY,
+      end_date: "2026-09-27",
+      is_present: false,
+    });
+    expect(warningBody()).toBe(
+      "Declan's open tasks Sep 23 – 27 are removed while away. Completed days are untouched.",
+    );
+
+    consequence = () => jsonResponse({ removed: 2 });
+    fireEvent.click(screen.getByRole("button", { name: "Maeve" }));
+    await waitFor(() => expect(headline()).toBe("This removes 2 upcoming tasks"));
+    expect(consequenceBodies()[2]).toEqual({
+      child_id: 2,
+      start_date: TODAY,
+      end_date: "2026-09-27",
+      is_present: false,
+    });
+    expect(warningBody()).toBe(
+      "Maeve's open tasks Sep 23 – 27 are removed while away. Completed days are untouched.",
+    );
+
+    // A Home override removes nothing by definition: no request, count 0.
+    fireEvent.click(screen.getByRole("button", { name: "Home" }));
+    expect(headline()).toBe("This removes 0 upcoming tasks");
+    expect(warningBody()).toBe(
+      "Maeve is home Sep 23 – 27, so no tasks are removed. Completed days are untouched.",
+    );
+    await pastDebounce();
+    expect(consequenceBodies()).toHaveLength(3);
+  });
+
+  it("renders the API's count verbatim — completed instances are excluded server-side", async () => {
+    // The range holds 3 open instances and 1 already completed. The API
+    // excludes the completed one (D-005; proven by
+    // tests/test_api_admin_presence_consequence.py::test_completed_instance_in_range_is_not_counted
+    // and ::test_count_matches_a_direct_materialise_comparison), so it answers 3,
+    // and the editor shows exactly that — it never counts days on its own.
+    consequence = () => jsonResponse({ removed: 3 });
+    await openEditor();
+    setDate("Through", "2026-09-25");
+    await waitFor(() => expect(headline()).toBe("This removes 3 upcoming tasks"));
+    expect(warningBody()).toBe(
+      "Declan's open tasks Sep 23 – 25 are removed while away. Completed days are untouched.",
+    );
+  });
+
+  it("a stale consequence response never overwrites a newer one", async () => {
+    const first = deferred();
+    const second = deferred();
+    const pending = [first, second];
+    consequence = () => pending.shift()!.promise;
+    await openEditor();
+    await waitFor(() => expect(consequenceBodies()).toHaveLength(1));
+
+    setDate("Through", "2026-09-26");
+    await waitFor(() => expect(consequenceBodies()).toHaveLength(2));
+
+    second.resolve(jsonResponse({ removed: 5 }));
+    await waitFor(() => expect(headline()).toBe("This removes 5 upcoming tasks"));
+    first.resolve(jsonResponse({ removed: 99 }));
+    await pastDebounce();
+    expect(headline()).toBe("This removes 5 upcoming tasks");
+  });
+
+  it("debounces rapid edits into one request for the final range", async () => {
+    await openEditor();
+    await waitFor(() => expect(consequenceBodies()).toHaveLength(1));
+    setDate("Through", "2026-09-24");
+    setDate("Through", "2026-09-25");
+    setDate("Through", "2026-09-26");
+    await pastDebounce();
+    expect(consequenceBodies().slice(1)).toEqual([
+      { child_id: 1, start_date: TODAY, end_date: "2026-09-26", is_present: false },
+    ]);
+  });
+
+  it("an incomplete or reversed range sends no consequence request and cannot be saved", async () => {
+    await openEditor();
+    await waitFor(() => expect(consequenceBodies()).toHaveLength(1));
+
+    setDate("Through", "");
+    expect(headline()).toBe("Choose a valid date range");
+    expect(saveButton().disabled).toBe(true);
+    await pastDebounce();
+    expect(consequenceBodies()).toHaveLength(1);
+
+    setDate("Through", "2026-09-20"); // before From
+    expect(headline()).toBe("Choose a valid date range");
+    await pastDebounce();
+    expect(consequenceBodies()).toHaveLength(1);
+    fireEvent.click(saveButton());
+    expect(calls().some((c) => c.method === "POST" && c.path === OVERRIDES_PATH)).toBe(false);
+  });
+
+  it("a malformed From date sends no consequence request and cannot be saved", async () => {
+    await openEditor();
+    await waitFor(() => expect(consequenceBodies()).toHaveLength(1));
+
+    setDate("From", "2026-02-30");
+    expect(headline()).toBe("Choose a valid date range");
+    expect(saveButton().disabled).toBe(true);
+    await pastDebounce();
+    expect(consequenceBodies()).toHaveLength(1);
+    fireEvent.click(saveButton());
+    expect(calls().some((c) => c.method === "POST" && c.path === OVERRIDES_PATH)).toBe(false);
+  });
+
+  it("Save sends the exact POST body, closes the editor and shows the new row", async () => {
+    await openEditor();
+    setDate("From", "2026-09-24");
+    setDate("Through", "2026-09-26");
+    fireEvent.change(screen.getByLabelText("Reason (optional)"), {
+      target: { value: "  Trip with grandparents " },
+    });
+    await waitFor(() => expect(saveButton().disabled).toBe(false));
+    const before = calls().length;
+    const patternsBefore = calls().filter((c) => c.path.endsWith("/presence-patterns")).length;
+
+    fireEvent.click(saveButton());
+    const row = await screen.findByTestId("override-50");
+    expect(row.textContent).toContain("Declan away · Sep 24 – 26");
+    expect(row.textContent).toContain("Trip with grandparents");
+    expect(screen.queryByRole("heading", { name: "Presence override" })).toBeNull();
+
+    const after = calls().slice(before);
+    const writes = after.filter((c) => c.method !== "GET");
+    // D-005: saving sends ONLY the create request — never a delete of an
+    // instance or an override. The API's regenerate path keeps completed
+    // instances (tests/test_materialize.py::
+    // test_regenerate_for_definition_rebuilds_horizon_and_preserves_completed).
+    expect(writes).toEqual([
+      {
+        method: "POST",
+        path: OVERRIDES_PATH,
+        body: {
+          child_id: 1,
+          start_date: "2026-09-24",
+          end_date: "2026-09-26",
+          is_present: false,
+          note: "Trip with grandparents",
+        },
+      },
+    ]);
+    expect(after.some((c) => c.method === "DELETE")).toBe(false);
+    // The overrides and the presence patterns are refetched for the grid.
+    expect(after.some((c) => c.method === "GET" && c.path === OVERRIDES_PATH)).toBe(true);
+    expect(calls().filter((c) => c.path.endsWith("/presence-patterns")).length).toBeGreaterThan(
+      patternsBefore,
+    );
+    // The grid reflects the new override.
+    expect(document.querySelector('[data-date="2026-09-25"]')?.getAttribute("data-state")).toBe(
+      "override-away",
+    );
+  });
+
+  it("omits an empty reason and saves a Home override", async () => {
+    await openEditor();
+    fireEvent.click(screen.getByRole("button", { name: "Home" }));
+    await waitFor(() => expect(saveButton().disabled).toBe(false));
+    fireEvent.click(saveButton());
+    await screen.findByTestId("override-50");
+    const post = calls().find((c) => c.method === "POST" && c.path === OVERRIDES_PATH);
+    expect(post?.body).toEqual({
+      child_id: 1,
+      start_date: TODAY,
+      end_date: TODAY,
+      is_present: true,
+    });
+  });
+
+  it("a 422 shows the API detail and keeps the form", async () => {
+    createResponse = () => jsonResponse({ detail: "overlaps an existing override" }, 422);
+    await openEditor();
+    setDate("Through", "2026-09-25");
+    fireEvent.change(screen.getByLabelText("Reason (optional)"), { target: { value: "Camp" } });
+    await waitFor(() => expect(saveButton().disabled).toBe(false));
+
+    fireEvent.click(saveButton());
+    const alert = await screen.findByTestId("override-error");
+    expect(alert.textContent).toBe("overlaps an existing override");
+    expect(screen.getByRole("heading", { name: "Presence override" })).toBeTruthy();
+    expect((screen.getByLabelText("Through") as HTMLInputElement).value).toBe("2026-09-25");
+    expect((screen.getByLabelText("Reason (optional)") as HTMLInputElement).value).toBe("Camp");
+    expect(saveButton().disabled).toBe(false);
+  });
+
+  it("Cancel and Back close the editor without writing", async () => {
+    await openEditor();
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    await screen.findByTestId("pattern-1");
+    fireEvent.click(screen.getByRole("button", { name: "Add" }));
+    fireEvent.click(await screen.findByRole("button", { name: "Back" }));
+    await screen.findByTestId("pattern-1");
+    expect(calls().some((c) => c.method === "POST" && c.path === OVERRIDES_PATH)).toBe(false);
+  });
+
+  it("Add opens the editor for the selected child", async () => {
+    render(<ScheduleTab today={TODAY} />);
+    await screen.findByTestId("pattern-1");
+    fireEvent.click(screen.getByRole("button", { name: "Maeve" }));
+    fireEvent.click(screen.getByRole("button", { name: "Add" }));
+    const kids = within(await screen.findByRole("group", { name: "Child" }));
+    expect(kids.getByRole("button", { name: "Maeve" }).getAttribute("aria-pressed")).toBe("true");
+    await waitFor(() =>
+      expect(consequenceBodies()).toEqual([
+        { child_id: 2, start_date: TODAY, end_date: TODAY, is_present: false },
+      ]),
+    );
+  });
+
+  it("the trash button deletes the override only after confirm", async () => {
+    render(<ScheduleTab today={TODAY} />);
+    const row = await screen.findByTestId("override-41");
+
+    fireEvent.click(within(row).getByRole("button", { name: "Delete override" }));
+    fireEvent.click(within(row).getByRole("button", { name: "Keep" }));
+    expect(calls().some((c) => c.method === "DELETE")).toBe(false);
+
+    fireEvent.click(within(row).getByRole("button", { name: "Delete override" }));
+    const confirm = within(row).getByRole("group", { name: "Confirm delete" });
+    fireEvent.click(within(confirm).getByRole("button", { name: "Delete" }));
+    await waitFor(() => expect(screen.queryByTestId("override-41")).toBeNull());
+    expect(calls().filter((c) => c.method === "DELETE")).toEqual([
+      { method: "DELETE", path: `${OVERRIDES_PATH}/41`, body: undefined },
+    ]);
+    expect(screen.getByText("No overrides for Declan.")).toBeTruthy();
+  });
+});
+
+describe("OverrideEditor focus", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    overrides = [...INITIAL_OVERRIDES];
+    consequence = () => jsonResponse({ removed: 4 });
+    createResponse = (body) => {
+      const created = { id: 50, note: null, ...body } as PresenceOverride;
+      overrides = [...overrides, created];
+      return jsonResponse(created, 201);
+    };
+    fetchMock = vi.fn(async (url: string, init?: RequestInit) => routeFetch(url, init));
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  function dialog(): HTMLElement {
+    return screen.getByRole("dialog", { name: "Presence override" });
+  }
+
+  function addButton(): HTMLElement {
+    return screen.getByRole("button", { name: "Add" });
+  }
+
+  it("moves focus into the editor on open", async () => {
+    await openEditor();
+    expect(document.activeElement).toBe(screen.getByRole("heading", { name: "Presence override" }));
+    expect(dialog().contains(document.activeElement)).toBe(true);
+  });
+
+  it("keeps Tab and Shift+Tab inside the editor", async () => {
+    await openEditor();
+    await waitFor(() => expect(saveButton().disabled).toBe(false));
+    const back = screen.getByRole("button", { name: "Back" });
+
+    saveButton().focus();
+    fireEvent.keyDown(saveButton(), { key: "Tab" });
+    expect(document.activeElement).toBe(back);
+
+    fireEvent.keyDown(back, { key: "Tab", shiftKey: true });
+    expect(document.activeElement).toBe(saveButton());
+
+    // From the focused heading (not in the tab order) Shift+Tab wraps to the end.
+    const title = screen.getByRole("heading", { name: "Presence override" });
+    title.focus();
+    fireEvent.keyDown(title, { key: "Tab", shiftKey: true });
+    expect(document.activeElement).toBe(saveButton());
+  });
+
+  it("makes the tab bar inert while open and restores it on close", async () => {
+    render(<App />);
+    fireEvent.click(screen.getByRole("tab", { name: "Schedule" }));
+    await screen.findByTestId("pattern-1");
+    fireEvent.click(addButton());
+    await screen.findByRole("heading", { name: "Presence override" });
+
+    const tabbar = document.querySelector(".admin-tabbar") as HTMLElement;
+    expect(tabbar.hasAttribute("inert")).toBe(true);
+    expect(tabbar.getAttribute("aria-hidden")).toBe("true");
+    expect(dialog().closest("[inert]")).toBeNull();
+
+    fireEvent.keyDown(dialog(), { key: "Escape" });
+    await screen.findByTestId("pattern-1");
+    expect(tabbar.hasAttribute("inert")).toBe(false);
+    expect(tabbar.hasAttribute("aria-hidden")).toBe(false);
+  });
+
+  it("Escape cancels without writing and returns focus to Add", async () => {
+    await openEditor();
+    fireEvent.keyDown(document.activeElement as HTMLElement, { key: "Escape" });
+    await screen.findByTestId("pattern-1");
+    expect(screen.queryByRole("dialog")).toBeNull();
+    expect(document.activeElement).toBe(addButton());
+    expect(calls().some((c) => c.method === "POST" && c.path === OVERRIDES_PATH)).toBe(false);
+  });
+
+  it("Escape does nothing while saving; focus returns to Add after the save", async () => {
+    const gate = deferred();
+    fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
+      const path = new URL(url, "http://x").pathname;
+      if (path === OVERRIDES_PATH && init?.method === "POST") await gate.promise;
+      return routeFetch(url, init);
+    });
+    await openEditor();
+    await waitFor(() => expect(saveButton().disabled).toBe(false));
+    fireEvent.click(saveButton());
+    expect(screen.getByRole("button", { name: "Saving…" })).toBeTruthy();
+
+    fireEvent.keyDown(dialog(), { key: "Escape" });
+    expect(screen.getByRole("dialog")).toBeTruthy();
+
+    gate.resolve(new Response(null));
+    await screen.findByTestId("override-50");
+    expect(screen.queryByRole("dialog")).toBeNull();
+    expect(document.activeElement).toBe(addButton());
+  });
+
+  it("Back and Cancel return focus to Add", async () => {
+    await openEditor();
+    fireEvent.click(screen.getByRole("button", { name: "Back" }));
+    await screen.findByTestId("pattern-1");
+    expect(document.activeElement).toBe(addButton());
+
+    fireEvent.click(addButton());
+    fireEvent.click(await screen.findByRole("button", { name: "Cancel" }));
+    await screen.findByTestId("pattern-1");
+    expect(document.activeElement).toBe(addButton());
+  });
+});
+
+describe("range validation", () => {
+  it("accepts only strict ISO calendar dates in order", () => {
+    expect(isIsoDate("2026-09-23")).toBe(true);
+    expect(isIsoDate("2026-02-30")).toBe(false);
+    expect(isIsoDate("2026-9-3")).toBe(false);
+    expect(isIsoDate("")).toBe(false);
+    expect(isValidRange("2026-09-23", "2026-09-23")).toBe(true);
+    expect(isValidRange("2026-09-23", "2026-09-22")).toBe(false);
+    expect(isValidRange("2026-09-23", "")).toBe(false);
+  });
+});

admin/src/schedule/OverrideEditor.tsx

@@ -0,0 +1,353 @@
+/**
+ * Presence override editor — the pushed screen of design/ADMIN-SPEC.md §6.
+ *
+ * The consequence warning is counted by the API (POST
+ * /presence-overrides/consequence) before anything is saved; Save stays off
+ * until that count is on screen. Saving only ever sends the create request:
+ * the API never removes an instance that already has a completion event (D-005).
+ */
+import { useEffect, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from "react";
+import { ApiForbiddenError } from "../api/client";
+import { ApiRequestError, type AdminChild } from "../api/definitions";
+import {
+  createPresenceOverride,
+  previewOverrideConsequence,
+  type PresenceOverride,
+  type PresenceOverrideBody,
+} from "../api/presence";
+import { dayNumber, isoFromDayNumber } from "./cycle";
+import { dateRange } from "./format";
+import { AlertCircleGlyph, ChevronLeftGlyph } from "./glyphs";
+import "./OverrideEditor.css";
+
+/** How long the form must sit still before the consequence is recounted. */
+export const CONSEQUENCE_DEBOUNCE_MS = 300;
+
+/** Strict "YYYY-MM-DD" naming a real calendar day (no 2026-02-30). */
+export function isIsoDate(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  return isoFromDayNumber(dayNumber(value)) === value;
+}
+
+export function isValidRange(start: string, end: string): boolean {
+  return isIsoDate(start) && isIsoDate(end) && start <= end;
+}
+
+type Consequence =
+  | { kind: "invalid" }
+  | { kind: "counting" }
+  | { kind: "ready"; removed: number }
+  | { kind: "error"; message: string };
+
+export function errorMessage(error: unknown, fallback: string): string {
+  if (error instanceof ApiForbiddenError) return error.message;
+  if (error instanceof ApiRequestError && error.detail) return error.detail;
+  return fallback;
+}
+
+export const FOCUSABLE =
+  'button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [href], [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Make everything outside `root` inert (siblings of each ancestor up to
+ * <body>), so the tab bar behind the pushed screen cannot take focus.
+ * Returns the undo.
+ */
+export function inertOutside(root: HTMLElement): () => void {
+  const made: HTMLElement[] = [];
+  for (let node: HTMLElement = root; node.parentElement && node !== document.body; node = node.parentElement) {
+    for (const sibling of Array.from(node.parentElement.children)) {
+      if (sibling === node || !(sibling instanceof HTMLElement) || sibling.hasAttribute("inert")) continue;
+      sibling.setAttribute("inert", "");
+      sibling.setAttribute("aria-hidden", "true");
+      made.push(sibling);
+    }
+  }
+  return () => {
+    for (const el of made) {
+      el.removeAttribute("inert");
+      el.removeAttribute("aria-hidden");
+    }
+  };
+}
+
+/** Keep Tab / Shift+Tab cycling inside `root` (a pushed modal screen). */
+export function trapTab(event: ReactKeyboardEvent<HTMLElement>, root: HTMLElement | null): void {
+  if (event.key !== "Tab" || !root) return;
+  const focusable = Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE));
+  if (focusable.length === 0) return;
+  const first = focusable[0];
+  const last = focusable[focusable.length - 1];
+  const current = document.activeElement;
+  const outside = !focusable.includes(current as HTMLElement);
+  if (event.shiftKey && (current === first || outside)) {
+    event.preventDefault();
+    last.focus();
+  } else if (!event.shiftKey && (current === last || outside)) {
+    event.preventDefault();
+    first.focus();
+  }
+}
+
+function tasksPhrase(count: number): string {
+  return `${count} upcoming ${count === 1 ? "task" : "tasks"}`;
+}
+
+export interface OverrideEditorProps {
+  /** Active children, in display order. */
+  childOptions: AdminChild[];
+  initialChildId: number;
+  /** "YYYY-MM-DD"; the date fields start here. */
+  today: string;
+  onCancel: () => void;
+  onSaved: (override: PresenceOverride) => void;
+}
+
+export default function OverrideEditor({
+  childOptions,
+  initialChildId,
+  today,
+  onCancel,
+  onSaved,
+}: OverrideEditorProps) {
+  const [childId, setChildId] = useState(initialChildId);
+  const [isPresent, setIsPresent] = useState(false);
+  const [startDate, setStartDate] = useState(today);
+  const [endDate, setEndDate] = useState(today);
+  const [note, setNote] = useState("");
+  const [consequence, setConsequence] = useState<Consequence>({ kind: "counting" });
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Every form change bumps the sequence; only the latest request may render.
+  const requestSeq = useRef(0);
+  const screenRef = useRef<HTMLDivElement>(null);
+  const titleRef = useRef<HTMLHeadingElement>(null);
+
+  // Modal focus: move in on open and keep the background out of reach. The
+  // opener hands focus back to its Add control once this screen closes.
+  useEffect(() => {
+    titleRef.current?.focus();
+    return screenRef.current ? inertOutside(screenRef.current) : undefined;
+  }, []);
+
+  function onKeyDown(event: ReactKeyboardEvent<HTMLDivElement>) {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      if (!saving) onCancel();
+      return;
+    }
+    trapTab(event, screenRef.current);
+  }
+
+  const child = childOptions.find((c) => c.id === childId) ?? childOptions[0];
+  const rangeValid = isValidRange(startDate, endDate);
+
+  useEffect(() => {
+    const seq = ++requestSeq.current;
+    if (!rangeValid) {
+      setConsequence({ kind: "invalid" });
+      return;
+    }
+    if (isPresent) {
+      // Keeping a child home removes nothing by definition.
+      setConsequence({ kind: "ready", removed: 0 });
+      return;
+    }
+    setConsequence({ kind: "counting" });
+    const timer = setTimeout(() => {
+      previewOverrideConsequence({
+        child_id: childId,
+        start_date: startDate,
+        end_date: endDate,
+        is_present: false,
+      })
+        .then((removed) => {
+          if (seq === requestSeq.current) setConsequence({ kind: "ready", removed });
+        })
+        .catch((err: unknown) => {
+          if (seq !== requestSeq.current) return;
+          setConsequence({
+            kind: "error",
+            message: errorMessage(err, "The upcoming tasks could not be counted. Try again."),
+          });
+        });
+    }, CONSEQUENCE_DEBOUNCE_MS);
+    return () => clearTimeout(timer);
+  }, [childId, startDate, endDate, isPresent, rangeValid]);
+
+  const canSave = rangeValid && consequence.kind === "ready" && !saving;
+
+  function save() {
+    if (!canSave) return;
+    const body: PresenceOverrideBody = {
+      child_id: childId,
+      start_date: startDate,
+      end_date: endDate,
+      is_present: isPresent,
+    };
+    const reason = note.trim();
+    if (reason) body.note = reason;
+    setSaving(true);
+    setError(null);
+    createPresenceOverride(body)
+      .then(onSaved)
+      .catch((err: unknown) => {
+        setError(errorMessage(err, "The override could not be saved. Check your connection and try again."));
+        setSaving(false);
+      });
+  }
+
+  let headline: string;
+  let detail: string;
+  const range = rangeValid ? dateRange(startDate, endDate) : "";
+  if (consequence.kind === "invalid") {
+    headline = "Choose a valid date range";
+    detail = "Through must be on or after From.";
+  } else if (consequence.kind === "counting") {
+    headline = "Counting upcoming tasks…";
+    detail = `${child.display_name} away ${range}. Completed days are untouched.`;
+  } else if (consequence.kind === "error") {
+    headline = "Upcoming tasks not counted";
+    detail = consequence.message;
+  } else {
+    headline = `This removes ${tasksPhrase(consequence.removed)}`;
+    detail = isPresent
+      ? `${child.display_name} is home ${range}, so no tasks are removed. Completed days are untouched.`
+      : `${child.display_name}'s open tasks ${range} are removed while away. Completed days are untouched.`;
+  }
+
+  return (
+    <div
+      ref={screenRef}
+      className="override-screen"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="override-title"
+      onKeyDown={onKeyDown}
+    >
+      <header className="override-header">
+        <button type="button" className="override-back" aria-label="Back" onClick={onCancel}>
+          <ChevronLeftGlyph size={20} />
+        </button>
+        <div>
+          <h2 className="override-title" id="override-title" ref={titleRef} tabIndex={-1}>
+            Presence override
+          </h2>
+          <p className="override-sub">Beats the custody pattern for these dates</p>
+        </div>
+      </header>
+
+      <div className="override-scroll">
+        <section className="override-card" aria-label="Override details">
+          <div className="override-field">
+            <span className="override-label" id="override-label-child">
+              Child
+            </span>
+            <div className="override-segments override-segments--3" role="group" aria-labelledby="override-label-child">
+              {childOptions.map((c) => (
+                <button
+                  key={c.id}
+                  type="button"
+                  className="override-segment override-segment--gradient"
+                  aria-pressed={c.id === childId}
+                  onClick={() => setChildId(c.id)}
+                >
+                  {c.display_name}
+                </button>
+              ))}
+            </div>
+          </div>
+
+          <div className="override-field">
+            <span className="override-label" id="override-label-status">
+              Status for these dates
+            </span>
+            <div className="override-segments override-segments--2" role="group" aria-labelledby="override-label-status">
+              <button
+                type="button"
+                className="override-segment override-segment--ink"
+                aria-pressed={!isPresent}
+                onClick={() => setIsPresent(false)}
+              >
+                Away
+              </button>
+              <button
+                type="button"
+                className="override-segment override-segment--ink"
+                aria-pressed={isPresent}
+                onClick={() => setIsPresent(true)}
+              >
+                Home
+              </button>
+            </div>
+          </div>
+
+          <div className="override-dates">
+            <label className="override-field">
+              <span className="override-label">From</span>
+              <input
+                className="override-input override-date"
+                type="date"
+                value={startDate}
+                onChange={(event) => setStartDate(event.target.value)}
+              />
+            </label>
+            <label className="override-field">
+              <span className="override-label">Through</span>
+              <input
+                className="override-input override-date"
+                type="date"
+                value={endDate}
+                min={isIsoDate(startDate) ? startDate : undefined}
+                onChange={(event) => setEndDate(event.target.value)}
+              />
+            </label>
+          </div>
+
+          <label className="override-field">
+            <span className="override-label">Reason (optional)</span>
+            <input
+              className="override-input"
+              type="text"
+              value={note}
+              onChange={(event) => setNote(event.target.value)}
+            />
+          </label>
+        </section>
+
+        <section
+          className="override-warning"
+          aria-label="Consequence"
+          aria-live="polite"
+          data-testid="override-consequence"
+          data-state={consequence.kind}
+        >
+          <span className="override-warning-glyph">
+            <AlertCircleGlyph />
+          </span>
+          <div>
+            <p className="override-warning-headline" data-testid="override-consequence-headline">
+              {headline}
+            </p>
+            <p className="override-warning-body">{detail}</p>
+          </div>
+        </section>
+
+        {error ? (
+          <p className="override-error" role="alert" data-testid="override-error">
+            {error}
+          </p>
+        ) : null}
+
+        <div className="override-footer">
+          <button type="button" className="override-cancel" onClick={onCancel} disabled={saving}>
+            Cancel
+          </button>
+          <button type="button" className="override-save" onClick={save} disabled={!canSave}>
+            {saving ? "Saving…" : "Save override"}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

admin/src/schedule/PatternEditor.tsx

@@ -0,0 +1,255 @@
+/**
+ * Presence pattern editor — a pushed screen like the override editor.
+ *
+ * Adds a pattern to the child's collection (POST) or edits one in place
+ * (PATCH with only the changed fields). The weekday numbering sent to the
+ * API stays Monday=0 .. Sunday=6; only the display is Sunday-first.
+ */
+import { useEffect, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from "react";
+import type { AdminChild } from "../api/definitions";
+import {
+  createPresencePattern,
+  updatePresencePattern,
+  type PatternKind,
+  type PatternWeeks,
+  type PresencePattern,
+  type PresencePatternBody,
+} from "../api/presence";
+import {
+  DISPLAY_WEEKDAYS,
+  WEEKDAY_SHORT,
+  dayNumber,
+  emptyPattern,
+  isoFromDayNumber,
+  resizePattern,
+  togglePatternDay,
+} from "./cycle";
+import { anchorLabel, shortDate } from "./format";
+import { ChevronLeftGlyph } from "./glyphs";
+import { errorMessage, inertOutside, isIsoDate, trapTab } from "./OverrideEditor";
+import "./OverrideEditor.css";
+
+export const CYCLE_LENGTH_CHOICES = [1, 2, 3, 4];
+
+const WEEKDAY_NAMES = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+
+/** The fields of `next` that differ from the stored pattern. */
+export function changedFields(
+  stored: PresencePatternBody,
+  next: PresencePatternBody,
+): Partial<PresencePatternBody> {
+  const changes: Partial<PresencePatternBody> = {};
+  if (next.name !== stored.name) changes.name = next.name;
+  if (next.kind !== stored.kind) changes.kind = next.kind;
+  if (next.cycle_length_weeks !== stored.cycle_length_weeks) {
+    changes.cycle_length_weeks = next.cycle_length_weeks;
+  }
+  if (next.anchor_date !== stored.anchor_date) changes.anchor_date = next.anchor_date;
+  const samePattern = Array.from({ length: next.cycle_length_weeks }, (_, week) => week).every(
+    (week) =>
+      JSON.stringify([...(stored.pattern[week] ?? [])].sort()) ===
+      JSON.stringify([...(next.pattern[week] ?? [])].sort()),
+  );
+  if (!samePattern || changes.cycle_length_weeks !== undefined) changes.pattern = next.pattern;
+  return changes;
+}
+
+export interface PatternEditorProps {
+  child: AdminChild;
+  /** The pattern being edited, or null to add a new one. */
+  pattern: PresencePattern | null;
+  /** "YYYY-MM-DD"; a new pattern's anchor starts here. */
+  today: string;
+  onCancel: () => void;
+  onSaved: (pattern: PresencePattern) => void;
+}
+
+export default function PatternEditor({ child, pattern, today, onCancel, onSaved }: PatternEditorProps) {
+  const [name, setName] = useState(pattern?.name ?? "");
+  const [kind, setKind] = useState<PatternKind>(pattern?.kind ?? "away");
+  const [cycleLength, setCycleLength] = useState(pattern?.cycle_length_weeks ?? 1);
+  const [anchor, setAnchor] = useState(pattern?.anchor_date ?? today);
+  const [weeks, setWeeks] = useState<PatternWeeks>(pattern?.pattern ?? emptyPattern(1));
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const screenRef = useRef<HTMLDivElement>(null);
+  const titleRef = useRef<HTMLHeadingElement>(null);
+
+  useEffect(() => {
+    titleRef.current?.focus();
+    return screenRef.current ? inertOutside(screenRef.current) : undefined;
+  }, []);
+
+  function onKeyDown(event: ReactKeyboardEvent<HTMLDivElement>) {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      if (!saving) onCancel();
+      return;
+    }
+    trapTab(event, screenRef.current);
+  }
+
+  const body: PresencePatternBody = {
+    name: name.trim(),
+    kind,
+    cycle_length_weeks: cycleLength,
+    anchor_date: anchor,
+    pattern: resizePattern(weeks, cycleLength),
+  };
+  const changes = pattern ? changedFields(pattern, body) : body;
+  // A pattern covering no day is valid (e.g. a migrated all-absent home schedule).
+  const canSave = body.name !== "" && isIsoDate(anchor) && Object.keys(changes).length > 0 && !saving;
+
+  function save() {
+    if (!canSave) return;
+    setSaving(true);
+    setError(null);
+    const request = pattern
+      ? updatePresencePattern(pattern.id, changes)
+      : createPresencePattern(child.id, body);
+    request.then(onSaved).catch((err: unknown) => {
+      setError(errorMessage(err, "The pattern could not be saved. Check your connection and try again."));
+      setSaving(false);
+    });
+  }
+
+  const title = pattern ? "Edit pattern" : "New pattern";
+  return (
+    <div
+      ref={screenRef}
+      className="override-screen"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="pattern-title"
+      onKeyDown={onKeyDown}
+    >
+      <header className="override-header">
+        <button type="button" className="override-back" aria-label="Back" onClick={onCancel}>
+          <ChevronLeftGlyph size={20} />
+        </button>
+        <div>
+          <h2 className="override-title" id="pattern-title" ref={titleRef} tabIndex={-1}>
+            {title}
+          </h2>
+          <p className="override-sub">Repeating presence for {child.display_name}</p>
+        </div>
+      </header>
+
+      <div className="override-scroll">
+        <section className="override-card" aria-label="Pattern details">
+          <label className="override-field">
+            <span className="override-label">Name</span>
+            <input
+              className="override-input"
+              type="text"
+              value={name}
+              onChange={(event) => setName(event.target.value)}
+            />
+          </label>
+
+          <div className="override-field">
+            <span className="override-label" id="pattern-label-kind">
+              Covered days are
+            </span>
+            <div className="override-segments override-segments--2" role="group" aria-labelledby="pattern-label-kind">
+              {(["away", "home"] as PatternKind[]).map((value) => (
+                <button
+                  key={value}
+                  type="button"
+                  className="override-segment override-segment--ink"
+                  aria-pressed={kind === value}
+                  onClick={() => setKind(value)}
+                >
+                  {value === "away" ? "Away" : "Home"}
+                </button>
+              ))}
+            </div>
+          </div>
+
+          <div className="override-dates">
+            <label className="override-field">
+              <span className="override-label">Cycle length</span>
+              <select
+                className="override-input"
+                value={cycleLength}
+                onChange={(event) => {
+                  const next = Number(event.target.value);
+                  setCycleLength(next);
+                  setWeeks((current) => resizePattern(current, next));
+                }}
+              >
+                {CYCLE_LENGTH_CHOICES.map((count) => (
+                  <option key={count} value={count}>
+                    {count} {count === 1 ? "week" : "weeks"}
+                  </option>
+                ))}
+              </select>
+            </label>
+            <label className="override-field">
+              <span className="override-label">Anchor date</span>
+              <input
+                className="override-input override-date"
+                type="date"
+                value={anchor}
+                onChange={(event) => setAnchor(event.target.value)}
+              />
+            </label>
+          </div>
+
+          {Array.from({ length: cycleLength }, (_, week) => {
+            const days = body.pattern[week];
+            const from = isIsoDate(anchor)
+              ? shortDate(isoFromDayNumber(dayNumber(anchor) + week * 7))
+              : null;
+            return (
+              <div key={week} className="override-field">
+                <span className="override-label" id={`pattern-label-week-${week}`}>
+                  Week {week + 1}
+                  {from ? ` · from ${from}` : ""}
+                </span>
+                <div
+                  className="override-segments override-segments--7"
+                  role="group"
+                  aria-labelledby={`pattern-label-week-${week}`}
+                >
+                  {DISPLAY_WEEKDAYS.map((weekday) => (
+                    <button
+                      key={weekday}
+                      type="button"
+                      className="override-segment override-segment--ink"
+                      aria-pressed={days.includes(weekday)}
+                      aria-label={WEEKDAY_NAMES[weekday]}
+                      onClick={() => setWeeks((current) => togglePatternDay(current, week, weekday))}
+                    >
+                      {WEEKDAY_SHORT[weekday].slice(0, 2)}
+                    </button>
+                  ))}
+                </div>
+              </div>
+            );
+          })}
+          <p className="override-sub">
+            {isIsoDate(anchor)
+              ? `Week 1 starts ${anchorLabel(anchor)}; the cycle repeats from there.`
+              : "Choose an anchor date."}
+          </p>
+        </section>
+
+        {error ? (
+          <p className="override-error" role="alert" data-testid="pattern-error">
+            {error}
+          </p>
+        ) : null}
+
+        <div className="override-footer">
+          <button type="button" className="override-cancel" onClick={onCancel} disabled={saving}>
+            Cancel
+          </button>
+          <button type="button" className="override-save" onClick={save} disabled={!canSave}>
+            {saving ? "Saving…" : "Save pattern"}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

admin/src/schedule/ScheduleTab.css

@@ -0,0 +1,363 @@
+/* Schedule tab — compact density (design/ADMIN-SPEC.md §4). Mobile-first at
+   the 390x844 reference; on wider viewports the column is capped and centred. */
+
+.schedule-screen {
+  width: 100%;
+  max-width: 640px;
+  margin: 0 auto;
+}
+
+.schedule-header {
+  background: var(--nq-a-surface);
+  border-bottom: 1px solid var(--nq-a-border);
+  padding: 14px 16px;
+}
+
+.schedule-title {
+  margin: 0;
+  font-size: var(--nq-a-size-screen);
+  font-weight: 800;
+  letter-spacing: -0.02em;
+}
+
+.schedule-sub {
+  margin: 2px 0 0;
+  min-height: 1.4em;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+/* Scroll column: 14px 16px, bottom 92px (set inline, ADMIN-SPEC §1). */
+.schedule-scroll {
+  display: flex;
+  flex-direction: column;
+  gap: var(--nq-a-density-gap);
+  padding: 14px 16px;
+}
+
+.schedule-card {
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+}
+
+/* Child selector */
+.schedule-children {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.schedule-child-chip {
+  min-height: 32px;
+  padding: 0 12px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-radius-pill);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink-secondary);
+  font-family: inherit;
+  font-size: 12.5px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.schedule-child-chip[aria-pressed="true"] {
+  border-color: var(--nq-brand-blue);
+  background: var(--nq-a-selected);
+  color: var(--nq-brand-blue);
+}
+
+/* Month grid card */
+.schedule-month {
+  padding: var(--nq-a-density-card-pad);
+}
+
+.schedule-month-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+
+.schedule-month-label {
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.schedule-chevrons {
+  display: flex;
+  gap: 4px;
+}
+
+.schedule-chevron {
+  display: grid;
+  place-items: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: 1px solid var(--nq-a-border);
+  border-radius: 6px;
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink-secondary);
+  cursor: pointer;
+}
+
+.schedule-grid {
+  display: grid;
+  grid-template-columns: repeat(7, 1fr);
+  gap: 4px;
+}
+
+.schedule-weekday {
+  text-align: center;
+  font-size: 10px;
+  font-weight: 700;
+  color: var(--nq-a-ink-tertiary);
+}
+
+.schedule-day {
+  display: grid;
+  place-items: center;
+  aspect-ratio: 1;
+  border: 1px solid transparent;
+  border-radius: 6px;
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.schedule-day--home {
+  background: var(--nq-a-selected);
+  color: #201f7a;
+}
+
+.schedule-day--away {
+  background: var(--nq-a-page);
+  color: var(--nq-a-ink-secondary);
+}
+
+.schedule-day--override-away,
+.schedule-day--override-home {
+  background: var(--nq-a-warning-bg);
+  color: var(--nq-a-warning-ink);
+  border-color: var(--nq-a-warning-border);
+}
+
+/* An override that keeps the child home reads with a dashed border. */
+.schedule-day--override-home {
+  border-style: dashed;
+}
+
+.schedule-day--today {
+  background: var(--nq-brand-gradient);
+  border-color: transparent;
+  color: #fff;
+  font-weight: 800;
+}
+
+.schedule-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px 12px;
+  margin: 10px 0 0;
+  padding: 0;
+  list-style: none;
+}
+
+.schedule-legend-item {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 10.5px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.schedule-swatch {
+  display: inline-block;
+  width: 12px;
+  height: 12px;
+  border: 1px solid transparent;
+  border-radius: 3px;
+}
+
+.schedule-legend-note {
+  margin: 8px 0 0;
+  font-size: 10.5px;
+  font-weight: 600;
+  color: var(--nq-a-ink-tertiary);
+}
+
+.schedule-save-status {
+  margin: 8px 0 0;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-success);
+}
+
+.schedule-save-status--error {
+  color: var(--nq-a-danger-strong);
+}
+
+/* Presence patterns + overrides cards */
+.schedule-section-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.schedule-section-label {
+  margin: 6px 0 -2px;
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--nq-a-ink-secondary);
+}
+
+.schedule-text-action {
+  padding: 4px 0 0;
+  border: 0;
+  background: none;
+  color: var(--nq-brand-blue);
+  font-family: inherit;
+  font-size: 12.5px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.schedule-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.schedule-list > li + li {
+  border-top: 1px solid var(--nq-a-divider);
+}
+
+.schedule-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: var(--nq-a-tap-min);
+  padding: var(--nq-a-density-row-pad);
+}
+
+.schedule-row-glyph {
+  flex: none;
+  display: flex;
+  color: var(--nq-a-warning-ink);
+}
+
+.schedule-row-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.schedule-row-title {
+  font-size: 13px;
+  font-weight: 700;
+}
+
+.schedule-row-meta {
+  font-size: var(--nq-a-size-meta);
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.schedule-icon-action {
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: var(--nq-a-tap-min);
+  height: var(--nq-a-tap-min);
+  margin: -8px -10px -8px 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--nq-a-ink-tertiary);
+  cursor: pointer;
+}
+
+.schedule-icon-action--edit {
+  margin-right: -4px;
+}
+
+.schedule-empty {
+  padding: var(--nq-a-density-card-pad);
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+/* Loading / error */
+.schedule-status {
+  padding: 24px 13px;
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  text-align: center;
+  font-size: 13.5px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.schedule-status--error {
+  color: var(--nq-a-danger-strong);
+}
+
+.schedule-status--error p {
+  margin: 0 0 10px;
+}
+
+.schedule-retry {
+  padding: 8px 16px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 13px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+/* Inline delete confirmation in an override row */
+.schedule-confirm {
+  flex: none;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.schedule-confirm-text {
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--nq-a-ink-secondary);
+}
+
+.schedule-confirm-keep,
+.schedule-confirm-delete {
+  min-height: 32px;
+  padding: 0 10px;
+  border-radius: 6px;
+  font-family: inherit;
+  font-size: 12px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.schedule-confirm-keep {
+  border: 1px solid var(--nq-a-border);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+}
+
+.schedule-confirm-delete {
+  border: 0;
+  background: var(--nq-a-danger);
+  color: #fff;
+}

admin/src/schedule/ScheduleTab.test.tsx

@@ -0,0 +1,657 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import ScheduleTab from "./ScheduleTab";
+import type { AdminChild } from "../api/definitions";
+import type { PresenceOverride, PresencePattern } from "../api/presence";
+import { storeTokens } from "../auth/oidc";
+import { cycleWeekIndex, monthDates, weekdayOf } from "./cycle";
+
+function child(id: number, display_name: string, sort_order: number, is_active = true): AdminChild {
+  return { id, display_name, colour: null, avatar_ref: null, sort_order, is_active };
+}
+
+const CHILDREN = [
+  child(3, "Rory", 3),
+  child(1, "Declan", 1),
+  child(2, "Maeve", 2),
+  child(9, "Former", 4, false),
+];
+
+// Declan: the migrated single schedule — one `home` pattern anchored Monday
+// 2026-09-07; cycle week 0 home every day, week 1 Sat/Sun only. Keys arrive
+// as JSON strings, exactly as the API serializes them.
+const DECLAN_HOME: PresencePattern = {
+  id: 1,
+  child_id: 1,
+  name: "Home weeks",
+  kind: "home",
+  cycle_length_weeks: 2,
+  anchor_date: "2026-09-07",
+  pattern: { "0": [0, 1, 2, 3, 4, 5, 6], "1": [5, 6] },
+};
+
+// Maeve: the owner scenario — away Thursday+Friday every week, and away
+// weekends every 2 weeks (the "on" week is cycle week 0 from Sep 7).
+const MAEVE_THU_FRI: PresencePattern = {
+  id: 2,
+  child_id: 2,
+  name: "Thursday+Friday",
+  kind: "away",
+  cycle_length_weeks: 1,
+  anchor_date: "2026-09-07",
+  pattern: { "0": [3, 4] },
+};
+
+const MAEVE_WEEKENDS: PresencePattern = {
+  id: 3,
+  child_id: 2,
+  name: "Alternate weekends",
+  kind: "away",
+  cycle_length_weeks: 2,
+  anchor_date: "2026-09-07",
+  pattern: { "0": [5, 6], "1": [] },
+};
+
+const OVERRIDES: PresenceOverride[] = [
+  { id: 41, child_id: 1, start_date: "2026-09-10", end_date: "2026-09-12", is_present: false, note: "Dentist trip" },
+  { id: 42, child_id: 1, start_date: "2026-09-16", end_date: "2026-09-16", is_present: true, note: null },
+  { id: 43, child_id: 2, start_date: "2026-09-28", end_date: "2026-10-02", is_present: false, note: "Camp" },
+];
+
+const TODAY = "2026-09-23";
+const PATTERNS_PATH = "/api/v1/admin/presence-patterns";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+interface Call {
+  method: string;
+  path: string;
+  body: unknown;
+}
+
+/** The server's pattern store; POST/PATCH/DELETE mutate it like the API. */
+let patterns: Record<number, PresencePattern[]>;
+let nextId: number;
+let writeFailure: Response | null;
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function calls(): Call[] {
+  return fetchMock.mock.calls.map((args: unknown[]) => {
+    const [url, init] = args as [string, RequestInit | undefined];
+    return {
+      method: init?.method ?? "GET",
+      path: new URL(String(url), "http://x").pathname,
+      body: init?.body ? JSON.parse(String(init.body)) : undefined,
+    };
+  });
+}
+
+function writes(): Call[] {
+  return calls().filter((c) => c.method !== "GET");
+}
+
+function findPattern(id: number): PresencePattern | undefined {
+  return Object.values(patterns)
+    .flat()
+    .find((p) => p.id === id);
+}
+
+function routeFetch(url: string, init: RequestInit = {}): Response {
+  const path = new URL(url, "http://x").pathname;
+  const method = init.method ?? "GET";
+  const body = init.body ? JSON.parse(String(init.body)) : undefined;
+  if (method !== "GET" && writeFailure) return writeFailure;
+  if (path.endsWith("/admin/children")) return jsonResponse({ children: CHILDREN });
+  const collection = /\/children\/(\d+)\/presence-patterns$/.exec(path);
+  if (collection) {
+    const childId = Number(collection[1]);
+    if (method === "POST") {
+      const stored: PresencePattern = { id: nextId++, child_id: childId, ...body };
+      patterns[childId] = [...(patterns[childId] ?? []), stored];
+      return jsonResponse(stored, 201);
+    }
+    return jsonResponse({ patterns: patterns[childId] ?? [] });
+  }
+  const single = /\/presence-patterns\/(\d+)$/.exec(path);
+  if (single) {
+    const id = Number(single[1]);
+    const existing = findPattern(id);
+    if (!existing) return jsonResponse({ detail: "Presence pattern not found" }, 404);
+    if (method === "PATCH") {
+      const updated = { ...existing, ...body };
+      patterns[existing.child_id] = patterns[existing.child_id].map((p) => (p.id === id ? updated : p));
+      return jsonResponse(updated);
+    }
+    if (method === "DELETE") {
+      patterns[existing.child_id] = patterns[existing.child_id].filter((p) => p.id !== id);
+      return jsonResponse({ status: "ok" });
+    }
+  }
+  if (path.endsWith("/presence-overrides")) return jsonResponse({ overrides: OVERRIDES });
+  return jsonResponse({ detail: "unexpected" }, 500);
+}
+
+function day(date: string): HTMLElement {
+  const cell = document.querySelector<HTMLElement>(`[data-date="${date}"]`);
+  if (!cell) throw new Error(`no cell for ${date}`);
+  return cell;
+}
+
+function saveButton(): HTMLButtonElement {
+  return screen.getByRole("button", { name: "Save pattern" }) as HTMLButtonElement;
+}
+
+function weekGroup(week: number): HTMLElement {
+  return screen.getByRole("group", { name: new RegExp(`^Week ${week}\\b`) });
+}
+
+async function renderReady() {
+  render(<ScheduleTab today={TODAY} />);
+  await screen.findByTestId("pattern-1");
+}
+
+async function selectMaeve() {
+  await renderReady();
+  fireEvent.click(screen.getByRole("button", { name: "Maeve" }));
+  await screen.findByTestId("pattern-3");
+}
+
+describe("ScheduleTab", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    patterns = { 1: [DECLAN_HOME], 2: [MAEVE_THU_FRI, MAEVE_WEEKENDS], 3: [] };
+    nextId = 50;
+    writeFailure = null;
+    fetchMock = vi.fn(async (url: string, init?: RequestInit) => routeFetch(url, init));
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("loads active children, their patterns and the overrides", async () => {
+    await renderReady();
+    const urls = calls().map((c) => c.path);
+    expect(urls).toContain("/api/v1/admin/children");
+    expect(urls).toContain("/api/v1/admin/children/1/presence-patterns");
+    expect(urls).toContain("/api/v1/admin/children/2/presence-patterns");
+    expect(urls).toContain("/api/v1/admin/children/3/presence-patterns");
+    expect(urls).not.toContain("/api/v1/admin/children/9/presence-patterns");
+    expect(urls).toContain("/api/v1/admin/presence-overrides");
+    const chips = within(screen.getByRole("group", { name: "Child" })).getAllByRole("button");
+    expect(chips.map((chip) => chip.textContent)).toEqual(["Declan", "Maeve", "Rory"]);
+    expect(chips[0].getAttribute("aria-pressed")).toBe("true");
+  });
+
+  it("header names the child and how many patterns it has", async () => {
+    await renderReady();
+    expect(screen.getByRole("heading", { name: "Schedule" })).toBeTruthy();
+    expect(screen.getByText("Declan · 1 pattern")).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "Maeve" }));
+    expect(screen.getByText("Maeve · 2 patterns")).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "Rory" }));
+    expect(screen.getByText("Rory · no patterns, home every day")).toBeTruthy();
+  });
+
+  it("a home-pattern-only child is away on days no home pattern covers", async () => {
+    await renderReady();
+    expect(screen.getByTestId("month-label").textContent).toBe("September 2026");
+    const states: Record<string, string> = {
+      "2026-09-01": "away", // before the anchor: cycle week 1, Tuesday
+      "2026-09-05": "home", // before the anchor: cycle week 1, Saturday
+      "2026-09-07": "home", // anchor: week 0
+      "2026-09-11": "override-away",
+      "2026-09-15": "away", // week 1, Tuesday
+      "2026-09-16": "override-home",
+      "2026-09-19": "home", // week 1, Saturday
+      "2026-09-22": "home", // wrap back to week 0
+      "2026-09-29": "away", // week 1 again
+    };
+    for (const [date, state] of Object.entries(states)) {
+      expect(day(date).dataset.state, date).toBe(state);
+      expect(day(date).className).toContain(`schedule-day--${state}`);
+      expect(day(date).className).not.toContain("schedule-day--today");
+    }
+    const today = day(TODAY);
+    expect(today.className).toContain("schedule-day--today");
+    expect(today.dataset.state).toBe("home");
+    expect(today.getAttribute("aria-label")).toBe("Sep 23 (today): Home");
+    // The grid is a read-out of the combined presence, not a set of toggles.
+    expect(today.tagName).toBe("SPAN");
+    // Sunday-first header; September 2026 starts on a Tuesday: two leading pads.
+    const grid = screen.getByRole("group", { name: "Month grid" });
+    expect(Array.from(grid.children, (c) => c.textContent).slice(0, 7)).toEqual([
+      "S",
+      "M",
+      "T",
+      "W",
+      "T",
+      "F",
+      "S",
+    ]);
+    expect(grid.children[7].getAttribute("data-date")).toBeNull();
+    expect(grid.children[8].getAttribute("data-date")).toBeNull();
+    expect(grid.children[9].getAttribute("data-date")).toBe("2026-09-01");
+
+    const legend = screen.getByRole("list", { name: "Legend" });
+    expect(within(legend).getAllByRole("listitem").map((li) => li.textContent)).toEqual([
+      "Home",
+      "Away",
+      "Override · away",
+      "Override · home",
+      "Today",
+    ]);
+    expect(screen.getByText(/Combined from every pattern/)).toBeTruthy();
+  });
+
+  it("the owner scenario: Thu/Fri away every week, Sat/Sun away only in the on week", async () => {
+    await selectMaeve();
+    for (const date of monthDates("2026-09-01")) {
+      if (date >= "2026-09-28") continue; // Camp override, checked below
+      const weekday = weekdayOf(date);
+      const onWeek = cycleWeekIndex("2026-09-07", date, 2) === 0;
+      const away = weekday === 3 || weekday === 4 || (weekday >= 5 && onWeek);
+      expect(day(date).dataset.state, date).toBe(away ? "away" : "home");
+    }
+    // Explicit spot checks of that rule.
+    expect(day("2026-09-03").dataset.state).toBe("away"); // Thu
+    expect(day("2026-09-04").dataset.state).toBe("away"); // Fri
+    expect(day("2026-09-05").dataset.state).toBe("home"); // Sat, off week (pre-anchor)
+    expect(day("2026-09-12").dataset.state).toBe("away"); // Sat, on week
+    expect(day("2026-09-13").dataset.state).toBe("away"); // Sun, on week
+    expect(day("2026-09-19").dataset.state).toBe("home"); // Sat, off week
+    expect(day("2026-09-20").dataset.state).toBe("home"); // Sun, off week
+    expect(day("2026-09-26").dataset.state).toBe("away"); // Sat, on week again
+    expect(day("2026-09-14").dataset.state).toBe("home"); // Mon
+    expect(day("2026-09-28").dataset.state).toBe("override-away");
+  });
+
+  it("navigates months with the chevrons", async () => {
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Next month" }));
+    expect(screen.getByTestId("month-label").textContent).toBe("October 2026");
+    // Oct 1 is day 24 from the anchor: cycle week 1, a Thursday — away.
+    expect(day("2026-10-01").dataset.state).toBe("away");
+    expect(day("2026-10-03").dataset.state).toBe("home"); // week 1, Saturday
+    expect(day("2026-10-05").dataset.state).toBe("home"); // week 0 again
+    fireEvent.click(screen.getByRole("button", { name: "Previous month" }));
+    expect(screen.getByTestId("month-label").textContent).toBe("September 2026");
+  });
+
+  it("patterns list shows each pattern's name, kind, cycle and weekday set", async () => {
+    await selectMaeve();
+    const list = screen.getByRole("list", { name: "Presence patterns" });
+    expect(within(list).getAllByRole("listitem")).toHaveLength(2);
+    const thuFri = within(list).getByTestId("pattern-2");
+    expect(within(thuFri).getByText("Thursday+Friday")).toBeTruthy();
+    expect(within(thuFri).getByText("Away · Every week")).toBeTruthy();
+    expect(within(thuFri).getByText("Thu, Fri")).toBeTruthy();
+    const weekends = within(list).getByTestId("pattern-3");
+    expect(within(weekends).getByText("Alternate weekends")).toBeTruthy();
+    expect(within(weekends).getByText("Away · Every 2 weeks")).toBeTruthy();
+    expect(within(weekends).getByText("Week 1: Sat, Sun · Week 2: No days")).toBeTruthy();
+    expect(within(weekends).getByRole("button", { name: "Edit Alternate weekends" })).toBeTruthy();
+    expect(within(weekends).getByRole("button", { name: "Delete Alternate weekends" })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "Declan" }));
+    const declan = screen.getByTestId("pattern-1");
+    expect(within(declan).getByText("Home · Every 2 weeks")).toBeTruthy();
+    expect(within(declan).getByText("Week 1: Every day · Week 2: Sat, Sun")).toBeTruthy();
+  });
+
+  it("a child with no patterns is home every day", async () => {
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Rory" }));
+    expect(screen.getByTestId("patterns-empty").textContent).toBe("No patterns for Rory — home every day.");
+    for (const date of monthDates("2026-09-01")) expect(day(date).dataset.state, date).toBe("home");
+    expect(screen.getByText("No overrides for Rory.")).toBeTruthy();
+  });
+
+  it("overrides card lists the selected child's overrides", async () => {
+    await renderReady();
+    const list = screen.getByRole("list", { name: "Overrides" });
+    expect(within(list).getAllByRole("listitem")).toHaveLength(2);
+    const away = within(list).getByTestId("override-41");
+    expect(within(away).getByText("Declan away · Sep 10 – 12")).toBeTruthy();
+    expect(within(away).getByText("Dentist trip")).toBeTruthy();
+    expect(within(away).getByRole("button", { name: "Delete override" })).toBeTruthy();
+    expect(within(list).getByText("Declan home · Sep 16")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Add" })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "Maeve" }));
+    expect(screen.getByText("Maeve away · Sep 28 – Oct 2")).toBeTruthy();
+  });
+
+  it("Add POSTs a new pattern to the child's collection and refreshes the list from the API", async () => {
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Rory" }));
+    fireEvent.click(screen.getByRole("button", { name: "Add pattern" }));
+    expect(await screen.findByRole("heading", { name: "New pattern" })).toBeTruthy();
+    // Nothing named yet.
+    expect(saveButton().disabled).toBe(true);
+
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "  Dad's weekends " } });
+    fireEvent.change(screen.getByLabelText("Cycle length"), { target: { value: "2" } });
+    fireEvent.change(screen.getByLabelText("Anchor date"), { target: { value: "2026-09-07" } });
+    // Sunday-first buttons; the body keeps Monday=0 numbering.
+    const week1 = weekGroup(1);
+    expect(within(week1).getAllByRole("button").map((b) => b.textContent)).toEqual([
+      "Su",
+      "Mo",
+      "Tu",
+      "We",
+      "Th",
+      "Fr",
+      "Sa",
+    ]);
+    fireEvent.click(within(week1).getByRole("button", { name: "Saturday" }));
+    fireEvent.click(within(week1).getByRole("button", { name: "Sunday" }));
+    expect(saveButton().disabled).toBe(false);
+
+    const before = calls().length;
+    fireEvent.click(saveButton());
+    const row = await screen.findByTestId("pattern-50");
+    expect(screen.queryByRole("heading", { name: "New pattern" })).toBeNull();
+
+    expect(writes()).toEqual([
+      {
+        method: "POST",
+        path: "/api/v1/admin/children/3/presence-patterns",
+        body: {
+          name: "Dad's weekends",
+          kind: "away",
+          cycle_length_weeks: 2,
+          anchor_date: "2026-09-07",
+          pattern: { "0": [5, 6], "1": [] },
+        },
+      },
+    ]);
+    const after = calls().slice(before);
+    expect(after.some((c) => c.method === "GET" && c.path === "/api/v1/admin/children/3/presence-patterns")).toBe(
+      true,
+    );
+    expect(within(row).getByText("Dad's weekends")).toBeTruthy();
+    expect(within(row).getByText("Away · Every 2 weeks")).toBeTruthy();
+    expect(day("2026-09-12").dataset.state).toBe("away");
+    expect(day("2026-09-19").dataset.state).toBe("home");
+    // Focus returns to the Add control of the patterns section.
+    expect(document.activeElement).toBe(screen.getByRole("button", { name: "Add pattern" }));
+  });
+
+  it("Add can save a Home pattern", async () => {
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Rory" }));
+    fireEvent.click(screen.getByRole("button", { name: "Add pattern" }));
+    await screen.findByRole("heading", { name: "New pattern" });
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "School nights" } });
+    fireEvent.click(screen.getByRole("button", { name: "Home" }));
+    fireEvent.click(within(weekGroup(1)).getByRole("button", { name: "Monday" }));
+    fireEvent.click(saveButton());
+    await screen.findByTestId("pattern-50");
+    expect(writes()[0].body).toEqual({
+      name: "School nights",
+      kind: "home",
+      cycle_length_weeks: 1,
+      anchor_date: TODAY,
+      pattern: { "0": [0] },
+    });
+    // A home pattern: uncovered days are now away.
+    expect(day("2026-09-14").dataset.state).toBe("home"); // Monday
+    expect(day("2026-09-15").dataset.state).toBe("away"); // Tuesday
+  });
+
+  it("Save requires a name; covered days alone are not enough", async () => {
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Rory" }));
+    fireEvent.click(screen.getByRole("button", { name: "Add pattern" }));
+    await screen.findByRole("heading", { name: "New pattern" });
+    fireEvent.click(within(weekGroup(1)).getByRole("button", { name: "Monday" }));
+    expect(saveButton().disabled).toBe(true);
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "   " } });
+    expect(saveButton().disabled).toBe(true);
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "Mondays" } });
+    expect(saveButton().disabled).toBe(false);
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "" } });
+    expect(saveButton().disabled).toBe(true);
+    fireEvent.click(saveButton());
+    expect(writes()).toEqual([]);
+  });
+
+  it("Add saves a pattern that covers no weekday and lists it", async () => {
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Rory" }));
+    fireEvent.click(screen.getByRole("button", { name: "Add pattern" }));
+    await screen.findByRole("heading", { name: "New pattern" });
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "Always away" } });
+    fireEvent.click(screen.getByRole("button", { name: "Home" }));
+    fireEvent.change(screen.getByLabelText("Cycle length"), { target: { value: "2" } });
+    expect(saveButton().disabled).toBe(false);
+    fireEvent.click(saveButton());
+    const row = await screen.findByTestId("pattern-50");
+
+    expect(writes()).toEqual([
+      {
+        method: "POST",
+        path: "/api/v1/admin/children/3/presence-patterns",
+        body: {
+          name: "Always away",
+          kind: "home",
+          cycle_length_weeks: 2,
+          anchor_date: TODAY,
+          pattern: { "0": [], "1": [] },
+        },
+      },
+    ]);
+    expect(findPattern(50)?.pattern).toEqual({ "0": [], "1": [] });
+    expect(within(row).getByText("Always away")).toBeTruthy();
+    expect(within(row).getByText("Home · Every 2 weeks")).toBeTruthy();
+    expect(within(row).getByText("Week 1: No days · Week 2: No days")).toBeTruthy();
+    // A home pattern covering no day: the child is away every day.
+    for (const date of monthDates("2026-09-01")) expect(day(date).dataset.state, date).toBe("away");
+  });
+
+  it("Edit of a migrated all-absent home pattern saves without touching any weekday", async () => {
+    const migrated: PresencePattern = {
+      id: 7,
+      child_id: 3,
+      name: "Home weeks",
+      kind: "home",
+      cycle_length_weeks: 2,
+      anchor_date: "2026-09-07",
+      pattern: { "0": [], "1": [] },
+    };
+    patterns[3] = [migrated];
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Rory" }));
+    fireEvent.click(await screen.findByRole("button", { name: "Edit Home weeks" }));
+    await screen.findByRole("heading", { name: "Edit pattern" });
+    for (const week of [1, 2]) {
+      for (const button of within(weekGroup(week)).getAllByRole("button")) {
+        expect(button.getAttribute("aria-pressed")).toBe("false");
+      }
+    }
+    // Unchanged: nothing to save.
+    expect(saveButton().disabled).toBe(true);
+
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "Never home" } });
+    expect(saveButton().disabled).toBe(false);
+    fireEvent.click(saveButton());
+    await waitFor(() => expect(screen.queryByRole("heading", { name: "Edit pattern" })).toBeNull());
+
+    expect(writes()).toEqual([{ method: "PATCH", path: `${PATTERNS_PATH}/7`, body: { name: "Never home" } }]);
+    expect(findPattern(7)).toEqual({ ...migrated, name: "Never home" });
+    const row = await screen.findByTestId("pattern-7");
+    expect(within(row).getByText("Week 1: No days · Week 2: No days")).toBeTruthy();
+  });
+
+  it("Edit PATCHes only the changed fields to /presence-patterns/{id} and refreshes", async () => {
+    await selectMaeve();
+    fireEvent.click(screen.getByRole("button", { name: "Edit Alternate weekends" }));
+    expect(await screen.findByRole("heading", { name: "Edit pattern" })).toBeTruthy();
+    expect((screen.getByLabelText("Name") as HTMLInputElement).value).toBe("Alternate weekends");
+    expect((screen.getByLabelText("Cycle length") as HTMLSelectElement).value).toBe("2");
+    expect((screen.getByLabelText("Anchor date") as HTMLInputElement).value).toBe("2026-09-07");
+    expect(within(weekGroup(1)).getByRole("button", { name: "Saturday" }).getAttribute("aria-pressed")).toBe(
+      "true",
+    );
+    // Unchanged: nothing to save.
+    expect(saveButton().disabled).toBe(true);
+
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "Every other weekend" } });
+    fireEvent.click(within(weekGroup(1)).getByRole("button", { name: "Sunday" }));
+    const before = calls().length;
+    fireEvent.click(saveButton());
+    await waitFor(() => expect(screen.queryByRole("heading", { name: "Edit pattern" })).toBeNull());
+
+    expect(writes()).toEqual([
+      {
+        method: "PATCH",
+        path: `${PATTERNS_PATH}/3`,
+        body: { name: "Every other weekend", pattern: { "0": [5], "1": [] } },
+      },
+    ]);
+    const after = calls().slice(before);
+    expect(after.some((c) => c.method === "GET" && c.path === "/api/v1/admin/children/2/presence-patterns")).toBe(
+      true,
+    );
+    const row = await screen.findByText("Every other weekend");
+    expect(within(row.closest("li")!).getByText("Week 1: Sat · Week 2: No days")).toBeTruthy();
+    expect(day("2026-09-12").dataset.state).toBe("away"); // Sat, on week
+    expect(day("2026-09-13").dataset.state).toBe("home"); // Sun no longer covered
+  });
+
+  it("Delete asks first, DELETEs /presence-patterns/{id} and refreshes the list", async () => {
+    await selectMaeve();
+    fireEvent.click(screen.getByRole("button", { name: "Delete Thursday+Friday" }));
+    const confirm = within(screen.getByTestId("pattern-2")).getByRole("group", { name: "Confirm delete" });
+    fireEvent.click(within(confirm).getByRole("button", { name: "Keep" }));
+    expect(writes()).toEqual([]);
+
+    fireEvent.click(screen.getByRole("button", { name: "Delete Thursday+Friday" }));
+    fireEvent.click(within(screen.getByTestId("pattern-2")).getByRole("button", { name: "Delete" }));
+    await waitFor(() => expect(screen.queryByTestId("pattern-2")).toBeNull());
+    expect(writes()).toEqual([{ method: "DELETE", path: `${PATTERNS_PATH}/2`, body: undefined }]);
+    expect(screen.getByTestId("pattern-3")).toBeTruthy();
+    expect(day("2026-09-17").dataset.state).toBe("home"); // Thursday, no longer away
+    expect(day("2026-09-12").dataset.state).toBe("away"); // weekends pattern still applies
+  });
+
+  it("deleting the last pattern leaves the child with none: home every day", async () => {
+    await renderReady();
+    expect(day("2026-09-15").dataset.state).toBe("away");
+    fireEvent.click(screen.getByRole("button", { name: "Delete Home weeks" }));
+    fireEvent.click(within(screen.getByTestId("pattern-1")).getByRole("button", { name: "Delete" }));
+    expect(await screen.findByTestId("patterns-empty")).toBeTruthy();
+    expect(screen.queryByRole("list", { name: "Presence patterns" })).toBeNull();
+    expect(patterns[1]).toEqual([]);
+    expect(day("2026-09-15").dataset.state).toBe("home");
+    expect(day("2026-09-11").dataset.state).toBe("override-away"); // overrides still win
+    expect(screen.getByText("Declan · no patterns, home every day")).toBeTruthy();
+  });
+
+  it("a 422 on save shows the API detail naming the field and keeps the editor open", async () => {
+    writeFailure = jsonResponse({ detail: "name must not be empty" }, 422);
+    await selectMaeve();
+    fireEvent.click(screen.getByRole("button", { name: "Edit Thursday+Friday" }));
+    await screen.findByRole("heading", { name: "Edit pattern" });
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "Thu/Fri" } });
+    fireEvent.click(saveButton());
+
+    const alert = await screen.findByTestId("pattern-error");
+    expect(alert.getAttribute("role")).toBe("alert");
+    expect(alert.textContent).toBe("name must not be empty");
+    expect(screen.getByRole("heading", { name: "Edit pattern" })).toBeTruthy();
+    expect((screen.getByLabelText("Name") as HTMLInputElement).value).toBe("Thu/Fri");
+    expect(saveButton().disabled).toBe(false);
+  });
+
+  it("a 403 on add is surfaced as the refusal, not swallowed", async () => {
+    writeFailure = new Response("", { status: 403 });
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Add pattern" }));
+    await screen.findByRole("heading", { name: "New pattern" });
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "Fridays" } });
+    fireEvent.click(within(weekGroup(1)).getByRole("button", { name: "Friday" }));
+    fireEvent.click(saveButton());
+    const alert = await screen.findByTestId("pattern-error");
+    expect(alert.textContent).toBe("Your account is not in the nestquest-admins group.");
+    expect(patterns[1]).toEqual([DECLAN_HOME]);
+  });
+
+  it("a 403 on delete is surfaced and the pattern stays listed", async () => {
+    writeFailure = new Response("", { status: 403 });
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Delete Home weeks" }));
+    fireEvent.click(within(screen.getByTestId("pattern-1")).getByRole("button", { name: "Delete" }));
+    const alert = await screen.findByRole("alert");
+    expect(alert.textContent).toBe("Your account is not in the nestquest-admins group.");
+    expect(screen.getByTestId("pattern-1")).toBeTruthy();
+  });
+
+  it("a 422 on delete shows the API detail", async () => {
+    writeFailure = jsonResponse({ detail: "pattern_id must be an integer" }, 422);
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Delete Home weeks" }));
+    fireEvent.click(within(screen.getByTestId("pattern-1")).getByRole("button", { name: "Delete" }));
+    expect((await screen.findByRole("alert")).textContent).toBe("pattern_id must be an integer");
+  });
+
+  it("Cancel closes the editor without any request", async () => {
+    await renderReady();
+    fireEvent.click(screen.getByRole("button", { name: "Add pattern" }));
+    await screen.findByRole("heading", { name: "New pattern" });
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "Draft" } });
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    expect(screen.queryByRole("heading", { name: "New pattern" })).toBeNull();
+    expect(writes()).toEqual([]);
+    expect(document.activeElement).toBe(screen.getByRole("button", { name: "Add pattern" }));
+  });
+
+  it("never calls the removed one-per-child /presence-schedule route", async () => {
+    await selectMaeve();
+    // Add, edit and delete: every pattern path the screen can take.
+    fireEvent.click(screen.getByRole("button", { name: "Add pattern" }));
+    await screen.findByRole("heading", { name: "New pattern" });
+    fireEvent.change(screen.getByLabelText("Name"), { target: { value: "Mondays" } });
+    fireEvent.click(within(weekGroup(1)).getByRole("button", { name: "Monday" }));
+    fireEvent.click(saveButton());
+    await screen.findByTestId("pattern-50");
+    fireEvent.click(screen.getByRole("button", { name: "Edit Mondays" }));
+    await screen.findByRole("heading", { name: "Edit pattern" });
+    fireEvent.click(screen.getByRole("button", { name: "Home" }));
+    fireEvent.click(saveButton());
+    await waitFor(() => expect(screen.queryByRole("heading", { name: "Edit pattern" })).toBeNull());
+    fireEvent.click(await screen.findByRole("button", { name: "Delete Mondays" }));
+    fireEvent.click(within(screen.getByTestId("pattern-50")).getByRole("button", { name: "Delete" }));
+    await waitFor(() => expect(screen.queryByTestId("pattern-50")).toBeNull());
+
+    expect(writes().map((c) => `${c.method} ${c.path}`)).toEqual([
+      "POST /api/v1/admin/children/2/presence-patterns",
+      `PATCH ${PATTERNS_PATH}/50`,
+      `DELETE ${PATTERNS_PATH}/50`,
+    ]);
+    expect(calls().filter((c) => c.path.includes("presence-schedule"))).toEqual([]);
+  });
+
+  it("scroll column ends with 92px bottom padding", async () => {
+    await renderReady();
+    expect(screen.getByTestId("schedule-scroll").style.paddingBottom).toBe("92px");
+  });
+
+  it("shows an error state on a failed load and retries", async () => {
+    fetchMock.mockResolvedValueOnce(new Response("boom", { status: 500 }));
+    render(<ScheduleTab today={TODAY} />);
+    const error = await screen.findByTestId("schedule-error");
+    expect(error.textContent).toContain("could not be loaded");
+    fireEvent.click(screen.getByRole("button", { name: "Try again" }));
+    expect(await screen.findByTestId("pattern-1")).toBeTruthy();
+  });
+});

admin/src/schedule/ScheduleTab.tsx

@@ -0,0 +1,586 @@
+/**
+ * Schedule tab — the presence month grid (design/ADMIN-SPEC.md §4) and the
+ * selected child's presence patterns and overrides.
+ *
+ * The grid shows the COMBINED presence of every pattern (./cycle.ts
+ * `dayState`); each pattern's cycle position comes from its own anchor date,
+ * never from ISO week numbers or week parity (D-004).
+ */
+import { useEffect, useRef, useState } from "react";
+import { ApiForbiddenError } from "../api/client";
+import { ApiRequestError, fetchChildren, type AdminChild } from "../api/definitions";
+import {
+  deletePresenceOverride,
+  deletePresencePattern,
+  fetchPresenceOverrides,
+  fetchPresencePatterns,
+  type PresenceOverride,
+  type PresencePattern,
+} from "../api/presence";
+import {
+  cycleLabel,
+  dayState,
+  localTodayIso,
+  monthDates,
+  monthStart,
+  patternDaysLabel,
+  weekdayOf,
+  type DayState,
+} from "./cycle";
+import { dateRange, monthLabel, shortDate } from "./format";
+import {
+  CalendarCheckGlyph,
+  CalendarXGlyph,
+  ChevronLeftGlyph,
+  ChevronRightGlyph,
+  PencilGlyph,
+  Trash2Glyph,
+} from "./glyphs";
+import OverrideEditor from "./OverrideEditor";
+import PatternEditor from "./PatternEditor";
+import "./ScheduleTab.css";
+
+/** ADMIN-SPEC §1: every scroll column ends with 92px so content clears the tab bar. */
+export const SCROLL_BOTTOM_PADDING = "92px";
+
+/** Sunday-first header; `weekdayOf` stays Monday=0. */
+const WEEKDAY_INITIALS = ["S", "M", "T", "W", "T", "F", "S"];
+
+export const STATE_LABELS: Record<DayState, string> = {
+  home: "Home",
+  away: "Away",
+  "override-away": "Override · away",
+  "override-home": "Override · home",
+};
+
+interface Loaded {
+  children: AdminChild[];
+  patterns: Record<number, PresencePattern[]>;
+  overrides: PresenceOverride[];
+}
+
+type LoadState =
+  | { kind: "loading" }
+  | { kind: "error"; message: string }
+  | { kind: "ready"; data: Loaded };
+
+type DeleteState =
+  | { kind: "idle" }
+  | { kind: "confirming"; id: number }
+  | { kind: "deleting"; id: number }
+  | { kind: "error"; id: number; message: string };
+
+type EditorState =
+  | { kind: "closed" }
+  | { kind: "override" }
+  | { kind: "pattern"; pattern: PresencePattern | null };
+
+async function loadSchedule(): Promise<Loaded> {
+  const children = (await fetchChildren())
+    .filter((child) => child.is_active)
+    .sort((a, b) => a.sort_order - b.sort_order);
+  const [patterns, overrides] = await Promise.all([
+    Promise.all(children.map((child) => fetchPresencePatterns(child.id))),
+    fetchPresenceOverrides(),
+  ]);
+  return {
+    children,
+    patterns: Object.fromEntries(children.map((child, i) => [child.id, patterns[i]])),
+    overrides,
+  };
+}
+
+function loadErrorMessage(error: unknown): string {
+  return error instanceof ApiForbiddenError
+    ? error.message
+    : "The schedule could not be loaded. Check your connection and try again.";
+}
+
+function saveErrorMessage(error: unknown, fallback: string): string {
+  if (error instanceof ApiForbiddenError) return error.message;
+  if (error instanceof ApiRequestError && error.detail) return error.detail;
+  return fallback;
+}
+
+function ScreenHeader({ sub }: { sub: string }) {
+  return (
+    <header className="schedule-header">
+      <h2 className="schedule-title">Schedule</h2>
+      <p className="schedule-sub">{sub}</p>
+    </header>
+  );
+}
+
+interface MonthGridProps {
+  month: string;
+  today: string;
+  /** Every pattern of the child; none means home every day. */
+  patterns: PresencePattern[];
+  overrides: PresenceOverride[];
+  onMonth: (delta: number) => void;
+}
+
+function MonthGrid({ month, today, patterns, overrides, onMonth }: MonthGridProps) {
+  const dates = monthDates(month);
+  const leading = (weekdayOf(month) + 1) % 7;
+  return (
+    <>
+      <div className="schedule-month-head">
+        <span className="schedule-month-label" data-testid="month-label">
+          {monthLabel(month)}
+        </span>
+        <div className="schedule-chevrons">
+          <button
+            type="button"
+            className="schedule-chevron"
+            aria-label="Previous month"
+            onClick={() => onMonth(-1)}
+          >
+            <ChevronLeftGlyph />
+          </button>
+          <button
+            type="button"
+            className="schedule-chevron"
+            aria-label="Next month"
+            onClick={() => onMonth(1)}
+          >
+            <ChevronRightGlyph />
+          </button>
+        </div>
+      </div>
+      <div className="schedule-grid" role="group" aria-label="Month grid">
+        {WEEKDAY_INITIALS.map((initial, i) => (
+          <span key={`wd-${i}`} className="schedule-weekday" aria-hidden="true">
+            {initial}
+          </span>
+        ))}
+        {Array.from({ length: leading }, (_, i) => (
+          <span key={`pad-${i}`} aria-hidden="true" />
+        ))}
+        {dates.map((date) => {
+          const state = dayState(patterns, overrides, date);
+          const isToday = date === today;
+          let className = `schedule-day schedule-day--${state}`;
+          if (isToday) className += " schedule-day--today";
+          return (
+            <span
+              key={date}
+              role="img"
+              className={className}
+              data-date={date}
+              data-state={state}
+              aria-label={`${shortDate(date)}${isToday ? " (today)" : ""}: ${STATE_LABELS[state]}`}
+            >
+              {Number(date.slice(8))}
+            </span>
+          );
+        })}
+      </div>
+      <ul className="schedule-legend" aria-label="Legend">
+        {(["home", "away", "override-away", "override-home"] as DayState[]).map((state) => (
+          <li key={state} className="schedule-legend-item">
+            <span className={`schedule-swatch schedule-day--${state}`} aria-hidden="true" />
+            {STATE_LABELS[state]}
+          </li>
+        ))}
+        <li className="schedule-legend-item">
+          <span className="schedule-swatch schedule-day--today" aria-hidden="true" />
+          Today
+        </li>
+      </ul>
+      <p className="schedule-legend-note">
+        Combined from every pattern: away beats home; overrides beat both.
+      </p>
+    </>
+  );
+}
+
+interface PatternRowProps {
+  pattern: PresencePattern;
+  deletion: DeleteState;
+  onEdit: () => void;
+  onAskDelete: () => void;
+  onKeep: () => void;
+  onDelete: () => void;
+}
+
+function PatternRow({ pattern, deletion, onEdit, onAskDelete, onKeep, onDelete }: PatternRowProps) {
+  const mine =
+    (deletion.kind === "confirming" || deletion.kind === "deleting") && deletion.id === pattern.id;
+  return (
+    <li className="schedule-row" data-testid={`pattern-${pattern.id}`}>
+      <span className="schedule-row-glyph">
+        {pattern.kind === "home" ? <CalendarCheckGlyph /> : <CalendarXGlyph />}
+      </span>
+      <div className="schedule-row-text">
+        <div className="schedule-row-title">{pattern.name}</div>
+        <div className="schedule-row-meta">
+          {pattern.kind === "home" ? "Home" : "Away"} · {cycleLabel(pattern.cycle_length_weeks)}
+        </div>
+        <div className="schedule-row-meta" data-testid={`pattern-days-${pattern.id}`}>
+          {patternDaysLabel(pattern)}
+        </div>
+      </div>
+      {mine ? (
+        <div className="schedule-confirm" role="group" aria-label="Confirm delete">
+          <span className="schedule-confirm-text">Delete pattern?</span>
+          <button
+            type="button"
+            className="schedule-confirm-keep"
+            onClick={onKeep}
+            disabled={deletion.kind === "deleting"}
+          >
+            Keep
+          </button>
+          <button
+            type="button"
+            className="schedule-confirm-delete"
+            onClick={onDelete}
+            disabled={deletion.kind === "deleting"}
+          >
+            {deletion.kind === "deleting" ? "Deleting…" : "Delete"}
+          </button>
+        </div>
+      ) : (
+        <>
+          <button
+            type="button"
+            className="schedule-icon-action schedule-icon-action--edit"
+            aria-label={`Edit ${pattern.name}`}
+            onClick={onEdit}
+          >
+            <PencilGlyph />
+          </button>
+          <button
+            type="button"
+            className="schedule-icon-action"
+            aria-label={`Delete ${pattern.name}`}
+            onClick={onAskDelete}
+          >
+            <Trash2Glyph />
+          </button>
+        </>
+      )}
+    </li>
+  );
+}
+
+interface OverrideRowProps {
+  override: PresenceOverride;
+  childName: string;
+  deletion: DeleteState;
+  onAskDelete: () => void;
+  onKeep: () => void;
+  onDelete: () => void;
+}
+
+function OverrideRow({ override, childName, deletion, onAskDelete, onKeep, onDelete }: OverrideRowProps) {
+  const mine =
+    (deletion.kind === "confirming" || deletion.kind === "deleting") && deletion.id === override.id;
+  return (
+    <li className="schedule-row" data-testid={`override-${override.id}`}>
+      <span className="schedule-row-glyph">
+        {override.is_present ? <CalendarCheckGlyph /> : <CalendarXGlyph />}
+      </span>
+      <div className="schedule-row-text">
+        <div className="schedule-row-title">
+          {childName} {override.is_present ? "home" : "away"} ·{" "}
+          {dateRange(override.start_date, override.end_date)}
+        </div>
+        <div className="schedule-row-meta">{override.note || "No reason given"}</div>
+      </div>
+      {mine ? (
+        <div className="schedule-confirm" role="group" aria-label="Confirm delete">
+          <span className="schedule-confirm-text">Delete override?</span>
+          <button
+            type="button"
+            className="schedule-confirm-keep"
+            onClick={onKeep}
+            disabled={deletion.kind === "deleting"}
+          >
+            Keep
+          </button>
+          <button
+            type="button"
+            className="schedule-confirm-delete"
+            onClick={onDelete}
+            disabled={deletion.kind === "deleting"}
+          >
+            {deletion.kind === "deleting" ? "Deleting…" : "Delete"}
+          </button>
+        </div>
+      ) : (
+        <button
+          type="button"
+          className="schedule-icon-action"
+          aria-label="Delete override"
+          onClick={onAskDelete}
+        >
+          <Trash2Glyph />
+        </button>
+      )}
+    </li>
+  );
+}
+
+export interface ScheduleTabProps {
+  /** "YYYY-MM-DD"; defaults to the viewer's local date. */
+  today?: string;
+}
+
+export default function ScheduleTab({ today = localTodayIso() }: ScheduleTabProps) {
+  const [state, setState] = useState<LoadState>({ kind: "loading" });
+  const [attempt, setAttempt] = useState(0);
+  const [selectedId, setSelectedId] = useState<number | null>(null);
+  const [month, setMonth] = useState(() => monthStart(today));
+  const [editor, setEditor] = useState<EditorState>({ kind: "closed" });
+  const [deletion, setDeletion] = useState<DeleteState>({ kind: "idle" });
+  const [patternDeletion, setPatternDeletion] = useState<DeleteState>({ kind: "idle" });
+  const addRef = useRef<HTMLButtonElement>(null);
+  const addPatternRef = useRef<HTMLButtonElement>(null);
+  const openedEditor = useRef<EditorState["kind"]>("closed");
+
+  // An editor replaces this screen, so the Add controls are remounted when
+  // it closes; hand focus back to the one that belongs to that editor.
+  useEffect(() => {
+    if (editor.kind === "closed") {
+      if (openedEditor.current === "override") addRef.current?.focus();
+      if (openedEditor.current === "pattern") addPatternRef.current?.focus();
+    }
+    openedEditor.current = editor.kind;
+  }, [editor.kind]);
+
+  /** Reload children, patterns and overrides in place (no loading flash). */
+  const refresh = () =>
+    loadSchedule()
+      .then((data) => setState({ kind: "ready", data }))
+      .catch((error: unknown) => setState({ kind: "error", message: loadErrorMessage(error) }));
+
+  useEffect(() => {
+    let cancelled = false;
+    setState({ kind: "loading" });
+    loadSchedule()
+      .then((data) => {
+        if (cancelled) return;
+        setState({ kind: "ready", data });
+        setSelectedId((current) => current ?? data.children[0]?.id ?? null);
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        setState({ kind: "error", message: loadErrorMessage(error) });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [attempt]);
+
+  if (editor.kind !== "closed" && state.kind === "ready" && state.data.children.length > 0) {
+    const { children } = state.data;
+    const current = children.find((c) => c.id === selectedId) ?? children[0];
+    if (editor.kind === "pattern") {
+      return (
+        <PatternEditor
+          child={current}
+          pattern={editor.pattern}
+          today={today}
+          onCancel={() => setEditor({ kind: "closed" })}
+          onSaved={() => {
+            setEditor({ kind: "closed" });
+            void refresh();
+          }}
+        />
+      );
+    }
+    return (
+      <OverrideEditor
+        childOptions={children}
+        initialChildId={current.id}
+        today={today}
+        onCancel={() => setEditor({ kind: "closed" })}
+        onSaved={(override) => {
+          setEditor({ kind: "closed" });
+          setSelectedId(override.child_id);
+          void refresh();
+        }}
+      />
+    );
+  }
+
+  let sub = "";
+  let body;
+  if (state.kind === "loading") {
+    body = (
+      <div className="schedule-status" role="status" data-testid="schedule-loading">
+        Loading schedule…
+      </div>
+    );
+  } else if (state.kind === "error") {
+    body = (
+      <div className="schedule-status schedule-status--error" role="alert" data-testid="schedule-error">
+        <p>{state.message}</p>
+        <button type="button" className="schedule-retry" onClick={() => setAttempt((n) => n + 1)}>
+          Try again
+        </button>
+      </div>
+    );
+  } else if (state.data.children.length === 0) {
+    body = <div className="schedule-card schedule-empty">No children yet.</div>;
+  } else {
+    const { data } = state;
+    const child = data.children.find((c) => c.id === selectedId) ?? data.children[0];
+    const patterns = data.patterns[child.id] ?? [];
+    const childOverrides = data.overrides.filter((o) => o.child_id === child.id);
+    sub =
+      patterns.length === 0
+        ? `${child.display_name} · no patterns, home every day`
+        : `${child.display_name} · ${patterns.length} ${patterns.length === 1 ? "pattern" : "patterns"}`;
+
+    const confirmDelete = (id: number) => {
+      setDeletion({ kind: "deleting", id });
+      deletePresenceOverride(id)
+        .then(() => refresh())
+        .then(() => setDeletion({ kind: "idle" }))
+        .catch((error: unknown) =>
+          setDeletion({
+            kind: "error",
+            id,
+            message: saveErrorMessage(
+              error,
+              "The override could not be deleted. Check your connection and try again.",
+            ),
+          }),
+        );
+    };
+    const confirmPatternDelete = (id: number) => {
+      setPatternDeletion({ kind: "deleting", id });
+      deletePresencePattern(id)
+        .then(() => refresh())
+        .then(() => setPatternDeletion({ kind: "idle" }))
+        .catch((error: unknown) =>
+          setPatternDeletion({
+            kind: "error",
+            id,
+            message: saveErrorMessage(
+              error,
+              "The pattern could not be deleted. Check your connection and try again.",
+            ),
+          }),
+        );
+    };
+
+    body = (
+      <>
+        <div className="schedule-children" role="group" aria-label="Child">
+          {data.children.map((c) => (
+            <button
+              key={c.id}
+              type="button"
+              className="schedule-child-chip"
+              aria-pressed={c.id === child.id}
+              onClick={() => {
+                setSelectedId(c.id);
+                setPatternDeletion({ kind: "idle" });
+              }}
+            >
+              {c.display_name}
+            </button>
+          ))}
+        </div>
+
+        <section className="schedule-card schedule-month" aria-label="Month grid card">
+          <MonthGrid
+            month={month}
+            today={today}
+            patterns={patterns}
+            overrides={childOverrides}
+            onMonth={(delta) => setMonth((m) => monthStart(m, delta))}
+          />
+        </section>
+
+        <div className="schedule-section-head">
+          <h3 className="schedule-section-label">Presence patterns</h3>
+          <button
+            ref={addPatternRef}
+            type="button"
+            className="schedule-text-action"
+            aria-label="Add pattern"
+            onClick={() => setEditor({ kind: "pattern", pattern: null })}
+          >
+            Add
+          </button>
+        </div>
+        {patterns.length > 0 ? (
+          <ul className="schedule-card schedule-list" aria-label="Presence patterns">
+            {patterns.map((pattern) => (
+              <PatternRow
+                key={pattern.id}
+                pattern={pattern}
+                deletion={patternDeletion}
+                onEdit={() => setEditor({ kind: "pattern", pattern })}
+                onAskDelete={() => setPatternDeletion({ kind: "confirming", id: pattern.id })}
+                onKeep={() => setPatternDeletion({ kind: "idle" })}
+                onDelete={() => confirmPatternDelete(pattern.id)}
+              />
+            ))}
+          </ul>
+        ) : (
+          <div className="schedule-card schedule-empty" data-testid="patterns-empty">
+            No patterns for {child.display_name} — home every day.
+          </div>
+        )}
+        {patternDeletion.kind === "error" ? (
+          <p className="schedule-save-status schedule-save-status--error" role="alert">
+            {patternDeletion.message}
+          </p>
+        ) : null}
+
+        <div className="schedule-section-head">
+          <h3 className="schedule-section-label">Overrides</h3>
+          <button
+            ref={addRef}
+            type="button"
+            className="schedule-text-action"
+            onClick={() => setEditor({ kind: "override" })}
+          >
+            Add
+          </button>
+        </div>
+        {childOverrides.length > 0 ? (
+          <ul className="schedule-card schedule-list" aria-label="Overrides">
+            {childOverrides.map((override) => (
+              <OverrideRow
+                key={override.id}
+                override={override}
+                childName={child.display_name}
+                deletion={deletion}
+                onAskDelete={() => setDeletion({ kind: "confirming", id: override.id })}
+                onKeep={() => setDeletion({ kind: "idle" })}
+                onDelete={() => confirmDelete(override.id)}
+              />
+            ))}
+          </ul>
+        ) : (
+          <div className="schedule-card schedule-empty">No overrides for {child.display_name}.</div>
+        )}
+        {deletion.kind === "error" ? (
+          <p className="schedule-save-status schedule-save-status--error" role="alert">
+            {deletion.message}
+          </p>
+        ) : null}
+      </>
+    );
+  }
+
+  return (
+    <div className="schedule-screen">
+      <ScreenHeader sub={sub} />
+      <div
+        className="schedule-scroll"
+        data-testid="schedule-scroll"
+        style={{ paddingBottom: SCROLL_BOTTOM_PADDING }}
+      >
+        {body}
+      </div>
+    </div>
+  );
+}

admin/src/schedule/cycle.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it } from "vitest";
+import {
+  cycleLabel,
+  cycleWeekIndex,
+  dayState,
+  emptyPattern,
+  monthDates,
+  monthStart,
+  patternDaysLabel,
+  patternIncludes,
+  resizePattern,
+  togglePatternDay,
+  weekdayOf,
+} from "./cycle";
+import type { PatternCycle, PatternKind, PresenceOverride } from "../api/presence";
+
+type KindedCycle = PatternCycle & { kind: PatternKind };
+
+// The migrated single schedule: anchor Monday 2026-09-07; week 0 home every
+// day, week 1 home Sat/Sun only.
+const SCHEDULE: KindedCycle = {
+  kind: "home",
+  cycle_length_weeks: 2,
+  anchor_date: "2026-09-07",
+  pattern: { 0: [0, 1, 2, 3, 4, 5, 6], 1: [5, 6] },
+};
+
+// The owner scenario: away Thu+Fri every week, away weekends every 2 weeks.
+const THU_FRI: KindedCycle = {
+  kind: "away",
+  cycle_length_weeks: 1,
+  anchor_date: "2026-09-07",
+  pattern: { 0: [3, 4] },
+};
+const ALTERNATE_WEEKENDS: KindedCycle = {
+  kind: "away",
+  cycle_length_weeks: 2,
+  anchor_date: "2026-09-07",
+  pattern: { 0: [5, 6], 1: [] },
+};
+
+describe("cycleWeekIndex", () => {
+  it("follows the anchor across a month, wrapping every 2 weeks", () => {
+    const expected: Record<string, number> = {};
+    for (const date of monthDates("2026-09-01")) {
+      const day = Number(date.slice(8));
+      // Sep 7-13 week 0, 14-20 week 1, 21-27 week 0 (wrap), 28-30 week 1;
+      // Sep 1-6 lie before the anchor and walk back into week 1.
+      expected[date] = day < 7 ? 1 : Math.floor((day - 7) / 7) % 2;
+    }
+    for (const [date, week] of Object.entries(expected)) {
+      expect(cycleWeekIndex(SCHEDULE.anchor_date, date, 2), date).toBe(week);
+    }
+    expect(cycleWeekIndex("2026-09-07", "2026-09-21", 2)).toBe(0);
+    expect(cycleWeekIndex("2026-09-07", "2026-09-28", 2)).toBe(1);
+  });
+
+  it("walks the cycle backwards before the anchor (floor division)", () => {
+    expect(cycleWeekIndex("2026-09-07", "2026-09-06", 2)).toBe(1); // day -1
+    expect(cycleWeekIndex("2026-09-07", "2026-08-31", 2)).toBe(1); // day -7
+    expect(cycleWeekIndex("2026-09-07", "2026-08-30", 2)).toBe(0); // day -8
+    expect(cycleWeekIndex("2026-09-07", "2026-08-24", 2)).toBe(0); // day -14
+    expect(cycleWeekIndex("2026-09-07", "2026-08-23", 2)).toBe(1); // day -15
+    expect(cycleWeekIndex("2026-09-07", "2026-09-06", 3)).toBe(2); // last week of a 3-week cycle
+  });
+
+  it("ignores ISO week parity across a 53-week year", () => {
+    // 2026-12-28 is ISO week 53 and 2027-01-04 ISO week 1 — both odd, so
+    // parity would call them the same week. From the anchor they alternate.
+    expect(cycleWeekIndex("2026-09-07", "2026-12-28", 2)).toBe(0);
+    expect(cycleWeekIndex("2026-09-07", "2027-01-04", 2)).toBe(1);
+  });
+});
+
+describe("calendar helpers", () => {
+  it("weekdayOf is Monday=0", () => {
+    expect(weekdayOf("2026-09-07")).toBe(0);
+    expect(weekdayOf("2026-09-01")).toBe(1);
+    expect(weekdayOf("2026-09-06")).toBe(6);
+  });
+
+  it("weekdayOf keeps the stored Monday=0 .. Sunday=6 numbering (display order is separate)", () => {
+    // A full known week plus dates across month and year ends.
+    expect(
+      [
+        "2026-09-07",
+        "2026-09-08",
+        "2026-09-09",
+        "2026-09-10",
+        "2026-09-11",
+        "2026-09-12",
+        "2026-09-13",
+      ].map(weekdayOf),
+    ).toEqual([0, 1, 2, 3, 4, 5, 6]);
+    expect(weekdayOf("2026-11-01")).toBe(6); // Sunday
+    expect(weekdayOf("2027-01-01")).toBe(4); // Friday
+    expect(weekdayOf("2024-02-29")).toBe(3); // Thursday
+  });
+
+  it("monthStart shifts across year ends", () => {
+    expect(monthStart("2026-12-15", 1)).toBe("2027-01-01");
+    expect(monthStart("2026-01-31", -1)).toBe("2025-12-01");
+    expect(monthDates("2026-02-01")).toHaveLength(28);
+  });
+});
+
+describe("dayState", () => {
+  const overrides: PresenceOverride[] = [
+    { id: 1, child_id: 1, start_date: "2026-09-10", end_date: "2026-09-12", is_present: false, note: null },
+    { id: 2, child_id: 1, start_date: "2026-09-16", end_date: "2026-09-16", is_present: true, note: null },
+  ];
+
+  it("a home-only child: overrides first, then absent on days no home pattern covers", () => {
+    const patterns = [SCHEDULE];
+    expect(dayState(patterns, overrides, "2026-09-08")).toBe("home");
+    expect(dayState(patterns, overrides, "2026-09-11")).toBe("override-away");
+    expect(dayState(patterns, overrides, "2026-09-15")).toBe("away");
+    expect(dayState(patterns, overrides, "2026-09-16")).toBe("override-home");
+    expect(dayState(patterns, overrides, "2026-09-19")).toBe("home");
+    expect(dayState(patterns, overrides, "2026-09-01")).toBe("away");
+    expect(dayState(patterns, overrides, "2026-09-05")).toBe("home");
+  });
+
+  it("combines the owner's two away patterns; every other day is home", () => {
+    const patterns = [THU_FRI, ALTERNATE_WEEKENDS];
+    const expected: Record<string, string> = {};
+    for (const date of monthDates("2026-09-01")) {
+      const weekday = weekdayOf(date);
+      const onWeek = cycleWeekIndex("2026-09-07", date, 2) === 0;
+      const away = weekday === 3 || weekday === 4 || (onWeek && weekday >= 5);
+      expected[date] = away ? "away" : "home";
+    }
+    for (const [date, state] of Object.entries(expected)) {
+      expect(dayState(patterns, [], date), date).toBe(state);
+    }
+    // Spot checks: Thu/Fri every week; weekends alternate from the anchor.
+    expect(dayState(patterns, [], "2026-09-10")).toBe("away"); // Thu, week 0
+    expect(dayState(patterns, [], "2026-09-18")).toBe("away"); // Fri, week 1
+    expect(dayState(patterns, [], "2026-09-12")).toBe("away"); // Sat, week 0
+    expect(dayState(patterns, [], "2026-09-20")).toBe("home"); // Sun, week 1
+    expect(dayState(patterns, [], "2026-09-27")).toBe("away"); // Sun, week 0
+    expect(dayState(patterns, [], "2026-09-15")).toBe("home"); // Tue
+  });
+
+  it("away beats home when both cover a date; a home pattern makes uncovered days away", () => {
+    const patterns = [SCHEDULE, THU_FRI];
+    expect(dayState(patterns, [], "2026-09-10")).toBe("away"); // home week 0 Thu, but away wins
+    expect(dayState(patterns, [], "2026-09-08")).toBe("home"); // home covers, away does not
+    expect(dayState(patterns, [], "2026-09-15")).toBe("away"); // no home pattern covers it
+    // An override still beats every pattern.
+    expect(
+      dayState(patterns, [{ ...overrides[1], start_date: "2026-09-10", end_date: "2026-09-10" }], "2026-09-10"),
+    ).toBe("override-home");
+  });
+
+  it("treats a child with no patterns as home every day", () => {
+    expect(dayState([], [], "2026-09-15")).toBe("home");
+  });
+});
+
+describe("pattern editing and labels", () => {
+  it("patternIncludes reads the date's cycle week from the anchor", () => {
+    expect(patternIncludes(ALTERNATE_WEEKENDS, "2026-09-12")).toBe(true);
+    expect(patternIncludes(ALTERNATE_WEEKENDS, "2026-09-19")).toBe(false);
+    expect(patternIncludes(ALTERNATE_WEEKENDS, "2026-09-05")).toBe(false); // pre-anchor week 1
+  });
+
+  it("toggles one weekday of one cycle week", () => {
+    expect(togglePatternDay(SCHEDULE.pattern, 1, 1)).toEqual({
+      0: [0, 1, 2, 3, 4, 5, 6],
+      1: [1, 5, 6],
+    });
+    expect(togglePatternDay(SCHEDULE.pattern, 1, 5)[1]).toEqual([6]);
+  });
+
+  it("resizes the pattern to the cycle length; added weeks cover no day", () => {
+    expect(resizePattern(SCHEDULE.pattern, 1)).toEqual({ 0: [0, 1, 2, 3, 4, 5, 6] });
+    expect(resizePattern(SCHEDULE.pattern, 3)[2]).toEqual([]);
+    expect(emptyPattern(2)).toEqual({ 0: [], 1: [] });
+  });
+
+  it("describes the cycle and the weekday set in plain language", () => {
+    expect(cycleLabel(1)).toBe("Every week");
+    expect(cycleLabel(2)).toBe("Every 2 weeks");
+    expect(patternDaysLabel(THU_FRI)).toBe("Thu, Fri");
+    expect(patternDaysLabel(ALTERNATE_WEEKENDS)).toBe("Week 1: Sat, Sun · Week 2: No days");
+    expect(patternDaysLabel(SCHEDULE)).toBe("Week 1: Every day · Week 2: Sat, Sun");
+    // Listed Monday-first by weekday number, whatever order they were stored in.
+    expect(patternDaysLabel({ ...THU_FRI, pattern: { "0": [6, 0] } })).toBe("Mon, Sun");
+  });
+});

admin/src/schedule/cycle.ts

@@ -0,0 +1,163 @@
+/**
+ * Pure presence-cycle math for the Schedule tab.
+ *
+ * Cycle position comes from the anchor date ONLY, mirroring
+ * core/presence.py `cycle_week_index`:
+ * `((date - anchor).days // 7) % cycle_length_weeks` with floor division,
+ * so dates before the anchor walk the cycle backwards. Never ISO week
+ * numbers or week parity (D-004).
+ *
+ * Calendar dates are "YYYY-MM-DD" strings handled as whole UTC days, so no
+ * viewer offset or DST change can shift a day.
+ */
+import type {
+  PatternCycle,
+  PatternKind,
+  PatternWeeks,
+  PresenceOverride,
+} from "../api/presence";
+
+const MS_PER_DAY = 86_400_000;
+
+export const ALL_WEEKDAYS = [0, 1, 2, 3, 4, 5, 6];
+
+/** Monday=0 weekday numbers in Sunday-first display order. */
+export const DISPLAY_WEEKDAYS = [6, 0, 1, 2, 3, 4, 5];
+
+/** Short names indexed by Monday=0 weekday number. */
+export const WEEKDAY_SHORT = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+
+/** Days since 1970-01-01 for a "YYYY-MM-DD" calendar date. */
+export function dayNumber(iso: string): number {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+  if (!match) throw new Error(`Invalid calendar date: ${iso}`);
+  const [, year, month, day] = match;
+  return Date.UTC(Number(year), Number(month) - 1, Number(day)) / MS_PER_DAY;
+}
+
+export function isoFromDayNumber(days: number): string {
+  return new Date(days * MS_PER_DAY).toISOString().slice(0, 10);
+}
+
+/** Floor modulo: always in 0..divisor-1, like Python's `%`. */
+function mod(value: number, divisor: number): number {
+  return ((value % divisor) + divisor) % divisor;
+}
+
+/** 0 = Monday .. 6 = Sunday (1970-01-01 was a Thursday). */
+export function weekdayOf(iso: string): number {
+  return mod(dayNumber(iso) + 3, 7);
+}
+
+/** `((date - anchor).days // 7) % cycleLengthWeeks`, Python semantics. */
+export function cycleWeekIndex(anchorDate: string, date: string, cycleLengthWeeks: number): number {
+  const days = dayNumber(date) - dayNumber(anchorDate);
+  return mod(Math.floor(days / 7), cycleLengthWeeks);
+}
+
+/** The viewer's local calendar date. */
+export function localTodayIso(now: Date = new Date()): string {
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${now.getFullYear()}-${month}-${day}`;
+}
+
+/** "YYYY-MM-01" of the month containing `iso`, shifted by `delta` months. */
+export function monthStart(iso: string, delta = 0): string {
+  const [year, month] = iso.split("-").map(Number);
+  const date = new Date(Date.UTC(year, month - 1 + delta, 1));
+  return date.toISOString().slice(0, 10);
+}
+
+/** Every date of the month starting at `firstIso`. */
+export function monthDates(firstIso: string): string[] {
+  const start = dayNumber(firstIso);
+  const end = dayNumber(monthStart(firstIso, 1));
+  const dates: string[] = [];
+  for (let day = start; day < end; day += 1) dates.push(isoFromDayNumber(day));
+  return dates;
+}
+
+/** Every week of the cycle covers no day yet (a new pattern). */
+export function emptyPattern(cycleLengthWeeks: number): PatternWeeks {
+  const pattern: PatternWeeks = {};
+  for (let week = 0; week < cycleLengthWeeks; week += 1) pattern[week] = [];
+  return pattern;
+}
+
+export type DayState = "home" | "away" | "override-home" | "override-away";
+
+/** Does the pattern cover `date` (its cycle week lists the date's weekday)? */
+export function patternIncludes(cycle: PatternCycle, date: string): boolean {
+  const week = cycleWeekIndex(cycle.anchor_date, date, cycle.cycle_length_weeks);
+  return (cycle.pattern[week] ?? []).includes(weekdayOf(date));
+}
+
+/**
+ * A date's combined state for one child, mirroring core/presence.py
+ * `is_present` — first match wins:
+ * 1. an override covering the date;
+ * 2. away when any `away` pattern covers it;
+ * 3. home when any `home` pattern covers it;
+ * 4. away when the child has at least one `home` pattern (a home pattern
+ *    lists the days the child IS here), else home (no patterns, or only
+ *    `away` ones).
+ */
+export function dayState(
+  patterns: (PatternCycle & { kind: PatternKind })[],
+  overrides: PresenceOverride[],
+  date: string,
+): DayState {
+  const override = overrides.find((o) => o.start_date <= date && date <= o.end_date);
+  if (override) return override.is_present ? "override-home" : "override-away";
+  if (patterns.some((p) => p.kind === "away" && patternIncludes(p, date))) return "away";
+  const homes = patterns.filter((p) => p.kind === "home");
+  if (homes.some((p) => patternIncludes(p, date))) return "home";
+  return homes.length > 0 ? "away" : "home";
+}
+
+/** Flip `weekday` in `week` of the pattern; returns a new pattern. */
+export function togglePatternDay(
+  pattern: PatternWeeks,
+  week: number,
+  weekday: number,
+): PatternWeeks {
+  const days = pattern[week] ?? [];
+  const next = days.includes(weekday)
+    ? days.filter((d) => d !== weekday)
+    : [...days, weekday].sort((a, b) => a - b);
+  return { ...pattern, [week]: next };
+}
+
+/** Fit the pattern to a new cycle length; added weeks start covering no day. */
+export function resizePattern(pattern: PatternWeeks, cycleLengthWeeks: number): PatternWeeks {
+  const next: PatternWeeks = {};
+  for (let week = 0; week < cycleLengthWeeks; week += 1) {
+    next[week] = pattern[week] ? [...pattern[week]] : [];
+  }
+  return next;
+}
+
+function daysLabel(days: number[]): string {
+  if (days.length === 7) return "Every day";
+  if (days.length === 0) return "No days";
+  return [...days].sort((a, b) => a - b).map((d) => WEEKDAY_SHORT[d]).join(", ");
+}
+
+/**
+ * Plain-language weekday set: `Thu, Fri` for a 1-week cycle, otherwise one
+ * entry per cycle week, e.g. `Week 1: Sat, Sun · Week 2: No days`.
+ */
+export function patternDaysLabel(cycle: PatternCycle): string {
+  if (cycle.cycle_length_weeks === 1) return daysLabel(cycle.pattern[0] ?? []);
+  const weeks: string[] = [];
+  for (let week = 0; week < cycle.cycle_length_weeks; week += 1) {
+    weeks.push(`Week ${week + 1}: ${daysLabel(cycle.pattern[week] ?? [])}`);
+  }
+  return weeks.join(" · ");
+}
+
+/** `Every week`, `Every 2 weeks`. */
+export function cycleLabel(cycleLengthWeeks: number): string {
+  return cycleLengthWeeks === 1 ? "Every week" : `Every ${cycleLengthWeeks} weeks`;
+}

admin/src/schedule/format.ts

@@ -0,0 +1,37 @@
+/**
+ * Date labels for the Schedule tab. Calendar dates are formatted in UTC from
+ * their components, so the printed day never shifts with the viewer's offset.
+ */
+import { dayNumber } from "./cycle";
+
+const LOCALE = "en-US";
+
+function utcDate(iso: string): Date {
+  return new Date(dayNumber(iso) * 86_400_000);
+}
+
+function format(iso: string, options: Intl.DateTimeFormatOptions): string {
+  return new Intl.DateTimeFormat(LOCALE, { ...options, timeZone: "UTC" }).format(utcDate(iso));
+}
+
+/** "Tuesday, Sep 1" */
+export function anchorLabel(iso: string): string {
+  return `${format(iso, { weekday: "long" })}, ${format(iso, { month: "short", day: "numeric" })}`;
+}
+
+/** "September 2026" */
+export function monthLabel(iso: string): string {
+  return format(iso, { month: "long", year: "numeric" });
+}
+
+/** "Sep 4" */
+export function shortDate(iso: string): string {
+  return format(iso, { month: "short", day: "numeric" });
+}
+
+/** "Sep 4 – 7", "Sep 28 – Oct 2", or "Sep 4" for a single day. */
+export function dateRange(start: string, end: string): string {
+  if (start === end) return shortDate(start);
+  const sameMonth = start.slice(0, 7) === end.slice(0, 7);
+  return `${shortDate(start)} – ${sameMonth ? Number(end.slice(8)) : shortDate(end)}`;
+}

admin/src/schedule/glyphs.tsx

@@ -0,0 +1,94 @@
+/**
+ * Inline stroke glyphs for the Schedule tab (Lucide-style 24px grid),
+ * CDN-free like the Today and Tasks tabs' glyphs.
+ */
+import type { ReactNode } from "react";
+
+function Glyph({ size, children }: { size: number; children: ReactNode }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    >
+      {children}
+    </svg>
+  );
+}
+
+export function ChevronLeftGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="m15 18-6-6 6-6" />
+    </Glyph>
+  );
+}
+
+export function ChevronRightGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="m9 18 6-6-6-6" />
+    </Glyph>
+  );
+}
+
+function CalendarFrame() {
+  return (
+    <>
+      <path d="M8 2v4M16 2v4" />
+      <rect x="3" y="4" width="18" height="18" rx="2" />
+      <path d="M3 10h18" />
+    </>
+  );
+}
+
+export function CalendarXGlyph({ size = 18 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <CalendarFrame />
+      <path d="m14 14-4 4M10 14l4 4" />
+    </Glyph>
+  );
+}
+
+export function CalendarCheckGlyph({ size = 18 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <CalendarFrame />
+      <path d="m9 16 2 2 4-4" />
+    </Glyph>
+  );
+}
+
+export function PencilGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z" />
+      <path d="m15 5 4 4" />
+    </Glyph>
+  );
+}
+
+export function Trash2Glyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="M3 6h18M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2M10 11v6M14 11v6" />
+    </Glyph>
+  );
+}
+
+export function AlertCircleGlyph({ size = 18 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <circle cx="12" cy="12" r="10" />
+      <path d="M12 8v4M12 16h.01" />
+    </Glyph>
+  );
+}

admin/src/settings/SettingsScreen.css

@@ -0,0 +1,367 @@
+/* Settings — pushed screen over the Today tab (and the tab bar), like the
+   presence override editor. Compact density list, roomy form card. */
+
+.settings-screen {
+  position: fixed;
+  inset: 0;
+  z-index: 30;
+  overflow-y: auto;
+  background: var(--nq-a-page);
+}
+
+.settings-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 14px 16px;
+  background: var(--nq-a-surface);
+  border-bottom: 1px solid var(--nq-a-border);
+}
+
+.settings-back {
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: var(--nq-a-tap-min);
+  height: var(--nq-a-tap-min);
+  margin: -6px 0 -6px -12px;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--nq-a-ink);
+  cursor: pointer;
+}
+
+.settings-title {
+  margin: 0;
+  font-size: var(--nq-a-size-screen);
+  font-weight: 800;
+  letter-spacing: -0.02em;
+}
+
+.settings-sub {
+  margin: 2px 0 0;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+/* Scroll column: 14px 16px, bottom 92px (set inline, ADMIN-SPEC §1). */
+.settings-scroll {
+  display: flex;
+  flex-direction: column;
+  gap: var(--nq-a-density-gap);
+  width: 100%;
+  max-width: 640px;
+  margin: 0 auto;
+  padding: 14px 16px;
+}
+
+.settings-section-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.settings-section-label {
+  margin: 0;
+  font-size: var(--nq-a-size-label);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: var(--nq-a-track-label);
+  color: var(--nq-a-ink-secondary);
+}
+
+.settings-add {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  min-height: 36px;
+  padding: 0 12px;
+  border: 0;
+  border-radius: var(--nq-a-radius-pill);
+  background: var(--nq-brand-gradient);
+  color: #fff;
+  font-family: inherit;
+  font-size: 12.5px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.settings-card {
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+}
+
+.settings-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.settings-list > li + li {
+  border-top: 1px solid var(--nq-a-divider);
+}
+
+.settings-child {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 10px;
+  padding: var(--nq-a-density-row-pad);
+}
+
+.settings-child--inactive .settings-child-name {
+  color: var(--nq-a-ink-tertiary);
+}
+
+.settings-swatch {
+  flex: none;
+  width: 22px;
+  height: 22px;
+  border-radius: var(--nq-a-radius-pill);
+  border: 1px solid rgba(9, 9, 11, 0.12);
+}
+
+.settings-child-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.settings-child-name {
+  font-size: var(--nq-a-size-row);
+  font-weight: 700;
+}
+
+.settings-child-meta {
+  margin-top: 1px;
+  font-size: var(--nq-a-size-meta);
+  font-weight: 600;
+  color: var(--nq-a-ink-tertiary);
+}
+
+.settings-pill {
+  flex: none;
+  padding: 2px 8px;
+  border-radius: var(--nq-a-radius-pill);
+  background: var(--nq-a-divider);
+  color: var(--nq-a-ink-secondary);
+  font-size: var(--nq-a-size-meta);
+  font-weight: 700;
+}
+
+.settings-pill--active {
+  background: #dcfce7;
+  color: var(--nq-a-success);
+}
+
+.settings-child-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: 6px;
+  width: 100%;
+}
+
+.settings-icon-button,
+.settings-action {
+  min-height: 36px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 12px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.settings-icon-button {
+  display: grid;
+  place-items: center;
+  width: 36px;
+  padding: 0;
+}
+
+.settings-action {
+  padding: 0 12px;
+}
+
+.settings-icon-button:disabled,
+.settings-action:disabled,
+.settings-add:disabled,
+.settings-back:disabled,
+.settings-cancel:disabled,
+.settings-save:disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+
+.settings-empty,
+.settings-status {
+  padding: 16px;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+  text-align: center;
+}
+
+.settings-status--error {
+  color: var(--nq-a-danger-strong);
+}
+
+.settings-status p {
+  margin: 0 0 10px;
+}
+
+.settings-action-error {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  padding: 10px 12px;
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-danger-bg);
+  color: var(--nq-a-danger-strong);
+  font-size: 12.5px;
+  font-weight: 700;
+}
+
+/* Add / edit form: roomy density, 18px padding, 16px gaps. */
+.settings-form {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 18px;
+}
+
+.settings-form-title {
+  margin: 0;
+  font-size: 17px;
+  font-weight: 800;
+}
+
+.settings-field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-width: 0;
+}
+
+.settings-label {
+  font-size: var(--nq-a-size-label);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: var(--nq-a-track-label);
+  color: var(--nq-a-ink-secondary);
+}
+
+.settings-input {
+  width: 100%;
+  min-height: var(--nq-a-tap-min);
+  padding: 13px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: 10px;
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 14px;
+  font-weight: 600;
+}
+
+.settings-swatches {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.settings-swatch-option {
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  border: 2px solid transparent;
+  border-radius: var(--nq-a-radius-pill);
+  cursor: pointer;
+}
+
+.settings-swatch-option[aria-pressed="true"] {
+  border-color: var(--nq-a-ink);
+  box-shadow: inset 0 0 0 2px var(--nq-a-surface);
+}
+
+.settings-error {
+  margin: 0;
+  padding: 10px 12px;
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-danger-bg);
+  color: var(--nq-a-danger-strong);
+  font-size: 12.5px;
+  font-weight: 700;
+}
+
+.settings-form-footer {
+  display: flex;
+  gap: 10px;
+}
+
+.settings-cancel,
+.settings-save {
+  padding: 15px 12px;
+  border-radius: 12px;
+  font-family: inherit;
+  font-size: 14px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.settings-cancel {
+  flex: 1;
+  border: 1px solid var(--nq-a-border);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+}
+
+.settings-save {
+  flex: 2;
+  border: 0;
+  background: var(--nq-brand-gradient);
+  color: #fff;
+}
+
+/* Preferences: one box per notification — its toggle, then its time. */
+.settings-notification {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 12px;
+  border: 1px solid var(--nq-a-divider);
+  border-radius: var(--nq-a-density-radius);
+}
+
+.settings-toggle {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: var(--nq-a-tap-min);
+  font-size: 14px;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.settings-toggle > input {
+  width: 20px;
+  height: 20px;
+  margin: 0;
+}
+
+.settings-notice {
+  margin: 0;
+  padding: 10px 12px;
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-divider);
+  color: var(--nq-a-ink-secondary);
+  font-size: 12.5px;
+  font-weight: 700;
+}

admin/src/settings/SettingsScreen.test.tsx

@@ -0,0 +1,514 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import App from "../App";
+import SettingsScreen, { SCROLL_BOTTOM_PADDING } from "./SettingsScreen";
+import type { AdminChild } from "../api/definitions";
+import type { HouseholdSettings } from "../api/settings";
+import { storeTokens } from "../auth/oidc";
+
+const CHILDREN_PATH = "/api/v1/admin/children";
+const REORDER_PATH = `${CHILDREN_PATH}/reorder`;
+const SETTINGS_PATH = "/api/v1/admin/settings";
+
+const DEFAULT_SETTINGS: HouseholdSettings = {
+  horizon_days: 14,
+  day_rollover_time: "03:00",
+  notify_target: "notify.family",
+  morning_summary_time: "07:00",
+  afternoon_reminder_time: "15:30",
+  end_of_day_report_time: "20:00",
+  morning_summary_enabled: true,
+  afternoon_reminder_enabled: false,
+  end_of_day_report_enabled: true,
+  celebration_enabled: false,
+};
+
+function child(
+  id: number,
+  display_name: string,
+  sort_order: number,
+  extra: Partial<AdminChild> = {},
+): AdminChild {
+  return { id, display_name, colour: null, avatar_ref: null, sort_order, is_active: true, ...extra };
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+interface Call {
+  method: string;
+  path: string;
+  body: unknown;
+}
+
+let children: AdminChild[];
+let settings: HouseholdSettings;
+/** Overrides the next write's response (the store is left untouched). */
+let writeResponse: (() => Response) | null;
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function calls(): Call[] {
+  return fetchMock.mock.calls.map((args: unknown[]) => {
+    const [url, init] = args as [string, RequestInit | undefined];
+    return {
+      method: init?.method ?? "GET",
+      path: new URL(String(url), "http://x").pathname,
+      body: init?.body ? JSON.parse(String(init.body)) : undefined,
+    };
+  });
+}
+
+function writes(): Call[] {
+  return calls().filter((c) => c.method !== "GET");
+}
+
+function childGets(): number {
+  return calls().filter((c) => c.method === "GET" && c.path === CHILDREN_PATH).length;
+}
+
+async function routeFetch(url: string, init: RequestInit = {}): Promise<Response> {
+  const path = new URL(url, "http://x").pathname;
+  const method = init.method ?? "GET";
+  const body = init.body ? JSON.parse(String(init.body)) : undefined;
+  if (method !== "GET" && writeResponse) {
+    const respond = writeResponse;
+    writeResponse = null;
+    return respond();
+  }
+  if (path === CHILDREN_PATH && method === "GET") return jsonResponse({ children });
+  if (path === SETTINGS_PATH && method === "GET") return jsonResponse(settings);
+  if (path === SETTINGS_PATH && method === "PATCH") {
+    settings = { ...settings, ...body };
+    return jsonResponse(settings);
+  }
+  if (path === CHILDREN_PATH && method === "POST") {
+    const created = child(9, body.display_name, body.sort_order ?? 0, {
+      colour: body.colour ?? null,
+      avatar_ref: body.avatar_ref ?? null,
+    });
+    children = [...children, created];
+    return jsonResponse(created, 201);
+  }
+  if (path === REORDER_PATH && method === "POST") {
+    const ids = body.ordered_ids as number[];
+    children = children.map((c) => ({ ...c, sort_order: ids.indexOf(c.id) + 1 }));
+    return jsonResponse({ status: "ok" });
+  }
+  const activeMatch = /\/children\/(\d+)\/active$/.exec(path);
+  if (activeMatch && method === "PATCH") {
+    const id = Number(activeMatch[1]);
+    children = children.map((c) => (c.id === id ? { ...c, is_active: body.is_active } : c));
+    return jsonResponse(children.find((c) => c.id === id));
+  }
+  const editMatch = /\/children\/(\d+)$/.exec(path);
+  if (editMatch && method === "PATCH") {
+    const id = Number(editMatch[1]);
+    children = children.map((c) => (c.id === id ? { ...c, ...body } : c));
+    return jsonResponse(children.find((c) => c.id === id));
+  }
+  if (path.endsWith("/admin/snapshot")) {
+    return jsonResponse({ today_iso: "2026-09-23", cycle_day: 5, children: [] });
+  }
+  return jsonResponse({ detail: "unexpected" }, 500);
+}
+
+function row(id: number) {
+  return within(screen.getByTestId(`settings-child-${id}`));
+}
+
+function listNames(): string[] {
+  return within(screen.getByRole("list", { name: "Children" }))
+    .getAllByRole("listitem")
+    .map((li) => li.querySelector(".settings-child-name")?.textContent ?? "");
+}
+
+function field(form: HTMLElement, label: string): HTMLInputElement {
+  return within(form).getByLabelText(label) as HTMLInputElement;
+}
+
+async function renderScreen(onClose = vi.fn()) {
+  render(<SettingsScreen onClose={onClose} />);
+  await screen.findByTestId("settings-child-1");
+  return onClose;
+}
+
+describe("SettingsScreen — children", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    children = [
+      child(2, "Maeve", 2, { colour: "#16a34a" }),
+      child(1, "Declan", 1, { colour: "#0ea5e9", avatar_ref: "fox" }),
+      child(3, "Rory", 3, { is_active: false }),
+    ];
+    settings = { ...DEFAULT_SETTINGS };
+    writeResponse = null;
+    fetchMock = vi.fn(async (url: string, init?: RequestInit) => routeFetch(url, init));
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("lists each child with name, colour swatch, active state and order", async () => {
+    await renderScreen();
+    expect(listNames()).toEqual(["Declan", "Maeve", "Rory"]);
+    expect(row(1).getByText("Order 1 · #0ea5e9")).toBeTruthy();
+    expect(screen.getByTestId("settings-swatch-1").style.background).toBe("rgb(14, 165, 233)");
+    expect(screen.getByTestId("settings-active-1").textContent).toBe("Active");
+    expect(row(3).getByText("Order 3 · no colour")).toBeTruthy();
+    expect(screen.getByTestId("settings-swatch-3").style.background).toBe("var(--nq-a-border)");
+    expect(screen.getByTestId("settings-active-3").textContent).toBe("Inactive");
+    expect(screen.getByTestId("settings-scroll").style.paddingBottom).toBe(SCROLL_BOTTOM_PADDING);
+  });
+
+  it("Add posts exactly the entered values, then shows the new child", async () => {
+    await renderScreen();
+    fireEvent.click(screen.getByRole("button", { name: "Add child" }));
+    const form = screen.getByRole("form", { name: "Add child" });
+    expect(field(form, "Order").value).toBe("4");
+    fireEvent.change(field(form, "Display name"), { target: { value: "  Nora " } });
+    fireEvent.click(within(form).getByRole("button", { name: "Colour #7c3aed" }));
+    fireEvent.change(field(form, "Avatar ref (optional)"), { target: { value: "owl" } });
+    fireEvent.change(field(form, "Order"), { target: { value: "5" } });
+    const gets = childGets();
+    fireEvent.click(within(form).getByRole("button", { name: "Add child" }));
+
+    await screen.findByTestId("settings-child-9");
+    expect(writes()).toEqual([
+      {
+        method: "POST",
+        path: CHILDREN_PATH,
+        body: { display_name: "Nora", colour: "#7c3aed", avatar_ref: "owl", sort_order: 5 },
+      },
+    ]);
+    expect(childGets()).toBe(gets + 1);
+    expect(listNames()).toEqual(["Declan", "Maeve", "Rory", "Nora"]);
+    expect(screen.queryByRole("form", { name: "Add child" })).toBeNull();
+  });
+
+  it("Add omits optional fields left blank and rejects a missing name", async () => {
+    await renderScreen();
+    fireEvent.click(screen.getByRole("button", { name: "Add child" }));
+    const form = screen.getByRole("form", { name: "Add child" });
+    fireEvent.change(field(form, "Order"), { target: { value: "" } });
+    fireEvent.click(within(form).getByRole("button", { name: "Add child" }));
+    expect(screen.getByTestId("child-form-error").textContent).toBe("Enter a display name.");
+    expect(writes()).toEqual([]);
+
+    fireEvent.change(field(form, "Display name"), { target: { value: "Nora" } });
+    fireEvent.click(within(form).getByRole("button", { name: "Add child" }));
+    await screen.findByTestId("settings-child-9");
+    expect(writes()[0].body).toEqual({ display_name: "Nora" });
+  });
+
+  it("Edit patches only the changed fields", async () => {
+    await renderScreen();
+    fireEvent.click(row(1).getByRole("button", { name: "Edit Declan" }));
+    const form = screen.getByRole("form", { name: "Edit Declan" });
+    expect(field(form, "Display name").value).toBe("Declan");
+    expect(field(form, "Colour").value).toBe("#0ea5e9");
+    fireEvent.change(field(form, "Display name"), { target: { value: "Dec" } });
+    fireEvent.change(field(form, "Colour"), { target: { value: "#FF8800" } });
+    fireEvent.click(within(form).getByRole("button", { name: "Save child" }));
+
+    await waitFor(() => expect(row(1).getByText("Dec")).toBeTruthy());
+    expect(writes()).toEqual([
+      { method: "PATCH", path: `${CHILDREN_PATH}/1`, body: { display_name: "Dec", colour: "#FF8800" } },
+    ]);
+    expect(row(1).getByText("Order 1 · #FF8800")).toBeTruthy();
+  });
+
+  it("Edit refuses to clear a set colour instead of sending null", async () => {
+    await renderScreen();
+    fireEvent.click(row(1).getByRole("button", { name: "Edit Declan" }));
+    const form = screen.getByRole("form", { name: "Edit Declan" });
+    fireEvent.change(field(form, "Colour"), { target: { value: "" } });
+    fireEvent.click(within(form).getByRole("button", { name: "Save child" }));
+    expect(screen.getByTestId("child-form-error").textContent).toMatch(/cannot be removed/);
+    expect(writes()).toEqual([]);
+  });
+
+  it("the active toggle patches /children/{id}/active with the new value", async () => {
+    await renderScreen();
+    fireEvent.click(row(1).getByRole("button", { name: "Deactivate Declan" }));
+    await waitFor(() => expect(screen.getByTestId("settings-active-1").textContent).toBe("Inactive"));
+    fireEvent.click(row(3).getByRole("button", { name: "Reactivate Rory" }));
+    await waitFor(() => expect(screen.getByTestId("settings-active-3").textContent).toBe("Active"));
+    expect(writes()).toEqual([
+      { method: "PATCH", path: `${CHILDREN_PATH}/1/active`, body: { is_active: false } },
+      { method: "PATCH", path: `${CHILDREN_PATH}/3/active`, body: { is_active: true } },
+    ]);
+  });
+
+  it("reorder posts the complete ordered id list, then shows the new order", async () => {
+    await renderScreen();
+    expect((row(1).getByRole("button", { name: "Move Declan up" }) as HTMLButtonElement).disabled).toBe(true);
+    expect((row(3).getByRole("button", { name: "Move Rory down" }) as HTMLButtonElement).disabled).toBe(true);
+    fireEvent.click(row(3).getByRole("button", { name: "Move Rory up" }));
+    await waitFor(() => expect(listNames()).toEqual(["Declan", "Rory", "Maeve"]));
+    expect(writes()).toEqual([{ method: "POST", path: REORDER_PATH, body: { ordered_ids: [1, 3, 2] } }]);
+  });
+
+  it("disables the write controls while a request is in flight (no double submit)", async () => {
+    await renderScreen();
+    let release!: () => void;
+    writeResponse = () => jsonResponse({ status: "ok" });
+    const gate = new Promise<void>((r) => {
+      release = r;
+    });
+    fetchMock.mockImplementationOnce(async (url: string, init?: RequestInit) => {
+      await gate;
+      return routeFetch(url, init);
+    });
+    const up = row(2).getByRole("button", { name: "Move Maeve up" }) as HTMLButtonElement;
+    fireEvent.click(up);
+    fireEvent.click(up);
+    await waitFor(() => expect(up.disabled).toBe(true));
+    expect((row(1).getByRole("button", { name: "Deactivate Declan" }) as HTMLButtonElement).disabled).toBe(true);
+    expect(writes()).toHaveLength(1);
+    release();
+    await waitFor(() => expect((row(1).getByRole("button", { name: "Edit Declan" }) as HTMLButtonElement).disabled).toBe(false));
+    expect(writes()).toHaveLength(1);
+  });
+
+  it("a 422 shows the API detail and keeps the form and the screen open", async () => {
+    const onClose = await renderScreen();
+    fireEvent.click(screen.getByRole("button", { name: "Add child" }));
+    const form = screen.getByRole("form", { name: "Add child" });
+    fireEvent.change(field(form, "Display name"), { target: { value: "Nora" } });
+    writeResponse = () => jsonResponse({ detail: "display_name is required" }, 422);
+    fireEvent.click(within(form).getByRole("button", { name: "Add child" }));
+
+    const error = await screen.findByTestId("child-form-error");
+    expect(error.textContent).toBe("The child could not be added: display_name is required");
+    expect(screen.getByRole("form", { name: "Add child" })).toBeTruthy();
+    expect(field(form, "Display name").value).toBe("Nora");
+    expect(onClose).not.toHaveBeenCalled();
+    expect(screen.getByRole("dialog", { name: "Settings" })).toBeTruthy();
+  });
+
+  it("a 403 on a row action shows the refusal message and keeps the screen open", async () => {
+    const onClose = await renderScreen();
+    writeResponse = () => jsonResponse({ detail: "forbidden" }, 403);
+    fireEvent.click(row(1).getByRole("button", { name: "Deactivate Declan" }));
+    const error = await screen.findByTestId("settings-action-error");
+    expect(error.textContent).toContain("Your account is not in the nestquest-admins group.");
+    expect(screen.getByTestId("settings-active-1").textContent).toBe("Active");
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("a 403 on load shows the refusal message", async () => {
+    fetchMock.mockImplementation(async () => jsonResponse({ detail: "forbidden" }, 403));
+    render(<SettingsScreen onClose={vi.fn()} />);
+    const error = await screen.findByTestId("settings-error");
+    expect(error.textContent).toContain("Your account is not in the nestquest-admins group.");
+  });
+
+  it("Escape and Back close the screen", async () => {
+    const onClose = await renderScreen();
+    fireEvent.keyDown(screen.getByRole("dialog", { name: "Settings" }), { key: "Escape" });
+    expect(onClose).toHaveBeenCalledTimes(1);
+    fireEvent.click(screen.getByRole("button", { name: "Back" }));
+    expect(onClose).toHaveBeenCalledTimes(2);
+  });
+
+  it("the Today Settings button opens the screen; closing restores focus and the background", async () => {
+    render(<App />);
+    const settings = await screen.findByRole("button", { name: "Settings" });
+    settings.focus();
+    fireEvent.click(settings);
+
+    const dialog = await screen.findByRole("dialog", { name: "Settings" });
+    await screen.findByTestId("settings-child-1");
+    expect(document.activeElement).toBe(screen.getByRole("heading", { name: "Settings" }));
+    const tabbar = document.querySelector("nav.admin-tabbar") as HTMLElement;
+    expect(tabbar.hasAttribute("inert")).toBe(true);
+    expect(dialog.closest("[inert]")).toBeNull();
+
+    fireEvent.keyDown(dialog, { key: "Escape" });
+    await waitFor(() => expect(screen.queryByRole("dialog", { name: "Settings" })).toBeNull());
+    expect(tabbar.hasAttribute("inert")).toBe(false);
+    expect(document.activeElement).toBe(screen.getByRole("button", { name: "Settings" }));
+  });
+});
+
+describe("SettingsScreen — preferences", () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    children = [child(1, "Declan", 1)];
+    settings = { ...DEFAULT_SETTINGS };
+    writeResponse = null;
+    fetchMock = vi.fn(async (url: string, init?: RequestInit) => routeFetch(url, init));
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  async function renderPreferences(onClose = vi.fn()) {
+    render(<SettingsScreen onClose={onClose} />);
+    await screen.findByTestId("settings-child-1");
+    const form = await screen.findByRole("form", { name: "Preferences" });
+    return { form, onClose };
+  }
+
+  function checkbox(form: HTMLElement, label: string): HTMLInputElement {
+    return within(form).getByRole("checkbox", { name: label }) as HTMLInputElement;
+  }
+
+  function save(form: HTMLElement) {
+    fireEvent.click(within(form).getByRole("button", { name: "Save preferences" }));
+  }
+
+  it("renders the current value of all ten fields", async () => {
+    const { form } = await renderPreferences();
+    expect(field(form, "Planning horizon (days)").value).toBe("14");
+    expect(field(form, "Day rollover").value).toBe("03:00");
+    expect(field(form, "Notify target").value).toBe("notify.family");
+    expect(field(form, "Morning summary time").value).toBe("07:00");
+    expect(field(form, "Afternoon reminder time").value).toBe("15:30");
+    expect(field(form, "End-of-day report time").value).toBe("20:00");
+    expect(checkbox(form, "Morning summary").checked).toBe(true);
+    expect(checkbox(form, "Afternoon reminder").checked).toBe(false);
+    expect(checkbox(form, "End-of-day report").checked).toBe(true);
+    expect(checkbox(form, "Celebration").checked).toBe(false);
+  });
+
+  it("saving one changed field patches exactly that field", async () => {
+    const { form } = await renderPreferences();
+    fireEvent.change(field(form, "Planning horizon (days)"), { target: { value: "21" } });
+    save(form);
+    await screen.findByText("Preferences saved.");
+    expect(writes()).toEqual([{ method: "PATCH", path: SETTINGS_PATH, body: { horizon_days: 21 } }]);
+    const reloaded = screen.getByRole("form", { name: "Preferences" });
+    expect(field(reloaded, "Planning horizon (days)").value).toBe("21");
+  });
+
+  it("saving several changed fields sends exactly those", async () => {
+    const { form } = await renderPreferences();
+    fireEvent.change(field(form, "Day rollover"), { target: { value: "04:15" } });
+    fireEvent.change(field(form, "Notify target"), { target: { value: " notify.parents " } });
+    fireEvent.change(field(form, "End-of-day report time"), { target: { value: "21:45" } });
+    fireEvent.click(checkbox(form, "Afternoon reminder"));
+    fireEvent.click(checkbox(form, "Celebration"));
+    save(form);
+    await screen.findByText("Preferences saved.");
+    expect(writes()).toEqual([
+      {
+        method: "PATCH",
+        path: SETTINGS_PATH,
+        body: {
+          day_rollover_time: "04:15",
+          notify_target: "notify.parents",
+          end_of_day_report_time: "21:45",
+          afternoon_reminder_enabled: true,
+          celebration_enabled: true,
+        },
+      },
+    ]);
+    const reloaded = screen.getByRole("form", { name: "Preferences" });
+    expect(checkbox(reloaded, "Celebration").checked).toBe(true);
+    expect(field(reloaded, "Notify target").value).toBe("notify.parents");
+  });
+
+  it("with nothing changed it says so and sends no request", async () => {
+    const { form } = await renderPreferences();
+    fireEvent.click(checkbox(form, "Celebration"));
+    fireEvent.click(checkbox(form, "Celebration"));
+    save(form);
+    expect(screen.getByTestId("preferences-message").textContent).toBe("No changes to save.");
+    expect(writes()).toEqual([]);
+  });
+
+  it("a 422 shows the API detail naming the field and keeps the edit", async () => {
+    const { form, onClose } = await renderPreferences();
+    fireEvent.change(field(form, "Notify target"), { target: { value: "notify.nobody" } });
+    writeResponse = () => jsonResponse({ detail: "notify_target is not a notify service" }, 422);
+    save(form);
+    const message = await screen.findByTestId("preferences-message");
+    expect(message.textContent).toBe(
+      "The preferences could not be saved: notify_target is not a notify service",
+    );
+    expect(message.getAttribute("role")).toBe("alert");
+    expect(field(form, "Notify target").value).toBe("notify.nobody");
+    expect(writes()).toEqual([
+      { method: "PATCH", path: SETTINGS_PATH, body: { notify_target: "notify.nobody" } },
+    ]);
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("a 403 on save shows the refusal message", async () => {
+    const { form } = await renderPreferences();
+    fireEvent.click(checkbox(form, "Celebration"));
+    writeResponse = () => jsonResponse({ detail: "forbidden" }, 403);
+    save(form);
+    const message = await screen.findByTestId("preferences-message");
+    expect(message.textContent).toContain("Your account is not in the nestquest-admins group.");
+    expect(checkbox(form, "Celebration").checked).toBe(true);
+  });
+
+  it.each([
+    ["empty", ""],
+    ["zero", "0"],
+    ["oversized (Infinity would serialize as null and reset the field)", "9".repeat(400)],
+    ["past the safe-integer range", "123456789012345678901"],
+  ])("a %s horizon is rejected before any request", async (_case, value) => {
+    const { form } = await renderPreferences();
+    fireEvent.change(field(form, "Planning horizon (days)"), { target: { value } });
+    save(form);
+    expect(screen.getByTestId("preferences-message").textContent).toBe(
+      "Planning horizon must be a whole number of days, at least 1.",
+    );
+    expect(writes()).toEqual([]);
+  });
+
+  it("disables every write control while a save is in flight (no double submit)", async () => {
+    const { form } = await renderPreferences();
+    let release!: () => void;
+    const gate = new Promise<void>((r) => {
+      release = r;
+    });
+    fetchMock.mockImplementationOnce(async (url: string, init?: RequestInit) => {
+      await gate;
+      return routeFetch(url, init);
+    });
+    fireEvent.click(checkbox(form, "Celebration"));
+    const button = within(form).getByRole("button", { name: "Save preferences" }) as HTMLButtonElement;
+    fireEvent.click(button);
+    fireEvent.click(button);
+    await waitFor(() => expect(button.disabled).toBe(true));
+    expect(checkbox(form, "Celebration").disabled).toBe(true);
+    expect(field(form, "Planning horizon (days)").disabled).toBe(true);
+    expect((row(1).getByRole("button", { name: "Edit Declan" }) as HTMLButtonElement).disabled).toBe(true);
+    expect(writes()).toHaveLength(1);
+    release();
+    await screen.findByText("Preferences saved.");
+    expect(writes()).toHaveLength(1);
+  });
+
+  it("a failed load shows the reason and Try again refetches", async () => {
+    let fail = true;
+    fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
+      if (fail && new URL(url, "http://x").pathname === SETTINGS_PATH) {
+        return jsonResponse({ detail: "boom" }, 500);
+      }
+      return routeFetch(url, init);
+    });
+    render(<SettingsScreen onClose={vi.fn()} />);
+    const error = await screen.findByTestId("preferences-error");
+    expect(error.textContent).toContain("Preferences could not be loaded: boom");
+    fail = false;
+    fireEvent.click(within(error).getByRole("button", { name: "Try again" }));
+    await screen.findByRole("form", { name: "Preferences" });
+  });
+});

admin/src/settings/SettingsScreen.tsx

@@ -0,0 +1,811 @@
+/**
+ * Settings — a pushed screen opened from the Today header's Settings button.
+ *
+ * Children: list, add, edit, deactivate/reactivate and reorder the
+ * household's child profiles. Every write refetches the list.
+ *
+ * Preferences: the household settings (planning horizon, day rollover,
+ * notifications). Save patches only the changed fields.
+ *
+ * One write at a time across both sections.
+ */
+import {
+  useEffect,
+  useRef,
+  useState,
+  type FormEvent,
+  type KeyboardEvent as ReactKeyboardEvent,
+} from "react";
+import { ApiForbiddenError } from "../api/client";
+import {
+  createChild,
+  reorderChildren,
+  setChildActive,
+  updateChild,
+  type ChildCreateBody,
+  type ChildEditBody,
+} from "../api/children";
+import { ApiRequestError, fetchChildren, type AdminChild } from "../api/definitions";
+import {
+  fetchSettings,
+  updateSettings,
+  type HouseholdSettings,
+  type SettingsChanges,
+} from "../api/settings";
+import { FOCUSABLE, inertOutside } from "../schedule/OverrideEditor";
+import { ArrowDownGlyph, ArrowUpGlyph, ChevronLeftGlyph, PlusGlyph } from "./glyphs";
+import "./SettingsScreen.css";
+
+/** The swatch picker's presets; any other "#RRGGBB" can be typed. */
+export const COLOUR_PRESETS = ["#e11d48", "#f97316", "#eab308", "#16a34a", "#0ea5e9", "#7c3aed"];
+
+/** ADMIN-SPEC §1: every scroll column ends with 92px so content clears the tab bar. */
+export const SCROLL_BOTTOM_PADDING = "92px";
+
+const HEX_COLOUR = /^#[0-9a-fA-F]{6}$/;
+
+type LoadState =
+  | { kind: "loading" }
+  | { kind: "error"; message: string }
+  | { kind: "ready"; children: AdminChild[] };
+
+type FormTarget = null | "new" | AdminChild;
+
+interface Draft {
+  name: string;
+  colour: string;
+  avatar: string;
+  order: string;
+}
+
+/** Display order: sort_order, ties broken by id (the API's own order). */
+function sortChildren(children: AdminChild[]): AdminChild[] {
+  return [...children].sort((a, b) => a.sort_order - b.sort_order || a.id - b.id);
+}
+
+function errorMessage(error: unknown, action: string): string {
+  if (error instanceof ApiForbiddenError) return error.message;
+  if (error instanceof ApiRequestError && error.detail) return `${action}: ${error.detail}`;
+  return `${action}. Check your connection and try again.`;
+}
+
+function draftFor(target: "new" | AdminChild, siblings: AdminChild[]): Draft {
+  if (target === "new") {
+    const next = siblings.reduce((max, c) => Math.max(max, c.sort_order), 0) + 1;
+    return { name: "", colour: "", avatar: "", order: String(next) };
+  }
+  return {
+    name: target.display_name,
+    colour: target.colour ?? "",
+    avatar: target.avatar_ref ?? "",
+    order: String(target.sort_order),
+  };
+}
+
+/** The request body for the draft, or a validation message. */
+function buildBody(
+  draft: Draft,
+  target: "new" | AdminChild,
+): ChildCreateBody | ChildEditBody | string {
+  const name = draft.name.trim();
+  const colour = draft.colour.trim();
+  const avatar = draft.avatar.trim();
+  const order = draft.order.trim();
+  if (!name) return "Enter a display name.";
+  if (colour && !HEX_COLOUR.test(colour)) return "Colour must be a hex value like #0ea5e9.";
+  if (order && !/^-?\d+$/.test(order)) return "Order must be a whole number.";
+
+  if (target === "new") {
+    const body: ChildCreateBody = { display_name: name };
+    if (colour) body.colour = colour;
+    if (avatar) body.avatar_ref = avatar;
+    if (order) body.sort_order = Number(order);
+    return body;
+  }
+
+  // The API rejects null, so a set colour, avatar or order cannot be cleared.
+  if (!colour && target.colour !== null) return "A colour, once set, cannot be removed. Pick another.";
+  if (!avatar && target.avatar_ref !== null) return "An avatar ref, once set, cannot be removed.";
+  if (!order) return "Enter an order.";
+  const body: ChildEditBody = {};
+  if (name !== target.display_name) body.display_name = name;
+  if (colour && colour !== target.colour) body.colour = colour;
+  if (avatar && avatar !== target.avatar_ref) body.avatar_ref = avatar;
+  if (Number(order) !== target.sort_order) body.sort_order = Number(order);
+  if (Object.keys(body).length === 0) return "No changes to save.";
+  return body;
+}
+
+function ChildForm({
+  target,
+  siblings,
+  saving,
+  error,
+  onCancel,
+  onSubmit,
+}: {
+  target: "new" | AdminChild;
+  /** The current list; a new child's order defaults to after the last. */
+  siblings: AdminChild[];
+  saving: boolean;
+  error: string | null;
+  onCancel: () => void;
+  onSubmit: (body: ChildCreateBody | ChildEditBody | string) => void;
+}) {
+  const [draft, setDraft] = useState<Draft>(() => draftFor(target, siblings));
+  const nameRef = useRef<HTMLInputElement>(null);
+  const update = (patch: Partial<Draft>) => setDraft((d) => ({ ...d, ...patch }));
+  const isNew = target === "new";
+  const title = isNew ? "Add child" : `Edit ${target.display_name}`;
+
+  useEffect(() => {
+    nameRef.current?.focus();
+  }, []);
+
+  function submit(event: FormEvent) {
+    event.preventDefault();
+    onSubmit(buildBody(draft, target));
+  }
+
+  return (
+    <form className="settings-card settings-form" aria-label={title} onSubmit={submit} noValidate>
+      <h4 className="settings-form-title">{title}</h4>
+      <label className="settings-field">
+        <span className="settings-label">Display name</span>
+        <input
+          ref={nameRef}
+          className="settings-input"
+          type="text"
+          required
+          value={draft.name}
+          disabled={saving}
+          onChange={(event) => update({ name: event.target.value })}
+        />
+      </label>
+      <div className="settings-field">
+        <label className="settings-field">
+          <span className="settings-label">Colour</span>
+          <input
+            className="settings-input"
+            type="text"
+            placeholder="#0ea5e9"
+            value={draft.colour}
+            disabled={saving}
+            onChange={(event) => update({ colour: event.target.value })}
+          />
+        </label>
+        <div className="settings-swatches" role="group" aria-label="Colour presets">
+          {COLOUR_PRESETS.map((hex) => (
+            <button
+              key={hex}
+              type="button"
+              className="settings-swatch-option"
+              style={{ background: hex }}
+              aria-label={`Colour ${hex}`}
+              aria-pressed={draft.colour.toLowerCase() === hex}
+              disabled={saving}
+              onClick={() => update({ colour: hex })}
+            />
+          ))}
+        </div>
+      </div>
+      <label className="settings-field">
+        <span className="settings-label">Avatar ref (optional)</span>
+        <input
+          className="settings-input"
+          type="text"
+          value={draft.avatar}
+          disabled={saving}
+          onChange={(event) => update({ avatar: event.target.value })}
+        />
+      </label>
+      <label className="settings-field">
+        <span className="settings-label">Order</span>
+        <input
+          className="settings-input"
+          type="text"
+          inputMode="numeric"
+          value={draft.order}
+          disabled={saving}
+          onChange={(event) => update({ order: event.target.value })}
+        />
+      </label>
+      {error ? (
+        <p className="settings-error" role="alert" data-testid="child-form-error">
+          {error}
+        </p>
+      ) : null}
+      <div className="settings-form-footer">
+        <button type="button" className="settings-cancel" disabled={saving} onClick={onCancel}>
+          Cancel
+        </button>
+        <button type="submit" className="settings-save" disabled={saving} aria-busy={saving}>
+          {saving ? "Saving…" : isNew ? "Add child" : "Save child"}
+        </button>
+      </div>
+    </form>
+  );
+}
+
+type PreferencesState =
+  | { kind: "loading" }
+  | { kind: "error"; message: string }
+  | { kind: "ready"; settings: HouseholdSettings };
+
+type TimeField =
+  | "day_rollover_time"
+  | "morning_summary_time"
+  | "afternoon_reminder_time"
+  | "end_of_day_report_time";
+
+type ToggleField =
+  | "morning_summary_enabled"
+  | "afternoon_reminder_enabled"
+  | "end_of_day_report_enabled"
+  | "celebration_enabled";
+
+const NOTIFICATIONS: { label: string; time: TimeField; toggle: ToggleField }[] = [
+  { label: "Morning summary", time: "morning_summary_time", toggle: "morning_summary_enabled" },
+  { label: "Afternoon reminder", time: "afternoon_reminder_time", toggle: "afternoon_reminder_enabled" },
+  { label: "End-of-day report", time: "end_of_day_report_time", toggle: "end_of_day_report_enabled" },
+];
+
+const HH_MM = /^([01]\d|2[0-3]):[0-5]\d$/;
+
+/** The form's working copy: the number is text so it can be mid-edit. */
+type PreferencesDraft = Omit<HouseholdSettings, "horizon_days"> & { horizon_days: string };
+
+function preferencesDraft(settings: HouseholdSettings): PreferencesDraft {
+  return { ...settings, horizon_days: String(settings.horizon_days) };
+}
+
+/** Only the fields that differ from `loaded`, or a validation message. */
+function buildChanges(draft: PreferencesDraft, loaded: HouseholdSettings): SettingsChanges | string {
+  const horizon = draft.horizon_days.trim();
+  const horizonDays = Number(horizon);
+  // A digit string too long for a safe integer would become Infinity, which
+  // JSON serializes as null, and the API reads null as "reset to default".
+  if (!/^\d+$/.test(horizon) || !Number.isSafeInteger(horizonDays) || horizonDays < 1) {
+    return "Planning horizon must be a whole number of days, at least 1.";
+  }
+  const times: [TimeField, string][] = [
+    ["day_rollover_time", "Day rollover"],
+    ...NOTIFICATIONS.map((n): [TimeField, string] => [n.time, `${n.label} time`]),
+  ];
+  for (const [key, label] of times) {
+    if (!HH_MM.test(draft[key])) return `${label} must be a time like 07:30.`;
+  }
+
+  const next: HouseholdSettings = {
+    ...draft,
+    horizon_days: horizonDays,
+    notify_target: draft.notify_target.trim(),
+  };
+  const changes: SettingsChanges = {};
+  for (const key of Object.keys(loaded) as (keyof HouseholdSettings)[]) {
+    if (next[key] !== loaded[key]) (changes as Record<string, unknown>)[key] = next[key];
+  }
+  if (Object.keys(changes).length === 0) return "No changes to save.";
+  return changes;
+}
+
+function PreferencesForm({
+  settings,
+  saving,
+  locked,
+  message,
+  onSubmit,
+}: {
+  settings: HouseholdSettings;
+  saving: boolean;
+  /** Another write is in flight. */
+  locked: boolean;
+  message: { kind: "error" | "info"; text: string } | null;
+  onSubmit: (changes: SettingsChanges | string) => void;
+}) {
+  const [draft, setDraft] = useState<PreferencesDraft>(() => preferencesDraft(settings));
+  const update = (patch: Partial<PreferencesDraft>) => setDraft((d) => ({ ...d, ...patch }));
+  const disabled = saving || locked;
+
+  function submit(event: FormEvent) {
+    event.preventDefault();
+    onSubmit(buildChanges(draft, settings));
+  }
+
+  function timeInput(key: TimeField, label: string) {
+    return (
+      <label className="settings-field">
+        <span className="settings-label">{label}</span>
+        <input
+          className="settings-input"
+          type="time"
+          value={draft[key]}
+          disabled={disabled}
+          onChange={(event) => update({ [key]: event.target.value })}
+        />
+      </label>
+    );
+  }
+
+  function toggle(key: ToggleField, label: string) {
+    return (
+      <label className="settings-toggle">
+        <input
+          type="checkbox"
+          checked={draft[key]}
+          disabled={disabled}
+          onChange={(event) => update({ [key]: event.target.checked })}
+        />
+        <span>{label}</span>
+      </label>
+    );
+  }
+
+  return (
+    <form className="settings-card settings-form" aria-label="Preferences" onSubmit={submit} noValidate>
+      <label className="settings-field">
+        <span className="settings-label">Planning horizon (days)</span>
+        <input
+          className="settings-input"
+          type="number"
+          min={1}
+          step={1}
+          inputMode="numeric"
+          value={draft.horizon_days}
+          disabled={disabled}
+          onChange={(event) => update({ horizon_days: event.target.value })}
+        />
+      </label>
+      {timeInput("day_rollover_time", "Day rollover")}
+      <label className="settings-field">
+        <span className="settings-label">Notify target</span>
+        <input
+          className="settings-input"
+          type="text"
+          value={draft.notify_target}
+          disabled={disabled}
+          onChange={(event) => update({ notify_target: event.target.value })}
+        />
+      </label>
+      {NOTIFICATIONS.map((n) => (
+        <div key={n.toggle} className="settings-notification">
+          {toggle(n.toggle, n.label)}
+          {timeInput(n.time, `${n.label} time`)}
+        </div>
+      ))}
+      {toggle("celebration_enabled", "Celebration")}
+      {message ? (
+        <p
+          className={message.kind === "error" ? "settings-error" : "settings-notice"}
+          role={message.kind === "error" ? "alert" : "status"}
+          data-testid="preferences-message"
+        >
+          {message.text}
+        </p>
+      ) : null}
+      <div className="settings-form-footer">
+        <button type="submit" className="settings-save" disabled={disabled} aria-busy={saving}>
+          {saving ? "Saving…" : "Save preferences"}
+        </button>
+      </div>
+    </form>
+  );
+}
+
+function ChildRow({
+  child,
+  index,
+  count,
+  busy,
+  onEdit,
+  onMove,
+  onToggleActive,
+}: {
+  child: AdminChild;
+  index: number;
+  count: number;
+  /** The in-flight action key, or null. Every write control waits on it. */
+  busy: string | null;
+  onEdit: () => void;
+  onMove: (delta: -1 | 1) => void;
+  onToggleActive: () => void;
+}) {
+  const locked = busy !== null;
+  const toggling = busy === `active-${child.id}`;
+  return (
+    <li
+      className={child.is_active ? "settings-child" : "settings-child settings-child--inactive"}
+      data-testid={`settings-child-${child.id}`}
+    >
+      <span
+        className="settings-swatch"
+        data-testid={`settings-swatch-${child.id}`}
+        style={{ background: child.colour ?? "var(--nq-a-border)" }}
+        aria-hidden="true"
+      />
+      <div className="settings-child-text">
+        <div className="settings-child-name">{child.display_name}</div>
+        <div className="settings-child-meta">
+          Order {child.sort_order} · {child.colour ?? "no colour"}
+        </div>
+      </div>
+      <span
+        className={child.is_active ? "settings-pill settings-pill--active" : "settings-pill"}
+        data-testid={`settings-active-${child.id}`}
+      >
+        {child.is_active ? "Active" : "Inactive"}
+      </span>
+      <div className="settings-child-actions">
+        <button
+          type="button"
+          className="settings-icon-button"
+          aria-label={`Move ${child.display_name} up`}
+          aria-busy={busy === `move-${child.id}`}
+          disabled={locked || index === 0}
+          onClick={() => onMove(-1)}
+        >
+          <ArrowUpGlyph />
+        </button>
+        <button
+          type="button"
+          className="settings-icon-button"
+          aria-label={`Move ${child.display_name} down`}
+          aria-busy={busy === `move-${child.id}`}
+          disabled={locked || index === count - 1}
+          onClick={() => onMove(1)}
+        >
+          <ArrowDownGlyph />
+        </button>
+        <button
+          type="button"
+          className="settings-action"
+          aria-label={`Edit ${child.display_name}`}
+          disabled={locked}
+          onClick={onEdit}
+        >
+          Edit
+        </button>
+        <button
+          type="button"
+          className="settings-action"
+          aria-label={`${child.is_active ? "Deactivate" : "Reactivate"} ${child.display_name}`}
+          aria-busy={toggling}
+          disabled={locked}
+          onClick={onToggleActive}
+        >
+          {toggling ? "Saving…" : child.is_active ? "Deactivate" : "Reactivate"}
+        </button>
+      </div>
+    </li>
+  );
+}
+
+export default function SettingsScreen({ onClose }: { onClose: () => void }) {
+  const [state, setState] = useState<LoadState>({ kind: "loading" });
+  const [attempt, setAttempt] = useState(0);
+  const [form, setForm] = useState<FormTarget>(null);
+  const [formError, setFormError] = useState<string | null>(null);
+  const [actionError, setActionError] = useState<string | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [preferences, setPreferences] = useState<PreferencesState>({ kind: "loading" });
+  const [preferencesAttempt, setPreferencesAttempt] = useState(0);
+  const [preferencesMessage, setPreferencesMessage] = useState<{
+    kind: "error" | "info";
+    text: string;
+  } | null>(null);
+  // A ref, not state: two taps in one frame must not both see `busy === null`.
+  const inFlight = useRef(false);
+  const screenRef = useRef<HTMLDivElement>(null);
+  const titleRef = useRef<HTMLHeadingElement>(null);
+  const addRef = useRef<HTMLButtonElement>(null);
+  const formWasOpen = useRef(false);
+
+  // Modal focus: move in on open, keep the background out of reach, and hand
+  // focus back to the opener (the Settings button) on close.
+  useEffect(() => {
+    const trigger = document.activeElement as HTMLElement | null;
+    titleRef.current?.focus();
+    const restoreBackground = screenRef.current ? inertOutside(screenRef.current) : undefined;
+    return () => {
+      restoreBackground?.();
+      if (trigger && trigger.isConnected) trigger.focus();
+    };
+  }, []);
+
+  // The form's controls unmount when it closes; hand focus to Add child then
+  // (after the render that re-enables it).
+  useEffect(() => {
+    if (formWasOpen.current && form === null) addRef.current?.focus();
+    formWasOpen.current = form !== null;
+  }, [form]);
+
+  useEffect(() => {
+    let cancelled = false;
+    setState((current) => (current.kind === "ready" ? current : { kind: "loading" }));
+    fetchChildren()
+      .then((children) => {
+        if (!cancelled) setState({ kind: "ready", children: sortChildren(children) });
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        setState({ kind: "error", message: errorMessage(error, "Children could not be loaded") });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [attempt]);
+
+  useEffect(() => {
+    let cancelled = false;
+    setPreferences({ kind: "loading" });
+    fetchSettings()
+      .then((settings) => {
+        if (!cancelled) setPreferences({ kind: "ready", settings });
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        setPreferences({ kind: "error", message: errorMessage(error, "Preferences could not be loaded") });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [preferencesAttempt]);
+
+  function onKeyDown(event: ReactKeyboardEvent<HTMLDivElement>) {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      if (!inFlight.current) onClose();
+      return;
+    }
+    if (event.key !== "Tab" || !screenRef.current) return;
+    const focusable = Array.from(screenRef.current.querySelectorAll<HTMLElement>(FOCUSABLE));
+    if (focusable.length === 0) return;
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const current = document.activeElement;
+    const outside = !focusable.includes(current as HTMLElement);
+    if (event.shiftKey && (current === first || outside)) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && (current === last || outside)) {
+      event.preventDefault();
+      first.focus();
+    }
+  }
+
+  /**
+   * Run one write, then refetch the list. One write at a time; a failure
+   * keeps the screen (and any open form) as it was and says why.
+   */
+  async function run(key: string, write: () => Promise<unknown>, action: string): Promise<boolean> {
+    if (inFlight.current) return false;
+    inFlight.current = true;
+    setBusy(key);
+    setActionError(null);
+    setFormError(null);
+    try {
+      await write();
+    } catch (error) {
+      const message = errorMessage(error, action);
+      if (key === "form") setFormError(message);
+      else setActionError(message);
+      inFlight.current = false;
+      setBusy(null);
+      return false;
+    }
+    try {
+      const children = await fetchChildren();
+      setState({ kind: "ready", children: sortChildren(children) });
+    } catch (error) {
+      setActionError(errorMessage(error, "Saved, but the children list could not be refreshed"));
+    }
+    inFlight.current = false;
+    setBusy(null);
+    return true;
+  }
+
+  function closeForm() {
+    setForm(null);
+    setFormError(null);
+  }
+
+  async function submitForm(body: ChildCreateBody | ChildEditBody | string) {
+    if (form === null) return;
+    if (typeof body === "string") {
+      setFormError(body);
+      return;
+    }
+    const saved =
+      form === "new"
+        ? await run("form", () => createChild(body as ChildCreateBody), "The child could not be added")
+        : await run("form", () => updateChild(form.id, body), "The child could not be saved");
+    if (saved) closeForm();
+  }
+
+  async function savePreferences(changes: SettingsChanges | string) {
+    if (typeof changes === "string") {
+      setPreferencesMessage({ kind: changes === "No changes to save." ? "info" : "error", text: changes });
+      return;
+    }
+    if (inFlight.current) return;
+    inFlight.current = true;
+    setBusy("preferences");
+    setPreferencesMessage(null);
+    try {
+      const settings = await updateSettings(changes);
+      setPreferences({ kind: "ready", settings });
+      setPreferencesMessage({ kind: "info", text: "Preferences saved." });
+    } catch (error) {
+      setPreferencesMessage({
+        kind: "error",
+        text: errorMessage(error, "The preferences could not be saved"),
+      });
+    }
+    inFlight.current = false;
+    setBusy(null);
+  }
+
+  function move(children: AdminChild[], index: number, delta: -1 | 1) {
+    const ids = children.map((c) => c.id);
+    const target = index + delta;
+    [ids[index], ids[target]] = [ids[target], ids[index]];
+    void run(`move-${children[index].id}`, () => reorderChildren(ids), "The order could not be saved");
+  }
+
+  function toggleActive(child: AdminChild) {
+    void run(
+      `active-${child.id}`,
+      () => setChildActive(child.id, !child.is_active),
+      child.is_active ? "The child could not be deactivated" : "The child could not be reactivated",
+    );
+  }
+
+  let body;
+  if (state.kind === "loading") {
+    body = (
+      <div className="settings-status" role="status" data-testid="settings-loading">
+        Loading children…
+      </div>
+    );
+  } else if (state.kind === "error") {
+    body = (
+      <div className="settings-status settings-status--error" role="alert" data-testid="settings-error">
+        <p>{state.message}</p>
+        <button type="button" className="settings-action" onClick={() => setAttempt((n) => n + 1)}>
+          Try again
+        </button>
+      </div>
+    );
+  } else {
+    const { children } = state;
+    body = (
+      <>
+        {children.length > 0 ? (
+          <ul className="settings-card settings-list" aria-label="Children">
+            {children.map((child, index) => (
+              <ChildRow
+                key={child.id}
+                child={child}
+                index={index}
+                count={children.length}
+                busy={busy}
+                onEdit={() => {
+                  setFormError(null);
+                  setForm(child);
+                }}
+                onMove={(delta) => move(children, index, delta)}
+                onToggleActive={() => toggleActive(child)}
+              />
+            ))}
+          </ul>
+        ) : (
+          <div className="settings-card settings-empty">No children yet.</div>
+        )}
+        {form !== null ? (
+          <ChildForm
+            key={form === "new" ? "new" : form.id}
+            target={form}
+            siblings={children}
+            saving={busy === "form"}
+            error={formError}
+            onCancel={closeForm}
+            onSubmit={(b) => void submitForm(b)}
+          />
+        ) : null}
+      </>
+    );
+  }
+
+  return (
+    <div
+      ref={screenRef}
+      className="settings-screen"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="settings-title"
+      onKeyDown={onKeyDown}
+    >
+      <header className="settings-header">
+        <button
+          type="button"
+          className="settings-back"
+          aria-label="Back"
+          disabled={busy !== null}
+          onClick={onClose}
+        >
+          <ChevronLeftGlyph size={20} />
+        </button>
+        <div>
+          <h2 className="settings-title" id="settings-title" ref={titleRef} tabIndex={-1}>
+            Settings
+          </h2>
+          <p className="settings-sub">Household setup</p>
+        </div>
+      </header>
+      <div
+        className="settings-scroll"
+        data-testid="settings-scroll"
+        style={{ paddingBottom: SCROLL_BOTTOM_PADDING }}
+      >
+        <div className="settings-section-head">
+          <h3 className="settings-section-label">Children</h3>
+          <button
+            ref={addRef}
+            type="button"
+            className="settings-add"
+            disabled={state.kind !== "ready" || busy !== null || form === "new"}
+            onClick={() => {
+              setFormError(null);
+              setForm("new");
+            }}
+          >
+            <PlusGlyph />
+            Add child
+          </button>
+        </div>
+        {actionError !== null ? (
+          <div className="settings-action-error" role="alert" data-testid="settings-action-error">
+            <span>{actionError}</span>
+            <button type="button" className="settings-action" onClick={() => setActionError(null)}>
+              Dismiss
+            </button>
+          </div>
+        ) : null}
+        {body}
+        <div className="settings-section-head">
+          <h3 className="settings-section-label">Preferences</h3>
+        </div>
+        {preferences.kind === "loading" ? (
+          <div className="settings-status" role="status" data-testid="preferences-loading">
+            Loading preferences…
+          </div>
+        ) : preferences.kind === "error" ? (
+          <div
+            className="settings-status settings-status--error"
+            role="alert"
+            data-testid="preferences-error"
+          >
+            <p>{preferences.message}</p>
+            <button
+              type="button"
+              className="settings-action"
+              onClick={() => setPreferencesAttempt((n) => n + 1)}
+            >
+              Try again
+            </button>
+          </div>
+        ) : (
+          <PreferencesForm
+            // A saved response remounts the form so its draft matches the store.
+            key={JSON.stringify(preferences.settings)}
+            settings={preferences.settings}
+            saving={busy === "preferences"}
+            locked={busy !== null && busy !== "preferences"}
+            message={preferencesMessage}
+            onSubmit={(changes) => void savePreferences(changes)}
+          />
+        )}
+      </div>
+    </div>
+  );
+}

admin/src/settings/glyphs.tsx

@@ -0,0 +1,56 @@
+/**
+ * Inline stroke glyphs for the Settings screen (Lucide-style 24px grid),
+ * CDN-free like the tabs' glyphs.
+ */
+import type { ReactNode } from "react";
+
+function Glyph({ size, children }: { size: number; children: ReactNode }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    >
+      {children}
+    </svg>
+  );
+}
+
+export function ChevronLeftGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="m15 18-6-6 6-6" />
+    </Glyph>
+  );
+}
+
+export function ArrowUpGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="m5 12 7-7 7 7M12 19V5" />
+    </Glyph>
+  );
+}
+
+export function ArrowDownGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="M12 5v14M19 12l-7 7-7-7" />
+    </Glyph>
+  );
+}
+
+export function PlusGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <path d="M12 5v14M5 12h14" />
+    </Glyph>
+  );
+}

admin/src/today/TodayTab.css

@@ -0,0 +1,331 @@
+/* Today tab — compact density (design/ADMIN-SPEC.md §2). Mobile-first at the
+   390x844 reference; on wider viewports the column is capped and centred. */
+
+.today-screen {
+  width: 100%;
+  max-width: 640px;
+  margin: 0 auto;
+}
+
+/* §2.1 header */
+.today-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  background: var(--nq-a-surface);
+  border-bottom: 1px solid var(--nq-a-border);
+  padding: 14px 16px;
+}
+
+.today-title {
+  margin: 0;
+  font-size: var(--nq-a-size-screen);
+  font-weight: 800;
+  letter-spacing: -0.02em;
+}
+
+.today-sub {
+  margin: 2px 0 0;
+  min-height: 1.4em;
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.today-icon-button {
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: 36px;
+  height: 36px;
+  padding: 0;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink-secondary);
+  cursor: pointer;
+}
+
+/* Scroll column: 14px 16px, bottom 92px (set inline, ADMIN-SPEC §1). */
+.today-scroll {
+  display: flex;
+  flex-direction: column;
+  gap: var(--nq-a-density-gap);
+  padding: 14px 16px;
+}
+
+.today-card {
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+}
+
+.today-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.today-list > li + li {
+  border-top: 1px solid var(--nq-a-divider);
+}
+
+/* §2.2 stat row */
+.today-stats {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 8px;
+}
+
+.today-stat {
+  padding: 12px;
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+}
+
+.today-stat-value {
+  font-size: var(--nq-a-size-stat);
+  font-weight: 800;
+  line-height: 1.1;
+}
+
+.today-stat-value--done {
+  color: var(--nq-brand-blue);
+}
+
+.today-stat-value--remaining {
+  color: var(--nq-a-ink);
+}
+
+.today-stat-value--overdue {
+  color: var(--nq-a-danger);
+}
+
+.today-stat-label {
+  margin-top: 2px;
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--nq-a-ink-secondary);
+}
+
+/* §2.3 child rows */
+.today-child {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: var(--nq-a-tap-min);
+  padding: var(--nq-a-density-row-pad);
+}
+
+.today-avatar {
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: 30px;
+  height: 30px;
+  border-radius: 7px;
+  background: var(--nq-brand-gradient);
+  color: #fff;
+  font-size: 13px;
+  font-weight: 800;
+}
+
+.today-child--away .today-avatar {
+  background: #9898a8;
+}
+
+.today-child-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.today-child-name {
+  font-size: 14px;
+  font-weight: 700;
+}
+
+.today-child-meta {
+  font-size: var(--nq-a-size-meta);
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.today-child-meta--done {
+  color: var(--nq-a-success);
+}
+
+.today-progress {
+  flex: none;
+  width: 82px;
+  height: var(--nq-a-progress-height);
+  border-radius: var(--nq-a-radius-pill);
+  background: var(--nq-a-divider);
+  overflow: hidden;
+}
+
+.today-progress-fill {
+  height: 100%;
+  border-radius: inherit;
+  background: var(--nq-brand-gradient-h);
+}
+
+/* §2.5 needs attention */
+.today-section-label {
+  margin: 6px 0 -2px;
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--nq-a-ink-secondary);
+}
+
+.today-event {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: var(--nq-a-tap-min);
+  padding: var(--nq-a-density-row-pad);
+}
+
+.today-event-glyph {
+  flex: none;
+  display: flex;
+  color: var(--nq-a-success);
+}
+
+.today-event-glyph--overdue {
+  color: var(--nq-a-danger);
+}
+
+.today-event-text {
+  flex: 1;
+  min-width: 0;
+}
+
+.today-event-title {
+  font-size: 13px;
+  font-weight: 700;
+}
+
+.today-event-meta {
+  font-size: var(--nq-a-size-meta);
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.today-event-meta--overdue {
+  color: var(--nq-a-danger);
+}
+
+.today-action {
+  flex: none;
+  min-height: var(--nq-a-tap-min);
+  padding: 0 4px;
+  border: 0;
+  background: none;
+  font-family: inherit;
+  font-size: 12.5px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.today-action--done {
+  color: var(--nq-brand-blue);
+}
+
+.today-action--undo {
+  color: var(--nq-brand-purple);
+}
+
+.today-action:disabled {
+  cursor: default;
+  opacity: 0.5;
+}
+
+/* Non-blocking Undo failure message. */
+.today-action-error {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  padding: var(--nq-a-density-row-pad);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-danger-bg);
+  color: var(--nq-a-danger-strong);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.today-action-dismiss {
+  flex: none;
+  padding: 4px 8px;
+  border: none;
+  background: none;
+  color: inherit;
+  font-family: inherit;
+  font-size: 12.5px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.today-empty {
+  padding: var(--nq-a-density-card-pad);
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+/* §2.6 permission note */
+.today-note {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 10px 12px;
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-info-bg);
+  color: var(--nq-a-info-ink);
+  font-size: 11.5px;
+  font-weight: 600;
+}
+
+.today-note-glyph {
+  flex: none;
+  display: flex;
+  color: var(--nq-a-info-icon);
+}
+
+/* Loading / error */
+.today-status {
+  padding: 24px 13px;
+  background: var(--nq-a-surface);
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  text-align: center;
+  font-size: 13.5px;
+  font-weight: 600;
+  color: var(--nq-a-ink-secondary);
+}
+
+.today-status--error {
+  color: var(--nq-a-danger-strong);
+}
+
+.today-status--error p {
+  margin: 0 0 10px;
+}
+
+.today-retry {
+  padding: 8px 16px;
+  border: 1px solid var(--nq-a-border);
+  border-radius: var(--nq-a-density-radius);
+  background: var(--nq-a-surface);
+  color: var(--nq-a-ink);
+  font-family: inherit;
+  font-size: 13px;
+  font-weight: 700;
+  cursor: pointer;
+}

admin/src/today/TodayTab.test.tsx

@@ -0,0 +1,408 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import TodayTab, { PERMISSION_NOTE } from "./TodayTab";
+import type { AdminSnapshot, SnapshotInstance } from "../api/snapshot";
+import { TransitionsProvider } from "../api/useTransitions";
+import { frame, testStream, type TestStream } from "../api/testStream";
+import { storeTokens } from "../auth/oidc";
+
+function instance(overrides: Partial<SnapshotInstance>): SnapshotInstance {
+  return {
+    id: 0,
+    definition_id: 1,
+    child_id: 1,
+    title: "Quest",
+    icon: null,
+    window: "morning",
+    due_time: null,
+    state: "open",
+    overdue: false,
+    completed_at: null,
+    on_time: null,
+    ...overrides,
+  };
+}
+
+const SNAPSHOT: AdminSnapshot = {
+  today_iso: "2026-09-23",
+  cycle_day: 5,
+  children: [
+    {
+      child_id: 1,
+      child_name: "Declan",
+      present: true,
+      next_present: null,
+      due_today: 7,
+      completed_today: 3,
+      remaining_today: 4,
+      completion_pct: 43,
+      instances: [
+        instance({ id: 11, title: "Brush teeth", due_time: "07:30", overdue: true }),
+        instance({
+          id: 12,
+          title: "Make bed",
+          state: "completed",
+          completed_at: "2026-09-23T11:04:00Z",
+          on_time: true,
+        }),
+        instance({ id: 13, title: "Homework", window: "afternoon", due_time: "16:00" }),
+        // Overdue but already completed: not counted as overdue.
+        instance({
+          id: 14,
+          title: "Pack bag",
+          state: "completed",
+          overdue: true,
+          completed_at: "2026-09-23T10:00:00Z",
+          on_time: false,
+        }),
+      ],
+    },
+    {
+      child_id: 2,
+      child_name: "Maeve",
+      present: true,
+      next_present: null,
+      due_today: 4,
+      completed_today: 4,
+      remaining_today: 0,
+      completion_pct: 100,
+      instances: [],
+    },
+    {
+      child_id: 3,
+      child_name: "Rory",
+      present: false,
+      next_present: "2026-10-01",
+      due_today: 0,
+      completed_today: 0,
+      remaining_today: 0,
+      completion_pct: 0,
+      instances: [],
+    },
+  ],
+};
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+async function renderReady() {
+  fetchMock.mockResolvedValue(jsonResponse(SNAPSHOT));
+  render(<TodayTab />);
+  await screen.findByText("Declan");
+}
+
+describe("TodayTab", () => {
+  beforeAll(() => {
+    // A negative-offset zone: `new Date("2026-09-23")` would read as Sep 22 here.
+    vi.stubEnv("TZ", "America/Los_Angeles");
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+  });
+
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("fetches the admin snapshot with the Bearer token", async () => {
+    await renderReady();
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toMatch(/\/api\/v1\/admin\/snapshot$/);
+    expect(init.headers.Authorization).toBe("Bearer at-123");
+  });
+
+  it("header shows the weekday, date and cycle day", async () => {
+    await renderReady();
+    expect(screen.getByRole("heading", { name: "Today" })).toBeTruthy();
+    expect(screen.getByText("Wednesday, September 23 · cycle day 5 of 14")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Settings" })).toBeTruthy();
+  });
+
+  it("stat row shows done, remaining and overdue totals", async () => {
+    await renderReady();
+    expect(screen.getByTestId("stat-done").textContent).toBe("7Done");
+    expect(screen.getByTestId("stat-remaining").textContent).toBe("4Remaining");
+    expect(screen.getByTestId("stat-overdue").textContent).toBe("1Overdue");
+  });
+
+  it("present child row shows progress meta and fill", async () => {
+    await renderReady();
+    const row = screen.getByTestId("child-1");
+    expect(within(row).getByText("3 of 7 · 1 overdue")).toBeTruthy();
+    const bar = within(row).getByRole("progressbar");
+    expect(bar.getAttribute("aria-valuenow")).toBe("43");
+    expect((bar.firstElementChild as HTMLElement).style.width).toBe("43%");
+    expect(row.className).not.toContain("today-child--away");
+  });
+
+  it("all-done child renders the success state", async () => {
+    await renderReady();
+    const meta = within(screen.getByTestId("child-2")).getByText("4 of 4 · all done");
+    expect(meta.className).toContain("today-child-meta--done");
+  });
+
+  it("away child shows the return date and the flat avatar", async () => {
+    await renderReady();
+    const row = screen.getByTestId("child-3");
+    expect(within(row).getByText("Away · returns Oct 1")).toBeTruthy();
+    expect(row.className).toContain("today-child--away");
+    expect(within(row).getByTestId("child-avatar").textContent).toBe("R");
+  });
+
+  it("needs-attention lists overdue and completed rows with their actions", async () => {
+    await renderReady();
+    const list = screen.getByRole("list", { name: "Needs attention" });
+    const overdue = within(list).getByTestId("attention-11");
+    expect(within(overdue).getByText("Brush teeth · Declan")).toBeTruthy();
+    expect(within(overdue).getByText("Overdue since 7:30 AM")).toBeTruthy();
+    expect(within(overdue).getByRole("button", { name: "Mark done" })).toBeTruthy();
+
+    const completed = within(list).getByTestId("attention-12");
+    expect(within(completed).getByText("Make bed · Declan")).toBeTruthy();
+    // 11:04Z is 4:04 AM in Los Angeles (PDT).
+    expect(within(completed).getByText("Completed 4:04 AM")).toBeTruthy();
+    expect(within(completed).getByRole("button", { name: "Undo" })).toBeTruthy();
+
+    // Open, not-overdue instances do not need attention.
+    expect(within(list).queryByTestId("attention-13")).toBeNull();
+    // No actor in the payload, so no "from panel".
+    expect(list.textContent).not.toContain("from panel");
+  });
+
+  it("permission note carries the exact copy", async () => {
+    await renderReady();
+    expect(PERMISSION_NOTE).toBe(
+      "Undo is admin-only. A panel tap can never reverse a completion.",
+    );
+    expect(screen.getByTestId("permission-note").textContent).toBe(PERMISSION_NOTE);
+  });
+
+  it("scroll column ends with 92px bottom padding", async () => {
+    await renderReady();
+    expect(screen.getByTestId("today-scroll").style.paddingBottom).toBe("92px");
+  });
+
+  it("shows a loading state while the snapshot is in flight", () => {
+    fetchMock.mockReturnValue(new Promise<Response>(() => {}));
+    render(<TodayTab />);
+    expect(screen.getByTestId("today-loading").textContent).toContain("Loading");
+    expect(screen.getByTestId("today-scroll").style.paddingBottom).toBe("92px");
+  });
+
+  it("shows an error state on a failed fetch and retries", async () => {
+    fetchMock.mockResolvedValueOnce(new Response("boom", { status: 500 }));
+    render(<TodayTab />);
+    const error = await screen.findByTestId("today-error");
+    expect(error.getAttribute("role")).toBe("alert");
+    expect(error.textContent).toContain("could not be loaded");
+
+    fetchMock.mockResolvedValueOnce(jsonResponse(SNAPSHOT));
+    fireEvent.click(screen.getByRole("button", { name: "Try again" }));
+    expect(await screen.findByText("Declan")).toBeTruthy();
+  });
+
+  it("shows the refusal message when the API answers 403", async () => {
+    fetchMock.mockResolvedValueOnce(new Response("", { status: 403 }));
+    render(<TodayTab />);
+    const error = await screen.findByTestId("today-error");
+    expect(error.textContent).toContain("nestquest-admins");
+  });
+});
+
+/** SNAPSHOT after instance 12 ("Make bed") is reversed back to open. */
+const AFTER_UNDO: AdminSnapshot = {
+  ...SNAPSHOT,
+  children: SNAPSHOT.children.map((child) =>
+    child.child_id !== 1
+      ? child
+      : {
+          ...child,
+          completed_today: 2,
+          remaining_today: 5,
+          completion_pct: 29,
+          instances: child.instances.map((i) =>
+            i.id === 12 ? { ...i, state: "open" as const, completed_at: null, on_time: null } : i,
+          ),
+        },
+  ),
+};
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((r) => {
+    resolve = r;
+  });
+  return { promise, resolve };
+}
+
+describe("TodayTab Undo and live updates", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let snapshots: AdminSnapshot[];
+  let uncomplete: () => Promise<Response>;
+  let streams: TestStream[];
+
+  function calls(pathSuffix: string, method = "GET") {
+    return fetchMock.mock.calls.filter(
+      ([url, init]) =>
+        new URL(String(url), "http://x").pathname.endsWith(pathSuffix) &&
+        (init?.method ?? "GET") === method,
+    );
+  }
+
+  beforeAll(() => {
+    vi.stubEnv("TZ", "America/Los_Angeles");
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+  });
+
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    snapshots = [SNAPSHOT, AFTER_UNDO];
+    uncomplete = () =>
+      Promise.resolve(jsonResponse({ instance_id: 12, state: "open", appended: true }));
+    streams = [];
+    fetchMock = vi.fn((url: string) => {
+      const path = new URL(url, "http://x").pathname;
+      if (path.endsWith("/api/v1/admin/snapshot")) {
+        const next = snapshots.length > 1 ? snapshots.shift()! : snapshots[0];
+        return Promise.resolve(jsonResponse(next));
+      }
+      if (path.endsWith("/api/v1/admin/instances/12/uncomplete")) return uncomplete();
+      if (path.endsWith("/api/v1/admin/events")) {
+        const stream = testStream();
+        streams.push(stream);
+        return Promise.resolve(stream.response);
+      }
+      return Promise.resolve(jsonResponse({ detail: "unexpected" }, 500));
+    });
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("Undo POSTs uncomplete for the completed instance and refetches the snapshot", async () => {
+    render(<TodayTab />);
+    const row = await screen.findByTestId("attention-12");
+    fireEvent.click(within(row).getByRole("button", { name: "Undo" }));
+
+    await waitFor(() => expect(screen.queryByTestId("attention-12")).toBeNull());
+    const posts = calls("/api/v1/admin/instances/12/uncomplete", "POST");
+    expect(posts).toHaveLength(1);
+    expect(posts[0][1].headers.Authorization).toBe("Bearer at-123");
+    expect(calls("/api/v1/admin/snapshot")).toHaveLength(2);
+    // The reversed instance is open again: one fewer done, one more remaining.
+    expect(screen.getByTestId("stat-done").textContent).toBe("6Done");
+    expect(screen.getByTestId("stat-remaining").textContent).toBe("5Remaining");
+    expect(screen.queryByTestId("today-undo-error")).toBeNull();
+  });
+
+  it("disables Undo while the request is in flight (no double submit)", async () => {
+    const pending = deferred<Response>();
+    uncomplete = () => pending.promise;
+    render(<TodayTab />);
+    const row = await screen.findByTestId("attention-12");
+    const button = within(row).getByRole("button", { name: "Undo" }) as HTMLButtonElement;
+
+    fireEvent.click(button);
+    await waitFor(() => expect(button.disabled).toBe(true));
+    expect(button.textContent).toBe("Undoing…");
+    // Every Undo is disabled while one reversal is in flight.
+    const other = within(screen.getByTestId("attention-14")).getByRole("button", {
+      name: "Undo",
+    }) as HTMLButtonElement;
+    expect(other.disabled).toBe(true);
+    fireEvent.click(button);
+    fireEvent.click(other);
+    expect(calls("/api/v1/admin/instances/12/uncomplete", "POST")).toHaveLength(1);
+    expect(calls("/uncomplete", "POST")).toHaveLength(1);
+
+    pending.resolve(jsonResponse({ instance_id: 12, state: "open", appended: true }));
+    await waitFor(() => expect(screen.queryByTestId("attention-12")).toBeNull());
+    expect(other.disabled).toBe(false);
+  });
+
+  it("a failed Undo shows a message and leaves the view intact", async () => {
+    uncomplete = () => Promise.resolve(jsonResponse({ detail: "instance 12 not found" }, 404));
+    render(<TodayTab />);
+    const row = await screen.findByTestId("attention-12");
+    fireEvent.click(within(row).getByRole("button", { name: "Undo" }));
+
+    const alert = await screen.findByTestId("today-undo-error");
+    expect(alert.textContent).toContain("The completion could not be undone: instance 12 not found");
+    // Still the original snapshot: nothing refetched, the row and its Undo remain usable.
+    expect(calls("/api/v1/admin/snapshot")).toHaveLength(1);
+    const button = within(screen.getByTestId("attention-12")).getByRole("button", {
+      name: "Undo",
+    }) as HTMLButtonElement;
+    expect(button.disabled).toBe(false);
+    expect(screen.getByTestId("stat-done").textContent).toBe("7Done");
+
+    fireEvent.click(within(alert).getByRole("button", { name: "Dismiss" }));
+    expect(screen.queryByTestId("today-undo-error")).toBeNull();
+  });
+
+  it("Mark done stays inert", async () => {
+    render(<TodayTab />);
+    const row = await screen.findByTestId("attention-11");
+    fireEvent.click(within(row).getByRole("button", { name: "Mark done" }));
+    expect(fetchMock.mock.calls.filter(([, init]) => init?.method === "POST")).toHaveLength(0);
+  });
+
+  it("a transition on the live stream refetches the snapshot without a reload", async () => {
+    const { unmount } = render(
+      <TransitionsProvider>
+        <TodayTab />
+      </TransitionsProvider>,
+    );
+    await screen.findByTestId("attention-12");
+    await waitFor(() => expect(streams).toHaveLength(1));
+    const [, init] = calls("/api/v1/admin/events")[0];
+    expect(init.headers.Authorization).toBe("Bearer at-123");
+
+    // An uncompletion made elsewhere, its frame split across two chunks.
+    const text = frame("nestquest_quest_uncompleted", {
+      child_id: 1,
+      child_name: "Declan",
+      instance_id: 12,
+      quest_title: "Make bed",
+      window: "morning",
+      due_date: "2026-09-23",
+      due_time: null,
+      occurred_at: "2026-09-23T12:00:00Z",
+    });
+    streams[0].push(text.slice(0, 25));
+    streams[0].push(text.slice(25));
+
+    await waitFor(() => expect(calls("/api/v1/admin/snapshot")).toHaveLength(2));
+    await waitFor(() => expect(screen.queryByTestId("attention-12")).toBeNull());
+    // Refreshed in place: the loading state never replaced the view.
+    expect(screen.queryByTestId("today-loading")).toBeNull();
+
+    const signal = init.signal as AbortSignal;
+    expect(signal.aborted).toBe(false);
+    unmount();
+    expect(signal.aborted).toBe(true);
+    await waitFor(() => expect(streams[0].cancelled()).toBe(true));
+  });
+});

admin/src/today/TodayTab.tsx

@@ -0,0 +1,365 @@
+/**
+ * Today tab — compact density (design/ADMIN-SPEC.md §2.1–2.3, §2.5–2.6).
+ */
+import { useEffect, useRef, useState } from "react";
+import {
+  fetchSnapshot,
+  type AdminSnapshot,
+  type SnapshotChild,
+  type SnapshotInstance,
+} from "../api/snapshot";
+import { ApiForbiddenError } from "../api/client";
+import { ApiRequestError } from "../api/definitions";
+import { uncompleteInstance } from "../api/instances";
+import { useTransitions } from "../api/useTransitions";
+import SettingsScreen from "../settings/SettingsScreen";
+import {
+  formatClockTime,
+  formatDueTime,
+  formatLongDate,
+  formatShortDate,
+} from "./format";
+import {
+  AlertCircleGlyph,
+  CheckCircleGlyph,
+  InfoGlyph,
+  SettingsGlyph,
+} from "./glyphs";
+import "./TodayTab.css";
+
+const CYCLE_LENGTH_DAYS = 14;
+
+/** ADMIN-SPEC §1: every scroll column ends with 92px so content clears the tab bar. */
+export const SCROLL_BOTTOM_PADDING = "92px";
+
+export const PERMISSION_NOTE =
+  "Undo is admin-only. A panel tap can never reverse a completion.";
+
+type LoadState =
+  | { kind: "loading" }
+  | { kind: "error"; message: string }
+  | { kind: "ready"; snapshot: AdminSnapshot };
+
+function isOverdueOpen(instance: SnapshotInstance): boolean {
+  return instance.overdue && instance.state === "open";
+}
+
+function ScreenHeader({ sub, onSettings }: { sub: string; onSettings: () => void }) {
+  return (
+    <header className="today-header">
+      <div>
+        <h2 className="today-title">Today</h2>
+        <p className="today-sub">{sub}</p>
+      </div>
+      {/* Opens the Settings screen. Only its Children section exists so far.
+          TODO: horizon days, day rollover time and notification config are a
+          separate later task. */}
+      <button
+        type="button"
+        className="today-icon-button"
+        aria-label="Settings"
+        onClick={onSettings}
+      >
+        <SettingsGlyph />
+      </button>
+    </header>
+  );
+}
+
+function StatRow({ snapshot }: { snapshot: AdminSnapshot }) {
+  const done = snapshot.children.reduce((sum, c) => sum + c.completed_today, 0);
+  const remaining = snapshot.children.reduce((sum, c) => sum + c.remaining_today, 0);
+  const overdue = snapshot.children.reduce(
+    (sum, c) => sum + c.instances.filter(isOverdueOpen).length,
+    0,
+  );
+  const stats = [
+    { key: "done", label: "Done", value: done },
+    { key: "remaining", label: "Remaining", value: remaining },
+    { key: "overdue", label: "Overdue", value: overdue },
+  ];
+  return (
+    <div className="today-stats">
+      {stats.map((stat) => (
+        <div key={stat.key} className="today-stat" data-testid={`stat-${stat.key}`}>
+          <div className={`today-stat-value today-stat-value--${stat.key}`}>
+            {stat.value}
+          </div>
+          <div className="today-stat-label">{stat.label}</div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function ChildRow({ child }: { child: SnapshotChild }) {
+  const overdue = child.instances.filter(isOverdueOpen).length;
+  const allDone = child.due_today > 0 && child.completed_today === child.due_today;
+  let meta: string;
+  let metaClass = "today-child-meta";
+  if (!child.present) {
+    meta = child.next_present
+      ? `Away · returns ${formatShortDate(child.next_present)}`
+      : "Away";
+  } else if (allDone) {
+    meta = `${child.completed_today} of ${child.due_today} · all done`;
+    metaClass += " today-child-meta--done";
+  } else {
+    meta = `${child.completed_today} of ${child.due_today} · ${overdue} overdue`;
+  }
+  const pct = Math.max(0, Math.min(100, child.completion_pct));
+  // ADMIN-SPEC §2.3 also asks for a lowercase `override` pill when an absence
+  // comes from a presence override. The snapshot carries no field saying
+  // where an absence came from, so the pill is omitted rather than guessed.
+  return (
+    <li
+      className={child.present ? "today-child" : "today-child today-child--away"}
+      data-testid={`child-${child.child_id}`}
+    >
+      <span className="today-avatar" data-testid="child-avatar" aria-hidden="true">
+        {child.child_name.charAt(0).toUpperCase()}
+      </span>
+      <div className="today-child-text">
+        <div className="today-child-name">{child.child_name}</div>
+        <div className={metaClass}>{meta}</div>
+      </div>
+      <div
+        className="today-progress"
+        role="progressbar"
+        aria-label={`${child.child_name} progress`}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-valuenow={pct}
+      >
+        <div className="today-progress-fill" style={{ width: `${pct}%` }} />
+      </div>
+    </li>
+  );
+}
+
+interface AttentionItem {
+  instance: SnapshotInstance;
+  childName: string;
+}
+
+function attentionItems(snapshot: AdminSnapshot): AttentionItem[] {
+  const all = snapshot.children.flatMap((child) =>
+    child.instances.map((instance) => ({ instance, childName: child.child_name })),
+  );
+  const overdue = all.filter((item) => isOverdueOpen(item.instance));
+  const completed = all
+    .filter((item) => item.instance.state === "completed" && item.instance.completed_at)
+    .sort((a, b) =>
+      (b.instance.completed_at ?? "").localeCompare(a.instance.completed_at ?? ""),
+    );
+  return [...overdue, ...completed];
+}
+
+interface UndoControl {
+  /** The instance whose Undo is in flight, or null. */
+  pendingId: number | null;
+  onUndo: (instanceId: number) => void;
+}
+
+function AttentionRow({ item, undo }: { item: AttentionItem; undo: UndoControl }) {
+  const { instance, childName } = item;
+  const overdue = isOverdueOpen(instance);
+  const undoing = undo.pendingId === instance.id;
+  // TODO(e57facc2): wire "Mark done". The admin plane has no complete route
+  // yet, so that action is inert here.
+  return (
+    <li className="today-event" data-testid={`attention-${instance.id}`}>
+      <span
+        className={overdue ? "today-event-glyph today-event-glyph--overdue" : "today-event-glyph"}
+      >
+        {overdue ? <AlertCircleGlyph /> : <CheckCircleGlyph />}
+      </span>
+      <div className="today-event-text">
+        <div className="today-event-title">
+          {instance.title} · {childName}
+        </div>
+        {overdue ? (
+          <div className="today-event-meta today-event-meta--overdue">
+            {instance.due_time
+              ? `Overdue since ${formatDueTime(instance.due_time)}`
+              : "Overdue"}
+          </div>
+        ) : (
+          // The snapshot carries no completion actor, so "from panel" is not printed.
+          <div className="today-event-meta">
+            Completed {formatClockTime(instance.completed_at as string)}
+          </div>
+        )}
+      </div>
+      {overdue ? (
+        <button type="button" className="today-action today-action--done">
+          Mark done
+        </button>
+      ) : (
+        <button
+          type="button"
+          className="today-action today-action--undo"
+          disabled={undo.pendingId !== null}
+          aria-busy={undoing}
+          onClick={() => undo.onUndo(instance.id)}
+        >
+          {undoing ? "Undoing…" : "Undo"}
+        </button>
+      )}
+    </li>
+  );
+}
+
+function PermissionNote() {
+  return (
+    <div className="today-note" data-testid="permission-note">
+      <span className="today-note-glyph">
+        <InfoGlyph />
+      </span>
+      <span>{PERMISSION_NOTE}</span>
+    </div>
+  );
+}
+
+export default function TodayTab() {
+  const [state, setState] = useState<LoadState>({ kind: "loading" });
+  const [attempt, setAttempt] = useState(0);
+  /** The next load is a refresh in place: keep the current view, no loading state. */
+  const silentNext = useRef(false);
+  const [undoingId, setUndoingId] = useState<number | null>(null);
+  const undoingRef = useRef(false);
+  const [undoError, setUndoError] = useState<string | null>(null);
+  const [settingsOpen, setSettingsOpen] = useState(false);
+
+  function refresh() {
+    silentNext.current = true;
+    setAttempt((n) => n + 1);
+  }
+
+  // Any transition (completed, uncompleted, missed, day complete) changes the snapshot.
+  useTransitions(refresh);
+
+  useEffect(() => {
+    let cancelled = false;
+    const silent = silentNext.current;
+    silentNext.current = false;
+    if (!silent) setState({ kind: "loading" });
+    fetchSnapshot()
+      .then((snapshot) => {
+        if (!cancelled) setState({ kind: "ready", snapshot });
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        const message =
+          error instanceof ApiForbiddenError
+            ? error.message
+            : "Today's snapshot could not be loaded. Check your connection and try again.";
+        // A failed refresh keeps the snapshot already on screen.
+        setState((prev) => (silent && prev.kind === "ready" ? prev : { kind: "error", message }));
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [attempt]);
+
+  /** Reverse one completion, then refetch the snapshot. One request at a time. */
+  async function undo(instanceId: number) {
+    if (undoingRef.current) return;
+    undoingRef.current = true;
+    setUndoingId(instanceId);
+    setUndoError(null);
+    try {
+      await uncompleteInstance(instanceId);
+      refresh();
+    } catch (error: unknown) {
+      setUndoError(
+        error instanceof ApiForbiddenError
+          ? error.message
+          : error instanceof ApiRequestError && error.detail
+            ? `The completion could not be undone: ${error.detail}`
+            : "The completion could not be undone. Check your connection and try again.",
+      );
+    } finally {
+      undoingRef.current = false;
+      setUndoingId(null);
+    }
+  }
+
+  let sub = "";
+  let body;
+  if (state.kind === "loading") {
+    body = (
+      <div className="today-status" role="status" data-testid="today-loading">
+        Loading today…
+      </div>
+    );
+  } else if (state.kind === "error") {
+    body = (
+      <div className="today-status today-status--error" role="alert" data-testid="today-error">
+        <p>{state.message}</p>
+        <button type="button" className="today-retry" onClick={() => setAttempt((n) => n + 1)}>
+          Try again
+        </button>
+      </div>
+    );
+  } else {
+    const { snapshot } = state;
+    sub = `${formatLongDate(snapshot.today_iso)} · cycle day ${snapshot.cycle_day} of ${CYCLE_LENGTH_DAYS}`;
+    const attention = attentionItems(snapshot);
+    body = (
+      <>
+        <StatRow snapshot={snapshot} />
+        <ul className="today-card today-list" aria-label="Children">
+          {snapshot.children.map((child) => (
+            <ChildRow key={child.child_id} child={child} />
+          ))}
+        </ul>
+        <h3 className="today-section-label">Needs attention</h3>
+        {attention.length > 0 ? (
+          <ul className="today-card today-list" aria-label="Needs attention">
+            {attention.map((item) => (
+              <AttentionRow
+                key={item.instance.id}
+                item={item}
+                undo={{ pendingId: undoingId, onUndo: (id) => void undo(id) }}
+              />
+            ))}
+          </ul>
+        ) : (
+          <div className="today-card today-empty">Nothing needs attention.</div>
+        )}
+        <PermissionNote />
+      </>
+    );
+  }
+
+  return (
+    <div className="today-screen">
+      <ScreenHeader sub={sub} onSettings={() => setSettingsOpen(true)} />
+      <div
+        className="today-scroll"
+        data-testid="today-scroll"
+        style={{ paddingBottom: SCROLL_BOTTOM_PADDING }}
+      >
+        {undoError !== null ? (
+          <div className="today-action-error" role="alert" data-testid="today-undo-error">
+            <span>{undoError}</span>
+            <button type="button" className="today-action-dismiss" onClick={() => setUndoError(null)}>
+              Dismiss
+            </button>
+          </div>
+        ) : null}
+        {body}
+      </div>
+      {settingsOpen ? (
+        <SettingsScreen
+          onClose={() => {
+            setSettingsOpen(false);
+            // Child names and order feed the snapshot.
+            refresh();
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}

admin/src/today/format.ts

@@ -0,0 +1,50 @@
+/**
+ * Date/time formatting for the Today tab.
+ *
+ * Calendar dates ("YYYY-MM-DD") are parsed by their components and formatted
+ * in UTC, so the printed day never shifts with the viewer's offset — unlike
+ * `new Date("YYYY-MM-DD")`, which is UTC midnight and reads as the previous
+ * day in negative-offset zones.
+ */
+
+const LOCALE = "en-US";
+
+function calendarDate(iso: string): Date {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+  if (!match) throw new Error(`Invalid calendar date: ${iso}`);
+  const [, year, month, day] = match;
+  return new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)));
+}
+
+function format(date: Date, options: Intl.DateTimeFormatOptions): string {
+  // Newer ICU puts a narrow no-break space before AM/PM; normalise it.
+  return new Intl.DateTimeFormat(LOCALE, options)
+    .format(date)
+    .replace(/ /g, " ");
+}
+
+/** "Wednesday, September 23" */
+export function formatLongDate(iso: string): string {
+  const date = calendarDate(iso);
+  const weekday = format(date, { weekday: "long", timeZone: "UTC" });
+  const monthDay = format(date, { month: "long", day: "numeric", timeZone: "UTC" });
+  return `${weekday}, ${monthDay}`;
+}
+
+/** "Sep 23" */
+export function formatShortDate(iso: string): string {
+  return format(calendarDate(iso), { month: "short", day: "numeric", timeZone: "UTC" });
+}
+
+/** "09:00" -> "9:00 AM" (a wall-clock time, no zone conversion). */
+export function formatDueTime(hhmm: string): string {
+  const match = /^(\d{2}):(\d{2})/.exec(hhmm);
+  if (!match) return hhmm;
+  const date = new Date(Date.UTC(2000, 0, 1, Number(match[1]), Number(match[2])));
+  return format(date, { hour: "numeric", minute: "2-digit", timeZone: "UTC" });
+}
+
+/** A UTC ISO timestamp shown as the viewer's local time, "7:04 AM". */
+export function formatClockTime(isoTimestamp: string): string {
+  return format(new Date(isoTimestamp), { hour: "numeric", minute: "2-digit" });
+}

admin/src/today/glyphs.tsx

@@ -0,0 +1,61 @@
+/**
+ * Inline stroke glyphs for the Today tab (Lucide-style 24px grid). The
+ * shipped Lucide subset is task b50b048f; these keep this screen CDN-free
+ * until then.
+ */
+import type { ReactNode } from "react";
+
+function Glyph({ size, children }: { size: number; children: ReactNode }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    >
+      {children}
+    </svg>
+  );
+}
+
+export function SettingsGlyph({ size = 18 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <circle cx="12" cy="12" r="3" />
+      <path d="M12 2v3M12 19v3M2 12h3M19 12h3M4.9 4.9l2.1 2.1M17 17l2.1 2.1M4.9 19.1 7 17M17 7l2.1-2.1" />
+    </Glyph>
+  );
+}
+
+export function InfoGlyph({ size = 16 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <circle cx="12" cy="12" r="10" />
+      <path d="M12 16v-4M12 8h.01" />
+    </Glyph>
+  );
+}
+
+export function AlertCircleGlyph({ size = 18 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <circle cx="12" cy="12" r="10" />
+      <path d="M12 8v4M12 16h.01" />
+    </Glyph>
+  );
+}
+
+export function CheckCircleGlyph({ size = 18 }: { size?: number }) {
+  return (
+    <Glyph size={size}>
+      <circle cx="12" cy="12" r="10" />
+      <path d="m9 12 2 2 4-4" />
+    </Glyph>
+  );
+}

admin/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "types": ["vite/client"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "useDefineForClassFields": true
+  },
+  "include": ["src"]
+}

admin/vite-sw-plugin.ts

@@ -0,0 +1,93 @@
+/* Build-time service worker injection. After Vite writes the bundle, the
+   hashed asset URLs referenced by dist/index.html and a content-derived
+   revision are written into dist/sw.js, so the offline shell is complete right
+   after install and every release ships a new worker with fresh caches.
+   Build tooling only — never imported by the app bundle. */
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Plugin } from "vite";
+
+export const REVISION_MARKER = "__NQ_BUILD_REVISION__";
+const PRECACHE_PLACEHOLDER = "const PRECACHE_ASSETS = [];";
+// Unhashed files sw.js precaches by fixed URL, relative to the build output.
+export const STATIC_PRECACHE_FILES = [
+  "manifest.webmanifest",
+  "icons/icon-192.png",
+  "icons/icon-512.png",
+  "icons/icon-maskable-512.png",
+];
+
+export interface PrecacheFile {
+  path: string;
+  bytes: string | Uint8Array;
+}
+
+// Every same-origin URL an index.html loads via <script src> or <link href>,
+// normalised to an absolute path, in document order and without duplicates.
+export function extractShellAssets(indexHtml: string): string[] {
+  const tags = indexHtml.match(/<(?:script|link)\b[^>]*>/gi) ?? [];
+  const urls = tags.flatMap((tag) => {
+    const attr = /\b(?:src|href)\s*=\s*["']([^"']+)["']/i.exec(tag);
+    if (!attr) return [];
+    const url = new URL(attr[1], "https://same-origin.invalid/");
+    return url.origin === "https://same-origin.invalid" ? [url.pathname] : [];
+  });
+  return [...new Set(urls)];
+}
+
+// Hash of every precached file, sorted by path; each entry is length-prefixed
+// so no two different file sets hash the same concatenation.
+export function computeRevision(files: PrecacheFile[]): string {
+  const hash = createHash("sha256");
+  for (const { path, bytes } of [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) {
+    const data = typeof bytes === "string" ? Buffer.from(bytes, "utf8") : bytes;
+    hash.update(`${path}\0${data.byteLength}\0`).update(data);
+  }
+  return hash.digest("hex").slice(0, 12);
+}
+
+// Returns swSource with the precache list and the build revision filled in.
+// The revision covers index.html (and so the hashed bundles it names), the
+// sw.js source and the bytes of every unhashed static file it precaches.
+export function injectServiceWorker(
+  indexHtml: string,
+  swSource: string,
+  staticFiles: PrecacheFile[],
+): string {
+  if (!swSource.includes(PRECACHE_PLACEHOLDER) || !swSource.includes(REVISION_MARKER)) {
+    throw new Error("sw.js is missing the PRECACHE_ASSETS placeholder or revision marker");
+  }
+  const assets = extractShellAssets(indexHtml);
+  const revision = computeRevision([
+    { path: "index.html", bytes: indexHtml },
+    { path: "sw.js", bytes: swSource },
+    ...staticFiles,
+  ]);
+  return swSource
+    .replace(PRECACHE_PLACEHOLDER, `const PRECACHE_ASSETS = ${JSON.stringify(assets)};`)
+    .replaceAll(REVISION_MARKER, revision);
+}
+
+export function serviceWorkerInjectPlugin(): Plugin {
+  let outDir = "";
+  return {
+    name: "nestquest-sw-inject",
+    apply: "build",
+    configResolved(config) {
+      outDir = resolve(config.root, config.build.outDir);
+    },
+    writeBundle() {
+      const swPath = resolve(outDir, "sw.js");
+      const indexHtml = readFileSync(resolve(outDir, "index.html"), "utf8");
+      const staticFiles = STATIC_PRECACHE_FILES.map((path) => ({
+        path,
+        bytes: readFileSync(resolve(outDir, path)),
+      }));
+      writeFileSync(
+        swPath,
+        injectServiceWorker(indexHtml, readFileSync(swPath, "utf8"), staticFiles),
+      );
+    },
+  };
+}

admin/vite.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+import { serviceWorkerInjectPlugin } from "./vite-sw-plugin";
+
+export default defineConfig({
+  plugins: [react(), serviceWorkerInjectPlugin()],
+  test: {
+    environment: "jsdom",
+  },
+});

api/README.md

@@ -0,0 +1,83 @@
+# NestQuest API
+
+Standalone FastAPI service owning the NestQuest database (Feature 16).
+Served with ``uvicorn --factory api.app:create_app``; configuration is
+environment-supplied (``api/config.py``) and every variable is required.
+
+## Runtime dependencies
+
+``api/requirements.txt`` is the API deployable's OWN dependency
+manifest (fastapi, uvicorn, pyjwt[crypto], httpx) — deliberately kept
+out of the integration's ``pyproject.toml`` dev group, which exists only
+so the monorepo test venv can run the API tests.
+
+## Container deployment (scaffold)
+
+The image is built from the repository ROOT context (the API loads the
+bundled domain core from ``custom_components/nestquest/core/`` by file
+location, so both trees must be in the build context):
+
+    docker build -t nestquest-api:latest .
+
+Run it with compose — the SQLite file lives on the named volume
+``nestquest-db`` so recreating the container keeps household data:
+
+    cp deploy/.env.example deploy/.env   # then fill in real values
+    docker compose -f deploy/compose.yaml up -d --build
+
+``deploy/.env`` is git-ignored and supplies the secrets (panel service
+token, Authentik OIDC settings); ``NESTQUEST_DB_PATH`` is fixed to
+``/var/lib/nestquest/nestquest.db`` by compose.
+
+The published port binds ``NESTQUEST_BIND_ADDRESS`` from
+``deploy/.env`` and defaults to ``127.0.0.1`` (localhost only). In
+production TLS is terminated by the shared Traefik reverse proxy,
+which serves ``https://nestquest.cubecraftlabs.com`` (Let's Encrypt,
+auto-renewed, HTTP redirected to HTTPS) and forwards to the API box
+on port 8080 — so on that box set ``NESTQUEST_BIND_ADDRESS`` to its
+LAN address (``10.60.1.14``). Traefik only allows
+``/api/v1/panel`` from the Home Assistant host. The full deployment,
+restore and verification procedure is in ``deploy/RUNBOOK.md``.
+
+## Continuous backup (Litestream)
+
+Compose also runs a ``litestream`` sidecar
+(``litestream/litestream:0.5.17``, config ``deploy/litestream.yml``).
+It mounts the same ``nestquest-db`` volume and continuously replicates
+``/var/lib/nestquest/nestquest.db`` over SFTP to the Synology NAS
+``CubeCraft-SRVR1`` (``joshua@10.60.1.50``), directory
+``/volume1/homes/Joshua/nestquest-backups`` (``/homes/Joshua/...`` in
+the NAS's chrooted SFTP view) — so the backup is outside the Docker
+host and its volume. A snapshot is taken daily and a week of
+snapshots plus incremental changes is retained; the NAS host key is
+pinned in the config.
+
+The SFTP login uses a dedicated keypair that lives only on the API
+box and is git-ignored. Create it once, before ``up``:
+
+    ssh-keygen -t ed25519 -N "" -C nestquest-litestream -f deploy/litestream_key
+
+then append ``restrict `` + the contents of ``deploy/litestream_key.pub``
+to ``joshua@10.60.1.50:~/.ssh/authorized_keys``. Compose mounts the
+private key read-only at ``/etc/litestream/sftp_key``. The sidecar runs
+as uid/gid 999 (the API's ``nestquest`` user), so give it the key:
+
+    sudo chown 999:999 deploy/litestream_key && chmod 600 deploy/litestream_key
+
+The sidecar needs WRITE access to the database volume: Litestream adds
+its own ``_litestream_seq``/``_litestream_lock`` tables to the database,
+writes the ``-wal``/``-shm`` files and checkpoints the WAL, and fails
+with "unable to open database file" on a read-only mount. That access
+is contained rather than removed — the sidecar runs as the non-root
+volume owner with a read-only root filesystem, ``no-new-privileges``
+and all Linux capabilities dropped.
+
+Check replication with
+``docker compose -f deploy/compose.yaml logs litestream`` or
+``docker compose -f deploy/compose.yaml exec litestream litestream ltx /var/lib/nestquest/nestquest.db``.
+To restore (high level): stop the ``api`` service, run
+``litestream restore -config /etc/litestream.yml -o <new path>
+/var/lib/nestquest/nestquest.db`` from a litestream container with the
+same mounts, verify the restored file, move it into place on the
+volume (removing any stale ``-wal``/``-shm`` files), and start ``api``
+again.

api/__init__.py

@@ -0,0 +1,19 @@
+"""NestQuest API service.
+
+A standalone FastAPI deployable that owns the NestQuest database and
+exposes it over HTTP to the Home Assistant integration (panel plane) and
+the admin PWA (admin plane).  See Feature 16 (task cd03735b) in the
+project tracker for the full contract.
+
+This package imports the NestQuest domain ``core`` WITHOUT executing
+``custom_components/nestquest/__init__.py`` — that parent package's
+``__init__.py`` imports ``homeassistant``, which is absent from the
+API's runtime.  The coupling is encapsulated in
+:mod:`api.nestquest_core`, which loads ``core`` by file location with
+:mod:`importlib.util` and registers it under the distinct top-level name
+``nestquest_core`` (no ``sys.path`` mutation, no generic top-level
+names published).  It is a TRANSITIONAL coupling that Feature 18 will
+revisit: once the integration becomes a thin API client and ``core``
+moves out of the integration bundle, this helper goes away.
+"""
+from __future__ import annotations

api/app.py

@@ -0,0 +1,139 @@
+"""The NestQuest FastAPI application.
+
+This module builds the ASGI app for the NestQuest API service (Feature
+16).  The skeleton here wires the bundled ``core`` (Feature 15) and
+exposes the two endpoints every later task depends on:
+
+- ``GET /health`` — returns ``200`` with a JSON status body once the
+  app has imported core, opened the database, and applied migrations;
+  a cheap ``SELECT 1`` confirms the connection is live without leaking
+  the filesystem path on an unauthenticated route.
+- ``GET /api/v1/panel/snapshot`` — the panel plane's today snapshot
+  (service-token protected; see :mod:`api.routes_panel`, whose router
+  carries the shared :func:`api.dependencies.require_panel_token`
+  check).
+- ``GET /api/v1/admin/ping`` — the admin plane's auth probe, protected
+  by the Authentik OIDC JWT check (see :mod:`api.routes_admin`, whose
+  router carries the shared :func:`api.auth.require_admin_jwt`
+  dependency; the JWKS document it verifies against is cached on
+  ``app.state.jwks_cache``).
+- ``GET /docs`` — FastAPI's auto-served OpenAPI document (Swagger UI);
+  ``/openapi.json`` is the raw schema.  No extra wiring is needed;
+  FastAPI serves both by default.
+
+The database is opened and migrated in a FastAPI lifespan context so a
+startup failure (e.g. an unwritable path) surfaces as a startup error
+rather than the first request.  The connection is closed on shutdown.
+
+This module exports ONLY the :func:`create_app` factory — there is no
+module-level app instance, because building one at import time would
+read ``NESTQUEST_DB_PATH`` at import (and fail-fast on a missing value)
+before any worker is ready to report it.  Serve with::
+
+    uvicorn --factory api.app:create_app
+
+so the factory runs on each worker startup and reads the environment
+then.
+"""
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator
+
+from fastapi import FastAPI
+
+from api.auth import JwksCache
+from api.config import ApiConfig
+from api.database import DatabaseState, make_database
+from api.events import TransitionPublisher
+from api.routes_admin import router as admin_router
+from api.routes_panel import router as panel_router
+from api.scheduler import MissedSweepScheduler
+
+
+def _build_lifespan(db_path: str):
+    """Return a lifespan that opens+migrates then closes one database.
+
+    Captured as a closure so the app factory can hand the configured
+    path in without threading it through FastAPI's lifespan signature.
+    The lifespan also installs the app's ONE in-process transition
+    publisher on ``app.state.publisher`` (see :mod:`api.events`) so
+    every route and SSE subscriber shares that single instance, and
+    starts the daily missed-sweep scheduler
+    (:class:`api.scheduler.MissedSweepScheduler`) against the same
+    database and publisher — cancelled before the connection closes on
+    shutdown.
+    """
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        state = make_database(db_path)
+        app.state.db = state
+        app.state.publisher = TransitionPublisher()
+        scheduler = MissedSweepScheduler(
+            state.database, publisher=app.state.publisher
+        )
+        app.state.sweep_scheduler = scheduler
+        try:
+            await state.open_and_migrate()
+            scheduler.start()
+            yield
+        finally:
+            await scheduler.stop()
+            await state.close()
+
+    return lifespan
+
+
+def create_app(config: ApiConfig | None = None) -> FastAPI:
+    """Build the NestQuest API FastAPI app.
+
+    ``config`` defaults to one built from the process environment, so
+    ``uvicorn --factory api.app:create_app`` picks up
+    ``NESTQUEST_DB_PATH`` (and fails fast on startup if it is missing).
+    Tests pass an explicit config so each test gets a hermetic temp
+    SQLite file.
+    """
+    cfg = config if config is not None else ApiConfig.from_env()
+
+    app = FastAPI(
+        title="NestQuest API",
+        description=(
+            "Standalone HTTP service that owns the NestQuest database and "
+            "exposes it to the Home Assistant integration (panel plane) and "
+            "the admin PWA (admin plane)."
+        ),
+        version="0.1.0",
+        lifespan=_build_lifespan(cfg.db_path),
+    )
+
+    # The resolved config rides on app.state so the reusable route
+    # dependencies (the panel service-token check, the admin JWT check)
+    # read the configured values from the app rather than module state.
+    app.state.config = cfg
+    # The admin plane's ONE per-app JWKS cache: fetched from the
+    # configured provider on first use, then reused until its TTL
+    # lapses (see api.auth.JwksCache).  Tests replace it with a
+    # stub-backed cache so no request ever leaves the process.
+    app.state.jwks_cache = JwksCache(cfg.oidc_jwks_url)
+    app.include_router(panel_router)
+    app.include_router(admin_router)
+
+    @app.get("/health", summary="Service health")
+    async def health() -> dict[str, str]:
+        """Return service health.
+
+        Returns ``200`` with ``{"status": "ok"}`` once the lifespan has
+        opened and migrated the database.  A cheap ``SELECT 1`` against
+        the live connection confirms the database is reachable WITHOUT
+        leaking the filesystem path on an unauthenticated route; if the
+        connection is dead the query raises and the probe fails.
+        """
+        state: DatabaseState = app.state.db
+        await state.database.fetch_one("SELECT 1")
+        return {"status": "ok"}
+
+    return app
+
+
+__all__ = ["create_app"]

api/auth.py

@@ -0,0 +1,490 @@
+"""Admin-plane authentication for the NestQuest API service.
+
+The admin plane (``/api/v1/admin/*``, D-012) is authenticated by
+Authentik-issued OIDC access tokens: the admin PWA presents its JWT as
+a Bearer credential and :func:`require_admin_jwt` — the ONE
+implementation of that check — verifies it before any admin route runs.
+Verification enforces, without exception:
+
+- the signature, against the RSA signing key published in the
+  provider's JWKS document (fetched from the configured
+  ``NESTQUEST_OIDC_JWKS_URL`` and cached per app — never per request);
+- the issuer (``iss`` must equal the configured
+  ``NESTQUEST_OIDC_ISSUER``);
+- the audience (``aud`` must carry the configured
+  ``NESTQUEST_OIDC_AUDIENCE``);
+- expiry (``exp`` is required and enforced, and ``nbf`` is enforced
+  when the token carries it).
+
+Every rejection raises the SAME :class:`~fastapi.HTTPException` with
+the same detail — nothing in the response distinguishes which check
+failed.  The check FAILS CLOSED: a missing app config, a malformed or
+missing ``Authorization`` header, a non-RS256 algorithm, an unknown
+``kid``, and any PyJWT verification error all yield the one 401.
+
+The token's header (``alg``, ``kid``) is parsed and checked BEFORE the
+JWKS cache is consulted, so structurally invalid tokens can never
+amplify load on the provider.  An unknown ``kid`` forces ONE
+TTL-bypassing refetch (throttled, see :class:`JwksCache`) so a rotated
+key is picked up without waiting out the TTL, and a JWKS entry that
+matches the ``kid`` but carries corrupt key material maps to the same
+401.  A JWKS FETCH failure is deliberately NOT mapped to 401: the
+provider being unreachable is a server-side fault (an HTTP 500
+surfaces) and never poisons the cache, so the plane stays closed while
+the real cause is visible in the server log instead of disguised as a
+bad credential; a short backoff window after a failed fetch fails fast
+(re-raising the recorded fault) rather than fetching once per request.
+
+Beyond authentication, :func:`require_admin` is the ONE dependency
+every admin route uses: it REJECTS the panel service token outright —
+that credential authenticates the panel plane only, so treating it as
+a JWT candidate would blur two credential types into one check — and
+then requires the verified JWT's ``groups`` claim to name the
+``nestquest-admins`` group (authorization, 403, distinct from the
+uniform authentication 401 so the two failure classes stay apart).
+"""
+from __future__ import annotations
+
+import asyncio
+import binascii
+import json
+import secrets
+import time
+from collections.abc import Awaitable, Callable
+from typing import Annotated
+
+import httpx
+import jwt
+from fastapi import Header, HTTPException, Request
+
+#: The authorization scheme the admin plane expects.  Matched
+#: case-insensitively, as RFC 9110 requires for scheme names.
+_BEARER_SCHEME = "bearer"
+
+#: The ONLY JWT signing algorithm accepted.  Pinned to one asymmetric
+#: algorithm (Authentik's RS256 default) so neither the header's ``alg``
+#: nor any JWKS key can talk the verifier into a weaker or symmetric
+#: scheme; PyJWT re-enforces it at decode time.
+_ALLOWED_ALGORITHM = "RS256"
+
+#: The 401 detail shared by every rejection — deliberately uniform so
+#: the response never reveals which part of the check failed.
+_REJECTION_DETAIL = "Missing or invalid admin credentials"
+
+#: Challenge header returned with a 401, per the Bearer auth scheme.
+_WWW_AUTHENTICATE = {"WWW-Authenticate": "Bearer"}
+
+#: The authorization group a verified admin JWT must name in its
+#: ``groups`` claim.  A module constant (the value Authentik's
+#: nestquest-admins group maps to) so it is clearly named in one place.
+ADMIN_GROUP = "nestquest-admins"
+
+#: Seconds a fetched JWKS document stays trusted before the next
+#: fetch.  Five minutes bounds how long a rotated-away key keeps
+#: verifying while staying far above a per-request fetch.
+_JWKS_TTL_SECONDS = 300.0
+
+#: Seconds a FAILED JWKS fetch blocks further fetch attempts.  Within
+#: this window after a failure the cache fails fast — it re-raises the
+#: recorded fault instead of touching the provider — so an outage is
+#: never amplified into one fetch per request.
+_JWKS_BACKOFF_SECONDS = 5.0
+
+#: Seconds that must pass before ANOTHER forced (TTL-bypassing) refetch
+#: may run.  An unmatched ``kid`` forces one refetch to pick up rotated
+#: keys; this interval bounds it, so a flood of unknown-``kid`` tokens
+#: cannot turn each request into a provider fetch either.
+_JWKS_KID_REFETCH_SECONDS = 5.0
+
+#: Seconds before the real JWKS fetch gives up on the provider.
+_JWKS_TIMEOUT_SECONDS = 5.0
+
+#: An async callable that fetches the JWKS document from a URL.  The
+#: real one (:func:`_fetch_jwks`) uses httpx; tests inject a stub so
+#: the suite stays hermetic (no network access).
+JwksFetcher = Callable[[str], Awaitable[dict[str, object]]]
+
+
+async def _fetch_jwks(url: str) -> dict[str, object]:
+    """Fetch the provider's JWKS document over HTTP (the real fetch).
+
+    Uses httpx with a short timeout; a non-2xx response or a body that
+    is not a ``{"keys": [...]}`` object raises — the cache never stores
+    a failed or malformed fetch.
+    """
+    async with httpx.AsyncClient(timeout=_JWKS_TIMEOUT_SECONDS) as client:
+        response = await client.get(url)
+        response.raise_for_status()
+        document = response.json()
+    if not isinstance(document, dict) or not isinstance(
+        document.get("keys"), list
+    ):
+        raise ValueError("JWKS document must be an object with a keys list")
+    return document
+
+
+class JwksCache:
+    """One app's cache of the OIDC provider's JWKS document.
+
+    The document is fetched through ``fetcher`` (the real one uses
+    httpx against the configured JWKS URL) and held for ``ttl_seconds``
+    — the dependency NEVER fetches per request.  A single fetch is
+    shared between concurrent requests via an :class:`asyncio.Lock`
+    (double-checked around it), and a failed fetch is never cached, so
+    the next request retries once the backoff window lapses rather than
+    being locked out until the TTL does.
+
+    Two bounds keep the provider out of an amplification loop:
+
+    - ``backoff_seconds``: after a FAILED fetch, :meth:`get` fails fast
+      for this long — re-raising the recorded fault WITHOUT touching
+      the fetcher or even the lock — instead of retrying per request.
+    - ``kid_refetch_seconds``: forced (TTL-bypassing) refetches — the
+      unmatched-``kid`` path — may run at most this often; a forced
+      refetch that is bounded out (or one inside the backoff window)
+      is served from the cached document as-is.
+
+    A successful fetch always clears the backoff; the document itself
+    is still trusted only for ``ttl_seconds`` — nothing is cached
+    indefinitely.
+
+    One instance lives on ``app.state.jwks_cache`` (installed by
+    :func:`api.app.create_app`); tests replace it with one built around
+    a stub fetcher, keeping the suite hermetic.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        ttl_seconds: float = _JWKS_TTL_SECONDS,
+        backoff_seconds: float = _JWKS_BACKOFF_SECONDS,
+        kid_refetch_seconds: float = _JWKS_KID_REFETCH_SECONDS,
+        fetcher: JwksFetcher | None = None,
+    ) -> None:
+        self._url = url
+        self._ttl_seconds = ttl_seconds
+        self._backoff_seconds = backoff_seconds
+        self._kid_refetch_seconds = kid_refetch_seconds
+        self._fetcher: JwksFetcher = (
+            fetcher if fetcher is not None else _fetch_jwks
+        )
+        self._document: dict[str, object] | None = None
+        self._fetched_at: float | None = None
+        self._failed_until: float | None = None
+        self._last_error: BaseException | None = None
+        self._forced_at: float | None = None
+        self._lock = asyncio.Lock()
+
+    async def get(self, *, force: bool = False) -> dict[str, object]:
+        """Return the JWKS document, refetching it if the TTL lapsed.
+
+        With ``force=True`` the TTL is bypassed so an unmatched ``kid``
+        can pick up a rotated key without waiting it out; the forced
+        refetch is itself bounded (see the class docstring): inside the
+        backoff window or the ``kid_refetch_seconds`` interval the
+        cached document is served as-is instead.  A failed fetch is
+        re-raised to the caller (a provider outage is a server fault,
+        never a 401) and starts the backoff window, during which every
+        caller — including forced ones with nothing cached — fails fast
+        on the recorded fault.
+        """
+        if not force:
+            fresh = self._fresh_document()
+            if fresh is not None:
+                return fresh
+        error = self._backoff_error()
+        if error is not None:
+            # Fail fast OUTSIDE the lock: a request inside the backoff
+            # window must not queue behind an in-flight fetch.
+            if force:
+                document = self._document
+                if document is not None:
+                    return document
+            raise error
+        async with self._lock:
+            if not force:
+                fresh = self._fresh_document()
+                if fresh is not None:
+                    return fresh
+            error = self._backoff_error()
+            if error is not None:
+                if force:
+                    document = self._document
+                    if document is not None:
+                        return document
+                raise error
+            if force and self._refetch_throttled():
+                document = self._document
+                if document is not None:
+                    return document
+            return await self._fetch_locked(force=force)
+
+    def _fresh_document(self) -> dict[str, object] | None:
+        """The cached document if one exists and is inside its TTL."""
+        document = self._document
+        fetched_at = self._fetched_at
+        if (
+            document is not None
+            and fetched_at is not None
+            and (time.monotonic() - fetched_at) < self._ttl_seconds
+        ):
+            return document
+        return None
+
+    def _backoff_error(self) -> BaseException | None:
+        """The recorded fetch fault while the backoff window is open."""
+        failed_until = self._failed_until
+        last_error = self._last_error
+        if (
+            failed_until is not None
+            and last_error is not None
+            and time.monotonic() < failed_until
+        ):
+            return last_error
+        return None
+
+    def _refetch_throttled(self) -> bool:
+        """Whether a forced refetch ran too recently to run another."""
+        forced_at = self._forced_at
+        return forced_at is not None and (
+            time.monotonic() - forced_at
+        ) < self._kid_refetch_seconds
+
+    async def _fetch_locked(self, *, force: bool) -> dict[str, object]:
+        """Run ONE fetch attempt (caller holds the lock) and record it.
+
+        A failed fetch starts the ``backoff_seconds`` window and is
+        re-raised; a successful one stores the document, restarts the
+        TTL and clears the backoff.  A forced attempt stamps
+        ``_forced_at`` so the ``kid_refetch_seconds`` interval bounds
+        how often forced refetches may run back-to-back.
+        """
+        if force:
+            self._forced_at = time.monotonic()
+        try:
+            document = await self._fetcher(self._url)
+        except Exception as error:
+            self._failed_until = time.monotonic() + self._backoff_seconds
+            self._last_error = error
+            raise
+        self._document = document
+        self._fetched_at = time.monotonic()
+        self._failed_until = None
+        self._last_error = None
+        return document
+
+
+#: 403 detail for the panel service token on an admin route.  Deliberately
+#: non-leaking: it names the credential TYPE, not its value or where it came
+#: from.  403 (not 401) because this is a REFUSED credential type, not an
+#: absent/invalid one — challenging re-authentication would suggest the same
+#: credential could work with a retry, which it never can here.
+_PANEL_TOKEN_REJECTION_DETAIL = "This credential type is not accepted for admin access"
+
+#: 403 detail for a valid JWT that is not a member of the admin group.
+#: Distinct from the uniform 401 on purpose: the token AUTHENTICATED, but
+#: the caller is not AUTHORIZED, so the response may say so.
+_FORBIDDEN_DETAIL = "Admin access requires membership in the nestquest-admins group"
+
+
+def _reject() -> HTTPException:
+    """Build the single 401 the dependency raises for every failure."""
+    return HTTPException(
+        status_code=401,
+        detail=_REJECTION_DETAIL,
+        headers=_WWW_AUTHENTICATE,
+    )
+
+
+def _matching_key(jwks: dict[str, object], kid: str) -> object | None:
+    """Return the RSA signing key named ``kid`` from the JWKS.
+
+    Only ``kty: RSA`` entries are considered (the pinned RS256 scheme
+    is asymmetric RSA); anything else — a missing ``keys`` list, no
+    entry with that ``kid`` — returns ``None`` rather than falling back
+    to "some" key.  The key is built through PyJWT's JWKS decoder, and
+    an entry that MATCHES the ``kid`` but carries corrupt key material
+    (a malformed ``n``/``e`` raises ``ValueError`` — ``binascii.Error``
+    is its subclass — or ``TypeError`` instead of a ``PyJWTError``) is
+    mapped to the one 401 like every other rejection: the caller must
+    never see a half-built key.
+    """
+    keys = jwks.get("keys")
+    if not isinstance(keys, list):
+        raise _reject()
+    for entry in keys:
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("kid") != kid or entry.get("kty") != "RSA":
+            continue
+        try:
+            return jwt.algorithms.RSAAlgorithm.from_jwk(json.dumps(entry))
+        except (
+            jwt.PyJWTError,
+            binascii.Error,
+            ValueError,
+            TypeError,
+            KeyError,
+        ):
+            raise _reject() from None
+    return None
+
+
+async def verify_admin_token(
+    request: Request, token: str
+) -> dict[str, object]:
+    """Verify ONE admin bearer token and return its verified claims.
+
+    Reads the OIDC settings off ``app.state.config`` and the JWKS cache
+    off ``app.state.jwks_cache`` (both installed by
+    :func:`api.app.create_app`) so the check carries no module state.
+    A missing config or cache, an EMPTY configured issuer/audience/JWKS
+    URL, a non-RS256 ``alg`` header, an absent ``kid``, an unknown
+    ``kid``, and any PyJWT verification failure (bad signature,
+    expired, wrong issuer, wrong audience, not-yet-valid, missing
+    ``exp``) raise the SAME 401 — the failure mode is never leaked.
+    ``exp`` is REQUIRED (a token that never expires is never accepted)
+    and PyJWT enforces ``nbf`` when the token carries it.
+
+    The token's HEADER (``alg``, ``kid``) is parsed and enforced BEFORE
+    the JWKS cache is consulted, so a structurally invalid token costs
+    no fetch, no lock, no provider load.  When the cached document has
+    no entry for the ``kid``, ONE forced (TTL-bypassing, throttled)
+    refetch is made and the match retried once — a rotated key is
+    picked up without waiting out the TTL — before the 401.
+
+    A JWKS fetch failure propagates (see the module docstring): the
+    provider being down is a server fault, not a bad credential.
+    """
+    config = getattr(request.app.state, "config", None)
+    if (
+        config is None
+        or not config.oidc_issuer
+        or not config.oidc_audience
+        or not config.oidc_jwks_url
+    ):
+        raise _reject()
+    cache = getattr(request.app.state, "jwks_cache", None)
+    if cache is None:
+        raise _reject()
+    try:
+        header = jwt.get_unverified_header(token)
+    except jwt.PyJWTError:
+        raise _reject() from None
+    if header.get("alg") != _ALLOWED_ALGORITHM:
+        raise _reject()
+    kid = header.get("kid")
+    if not isinstance(kid, str) or not kid:
+        raise _reject()
+    jwks = await cache.get()
+    try:
+        key = _matching_key(jwks, kid)
+        if key is None:
+            # The kid is not in the cached document: force ONE
+            # TTL-bypassing refetch (bounded by the cache) and retry
+            # the match once before rejecting.
+            jwks = await cache.get(force=True)
+            key = _matching_key(jwks, kid)
+            if key is None:
+                raise _reject()
+        claims = jwt.decode(
+            token,
+            key=key,
+            algorithms=[_ALLOWED_ALGORITHM],
+            issuer=config.oidc_issuer,
+            audience=config.oidc_audience,
+            options={"require": ["exp"]},
+        )
+    except jwt.PyJWTError:
+        raise _reject() from None
+    return claims
+
+
+async def require_admin_jwt(
+    request: Request,
+    authorization: Annotated[str | None, Header()] = None,
+) -> dict[str, object]:
+    """Reject the request with 401 unless it carries a valid admin JWT.
+
+    Extracts the Bearer credential — a missing or malformed
+    ``Authorization`` header (wrong scheme, empty credential) raises
+    the one 401 — and delegates the verification to
+    :func:`verify_admin_token`, returning the verified claims for the
+    route to use (the probe route surfaces the token's ``sub``).
+
+    The nestquest-admins GROUP check lives in :func:`require_admin`,
+    which wraps this dependency; ``require_admin_jwt`` remains the plain
+    JWT-validation contract — the 401 path stays exactly this uniform.
+    """
+    if authorization is None:
+        raise _reject()
+    scheme, _, credential = authorization.partition(" ")
+    if scheme.lower() != _BEARER_SCHEME or not credential.strip():
+        raise _reject()
+    return await verify_admin_token(request, credential.strip())
+
+
+async def require_admin(
+    request: Request,
+    authorization: Annotated[str | None, Header()] = None,
+) -> dict[str, object]:
+    """The ONE admin-plane dependency: service-token refusal + group gate.
+
+    Order matters.  FIRST the Bearer credential is compared against the
+    configured panel service token (``app.state.config.panel_token``):
+    a match is refused OUTRIGHT with 403 — BEFORE any JWT parsing — so
+    the panel credential is never even treated as a JWT candidate, let
+    alone a non-admin JWT.  (403 rather than 401 because this is a
+    refused credential TYPE, not an invalid one: challenging
+    re-authentication would imply retrying could ever succeed; the
+    detail names the type only, never the value.)  A config with an
+    EMPTY panel token never matches anything, so it cannot lock every
+    Bearer request out.
+
+    Otherwise the credential goes through the existing JWT path
+    (:func:`require_admin_jwt` → :func:`verify_admin_token`): a missing
+    or malformed header and any invalid JWT still yield the SAME
+    uniform 401 as before.  A VALID JWT is then checked for
+    authorization: its ``groups`` claim must be a list containing
+    :data:`ADMIN_GROUP` — a missing, empty, or non-list ``groups`` or
+    one without the group raises 403 (distinct from the 401 on
+    purpose: the token authenticated, the caller did not authorize).
+
+    Returns the verified claims for the route.
+    """
+    if authorization is not None:
+        scheme, _, credential = authorization.partition(" ")
+        if scheme.lower() == _BEARER_SCHEME and credential.strip():
+            config = getattr(request.app.state, "config", None)
+            if (
+                config is not None
+                and config.panel_token
+                # compare_digest on bytes (as require_panel_token does)
+                # so the refusal does not short-circuit on the first
+                # mismatching byte — a constant-time comparison keeps a
+                # timing side channel on the credential off the table.
+                and secrets.compare_digest(
+                    credential.strip().encode("utf-8"),
+                    config.panel_token.encode("utf-8"),
+                )
+            ):
+                raise HTTPException(
+                    status_code=403,
+                    detail=_PANEL_TOKEN_REJECTION_DETAIL,
+                )
+    claims = await require_admin_jwt(request, authorization)
+    groups = claims.get("groups")
+    if not isinstance(groups, list) or ADMIN_GROUP not in groups:
+        raise HTTPException(status_code=403, detail=_FORBIDDEN_DETAIL)
+    return claims
+
+
+__all__ = [
+    "ADMIN_GROUP",
+    "JwksCache",
+    "JwksFetcher",
+    "require_admin",
+    "require_admin_jwt",
+    "verify_admin_token",
+]

api/config.py

@@ -0,0 +1,174 @@
+"""Configuration for the NestQuest API service.
+
+The API reads its configuration knobs from environment variables:
+
+- ``NESTQUEST_DB_PATH`` — the SQLite database file.  The API opens this
+  file on startup (creating it if absent) and applies migrations.
+- ``NESTQUEST_PANEL_TOKEN`` — the static panel-plane service token
+  (D-012): the credential ``/api/v1/panel/*`` routes require via
+  :func:`api.dependencies.require_panel_token`.  It is stored outside
+  the repo and handed to the service through the environment.
+- ``NESTQUEST_OIDC_ISSUER`` — the Authentik OIDC issuer URL whose
+  ``iss`` claim admin tokens must carry (D-012 admin plane).
+- ``NESTQUEST_OIDC_AUDIENCE`` — the OIDC client id the admin tokens
+  must carry as their ``aud`` claim (the API service's client id).
+- ``NESTQUEST_OIDC_JWKS_URL`` — the Authentik endpoint serving the
+  signing keys (the JWKS document) the admin tokens' signatures are
+  verified against.  Cached per app (see :class:`api.auth.JwksCache`).
+
+Unlike a dev convenience default, a missing or empty value is a
+configuration ERROR, not a silent fallback: a default database path
+would silently drop data at reboot, a default (or empty) service token
+would either authenticate everyone or lock the panel plane out for
+good, and a default (or empty) OIDC setting would silently leave the
+admin plane trusting an issuer that was never configured.  All five
+variables are therefore REQUIRED — ``ApiConfig.from_env`` RAISES when
+any of them is unset or empty.  This mirrors the integration's
+"explicit settings object" discipline (Feature 15's ``core.settings``):
+the API never reads HA config; callers pass the resolved values into
+the wiring.
+
+Serving: the app is built with the factory ``api.app:create_app`` — run
+it with ``uvicorn --factory api.app:create_app`` so the factory reads
+the environment on each worker startup rather than at import time.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+#: Environment variable holding the SQLite file path.  The API opens
+#: this file on startup (creating it if absent) and applies migrations.
+#: REQUIRED — unset or empty raises :class:`ConfigError` from
+#: :meth:`ApiConfig.from_env`.
+DB_PATH_ENV = "NESTQUEST_DB_PATH"
+
+#: Environment variable holding the static panel-plane service token
+#: (D-012), checked by :func:`api.dependencies.require_panel_token`.
+#: REQUIRED — unset or empty raises :class:`ConfigError` from
+#: :meth:`ApiConfig.from_env`; there is no silent default, because an
+#: empty configured token would either authenticate every caller or
+#: lock the panel plane out permanently.
+PANEL_TOKEN_ENV = "NESTQUEST_PANEL_TOKEN"
+
+#: Environment variable holding the Authentik OIDC issuer URL (D-012
+#: admin plane): every admin JWT's ``iss`` claim must equal it.  Checked
+#: by :func:`api.auth.require_admin_jwt`.  REQUIRED — unset or empty
+#: raises :class:`ConfigError` from :meth:`ApiConfig.from_env`; a default
+#: issuer would silently make the admin plane trust tokens from an
+#: issuer nobody configured.
+OIDC_ISSUER_ENV = "NESTQUEST_OIDC_ISSUER"
+
+#: Environment variable holding the OIDC audience (the API service's
+#: client id at Authentik): every admin JWT's ``aud`` claim must carry
+#: it.  Checked by :func:`api.auth.require_admin_jwt`.  REQUIRED — unset
+#: or empty raises :class:`ConfigError` from :meth:`ApiConfig.from_env`.
+OIDC_AUDIENCE_ENV = "NESTQUEST_OIDC_AUDIENCE"
+
+#: Environment variable holding the Authentik JWKS URL: the endpoint
+#: serving the signing keys admin JWT signatures are verified against.
+#: Fetched and cached by :class:`api.auth.JwksCache`.  REQUIRED — unset
+#: or empty raises :class:`ConfigError` from :meth:`ApiConfig.from_env`;
+#: without the provider's keys no token can be verified, so a silent
+#: default would only move the failure to request time.
+OIDC_JWKS_URL_ENV = "NESTQUEST_OIDC_JWKS_URL"
+
+
+class ConfigError(RuntimeError):
+    """Raised when required API configuration is missing or invalid."""
+
+
+@dataclass(frozen=True)
+class ApiConfig:
+    """Resolved API configuration.
+
+    Every field is required (no defaults): ``from_env`` rejects an
+    unset or empty value for each, and a caller building the dataclass
+    directly must pass explicit values — the token check and the JWT
+    checks themselves fail closed on empty configured values, but
+    expecting a caller to discover that at request time is a wiring
+    mistake, so every field is mandatory.  Kept as a dataclass so later
+    tasks (SSE, settings persistence) can extend it without touching
+    the call sites that read ``db_path``.
+    """
+
+    db_path: str
+    panel_token: str
+    #: The Authentik OIDC issuer URL admin tokens' ``iss`` must equal.
+    oidc_issuer: str
+    #: The OIDC audience (the API service's client id) admin tokens'
+    #: ``aud`` must carry.
+    oidc_audience: str
+    #: The Authentik JWKS URL the signing keys are fetched from.
+    oidc_jwks_url: str
+
+    @classmethod
+    def from_env(cls, env: dict[str, str] | None = None) -> "ApiConfig":
+        """Build configuration from the process environment.
+
+        ``env`` defaults to ``os.environ``; tests pass an explicit dict
+        so they are hermetic (no monkeypatch of the global environ).
+
+        Raises :class:`ConfigError` when ANY of the five variables is
+        unset or empty/whitespace-only — there is no silent default:
+
+        - ``NESTQUEST_DB_PATH``: a default in the temp directory would
+          silently lose data at reboot;
+        - ``NESTQUEST_PANEL_TOKEN``: a default token is never invented —
+          the panel plane is closed until a real one is configured;
+        - the three OIDC variables: an unconfigured issuer/audience/JWKS
+          URL must not silently leave the admin plane open (a default
+          JWKS URL or issuer would point at a provider nobody set up).
+        """
+        source = env if env is not None else os.environ
+
+        def require(env_var: str, reason: str) -> str:
+            """Return the stripped env value or raise ConfigError."""
+            value = source.get(env_var, "").strip()
+            if not value:
+                raise ConfigError(f"{env_var} {reason}")
+            return value
+
+        return cls(
+            db_path=require(
+                DB_PATH_ENV,
+                "must be set to a writable SQLite file path (it is unset "
+                "or empty — the API will not fall back to a temp directory "
+                "and silently lose data)",
+            ),
+            panel_token=require(
+                PANEL_TOKEN_ENV,
+                "must be set to the panel service token (it is unset or "
+                "empty — the API will not start without one, and no "
+                "default token is invented)",
+            ),
+            oidc_issuer=require(
+                OIDC_ISSUER_ENV,
+                "must be set to the Authentik OIDC issuer URL (it is "
+                "unset or empty — the admin plane will not trust tokens "
+                "from an issuer nobody configured)",
+            ),
+            oidc_audience=require(
+                OIDC_AUDIENCE_ENV,
+                "must be set to the OIDC audience the admin tokens carry "
+                "(it is unset or empty — the admin plane will not accept "
+                "tokens without a configured audience)",
+            ),
+            oidc_jwks_url=require(
+                OIDC_JWKS_URL_ENV,
+                "must be set to the Authentik JWKS URL (it is unset or "
+                "empty — admin token signatures cannot be verified "
+                "without the provider's signing keys)",
+            ),
+        )
+
+
+__all__ = [
+    "ApiConfig",
+    "ConfigError",
+    "DB_PATH_ENV",
+    "OIDC_AUDIENCE_ENV",
+    "OIDC_ISSUER_ENV",
+    "OIDC_JWKS_URL_ENV",
+    "PANEL_TOKEN_ENV",
+]

api/database.py

@@ -0,0 +1,82 @@
+"""Database wiring for the NestQuest API service.
+
+The API owns the database (it is the writer of record per Feature 16's
+contract).  This module owns one application-lifetime
+:class:`core.db.NestQuestDatabase`: it opens the SQLite file at the
+configured path on startup, applies migrations (creating the schema on
+a fresh file), and closes the connection on shutdown.
+
+The executor callable passed into ``NestQuestDatabase`` mirrors the
+contract of ``hass.async_add_executor_job``: schedule a synchronous
+callable on a worker and await its result.  HA's own version lives on
+the event loop; the API is not HA, so it uses
+:func:`asyncio.to_thread` for the same effect — sqlite3 calls run on a
+worker thread and only plain data returns to the event loop.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from api.nestquest_core import core_db, core_migrations
+
+LOGGER = logging.getLogger(__name__)
+
+#: The async SQLite wrapper.  Re-exported so route handlers and later
+#: tasks reach it through the API package, not the bundled core.
+NestQuestDatabase = core_db.NestQuestDatabase
+
+#: The migration runner.  Re-exported for the same reason.
+apply_migrations = core_migrations.apply_migrations
+
+
+async def _executor(fn: Any, *args: Any, **kwargs: Any) -> Any:
+    """Run a synchronous callable on a worker thread and await its result.
+
+    Mirrors the contract of ``hass.async_add_executor_job`` so the
+    bundled ``NestQuestDatabase`` (written against that contract) works
+    unchanged in the API process: sqlite3 calls never block the event
+    loop, and only plain Python data (row tuples,
+    :class:`core.db.ExecutionResult`) crosses back.
+    """
+    return await asyncio.to_thread(fn, *args, **kwargs)
+
+
+class DatabaseState:
+    """Holds the live database wrapper and its resolved path.
+
+    A small container so the lifespan and the route handlers share one
+    authoritative reference; FastAPI's lifespan stores one of these on
+    ``app.state.db`` and the health route reads it back.
+    """
+
+    __slots__ = ("database", "db_path")
+
+    def __init__(self, database: NestQuestDatabase, db_path: str) -> None:
+        self.database = database
+        self.db_path = db_path
+
+    async def open_and_migrate(self) -> None:
+        """Open the connection and apply migrations to the latest version."""
+        LOGGER.info("Opening NestQuest database at %s", self.db_path)
+        await self.database.open(self.db_path)
+        version = await apply_migrations(self.database)
+        LOGGER.info("NestQuest schema at version %d", version)
+
+    async def close(self) -> None:
+        """Close the connection; safe to call even if open failed."""
+        await self.database.close()
+
+
+def make_database(db_path: str) -> DatabaseState:
+    """Construct a :class:`DatabaseState` for the given path (not yet open)."""
+    return DatabaseState(NestQuestDatabase(_executor), db_path)
+
+
+__all__ = [
+    "DatabaseState",
+    "NestQuestDatabase",
+    "apply_migrations",
+    "make_database",
+]

api/dependencies.py

@@ -0,0 +1,81 @@
+"""Reusable FastAPI dependencies for the NestQuest API routes.
+
+The panel plane (``/api/v1/panel/*``) is authenticated by the static
+service token configured through ``NESTQUEST_PANEL_TOKEN`` (D-012): the
+HA integration presents it as a Bearer credential on every panel
+request.  :func:`require_panel_token` is the ONE implementation of that
+check — every panel route (this task's snapshot route and each later
+panel route) declares it as a dependency rather than re-implementing
+token handling, so the credential, the failure behaviour, and the
+401 contract stay in exactly one place.
+
+The dependency FAILS CLOSED: a missing ``Authorization`` header, a
+malformed one (wrong scheme or empty credential), a token that does not
+match the configured value, and an empty configured token all yield
+HTTP 401.  The comparison is constant-time (:func:`secrets.compare_digest`)
+so the wall-clock difference between "wrong length" and "wrong value"
+cannot be used to probe the token byte by byte, and every rejection
+carries the same detail — nothing in the response distinguishes which
+part of the check failed.
+"""
+from __future__ import annotations
+
+import secrets
+from typing import Annotated
+
+from fastapi import Header, HTTPException, Request
+
+#: The authorization scheme the panel plane expects.  Matched
+#: case-insensitively, as RFC 9110 requires for scheme names.
+_BEARER_SCHEME = "bearer"
+
+#: The 401 detail shared by every rejection — deliberately uniform so
+#: the response never reveals which part of the check failed.
+_REJECTION_DETAIL = "Missing or invalid panel service token"
+
+#: Challenge header returned with a 401, per the Bearer auth scheme.
+_WWW_AUTHENTICATE = {"WWW-Authenticate": "Bearer"}
+
+
+def _reject() -> HTTPException:
+    """Build the single 401 the dependency raises for every failure."""
+    return HTTPException(
+        status_code=401,
+        detail=_REJECTION_DETAIL,
+        headers=_WWW_AUTHENTICATE,
+    )
+
+
+async def require_panel_token(
+    request: Request,
+    authorization: Annotated[str | None, Header()] = None,
+) -> None:
+    """Reject the request with 401 unless it carries the panel token.
+
+    Reads the configured token off ``app.state.config`` (set by
+    :func:`api.app.create_app`) so the dependency stays reusable across
+    routes and carries no module state of its own.  A missing or
+    malformed ``Authorization`` header, a non-matching credential, and
+    an EMPTY configured token (a wiring mistake) all raise the same
+    ``HTTPException(401)`` — the check is closed even when the service
+    is misconfigured.
+
+    Returns ``None`` on success; FastAPI discards a ``None`` return,
+    the route handler simply proceeds.
+    """
+    config = getattr(request.app.state, "config", None)
+    expected = config.panel_token if config is not None else ""
+    if not expected or authorization is None:
+        raise _reject()
+    scheme, _, credential = authorization.partition(" ")
+    if scheme.lower() != _BEARER_SCHEME or not credential.strip():
+        raise _reject()
+    # compare_digest on bytes so a non-ASCII token raises nothing and a
+    # timing side channel on the str path is not available.
+    if not secrets.compare_digest(
+        credential.strip().encode("utf-8"), expected.encode("utf-8")
+    ):
+        raise _reject()
+
+
+__all__ = ["require_panel_token"]

api/events.py

@@ -0,0 +1,78 @@
+"""The ONE in-process transition-event publisher for the API service.
+
+Route handlers call :meth:`TransitionPublisher.publish` synchronously
+(no ``await``, callable from any async handler); SSE subscribers stream
+those transitions through an async generator.  The scope of "ONE" is
+deliberate: a single :class:`TransitionPublisher` instance is created
+in the app lifespan and stored on ``app.state.publisher`` — per-app,
+so tests build their own hermetic app without module-level state, and
+both the panel complete route and the SSE endpoint resolve the SAME
+instance off ``request.app.state`` (exactly one publisher exists per
+running app; nothing else may create one).
+
+Design (small and dependency-free, asyncio only):
+
+- Each subscriber gets its own ``asyncio.Queue(maxsize=64)``.
+- ``publish`` is synchronous and non-blocking: it puts the event on
+  every live queue with ``put_nowait``.  A slow subscriber that lets
+  its queue fill gets the event DROPPED (oldest overflow) — never a
+  blocked publisher, never unbounded growth.
+- A disconnected subscriber's queue is removed in the generator's
+  ``finally`` block, so teardown is clean and a closed consumer cannot
+  leak its queue.
+
+Fan-out is fire-and-forget by design: the SSE plane mirrors transition
+events for the panel UI; a dropped event costs the panel one UI
+refresh, and the documented recovery path is the next snapshot poll.
+"""
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+
+#: Per-subscriber queue capacity.  Bounded so a stalled consumer can
+#: never make the publisher or another subscriber wait; beyond this
+#: the slow subscriber drops the event (see module docstring).
+_QUEUE_MAXSIZE = 64
+
+__all__ = ["TransitionPublisher"]
+
+
+class TransitionPublisher:
+    """A single in-process fan-out point for transition events."""
+
+    def __init__(self) -> None:
+        """Create the publisher with no subscribers."""
+        self._subscribers: set[asyncio.Queue] = set()
+
+    def publish(self, event_type: str, payload: dict) -> None:
+        """Fan one transition event out to every current subscriber.
+
+        Synchronous and non-blocking: each subscriber's bounded queue
+        is filled with ``put_nowait``, and a FULL queue silently drops
+        the event for that (slow) subscriber rather than blocking the
+        route handler or growing without bound.
+        """
+        for queue in tuple(self._subscribers):
+            try:
+                queue.put_nowait((event_type, payload))
+            except asyncio.QueueFull:
+                # The subscriber is not keeping up; drop the event for
+                # it and move on (the panel recovers by polling).
+                pass
+
+    async def subscribe(self) -> AsyncIterator[tuple[str, dict]]:
+        """Yield ``(event_type, payload)`` tuples until the consumer breaks.
+
+        Registers ONE bounded queue for the duration of the iteration
+        and removes it in the ``finally`` block, so a client disconnect
+        (or any break out of the loop) tears the subscription down
+        cleanly with no leaked queue.
+        """
+        queue: asyncio.Queue = asyncio.Queue(maxsize=_QUEUE_MAXSIZE)
+        self._subscribers.add(queue)
+        try:
+            while True:
+                yield await queue.get()
+        finally:
+            self._subscribers.discard(queue)

api/nestquest_core.py

@@ -0,0 +1,233 @@
+"""Transitional coupling: import ``core`` without importing Home Assistant.
+
+The NestQuest domain ``core`` package (Feature 15) is bundled INSIDE the
+Home Assistant integration at ``custom_components/nestquest/core/``.
+Importing it the obvious way — ``import custom_components.nestquest.core``
+— would execute ``custom_components/nestquest/__init__.py``, which
+imports ``homeassistant``.  Home Assistant is NOT installed in the API
+service's runtime, so that import raises ``ModuleNotFoundError`` and the
+API cannot start.
+
+``core`` itself is a clean, Home-Assistant-free package: its
+``__init__.py`` is a bare docstring and every internal import is
+relative (``from .db import ...``).  It can therefore be imported by
+file location as a standalone package.
+
+This module loads ``core`` with :func:`importlib.util.spec_from_file_location`
+— registering it under the distinct top-level name ``nestquest_core``
+with ``submodule_search_locations`` set to the bundled ``core``
+directory — so its relative imports resolve against that directory
+without touching ``sys.path``.  No generic top-level name (``db``,
+``const``, ``schema``, ...) is published, so nothing here can silently
+shadow a future dependency, and the integration's HA-coupled
+``__init__.py`` is never executed: ``custom_components.nestquest`` is
+never imported.
+
+Usage::
+
+    from api.nestquest_core import core_db, core_migrations
+    # core_db.NestQuestDatabase, core_migrations.apply_migrations, ...
+
+This is a TRANSITIONAL coupling.  Feature 18 (task 430f7f98) converts
+the integration into a thin API client and moves ``core`` out of the
+integration bundle; once that lands, this bootstrap helper goes away and
+the API imports ``core`` as an ordinary installed dependency.
+
+NOTE on the pytest process: the suite's ``conftest.py`` stubs the
+parent integration package and imports ``custom_components.nestquest.core.*``
+BEFORE any API test runs, so two copies of the core package coexist in
+the pytest process — the one registered here as ``nestquest_core.*``
+(loaded by file location) and the conftest-stubbed
+``custom_components.nestquest.core.*``.  Later tasks must NOT compare
+class or exception identity across these two copies: a
+``nestquest_core.db.NestQuestDatabase`` is a DIFFERENT class object from
+``custom_components.nestquest.core.db.NestQuestDatabase`` even though
+they share source.  Operate on a single copy within any one code path.
+"""
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+#: The repository root (this file is ``<root>/api/nestquest_core.py``).
+_REPO_ROOT: Path = Path(__file__).resolve().parent.parent
+
+#: The bundled ``core`` package directory, inside the HA integration.
+_CORE_DIR: Path = _REPO_ROOT / "custom_components" / "nestquest" / "core"
+
+#: The ``core`` package's ``__init__.py`` — a bare docstring, so loading
+#: it by file location executes no imports of its own.
+_CORE_INIT: Path = _CORE_DIR / "__init__.py"
+
+#: The distinct top-level name under which the bundled ``core`` package
+#: is registered in ``sys.modules``.  A distinctive name (rather than the
+#: generic ``core``) avoids publishing shadow-able top-level names and
+#: keeps the bundled copy separate from the conftest-stubbed
+#: ``custom_components.nestquest.core`` present in the pytest process.
+_CORE_MODULE_NAME = "nestquest_core"
+
+
+def _load_core() -> ModuleType:
+    """Load the bundled ``core`` package by file location and return it.
+
+    Registers the package under :data:`_CORE_MODULE_NAME` in
+    ``sys.modules`` with ``submodule_search_locations`` pointing at the
+    bundled directory, so its relative imports (``from .db import ...``)
+    resolve to ``nestquest_core.<submodule>`` against that directory
+    without mutating ``sys.path``.  Idempotent: a second call returns
+    the already-registered module.
+    """
+    existing = sys.modules.get(_CORE_MODULE_NAME)
+    if existing is not None:
+        return existing
+    spec = importlib.util.spec_from_file_location(
+        _CORE_MODULE_NAME,
+        _CORE_INIT,
+        submodule_search_locations=[str(_CORE_DIR)],
+    )
+    if spec is None or spec.loader is None:
+        raise ImportError(f"could not load core from {_CORE_INIT}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[_CORE_MODULE_NAME] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+#: The bundled core package, loaded by file location and registered as
+#: ``nestquest_core`` in ``sys.modules``.  Held here so callers import the
+#: submodules through it (``nestquest_core.db``, ``nestquest_core.migrations``)
+#: the same relative way the integration does.
+core: ModuleType = _load_core()
+
+#: Re-exported for convenience; route handlers import these names from
+#: here rather than reaching into the core package directly.
+core_db = importlib.import_module(f"{_CORE_MODULE_NAME}.db")
+core_migrations = importlib.import_module(f"{_CORE_MODULE_NAME}.migrations")
+
+#: The panel snapshot builder and its payload shaper
+#: (``core.snapshot.build_snapshot`` / ``instance_payload``) — the pure
+#: assembly the panel routes call.
+core_snapshot = importlib.import_module(f"{_CORE_MODULE_NAME}.snapshot")
+
+#: The completion service (``core.completion.complete_instance`` /
+#: ``uncomplete_instance``) the panel's write routes call.
+core_completion = importlib.import_module(f"{_CORE_MODULE_NAME}.completion")
+
+#: The read-only history layer (``core.history.query_history``,
+#: ``export_history_csv``, ``rows_to_csv``) the admin plane's history
+#: query and CSV export routes call.
+core_history = importlib.import_module(f"{_CORE_MODULE_NAME}.history")
+
+#: The transition-event builders (``core.events.build_quest_completed_event``
+#: et al.) the panel's write routes build their SSE events with.
+core_events = importlib.import_module(f"{_CORE_MODULE_NAME}.events")
+
+#: The explicit settings object (``core.settings.NestQuestSettings``)
+#: the snapshot builder's ``settings`` parameter takes.
+core_settings = importlib.import_module(f"{_CORE_MODULE_NAME}.settings")
+
+#: The durable settings store (``core.settings_store.load_settings`` /
+#: ``update_settings``) the admin plane's settings routes read and
+#: write — the API's OWN settings source: a validated JSON document in
+#: the existing ``nestquest_meta_state`` table, resolved through the
+#: same core settings validators (the integration's HA config-entry
+#: options remain a temporary separate source until Feature 18 wires
+#: the client to the API).
+core_settings_store = importlib.import_module(
+    f"{_CORE_MODULE_NAME}.settings_store"
+)
+
+#: The children business layer (``core.children.create_child`` et al.)
+#: the admin plane's children routes call.
+core_children = importlib.import_module(f"{_CORE_MODULE_NAME}.children")
+
+#: The quest-definition business layer (``core.quest_definitions`` —
+#: ``create_quest_definition``, ``edit_quest_definition``,
+#: ``set_quest_definition_active``) the admin plane's quest-definition
+#: routes call.
+core_quest_definitions = importlib.import_module(
+    f"{_CORE_MODULE_NAME}.quest_definitions"
+)
+
+#: The icon-key module (``core.icons.normalize_icon_for_read``) the
+#: admin plane's quest-definition responses normalize ``icon`` through.
+core_icons = importlib.import_module(f"{_CORE_MODULE_NAME}.icons")
+
+#: The recurrence model (``core.recurrence.ScheduleRule`` and
+#: ``RuleValidationError``) the quest-definition routes build request
+#: rules with — the model validates at construction, the routes never
+#: re-implement rule validation.
+core_recurrence = importlib.import_module(f"{_CORE_MODULE_NAME}.recurrence")
+
+#: The presence model (``core.presence.PresenceEngine``,
+#: ``PresencePattern``, ``PresenceOverride``) the admin plane's
+#: presence routes serialize and the tests resolve presence with.
+core_presence = importlib.import_module(f"{_CORE_MODULE_NAME}.presence")
+
+#: The presence-write business layer
+#: (``core.presence_management.create_presence_pattern`` et al.) the
+#: admin plane's presence routes call — the ONE implementation the HA
+#: services share.
+core_presence_management = importlib.import_module(
+    f"{_CORE_MODULE_NAME}.presence_management"
+)
+
+#: The typed presence DAOs (``core.dao_presence``) the admin-plane tests
+#: read stored patterns and overrides back through.
+core_dao_presence = importlib.import_module(
+    f"{_CORE_MODULE_NAME}.dao_presence"
+)
+
+#: The materialization walk (``core.materialize.materialize``,
+#: ``regenerate_for_definition``, ``regenerate_for_child``) the admin
+#: plane's regenerate route calls — the same walk the integration's
+#: config/presence changes trigger.
+core_materialize = importlib.import_module(f"{_CORE_MODULE_NAME}.materialize")
+
+#: The core constants module (``core.const.DEFAULT_HORIZON_DAYS``) the
+#: regenerate route sizes the household rolling horizon with.
+core_const = importlib.import_module(f"{_CORE_MODULE_NAME}.const")
+
+#: The typed child DAO (``core.dao_children.ChildrenDao.get``) the
+#: regenerate route reads a child's existence with before delegating.
+core_dao_children = importlib.import_module(
+    f"{_CORE_MODULE_NAME}.dao_children"
+)
+
+#: The typed definition DAO (``core.dao_rules.QuestDefinitionsDao.get``)
+#: the regenerate route reads a definition's existence with before
+#: delegating.
+core_dao_rules = importlib.import_module(f"{_CORE_MODULE_NAME}.dao_rules")
+
+#: The HA-free missed sweep (``core.sweep.run_missed_sweep`` +
+#: ``SWEEP_WATERMARK_KEY``) the admin plane's trigger route calls and
+#: the daily scheduler runs — the ONE sweep policy the integration's
+#: bus shim shares.
+core_sweep = importlib.import_module(f"{_CORE_MODULE_NAME}.sweep")
+
+__all__ = [
+    "core",
+    "core_children",
+    "core_completion",
+    "core_const",
+    "core_dao_children",
+    "core_dao_presence",
+    "core_dao_rules",
+    "core_db",
+    "core_events",
+    "core_history",
+    "core_icons",
+    "core_materialize",
+    "core_migrations",
+    "core_presence",
+    "core_presence_management",
+    "core_quest_definitions",
+    "core_recurrence",
+    "core_snapshot",
+    "core_settings",
+    "core_settings_store",
+    "core_sweep",
+]

api/requirements.txt

@@ -0,0 +1,38 @@
+# Runtime dependency manifest for the NestQuest API deployable.
+#
+# The monorepo's pyproject.toml carries fastapi/uvicorn/pyjwt/httpx in
+# the INTEGRATION's dev group only (so the test venv can exercise the
+# API); they are deliberately NOT integration runtime dependencies.
+# Per that manifest's own comment, the API deployable declares its own
+# runtime dependencies HERE — this file is what the container image
+# installs (see the Dockerfile at the repository root).
+#
+# EXACT pins: the versions installed in the deployed image
+# (nestquest-api:latest on the API box, read with importlib.metadata),
+# so a rebuild resolves the same packages.  The four direct
+# dependencies come first; the rest is their resolved transitive
+# closure, pinned too so nothing floats.  The dev group's floors in
+# pyproject.toml are unchanged.  Bump deliberately, together with the
+# Dockerfile's digest-pinned base image.
+fastapi==0.141.1
+uvicorn==0.53.0
+pyjwt[crypto]==2.15.0
+httpx==0.28.1
+
+# Transitive dependencies of the above.
+annotated-doc==0.0.5
+annotated-types==0.8.0
+anyio==4.15.1
+certifi==2026.7.22
+cffi==2.1.1
+click==8.5.0
+cryptography==50.0.1
+h11==0.16.0
+httpcore==1.0.9
+idna==3.20
+pycparser==3.0
+pydantic==2.13.5
+pydantic_core==2.46.5
+starlette==1.7.0
+typing-inspection==0.4.4
+typing_extensions==4.16.0

api/routes_panel.py

@@ -0,0 +1,350 @@
+"""Panel-plane routes for the NestQuest API service.
+
+The panel plane (``/api/v1/panel/*``, D-012) serves the wall panel's
+reads.  Every route on :data:`router` requires the panel service token
+through the ONE reusable dependency :func:`api.dependencies.require_panel_token`
+(declared once at the router level, so each later panel route added to
+this router inherits the check).
+
+The snapshot route is a thin adapter over the bundled core: it performs
+NO business logic.  It reads the live database off ``app.state.db``,
+resolves ONE timezone-aware ``now`` (the API host's local time — the
+API is the household's "local" host now that the domain no longer lives
+inside Home Assistant), calls the pure
+:func:`nestquest_core.snapshot.build_snapshot`, shapes each child's
+instances through :func:`nestquest_core.snapshot.instance_payload` with
+``include_missed=False`` (D-009: missed instances are OMITTED from the
+panel payload), and returns the documented JSON shape:
+
+.. code-block:: json
+
+    {
+      "today_iso": "2026-09-22",
+      "cycle_day": 2,
+      "children": [
+        {
+          "child_id": 1,
+          "child_name": "Ada",
+          "present": false,
+          "next_present": "2026-09-24",
+          "due_today": 1,
+          "completed_today": 0,
+          "remaining_today": 1,
+          "completion_pct": 0,
+          "instances": [
+            {"id": 7, "definition_id": 3, "child_id": 1,
+             "title": "Pack bag", "icon": null, "window": "morning",
+             "due_time": "10:00", "state": "open", "overdue": true,
+             "completed_at": null, "on_time": null}
+          ]
+        }
+      ]
+    }
+
+``children`` follows the household's sort order (the core builder lists
+active children ``ORDER BY sort_order, id``); ``state`` is the
+documented panel spelling ``open`` | ``completed`` (§1 of
+design/ENTITIES-AND-SERVICES.md); ``cycle_day`` is today's 1-based day
+in the first scheduled child's custody cycle (0 when no child has one).
+The same :class:`PanelSnapshotResponse` Pydantic model is the route's
+``response_model``, so the OpenAPI document carries the shape too.
+"""
+from __future__ import annotations
+
+import datetime
+import importlib
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, field_validator
+
+from api.database import DatabaseState
+from api.dependencies import require_panel_token
+from api.nestquest_core import (
+    core_completion,
+    core_events,
+    core_settings,
+    core_snapshot,
+)
+from api import transitions as api_transitions
+from api.sse import transition_event_stream
+
+#: The instance DAO, imported on the app's core copy for the
+#: child-mismatch guard on the complete route.
+_dao_instances = importlib.import_module("nestquest_core.dao_instances")
+
+#: All panel-plane routes share this router; the service-token check is
+#: attached HERE so every panel route (current and later) requires it.
+router = APIRouter(
+    prefix="/api/v1/panel",
+    dependencies=[Depends(require_panel_token)],
+)
+
+
+class PanelInstancePayload(BaseModel):
+    """One instance in the documented panel payload shape (§1).
+
+    Mirrors :func:`nestquest_core.snapshot.instance_payload`:
+    ``state`` is ``open`` | ``completed`` (missed instances never reach
+    the panel payload), ``on_time`` passes the completion event's flag
+    through verbatim (``None`` for an open instance), and
+    ``completed_at`` is the event's UTC timestamp when completed.
+    """
+
+    id: int
+    definition_id: int
+    child_id: int
+    title: str
+    icon: str | None
+    window: str
+    due_time: str | None
+    state: str
+    overdue: bool
+    completed_at: str | None
+    on_time: bool | None
+
+
+class PanelChildPayload(BaseModel):
+    """One child's day: presence, rollup counts, and today's instances."""
+
+    child_id: int
+    child_name: str
+    present: bool
+    #: ISO date of the child's next present day while they are away
+    #: (the away plate renders ``Returns <weekday>, <Mon D>`` from it);
+    #: ``None`` when the child is present today.
+    next_present: str | None
+    due_today: int
+    completed_today: int
+    remaining_today: int
+    completion_pct: int
+    instances: list[PanelInstancePayload]
+
+
+class PanelSnapshotResponse(BaseModel):
+    """The whole household snapshot the panel renders from.
+
+    ``today_iso`` anchors the payload's day; ``cycle_day`` is today's
+    1-based day in the first scheduled child's custody cycle (0 when no
+    child has a schedule); ``children`` is in the household's sort
+    order.
+    """
+
+    today_iso: str
+    cycle_day: int
+    children: list[PanelChildPayload]
+
+
+class PanelCompleteRequest(BaseModel):
+    """The body of ``POST /api/v1/panel/instances/{id}/complete``.
+
+    Matches the panel's ``nestquest.complete_quest`` payload (§2 of
+    design/ENTITIES-AND-SERVICES.md): ``actor_child_id`` is the tapped
+    profile.  A positive integer is required — the core completion
+    layer rejects non-int (and bool) ids anyway, but rejecting them
+    here with 422 keeps the contract visible in the OpenAPI document
+    and fails before any database work.
+    """
+
+    actor_child_id: int
+
+    model_config = {
+        "json_schema_extra": {
+            "description": (
+                "The tapped child profile the completion is "
+                "attributed to (decision 9)."
+            )
+        }
+    }
+
+    @field_validator("actor_child_id")
+    @classmethod
+    def _positive(cls, value: int) -> int:
+        """Reject zero and negative ids with a validation error."""
+        if value < 1:
+            raise ValueError("actor_child_id must be a positive integer")
+        return value
+
+
+def _local_now() -> datetime.datetime:
+    """Return the API host's local time as ONE timezone-aware clock read.
+
+    ``now().astimezone()`` attaches the host's local timezone to a
+    single clock read, so the calendar date and wall-clock time the
+    builder derives can never disagree.  Kept as a module function (not
+    inlined) so tests pin the instant the same way the coordinator's
+    ``_local_now`` is pinned.
+    """
+    return datetime.datetime.now().astimezone()
+
+
+@router.get(
+    "/snapshot",
+    summary="Today's household snapshot",
+    response_model=PanelSnapshotResponse,
+)
+async def panel_snapshot(request: Request) -> PanelSnapshotResponse:
+    """Return today's full household snapshot for the panel.
+
+    Requires the panel service token (checked by the router's shared
+    :func:`~api.dependencies.require_panel_token` dependency).  Builds
+    the snapshot through the pure core builder against the live
+    database and shapes each child's instances with
+    ``instance_payload(include_missed=False)`` — missed instances are
+    OMITTED from the panel payload (D-009) — then returns the shape
+    documented in this module's docstring and
+    :class:`PanelSnapshotResponse`.
+    """
+    state: DatabaseState = request.app.state.db
+    snapshot = await core_snapshot.build_snapshot(
+        state.database, core_settings.NestQuestSettings(), _local_now()
+    )
+    return PanelSnapshotResponse(
+        today_iso=snapshot.today_iso,
+        cycle_day=snapshot.cycle_day,
+        children=[
+            PanelChildPayload(
+                child_id=child.child_id,
+                child_name=child.child_name,
+                present=child.present,
+                next_present=child.next_present,
+                due_today=child.due_today,
+                completed_today=child.completed_today,
+                remaining_today=child.remaining_today,
+                completion_pct=child.completion_pct,
+                instances=[
+                    PanelInstancePayload.model_validate(instance)
+                    for instance in core_snapshot.instance_payload(
+                        child.instances, include_missed=False
+                    )
+                ],
+            )
+            for child in snapshot.children
+        ],
+    )
+
+
+@router.post(
+    "/instances/{instance_id}/complete",
+    summary="Complete one quest instance",
+    status_code=200,
+)
+async def panel_complete_instance(
+    instance_id: int, body: PanelCompleteRequest, request: Request
+) -> dict[str, str]:
+    """Complete one quest instance as the tapped child profile.
+
+    Requires the panel service token (checked by the router's shared
+    :func:`~api.dependencies.require_panel_token` dependency — the ONE
+    token check; this handler performs NO auth of its own).
+
+    Thin adapter only: resolves the live database off ``app.state.db``,
+    reads ONE timezone-aware clock (:func:`_local_now`), and delegates
+    to :func:`nestquest_core.completion.complete_instance` with
+    ``actor_source="panel"`` and the tapped ``actor_child_id`` — the
+    append/idempotence logic, the lock, and the actor-shape validation
+    all live in the core layer, never here.
+
+    Response and idempotence: ``complete_instance`` returns a
+    :class:`~nestquest_core.completion.CompletionResult` whose
+    ``appended`` flag reports whether THIS call wrote an event; a
+    repeat call for an already-completed instance is a no-op inside
+    the core layer (no duplicate event) and this route still answers
+    ``{"status": "done"}`` either way, so a retried panel tap succeeds.
+
+    Error mapping (deliberately narrow): the ONLY ``ValueError`` mapped
+    to 404 is the unknown-``instance_id`` one, identified by the
+    ``instance_id:`` prefix ``complete_instance`` names the failing
+    field with.  Every other ``ValueError`` (an invalid actor shape,
+    which the body model and the panel actor contract already make
+    unreachable) re-raises to the framework's 500 — nothing else is
+    turned into a 404 or a 500 of our own making.
+
+    Child mismatch: ``complete_instance`` verifies the tapped
+    ``actor_child_id`` exists but does NOT check it is the child the
+    instance belongs to.  The route performs that check here (one
+    ``QuestInstancesDao.get_by_id`` read) and answers 404 when the
+    instance's ``child_id`` differs — completing another child's quest
+    from the wrong profile must not succeed, and 404 (not 403) keeps
+    the instance's existence from leaking to a wrong-profile tap.
+    """
+    state: DatabaseState = request.app.state.db
+    database = state.database
+
+    # Child-mismatch guard (see docstring): the instance must belong to
+    # the tapped profile before the completion layer is entered.
+    instance = await _dao_instances.QuestInstancesDao(database).get_by_id(
+        instance_id
+    )
+    if instance is not None and instance.child_id != body.actor_child_id:
+        raise HTTPException(
+            status_code=404,
+            detail="Quest instance not found for this child",
+        )
+
+    now = _local_now()
+    try:
+        result = await core_completion.complete_instance(
+            database,
+            instance_id,
+            actor_source="panel",
+            actor_child_id=body.actor_child_id,
+            now=now,
+        )
+    except ValueError as error:
+        message = str(error)
+        if message.startswith("instance_id:"):
+            # complete_instance names the field in its ValueError:
+            # "instance_id: quest instance N does not exist".
+            raise HTTPException(
+                status_code=404,
+                detail="Quest instance not found",
+            ) from error
+        raise
+    # The derived state is "done" in both the appended and no-op cases;
+    # ``result.appended`` distinguishes them for callers that care —
+    # the panel route returns the same success either way.
+    if result.appended:
+        # An ACTUAL transition: publish the SSE transition event.  The
+        # payload is built by the core builder (never hand-built here)
+        # and fan-out is fire-and-forget (see api/events.py).
+        event_type, payload = await core_events.build_quest_completed_event(
+            database, instance_id, was_on_time=result.was_on_time
+        )
+        request.app.state.publisher.publish(event_type, payload)
+        # THEN evaluate the day-complete rule off the completed event's
+        # payload (the core builder decides when the child's whole day
+        # is cleared — a zero-quest day and a non-today instance never
+        # fire it).  ``today`` comes from the route's single clock read
+        # so the calendar date can never disagree with the completion's.
+        await api_transitions.publish_child_day_complete(
+            database,
+            payload,
+            now.date(),
+            request.app.state.publisher,
+        )
+    return {"status": str(result)}
+
+
+@router.get(
+    "/events",
+    summary="Stream panel transition events (SSE)",
+)
+async def panel_events(request: Request) -> StreamingResponse:
+    """Stream the app's transition events to the panel (Server-Sent
+    Events).
+
+    Requires the panel service token (checked by the router's shared
+    :func:`~api.dependencies.require_panel_token` dependency — the ONE
+    token check; this handler performs NO auth of its own).
+
+    Returns the shared :func:`api.sse.transition_event_stream` response
+    off the app's single in-process publisher (``app.state.publisher``,
+    installed in the lifespan).  The stream ends when the client
+    disconnects, at which point the subscription is torn down (its
+    queue removed) with nothing leaked.
+    """
+    return transition_event_stream(request)
+
+
+__all__ = ["router"]

api/scheduler.py

@@ -0,0 +1,173 @@
+"""Daily missed-sweep background scheduler for the API service.
+
+The API service has no Home Assistant, so nobody re-fires the
+integration's day-rollover listener for it: this module owns the API
+plane's own background job.  One :class:`MissedSweepScheduler` per app
+(installed on ``app.state`` by the lifespan) sleeps until the
+configured ``day_rollover_time`` — read fresh from the settings store
+at the top of EVERY cycle, so an admin's settings change applies on
+the next scheduling decision without a restart — then runs the
+HA-free core's :func:`nestquest_core.sweep.run_missed_sweep` for the
+API host's local date and publishes each returned
+``nestquest_quest_missed`` event on the app's ONE transition publisher
+(the same SSE stream every route publishes through).
+
+All sweep policy lives in the core (the watermark, the
+``[watermark, today)`` window, the no-completion-event rule): this
+scheduler only decides WHEN.  A same-night rerun — e.g. two workers,
+or a settings change moving the rollover past itself — fires nothing:
+the core's watermark makes the run an empty no-op.
+
+Testability: ``clock`` (an aware-now callable) and ``sleep`` (an
+awaitable delay) are injectable, so tests pin the time, fast-forward
+through the wait, and observe the computed delays without waiting a
+real day.  Cancellation: :meth:`stop` cancels the loop task and waits
+for it, so the lifespan's shutdown is clean and a mid-run sweep is
+interrupted before the connection closes.  A failed iteration (a
+database hiccup, a rejected setting) is logged and retried after a
+fixed backoff rather than silently killing the job.
+"""
+from __future__ import annotations
+
+import asyncio
+import datetime
+import logging
+
+from api.nestquest_core import core_settings_store, core_sweep
+
+LOGGER = logging.getLogger(__name__)
+
+#: Backoff after a failed scheduling cycle (settings read or sweep
+#: error), so a persistent failure retries every minute instead of
+#: spinning or dying.
+_RETRY_BACKOFF_SECONDS = 60.0
+
+
+def _delay_seconds(target: datetime.time, now: datetime.datetime) -> float:
+    """Seconds from ``now`` until the next occurrence of ``target``.
+
+    ``target`` is a plain ``HH:MM`` time of day: the next wall-clock
+    occurrence strictly AFTER ``now`` (an equal time schedules for
+    tomorrow, so the just-run sweep is never instantly re-run).
+    """
+    scheduled = now.replace(
+        hour=target.hour, minute=target.minute, second=0, microsecond=0
+    )
+    if scheduled <= now:
+        scheduled += datetime.timedelta(days=1)
+    return (scheduled - now).total_seconds()
+
+
+class MissedSweepScheduler:
+    """Run the missed sweep once per day at ``day_rollover_time``."""
+
+    def __init__(
+        self,
+        database: object,
+        *,
+        publisher: object | None = None,
+        clock: object | None = None,
+        sleep: object | None = None,
+    ) -> None:
+        """Create the scheduler (not yet running).
+
+        ``database`` is the app's live :class:`~api.database.NestQuestDatabase`.
+        ``publisher`` is the app's ONE
+        :class:`~api.events.TransitionPublisher` (publishing is skipped
+        when ``None``).  ``clock`` defaults to the API host's local
+        aware now (``datetime.datetime.now().astimezone()``) — the same
+        single-clock discipline the routes' ``_local_now`` uses;
+        ``sleep`` defaults to :func:`asyncio.sleep`.
+        """
+        self._database = database
+        self._publisher = publisher
+        self._clock = clock if clock is not None else (
+            lambda: datetime.datetime.now().astimezone()
+        )
+        self._sleep = sleep if sleep is not None else asyncio.sleep
+        self._task: asyncio.Task | None = None
+
+    def start(self) -> None:
+        """Start the background loop (idempotent: a running one stays)."""
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(
+                self._run_forever(), name="nestquest-missed-sweep"
+            )
+
+    async def stop(self) -> None:
+        """Cancel the loop and wait for it to finish (safe if never started)."""
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+
+    @property
+    def running(self) -> bool:
+        """Whether the background loop task is alive."""
+        return self._task is not None and not self._task.done()
+
+    async def _run_forever(self) -> None:
+        """Schedule → sweep → repeat, forever (until cancelled)."""
+        while True:
+            try:
+                settings = await core_settings_store.load_settings(
+                    self._database
+                )
+                rollover = datetime.time.fromisoformat(
+                    settings.day_rollover_time
+                )
+            except Exception:
+                # Not silent: the failure is logged and retried after
+                # the backoff, so one bad settings document or a
+                # transient database error never kills the scheduler.
+                LOGGER.exception(
+                    "NestQuest missed-sweep scheduler failed to resolve "
+                    "the day rollover time; retrying in %gs",
+                    _RETRY_BACKOFF_SECONDS,
+                )
+                await self._sleep(_RETRY_BACKOFF_SECONDS)
+                continue
+            delay = _delay_seconds(rollover, self._clock())
+            LOGGER.info(
+                "NestQuest missed sweep scheduled for %s (%.0fs from now)",
+                settings.day_rollover_time,
+                delay,
+            )
+            await self._sleep(delay)
+            try:
+                await self._run_once(self._clock().date())
+            except Exception:
+                # Not silent either: the sweep error is logged and the
+                # loop backs off before the next cycle, whose watermark
+                # re-read makes an already-swept day a no-op.
+                LOGGER.exception(
+                    "NestQuest scheduled missed sweep failed; retrying in "
+                    "%gs",
+                    _RETRY_BACKOFF_SECONDS,
+                )
+                await self._sleep(_RETRY_BACKOFF_SECONDS)
+
+    async def _run_once(self, today: datetime.date) -> None:
+        """Run ONE sweep for ``today`` and publish what it built.
+
+        A failure propagates to :meth:`_run_forever`, which logs it and
+        backs off before the next cycle; the watermark makes a re-run
+        of an already-swept day announce nothing twice.
+        """
+        events = await core_sweep.run_missed_sweep(
+            self._database, today=today
+        )
+        for event_type, payload in events:
+            if self._publisher is not None:
+                self._publisher.publish(event_type, payload)
+        LOGGER.info(
+            "NestQuest scheduled missed sweep for %s published %d event(s)",
+            today.isoformat(),
+            len(events),
+        )
+
+
+__all__ = ["MissedSweepScheduler"]