Describe settings form test accurately: ten form fields, timezone is API-only

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*

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"]

RELEASE_NOTES.md

@@ -1,5 +1,240 @@
 # NestQuest Release Notes
 
+## Version 0.8.0 — 2026-09-25
+
+### 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

THIRD-PARTY-NOTICES.md

@@ -0,0 +1,31 @@
+# Third-party notices
+
+NestQuest bundles glyph data from the icon sets below. The curated names are listed in
+`tools/icons/curated-icons.json`; `tools/icons/generate.mjs` reads each glyph's SVG path
+data from the locally installed packages and generates it into both bundles
+(`admin/src/icons/registry.generated.ts` and `frontend/src/icons/registry.generated.ts`).
+Nothing is loaded from a CDN or fetched at runtime. The package versions used are recorded
+in the header of each generated file.
+
+## Font Awesome Free
+
+- Project: <https://fontawesome.com> · repository: <https://github.com/FortAwesome/Font-Awesome>
+- Package: `@fortawesome/free-solid-svg-icons`
+- Licence: <https://fontawesome.com/license/free>
+  - Icons: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+  - Fonts: [SIL OFL 1.1](https://openfontlicense.org)
+  - Code: [MIT](https://opensource.org/licenses/MIT)
+- Use in NestQuest: a curated subset of the Free **solid** icon set, embedded as SVG path
+  data. No fonts are bundled.
+
+Font Awesome Free by @fontawesome — https://fontawesome.com — icons licensed under CC BY 4.0.
+
+## Lucide
+
+- Project: <https://lucide.dev> · repository: <https://github.com/lucide-icons/lucide>
+- Package: `lucide-react`
+- Licence: [ISC](https://github.com/lucide-icons/lucide/blob/main/LICENSE)
+- Use in NestQuest: a curated subset of Lucide icons, embedded as SVG path data.
+
+Lucide icons are Copyright (c) Lucide Contributors, licensed under the ISC License.
+Portions derived from Feather are Copyright (c) Cole Bemis, licensed under the MIT License.

admin/package-lock.json

@@ -12,12 +12,14 @@
         "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"
@@ -981,6 +983,29 @@
         }
       }
     },
+    "node_modules/@fortawesome/fontawesome-common-types": {
+      "version": "7.3.1",
+      "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-7.3.1.tgz",
+      "integrity": "sha512-k0C0sdHmZtAo6dRDtd1Z/qcpyHbL0CKsjV8seMY/21xGhY5Wsv0XRmiI/xEEH4y2c9b1+jvgNs/3EqhV27yUEA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/@fortawesome/free-solid-svg-icons": {
+      "version": "7.3.1",
+      "resolved": "https://registry.npmjs.org/@fortawesome/free-solid-svg-icons/-/free-solid-svg-icons-7.3.1.tgz",
+      "integrity": "sha512-v0BLa0eqg7ubvVWeNSHVBs8fWH/GJicERZoJaxJ3FE/lj67VSqzoMg9pzfZVOfLMX10y0pGwQAuxoRVVH2patg==",
+      "dev": true,
+      "license": "(CC-BY-4.0 AND MIT)",
+      "dependencies": {
+        "@fortawesome/fontawesome-common-types": "7.3.1"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/@jridgewell/gen-mapping": {
       "version": "0.3.13",
       "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
@@ -2257,6 +2282,16 @@
         "yallist": "^3.0.2"
       }
     },
+    "node_modules/lucide-react": {
+      "version": "1.47.0",
+      "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.47.0.tgz",
+      "integrity": "sha512-o8C23aXpNQypRY73W7fW02EyvWJinEMXgKeGjFoKym0zj3Q73hD97A1IQps1g8C14HTGsOpZL0Am+xjfgFZAbg==",
+      "dev": true,
+      "license": "ISC",
+      "peerDependencies": {
+        "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/lz-string": {
       "version": "1.5.0",
       "resolved": "https://registry.npmjs.org/lz-string/-/lz-string-1.5.0.tgz",

admin/package.json

@@ -14,14 +14,16 @@
     "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/src/App.css

@@ -48,17 +48,6 @@
   border: 0;
 }
 
-.admin-placeholder {
-  margin: 0;
-  padding: 13px;
-  background: var(--nq-a-surface);
-  border: 1px solid var(--nq-a-border);
-  border-radius: 8px;
-  font-size: 13.5px;
-  font-weight: 600;
-  color: var(--nq-a-ink-secondary);
-}
-
 .admin-tabbar {
   position: fixed;
   inset: auto 0 0;

admin/src/App.test.tsx

@@ -29,11 +29,19 @@ describe("NestQuest Admin shell", () => {
 
     fireEvent.click(screen.getByRole("tab", { name: "History" }));
 
-    expect(screen.getByRole("tabpanel").textContent).toContain(
-      "History placeholder",
-    );
+    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

@@ -1,5 +1,9 @@
 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 = [
@@ -13,45 +17,47 @@ type TabId = (typeof TABS)[number]["id"];
 
 export default function App() {
   const [active, setActive] = useState<TabId>("today");
-  // Built screens own their header (ADMIN-SPEC §1); the generic shell header
-  // stays for placeholder tabs and is visually hidden otherwise.
-  const hasScreen = active === "today";
 
   return (
-    <div className="admin-shell">
-      <header className={hasScreen ? "admin-header visually-hidden" : "admin-header"}>
-        <h1 className="admin-title">NestQuest Admin</h1>
-        <p className="admin-subline">Admin console</p>
-      </header>
-      <main
-        className={hasScreen ? "admin-panel admin-panel--screen" : "admin-panel"}
-        role="tabpanel"
-        aria-labelledby={`tab-${active}`}
-      >
-        {active === "today" ? (
-          <TodayTab />
-        ) : (
-          <p className="admin-placeholder">
-            {TABS.find((tab) => tab.id === active)?.label} placeholder — screens
-            arrive in later tasks.
-          </p>
-        )}
-      </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>
+      <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

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import AppRoutes from "./AppRoutes";
 import { storeTokens } from "./auth/oidc";
 import { config } from "./config";
@@ -32,6 +32,32 @@ describe("AppRoutes auth gating", () => {
     ).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([]));
@@ -45,6 +71,9 @@ describe("AppRoutes auth gating", () => {
     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 () => {
@@ -58,6 +87,97 @@ describe("AppRoutes auth gating", () => {
       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", () => {

admin/src/AppRoutes.tsx

@@ -12,7 +12,7 @@ import {
   handleCallback,
   isAuthenticated,
 } from "./auth/oidc";
-import { ApiForbiddenError, apiFetch } from "./api/client";
+import { ApiForbiddenError, ApiUnauthorizedError, apiFetch } from "./api/client";
 import AdminShell from "./App";
 
 type Screen =
@@ -21,18 +21,28 @@ type Screen =
   | { 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) {
-  // A cheap authenticated probe so a 403 surfaces as an explicit refusal
-  // right after login instead of a silent empty shell.
+  // 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 {
-    await apiFetch("/api/v1/children", {}, config);
-    setScreen({ kind: "app" });
+    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 });
@@ -42,9 +52,15 @@ async function probeApi(setScreen: (screen: Screen) => void) {
       setScreen({ kind: "refusal", message: error.message });
       return;
     }
-    // Network or other failures still allow the shell to render; API screens
-    // handle their own errors in later tasks.
-    setScreen({ kind: "app" });
+    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.",
+    });
   }
 }
 
@@ -170,6 +186,25 @@ export default function AppRoutes() {
           </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/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/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/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,146 @@
+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 { EMOJI_MAX_CODE_POINTS, 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;
+
+type EmojiPayloadCase = { payload: string; valid: boolean; why: string };
+
+const emojiPayloadCases = JSON.parse(
+  readFileSync(join(REPO_ROOT, "tools", "icons", "emoji-payload-cases.json"), "utf8"),
+) as { cases: EmojiPayloadCase[] };
+
+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 });
+  });
+
+  // tests/test_core_icons.py asserts the same table against the backend's
+  // validate_icon, so the two emoji rules cannot drift apart silently.
+  it.each(emojiPayloadCases.cases)("emoji verdict matches the shared table: $why", ({ payload, valid }) => {
+    const value = `emoji:${payload}`;
+    expect(resolveIcon(value)).toEqual(valid ? { kind: "emoji", key: value, text: payload } : FALLBACK_ICON);
+  });
+
+  it("the shared emoji table covers the contract edges", () => {
+    const verdicts = new Map(emojiPayloadCases.cases.map(({ payload, valid }) => [payload, valid]));
+    expect(verdicts.get("\ufeff")).toBe(false);
+    expect(verdicts.get("👨\u200d👩\u200d👧\u200d👦")).toBe(true);
+    expect(verdicts.get("🐕 ")).toBe(false);
+    expect(verdicts.get("🐕\u0000")).toBe(false);
+    for (const markup of ["<b>", "a>b", "a&b"]) expect(verdicts.get(markup)).toBe(false);
+    expect(verdicts.get("⭐".repeat(EMOJI_MAX_CODE_POINTS))).toBe(true);
+    expect(verdicts.get("⭐".repeat(EMOJI_MAX_CODE_POINTS + 1))).toBe(false);
+  });
+});
+
+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

@@ -11,6 +11,7 @@
 
   --nq-a-page: #f4f4f6;
   --nq-a-surface: #ffffff;
+  --nq-a-selected: #ebebf8;
   --nq-a-border: #e4e4ea;
   --nq-a-divider: #ededf1;
 
@@ -21,14 +22,23 @@
   --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;
@@ -38,7 +48,13 @@
   --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;
 }
 
 * {

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 the ten settings form fields (timezone is API-only)", 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

@@ -241,6 +241,37 @@
   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;

admin/src/today/TodayTab.test.tsx

@@ -1,7 +1,9 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import { cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+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 {
@@ -221,3 +223,186 @@ describe("TodayTab", () => {
     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

@@ -1,7 +1,7 @@
 /**
  * Today tab — compact density (design/ADMIN-SPEC.md §2.1–2.3, §2.5–2.6).
  */
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import {
   fetchSnapshot,
   type AdminSnapshot,
@@ -9,6 +9,10 @@ import {
   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,
@@ -40,15 +44,22 @@ function isOverdueOpen(instance: SnapshotInstance): boolean {
   return instance.overdue && instance.state === "open";
 }
 
-function ScreenHeader({ sub }: { sub: string }) {
+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>
-      {/* Settings screen is a later task; the control is not wired yet. */}
-      <button type="button" className="today-icon-button" aria-label="Settings">
+      {/* 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>
@@ -144,11 +155,18 @@ function attentionItems(snapshot: AdminSnapshot): AttentionItem[] {
   return [...overdue, ...completed];
 }
 
-function AttentionRow({ item }: { item: AttentionItem }) {
+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);
-  // TODO(e57facc2): wire "Mark done" / "Undo" mutations and live updates.
-  // The admin plane has no complete route yet, so both actions are inert here.
+  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
@@ -173,12 +191,21 @@ function AttentionRow({ item }: { item: AttentionItem }) {
           </div>
         )}
       </div>
-      <button
-        type="button"
-        className={overdue ? "today-action today-action--done" : "today-action today-action--undo"}
-      >
-        {overdue ? "Mark done" : "Undo"}
-      </button>
+      {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>
   );
 }
@@ -197,10 +224,26 @@ function PermissionNote() {
 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;
-    setState({ kind: "loading" });
+    const silent = silentNext.current;
+    silentNext.current = false;
+    if (!silent) setState({ kind: "loading" });
     fetchSnapshot()
       .then((snapshot) => {
         if (!cancelled) setState({ kind: "ready", snapshot });
@@ -211,13 +254,37 @@ export default function TodayTab() {
           error instanceof ApiForbiddenError
             ? error.message
             : "Today's snapshot could not be loaded. Check your connection and try again.";
-        setState({ kind: "error", message });
+        // 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") {
@@ -251,7 +318,11 @@ export default function TodayTab() {
         {attention.length > 0 ? (
           <ul className="today-card today-list" aria-label="Needs attention">
             {attention.map((item) => (
-              <AttentionRow key={item.instance.id} item={item} />
+              <AttentionRow
+                key={item.instance.id}
+                item={item}
+                undo={{ pendingId: undoingId, onUndo: (id) => void undo(id) }}
+              />
             ))}
           </ul>
         ) : (
@@ -264,14 +335,31 @@ export default function TodayTab() {
 
   return (
     <div className="today-screen">
-      <ScreenHeader sub={sub} />
+      <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>
   );
 }

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/nestquest_core.py

@@ -152,6 +152,10 @@ 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
@@ -159,12 +163,12 @@ core_quest_definitions = importlib.import_module(
 core_recurrence = importlib.import_module(f"{_CORE_MODULE_NAME}.recurrence")
 
 #: The presence model (``core.presence.PresenceEngine``,
-#: ``PresenceSchedule``, ``PresenceOverride``) the admin plane's
+#: ``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.set_presence_schedule`` et al.) the
+#: (``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(
@@ -172,7 +176,7 @@ core_presence_management = importlib.import_module(
 )
 
 #: The typed presence DAOs (``core.dao_presence``) the admin-plane tests
-#: read stored schedules and overrides back through.
+#: read stored patterns and overrides back through.
 core_dao_presence = importlib.import_module(
     f"{_CORE_MODULE_NAME}.dao_presence"
 )
@@ -215,6 +219,7 @@ __all__ = [
     "core_db",
     "core_events",
     "core_history",
+    "core_icons",
     "core_materialize",
     "core_migrations",
     "core_presence",

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

@@ -8,9 +8,9 @@ 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
+resolves ONE timezone-aware ``now`` (the host clock re-expressed in the
+stored household ``timezone`` setting — the API host may run UTC while
+the household does not), 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
@@ -53,9 +53,6 @@ from __future__ import annotations
 
 import datetime
 import importlib
-import json
-
-from collections.abc import AsyncIterator
 
 from fastapi import APIRouter, Depends, HTTPException, Request
 from fastapi.responses import StreamingResponse
@@ -66,10 +63,11 @@ from api.dependencies import require_panel_token
 from api.nestquest_core import (
     core_completion,
     core_events,
-    core_settings,
+    core_settings_store,
     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.
@@ -180,6 +178,20 @@ def _local_now() -> datetime.datetime:
     return datetime.datetime.now().astimezone()
 
 
+async def _household_clock(
+    database: object,
+) -> tuple[object, datetime.datetime]:
+    """Return the stored settings and ONE household-local clock read.
+
+    The API host may run UTC while the household does not, so the one
+    :func:`_local_now` read is re-expressed in the stored settings'
+    ``timezone`` (:meth:`NestQuestSettings.household_now`); an unset
+    zone keeps the host's local time.
+    """
+    settings = await core_settings_store.load_settings(database)
+    return settings, settings.household_now(_local_now())
+
+
 @router.get(
     "/snapshot",
     summary="Today's household snapshot",
@@ -198,8 +210,9 @@ async def panel_snapshot(request: Request) -> PanelSnapshotResponse:
     :class:`PanelSnapshotResponse`.
     """
     state: DatabaseState = request.app.state.db
+    settings, now = await _household_clock(state.database)
     snapshot = await core_snapshot.build_snapshot(
-        state.database, core_settings.NestQuestSettings(), _local_now()
+        state.database, settings, now
     )
     return PanelSnapshotResponse(
         today_iso=snapshot.today_iso,
@@ -284,7 +297,7 @@ async def panel_complete_instance(
             detail="Quest instance not found for this child",
         )
 
-    now = _local_now()
+    _settings, now = await _household_clock(database)
     try:
         result = await core_completion.complete_instance(
             database,
@@ -328,23 +341,6 @@ async def panel_complete_instance(
     return {"status": str(result)}
 
 
-async def _sse_stream(request: Request) -> AsyncIterator[str]:
-    """Yield the SSE frames for every published transition event.
-
-    One subscriber of the app's single publisher (resolved off
-    ``app.state.publisher``); each event becomes one
-    ``event: <type>\\ndata: <json>\\n\\n`` frame.  Breaking out of the
-    publisher's subscription (on client disconnect) tears the
-    subscription down cleanly — no queue is leaked.
-    """
-    publisher = request.app.state.publisher
-    async for event_type, payload in publisher.subscribe():
-        yield (
-            f"event: {event_type}\n"
-            f"data: {json.dumps(payload)}\n\n"
-        )
-
-
 @router.get(
     "/events",
     summary="Stream panel transition events (SSE)",
@@ -357,17 +353,13 @@ async def panel_events(request: Request) -> StreamingResponse:
     :func:`~api.dependencies.require_panel_token` dependency — the ONE
     token check; this handler performs NO auth of its own).
 
-    Returns a ``text/event-stream`` response whose body is produced by
-    :func:`_sse_stream` 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.
+    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 StreamingResponse(
-        _sse_stream(request),
-        media_type="text/event-stream",
-        headers={"Cache-Control": "no-cache"},
-    )
+    return transition_event_stream(request)
 
 
 __all__ = ["router"]

api/scheduler.py

@@ -8,7 +8,8 @@ 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
+household-local date (the stored ``timezone`` setting; the API host's
+local date when unset) and publishes each returned
 ``nestquest_quest_missed`` event on the app's ONE transition publisher
 (the same SSE stream every route publishes through).
 
@@ -43,19 +44,56 @@ LOGGER = logging.getLogger(__name__)
 _RETRY_BACKOFF_SECONDS = 60.0
 
 
-def _delay_seconds(target: datetime.time, now: datetime.datetime) -> float:
-    """Seconds from ``now`` until the next occurrence of ``target``.
+#: Upper bound on the minute-by-minute search past a nonexistent wall
+#: time; real DST gaps are an hour, the largest ever skipped a day.
+_MAX_GAP_MINUTES = 2 * 24 * 60
 
-    ``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).
+
+def _resolve_wall_time(
+    day: datetime.date, target: datetime.time, zone: datetime.tzinfo
+) -> datetime.datetime:
+    """The aware instant ``target`` (``HH:MM``) names on ``day`` in ``zone``.
+
+    A nonexistent wall time (inside a spring-forward gap) resolves to
+    the first valid wall minute at/after it — the gap's end, e.g. 02:30
+    on a 02:00→03:00 day becomes 03:00.  An ambiguous wall time (the
+    repeated fall-back hour) resolves to its FIRST occurrence
+    (``fold=0``).
     """
-    scheduled = now.replace(
-        hour=target.hour, minute=target.minute, second=0, microsecond=0
+    wall = datetime.datetime.combine(
+        day, datetime.time(target.hour, target.minute)
     )
-    if scheduled <= now:
-        scheduled += datetime.timedelta(days=1)
-    return (scheduled - now).total_seconds()
+    for _ in range(_MAX_GAP_MINUTES):
+        candidate = wall.replace(tzinfo=zone)
+        round_trip = candidate.astimezone(datetime.timezone.utc).astimezone(
+            zone
+        )
+        if round_trip.replace(tzinfo=None) == wall:
+            return candidate
+        wall += datetime.timedelta(minutes=1)
+    raise ValueError(f"no valid wall time at/after {target} on {day}")
+
+
+def _delay_seconds(target: datetime.time, now: datetime.datetime) -> float:
+    """Real seconds from ``now`` until the next occurrence of ``target``.
+
+    ``target`` is a plain ``HH:MM`` household time of day, resolved in
+    ``now``'s zone by :func:`_resolve_wall_time` (nonexistent → first
+    valid instant after the gap; ambiguous → first occurrence).  The
+    result is the next such instant strictly AFTER ``now`` (an equal
+    time schedules for tomorrow, so the just-run sweep is never
+    instantly re-run).  Both instants are compared and subtracted in
+    UTC: same-``tzinfo`` aware arithmetic is wall-clock arithmetic and
+    would be an hour off across a DST transition.
+    """
+    now_utc = now.astimezone(datetime.timezone.utc)
+    day = now.date()
+    while True:
+        scheduled = _resolve_wall_time(day, target, now.tzinfo)
+        scheduled_utc = scheduled.astimezone(datetime.timezone.utc)
+        if scheduled_utc > now_utc:
+            return (scheduled_utc - now_utc).total_seconds()
+        day += datetime.timedelta(days=1)
 
 
 class MissedSweepScheduler:
@@ -130,7 +168,11 @@ class MissedSweepScheduler:
                 )
                 await self._sleep(_RETRY_BACKOFF_SECONDS)
                 continue
-            delay = _delay_seconds(rollover, self._clock())
+            # The host may run UTC: the rollover is a household wall-clock
+            # time, so the clock read is re-expressed in the stored zone.
+            delay = _delay_seconds(
+                rollover, settings.household_now(self._clock())
+            )
             LOGGER.info(
                 "NestQuest missed sweep scheduled for %s (%.0fs from now)",
                 settings.day_rollover_time,
@@ -138,7 +180,9 @@ class MissedSweepScheduler:
             )
             await self._sleep(delay)
             try:
-                await self._run_once(self._clock().date())
+                await self._run_once(
+                    settings.household_now(self._clock()).date()
+                )
             except Exception:
                 # Not silent either: the sweep error is logged and the
                 # loop backs off before the next cycle, whose watermark

api/sse.py

@@ -0,0 +1,50 @@
+"""The ONE Server-Sent Events response helper for the API service.
+
+Both SSE planes — the panel plane (``/api/v1/panel/events``, panel
+service token, LAN-only) and the admin plane (``/api/v1/admin/events``,
+Authentik admin JWT) — stream the SAME transitions off the SAME
+in-process publisher (``app.state.publisher``, see :mod:`api.events`)
+with the SAME framing and teardown, so the stream lives here once and
+each plane's route only supplies its own router-level auth.
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+
+from fastapi import Request
+from fastapi.responses import StreamingResponse
+
+__all__ = ["transition_event_stream"]
+
+
+async def _sse_stream(request: Request) -> AsyncIterator[str]:
+    """Yield the SSE frames for every published transition event.
+
+    One subscriber of the app's single publisher (resolved off
+    ``app.state.publisher``); each event becomes one
+    ``event: <type>\\ndata: <json>\\n\\n`` frame.  Breaking out of the
+    publisher's subscription (on client disconnect) tears the
+    subscription down cleanly — no queue is leaked.
+    """
+    publisher = request.app.state.publisher
+    async for event_type, payload in publisher.subscribe():
+        yield (
+            f"event: {event_type}\n"
+            f"data: {json.dumps(payload)}\n\n"
+        )
+
+
+def transition_event_stream(request: Request) -> StreamingResponse:
+    """A ``text/event-stream`` response over the app's transition events.
+
+    Performs NO auth of its own: the calling route's router-level
+    dependency is the ONE check for its plane.  The stream ends when
+    the client disconnects, at which point the subscription is torn
+    down (its queue removed) with nothing leaked.
+    """
+    return StreamingResponse(
+        _sse_stream(request),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache"},
+    )

custom_components/nestquest/core/const.py

@@ -112,6 +112,13 @@ CONF_AFTERNOON_REMINDER_ENABLED = "afternoon_reminder_enabled"
 CONF_END_OF_DAY_REPORT_ENABLED = "end_of_day_report_enabled"
 CONF_CELEBRATION_ENABLED = "celebration_enabled"
 DEFAULT_AUTOMATION_ENABLED = True
+# The household's IANA time zone (e.g. ``America/New_York``) the API
+# service reads its clock in.  The empty string keeps the historical
+# behaviour — the API host's own local time — so an existing install is
+# unchanged until the owner sets it.  The integration itself always uses
+# Home Assistant's configured ``time_zone`` and ignores this field.
+CONF_TIMEZONE = "timezone"
+DEFAULT_TIMEZONE = ""
 
 # Panel-plane API client (Feature 18): the integration reaches the
 # NestQuest API service (Feature 16) over HTTP instead of the database.

custom_components/nestquest/core/dao_presence.py

@@ -1,4 +1,4 @@
-"""Typed DAO layer for the presence_schedules and presence_overrides tables.
+"""Typed DAO layer for the presence_patterns and presence_overrides tables.
 
 All SQL for these tables lives in this module per the feature
 guardrails: callers get typed dataclasses back and never see raw rows
@@ -8,11 +8,12 @@ executor and the event loop never blocks.
 
 Semantics per the done-condition and Feature 05:
 
-- A child has AT MOST ONE presence schedule (schema UNIQUE); upserting
-  by child updates the existing row rather than raising.
-- A child with NO schedule row is present every day — the absence of a
-  row is meaningful state, expressed by :meth:`PresenceSchedulesDao.get_by_child`
-  returning None, never by an empty pattern row.
+- A child has ZERO OR MORE presence patterns (schema 9 — no UNIQUE on
+  ``child_id``); each is created, updated and deleted by its own id.
+- A child with NO pattern row is present every day — the absence of a
+  row is meaningful state, expressed by
+  :meth:`PresencePatternsDao.list_by_child` returning an empty list,
+  never by an empty pattern row.
 - Overrides beat the pattern for their date range (that resolution is
   the presence engine's job, Feature 05); the DAO only stores and
   lists them.  A single-day override stores the same date as both
@@ -32,11 +33,13 @@ from .db import NestQuestDatabase
 
 
 @dataclass(frozen=True)
-class PresenceScheduleRecord:
-    """One row of ``presence_schedules``."""
+class PresencePatternRecord:
+    """One row of ``presence_patterns``."""
 
     id: int
     child_id: int
+    name: str
+    kind: str
     cycle_length_weeks: int
     anchor_date: str
     pattern: str
@@ -54,21 +57,23 @@ class PresenceOverrideRecord:
     note: str | None
 
 
-_SCHEDULE_COLUMNS = (
-    "id, child_id, cycle_length_weeks, anchor_date, pattern"
+_PATTERN_COLUMNS = (
+    "id, child_id, name, kind, cycle_length_weeks, anchor_date, pattern"
 )
 _OVERRIDE_COLUMNS = (
     "id, child_id, start_date, end_date, is_present, note"
 )
 
 
-def _schedule_from_row(row: tuple) -> PresenceScheduleRecord:
-    return PresenceScheduleRecord(
+def _pattern_from_row(row: tuple) -> PresencePatternRecord:
+    return PresencePatternRecord(
         id=row[0],
         child_id=row[1],
-        cycle_length_weeks=row[2],
-        anchor_date=row[3],
-        pattern=row[4],
+        name=row[2],
+        kind=row[3],
+        cycle_length_weeks=row[4],
+        anchor_date=row[5],
+        pattern=row[6],
     )
 
 
@@ -83,29 +88,27 @@ def _override_from_row(row: tuple) -> PresenceOverrideRecord:
     )
 
 
-class PresenceSchedulesDao:
-    """Typed async access to the ``presence_schedules`` table."""
+class PresencePatternsDao:
+    """Typed async access to the ``presence_patterns`` table."""
 
     def __init__(self, database: NestQuestDatabase) -> None:
         self._database = database
 
-    async def upsert_by_child(
+    async def create(
         self,
         child_id: int,
+        name: str,
+        kind: str,
         cycle_length_weeks: int,
         anchor_date: str,
         pattern: str,
-    ) -> PresenceScheduleRecord:
-        """Set the child's presence schedule, replacing any existing one.
+    ) -> PresencePatternRecord:
+        """Insert one pattern for the child and return it as stored.
 
-        Upsert semantics are the done-condition: a second schedule for
-        the same child updates the existing row rather than raising.
-        Runs under the connection lock so a concurrent upsert/delete
-        for the same child serializes instead of colliding on the
-        schema's UNIQUE(child_id).  Pattern validity (segment shape,
-        segment count = cycle_length_weeks) is enforced by the schema
-        CHECKs; the child must exist (FK) — validated atomically here
-        so a deleted child cannot pass a stale check.
+        The child must exist (FK) — validated atomically under the
+        connection lock so a deleted child cannot pass a stale check.
+        ``kind``, the cycle length and the pattern shape (segment count
+        = ``cycle_length_weeks``) are enforced by the schema CHECKs.
         """
         _validate_date(anchor_date, "anchor_date")
         async with _connection_lock(self._database):
@@ -115,53 +118,98 @@ class PresenceSchedulesDao:
                 )
                 if child is None:
                     raise ValueError(f"child {child_id} does not exist")
-                await self._database.execute(
-                    "INSERT INTO presence_schedules (child_id, "
+                result = await self._database.execute(
+                    "INSERT INTO presence_patterns (child_id, name, kind, "
                     "cycle_length_weeks, anchor_date, pattern) "
-                    "VALUES (?, ?, ?, ?) "
-                    "ON CONFLICT (child_id) DO UPDATE SET "
-                    "cycle_length_weeks = excluded.cycle_length_weeks, "
-                    "anchor_date = excluded.anchor_date, "
-                    "pattern = excluded.pattern",
-                    (child_id, cycle_length_weeks, anchor_date, pattern),
+                    "VALUES (?, ?, ?, ?, ?, ?)",
+                    (
+                        child_id,
+                        name,
+                        kind,
+                        cycle_length_weeks,
+                        anchor_date,
+                        pattern,
+                    ),
                 )
-                schedule = await self.get_by_child(child_id)
-        assert schedule is not None
-        return schedule
+                record = await self.get(result.lastrowid)
+        assert record is not None
+        return record
 
-    async def get_by_child(
-        self, child_id: int
-    ) -> PresenceScheduleRecord | None:
-        """Return the child's schedule, or None when the child has none.
+    async def list_by_child(self, child_id: int) -> list[PresencePatternRecord]:
+        """Return the child's patterns ordered by id; empty when none.
 
-        None is meaningful and UNAMBIGUOUS here: the child exists and
-        has no schedule row, i.e. the child is present every day
-        (Feature 05 guardrail).  An unknown child id raises ValueError
-        instead of returning None, because "nonexistent child" must
-        never be silently read as "present every day".
+        An empty list is meaningful and UNAMBIGUOUS here: the child
+        exists and has no pattern row, i.e. the child is present every
+        day (Feature 05 guardrail).  An unknown child id raises
+        ValueError instead of returning an empty list, because
+        "nonexistent child" must never be silently read as "present
+        every day".
         """
         child = await self._database.fetch_one(
             "SELECT 1 FROM children WHERE id = ?", (child_id,)
         )
         if child is None:
             raise ValueError(f"child {child_id} does not exist")
-        row = await self._database.fetch_one(
-            f"SELECT {_SCHEDULE_COLUMNS} FROM presence_schedules "
-            "WHERE child_id = ?",
+        rows = await self._database.fetch_all(
+            f"SELECT {_PATTERN_COLUMNS} FROM presence_patterns "
+            "WHERE child_id = ? ORDER BY id",
             (child_id,),
         )
-        return _schedule_from_row(row) if row is not None else None
+        return [_pattern_from_row(row) for row in rows]
 
-    async def delete(self, child_id: int) -> bool:
-        """Remove the child's schedule; True if a row was removed.
+    async def get(self, pattern_id: int) -> PresencePatternRecord | None:
+        """Return one pattern by id, or None when it does not exist."""
+        row = await self._database.fetch_one(
+            f"SELECT {_PATTERN_COLUMNS} FROM presence_patterns WHERE id = ?",
+            (pattern_id,),
+        )
+        return _pattern_from_row(row) if row is not None else None
 
-        After deletion the child is present every day (no row means
-        no restriction).  Deleting a schedule the child never had
-        returns False.
+    async def update(
+        self,
+        pattern_id: int,
+        name: str,
+        kind: str,
+        cycle_length_weeks: int,
+        anchor_date: str,
+        pattern: str,
+    ) -> PresencePatternRecord | None:
+        """Replace one pattern's fields; None when the id does not exist.
+
+        Every column but ``id`` and ``child_id`` is rewritten — a
+        pattern never moves to another child.  The schema CHECKs apply
+        exactly as on :meth:`create`.
+        """
+        _validate_date(anchor_date, "anchor_date")
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                result = await self._database.execute(
+                    "UPDATE presence_patterns SET name = ?, kind = ?, "
+                    "cycle_length_weeks = ?, anchor_date = ?, pattern = ? "
+                    "WHERE id = ?",
+                    (
+                        name,
+                        kind,
+                        cycle_length_weeks,
+                        anchor_date,
+                        pattern,
+                        pattern_id,
+                    ),
+                )
+                if result.rowcount == 0:
+                    return None
+                record = await self.get(pattern_id)
+        return record
+
+    async def delete(self, pattern_id: int) -> bool:
+        """Remove one pattern by id; True if a row was removed.
+
+        Deleting a child's last pattern leaves it present every day (no
+        row means no restriction).
         """
         result = await self._database.execute(
-            "DELETE FROM presence_schedules WHERE child_id = ?",
-            (child_id,),
+            "DELETE FROM presence_patterns WHERE id = ?",
+            (pattern_id,),
         )
         return result.rowcount > 0
 
@@ -270,6 +318,57 @@ class PresenceOverridesDao:
         )
         return [_override_from_row(row) for row in rows]
 
+    async def list_filtered(
+        self,
+        *,
+        child_id: int | None = None,
+        start: str | None = None,
+        end: str | None = None,
+    ) -> list[PresenceOverrideRecord]:
+        """Return the household's overrides, optionally narrowed.
+
+        Every filter is optional and they combine: ``child_id`` keeps
+        that child's overrides only (an unknown child raises ValueError
+        rather than reading as "no overrides"); ``start`` keeps
+        overrides ending on or after it and ``end`` keeps overrides
+        starting on or before it, so both together select the overrides
+        overlapping the closed range ``[start, end]`` (the
+        :meth:`list_by_child_and_range` boundary rule).  Dates are
+        strict YYYY-MM-DD and ``end`` must not precede ``start``.
+        Ordered stably by start date, then child id, then id.
+        """
+        if start is not None:
+            _validate_date(start, "start")
+        if end is not None:
+            _validate_date(end, "end")
+        if start is not None and end is not None and end < start:
+            raise ValueError(
+                f"end must be on or after start, got {end!r} < {start!r}"
+            )
+        clauses: list[str] = []
+        params: list[object] = []
+        if child_id is not None:
+            child = await self._database.fetch_one(
+                "SELECT 1 FROM children WHERE id = ?", (child_id,)
+            )
+            if child is None:
+                raise ValueError(f"child {child_id} does not exist")
+            clauses.append("child_id = ?")
+            params.append(child_id)
+        if start is not None:
+            clauses.append("end_date >= ?")
+            params.append(start)
+        if end is not None:
+            clauses.append("start_date <= ?")
+            params.append(end)
+        where = f" WHERE {' AND '.join(clauses)}" if clauses else ""
+        rows = await self._database.fetch_all(
+            f"SELECT {_OVERRIDE_COLUMNS} FROM presence_overrides{where} "
+            "ORDER BY start_date, child_id, id",
+            tuple(params),
+        )
+        return [_override_from_row(row) for row in rows]
+
     async def get(self, override_id: int) -> PresenceOverrideRecord | None:
         """Return one override by id, or None when it does not exist."""
         row = await self._database.fetch_one(
@@ -294,22 +393,23 @@ async def read_snapshot_unlocked(
     range_start: str,
     range_end: str,
 ) -> tuple[
-    dict[int, PresenceScheduleRecord],
+    dict[int, list[PresencePatternRecord]],
     dict[int, list[PresenceOverrideRecord]],
 ]:
-    """Read schedules and overrides for ``child_ids`` WITHOUT locking.
+    """Read patterns and overrides for ``child_ids`` WITHOUT locking.
 
     MUST be called inside the connection lock and an open transaction, so
-    the schedules and overrides returned here stay coherent with every
+    the patterns and overrides returned here stay coherent with every
     other table the caller reads inside that same transaction (the
     materialization walk's single input snapshot does exactly that).  The
     date range comes already validated by the caller.
 
-    Returns ``(schedules, overrides)``:
+    Returns ``(patterns, overrides)``:
 
-    - ``schedules`` maps ``child_id`` to its :class:`PresenceScheduleRecord`
-      for every child that HAS a schedule row.  A child absent from the
-      mapping has no schedule, i.e. is present every day (Feature 05).
+    - ``patterns`` maps ``child_id`` to its :class:`PresencePatternRecord`
+      list (ordered by id) for every child that HAS a pattern row.  A
+      child absent from the mapping has no pattern, i.e. is present
+      every day (Feature 05).
     - ``overrides`` maps ``child_id`` to that child's overrides overlapping
       ``[range_start, range_end]`` (inclusive boundaries), ordered by start
       date; a child with no matching override is absent from the mapping.
@@ -321,9 +421,9 @@ async def read_snapshot_unlocked(
     if not children:
         return {}, {}
     placeholders = ",".join("?" for _ in children)
-    schedule_rows = await database.fetch_all(
-        f"SELECT {_SCHEDULE_COLUMNS} FROM presence_schedules "
-        f"WHERE child_id IN ({placeholders})",
+    pattern_rows = await database.fetch_all(
+        f"SELECT {_PATTERN_COLUMNS} FROM presence_patterns "
+        f"WHERE child_id IN ({placeholders}) ORDER BY id",
         tuple(children),
     )
     override_rows = await database.fetch_all(
@@ -332,12 +432,12 @@ async def read_snapshot_unlocked(
         "AND start_date <= ? ORDER BY start_date",
         tuple(children) + (range_start, range_end),
     )
-    schedules = {
-        record.child_id: record
-        for record in map(_schedule_from_row, schedule_rows)
-    }
+    patterns: dict[int, list[PresencePatternRecord]] = {}
+    for row in pattern_rows:
+        record = _pattern_from_row(row)
+        patterns.setdefault(record.child_id, []).append(record)
     overrides: dict[int, list[PresenceOverrideRecord]] = {}
     for row in override_rows:
         record = _override_from_row(row)
         overrides.setdefault(record.child_id, []).append(record)
-    return schedules, overrides
+    return patterns, overrides

custom_components/nestquest/core/dao_rules.py

@@ -105,6 +105,19 @@ def _validate_window(window: str) -> None:
         )
 
 
+def _validate_skip_on_away(value: object) -> int:
+    """Return ``value`` as 0/1, raising ValueError for anything else.
+
+    The fresh-schema CHECK constraint enforces this in SQLite, but a
+    migrated database gained the column through ``ADD COLUMN`` without
+    it, so every DAO write path validates here instead.  Accepts a bool
+    or the ints 0/1; floats, strings and other ints are rejected.
+    """
+    if not isinstance(value, int) or value not in (0, 1):
+        raise ValueError(f"skip_on_away must be 0 or 1, got {value!r}")
+    return int(value)
+
+
 @dataclass(frozen=True)
 class ScheduleRuleRecord:
     """One row of ``schedule_rules``."""
@@ -152,6 +165,7 @@ class QuestDefinitionRecord:
     due_time: str | None
     is_active: bool
     created_at: str
+    skip_on_away: bool
 
 
 @dataclass(frozen=True)
@@ -187,7 +201,7 @@ _RULE_COLUMNS = (
 )
 _DEFINITION_COLUMNS = (
     "id, title, description, icon, schedule_rule_id, due_time, "
-    "is_active, created_at"
+    "is_active, created_at, skip_on_away"
 )
 _WINDOW_COLUMNS = "definition_id, window, due_time"
 
@@ -216,6 +230,7 @@ def _definition_from_row(row: tuple) -> QuestDefinitionRecord:
         due_time=row[5],
         is_active=bool(row[6]),
         created_at=row[7],
+        skip_on_away=bool(row[8]),
     )
 
 
@@ -632,6 +647,7 @@ class QuestDefinitionsDao:
         due_time: str | None = None,
         is_active: bool = True,
         assignee_child_ids: list[int] | None = None,
+        skip_on_away: bool = True,
     ) -> QuestDefinitionRecord:
         """Insert one definition and return the record as stored.
 
@@ -644,6 +660,7 @@ class QuestDefinitionsDao:
         empty list or None creates an unassigned definition, which
         callers may fill via :meth:`add_assignee`.
         """
+        skip_on_away_value = _validate_skip_on_away(skip_on_away)
         async with _connection_lock(self._database):
             async with self._database.transaction():
                 await self._validate_rule_exists(schedule_rule_id)
@@ -652,7 +669,8 @@ class QuestDefinitionsDao:
                 result = await self._database.execute(
                     "INSERT INTO quest_definitions (title, description, "
                     "icon, schedule_rule_id, due_time, is_active, "
-                    "created_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    "created_at, skip_on_away) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
                     (
                         title,
                         description,
@@ -661,6 +679,7 @@ class QuestDefinitionsDao:
                         due_time,
                         int(is_active),
                         created_at,
+                        skip_on_away_value,
                     ),
                 )
                 definition_id = result.lastrowid
@@ -684,6 +703,7 @@ class QuestDefinitionsDao:
         *,
         description: str | None = None,
         icon: str | None = None,
+        skip_on_away: bool = True,
     ) -> QuestDefinitionSnapshot:
         """Insert a rule, definition, assignees and windows atomically.
 
@@ -713,6 +733,7 @@ class QuestDefinitionsDao:
         _validate_date(schedule_rule.start_date, "start_date")
         if schedule_rule.end_date is not None:
             _validate_date(schedule_rule.end_date, "end_date")
+        skip_on_away_value = _validate_skip_on_away(skip_on_away)
         async with _connection_lock(self._database):
             async with self._database.transaction():
                 for child_id in assignee_child_ids:
@@ -721,8 +742,18 @@ class QuestDefinitionsDao:
                 result = await self._database.execute(
                     "INSERT INTO quest_definitions (title, description, "
                     "icon, schedule_rule_id, due_time, is_active, "
-                    "created_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
-                    (title, description, icon, rule_id, None, 1, created_at),
+                    "created_at, skip_on_away) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    (
+                        title,
+                        description,
+                        icon,
+                        rule_id,
+                        None,
+                        1,
+                        created_at,
+                        skip_on_away_value,
+                    ),
                 )
                 definition_id = result.lastrowid
                 for child_id in assignee_child_ids:
@@ -764,8 +795,10 @@ class QuestDefinitionsDao:
         icon: str | None | object = _UNSET,
         rule: ScheduleRuleStorage | object = _UNSET,
         windows: list[tuple[str, str | None]] | object = _UNSET,
+        skip_on_away: bool | object = _UNSET,
+        assignee_child_ids: list[int] | object = _UNSET,
     ) -> QuestDefinitionSnapshot:
-        """Edit a definition's metadata, rule and windows atomically.
+        """Edit a definition's metadata, rule, windows and assignees atomically.
 
         Mirrors :meth:`create_with_rule_and_windows`: everything runs
         inside ONE transaction under the connection lock, and the
@@ -774,9 +807,10 @@ class QuestDefinitionsDao:
         ``_UNSET`` meaning "leave this field alone"; ``None`` writes SQL
         NULL so optional metadata (description, icon) can be cleared.
 
-        - ``title``/``description``/``icon`` update the definition row
-          in place; the definition-level ``due_time`` column is never
-          written (per-window due times supersede it, D-008).
+        - ``title``/``description``/``icon``/``skip_on_away`` update the
+          definition row in place; the definition-level ``due_time``
+          column is never written (per-window due times supersede it,
+          D-008).
         - ``rule`` (a pre-validated :class:`ScheduleRuleStorage`)
           overwrites the referenced ``schedule_rules`` row in place: the
           definition keeps its ``schedule_rule_id``, so no new or
@@ -785,13 +819,19 @@ class QuestDefinitionsDao:
           are deleted and the given set re-inserted, so missing windows
           are added, changed due times updated and removed windows
           dropped.
+        - ``assignee_child_ids`` REPLACES the whole assignee set: every
+          id is validated as existing-and-active BEFORE any write (the
+          same check :meth:`add_assignee` applies), then links for
+          children no longer listed are removed and links for newly
+          listed children inserted; unchanged links are left alone.
 
-        Assignment is deliberately not settable here (multi-assignee is
-        managed by :meth:`add_assignee`/:meth:`remove_assignee`), and
-        activation is untouched.  Raises ValueError when the definition
-        does not exist.  Edits change future instances only: no
+        Activation is untouched.  Raises ValueError when the definition
+        does not exist or an assignee is rejected; either way the
+        transaction rolls back and nothing is written.  Edits change future instances only: no
         ``quest_instances`` or ``completion_events`` row is touched.
         """
+        if skip_on_away is not _UNSET:
+            skip_on_away = _validate_skip_on_away(skip_on_away)
         async with _connection_lock(self._database):
             async with self._database.transaction():
                 definition = await self.get(definition_id)
@@ -799,6 +839,9 @@ class QuestDefinitionsDao:
                     raise ValueError(
                         f"quest definition {definition_id} does not exist"
                     )
+                if assignee_child_ids is not _UNSET:
+                    for child_id in assignee_child_ids:
+                        await self._validate_assignable_child(child_id)
                 assignments: list[str] = []
                 parameters: list[object] = []
                 for column, value in (
@@ -809,6 +852,9 @@ class QuestDefinitionsDao:
                     if value is not _UNSET:
                         assignments.append(f"{column} = ?")
                         parameters.append(value)
+                if skip_on_away is not _UNSET:
+                    assignments.append("skip_on_away = ?")
+                    parameters.append(skip_on_away)
                 if assignments:
                     parameters.append(definition_id)
                     await self._database.execute(
@@ -844,6 +890,10 @@ class QuestDefinitionsDao:
                             "VALUES (?, ?, ?)",
                             (definition_id, window, due_time),
                         )
+                if assignee_child_ids is not _UNSET:
+                    await self._replace_assignees(
+                        definition_id, assignee_child_ids
+                    )
                 updated = await self.get(definition_id)
                 assignees = await self.list_assignees(definition_id)
                 window_records = await self.list_windows(definition_id)
@@ -859,6 +909,36 @@ class QuestDefinitionsDao:
             windows=window_records,
         )
 
+    async def _replace_assignees(
+        self, definition_id: int, child_ids: list[int]
+    ) -> None:
+        """Make the definition's assignee links exactly ``child_ids``.
+
+        Removes the links for children not in ``child_ids`` and inserts
+        the missing ones.  MUST be called inside the connection lock and
+        an open transaction, after the ids were validated as assignable.
+        """
+        rows = await self._database.fetch_all(
+            "SELECT child_id FROM quest_definition_assignees "
+            "WHERE definition_id = ?",
+            (definition_id,),
+        )
+        current = {row[0] for row in rows}
+        wanted = set(child_ids)
+        for child_id in sorted(current - wanted):
+            await self._database.execute(
+                "DELETE FROM quest_definition_assignees "
+                "WHERE definition_id = ? AND child_id = ?",
+                (definition_id, child_id),
+            )
+        for child_id in child_ids:
+            if child_id not in current:
+                await self._database.execute(
+                    "INSERT INTO quest_definition_assignees "
+                    "(definition_id, child_id) VALUES (?, ?)",
+                    (definition_id, child_id),
+                )
+
     async def _validate_rule_exists(self, schedule_rule_id: int) -> None:
         """Raise ValueError unless the rule exists.
 
@@ -907,6 +987,13 @@ class QuestDefinitionsDao:
         )
         return [_definition_from_row(row) for row in rows]
 
+    async def list_all(self) -> list[QuestDefinitionRecord]:
+        """Return every definition, active AND inactive, oldest first."""
+        rows = await self._database.fetch_all(
+            f"SELECT {_DEFINITION_COLUMNS} FROM quest_definitions ORDER BY id"
+        )
+        return [_definition_from_row(row) for row in rows]
+
     async def _snapshots_for(
         self, definitions: list[QuestDefinitionRecord]
     ) -> list[QuestDefinitionSnapshot]:
@@ -951,6 +1038,18 @@ class QuestDefinitionsDao:
                 definitions = await self.list_active()
                 return await self._snapshots_for(definitions)
 
+    async def list_snapshots_all(self) -> list[QuestDefinitionSnapshot]:
+        """Return every definition (active AND inactive) with its rule,
+        assignees and windows, all read inside one locked transaction.
+
+        Mirrors :meth:`list_snapshots_active` over :meth:`list_all`
+        (oldest first), with the same coherence guarantee.
+        """
+        async with _connection_lock(self._database):
+            async with self._database.transaction():
+                definitions = await self.list_all()
+                return await self._snapshots_for(definitions)
+
     async def read_snapshots_active(self) -> list[QuestDefinitionSnapshot]:
         """Return every active definition's snapshot WITHOUT locking.
 
@@ -990,13 +1089,16 @@ class QuestDefinitionsDao:
         description: str | None | object = _UNSET,
         icon: str | None | object = _UNSET,
         due_time: str | None | object = _UNSET,
+        skip_on_away: bool | None = None,
     ) -> int:
         """Update the given fields; returns rows updated (0 if absent).
 
         Arguments default to the module sentinel ``_UNSET`` meaning
         "leave this column alone"; passing ``None`` explicitly writes
         SQL NULL, so callers can remove optional metadata
-        (description, icon, due_time).  Assignment and activation are
+        (description, icon, due_time).  ``skip_on_away`` is NOT NULL,
+        so its ``None`` default leaves it unchanged; a supplied value
+        must be 0/1 (a bool).  Assignment and activation are
         deliberately NOT settable here: they have their own explicit
         operations (:meth:`add_assignee`, :meth:`remove_assignee`,
         :meth:`set_active`) so they stay separately loggable and
@@ -1013,6 +1115,9 @@ class QuestDefinitionsDao:
             if value is not _UNSET:
                 assignments.append(f"{column} = ?")
                 parameters.append(value)
+        if skip_on_away is not None:
+            assignments.append("skip_on_away = ?")
+            parameters.append(_validate_skip_on_away(skip_on_away))
         if not assignments:
             return 0
         parameters.append(definition_id)
@@ -1214,16 +1319,16 @@ async def load_materialization_input(
 ):
     """Read every materialization input in ONE locked transaction.
 
-    Returns ``(snapshots, schedules, overrides)``:
+    Returns ``(snapshots, patterns, overrides)``:
 
     - ``snapshots``: every active definition with its rule, assignees and
       windows (the :class:`QuestDefinitionSnapshot` shape).
-    - ``schedules`` / ``overrides``: the presence schedules and
+    - ``patterns`` / ``overrides``: the presence patterns and
       range-scoped overrides of every assignee child, in
       :mod:`.dao_presence`'s record shapes.
 
     The whole read — definitions, rules, assignees, windows, and the
-    assignees' presence schedules and overrides — runs inside a single
+    assignees' presence patterns and overrides — runs inside a single
     BEGIN..COMMIT span under the connection lock, so a concurrent edit
     (definition, assignment, window, or presence) cannot interleave
     between the parts and the walk never sees a mixed-time view.  Each
@@ -1244,7 +1349,7 @@ async def load_materialization_input(
             )
             from . import dao_presence  # lazy: dao_presence imports us
 
-            schedules, overrides = await dao_presence.read_snapshot_unlocked(
+            patterns, overrides = await dao_presence.read_snapshot_unlocked(
                 database, child_ids, range_start, range_end
             )
-    return snapshots, schedules, overrides
+    return snapshots, patterns, overrides

custom_components/nestquest/core/icons.py

@@ -0,0 +1,119 @@
+"""Namespaced quest-definition icon keys.
+
+A definition's ``icon`` is stored as ``<namespace>:<name>`` where the
+namespace is one of :data:`ICON_NAMESPACES`:
+
+- ``lucide:<name>`` / ``fa:<name>`` — ``<name>`` is a lowercase kebab
+  name (ASCII ``[a-z0-9-]``, not starting or ending with ``-``).
+- ``emoji:<payload>`` — a short emoji string of at most
+  :data:`EMOJI_MAX_CODE_POINTS` code points, with no whitespace (JS
+  ``\\s``, so including U+FEFF), no control characters and none of
+  ``<``, ``>``, ``&``.
+
+Rows written before namespacing hold a bare Lucide name (``dog``).
+:func:`validate_icon` (writes) normalizes such a legacy value to
+``lucide:<name>``; :func:`normalize_icon_for_read` (reads) does the same
+leniently so legacy rows render without a data migration.
+
+Nothing here imports :mod:`homeassistant`.
+"""
+from __future__ import annotations
+
+import re
+import unicodedata
+
+ICON_NAMESPACE_LUCIDE = "lucide"
+ICON_NAMESPACE_FA = "fa"
+ICON_NAMESPACE_EMOJI = "emoji"
+ICON_NAMESPACES = frozenset(
+    {ICON_NAMESPACE_LUCIDE, ICON_NAMESPACE_FA, ICON_NAMESPACE_EMOJI}
+)
+
+#: Upper bound on an emoji payload's length in code points — enough for
+#: ZWJ sequences such as a family emoji, too short for arbitrary text.
+EMOJI_MAX_CODE_POINTS = 8
+
+_KEBAB_NAME = re.compile(r"[a-z0-9](?:[a-z0-9-]*[a-z0-9])?")
+# U+FEFF (BOM / zero-width no-break space) is neither str.isspace() nor
+# ``Cc`` in Python, but JS ``\s`` matches it, so it is listed here to keep
+# this rule identical to the frontends' isEmojiPayload (/[\s<>&]|\p{Cc}/u).
+# Other format characters, notably the ZWJ U+200D that emoji sequences
+# need, stay valid in both runtimes.
+_EMOJI_FORBIDDEN = frozenset("<>&\ufeff")
+
+
+def _is_kebab_name(value: str) -> bool:
+    return _KEBAB_NAME.fullmatch(value) is not None
+
+
+def _is_valid_emoji_payload(value: str) -> bool:
+    if not value or len(value) > EMOJI_MAX_CODE_POINTS:
+        return False
+    return not any(
+        char.isspace()
+        or char in _EMOJI_FORBIDDEN
+        or unicodedata.category(char) == "Cc"
+        for char in value
+    )
+
+
+def validate_icon(value: object) -> str | None:
+    """Return the canonical namespaced icon key, or raise naming ``icon``.
+
+    ``None`` or an empty/whitespace-only string returns ``None`` (the
+    icon is cleared).  Otherwise the raw value is validated untrimmed, so
+    edge whitespace or control characters are rejected rather than
+    silently stripped.  A value with no ``:`` is a legacy bare Lucide
+    name and is stored as ``lucide:<value>``.  An unknown namespace, an
+    empty or malformed name, or an invalid emoji payload raises
+    ValueError.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"icon must be a string, got {value!r}")
+    if not value.strip():
+        return None
+
+    namespace, separator, name = value.partition(":")
+    if not separator:
+        if not _is_kebab_name(value):
+            raise ValueError(
+                f"icon must be a lowercase kebab name, got {value!r}"
+            )
+        return f"{ICON_NAMESPACE_LUCIDE}:{value}"
+
+    if namespace not in ICON_NAMESPACES:
+        raise ValueError(
+            f"icon has an unknown namespace {namespace!r}; expected one of "
+            f"{sorted(ICON_NAMESPACES)}"
+        )
+    if namespace == ICON_NAMESPACE_EMOJI:
+        if not _is_valid_emoji_payload(name):
+            raise ValueError(
+                f"icon emoji must be 1-{EMOJI_MAX_CODE_POINTS} code points "
+                f"with no whitespace, control characters or markup, "
+                f"got {value!r}"
+            )
+    elif not _is_kebab_name(name):
+        raise ValueError(
+            f"icon {namespace} name must be a lowercase kebab name, "
+            f"got {value!r}"
+        )
+    return value
+
+
+def normalize_icon_for_read(value: str | None) -> str | None:
+    """Return a stored icon in namespaced form for output.
+
+    Lenient: ``None``/empty returns ``None``, a recognised namespace is
+    returned unchanged, and anything else becomes ``lucide:<value>`` so
+    legacy rows render (an unknown name falls through to the frontend's
+    fallback icon rather than erroring).
+    """
+    if not value or not value.strip():
+        return None
+    namespace, separator, _ = value.partition(":")
+    if separator and namespace in ICON_NAMESPACES:
+        return value
+    return f"{ICON_NAMESPACE_LUCIDE}:{value}"

custom_components/nestquest/core/materialize.py

@@ -9,7 +9,7 @@ task and lives elsewhere.
 The walk is deterministic and idempotent:
 
 - All inputs — the active definitions with their rules, assignees and
-  windows, AND the assignee children's presence schedules and scoped
+  windows, AND the assignee children's presence patterns and scoped
   overrides — are read inside ONE locked transaction (see
   :func:`~.dao_rules.load_materialization_input`), so the walk sees a
   single coherent snapshot rather than a definition state from one
@@ -18,7 +18,8 @@ The walk is deterministic and idempotent:
   :class:`~.presence.PresenceEngine` from that same coherent read.
 - For each date in the range, each definition whose decoded rule
   :func:`~.recurrence.occurs_on` on that date, each assignee who is
-  ``is_present`` on that date and each declared window, one instance is
+  ``is_present`` on that date (or every assignee, when the definition's
+  ``skip_on_away`` is off) and each declared window, one instance is
   written through :class:`~.dao_instances.QuestInstancesDao.upsert_if_valid`
   with a ``generated_at`` stamp shared by the whole batch (one coherent
   time per run).
@@ -50,12 +51,12 @@ never the past — and re-run the walk over the rolling horizon
 HOOK (Feature 09 presence services): the presence business layer that
 lands in Feature 09 MUST call :func:`regenerate_for_child` after EVERY
 presence-state write so a child's future instances track its presence:
-``set_presence_pattern`` (including clearing/setting an empty pattern),
-deleting/clearing the presence schedule
-(:meth:`~.dao_presence.PresenceSchedulesDao.delete`),
+creating, updating and deleting a presence pattern
+(:mod:`.presence_management`'s ``create_presence_pattern`` /
+``update_presence_pattern`` / ``delete_presence_pattern``),
 ``create_presence_override``, and ``delete_presence_override``.  A
-schedule delete changes presence state too (the child becomes
-always-present), so it must regenerate just like the others.  This hook
+pattern delete changes presence state too, so it must regenerate just
+like the others.  This hook
 is documented, not yet wired: no presence business layer exists yet, and
 the presence DAO (``dao_presence.py``) must stay free of business rules
 — never call :func:`regenerate_for_child` from inside the DAO layer.
@@ -63,9 +64,14 @@ the presence DAO (``dao_presence.py``) must stay free of business rules
 from __future__ import annotations
 
 import datetime
+from typing import NamedTuple
 
 from .const import DEFAULT_HORIZON_DAYS
-from .dao_instances import QuestInstancesDao, _resolve_today
+from .dao_instances import (
+    CompletionEventsDao,
+    QuestInstancesDao,
+    _resolve_today,
+)
 from .dao_rules import (
     _validate_date,
     load_materialization_input,
@@ -73,7 +79,7 @@ from .dao_rules import (
     schedule_rule_storage_from_record,
 )
 from .db import NestQuestDatabase
-from .presence import PresenceEngine, PresenceOverride, PresenceSchedule
+from .presence import PresenceEngine, PresenceOverride, PresencePattern
 from .recurrence import ScheduleRule, occurs_on
 
 
@@ -123,15 +129,29 @@ def _decode_rule(snapshot) -> ScheduleRule:
 
 
 def _build_engine(
-    schedules_records,
+    patterns_records,
     overrides_records,
+    *,
+    extra_overrides: tuple[PresenceOverride, ...] = (),
 ) -> PresenceEngine:
-    """Convert raw presence records into an immutable PresenceEngine."""
-    schedules: dict[int, PresenceSchedule] = {}
-    for child_id, record in schedules_records.items():
-        schedules[child_id] = PresenceSchedule.decode(
-            child_id, record.anchor_date, record.pattern
-        )
+    """Convert raw presence records into an immutable PresenceEngine.
+
+    ``extra_overrides`` layers already-validated, NOT-yet-stored
+    overrides on top of the stored ones — the consequence preview's
+    proposed override (:func:`count_removed_by_override`).
+    """
+    patterns: dict[int, list[PresencePattern]] = {}
+    for child_id, records in patterns_records.items():
+        patterns[child_id] = [
+            PresencePattern.decode(
+                record.child_id,
+                record.name,
+                record.kind,
+                record.anchor_date,
+                record.pattern,
+            )
+            for record in records
+        ]
     overrides: dict[int, list[PresenceOverride]] = {}
     for child_id, records in overrides_records.items():
         overrides[child_id] = [
@@ -144,7 +164,73 @@ def _build_engine(
             )
             for record in records
         ]
-    return PresenceEngine(schedules, overrides)
+    for override in extra_overrides:
+        overrides.setdefault(override.child_id, []).append(override)
+    return PresenceEngine(patterns, overrides)
+
+
+class GeneratedTuple(NamedTuple):
+    """One instance the walk WOULD write: its upsert key plus due time."""
+
+    definition_id: int
+    child_id: int
+    due_date: str
+    window: str
+    due_time: str | None
+
+
+def _generation_preview(
+    snapshots,
+    engine: PresenceEngine,
+    start: datetime.date,
+    end: datetime.date,
+    *,
+    child_filter: set[int] | None = None,
+) -> list[GeneratedTuple]:
+    """Return the tuples the walk would write over ``[start, end]``.
+
+    The pure, read-only half of :func:`materialize`: for each date, each
+    definition whose decoded rule :func:`~.recurrence.occurs_on` it,
+    each assignee in ``child_filter`` (every assignee when None) who is
+    ``is_present`` on it — or every assignee when the definition's
+    ``skip_on_away`` is off — and each declared window, one tuple, in
+    the walk's write order.  :func:`materialize` writes exactly these
+    tuples and :func:`count_removed_by_override` compares two of these
+    previews, so the write and the consequence preview can never
+    diverge.  No database access.
+    """
+    definitions = [
+        (snapshot.definition.id, _decode_rule(snapshot),
+         snapshot.assignees, snapshot.windows,
+         snapshot.definition.skip_on_away)
+        for snapshot in snapshots
+    ]
+    generated: list[GeneratedTuple] = []
+    cursor = start
+    while cursor <= end:
+        iso = cursor.isoformat()
+        for (
+            definition_id, rule, assignees, windows, skip_on_away
+        ) in definitions:
+            if not occurs_on(rule, cursor):
+                continue
+            for child in assignees:
+                if child_filter is not None and child.id not in child_filter:
+                    continue
+                if skip_on_away and not engine.is_present(child.id, cursor):
+                    continue
+                for window in windows:
+                    generated.append(
+                        GeneratedTuple(
+                            definition_id,
+                            child.id,
+                            iso,
+                            window.window,
+                            window.due_time,
+                        )
+                    )
+        cursor += datetime.timedelta(days=1)
+    return generated
 
 
 async def materialize(
@@ -200,18 +286,12 @@ async def materialize(
             f"{end_date!r} < {start_date!r}"
         )
 
-    snapshots, schedules_records, overrides_records = await (
+    snapshots, patterns_records, overrides_records = await (
         load_materialization_input(database, start_date, end_date)
     )
-    engine = _build_engine(schedules_records, overrides_records)
+    engine = _build_engine(patterns_records, overrides_records)
     child_filter = None if child_ids is None else set(child_ids)
 
-    definitions = [
-        (snapshot.definition.id, _decode_rule(snapshot),
-         snapshot.assignees, snapshot.windows)
-        for snapshot in snapshots
-    ]
-
     generated_at = _now_stamp()
     instances = QuestInstancesDao(database)
 
@@ -226,30 +306,20 @@ async def materialize(
     start = max(start, today_date)
 
     count = 0
-    cursor = start
-    while cursor <= end:
-        iso = cursor.isoformat()
-        for definition_id, rule, assignees, windows in definitions:
-            if not occurs_on(rule, cursor):
-                continue
-            for child in assignees:
-                if child_filter is not None and child.id not in child_filter:
-                    continue
-                if not engine.is_present(child.id, cursor):
-                    continue
-                for window in windows:
-                    written = await instances.upsert_if_valid(
-                        definition_id,
-                        child.id,
-                        iso,
-                        generated_at,
-                        window=window.window,
-                        due_time=window.due_time,
-                        today=today,
-                    )
-                    if written is not None:
-                        count += 1
-        cursor += datetime.timedelta(days=1)
+    for generated in _generation_preview(
+        snapshots, engine, start, end, child_filter=child_filter
+    ):
+        written = await instances.upsert_if_valid(
+            generated.definition_id,
+            generated.child_id,
+            generated.due_date,
+            generated_at,
+            window=generated.window,
+            due_time=generated.due_time,
+            today=today,
+        )
+        if written is not None:
+            count += 1
     return count
 
 
@@ -303,12 +373,11 @@ async def regenerate_for_definition(
 # child-presence counterpart to ``regenerate_for_definition``.  The
 # presence business layer that lands in Feature 09 MUST call
 # ``regenerate_for_child`` after EVERY presence-state write, so future
-# instances track a child's changed presence: set_presence_pattern
-# (including clearing/setting an empty pattern), deleting/clearing the
-# presence schedule (PresenceSchedulesDao.delete),
-# create_presence_override, and delete_presence_override.  A schedule
-# delete changes presence state too (the child becomes always-present),
-# so it must regenerate just like the others.  It is deliberately NOT
+# instances track a child's changed presence: create_presence_pattern,
+# update_presence_pattern, delete_presence_pattern,
+# create_presence_override, and delete_presence_override.  A pattern
+# delete changes presence state too, so it must regenerate just like
+# the others.  It is deliberately NOT
 # wired into ``dao_presence.py``: the DAO layer stays pure storage (no
 # business rules), and no presence business layer exists yet to host the
 # call — see the module docstring note above.
@@ -322,9 +391,8 @@ async def regenerate_for_child(
     """Regenerate a child's future instances after a presence change.
 
     The Feature 09 presence services call this after every
-    presence-state write — set_presence_pattern (including clearing or
-    setting an empty pattern), deleting/clearing the presence schedule
-    (:meth:`~.dao_presence.PresenceSchedulesDao.delete`),
+    presence-state write — create_presence_pattern,
+    update_presence_pattern, delete_presence_pattern,
     create_presence_override, and delete_presence_override — so a
     child's future instances track its new presence: the child's open
     instances at or after today are deleted across ALL its definitions
@@ -375,3 +443,93 @@ async def regenerate_for_child(
     return await materialize(
         database, start.isoformat(), end_date, child_ids=[child_id], today=today
     )
+
+
+async def count_removed_by_override(
+    database: NestQuestDatabase,
+    override: PresenceOverride,
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> int:
+    """Count the upcoming instances saving ``override`` would remove.
+
+    Read-only: nothing is written.  The window is the part of the
+    override's range inside the rolling horizon ``[today, today +
+    horizon_days]`` that :func:`regenerate_for_child` rebuilds after the
+    override is saved (outside the range the two presence answers agree,
+    so nothing there can change).  The materialization input is read
+    ONCE (:func:`~.dao_rules.load_materialization_input`) and
+    :func:`_generation_preview` runs twice over it for the override's
+    child — with the stored presence, and with ``override`` layered on
+    top (:func:`_build_engine`'s ``extra_overrides``).  The count is the
+    tuples the first preview generates and the second does not, MINUS
+    every (definition, date, window) whose stored instance already has a
+    completion event (D-005: regeneration never deletes those).  A
+    definition with ``skip_on_away`` off generates regardless of
+    presence, so it contributes nothing; a present override only ever
+    ADDS tuples, so it counts 0.
+
+    An override overlapping a stored one (which the create path refuses)
+    resolves through the engine's latest-start-wins rule.  ``today`` and
+    ``horizon_days`` resolve exactly as :func:`regenerate_for_child`
+    resolves them; a malformed horizon raises ValueError.
+    """
+    horizon = _resolve_horizon_days(horizon_days)
+    today_date = _resolve_today(today)
+    start = max(today_date, override.start_date)
+    end = min(
+        today_date + datetime.timedelta(days=horizon), override.end_date
+    )
+    if end < start:
+        return 0
+    start_date, end_date = start.isoformat(), end.isoformat()
+    child_id = override.child_id
+
+    snapshots, patterns_records, overrides_records = await (
+        load_materialization_input(database, start_date, end_date)
+    )
+    current = _generation_preview(
+        snapshots,
+        _build_engine(patterns_records, overrides_records),
+        start,
+        end,
+        child_filter={child_id},
+    )
+    proposed = set(
+        _generation_preview(
+            snapshots,
+            _build_engine(
+                patterns_records,
+                overrides_records,
+                extra_overrides=(override,),
+            ),
+            start,
+            end,
+            child_filter={child_id},
+        )
+    )
+    removed = [generated for generated in current if generated not in proposed]
+    if not removed:
+        return 0
+
+    stored = await QuestInstancesDao(database).list_by_date_range(
+        child_id, start_date, end_date
+    )
+    touched = {
+        event.instance_id
+        for event in await CompletionEventsDao(
+            database
+        ).list_by_child_and_date_range(child_id, start_date, end_date)
+    }
+    completed = {
+        (instance.definition_id, instance.due_date, instance.window)
+        for instance in stored
+        if instance.id in touched
+    }
+    return sum(
+        1
+        for generated in removed
+        if (generated.definition_id, generated.due_date, generated.window)
+        not in completed
+    )

custom_components/nestquest/core/migrations.py

@@ -30,8 +30,13 @@ widened (definition_id, child_id, due_date, window) key, and migration
 6 rebuilds ``completion_events`` with the D-008 ``actor_child_id``
 column.  Migration 7 adds the generic ``nestquest_meta_state``
 key/value table for integration-owned bookkeeping (Feature 11's
-missed-sweep watermark).  Each callable migration runs inside its own
-transaction
+missed-sweep watermark).  Migration 8 adds the ``skip_on_away``
+column to ``quest_definitions`` (Feature 22), defaulting to 1.
+Migration 9 replaces the one-per-child ``presence_schedules`` table
+with ``presence_patterns`` (zero or more patterns per child), copying
+every schedule across as a ``home`` pattern and dropping the old table
+— see :data:`MIGRATION_9_PRESENCE_PATTERNS` for the rollback note.  Each
+callable migration runs inside its own transaction
 together with its version stamp, so a crash mid-step rolls the
 statements and the stamp back together.
 
@@ -84,6 +89,7 @@ from .schema import (
     SCHEMA_V1_QUEST_DEFINITION_ASSIGNEES_DDL,
     SCHEMA_V1_QUEST_DEFINITION_WINDOWS_DDL,
     SCHEMA_V7_META_STATE_DDL,
+    SCHEMA_V9_PRESENCE_PATTERNS_DDL,
 )
 
 LOGGER = logging.getLogger(__name__)
@@ -115,9 +121,76 @@ VERSION_TABLE_DDL = f"""
     )
 """
 
+#: The retired ``presence_schedules`` DDL (one schedule per child),
+#: frozen here verbatim: migration 1 shipped creating this table and
+#: applied migrations are never edited, so a fresh file still walks
+#: through it and migration 9 retires it.  :mod:`.schema` no longer
+#: declares it.
+_MIGRATION_1_PRESENCE_SCHEDULES_DDL = """
+    CREATE TABLE IF NOT EXISTS presence_schedules (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        child_id INTEGER NOT NULL UNIQUE REFERENCES children(id),
+        cycle_length_weeks INTEGER NOT NULL CHECK (typeof(cycle_length_weeks) = 'integer' AND cycle_length_weeks >= 1 AND cycle_length_weeks <= 4),
+        anchor_date TEXT NOT NULL,
+        pattern TEXT NOT NULL CHECK (
+            NOT pattern GLOB '*[^0-6,|]*'
+            AND NOT pattern GLOB '*[0-6][0-6]*'
+            AND NOT pattern GLOB '*,,*'
+            AND NOT pattern GLOB '*,|*'
+            AND NOT pattern GLOB '*|,*'
+            AND NOT pattern GLOB ',*'
+            AND NOT pattern GLOB '*,'
+            AND NOT pattern GLOB '*[0-6],[0-6],[0-6],[0-6],[0-6],[0-6],[0-6],[0-6]*'
+            AND (LENGTH(pattern) - LENGTH(REPLACE(pattern, '|', '')) + 1) = cycle_length_weeks
+        )
+    )
+    """
+
 #: One-based index into :data:`MIGRATIONS`: entry ``n`` upgrades
-#: version ``n-1`` to version ``n``.
-MIGRATION_1_V1_DDL: list[str] = list(SCHEMA_V1_STATEMENTS)
+#: version ``n-1`` to version ``n``.  Migration 1 is the v1 DDL as it
+#: shipped: the current tables, except that it still creates the
+#: retired ``presence_schedules`` table in place of
+#: ``presence_patterns`` (which migration 9 creates).
+MIGRATION_1_V1_DDL: list[str] = [
+    _MIGRATION_1_PRESENCE_SCHEDULES_DDL
+    if sql in SCHEMA_V9_PRESENCE_PATTERNS_DDL
+    else sql
+    for sql in SCHEMA_V1_STATEMENTS
+]
+
+#: The label every migrated ``presence_schedules`` row carries as a
+#: ``presence_patterns`` row.
+MIGRATED_PRESENCE_PATTERN_NAME = "Home schedule"
+
+#: Migration 9 (schema 9): multiple presence patterns per child.
+#: Creates ``presence_patterns``, copies EVERY ``presence_schedules``
+#: row into it as a ``home`` pattern named
+#: :data:`MIGRATED_PRESENCE_PATTERN_NAME` — ``cycle_length_weeks``,
+#: ``anchor_date`` and ``pattern`` verbatim, the row id kept — and
+#: drops ``presence_schedules``.  A ``home`` pattern with no other
+#: pattern beside it answers exactly as the old schedule did (the
+#: engine treats a date no home pattern covers as a day away), so every
+#: child's presence is unchanged.  A plain statement list: the runner
+#: applies it and the version stamp in ONE transaction, so a failure
+#: rolls the copy and the drop back together.  Dropping a table nothing
+#: references needs no ``foreign_keys = OFF`` bracket.
+#:
+#: Rollback: the drop is one-way.  A 0.7.1 build refuses a version-9
+#: file ("newer than this integration understands") and could not read
+#: ``presence_patterns`` anyway, so take a copy of the SQLite file (or
+#: note the Litestream generation) BEFORE the first start of the release
+#: carrying migration 9; rolling back to 0.7.1 means restoring that
+#: pre-migration copy, which still holds the single-schedule rows.
+#: Pattern edits made after the upgrade are not in that copy.
+MIGRATION_9_PRESENCE_PATTERNS: list[str] = [
+    *SCHEMA_V9_PRESENCE_PATTERNS_DDL,
+    "INSERT INTO presence_patterns (id, child_id, name, kind, "
+    "cycle_length_weeks, anchor_date, pattern) "
+    f"SELECT id, child_id, '{MIGRATED_PRESENCE_PATTERN_NAME}', 'home', "
+    "cycle_length_weeks, anchor_date, pattern "
+    "FROM presence_schedules ORDER BY id",
+    "DROP TABLE presence_schedules",
+]
 
 #: The assignees table DDL, shared with migration 1 via the schema
 #: module so a rebuilt and a freshly created table cannot drift.
@@ -400,6 +473,28 @@ async def _add_actor_child_id(
         await database.execute("PRAGMA foreign_keys = ON")
 
 
+async def _add_skip_on_away(
+    database: NestQuestDatabase, target_version: int
+) -> None:
+    """Add the ``skip_on_away`` column to ``quest_definitions``.
+
+    Strictly additive: ``ALTER TABLE ... ADD COLUMN`` with a NOT NULL
+    DEFAULT 1, so existing rows read as 1 (skip absent dates — the
+    behaviour before the flag existed).  Fresh databases already carry
+    the column from the canonical DDL, so the ALTER is guarded and the
+    step only stamps there.
+    """
+    async with database.transaction():
+        if not await _table_has_column(
+            database, "quest_definitions", "skip_on_away"
+        ):
+            await database.execute(
+                "ALTER TABLE quest_definitions ADD COLUMN "
+                "skip_on_away INTEGER NOT NULL DEFAULT 1"
+            )
+        await stamp_schema_version(database, target_version)
+
+
 #: The ordered migration list.  Append-only: never edit an applied
 #: entry, add the next one instead.  (Migration 1's content was
 #: rewritten pre-release per D-007 — no version 1 database shipped.)
@@ -423,6 +518,13 @@ MIGRATIONS: Sequence[MigrationStep] = [
     # fresh databases (which already made it in migration 1) and
     # pre-v7 databases.  Strictly additive; no existing table changes.
     list(SCHEMA_V7_META_STATE_DDL),
+    # Migration 8 (Feature 22): the skip_on_away flag on
+    # quest_definitions — an additive column defaulting to 1, so every
+    # pre-existing definition keeps today's skip-when-absent behaviour.
+    _add_skip_on_away,
+    # Migration 9 (schema 9): presence_schedules -> presence_patterns,
+    # each schedule copied across as a 'home' pattern.
+    MIGRATION_9_PRESENCE_PATTERNS,
 ]
 
 

custom_components/nestquest/core/presence.py

@@ -5,21 +5,24 @@ timezone logic — it operates on plain calendar dates only (feature
 guardrail).  The later engine (cycle position, ``is_present``,
 overrides, previews) builds directly on this model.
 
-A :class:`PresenceSchedule` answers "on which weekdays of which cycle
-week is this child at this house?" for an N-week repeating custody
-pattern.  Two of the household's three children follow a two-week
-rotation; a child with NO schedule row is present every day (that
-default lives in the engine, not here).
+A :class:`PresencePattern` answers "on which weekdays of which cycle
+week does this rule apply to this child?" for an N-week repeating
+custody rule, and its ``kind`` says what the rule claims on those
+days: ``home`` (the child is at this house) or ``away``.  A child
+carries ZERO OR MORE patterns (schema 9), e.g. "away every Thursday
+and Friday" plus "away every other weekend"; a child with NO pattern
+is present every day (that default, and how patterns combine, lives in
+the engine, not here).
 
 Pattern encoding: the model's canonical serialization is the SAME
 pipe-separated CSV the database stores (see schema.py's
-``presence_schedules.pattern``): segment ``i`` (week index ``i``) is a
-comma-separated list of present weekdays, 0 = Monday .. 6 = Sunday,
-e.g. ``'0,2,4|1,3'`` = Mon/Wed/Fri in week 0, Tue/Thu in week 1.  An
-empty segment means absent every day of that week.  Encoding sorts
-each segment's weekdays and uses the exact segment order, so
-``decode(encode(schedule))`` round-trips losslessly and two schedules
-with equal patterns produce equal strings.
+``presence_patterns.pattern``): segment ``i`` (week index ``i``) is a
+comma-separated list of the weekdays the pattern covers, 0 = Monday ..
+6 = Sunday, e.g. ``'0,2,4|1,3'`` = Mon/Wed/Fri in week 0, Tue/Thu in
+week 1.  An empty segment means the pattern covers no day of that
+week.  Encoding sorts each segment's weekdays and uses the exact
+segment order, so ``decode(encode(pattern))`` round-trips losslessly
+and two patterns with equal weekday sets produce equal strings.
 
 Anchor-date policy: ``anchor_date`` pins the cycle.  Cycle position is
 computed from anchor-date arithmetic ONLY — never ISO week numbers or
@@ -28,7 +31,9 @@ week parity (D-004): 53-week years silently invert parity on January
 that the anchor is a strict calendar date.
 
 Validation policy: construction is total — every reject happens in
-``__init__`` so no invalid schedule can ever exist:
+``__init__`` so no invalid pattern can ever exist:
+- ``name`` must be a string that is not blank; it is stored trimmed.
+- ``kind`` must be ``'home'`` or ``'away'``.
 - ``cycle_length_weeks`` must be an integer 1..4.  The 4 cap matches
   the database CHECK (schema.py) and keeps anchor arithmetic and the
   encoded pattern human-readable; revisit both together if a longer
@@ -49,6 +54,10 @@ from types import MappingProxyType
 #: the pattern human-readable and the anchor arithmetic small).
 MAX_CYCLE_LENGTH_WEEKS = 4
 
+#: The pattern kinds the schema's CHECK allows: what a covering
+#: pattern claims about the child on that date.
+PATTERN_KINDS = ("home", "away")
+
 _DATE_FORMAT = "%Y-%m-%d"
 
 
@@ -126,6 +135,25 @@ def _validate_weekday_set(week: int, weekdays: object) -> frozenset[int]:
     return frozenset(members)
 
 
+def _validate_name(value: object) -> str:
+    """Reject non-string and blank pattern names; return it trimmed."""
+    if not isinstance(value, str):
+        raise ValueError(f"name must be a string, got {value!r}")
+    trimmed = value.strip()
+    if not trimmed:
+        raise ValueError("name must not be empty")
+    return trimmed
+
+
+def _validate_kind(value: object) -> str:
+    """Reject any kind other than the schema's ``home`` / ``away``."""
+    if not isinstance(value, str) or value not in PATTERN_KINDS:
+        raise ValueError(
+            f"kind must be one of {', '.join(PATTERN_KINDS)}, got {value!r}"
+        )
+    return value
+
+
 def _validate_cycle_length(value: object) -> int:
     """Reject non-int and out-of-range cycle lengths (bools included)."""
     if isinstance(value, bool) or not isinstance(value, int):
@@ -148,17 +176,19 @@ def _validate_child_id(value: object) -> int:
 
 
 @dataclass(frozen=True, init=False)
-class PresenceSchedule:
-    """One child's N-week repeating presence pattern.
+class PresencePattern:
+    """One of a child's N-week repeating presence rules.
 
     ``pattern`` maps each week index of the cycle (``0`` .. ``n-1``)
-    to the set of present weekdays (ints, Monday=0).  A week with an
-    empty set means the child is absent every day of that week — which
-    is distinct from having no schedule at all (the engine treats a
-    missing schedule as present every day).
+    to the set of weekdays the rule covers (ints, Monday=0); ``kind``
+    is what the rule claims on a covered date (``home`` or ``away``).
+    A week with an empty set covers no day of that week.  How several
+    patterns combine is the engine's job (:class:`PresenceEngine`).
     """
 
     child_id: int
+    name: str
+    kind: str
     cycle_length_weeks: int
     anchor_date: datetime.date
     pattern: MappingProxyType  # week index -> frozenset of weekdays
@@ -166,11 +196,15 @@ class PresenceSchedule:
     def __init__(
         self,
         child_id: int,
+        name: str,
+        kind: str,
         cycle_length_weeks: int,
         anchor_date: object,
         pattern: dict[int, object],
     ) -> None:
         object.__setattr__(self, "child_id", _validate_child_id(child_id))
+        object.__setattr__(self, "name", _validate_name(name))
+        object.__setattr__(self, "kind", _validate_kind(kind))
         cycle = _validate_cycle_length(cycle_length_weeks)
         object.__setattr__(self, "cycle_length_weeks", cycle)
         object.__setattr__(
@@ -178,7 +212,7 @@ class PresenceSchedule:
         )
         if not isinstance(pattern, dict):
             raise ValueError(
-                "pattern must map week index to a set of present "
+                "pattern must map week index to a set of covered "
                 f"weekdays, got {pattern!r}"
             )
         normalised: dict[int, frozenset[int]] = {}
@@ -204,9 +238,9 @@ class PresenceSchedule:
         """Serialize to the database's pipe-separated CSV shape.
 
         Segments appear in week order; each segment is the week's
-        present weekdays as a sorted comma-separated list (an empty set
-        encodes as an empty segment).  Two schedules with equal
-        patterns encode identically.
+        covered weekdays as a sorted comma-separated list (an empty set
+        encodes as an empty segment).  Two patterns with equal weekday
+        sets encode identically.
         """
         segments = [
             ",".join(str(day) for day in sorted(self.pattern[week]))
@@ -218,10 +252,12 @@ class PresenceSchedule:
     def decode(
         cls,
         child_id: int,
+        name: str,
+        kind: str,
         anchor_date: object,
         encoded: str,
-    ) -> "PresenceSchedule":
-        """Build a schedule from its encoded pattern.
+    ) -> "PresencePattern":
+        """Build a pattern from its encoded weekday sets.
 
         The cycle length is derived from the segment count, mirroring
         the database's segment-count CHECK.  Decoding is strict: wrong
@@ -248,7 +284,15 @@ class PresenceSchedule:
                         )
                     weekdays.add(int(part))
             pattern[week] = weekdays
-        return cls(child_id, len(segments), anchor_date, pattern)
+        return cls(child_id, name, kind, len(segments), anchor_date, pattern)
+
+    def covers(self, date: datetime.date) -> bool:
+        """Return True when ``date``'s weekday is in its cycle week's set.
+
+        The cycle week comes from :func:`cycle_week_index` — anchor-date
+        arithmetic only, never ISO week numbers or parity (D-004).
+        """
+        return date.weekday() in self.pattern[cycle_week_index(self, date)]
 
 
 @dataclass(frozen=True, init=False)
@@ -301,7 +345,7 @@ class PresenceOverride:
 
 
 def cycle_week_index(
-    schedule: PresenceSchedule, target_date: object
+    pattern: PresencePattern, target_date: object
 ) -> int:
     """Return the cycle week index ``target_date`` falls in.
 
@@ -315,14 +359,14 @@ def cycle_week_index(
     valid week index.
     """
     target = _parse_date(target_date, "target_date")
-    days = (target - schedule.anchor_date).days
-    return (days // 7) % schedule.cycle_length_weeks
+    days = (target - pattern.anchor_date).days
+    return (days // 7) % pattern.cycle_length_weeks
 
 
 #: Search cap for :meth:`PresenceEngine.next_present_dates`: two full
-#: years of daily checks.  A child absent every day (an all-absent
-#: pattern with a blocking override) would otherwise loop forever; the
-#: cap bounds the scan and surfaces the situation as an error instead.
+#: years of daily checks.  A child absent every day (an away pattern
+#: covering every weekday) would otherwise loop forever; the cap bounds
+#: the scan and surfaces the situation as an error instead.
 MAX_PREVIEW_SCAN_DAYS = 366 * 2
 
 
@@ -330,40 +374,45 @@ class PresenceEngine:
     """Answers "is this child at this house on this date?".
 
     Pure and side-effect-free: built from an immutable snapshot of the
-    children's schedules (``child_id -> PresenceSchedule``), it never
-    touches the database — callers build a snapshot from the DAO layer
-    and pass it in.  A child with NO schedule entry is present every
-    day (the third household child's case); a child WITH a schedule is
-    present exactly when the date's weekday is in that schedule's
-    pattern for the date's cycle week index (anchor-date arithmetic —
-    :func:`cycle_week_index`, never ISO week parity).
+    children's patterns (``child_id -> list of PresencePattern``), it
+    never touches the database — callers build a snapshot from the DAO
+    layer and pass it in.  A child with NO pattern is present every day
+    (the third household child's case).  Evaluation order, first match
+    wins — see :meth:`is_present`.  Pattern coverage is anchor-date
+    arithmetic (:func:`cycle_week_index`, never ISO week parity).
     """
 
     def __init__(
         self,
-        schedules: dict[int, PresenceSchedule],
+        patterns: dict[int, list[PresencePattern]],
         overrides: dict[int, list[PresenceOverride]] | None = None,
     ) -> None:
-        if not isinstance(schedules, dict):
+        if not isinstance(patterns, dict):
             raise ValueError(
-                f"schedules must map child_id to PresenceSchedule, got "
-                f"{schedules!r}"
+                "patterns must map child_id to a list of PresencePattern, "
+                f"got {patterns!r}"
             )
-        for child_id, schedule in schedules.items():
+        for child_id, entries in patterns.items():
             # Validate the KEY as a model child id too: True and 1.0
-            # compare equal to 1, so {True: schedule(1)} would be
+            # compare equal to 1, so {True: [pattern(1)]} would be
             # accepted and then behave differently on lookup.
             _validate_child_id(child_id)
-            if not isinstance(schedule, PresenceSchedule):
+            if not isinstance(entries, list):
                 raise ValueError(
-                    f"schedules[{child_id!r}] must be a PresenceSchedule, "
-                    f"got {schedule!r}"
-                )
-            if schedule.child_id != child_id:
-                raise ValueError(
-                    f"schedules is keyed {child_id!r} but holds the "
-                    f"schedule of child {schedule.child_id}"
+                    f"patterns[{child_id!r}] must be a list of "
+                    f"PresencePattern, got {entries!r}"
                 )
+            for entry in entries:
+                if not isinstance(entry, PresencePattern):
+                    raise ValueError(
+                        f"patterns[{child_id!r}] entries must be "
+                        f"PresencePattern, got {entry!r}"
+                    )
+                if entry.child_id != child_id:
+                    raise ValueError(
+                        f"patterns is keyed {child_id!r} but holds a "
+                        f"pattern of child {entry.child_id}"
+                    )
         if overrides is None:
             overrides = {}
         if not isinstance(overrides, dict):
@@ -391,11 +440,17 @@ class PresenceEngine:
                     )
         # Read-only snapshot: reassignment is refused and no mutator
         # exists, so a built engine answers consistently for its
-        # lifetime.  The overrides lists are copied to immutable
-        # tuples — a shallow mapping copy alone would leave caller-
-        # owned lists reachable through _overrides, and mutating one
-        # later would change is_present results.
-        object.__setattr__(self, "_schedules", MappingProxyType(dict(schedules)))
+        # lifetime.  The patterns and overrides lists are copied to
+        # immutable tuples — a shallow mapping copy alone would leave
+        # caller-owned lists reachable, and mutating one later would
+        # change is_present results.
+        object.__setattr__(
+            self,
+            "_patterns",
+            MappingProxyType(
+                {child_id: tuple(entries) for child_id, entries in patterns.items()}
+            ),
+        )
         object.__setattr__(
             self,
             "_overrides",
@@ -407,12 +462,22 @@ class PresenceEngine:
     def is_present(self, child_id: object, date: object) -> bool:
         """Return whether ``child_id`` is present on ``date``.
 
-        Overrides take precedence over the repeating pattern: when an
-        override covers the date, its flag IS the answer — including
-        for a child with no schedule at all.  The DAO layer guarantees
-        a child's overrides never overlap; if a snapshot still carries
-        two covering the same date, the one with the LATEST start date
-        wins (deterministic, and matches "the most specific swap wins").
+        Ordered, first match wins:
+
+        1. An override covering the date — its flag IS the answer,
+           including for a child with no pattern at all.  The DAO layer
+           guarantees a child's overrides never overlap; if a snapshot
+           still carries two covering the same date, the one with the
+           LATEST start date wins (deterministic, and matches "the most
+           specific swap wins").
+        2. Any ``away`` pattern covering the date — absent.
+        3. Any ``home`` pattern covering the date — present.
+        4. Otherwise: absent when the child has at least one ``home``
+           pattern (a home pattern lists the days the child IS here, so
+           an uncovered date is a day away — the retired single-schedule
+           semantics, which migration 9 carries across as ``home``
+           patterns unchanged), else present (no pattern, or ``away``
+           patterns only: the household default).
         """
         if isinstance(child_id, bool) or not isinstance(child_id, int):
             raise ValueError(f"child_id must be an integer, got {child_id!r}")
@@ -424,12 +489,16 @@ class PresenceEngine:
         if covering:
             winner = max(covering, key=lambda entry: entry.start_date)
             return winner.is_present
-        schedule = self._schedules.get(child_id)
-        if schedule is None:
-            # No schedule at all: present every day (household default).
+        patterns = self._patterns.get(child_id) or ()
+        if any(
+            pattern.kind == "away" and pattern.covers(target)
+            for pattern in patterns
+        ):
+            return False
+        homes = [pattern for pattern in patterns if pattern.kind == "home"]
+        if any(pattern.covers(target) for pattern in homes):
             return True
-        week = cycle_week_index(schedule, target)
-        return target.weekday() in schedule.pattern[week]
+        return not homes
 
     def next_present_dates(
         self,
@@ -442,7 +511,7 @@ class PresenceEngine:
         Walks forward from ``start_date`` (INCLUSIVE — a parent
         previewing "starting Monday" expects Monday itself when the
         child is present) checking :meth:`is_present` for every day,
-        so overrides and the pattern are honoured identically.  The
+        so overrides and the patterns are honoured identically.  The
         admin Schedule tab renders this preview so a parent can confirm
         a custody pattern is right before saving it.
 

custom_components/nestquest/core/presence_management.py

@@ -2,11 +2,11 @@
 
 Sits between the write callers (the Feature 09 HA service handlers and
 the API admin plane's presence routes) and the typed presence DAOs plus
-the pure presence model: callers get the model validation, the upsert /
-create / delete operations and the regeneration side effect here, and
+the pure presence model: callers get the model validation, the create /
+update / delete operations and the regeneration side effect here, and
 never touch the DAO or SQL directly.  This is the ONE implementation of
 these business rules — every caller constructs the same
-:class:`~.presence.PresenceSchedule` / :class:`~.presence.PresenceOverride`
+:class:`~.presence.PresencePattern` / :class:`~.presence.PresenceOverride`
 models (whose constructors are total, so no re-validation happens in a
 handler) and gets the same post-write
 :func:`~.materialize.regenerate_for_child`, so a child's future quest
@@ -15,26 +15,33 @@ write.  Like the model it is Home-Assistant-free: ``today`` is a plain
 calendar date threaded through to the regeneration, defaulting to the
 host clock there.
 
-Upsert policy (Feature 05, unchanged): a child has AT MOST ONE presence
-schedule — setting again REPLACES the existing row rather than
-duplicating it.  Overrides are deletable by design (children are not —
-the children layer owns that guardrail).  Deleting a nonexistent
-override raises ValueError prefixed ``override_id:`` so a caller can
-distinguish "unknown id" from a rejected argument the same way the
+Pattern policy (schema 9): a child has ZERO OR MORE presence patterns,
+each created, edited and deleted by its own id.  Patterns and overrides
+are deletable by design (children are not — the children layer owns
+that guardrail).  An unknown pattern or override id raises ValueError
+prefixed ``pattern_id:`` / ``override_id:`` so a caller can distinguish
+"unknown id" from a rejected argument the same way the
 quest-definitions layer prefixes ``definition_id:``.
+
+The admin plane's presence READS go through here too
+(:func:`list_presence_patterns`, :func:`list_presence_overrides`), so a
+reader never touches the DAO directly either.
 """
 from __future__ import annotations
 
 import datetime
 
+from .dao_children import ChildrenDao
 from .dao_presence import (
     PresenceOverrideRecord,
     PresenceOverridesDao,
-    PresenceSchedulesDao,
+    PresencePatternRecord,
+    PresencePatternsDao,
 )
+from .dao_rules import _UNSET
 from .db import NestQuestDatabase
-from .materialize import regenerate_for_child
-from .presence import PresenceOverride, PresenceSchedule
+from .materialize import count_removed_by_override, regenerate_for_child
+from .presence import PresenceOverride, PresencePattern
 
 
 def _validate_override_id(value: object) -> int:
@@ -44,49 +51,159 @@ def _validate_override_id(value: object) -> int:
     return value
 
 
-async def set_presence_schedule(
+def _validate_pattern_id(value: object) -> int:
+    """Reject non-int pattern ids (bools would silently address id 1)."""
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"pattern_id must be an integer, got {value!r}")
+    return value
+
+
+async def _get_pattern_or_raise(
+    dao: PresencePatternsDao, pattern_id: object
+) -> PresencePatternRecord:
+    """Return the stored pattern; an unknown id raises ``pattern_id:``."""
+    record = await dao.get(_validate_pattern_id(pattern_id))
+    if record is None:
+        raise ValueError(
+            f"pattern_id: presence pattern {pattern_id} does not exist"
+        )
+    return record
+
+
+def decode_pattern_record(record: PresencePatternRecord) -> PresencePattern:
+    """Decode one stored pattern row back through the model."""
+    return PresencePattern.decode(
+        record.child_id,
+        record.name,
+        record.kind,
+        record.anchor_date,
+        record.pattern,
+    )
+
+
+async def create_presence_pattern(
     database: NestQuestDatabase,
     child_id: int,
+    name: str,
+    kind: str,
     cycle_length_weeks: int,
     anchor_date: object,
     pattern: dict[int, object],
     *,
     today: datetime.date | None = None,
     horizon_days: int | None = None,
-) -> PresenceSchedule:
-    """Set (upsert) a child's repeating presence schedule.
+) -> PresencePatternRecord:
+    """Add one repeating presence pattern to a child.
 
-    The :class:`~.presence.PresenceSchedule` model validates at
-    construction — cycle length 1..4, a strict calendar anchor date,
-    and a pattern covering week indices 0..n-1 with weekday sets — so
-    no invalid schedule reaches the DAO.  The encoded pattern is
-    UPSERTed by child (a second set REPLACES the child's existing
-    schedule; the schema's UNIQUE(child_id) makes duplication
-    unrepresentable), then :func:`~.materialize.regenerate_for_child`
+    The :class:`~.presence.PresencePattern` model validates at
+    construction — a non-blank name, ``kind`` ``home``/``away``, cycle
+    length 1..4, a strict calendar anchor date, and a pattern covering
+    week indices 0..n-1 with weekday sets — so no invalid pattern
+    reaches the DAO.  The encoded pattern is inserted beside the
+    child's other patterns, then :func:`~.materialize.regenerate_for_child`
     re-materializes the child's future instances against the new
     presence.  ``today``/``horizon_days`` thread through to that
     regeneration; raising ValueError names what to fix (an unknown
     child reads ``child N does not exist``).
 
-    Returns the STORED schedule decoded back through the model — the
-    round-trip proves the encoded pattern the database now holds is
-    exactly the one the caller asked for.
+    Returns the STORED record WITH its ``id`` — the handle
+    :func:`update_presence_pattern` and :func:`delete_presence_pattern`
+    take.
     """
-    schedule = PresenceSchedule(
-        child_id, cycle_length_weeks, anchor_date, pattern
+    model = PresencePattern(
+        child_id, name, kind, cycle_length_weeks, anchor_date, pattern
     )
-    record = await PresenceSchedulesDao(database).upsert_by_child(
-        schedule.child_id,
-        schedule.cycle_length_weeks,
-        schedule.anchor_date.isoformat(),
-        schedule.encode(),
+    record = await PresencePatternsDao(database).create(
+        model.child_id,
+        model.name,
+        model.kind,
+        model.cycle_length_weeks,
+        model.anchor_date.isoformat(),
+        model.encode(),
     )
     await regenerate_for_child(
-        database, schedule.child_id, today=today, horizon_days=horizon_days
+        database, model.child_id, today=today, horizon_days=horizon_days
     )
-    return PresenceSchedule.decode(
-        record.child_id, record.anchor_date, record.pattern
+    return record
+
+
+async def update_presence_pattern(
+    database: NestQuestDatabase,
+    pattern_id: int,
+    *,
+    name: str | object = _UNSET,
+    kind: str | object = _UNSET,
+    cycle_length_weeks: int | object = _UNSET,
+    anchor_date: object = _UNSET,
+    pattern: dict[int, object] | object = _UNSET,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> PresencePatternRecord:
+    """Edit one presence pattern; only supplied fields change.
+
+    The pattern is looked up FIRST (an unknown id raises ValueError
+    prefixed ``pattern_id:``), the supplied fields are laid over the
+    stored ones and the WHOLE result is rebuilt through the
+    :class:`~.presence.PresencePattern` model — so a partial edit is
+    validated exactly as a create is (changing ``cycle_length_weeks``
+    without a matching ``pattern`` is rejected), and an explicit None
+    is rejected rather than ignored.  The pattern stays with its child;
+    the child's future instances are regenerated afterwards.
+    """
+    dao = PresencePatternsDao(database)
+    stored = decode_pattern_record(await _get_pattern_or_raise(dao, pattern_id))
+    model = PresencePattern(
+        stored.child_id,
+        stored.name if name is _UNSET else name,
+        stored.kind if kind is _UNSET else kind,
+        (
+            stored.cycle_length_weeks
+            if cycle_length_weeks is _UNSET
+            else cycle_length_weeks
+        ),
+        stored.anchor_date if anchor_date is _UNSET else anchor_date,
+        dict(stored.pattern) if pattern is _UNSET else pattern,
     )
+    record = await dao.update(
+        pattern_id,
+        model.name,
+        model.kind,
+        model.cycle_length_weeks,
+        model.anchor_date.isoformat(),
+        model.encode(),
+    )
+    if record is None:
+        raise ValueError(
+            f"pattern_id: presence pattern {pattern_id} does not exist"
+        )
+    await regenerate_for_child(
+        database, model.child_id, today=today, horizon_days=horizon_days
+    )
+    return record
+
+
+async def delete_presence_pattern(
+    database: NestQuestDatabase,
+    pattern_id: int,
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> PresencePatternRecord:
+    """Delete one presence pattern by id and return it as it was stored.
+
+    The pattern is looked up FIRST and an unknown id raises ValueError
+    prefixed ``pattern_id:`` BEFORE any delete, so a mistyped id can
+    never be silently swallowed by a no-op.  The deletion is followed
+    by :func:`~.materialize.regenerate_for_child` for the pattern's own
+    child — the id decides the child, never a caller-supplied one.
+    """
+    dao = PresencePatternsDao(database)
+    record = await _get_pattern_or_raise(dao, pattern_id)
+    await dao.delete(record.id)
+    await regenerate_for_child(
+        database, record.child_id, today=today, horizon_days=horizon_days
+    )
+    return record
 
 
 async def create_presence_override(
@@ -130,6 +247,73 @@ async def create_presence_override(
     return record
 
 
+async def preview_presence_override_consequence(
+    database: NestQuestDatabase,
+    child_id: int,
+    start_date: object,
+    end_date: object,
+    is_present: bool,
+    *,
+    today: datetime.date | None = None,
+    horizon_days: int | None = None,
+) -> int:
+    """Return how many upcoming instances saving this override removes.
+
+    The admin override editor's live consequence warning, computed
+    BEFORE anything is saved: the arguments build the SAME
+    :class:`~.presence.PresenceOverride` :func:`create_presence_override`
+    builds (so a malformed or inverted range, or a non-bool
+    ``is_present``, raises the same ValueError), then
+    :func:`~.materialize.count_removed_by_override` compares what the
+    materialization walk generates for the child with and without it.
+    Nothing is written.  An unknown child reads ``child N does not
+    exist``; an INACTIVE child has no instances to remove (the walk's
+    write path never materializes one), so it counts 0.
+    ``today``/``horizon_days`` resolve as the post-save regeneration
+    resolves them.
+    """
+    override = PresenceOverride(child_id, start_date, end_date, is_present)
+    child = await ChildrenDao(database).get(override.child_id)
+    if child is None:
+        raise ValueError(f"child {override.child_id} does not exist")
+    if not child.is_active:
+        return 0
+    return await count_removed_by_override(
+        database, override, today=today, horizon_days=horizon_days
+    )
+
+
+async def list_presence_patterns(
+    database: NestQuestDatabase, child_id: int
+) -> list[PresencePatternRecord]:
+    """Return the child's presence patterns ordered by id.
+
+    An empty list means the child exists and has no pattern — present
+    every day (Feature 05).  An unknown child raises ValueError
+    (``child N does not exist``) rather than reading as present.
+    """
+    return await PresencePatternsDao(database).list_by_child(child_id)
+
+
+async def list_presence_overrides(
+    database: NestQuestDatabase,
+    *,
+    child_id: int | None = None,
+    start: str | None = None,
+    end: str | None = None,
+) -> list[PresenceOverrideRecord]:
+    """Return the household's presence overrides, optionally filtered.
+
+    ``child_id`` narrows to one child (unknown: ``child N does not
+    exist``); ``start``/``end`` keep the overrides overlapping that
+    closed range (strict YYYY-MM-DD, ``end >= start``).  Ordered by
+    start date, then child id, then id.
+    """
+    return await PresenceOverridesDao(database).list_filtered(
+        child_id=child_id, start=start, end=end
+    )
+
+
 async def delete_presence_override(
     database: NestQuestDatabase,
     override_id: int,

custom_components/nestquest/core/quest_definitions.py

@@ -4,8 +4,9 @@ Sits between the Feature 09 service gate and the typed
 :class:`~.dao_rules.QuestDefinitionsDao`: callers get validation and the
 all-or-nothing create/edit here, and never touch the DAO SQL directly.
 :func:`create_quest_definition` is the create path,
-:func:`edit_quest_definition` the edit path, :func:`assign_child` and
-:func:`unassign_child` the assignment paths, and
+:func:`edit_quest_definition` the edit path (which may also replace the
+whole assignee set), :func:`assign_child` and
+:func:`unassign_child` the single-child assignment paths, and
 :func:`set_quest_definition_active` the deactivate/reactivate path.
 There is no permission check here (that is Feature 09).
 
@@ -58,6 +59,7 @@ from .dao_rules import (
     schedule_rule_to_storage,
 )
 from .db import NestQuestDatabase
+from .icons import validate_icon
 from .materialize import regenerate_for_definition
 from .recurrence import ScheduleRule, occurs_on
 
@@ -191,6 +193,17 @@ def _validate_definition_id(value: object) -> int:
     return value
 
 
+def _validate_skip_on_away(value: object) -> bool:
+    """Reject a non-bool ``skip_on_away`` before any write.
+
+    The DAO's ``int()`` would otherwise silently coerce strings and
+    numerics ("0", 1) into a state the caller never asked for.
+    """
+    if not isinstance(value, bool):
+        raise ValueError(f"skip_on_away must be a real bool, got {value!r}")
+    return value
+
+
 def _validate_child_id(value: object) -> int:
     """Reject non-int child ids (bools included) before any lookup.
 
@@ -212,6 +225,7 @@ async def create_quest_definition(
     *,
     description: str | None = None,
     icon: str | None = None,
+    skip_on_away: bool = True,
 ) -> CreatedQuestDefinition:
     """Create a quest definition (rule + assignees + windows) atomically.
 
@@ -222,6 +236,11 @@ async def create_quest_definition(
     transaction, so the returned bundle is a consistent creation
     snapshot.  Raises ValueError on any rejected argument; a rejected or
     failed create persists nothing.
+
+    After the write, :func:`~.materialize.regenerate_for_definition`
+    materializes the new definition's instances over the rolling horizon
+    (host clock, :data:`~.const.DEFAULT_HORIZON_DAYS`), so it reaches the
+    board without waiting for an unrelated write.
     """
     name = _validate_text(title, "title", required=True)
     assert name is not None
@@ -230,7 +249,8 @@ async def create_quest_definition(
     assignee_ids = _validate_assignee_ids(assignee_child_ids)
     window_specs = _normalize_windows(windows)
     description_value = _validate_text(description, "description")
-    icon_value = _validate_text(icon, "icon")
+    icon_value = validate_icon(icon)
+    skip_on_away_value = _validate_skip_on_away(skip_on_away)
 
     storage = schedule_rule_to_storage(rule)
     dao = QuestDefinitionsDao(database)
@@ -243,6 +263,7 @@ async def create_quest_definition(
             window_specs,
             description=description_value,
             icon=icon_value,
+            skip_on_away=skip_on_away_value,
         )
     except ValueError as error:
         # The DAO's assignee check names only the child; re-raise so the
@@ -254,6 +275,9 @@ async def create_quest_definition(
             ) from error
         raise
     decoded_rule = schedule_rule_from_storage(storage)
+
+    await regenerate_for_definition(database, snapshot.definition.id)
+
     return CreatedQuestDefinition(
         definition=snapshot.definition,
         rule=decoded_rule,
@@ -271,10 +295,12 @@ async def edit_quest_definition(
     icon: str | None | object = _UNSET,
     rule: ScheduleRule | object = _UNSET,
     windows: list[str | tuple[str, str | None]] | object = _UNSET,
+    skip_on_away: bool | None = None,
+    assignee_child_ids: list[int] | object = _UNSET,
     today: datetime.date | None = None,
     horizon_days: int | None = None,
 ) -> CreatedQuestDefinition:
-    """Edit a quest definition's metadata, rule and windows atomically.
+    """Edit a quest definition's metadata, rule, windows and assignees atomically.
 
     Arguments default to the sentinel ``_UNSET`` meaning "leave this
     field alone".  A provided ``title`` is validated like create's
@@ -285,9 +311,16 @@ async def edit_quest_definition(
     ``schedule_rules`` row is updated, never orphaned or duplicated.  A
     provided ``windows`` list REPLACES the whole window set (each entry
     a ``const.QUEST_WINDOWS`` name, optionally with a strict HH:MM due
-    time), matching create's non-empty contract.  Assignment is NOT
-    settable here.  Raises ValueError when the definition does not
-    exist or any argument is rejected.
+    time), matching create's non-empty contract.  A provided
+    ``skip_on_away`` (a real bool) replaces the stored flag; ``None``
+    leaves it unchanged.  A provided ``assignee_child_ids`` REPLACES the
+    whole assignee set under create's contract (a non-empty list of
+    distinct plain ints, each an existing ACTIVE child — the DAO checks
+    that inside the edit's transaction): newly listed children are
+    assigned and unlisted ones unassigned.  Raises ValueError when the
+    definition does not exist or any argument is rejected; a rejection
+    writes nothing, so the stored assignees (and every other field)
+    stay unchanged.
 
     Returns the updated definition together with its decoded rule,
     assignees and windows — all read back inside the DAO's transaction,
@@ -319,7 +352,7 @@ async def edit_quest_definition(
 
     icon_value: str | None | object = _UNSET
     if icon is not _UNSET:
-        icon_value = _validate_text(icon, "icon")
+        icon_value = validate_icon(icon)
 
     rule_storage: ScheduleRuleStorage | object = _UNSET
     if rule is not _UNSET:
@@ -331,6 +364,14 @@ async def edit_quest_definition(
     if windows is not _UNSET:
         window_specs = _normalize_windows(windows)
 
+    assignee_ids: list[int] | object = _UNSET
+    if assignee_child_ids is not _UNSET:
+        assignee_ids = _validate_assignee_ids(assignee_child_ids)
+
+    skip_on_away_value: bool | object = _UNSET
+    if skip_on_away is not None:
+        skip_on_away_value = _validate_skip_on_away(skip_on_away)
+
     dao = QuestDefinitionsDao(database)
     try:
         snapshot = await dao.edit_definition(
@@ -340,14 +381,18 @@ async def edit_quest_definition(
             icon=icon_value,
             rule=rule_storage,
             windows=window_specs,
+            skip_on_away=skip_on_away_value,
+            assignee_child_ids=assignee_ids,
         )
     except ValueError as error:
-        # The DAO's missing-definition error names only the id; re-raise
-        # so the public contract names the field the caller passed (matching
-        # assign/unassign/deactivate).
+        # The DAO's missing-definition and assignee errors name only the
+        # id; re-raise so the public contract names the field the caller
+        # passed (matching create/assign/unassign/deactivate).
         message = str(error)
         if message.startswith("quest definition "):
             raise ValueError(f"definition_id: {message}") from error
+        if message.startswith("child "):
+            raise ValueError(f"assignee_child_ids: {message}") from error
         raise
 
     decoded_rule = schedule_rule_from_storage(
@@ -558,6 +603,21 @@ async def list_active_definitions(
     return [_bundle_snapshot(snapshot) for snapshot in snapshots]
 
 
+async def list_all_definitions(
+    database: NestQuestDatabase,
+) -> list[CreatedQuestDefinition]:
+    """Return EVERY definition, active AND inactive (rich view).
+
+    Mirrors :func:`list_active_definitions` without the activity
+    filter: ordered by rising definition id, each entry the same
+    :class:`CreatedQuestDefinition` snapshot, read by the DAO inside one
+    locked transaction.
+    """
+    dao = QuestDefinitionsDao(database)
+    snapshots = await dao.list_snapshots_all()
+    return [_bundle_snapshot(snapshot) for snapshot in snapshots]
+
+
 async def list_definitions_for_child(
     database: NestQuestDatabase,
     child_id: int,

custom_components/nestquest/core/schema.py

@@ -43,18 +43,19 @@ rule or a monthly rule could later be pinned to a month) nor extra
 fields on weekly/monthly/yearly rules generally, so the CHECKs only
 reject what the rule engine definitively cannot express now.
 
-Presence pattern format: ``presence_schedules.pattern`` encodes the
+Presence pattern format: ``presence_patterns.pattern`` encodes the
 whole N-week repeating cycle in one TEXT column as pipe-separated
 segments, one per week of the cycle: segment ``i`` is a ``weekday_set``
 CSV (same single-digit 0-6 convention as ``schedule_rules.weekday_set``)
 for week ``i``, e.g. ``'0,2,4|1,3'`` = Mon/Wed/Fri in week 0, Tue/Thu in
-week 1.  An empty segment means the child is absent every day of that
-week; a wholly empty pattern with ``cycle_length_weeks = 1`` means
-absent every day of every week, which is distinct from having no
-schedule row at all (a child with no schedule is present every day, per
-the feature guardrails).  Chosen over JSON or per-week rows to stay
-consistent with the CSV ``weekday_set`` convention and fully checkable
-by plain CHECKs.  DB-level validation is pure CHECK, no triggers or
+week 1.  An empty segment means the pattern covers no day of that week.
+A child carries zero or more patterns, each ``kind`` ``home`` or
+``away``; a child with no pattern row at all is present every day, per
+the feature guardrails (how patterns combine is the presence engine's
+job).  The encoding and its CHECKs are carried over verbatim from the
+retired ``presence_schedules`` table (schema 9).  Chosen over JSON or
+per-week rows to stay consistent with the CSV ``weekday_set``
+convention and fully checkable by plain CHECKs.  DB-level validation is pure CHECK, no triggers or
 custom functions: char-class GLOBs reject every character outside
 digits 0-6, comma and pipe; adjacency GLOBs reject empty elements
 (double comma, comma next to a pipe, leading/trailing comma) and
@@ -68,7 +69,8 @@ weekday_set this is not full CSV-set normalisation (duplicates like
 the engine treats the segment as a set.  A
 one-row-per-``week_index`` normalization was considered and rejected:
 the flat single-column encoding keeps the done-condition's table shape
-and proved fully checkable with plain CHECKs.
+and proved fully checkable with plain CHECKs.  ``name`` is a short
+label and carries no CHECK; the model rejects a blank one.
 
 ``cycle_length_weeks`` is capped at 4: 2 (alternating weeks) is the
 common case, and a small cap keeps anchor arithmetic and the encoded
@@ -257,7 +259,8 @@ QUEST_DEFINITIONS_TABLE_SQL = """(
     schedule_rule_id INTEGER NOT NULL REFERENCES schedule_rules(id),
     due_time TEXT,
     is_active INTEGER NOT NULL DEFAULT 1 CHECK (typeof(is_active) = 'integer' AND is_active IN (0, 1)),
-    created_at TEXT NOT NULL
+    created_at TEXT NOT NULL,
+    skip_on_away INTEGER NOT NULL DEFAULT 1 CHECK (skip_on_away IN (0, 1))
 )"""
 
 SCHEMA_V1_QUEST_DEFINITIONS_DDL: list[str] = [
@@ -287,11 +290,19 @@ SCHEMA_V1_QUEST_DEFINITION_WINDOWS_DDL: list[str] = [
     """,
 ]
 
-SCHEMA_V1_PRESENCE_SCHEDULES_DDL: list[str] = [
-    f"""
-    CREATE TABLE IF NOT EXISTS presence_schedules (
+#: ``presence_patterns`` (schema version 9): zero or more repeating
+#: presence rules per child, replacing the retired one-per-child
+#: ``presence_schedules`` table.  ``child_id`` is deliberately NOT
+#: unique; ``kind`` is what a covering pattern claims (``home`` or
+#: ``away``); ``pattern`` keeps the retired table's encoding and CHECKs
+#: verbatim.
+SCHEMA_V9_PRESENCE_PATTERNS_DDL: list[str] = [
+    """
+    CREATE TABLE IF NOT EXISTS presence_patterns (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
-        child_id INTEGER NOT NULL UNIQUE REFERENCES children(id),
+        child_id INTEGER NOT NULL REFERENCES children(id),
+        name TEXT NOT NULL,
+        kind TEXT NOT NULL CHECK (kind IN ('home', 'away')),
         cycle_length_weeks INTEGER NOT NULL CHECK (typeof(cycle_length_weeks) = 'integer' AND cycle_length_weeks >= 1 AND cycle_length_weeks <= 4),
         anchor_date TEXT NOT NULL,
         pattern TEXT NOT NULL CHECK (
@@ -406,7 +417,7 @@ SCHEMA_V1_STATEMENTS: list[str] = [
     *SCHEMA_V1_QUEST_DEFINITIONS_DDL,
     *SCHEMA_V1_QUEST_DEFINITION_ASSIGNEES_DDL,
     *SCHEMA_V1_QUEST_DEFINITION_WINDOWS_DDL,
-    *SCHEMA_V1_PRESENCE_SCHEDULES_DDL,
+    *SCHEMA_V9_PRESENCE_PATTERNS_DDL,
     *SCHEMA_V1_PRESENCE_OVERRIDES_DDL,
     *SCHEMA_V1_QUEST_INSTANCES_DDL,
     *SCHEMA_V1_COMPLETION_EVENTS_DDL,

custom_components/nestquest/core/settings.py

@@ -35,6 +35,7 @@ from collections.abc import Callable
 from dataclasses import dataclass
 from types import MappingProxyType
 from typing import Any, Mapping
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 from .const import (
     CONF_AFTERNOON_REMINDER_ENABLED,
@@ -47,12 +48,14 @@ from .const import (
     CONF_MORNING_SUMMARY_ENABLED,
     CONF_MORNING_SUMMARY_TIME,
     CONF_NOTIFY_TARGET,
+    CONF_TIMEZONE,
     DEFAULT_AFTERNOON_REMINDER_TIME,
     DEFAULT_AUTOMATION_ENABLED,
     DEFAULT_DAY_ROLLOVER_TIME,
     DEFAULT_END_OF_DAY_REPORT_TIME,
     DEFAULT_HORIZON_DAYS,
     DEFAULT_MORNING_SUMMARY_TIME,
+    DEFAULT_TIMEZONE,
     LOGGER,
     TIME_PATTERN,
 )
@@ -153,6 +156,29 @@ def _resolve_optional_str(value: Any) -> str:
     return value.strip()
 
 
+def _resolve_timezone(value: Any) -> str:
+    """Validate a household time zone and return it.
+
+    The empty string means "the API host's local time" (the historical
+    behaviour); anything else must be an IANA key :class:`ZoneInfo`
+    resolves (e.g. ``America/New_York``).  A non-str (including
+    ``None``) is rejected; the ``None``-as-absent mapping lives ONLY in
+    :meth:`NestQuestSettings.from_options` (via :func:`_option_value`).
+    """
+    if not isinstance(value, str):
+        raise ValueError(f"timezone must be a string, got {value!r}")
+    if value == "":
+        return value
+    try:
+        ZoneInfo(value)
+    except (ZoneInfoNotFoundError, ValueError) as error:
+        raise ValueError(
+            f"timezone must be an IANA time zone name such as "
+            f"'America/New_York', got {value!r}"
+        ) from error
+    return value
+
+
 #: The single field table the two builders share.  Each row is
 #: ``(field_name, CONF_* key, default, validator)``.  ``from_options``
 #: applies every validator (raising on the first invalid value) while
@@ -214,6 +240,7 @@ _FIELDS: tuple[tuple[str, str, Any, Callable[[Any], Any]], ...] = (
         DEFAULT_AUTOMATION_ENABLED,
         _resolve_bool,
     ),
+    ("timezone", CONF_TIMEZONE, DEFAULT_TIMEZONE, _resolve_timezone),
 )
 
 
@@ -243,6 +270,7 @@ class NestQuestSettings:
     afternoon_reminder_enabled: bool = DEFAULT_AUTOMATION_ENABLED
     end_of_day_report_enabled: bool = DEFAULT_AUTOMATION_ENABLED
     celebration_enabled: bool = DEFAULT_AUTOMATION_ENABLED
+    timezone: str = DEFAULT_TIMEZONE
 
     def __post_init__(self) -> None:
         # Validate STRICTLY at construction so a hand-built instance
@@ -281,6 +309,21 @@ class NestQuestSettings:
                 raise ValueError(
                     f"{name} must be a boolean, got {value!r}"
                 )
+        _resolve_timezone(self.timezone)
+
+    def household_now(self, instant: datetime.datetime) -> datetime.datetime:
+        """Return the aware ``instant`` expressed in the household's zone.
+
+        The API service has no Home Assistant ``time_zone``, so its one
+        clock read (an aware host-local ``now``) is converted here: with
+        :attr:`timezone` set the SAME instant is re-expressed in that
+        zone, so ``.date()`` and ``.time()`` are the household's wall
+        clock even when the host runs UTC.  With :attr:`timezone` empty
+        the instant is returned unchanged (the host's local time).
+        """
+        if not self.timezone:
+            return instant
+        return instant.astimezone(ZoneInfo(self.timezone))
 
     @property
     def day_rollover_hour_minute(self) -> tuple[int, int]:

custom_components/nestquest/core/settings_store.py

@@ -18,7 +18,7 @@ API client; the two are deliberately NOT unified here, and neither
 side reads the other's values.
 
 STORED SERIALIZATION — the document at ``SETTINGS_META_KEY`` is a JSON
-object holding exactly the TEN settings fields, keyed by field name
+object holding exactly the ELEVEN settings fields, keyed by field name
 (which equals the ``CONF_*`` option key for every field), complete
 after the first update:
 
@@ -30,7 +30,10 @@ after the first update:
   core's normalizer),
 - ``morning_summary_enabled``, ``afternoon_reminder_enabled``,
   ``end_of_day_report_enabled``, ``celebration_enabled`` — real
-  booleans.
+  booleans,
+- ``timezone`` — ``""`` (the API host's local time) or an IANA time
+  zone name such as ``America/New_York``.  A document stored before
+  this field existed simply lacks it and resolves to ``""``.
 
 Only values whose core validators ACCEPTED are ever written, so a
 stored document always round-trips through the core's option builders.
@@ -172,7 +175,7 @@ async def update_settings(
     update can never leave a half-applied document behind.
 
     The validated changes are merged onto the current effective
-    settings and the merged (complete, ten-field) document is persisted
+    settings and the merged (complete, eleven-field) document is persisted
     in one atomic upsert; the updated settings are returned.  The whole
     read → merge → write span runs inside the per-database settings
     lock, so concurrent updates queue instead of interleaving.

custom_components/nestquest/core/snapshot.py

@@ -39,14 +39,15 @@ from typing import Any
 from .completion import derive_state
 from .dao_children import ChildrenDao
 from .dao_instances import CompletionEventsDao, QuestInstancesDao
-from .dao_presence import PresenceOverridesDao, PresenceSchedulesDao
+from .dao_presence import PresenceOverridesDao, PresencePatternsDao
 from .dao_rules import QuestDefinitionsDao
 from .db import NestQuestDatabase
+from .icons import normalize_icon_for_read
 from .presence import (
     MAX_PREVIEW_SCAN_DAYS,
     PresenceEngine,
     PresenceOverride,
-    PresenceSchedule,
+    PresencePattern,
 )
 from .settings import NestQuestSettings
 
@@ -98,20 +99,26 @@ class NestQuestSnapshot:
 
 
 def _cycle_day(
-    schedules: dict[int, PresenceSchedule], children, today: datetime.date
+    patterns: dict[int, list[PresencePattern]],
+    children,
+    today: datetime.date,
 ) -> int:
-    """Return today's 1-based day in the first scheduled child's cycle.
+    """Return today's 1-based day in the first patterned child's cycle.
 
-    Anchor-date arithmetic ONLY (D-004): the day offset is computed from
-    the schedule's own anchor, never ISO week numbers or parity, so a
-    53-week year cannot silently invert the cycle.
+    The cycle is that child's FIRST pattern (lowest id) — one number
+    for the household's cycle-day sensor even when a child carries
+    several patterns.  Anchor-date arithmetic ONLY (D-004): the day
+    offset is computed from the pattern's own anchor, never ISO week
+    numbers or parity, so a 53-week year cannot silently invert the
+    cycle.
     """
     for child in children:
-        schedule = schedules.get(child.id)
-        if schedule is None:
+        entries = patterns.get(child.id)
+        if not entries:
             continue
-        days = (today - schedule.anchor_date).days
-        cycle_length = schedule.cycle_length_weeks * 7
+        pattern = entries[0]
+        days = (today - pattern.anchor_date).days
+        cycle_length = pattern.cycle_length_weeks * 7
         return (days % cycle_length) + 1
     return 0
 
@@ -191,16 +198,21 @@ async def build_snapshot(
 
     children = await ChildrenDao(database).list_active()
 
-    schedules: dict[int, PresenceSchedule] = {}
+    patterns: dict[int, list[PresencePattern]] = {}
     overrides: dict[int, list[PresenceOverride]] = {}
     for child in children:
-        schedule = await PresenceSchedulesDao(database).get_by_child(
-            child.id
-        )
-        if schedule is not None:
-            schedules[child.id] = PresenceSchedule.decode(
-                child.id, schedule.anchor_date, schedule.pattern
-            )
+        records = await PresencePatternsDao(database).list_by_child(child.id)
+        if records:
+            patterns[child.id] = [
+                PresencePattern.decode(
+                    record.child_id,
+                    record.name,
+                    record.kind,
+                    record.anchor_date,
+                    record.pattern,
+                )
+                for record in records
+            ]
         window_end = today + datetime.timedelta(
             days=MAX_PREVIEW_SCAN_DAYS
         )
@@ -222,7 +234,7 @@ async def build_snapshot(
                 )
                 for record in ranged
             ]
-    engine = PresenceEngine(schedules, overrides)
+    engine = PresenceEngine(patterns, overrides)
 
     instances_dao = QuestInstancesDao(database)
     events_dao = CompletionEventsDao(database)
@@ -251,7 +263,11 @@ async def build_snapshot(
                     definition_id=instance.definition_id,
                     child_id=instance.child_id,
                     title=definition.title if definition else "Quest",
-                    icon=definition.icon if definition else None,
+                    icon=(
+                        normalize_icon_for_read(definition.icon)
+                        if definition
+                        else None
+                    ),
                     window=instance.window,
                     due_date=instance.due_date,
                     due_time=instance.due_time,
@@ -302,5 +318,5 @@ async def build_snapshot(
     return NestQuestSnapshot(
         today_iso=today_iso,
         children=tuple(snapshots),
-        cycle_day=_cycle_day(schedules, children, today),
+        cycle_day=_cycle_day(patterns, children, today),
     )

custom_components/nestquest/core/sweep.py

@@ -40,8 +40,8 @@ announces nothing.
 
 The caller supplies ``today`` as a plain :class:`datetime.date`: the
 household-local calendar date, read from ``hass.config.time_zone`` by
-the integration or from the API host's local clock by the API.  This
-module never reads a timezone database or config of its own.
+the integration or from the configured household timezone by the API.
+This module never reads a timezone database or config of its own.
 """
 from __future__ import annotations
 
@@ -98,7 +98,8 @@ async def run_missed_sweep(
 
     ``today`` is the household-local calendar date the sweep runs for
     (the caller owns the clock: the integration reads it from
-    ``hass.config.time_zone``, the API from its host's local time).
+    ``hass.config.time_zone``, the API from the configured household
+    timezone, falling back to its host's local time when unset).
     Returns the ``(event_type, payload)`` tuples to announce, EMPTY
     when the watermark already covers ``today`` (a same-night rerun) —
     the caller decides how to publish them and announces nothing on

custom_components/nestquest/manifest.json

@@ -15,5 +15,5 @@
   "iot_class": "local_polling",
   "issue_tracker": "https://github.com/Maniacs-Mansion/NestQuest/issues",
   "requirements": [],
-  "version": "0.6.0"
+  "version": "0.8.0"
 }

deploy/.env.example

@@ -0,0 +1,34 @@
+# Example environment for the NestQuest API container deployment.
+#
+# Copy to ``deploy/.env`` (git-ignored) and fill in REAL values there;
+# this example carries placeholder names only and is never a source of
+# secrets.  Compose loads ``deploy/.env`` into the api service; the
+# API fails fast on startup when any of these is unset or empty
+# (api/config.py — there are no silent defaults).
+
+# The static panel-plane service token the HA integration presents as
+# a Bearer credential on /api/v1/panel/* routes. Generate one, e.g.:
+#   python -c "import secrets; print(secrets.token_urlsafe(32))"
+NESTQUEST_PANEL_TOKEN=
+
+# The Authentik OIDC settings the admin plane verifies JWTs against.
+NESTQUEST_OIDC_ISSUER=
+NESTQUEST_OIDC_AUDIENCE=
+NESTQUEST_OIDC_JWKS_URL=
+
+# The host interface the API's port 8080 is published on (compose
+# interpolation, not read by the API).  Defaults to 127.0.0.1 when
+# unset; on the API box set the LAN address the reverse proxy
+# forwards to, e.g. 10.60.1.14.
+NESTQUEST_BIND_ADDRESS=
+
+# Admin PWA build args (compose interpolation into the pwa service's
+# VITE_* build args; baked into the bundle, so rebuild after changing).
+# PUBLIC values, not secrets: the Authentik application is a PKCE client
+# with no client secret.  All three are required — the pwa image build
+# fails when any is empty.
+#   NESTQUEST_AUTHENTIK_ISSUER=https://auth.cubecraftlabs.com/application/o/nestquest/
+#   NESTQUEST_API_BASE_URL=https://nestquest.cubecraftlabs.com
+NESTQUEST_AUTHENTIK_CLIENT_ID=
+NESTQUEST_AUTHENTIK_ISSUER=
+NESTQUEST_API_BASE_URL=

deploy/RUNBOOK.md

@@ -0,0 +1,622 @@
+# NestQuest API — deployment and restore runbook
+
+Operator procedure to rebuild the production NestQuest API deployment end
+to end from this repository, restore its database from backup, and verify
+it. Every value below is the real, non-secret production value. **No
+secret appears in this file** — secrets are named and their location is
+given, never their content.
+
+| Piece | Where | Real value |
+| --- | --- | --- |
+| API box (Docker host) | this repository's `deploy/` | `10.60.1.14`, port `8080` (API), `8081` (admin PWA, section 10) |
+| Reverse proxy / TLS | shared Traefik on `nukapi-03` | `10.60.1.33` |
+| Public hostname | Cloudflare DNS | `nestquest.cubecraftlabs.com` |
+| Identity | Authentik | `https://auth.cubecraftlabs.com` |
+| Home Assistant box (panel client) | LAN | `10.60.1.80` |
+| Local DNS | Pi-hole | `10.60.1.101` |
+| Backup target | Synology NAS `CubeCraft-SRVR1`, SFTP | `10.60.1.50:/homes/Joshua/nestquest-backups` |
+
+All `docker compose` commands below are run **on the API box, from the
+repository root**. The shorthand `dc` means:
+
+    alias dc='docker compose -f deploy/compose.yaml'
+
+Compose v2.24 or newer is required (`env_file` uses the `path`/`required`
+form).
+
+---
+
+## 1. Image build
+
+The image is defined by the root `Dockerfile` and is built from the
+**repository root** as the build context: the API (`api/`) loads the
+bundled domain core from `custom_components/nestquest/core/` by file
+location, so both trees must be in the context. `.dockerignore` keeps
+everything else (including `deploy/`, `.env` files and `*.db`) out of the
+build.
+
+- Multi-stage on `python:3.12-slim`: the builder installs
+  `api/requirements.txt`, the runtime copies only the installed packages
+  plus `api/` and `custom_components/nestquest/core/` into `/app`.
+- Runs as the non-root system user `nestquest` (uid/gid `999`), which owns
+  `/var/lib/nestquest`.
+- Command: `uvicorn --factory api.app:create_app --host 0.0.0.0 --port 8080`.
+
+Get the code and build:
+
+    git clone ssh://code.cubecraftlabs.com:2288/Maniacs_Mansion/NestQuest.git
+    cd NestQuest
+    git checkout <release branch or tag being deployed>
+    dc build api          # equivalent: docker build -t nestquest-api:latest .
+
+Confirm the runtime user (the Litestream sidecar and the key ownership in
+section 5 depend on uid 999):
+
+    docker run --rm --entrypoint id nestquest-api:latest
+    # uid=999(nestquest) gid=999(nestquest) groups=999(nestquest)
+
+## 2. Compose
+
+`deploy/compose.yaml` defines three services and one named volume:
+
+| Service | Image | Role |
+| --- | --- | --- |
+| `api` | `nestquest-api:latest` (built, section 1) | FastAPI service on `8080`, healthcheck on `/health` |
+| `litestream` | `litestream/litestream:0.5.17` | Continuous SFTP backup of the database (section 7); starts only once `api` is healthy |
+| `pwa` | `nestquest-pwa:latest` (built from `deploy/pwa`, section 10) | Admin PWA served by nginx on `8081`; independent of the other two |
+
+- **Volume `nestquest-db`** is mounted at `/var/lib/nestquest` in both
+  services. The database is `NESTQUEST_DB_PATH=/var/lib/nestquest/nestquest.db`
+  (fixed by compose, not a secret). `docker compose down` keeps named
+  volumes; **never run `down -v`** on the API box. Docker prefixes the
+  volume with the compose project name — with the default project
+  (`deploy`, the compose file's directory) it is `deploy_nestquest-db`;
+  confirm with `docker volume ls | grep nestquest-db`.
+- **Published port**: `${NESTQUEST_BIND_ADDRESS:-127.0.0.1}:8080:8080`.
+  The default binds localhost only, so an unconfigured host is never
+  exposed. On the API box `deploy/.env` sets
+  `NESTQUEST_BIND_ADDRESS=10.60.1.14` so Traefik on nukapi-03 can reach
+  `http://10.60.1.14:8080`.
+- **Secrets** come from `deploy/.env` (git-ignored, section 5) via
+  `env_file`.
+
+Bring the stack up (after section 5's secrets exist):
+
+    dc up -d --build
+    dc ps          # api "healthy", litestream "Up"
+    curl -s http://10.60.1.14:8080/health      # {"status":"ok"}
+
+## 3. TLS and reverse proxy (Traefik on nukapi-03)
+
+TLS is terminated by the **shared** Traefik instance on `nukapi-03`
+(`10.60.1.33`), not by this repository. Its NestQuest routing is the
+owner-authored dynamic file-provider config
+**`config/dynamic/nestquest-ccl.yml`** in the Traefik deployment on
+nukapi-03 — that live file is authoritative; it is not stored in this
+repository. What it must contain:
+
+| Router | Rule | Middleware | Service |
+| --- | --- | --- | --- |
+| `nestquest-panel` (priority 200) | ``Host(`nestquest.cubecraftlabs.com`) && PathPrefix(`/api/v1/panel`)`` | `nestquest-panel-lan`: `ipAllowList`, `sourceRange: ["10.60.1.80/32"]` (HA box only) | `nestquest-api` → `http://10.60.1.14:8080` |
+| `nestquest-admin` (priority 100: `/api/v1/admin`, `/health`, `/openapi.json`, `/docs`) | ``Host(`nestquest.cubecraftlabs.com`) && (PathPrefix(`/api/v1/admin`) \|\| Path(`/health`) \|\| Path(`/openapi.json`) \|\| PathPrefix(`/docs`))`` | `nestquest-headers` — no source restriction; the API itself enforces Authentik JWTs (section 4) | `nestquest-api` → `http://10.60.1.14:8080` |
+| `nestquest-app` (priority 50: everything else — the admin PWA) | see section 10 | none at Traefik; nginx allow-lists the proxy | `nestquest-pwa` → `http://10.60.1.14:8081` |
+
+All routers use the HTTPS entrypoint `websecure` with `tls.certResolver: myresolver`
+(HTTP is redirected to HTTPS by the shared Traefik). Priorities are set
+explicitly so the order never depends on rule length: panel (200) above
+admin (100), and the PWA's `nestquest-app` router (50) below both. The
+admin router is scoped to `/api/v1/admin`, `/health`, `/openapi.json`
+and `/docs` — a bare ``Host(...)`` rule at a higher priority would
+swallow `/` and every PWA route. Any other `/api/*` path matches no
+router (the app router excludes `/api`), so Traefik answers `404`.
+
+Reference shape, to rebuild the file if it is ever lost (entrypoint names
+must match the shared Traefik's static config on nukapi-03):
+
+```yaml
+http:
+  routers:
+    nestquest-panel:
+      rule: "Host(`nestquest.cubecraftlabs.com`) && PathPrefix(`/api/v1/panel`)"
+      priority: 200
+      entryPoints: [websecure]
+      middlewares: [nestquest-panel-lan]
+      service: nestquest-api
+      tls:
+        certResolver: myresolver
+    nestquest-admin:
+      rule: "Host(`nestquest.cubecraftlabs.com`) && (PathPrefix(`/api/v1/admin`) || Path(`/health`) || Path(`/openapi.json`) || PathPrefix(`/docs`))"
+      priority: 100
+      entryPoints: [websecure]
+      middlewares: [nestquest-headers]
+      service: nestquest-api
+      tls:
+        certResolver: myresolver
+    nestquest-app:
+      rule: "Host(`nestquest.cubecraftlabs.com`) && !PathPrefix(`/api`) && !Path(`/health`) && !Path(`/openapi.json`) && !PathPrefix(`/docs`)"
+      priority: 50
+      entryPoints: [websecure]
+      service: nestquest-pwa
+      tls:
+        certResolver: myresolver
+  middlewares:
+    nestquest-panel-lan:
+      ipAllowList:
+        sourceRange: ["10.60.1.80/32"]
+    nestquest-headers:
+      # headers middleware; copy its definition from the live file
+  services:
+    nestquest-api:
+      loadBalancer:
+        servers:
+          - url: "http://10.60.1.14:8080"
+    nestquest-pwa:
+      loadBalancer:
+        servers:
+          - url: "http://10.60.1.14:8081"
+```
+
+**Certificates.** `myresolver` is the shared Traefik's ACME (Let's
+Encrypt) resolver using the **Cloudflare DNS-01 challenge**; the
+Cloudflare API token is held by the Traefik deployment on
+nukapi-03, never in this repository. Because DNS-01 proves control
+through a DNS TXT record, issuance and renewal need no inbound HTTP and
+work regardless of the Cloudflare proxy setting. Certificates renew
+automatically.
+
+**Cloudflare proxy note.** Public traffic for
+`nestquest.cubecraftlabs.com` resolves through Cloudflare, so a request
+from the internet reaches Traefik from a Cloudflare edge address, never
+from `10.60.1.80` — which is exactly why the panel allowlist refuses it
+(403). The HA box does not go through Cloudflare at all: the local DNS
+override in section 6 sends it straight to Traefik on the LAN, so Traefik
+sees its real address. Do **not** add Cloudflare ranges to the panel
+allowlist or make the allowlist trust `X-Forwarded-For`; that would let
+any internet client through to the panel plane.
+
+## 4. Authentik (admin identity)
+
+Admin-plane requests (`/api/v1/admin/*`) carry an Authentik OIDC access
+token (JWT). The API verifies issuer, audience, RS256 signature against
+the JWKS, and expiry, then requires the `groups` claim to contain
+`nestquest-admins` (`api/auth.py`). Configure in Authentik
+(`https://auth.cubecraftlabs.com`, admin interface):
+
+1. **Provider** — *OAuth2/OpenID Provider*:
+   - Client type: **Public** (no client secret; the admin PWA is a browser
+     SPA).
+   - PKCE: the PWA always uses the authorization-code flow with PKCE,
+     `code_challenge_method=S256`, and never sends a client secret.
+   - Redirect URI (strict): `https://nestquest.cubecraftlabs.com/auth/callback`.
+   - Signing key: an **RSA** certificate (the API only accepts `RS256`).
+   - Scopes: the default `openid`, `email`, `profile` mappings (the PWA
+     requests `openid email profile`; Authentik's default `profile`
+     mapping emits the `groups` claim the API checks).
+   - Note the generated **Client ID** — it is the audience below and the
+     PWA's `VITE_AUTHENTIK_CLIENT_ID`.
+2. **Application** — slug **`nestquest`**, bound to the provider above.
+   The slug fixes the issuer URL.
+3. **Group** — **`nestquest-admins`**. Add each parent's Authentik user.
+   Membership is the single source of truth for "who is an admin"; the
+   API refuses a signed-in non-member with 403.
+
+API settings (in `deploy/.env`, section 5):
+
+| Variable | Value |
+| --- | --- |
+| `NESTQUEST_OIDC_ISSUER` | `https://auth.cubecraftlabs.com/application/o/nestquest/` |
+| `NESTQUEST_OIDC_AUDIENCE` | the provider's Client ID |
+| `NESTQUEST_OIDC_JWKS_URL` | `https://auth.cubecraftlabs.com/application/o/nestquest/jwks/` |
+
+Check them against Authentik's discovery document (the issuer must match
+byte for byte, including the trailing slash):
+
+    curl -s https://auth.cubecraftlabs.com/application/o/nestquest/.well-known/openid-configuration \
+      | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["issuer"]); print(d["jwks_uri"])'
+
+## 5. Secrets
+
+Nothing below is ever committed; `.gitignore` excludes `.env`,
+`**/.env`, `deploy/*key*` and `deploy/litestream_key*`.
+
+**`deploy/.env`** — created on the API box from the committed example:
+
+    cp deploy/.env.example deploy/.env
+    chmod 600 deploy/.env
+    # edit deploy/.env and fill in:
+    #   NESTQUEST_PANEL_TOKEN   = a new random token, e.g.
+    #                             python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+    #                             (the same value is configured in the HA integration)
+    #   NESTQUEST_OIDC_ISSUER   = section 4
+    #   NESTQUEST_OIDC_AUDIENCE = section 4 (Authentik Client ID)
+    #   NESTQUEST_OIDC_JWKS_URL = section 4
+    #   NESTQUEST_BIND_ADDRESS  = 10.60.1.14
+
+The API fails fast at startup if any of the four API
+variables is unset or empty (`api/config.py`); `dc logs api` names the
+missing one. `NESTQUEST_BIND_ADDRESS` is read by compose only.
+
+**Litestream SFTP key `deploy/litestream_key`** — a dedicated keypair that
+lives only on the API box. Create it once, before the first `up`:
+
+    ssh-keygen -t ed25519 -N "" -C nestquest-litestream -f deploy/litestream_key
+    sudo chown 999:999 deploy/litestream_key
+    chmod 600 deploy/litestream_key
+
+Then append `restrict ` followed by the contents of
+`deploy/litestream_key.pub` as one line to
+`joshua@10.60.1.50:~/.ssh/authorized_keys` on the NAS. Compose mounts the
+private key read-only at `/etc/litestream/sftp_key` in the sidecar, which
+runs as uid 999 — hence the ownership. The NAS host key is pinned in the
+committed `deploy/litestream.yml` (`host-key`, the NAS's ECDSA key), so no
+`known_hosts` is involved.
+
+| Secret | Supplied by | Consumed by |
+| --- | --- | --- |
+| `NESTQUEST_PANEL_TOKEN` | `deploy/.env` → `env_file` | `api` (panel plane); also set in the HA integration |
+| `NESTQUEST_OIDC_*` (not secret, but environment-supplied) | `deploy/.env` → `env_file` | `api` (admin plane) |
+| SFTP private key | `deploy/litestream_key` → read-only bind mount | `litestream` |
+| Cloudflare DNS API token | Traefik deployment on nukapi-03 | Traefik ACME `myresolver` |
+
+## 6. Network separation and firewall
+
+- **Panel plane** (`/api/v1/panel/*`, static service token): reachable
+  only from the HA box. Traefik's `ipAllowList` on the panel router allows
+  `10.60.1.80/32` and returns **403** to every other source, before the
+  request reaches the API. The API additionally requires the panel token
+  (401 without it).
+- **Admin plane** (`/api/v1/admin/*`) and `/health`, `/docs`: public
+  through Cloudflare and Traefik; admin routes are protected by the API's
+  Authentik JWT check (401 without a valid token, 403 without
+  `nestquest-admins` or when a panel token is presented).
+- **Local DNS override** so the HA box reaches Traefik directly, keeping
+  its real source address: in Pi-hole (`10.60.1.101`) local DNS records,
+  add `nestquest.cubecraftlabs.com` → `10.60.1.33`. The HA box
+  must use Pi-hole as its resolver. Check from the HA box:
+
+      nslookup nestquest.cubecraftlabs.com 10.60.1.101   # Address: 10.60.1.33
+
+- **Direct `:8080` access is firewalled.** The API box publishes `8080`
+  on `10.60.1.14`, which alone would let any LAN host bypass Traefik and
+  the panel `ipAllowList`. This is enforced on the API box in Docker's
+  `DOCKER-USER` chain (which Docker evaluates before its own forwarding
+  rules for published ports), in this order:
+
+      -A DOCKER-USER -s 10.60.1.33/32 -p tcp --dport 8080 -j RETURN   # Traefik on nukapi-03
+      -A DOCKER-USER -s 10.60.1.14/32 -p tcp --dport 8080 -j RETURN   # the API box itself
+      -A DOCKER-USER -p tcp --dport 8080 -j DROP                      # every other source
+
+  The rules are persisted by the systemd oneshot unit
+  **`nestquest-api-firewall.service`**, committed as
+  `deploy/systemd/nestquest-api-firewall.service` (ordered after
+  `docker.service`, it idempotently applies the three rules at every
+  boot). Install and enable it on the API box, from the repository
+  checkout, **before** exposing the API:
+
+      sudo cp deploy/systemd/nestquest-api-firewall.service /etc/systemd/system/ \
+        && sudo systemctl daemon-reload \
+        && sudo systemctl enable --now nestquest-api-firewall.service
+
+  The HA box and every other client must use the Traefik hostname,
+  never `:8080` directly. Check it:
+
+      sudo systemctl is-enabled nestquest-api-firewall.service   # enabled
+      sudo systemctl is-active nestquest-api-firewall.service    # active
+      sudo iptables -S DOCKER-USER                               # the three rules above, in that order
+
+      # on nukapi-03 (10.60.1.33) — allowed:
+      curl -s -o /dev/null -w '%{http_code}\n' http://10.60.1.14:8080/health   # 200
+      # on any other LAN host, e.g. 10.60.1.101 — dropped:
+      curl -s -m 5 -o /dev/null -w '%{http_code}\n' http://10.60.1.14:8080/health   # 000, timeout
+      # public path still works:
+      curl -s -o /dev/null -w '%{http_code}\n' https://nestquest.cubecraftlabs.com/health   # 200
+
+  On a rebuilt API box, install the unit with the commands above before
+  exposing the API. The committed file is the authoritative copy; the
+  deployed unit must match it:
+
+      diff deploy/systemd/nestquest-api-firewall.service \
+        /etc/systemd/system/nestquest-api-firewall.service   # no output
+
+## 7. Backup (Litestream to the Synology NAS)
+
+The `litestream` sidecar (config `deploy/litestream.yml`, mounted at
+`/etc/litestream.yml`) replicates `/var/lib/nestquest/nestquest.db` to:
+
+- SFTP `joshua@10.60.1.50`, path `/homes/Joshua/nestquest-backups` (the
+  NAS's SFTP view is chrooted to the shared folders; over SSH the same
+  directory is `/volume1/homes/Joshua/nestquest-backups`).
+- Every committed change is shipped as an LTX file within about a second.
+  Litestream 0.5.17 compacts them into coarser levels on its built-in
+  schedule (level 1 every 30s, level 2 every 5m, level 3 every 1h).
+- **Snapshots**: `snapshot.interval: 24h` (a full snapshot daily);
+  **retention**: `snapshot.retention: 168h` — a week of snapshots plus the
+  changes between them, i.e. a 7-day point-in-time restore window.
+
+The sidecar runs as uid 999 with a read-only root filesystem,
+`no-new-privileges` and all capabilities dropped. It needs the database
+volume read-write (it keeps its `_litestream_*` tables and writes the
+WAL); its local state lives beside the database in
+`/var/lib/nestquest/.nestquest.db-litestream/`.
+
+Check it:
+
+    dc ps litestream                                           # Up
+    dc logs --tail 50 litestream                               # no "error" lines
+    dc exec litestream litestream status                       # status "ok", local txid advancing
+    dc exec litestream litestream ltx /var/lib/nestquest/nestquest.db | tail   # newest LTX files and timestamps
+
+A change made in the app should appear as a new level-0 LTX file within
+seconds. On the NAS, the files are under
+`/volume1/homes/Joshua/nestquest-backups/ltx/`.
+
+## 8. Restore
+
+Restores the database from the SFTP replica into the `nestquest-db`
+volume at `NESTQUEST_DB_PATH` (`/var/lib/nestquest/nestquest.db`). The
+same procedure serves both a damaged database on the existing box and a
+rebuilt box. The restore runs in one-off `litestream` containers so it
+has the same user (999), volume, config and SFTP key as the sidecar.
+
+**0. Fresh box only.** Complete sections 1 and 5, then start **only the
+API** once so the volume exists and is owned by uid 999:
+
+    dc up -d api
+
+Do not start `litestream` yet — it would begin replicating the new,
+empty database the API just created. The swap in step 4 moves that empty
+file aside, and step 5 creates and starts the sidecar with
+`dc up -d litestream` once the API is healthy.
+
+**1. Stop writers** — both the API and the sidecar (Litestream must not
+replicate while the file is being replaced):
+
+    dc stop api litestream
+
+**2. Restore beside the live database** (never over it), with a full
+integrity check:
+
+    dc run --rm --no-deps litestream restore \
+      -config /etc/litestream.yml \
+      -integrity-check full \
+      -o /var/lib/nestquest/nestquest.db.restored \
+      /var/lib/nestquest/nestquest.db
+
+Expect `post-restore integrity check passed` and exit code 0. For a
+point in time within the retention window, add
+`-timestamp 2026-09-24T12:00:00Z` (UTC). To preview without writing, add
+`-dry-run`.
+
+**3. Inspect the restored file** before switching to it — confirm known
+children and definitions are present:
+
+    dc run --rm --no-deps --entrypoint sqlite3 litestream \
+      /var/lib/nestquest/nestquest.db.restored \
+      'PRAGMA integrity_check;' \
+      'SELECT id, display_name FROM children;' \
+      'SELECT id, title FROM quest_definitions;'
+
+Expect `ok`, then the household's children and quest definitions.
+
+**4. Swap it into place**, keeping the old files (database, its
+`-wal`/`-shm`, and Litestream's local state) in a timestamped directory
+on the volume:
+
+    dc run --rm --no-deps --entrypoint sh litestream -c '
+      set -e
+      cd /var/lib/nestquest
+      ts=$(date -u +%Y%m%dT%H%M%SZ)
+      mkdir -p "pre-restore-$ts"
+      for f in nestquest.db nestquest.db-wal nestquest.db-shm .nestquest.db-litestream; do
+        if [ -e "$f" ]; then mv "$f" "pre-restore-$ts/"; fi
+      done
+      mv nestquest.db.restored nestquest.db
+      ls -la'
+
+**5. Start the API, then the sidecar:**
+
+    dc start api
+    dc ps api            # wait for "healthy"
+    dc up -d litestream
+    dc ps litestream     # Up
+    dc logs --tail 20 litestream
+
+Use `dc up -d litestream`, not `dc start`: on a fresh box step 0 never
+created the sidecar container, and `start` cannot start a container that
+does not exist. `up -d` creates it if needed (or starts the existing one),
+so continuous replication is back online on both paths.
+
+The sidecar resumes replication from the restored position (it logs
+`detected database behind replica` / `fetched latest L0 file from
+replica`, then continues normally).
+
+**6. Verify through the API** — the panel snapshot lists the restored
+children. On the API box against `10.60.1.14:8080` directly (other LAN
+hosts, including the HA box, are dropped on `:8080` by the section 6
+firewall; from the HA box use the Traefik hostname instead):
+
+    PANEL_TOKEN=$(grep '^NESTQUEST_PANEL_TOKEN=' deploy/.env | cut -d= -f2-)
+    curl -s -H "Authorization: Bearer $PANEL_TOKEN" \
+      http://10.60.1.14:8080/api/v1/panel/snapshot
+
+Expect HTTP 200 and `children` naming the known child(ren). Then run
+section 9.
+
+Once satisfied, remove the old copy:
+`dc run --rm --no-deps --entrypoint rm litestream -rf /var/lib/nestquest/pre-restore-<ts>`.
+
+This exact sequence (stop, restore with integrity check, inspect, swap,
+start, snapshot shows the restored child, replication resumes) was
+rehearsed against a local file replica with the committed compose file;
+the live proof against the SFTP replica is recorded separately by the
+controller.
+
+## 9. Verification checklist
+
+Run after every deploy and every restore. `$PANEL_TOKEN` is the value from
+`deploy/.env`; never paste it into shared logs.
+
+| # | Check | Command | Expect |
+| --- | --- | --- | --- |
+| 1 | Health over TLS | `curl -s -o /dev/null -w '%{http_code}\n' https://nestquest.cubecraftlabs.com/health` | `200` |
+| 2 | Valid certificate | `curl -sv https://nestquest.cubecraftlabs.com/health 2>&1 \| grep -E 'issuer\|expire date'` | Let's Encrypt issuer, future expiry (no `-k` needed) |
+| 3 | Docs public | `curl -s -o /dev/null -w '%{http_code}\n' https://nestquest.cubecraftlabs.com/docs` | `200` |
+| 4 | Panel refused externally | from any host other than `10.60.1.80` (e.g. a phone off Wi-Fi, or a LAN machine): `curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $PANEL_TOKEN" https://nestquest.cubecraftlabs.com/api/v1/panel/snapshot` | `403` (Traefik allowlist) |
+| 5 | Panel allowed from HA box | on `10.60.1.80`: same command | `200`, snapshot JSON |
+| 6 | Panel needs the token | on `10.60.1.80`, without the header | `401` |
+| 7 | Admin JWT accepted | `curl -s -w '\n%{http_code}\n' -H "Authorization: Bearer $ADMIN_JWT" https://nestquest.cubecraftlabs.com/api/v1/admin/ping` with a token of a `nestquest-admins` member | `200`, `{"status":"ok","sub":...}` |
+| 8 | Non-admin refused | same, with a token of a user **not** in `nestquest-admins` | `403`, "Admin access requires membership in the nestquest-admins group" |
+| 9 | No/invalid token refused | same, without a header or with garbage | `401` |
+| 10 | Panel token refused on admin | same, with `$PANEL_TOKEN` | `403` |
+| 11 | Backup running | `dc exec litestream litestream status` | status `ok` |
+
+To obtain `$ADMIN_JWT`: sign in to the admin PWA as the user, open the
+browser developer tools, and copy the session-storage value
+`nestquest.access_token`. Tokens are short-lived and are credentials —
+do not store them.
+
+## 10. Admin PWA hosting
+
+The admin PWA (`admin/`, a Vite + React single-page app) is served from
+the API box by the compose service **`pwa`**: nginx on container port
+`80`, published on `${NESTQUEST_BIND_ADDRESS:-127.0.0.1}:8081` (on the API
+box `10.60.1.14:8081`). Traefik sends every path of
+`nestquest.cubecraftlabs.com` that is not the API to it.
+
+**Image** — `deploy/pwa/Dockerfile`, built from the **repository root**
+(it needs `admin/`); `deploy/pwa/Dockerfile.dockerignore` limits the
+context to `admin/` (without `node_modules`, `dist` or `.env` files) and
+`deploy/pwa/nginx.conf`.
+
+- Stage 1, `node:22-alpine` (pinned by digest): `npm ci`, then
+  `npm run build` with the three `VITE_*` build args below. Vite bakes
+  them into the bundle, so **changing any of them needs a rebuild**. The
+  build fails if any is empty.
+- Stage 2, `nginx:alpine` pinned to
+  `sha256:1ed1b0e1d7652937d6cbdaf4018c7b6fc009a7dd6c3047351e2eddda745de43f`
+  (nginx 1.31.6): the built `dist/` in `/usr/share/nginx/html` and
+  `deploy/pwa/nginx.conf` as `conf.d/default.conf`.
+
+**Build args** — compose reads them from `deploy/.env` (documented in
+`deploy/.env.example`). They are **public values, not secrets**: the
+Authentik application is a PKCE client with no client secret.
+
+| `deploy/.env` variable | Build arg | Production value |
+| --- | --- | --- |
+| `NESTQUEST_AUTHENTIK_CLIENT_ID` | `VITE_AUTHENTIK_CLIENT_ID` | client id of the Authentik NestQuest application (Authentik admin → Applications → Providers) |
+| `NESTQUEST_AUTHENTIK_ISSUER` | `VITE_AUTHENTIK_ISSUER` | `https://auth.cubecraftlabs.com/application/o/nestquest/` |
+| `NESTQUEST_API_BASE_URL` | `VITE_API_BASE_URL` | `https://nestquest.cubecraftlabs.com` |
+
+The Authentik application's redirect URI must include
+`https://nestquest.cubecraftlabs.com/auth/callback`.
+
+**nginx** (`deploy/pwa/nginx.conf`):
+
+- `allow 10.60.1.33; allow 10.60.1.14; deny all;` — only Traefik on
+  nukapi-03 and the API box itself get content; any other source gets
+  `403`, even with the port reachable on the LAN. Checks run on the API
+  box must use its LAN address (`10.60.1.14:8081`), not `127.0.0.1`.
+- SPA fallback: unknown paths (e.g. `/auth/callback`) serve `index.html`;
+  `/assets/*` (content-hashed, cached for a year) returns a real `404`
+  when missing.
+- `/sw.js` and `/manifest.webmanifest` (`application/manifest+json`) are
+  served from the site root with `Cache-Control: no-cache`, as is
+  `index.html`, so a new release's service worker is picked up.
+
+Build and start (the `api` and `litestream` services are unaffected):
+
+    dc build pwa
+    dc up -d pwa
+    dc ps pwa      # "Up"
+
+**Traefik router** — in `config/dynamic/nestquest-ccl.yml` on nukapi-03
+(reference shape in section 3):
+
+| Router | Rule | Priority | Service |
+| --- | --- | --- | --- |
+| `nestquest-app` | ``Host(`nestquest.cubecraftlabs.com`) && !PathPrefix(`/api`) && !Path(`/health`) && !Path(`/openapi.json`) && !PathPrefix(`/docs`)`` | `50` — below `nestquest-admin` (100) and `nestquest-panel` (200) | `nestquest-pwa` → `http://10.60.1.14:8081` |
+
+Same `websecure` entrypoint and `myresolver` certificate as the API
+routers; no Traefik middleware (nginx enforces the source allow-list).
+The file provider reloads the dynamic file on save.
+
+**Verification** (in addition to section 9):
+
+| # | Check | Command | Expect |
+| --- | --- | --- | --- |
+| 1 | PWA root over TLS | `curl -s -w '\n%{http_code}\n' https://nestquest.cubecraftlabs.com/ \| tail -3` | `200`, the `NestQuest Admin` shell |
+| 2 | Client route fallback | `curl -s -o /dev/null -w '%{http_code} %{content_type}\n' https://nestquest.cubecraftlabs.com/auth/callback` | `200 text/html` |
+| 3 | Manifest and worker | `curl -s -o /dev/null -w '%{http_code} %{content_type}\n' https://nestquest.cubecraftlabs.com/manifest.webmanifest` and the same for `/sw.js` | `200 application/manifest+json`, `200 application/javascript` |
+| 4 | API still routed to the API | `curl -s -o /dev/null -w '%{http_code}\n' https://nestquest.cubecraftlabs.com/health` | `200` (`{"status":"ok"}`, not HTML) |
+| 5 | Panel refused externally | section 9 check 4 | `403` |
+| 6 | Non-Traefik source refused | from a LAN machine other than `10.60.1.33`/`10.60.1.14`: `curl -s -o /dev/null -w '%{http_code}\n' http://10.60.1.14:8081/` | `403` (nginx `deny all`) |
+| 7 | Proxy source allowed | on `10.60.1.14`: `curl -s -o /dev/null -w '%{http_code}\n' http://10.60.1.14:8081/` | `200` |
+
+## 11. Upgrades and rollback
+
+The API applies pending schema migrations when it starts (FastAPI
+lifespan, before `/health` answers), so **the first start of a new
+version is the point of no return** for any migration it carries. A
+build refuses a database whose schema version is newer than it
+understands ("newer than this integration understands … downgrades are
+not supported") and does not start.
+
+### Migration 9 (multiple presence patterns)
+
+Migration 9 creates `presence_patterns`, copies every row of the old
+one-per-child `presence_schedules` table into it as a `home` pattern
+named `Home schedule`, and **drops `presence_schedules`**. Version 0.7.1
+refuses the resulting version-9 database, and could not read
+`presence_patterns` anyway, so the only way back to 0.7.1 is a copy of
+the database taken **before** the first start on the new version.
+
+**Before the first start on the new version**, with the old version
+still deployed:
+
+1. Stop writers (as section 8 step 1):
+
+       dc stop api litestream
+
+2. Copy the database file beside the live one with SQLite's online
+   backup (includes anything still in the WAL), then check it:
+
+       ts=$(date -u +%Y%m%dT%H%M%SZ)
+       dc run --rm --no-deps --entrypoint sqlite3 litestream \
+         /var/lib/nestquest/nestquest.db \
+         ".backup /var/lib/nestquest/pre-v9-$ts.db"
+       dc run --rm --no-deps --entrypoint sqlite3 litestream \
+         /var/lib/nestquest/pre-v9-$ts.db \
+         'PRAGMA integrity_check;' \
+         'SELECT version FROM nestquest_schema_version;' \
+         'SELECT count(*) FROM presence_schedules;'
+
+   Expect `ok`, schema version `8`, and the number of presence
+   schedules. Write down `$ts`.
+
+3. Also record the Litestream replica position and the UTC time, so a
+   point-in-time restore (section 8, `-timestamp`) can reach the
+   pre-upgrade state even if the local copy is lost:
+
+       dc up -d litestream
+       dc exec litestream litestream status      # note the txid
+       date -u +%Y-%m-%dT%H:%M:%SZ               # note the time
+       dc stop litestream
+
+   The replica only covers the 7-day retention window (section 7).
+
+4. Deploy the new version (sections 1–2) and run section 9. Confirm the
+   live database is at version `9` (the section 8 step 3 `sqlite3`
+   command against `nestquest.db`, with
+   `'SELECT version FROM nestquest_schema_version;'`) and that the
+   Schedule tab lists each child's old schedule as a `Home schedule`
+   pattern.
+
+**Rollback to 0.7.1:** check out and build 0.7.1 (section 1), then put
+the pre-upgrade database back with section 8: either steps 1 and 4–6
+with `pre-v9-<ts>.db` in place of `nestquest.db.restored`, or the full
+restore with `-timestamp` set to the time noted in step 3. Presence
+pattern changes made after the upgrade are not in that copy and are
+lost. Once the new version has proven itself, remove the copy:
+`dc run --rm --no-deps --entrypoint rm litestream -f /var/lib/nestquest/pre-v9-<ts>.db`.
+
+This rollback has not yet been rehearsed.

deploy/compose.yaml

@@ -0,0 +1,98 @@
+# Compose deployment scaffold for the NestQuest API service (Feature
+# 17).  The SQLite database lives on the NAMED VOLUME ``nestquest-db``
+# mounted at /var/lib/nestquest — recreating the container keeps the
+# household data (``docker compose down`` leaves named volumes alone).
+#
+# Configuration is supplied by the environment: the fixed database
+# path here, and the secret values (panel service token, Authentik
+# OIDC settings) from ``deploy/.env`` — a git-ignored file you create
+# from ``deploy/.env.example`` (placeholder names only; never commit
+# real values).
+#
+# TLS is terminated by the shared Traefik reverse proxy on another
+# host, which forwards to this service on port 8080.  The published
+# port binds NESTQUEST_BIND_ADDRESS (read from deploy/.env, the
+# project directory's env file): it defaults to 127.0.0.1 so an
+# unconfigured deployment is never exposed; set it to the host's LAN
+# address on the API box so the proxy can reach it.
+services:
+  api:
+    build:
+      context: ..
+      dockerfile: Dockerfile
+    image: nestquest-api:latest
+    init: true
+    restart: unless-stopped
+    ports:
+      - "${NESTQUEST_BIND_ADDRESS:-127.0.0.1}:8080:8080"
+    environment:
+      # The SQLite file inside the named volume; fixed, not a secret.
+      NESTQUEST_DB_PATH: /var/lib/nestquest/nestquest.db
+    env_file:
+      # Secret values (NESTQUEST_PANEL_TOKEN, NESTQUEST_OIDC_*); absent
+      # until you create deploy/.env from the example.
+      - path: .env
+        required: false
+    volumes:
+      - nestquest-db:/var/lib/nestquest
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health')"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+  # Admin PWA (Feature 24): the Vite bundle from admin/ served by nginx
+  # (deploy/pwa/).  Traefik routes every non-API path of the public host
+  # here on port 8081; nginx itself only accepts the proxy (10.60.1.33)
+  # and this host (10.60.1.14).  The three build args are PUBLIC values
+  # (the OIDC client is a PKCE client, no secret) read from deploy/.env
+  # by compose interpolation; the image build fails if any is empty.
+  pwa:
+    build:
+      context: ..
+      dockerfile: deploy/pwa/Dockerfile
+      args:
+        VITE_AUTHENTIK_CLIENT_ID: ${NESTQUEST_AUTHENTIK_CLIENT_ID:-}
+        VITE_AUTHENTIK_ISSUER: ${NESTQUEST_AUTHENTIK_ISSUER:-}
+        VITE_API_BASE_URL: ${NESTQUEST_API_BASE_URL:-}
+    image: nestquest-pwa:latest
+    restart: unless-stopped
+    ports:
+      - "${NESTQUEST_BIND_ADDRESS:-127.0.0.1}:8081:80"
+
+  # Continuous backup: streams the SQLite database on the shared named
+  # volume to the Synology NAS over SFTP (config: deploy/litestream.yml).
+  # The SFTP private key deploy/litestream_key is git-ignored and must be
+  # created on the API box before starting (see api/README.md).
+  #
+  # The database volume is mounted READ-WRITE on purpose: Litestream
+  # cannot run against a read-only mount ("unable to open database file
+  # (14)", even with its metadata moved elsewhere) because it writes its
+  # _litestream_seq/_litestream_lock tables into the database, opens the
+  # -wal/-shm files for writing, and checkpoints the WAL.  The write
+  # access is contained instead: it runs as the API's own non-root user
+  # (uid/gid 999, owner of the volume) with a read-only root filesystem,
+  # no privilege escalation and no Linux capabilities.
+  litestream:
+    image: litestream/litestream:0.5.17@sha256:4b02b9859a6b6b4087d8b8944e15f7e984bd7957cba322bbeee38b0e27b9656a
+    restart: unless-stopped
+    command: ["replicate", "-config", "/etc/litestream.yml"]
+    user: "999:999"
+    read_only: true
+    tmpfs:
+      - /tmp
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    depends_on:
+      api:
+        condition: service_healthy
+    volumes:
+      - nestquest-db:/var/lib/nestquest
+      - ./litestream.yml:/etc/litestream.yml:ro
+      - ./litestream_key:/etc/litestream/sftp_key:ro
+
+volumes:
+  nestquest-db:

deploy/litestream.yml

@@ -0,0 +1,32 @@
+# Litestream continuous backup of the NestQuest SQLite database (Feature
+# 17).  The ``litestream`` compose service mounts the same named volume
+# as the API and streams every committed change to the Synology NAS
+# over SFTP, so the backup lives OUTSIDE the container's volume.
+#
+# Nothing here is secret.  The SFTP private key is a dedicated,
+# git-ignored keypair (deploy/litestream_key) mounted read-only by
+# compose at /etc/litestream/sftp_key; its public half is in
+# joshua@10.60.1.50:~/.ssh/authorized_keys.  ``host-key`` pins the
+# NAS's host key so the connection is verified; it must be the ECDSA
+# key, because that is the algorithm Litestream's SSH client negotiates
+# with this NAS (pinning the ed25519 key fails with "host key mismatch").
+#
+# The Synology SFTP server is chrooted to the shared folders, so the
+# directory seen over SSH as /volume1/homes/Joshua/nestquest-backups is
+# /homes/Joshua/nestquest-backups over SFTP.
+
+# Take a full snapshot daily and keep a week of snapshots plus the
+# incremental changes between them (point-in-time restore window).
+snapshot:
+  interval: 24h
+  retention: 168h
+
+dbs:
+  - path: /var/lib/nestquest/nestquest.db
+    replicas:
+      - type: sftp
+        host: 10.60.1.50
+        user: joshua
+        path: /homes/Joshua/nestquest-backups
+        key-path: /etc/litestream/sftp_key
+        host-key: ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBNujay9nYEiXuRQf4wDRDU1gp+CDvpeMdhuhC2XypIihzKGEtB654kwrUGfA2kDWAoSPGlmojeS3OIRtHPkj6GY=

deploy/pwa/Dockerfile

@@ -0,0 +1,29 @@
+# Admin PWA image (Feature 24): builds the Vite bundle from admin/ and
+# serves it with nginx.  Build context is the REPOSITORY ROOT (it needs
+# admin/); deploy/pwa/Dockerfile.dockerignore limits that context to
+# admin/ and this directory's nginx.conf.
+#
+#   docker compose -f deploy/compose.yaml build pwa
+#
+# The VITE_* values are baked into the bundle at build time.  None is a
+# secret (the OIDC client is a public PKCE client), and all three are
+# required: the build fails fast rather than relying on app defaults.
+
+FROM node:22-alpine@sha256:0a7108bf6c7bf5de370ffb1a3ed6be93d405b43ff159f681a8d18c0e2bc2e402 AS build
+
+ARG VITE_AUTHENTIK_CLIENT_ID
+ARG VITE_AUTHENTIK_ISSUER
+ARG VITE_API_BASE_URL
+
+WORKDIR /src/admin
+COPY admin/package.json admin/package-lock.json ./
+RUN npm ci
+COPY admin/ ./
+RUN test -n "$VITE_AUTHENTIK_CLIENT_ID" && test -n "$VITE_AUTHENTIK_ISSUER" && test -n "$VITE_API_BASE_URL" \
+    || { echo "VITE_AUTHENTIK_CLIENT_ID, VITE_AUTHENTIK_ISSUER and VITE_API_BASE_URL build args are required" >&2; exit 1; }
+RUN npm run build
+
+FROM nginx:alpine@sha256:1ed1b0e1d7652937d6cbdaf4018c7b6fc009a7dd6c3047351e2eddda745de43f
+
+COPY deploy/pwa/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /src/admin/dist/ /usr/share/nginx/html/

deploy/pwa/Dockerfile.dockerignore

@@ -0,0 +1,11 @@
+# Build-context filter for deploy/pwa/Dockerfile (BuildKit reads
+# <Dockerfile>.dockerignore in place of the root .dockerignore, which
+# excludes deploy/).  Only admin/ sources and nginx.conf enter the
+# build; local dependencies, build output and .env files never do.
+*
+!admin/
+!deploy/pwa/nginx.conf
+admin/node_modules
+admin/dist
+**/.env
+**/.env.*

deploy/pwa/nginx.conf

@@ -0,0 +1,53 @@
+# nginx server for the NestQuest admin PWA (Feature 24).  Replaces the
+# image's /etc/nginx/conf.d/default.conf.  The shared Traefik on
+# nukapi-03 (10.60.1.33) terminates TLS for nestquest.cubecraftlabs.com
+# and forwards every path that is not the API (/api, /health,
+# /openapi.json, /docs) here; see deploy/RUNBOOK.md section 10.
+server {
+    listen 80;
+    server_name _;
+
+    # Only the reverse proxy and the API box itself may connect; every
+    # other source is refused (403) even if the port is reachable.
+    allow 10.60.1.33;
+    allow 10.60.1.14;
+    deny all;
+
+    root /usr/share/nginx/html;
+    index index.html;
+    server_tokens off;
+
+    # Content-hashed bundle files: cache forever, and a missing asset is
+    # a real 404 rather than the SPA shell.
+    location /assets/ {
+        try_files $uri =404;
+        add_header Cache-Control "public, max-age=31536000, immutable";
+    }
+
+    # The service worker must be revalidated on every load so a new
+    # release's worker (fresh revision, see admin/vite-sw-plugin.ts) is
+    # picked up.
+    location = /sw.js {
+        try_files $uri =404;
+        add_header Cache-Control "no-cache";
+    }
+
+    # nginx's stock mime.types has no .webmanifest entry.
+    location = /manifest.webmanifest {
+        types { }
+        default_type application/manifest+json;
+        try_files $uri =404;
+        add_header Cache-Control "no-cache";
+    }
+
+    # SPA fallback: client routes such as /auth/callback resolve to the
+    # app shell, which is never cached so it always names the current
+    # hashed assets.
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    location = /index.html {
+        add_header Cache-Control "no-cache";
+    }
+}

deploy/systemd/nestquest-api-firewall.service

@@ -0,0 +1,12 @@
+[Unit]
+Description=Restrict NestQuest API port 8080 to Traefik (DOCKER-USER)
+After=docker.service
+Requires=docker.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/bin/sh -c "iptables -C DOCKER-USER -s 10.60.1.33/32 -p tcp --dport 8080 -j RETURN 2>/dev/null || iptables -I DOCKER-USER 1 -s 10.60.1.33 -p tcp --dport 8080 -j RETURN; iptables -C DOCKER-USER -s 10.60.1.14/32 -p tcp --dport 8080 -j RETURN 2>/dev/null || iptables -I DOCKER-USER 2 -s 10.60.1.14 -p tcp --dport 8080 -j RETURN; iptables -C DOCKER-USER -p tcp --dport 8080 -j DROP 2>/dev/null || iptables -A DOCKER-USER -p tcp --dport 8080 -j DROP"
+
+[Install]
+WantedBy=multi-user.target

design/ADMIN-SPEC.md

@@ -37,7 +37,7 @@ One card, rows divided by `--nq-a-divider`, row padding 11px 13px:
 meta 11px/600 (`3 of 7 · 1 overdue`; all-done in `--nq-a-success`; away reads
 `Away · returns <Mon D>`) · 82×6px progress track with gradient fill. An away child's
 avatar is flat `#9898A8` and the row carries a lowercase `override` pill when the absence
-comes from a presence override rather than the pattern.
+comes from a presence override rather than a presence pattern.
 
 ### 2.4 Roomy variant (1h)
 Header becomes a hero: kicker 11px/700 uppercase, `8 of 12 done` 32px/800, 10px gradient
@@ -84,24 +84,84 @@ Footer: `Cancel` (flex 1, bordered) + `Save changes` (flex 2, gradient), both 13
 padding. Sheet enters over the dimmed list in `--nq-dur-modal`.
 
 ### 3.3 Icon picker
-Each definition carries a Lucide glyph, shown on both surfaces. **The allowed subset is not
-yet defined** — pick 24–40 household-relevant glyphs and ship them as a grid picker.
+Each definition carries one optional icon, shown on both surfaces. The picker offers three
+sources:
+
+- **Lucide** — a grid of the curated Lucide glyphs, drawn stroked.
+- **Font Awesome** — a grid of a curated subset of the Font Awesome Free *solid* set,
+  drawn filled.
+- **Emoji** — a text input; the typed emoji is stored as entered (not trimmed) and must be
+  1–8 code points with no whitespace, control characters, `<`, `>` or `&`.
+
+Both curated lists come from `tools/icons/curated-icons.json`; their glyph path data is
+generated into the admin and panel bundles by `tools/icons/generate.mjs` (no CDN, no
+runtime fetch). See `THIRD-PARTY-NOTICES.md` for licences.
+
+The stored value is a **namespaced key**:
+
+| Source | Stored key | Example |
+|---|---|---|
+| Lucide | `lucide:<name>` | `lucide:dog` |
+| Font Awesome | `fa:<name>` | `fa:paw` |
+| Emoji | `emoji:<grapheme>` | `emoji:🐶` |
+
+`<name>` is a lowercase kebab name (`[a-z0-9-]`, no leading or trailing `-`). A **legacy
+bare name** written before namespacing (`dog`) reads as `lucide:<name>` — the API returns it
+namespaced, and any write of a bare name is stored as `lucide:<name>`; no data migration. An
+empty value clears the icon. An empty, unknown, or unresolvable key renders the **fallback
+glyph** — in the admin, the generic task glyph (clipboard with a check); on the panel, the
+star (`PANEL-SPEC.md` §3.2).
 
 ## 4. Schedule (1f)
 
-- Header `Schedule` / `2-week cycle · anchor <weekday>, <Mon D>`.
+A child has **zero or more** presence patterns (schema 9). Each pattern has a name, a
+kind (`Home` or `Away`), its own cycle length (1–4 weeks), its own anchor date, and a
+weekday set per cycle week. The screen shows one child at a time.
+
+- Header `Schedule` / `<Child> · N patterns` (`<Child> · no patterns, home every day`
+  when the child has none).
+- **Child** chip row: one chip per child; the selected chip drives everything below.
 - **Month grid** card: month label 11px/700 uppercase + chevron pair; weekday initials
-  10px/700 `--nq-a-ink-tertiary`; day cells `aspect-ratio: 1`, radius 6px —
-  rotation-home days `--nq-a-selected` with `#201F7A` numerals, away days
-  `--nq-a-page` with `--nq-a-ink-secondary`, override days `--nq-a-warning-bg` with
-  `--nq-a-warning-ink` and a 1px warning border, today filled with the brand gradient in
-  white 800. Legend row beneath, 10.5px/600, one swatch per state.
-- **Presence pattern** card: one row per child, name 13px/700 + rule 12px/600
-  (`Weeks 1 & 3 of cycle`, `Every day`).
+  10px/700 `--nq-a-ink-tertiary`, **Sunday first** (`S M T W T F S`); day cells
+  `aspect-ratio: 1`, radius 6px — home days `--nq-a-selected` with `#201F7A` numerals,
+  away days `--nq-a-page` with `--nq-a-ink-secondary`, override days
+  `--nq-a-warning-bg` with `--nq-a-warning-ink` and a 1px warning border, today filled
+  with the brand gradient in white 800. Legend row beneath, 10.5px/600, one swatch per
+  state (`Home`, `Away`, `Override · away`, `Override · home`, `Today`), then the note
+  "Combined from every pattern: away beats home; overrides beat both."
+- The grid shows the child's **combined** presence, first match wins: an override
+  covering the date; else away if any Away pattern covers it; else home if any Home
+  pattern covers it; else away when the child has at least one Home pattern (a Home
+  pattern lists the days the child is here); else home (only Away patterns, or none).
+- **Presence patterns** card: `Add` text action; one row per pattern with
+  `calendar-check` (Home) / `calendar-x` (Away), title = pattern name 13px/700, meta
+  `Home · Every 2 weeks` 12px/600, and the weekday set (`Thu, Fri` for a 1-week cycle,
+  otherwise `Week 1: Sat, Sun · Week 2: No days`). Trailing `pencil` opens the pattern
+  editor (§4.1); trailing `trash-2` asks `Delete pattern?` inline before deleting. With
+  no patterns the card reads "No patterns for <Child> — home every day."
 - **Overrides** card: `Add` text action; rows with `calendar-x` / `calendar-check`,
   title `<Child> away · <Mon D – D>`, meta reason, trailing `trash-2`.
-- Cycle position is always computed from the anchor date. **Never** from ISO week numbers
-  or week parity (D-004).
+- Cycle position is always computed from each pattern's own anchor date. **Never** from
+  ISO week numbers or week parity (D-004).
+- Weekday numbering on the wire stays **Monday=0 .. Sunday=6**; Sunday-first is display
+  order only.
+
+### 4.1 Pattern editor
+
+Pushed screen with a back chevron; title `New pattern` / `Edit pattern`, sub "Repeating
+presence for <Child>". Form card fields:
+
+- **Name** text field (required, not blank).
+- **Covered days are** 2-up segmented (`Away` / `Home`), selected = `#18181D`.
+- **Cycle length** select (`1 week` … `4 weeks`) and **Anchor date** side by side.
+  Changing the cycle length keeps existing weeks and adds new weeks covering no day.
+- One **weekday picker** per cycle week, labelled `Week N · from <Mon D>` (the date is
+  anchor + (N−1) weeks): seven toggle cells in **Sunday-first** order
+  (`Su Mo Tu We Th Fr Sa`). A week may cover no day.
+
+Footer: `Cancel` (flex 1, white, bordered) + `Save pattern` (flex 2, gradient), as the
+override editor (§6). Save stays disabled until the name is set, the anchor is a valid
+date, and something changed.
 
 ## 5. History (1g)
 

design/DESIGN-HANDOFF.md

@@ -78,5 +78,6 @@ The panel speaks tabletop; the admin speaks plainly. Both sit on the same `quest
   decide before shipping the card.
 - No gamification is in scope. XP, levels, streaks and rarity were explicitly deferred,
   but the append-only event log already supports computing them later.
-- Icon per quest definition is chosen by the parent from a Lucide subset; the subset is
-  not yet defined (`ADMIN-SPEC.md` §3.3).
+- Icon per quest definition is chosen by the parent from curated Lucide and Font Awesome
+  Free sets or as an emoji, stored as a namespaced key (`lucide:`/`fa:`/`emoji:`) —
+  resolved 2026-09-26, see `ADMIN-SPEC.md` §3.3.

design/ENTITIES-AND-SERVICES.md

@@ -19,6 +19,14 @@ Planned surface from CTXD CONTEXT.MD, adjusted for the design decisions in
 | `sensor.nestquest_cycle_day` | int | 1d sub-line, 1f header |
 | *configured* `weather.<entity>` | HA core | panel dock |
 
+`present_today` is the child's **combined** presence across all of their presence patterns
+(a child has zero or more, each `home` or `away`) and overrides, first match wins: an
+override covering the date; else absent if any `away` pattern covers it; else present if
+any `home` pattern covers it; else absent when the child has at least one `home` pattern;
+else present. `cycle_day` is the 1-based day in the first patterned child's lowest-id
+pattern, from that pattern's anchor date (never ISO week numbers or parity); `0` when no
+child has a pattern.
+
 Per-instance data is too granular for entity state. The cards read the day's instance list
 from an attribute payload on the per-child sensor (or a websocket command —
 implementer's call), shaped:
@@ -27,7 +35,7 @@ implementer's call), shaped:
 {
   "instances": [
     { "id": 4821, "definition_id": 12, "child_id": 3, "title": "Fill bird feeder",
-      "icon": "bird", "window": "afternoon", "due_time": "17:00",
+      "icon": "lucide:bird", "window": "afternoon", "due_time": "17:00",
       "state": "open", "overdue": true, "completed_at": null, "on_time": null }
   ]
 }
@@ -45,12 +53,17 @@ implementer's call), shaped:
 | `nestquest.create_quest_definition` | **yes** | 1e `New` |
 | `nestquest.update_quest_definition` | **yes** | 1e sheet `Save changes` |
 | `nestquest.set_quest_definition_active` | **yes** | 1e row action |
-| `nestquest.set_presence_pattern` | **yes** | 1f presence card |
 | `nestquest.create_presence_override` | **yes** | 1i `Save override` |
 | `nestquest.delete_presence_override` | **yes** | 1f override row `trash-2` |
 | `nestquest.export_history_csv` | **yes** | 1g `CSV` |
 | `nestquest.manage_child` | **yes** | settings |
 
+Presence patterns have no HA service: the admin surface is the PWA (ARCHITECTURE §10),
+which manages a child's patterns through the admin API —
+`GET`/`POST /api/v1/admin/children/{child_id}/presence-patterns` to list and add, and
+`PATCH`/`DELETE /api/v1/admin/presence-patterns/{pattern_id}` to edit and delete one
+pattern (1f patterns card and pattern editor).
+
 `complete_quest` payload from the panel:
 
 ```yaml

design/IMPLEMENTATION-ORDER.md

@@ -11,7 +11,9 @@ rather than aliasing.
 
 - `schema.py`: `task_definitions` → `quest_definitions`, `task_instances` →
   `quest_instances`. Keep `completion_events`, `children`, `admin_users`,
-  `schedule_rules`, `presence_schedules`, `presence_overrides`.
+  `schedule_rules`, `presence_patterns`, `presence_overrides`. (`presence_patterns` —
+  zero or more `home`/`away` patterns per child — replaced the retired one-per-child
+  schedule table in schema 9; migration 9 converts its rows into `home` patterns.)
 - `db.py` / `store.py`: rename DAO methods and any SQL literals.
 - `const.py`: no table names live there today; keep it that way.
 - `tests/test_schema.py`, `tests/test_store.py`, `tests/test_db.py`: update expectations.
@@ -43,8 +45,9 @@ Nullable int. Set for panel completions, null for admin ones. Still append-only.
 
 ## 2. Engines and materialisation
 Unchanged in intent: pure recurrence engine, pure presence engine with anchor-date
-arithmetic, daily materialiser over `horizon_days` at `day_rollover_time`. Only the
-instance fan-out changes (assignees × windows).
+arithmetic (per pattern, each with its own anchor; since schema 9 it combines a child's
+patterns and overrides first-match-wins), daily materialiser over `horizon_days` at
+`day_rollover_time`. Only the instance fan-out changes (assignees × windows).
 
 ## 3. Services, permissions, entities
 Implement the service table in `ENTITIES-AND-SERVICES.md` §2 behind the permission

design/PANEL-SPEC.md

@@ -22,10 +22,14 @@ Screens `1a`, `1b`, `1j`, `1c` of the mockups. Two cards:
 
 Default view on the wall. Layout top to bottom:
 
-1. **Wordmark row** at y=64. Rule · d20 hexagon · `NestQuest` (66px/900 display, brand
-   gradient via `background-clip: text`) · d20 · rule. d20 marks are 34px hexagons
-   (`clip-path: polygon(50% 0, 93% 25%, 93% 75%, 50% 100%, 7% 75%, 7% 25%)`) filled with
-   the brand gradient, numeral 15px/700 Cinzel.
+1. **Wordmark row** at y=64. Rule · monogram · `NestQuest` (66px/900 Cinzel Decorative
+   display, brand gradient via `background-clip: text`) · rule — the horizontal lockup of
+   `design/logos/NestQuest_Logo.png`. The monogram is an 80px inline SVG (no raster, no
+   remote asset): a compass rose — four long cardinal points, four short diagonal points,
+   a ring broken by the points — around a d20 hexagon with facet lines and a knocked-out
+   Cinzel Decorative "N", filled with the brand gradient (`--nq-brand-blue` →
+   `--nq-brand-purple`, 135°). Gaps are SVG masks, so the mark stays transparent over the
+   parchment.
 2. **Kicker** `The Party · <weekday>, <Month D>` — 21px/600 Cinzel, tracking .30em, uppercase.
 3. **Adventurer plates**, 3-up grid, 56px gap, page inset 110px, top y=262. One plate per
    child returned by the party sensor, in configured order.
@@ -91,7 +95,14 @@ collapse the column, the three-column rhythm is the layout.
 `--nq-p-quest-min-height` 116px, radius 12px, `--nq-p-card-open`, 1px
 `--nq-p-card-border`, `--nq-p-card-shadow`, padding 22px, 22px gap, row layout:
 
-1. **Icon tile** 64×64, radius 10px, `--nq-p-icon-tile`, Lucide glyph 34px white.
+1. **Icon tile** 64×64, radius 10px, `--nq-p-icon-tile`, glyph 34px white — the
+   definition's icon, resolved from its namespaced key (`ADMIN-SPEC.md` §3.3):
+   `lucide:<name>` draws the curated Lucide glyph **stroked** (fill none, stroke-width 2,
+   round caps and joins); `fa:<name>` draws the curated Font Awesome glyph **filled**;
+   `emoji:<grapheme>` renders the emoji **as text**. A legacy bare name resolves as
+   `lucide:<name>`. No icon, or any key that does not resolve (unknown namespace or name,
+   malformed emoji), falls back to the **star** glyph. Glyph data is bundled from the
+   shared registry — nothing is fetched at runtime.
 2. **Text** title 30px/700 Cinzel `--nq-p-ink`; meta 22px/600 Nunito
    `--nq-p-ink-secondary` reading `Due by <h:mm A>`. If past due:
    `Overdue · due <h:mm A>` in 22px/700 Cinzel uppercase, tracking .10em,
@@ -106,7 +117,9 @@ Both the card body and the button open the confirm dialog (§4). Press feedback:
 ### 3.3 Quest card — sealed
 
 `--nq-p-card-done`, `opacity: .82`, no shadow, **not tappable**. Icon tile
-`--nq-p-icon-tile-done` with the glyph in `--nq-p-ink-secondary`. Title 30px/700 Cinzel
+`--nq-p-icon-tile-done` with the glyph in `--nq-p-ink-secondary`. The sealed tile keeps
+the static star glyph — it does **not** render the definition icon — alongside the wax
+seal below. Title 30px/700 Cinzel
 `--nq-p-ink-muted` with `text-decoration: line-through`. Meta reads
 `Claimed <h:mm A>` 22px/600 Nunito `--nq-p-ink-secondary`.
 

docs/ARCHITECTURE.md

@@ -61,6 +61,44 @@ two-writer problem entirely.
 - **Backups:** continuous replication (e.g. Litestream) plus a proven restore.
   A configured-but-untested backup is not a backup.
 
+### Presence model (schema 9)
+
+A child has **zero or more** presence patterns, stored one row each in
+`presence_patterns` (`child_id` is not unique):
+
+| Column | Meaning |
+|---|---|
+| `name` | Label shown in the admin PWA, not blank |
+| `kind` | `home` or `away` — what the pattern claims on the days it covers |
+| `cycle_length_weeks` | 1–4; the pattern's own repeating cycle |
+| `anchor_date` | ISO date that starts week 1 of the pattern's cycle |
+| `pattern` | Pipe-separated weekday sets, one CSV segment per cycle week, weekdays **Monday=0 .. Sunday=6** (e.g. `0,2,4\|1,3`); an empty segment covers no day that week |
+
+Cycle position is anchor-date arithmetic per pattern — **never** ISO week
+numbers or week parity (D-004). A child's presence on a date is decided
+first match wins:
+
+1. A presence override covering the date — its flag is the answer.
+2. Any `away` pattern covers the date — **away**.
+3. Any `home` pattern covers the date — **present**.
+4. The child has at least one `home` pattern — **away** (a home pattern lists
+   the days the child is home; every other day is away).
+5. Otherwise (only `away` patterns, or no patterns) — **present**.
+
+The core presence engine, the snapshot's `present_today`, the materialiser's
+skip-on-away-days rule, and the admin PWA's month grid all apply this order.
+The admin plane manages patterns with
+`GET`/`POST /api/v1/admin/children/{child_id}/presence-patterns` and
+`PATCH`/`DELETE /api/v1/admin/presence-patterns/{pattern_id}`.
+
+**Migration 9** replaced the older one-schedule-per-child table: it creates
+`presence_patterns`, copies every old schedule row into a `home` pattern
+named `Home schedule` (cycle length, anchor date and weekday sets
+unchanged, row id kept), and drops the old table, all in one transaction.
+A lone `home` pattern answers exactly as the old schedule did, so no
+child's presence changes. The drop is one-way and 0.7.1 refuses a
+version-9 database; see the rollback step in `deploy/RUNBOOK.md` §11.
+
 ## 4. Authentication: two planes
 
 The kid panel and the admin PWA have opposite trust levels, so they use

frontend/src/cards/party-board.ts

@@ -231,8 +231,76 @@ function conditionPhrase(condition: string, label: string): string {
 }
 
 const SHIELD_CLIP = "polygon(0 0, 100% 0, 100% 62%, 50% 100%, 0 62%)";
-const HEXAGON_CLIP =
-  "polygon(50% 0, 93% 25%, 93% 75%, 50% 100%, 7% 75%, 7% 25%)";
+// The brand monogram (design/logos/NestQuest_Logo.png): a compass rose —
+// four long cardinal points, four short diagonal points, a ring broken by
+// the points — around a d20 hexagon carrying a knocked-out "N". Drawn on
+// a 100-unit grid and filled with the brand gradient; the masks cut the
+// parchment gaps so the mark stays transparent on any backdrop.
+const MONOGRAM_POINTS =
+  "M50 3 44.5 24.1 50 26 55.5 24.1Z M100 50 75.9 44.5 74 50 75.9 55.5Z " +
+  "M50 97 55.5 75.9 50 74 44.5 75.9Z M0 50 24.1 55.5 26 50 24.1 44.5Z " +
+  "M29.1 29.1 29.7 36.3 36.3 29.7Z M70.9 29.1 63.7 29.7 70.3 36.3Z " +
+  "M70.9 70.9 70.3 63.7 63.7 70.3Z M29.1 70.9 36.3 70.3 29.7 63.7Z";
+const MONOGRAM_HEX = "M50 26.5 70.4 38.2 70.4 61.8 50 73.5 29.6 61.8 29.6 38.2Z";
+const MONOGRAM_FACETS =
+  "M29.6 38.2H70.4M29.6 61.8H70.4M50 26.5 36.5 38.2M50 26.5 63.5 38.2" +
+  "M50 73.5 36.5 61.8M50 73.5 63.5 61.8M36.5 38.2V61.8M63.5 38.2V61.8" +
+  "M29.6 38.2 36.5 61.8M36.5 38.2 29.6 61.8" +
+  "M70.4 38.2 63.5 61.8M63.5 38.2 70.4 61.8";
+const MONOGRAM = html`<svg
+  class="monogram"
+  viewBox="0 0 100 100"
+  aria-hidden="true"
+  focusable="false"
+>
+  <defs>
+    <linearGradient
+      id="nq-monogram-fill"
+      gradientUnits="userSpaceOnUse"
+      x1="0"
+      y1="0"
+      x2="100"
+      y2="100"
+    >
+      <stop offset="0" style="stop-color: var(--nq-brand-blue)" />
+      <stop offset="1" style="stop-color: var(--nq-brand-purple)" />
+    </linearGradient>
+    <mask id="nq-monogram-points-gap" maskUnits="userSpaceOnUse">
+      <rect width="100" height="100" fill="#fff" />
+      <path d=${MONOGRAM_POINTS} stroke="#000" stroke-width="3.5" />
+    </mask>
+    <mask id="nq-monogram-facets" maskUnits="userSpaceOnUse">
+      <rect width="100" height="100" fill="#fff" />
+      <path d=${MONOGRAM_FACETS} stroke="#000" stroke-width="1.6" />
+      <text
+        x="50"
+        y="59.4"
+        text-anchor="middle"
+        font-family="'Cinzel Decorative', Cinzel, serif"
+        font-weight="900"
+        font-size="25"
+        fill="#fff"
+        stroke="#000"
+        stroke-width="2"
+        paint-order="stroke"
+      >N</text>
+    </mask>
+  </defs>
+  <g fill="url(#nq-monogram-fill)">
+    <path d=${MONOGRAM_POINTS} />
+    <g mask="url(#nq-monogram-points-gap)">
+      <circle
+        cx="50"
+        cy="50"
+        r="34.25"
+        fill="none"
+        stroke="url(#nq-monogram-fill)"
+        stroke-width="6.5"
+      />
+      <path mask="url(#nq-monogram-facets)" d=${MONOGRAM_HEX} />
+    </g>
+  </g>
+</svg>`;
 
 const boardStyles = css`
   * {
@@ -299,23 +367,11 @@ const boardStyles = css`
     background: rgba(92, 62, 26, 0.35);
   }
 
-  .d20 {
+  .monogram {
     flex: none;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    width: 34px;
-    height: 34px;
-    clip-path: ${unsafeCSS(HEXAGON_CLIP)};
-    background: var(--nq-brand-gradient);
-  }
-
-  .d20-numeral {
-    font-family: var(--nq-p-font-heading);
-    font-size: 15px;
-    font-weight: 700;
-    line-height: 1;
-    color: #ffffff;
+    display: block;
+    width: 80px;
+    height: 80px;
   }
 
   .wordmark {
@@ -497,11 +553,12 @@ const boardStyles = css`
 
   .hint {
     position: absolute;
-    top: 930px;
+    top: 896px;
     left: 0;
     right: 0;
+    margin: 0;
     font-family: var(--nq-p-font-body);
-    font-size: 24px;
+    font-size: 27px;
     font-weight: 600;
     line-height: 1.4;
     text-align: center;
@@ -861,13 +918,8 @@ export class NestQuestPartyBoardCard extends LitElement {
         <div class="frame frame-inner"></div>
         <div class="wordmark-row">
           <span class="rule"></span>
-          <span class="d20" aria-hidden="true">
-            <span class="d20-numeral">20</span>
-          </span>
+          ${MONOGRAM}
           <span class="wordmark">NestQuest</span>
-          <span class="d20" aria-hidden="true">
-            <span class="d20-numeral">20</span>
-          </span>
           <span class="rule"></span>
         </div>
         <p class="kicker">The Party · ${formatDay(this._now, this._timeZone())}</p>

frontend/src/cards/quest-log.ts

@@ -2,6 +2,7 @@ import { LitElement, css, html, nothing, unsafeCSS, type TemplateResult } from "
 import { repeat } from "lit/directives/repeat.js";
 import panelTokens from "../../../custom_components/nestquest/www/nestquest-panel-tokens.css?inline";
 
+import { renderQuestIcon } from "../icons/render";
 import { registerCustomCard, type CardConfig, type HassLike } from "../types";
 
 type QuestLogCardConfig = CardConfig & {
@@ -378,7 +379,7 @@ const logStyles = css`
     flex: none;
     width: 96px;
     height: 110px;
-    padding: 3px;
+    padding: 4px;
     clip-path: ${unsafeCSS(SHIELD_CLIP)};
     background: rgba(255, 255, 255, 0.22);
   }
@@ -614,6 +615,11 @@ const logStyles = css`
     height: 34px;
   }
 
+  .tile .emoji {
+    font-size: 30px;
+    line-height: 1;
+  }
+
   .sealed .tile {
     background: var(--nq-p-icon-tile-done);
     color: var(--nq-p-ink-secondary);
@@ -1938,7 +1944,7 @@ export class NestQuestQuestLogCard extends LitElement {
     const initial = (name?.charAt(0) || "?").toUpperCase();
     return html`
       <header class="header">
-        <span class="crest${away ? " away" : nothing}" aria-hidden="true">
+        <span class="crest${away ? " away" : ""}" aria-hidden="true">
           <span class="crest-face">
             <span class="initial">${initial}</span>
           </span>
@@ -2093,10 +2099,10 @@ export class NestQuestQuestLogCard extends LitElement {
           }
         }}
       >
-        <span class="tile" aria-hidden="true">${ICON_STAR}</span>
+        <span class="tile" aria-hidden="true">${renderQuestIcon(instance.icon, ICON_STAR)}</span>
         <div class="body">
           <span class="quest-title">${instance.title}</span>
-          <span class="meta ${meta.late ? "late" : nothing}">${meta.text}</span>
+          <span class="${meta.late ? "meta late" : "meta"}">${meta.text}</span>
         </div>
         <button
           class="complete"

frontend/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;
+}

frontend/src/icons/render.ts

@@ -0,0 +1,48 @@
+/**
+ * Lit rendering for the shared icon registry (`registry.generated.ts`,
+ * generated from tools/icons/curated-icons.json). The glyph path data is
+ * bundled — no CDN and no runtime fetch.
+ */
+import { html, svg, type TemplateResult } from "lit";
+
+import { resolveIcon } from "./registry.generated";
+
+/**
+ * A stored definition icon (`lucide:<name>`, `fa:<name>`, `emoji:<grapheme>`
+ * or a legacy bare Lucide name) as a template; anything that resolves to the
+ * registry fallback renders `fallback` instead.
+ */
+export function renderQuestIcon(
+  value: string | null,
+  fallback: TemplateResult
+): TemplateResult {
+  const icon = resolveIcon(value);
+  switch (icon.kind) {
+    case "lucide":
+      return html`<svg
+        viewBox=${icon.viewBox}
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        aria-hidden="true"
+        data-icon=${icon.key}
+      >
+        ${icon.paths.map((d) => svg`<path d=${d}></path>`)}
+      </svg>`;
+    case "fa":
+      return html`<svg
+        viewBox=${icon.viewBox}
+        fill="currentColor"
+        aria-hidden="true"
+        data-icon=${icon.key}
+      >
+        ${icon.paths.map((d) => svg`<path d=${d}></path>`)}
+      </svg>`;
+    case "emoji":
+      return html`<span class="emoji" data-icon=${icon.key}>${icon.text}</span>`;
+    case "fallback":
+      return fallback;
+  }
+}

frontend/tests/render-quest-log.mjs

@@ -7,10 +7,14 @@
  * the card is mounted at the given URL (it resolves its child from the
  * pathname's last segment), after the optional probe wait one snapshot of
  * the render is taken mid-wait, then after the optional idle wait stdout
- * receives one JSON object {location, headline, countdown, html, probe} —
- * the final window pathname, the rendered title, the complete-screen
- * countdown text, the rendered shadow DOM, and the probe snapshot when
- * probe_ms was given. The Python panel tests drive this harness so the
+ * receives one JSON object {location, headline, countdown, html, tiles,
+ * probe, tap} — the final window pathname, the rendered title, the
+ * complete-screen countdown text, the rendered shadow DOM, each quest
+ * card's icon tile, and the probe snapshot when probe_ms was given. With
+ * tap_complete: <instance id> the harness taps that card's Complete button,
+ * records whether the confirm dialog opened, taps the dialog's Complete, and
+ * reports every hass.callService call as tap: {dialog_opened, service_calls}.
+ * The Python panel tests drive this harness so the
  * assertions run against the exact bundle HACS ships.
  */
 import { readFileSync } from "node:fs";
@@ -43,12 +47,34 @@ globalThis.Event = dom.window.Event;
 
 await import(pathToFileURL(spec.bundle).href);
 
+const serviceCalls = [];
+const hass = {
+  ...spec.hass,
+  callService(domain, service, data) {
+    serviceCalls.push({ domain, service, data });
+    return Promise.resolve();
+  },
+};
+
 const element = document.createElement("nestquest-quest-log-card");
 element.setConfig(spec.config);
-element.hass = spec.hass;
+element.hass = hass;
 document.body.appendChild(element);
 await element.updateComplete;
 
+let tap = null;
+if (spec.tap_complete !== undefined) {
+  element.shadowRoot
+    .querySelector(`.quest[data-instance-id="${spec.tap_complete}"] button.complete`)
+    .click();
+  await element.updateComplete;
+  const confirm = element.shadowRoot.querySelector("button.do-complete");
+  confirm?.click();
+  await element.updateComplete;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  tap = { dialog_opened: confirm !== null, service_calls: serviceCalls };
+}
+
 const snapshot = () => ({
   location: window.location.pathname,
   headline: element.shadowRoot.querySelector(".title")?.textContent?.trim() ?? "",
@@ -56,6 +82,22 @@ const snapshot = () => ({
     element.shadowRoot.querySelector(".complete-countdown")?.textContent?.trim() ??
     "",
   html: element.shadowRoot.innerHTML,
+  // Each quest card's icon tile: the registry glyph it rendered (its
+  // data-icon key and svg fill), its text (an emoji), and whether it shows
+  // the static star (the star's polygon).
+  tiles: [...element.shadowRoot.querySelectorAll(".quest")].map((quest) => {
+    const tile = quest.querySelector(".tile");
+    const glyph = tile?.querySelector("[data-icon]");
+    return {
+      id: Number(quest.dataset.instanceId),
+      sealed: quest.classList.contains("sealed"),
+      icon: glyph?.getAttribute("data-icon") ?? null,
+      fill: glyph?.getAttribute("fill") ?? null,
+      paths: tile?.querySelectorAll("path").length ?? 0,
+      text: tile?.textContent?.trim() ?? "",
+      star: Boolean(tile?.querySelector("polygon")),
+    };
+  }),
 });
 
 let probe = null;
@@ -68,6 +110,6 @@ if (spec.idle_ms !== undefined) {
   await new Promise((resolve) => setTimeout(resolve, spec.idle_ms));
 }
 
-const payload = JSON.stringify({ ...snapshot(), probe });
+const payload = JSON.stringify({ ...snapshot(), probe, tap });
 await new Promise((resolve) => process.stdout.write(payload, () => resolve()));
 process.exit(0);

frontend/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "target": "ES2022",
+    "useDefineForClassFields": false,
     "module": "ESNext",
     "moduleResolution": "bundler",
     "lib": ["ES2022", "DOM"],

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nestquest"
-version = "0.6.0"
+version = "0.8.0"
 description = "NestQuest Home Assistant Integration"
 readme = "README.md"
 requires-python = ">=3.11"

tests/test_api_admin_occurrences.py

@@ -0,0 +1,431 @@
+"""Admin-plane occurrence-preview route tests (task 5f843564).
+
+These tests exercise ``POST /api/v1/admin/quest-definitions/occurrences-preview``
+against the ASGI app with httpx, reusing the shared local-RSA-key/
+stubbed-JWKS harness (:mod:`tests.admin_jwt_harness`) so an admin JWT
+genuinely authenticates with NO network access.
+
+- Authentication runs through the router's ONE ``require_admin``
+  dependency: no credential is 401, the panel service token is 403
+  (refused as a credential type), a JWT without the admin group is
+  403, an admin JWT is 200.
+- The returned dates are asserted EXACTLY for a weekly rule with an
+  interval and a start_date, a daily rule with an interval, a rule
+  with an end_date (the list stops at it), a month-end-clamped monthly
+  rule, and the default start (the pinned host clock's today); one
+  case also asserts parity with the core's own ``occurrences_between``
+  over the documented window.
+- A rejected rule (the same core ``from_dict`` validation create/edit
+  use), a non-strict ``start_date`` and a ``count`` outside 1..50 are
+  422.
+"""
+from __future__ import annotations
+
+import datetime
+import importlib
+from types import SimpleNamespace
+from zoneinfo import ZoneInfo
+
+import pytest
+
+from api import routes_admin
+from tests.admin_jwt_harness import (
+    ADMIN_KEY,
+    KID,
+    AdminRunner,
+    jwks_for,
+    make_token,
+)
+
+# The recurrence engine through the SAME core copy the app uses
+# (nestquest_core.*, NOT the conftest-stubbed custom_components copy).
+_recurrence = importlib.import_module("nestquest_core.recurrence")
+
+PREVIEW_URL = "/api/v1/admin/quest-definitions/occurrences-preview"
+
+#: The panel service token the harness app is configured with.
+HARNESS_PANEL_TOKEN = "admin-test-panel-token"
+
+#: The 403 detail for the panel service token on an admin route.
+PANEL_TOKEN_REJECTION_DETAIL = (
+    "This credential type is not accepted for admin access"
+)
+
+#: The 403 detail for a valid JWT without the admin group.
+FORBIDDEN_DETAIL = (
+    "Admin access requires membership in the nestquest-admins group"
+)
+
+#: The pinned host instant: Wednesday 2026-09-23, noon UTC.
+PINNED_NOW = datetime.datetime(2026, 9, 23, 12, 0, 0, tzinfo=ZoneInfo("UTC"))
+
+
+def _admin_headers() -> dict[str, str]:
+    """The Authorization header of a valid nestquest-admins JWT."""
+    return {"Authorization": f"Bearer {make_token()}"}
+
+
+def _weekly_rule() -> dict[str, object]:
+    """Every OTHER week's Tuesday and Friday, anchored on Tue 2026-03-03."""
+    return {
+        "rule_type": "weekly",
+        "interval": 2,
+        "weekday_set": [1, 4],
+        "start_date": "2026-03-03",
+    }
+
+
+@pytest.fixture
+async def preview(temp_db_path: str, monkeypatch) -> SimpleNamespace:
+    """An admin-plane app client with the host clock pinned (and counted)."""
+    clock_reads: list[datetime.datetime] = []
+
+    def _admin_now() -> datetime.datetime:
+        clock_reads.append(PINNED_NOW)
+        return PINNED_NOW
+
+    monkeypatch.setattr(routes_admin, "_local_now", _admin_now)
+    runner = AdminRunner(temp_db_path, jwks_for(ADMIN_KEY, KID))
+    async with runner as client:
+        yield SimpleNamespace(client=client, clock_reads=clock_reads)
+
+
+async def _post(client: object, body: dict[str, object]) -> object:
+    """POST a preview body with an admin JWT."""
+    return await client.post(PREVIEW_URL, json=body, headers=_admin_headers())
+
+
+# --- authentication: the ONE require_admin dependency ----------------------
+
+
+async def test_preview_without_credential_is_401(
+    preview: SimpleNamespace,
+) -> None:
+    """No Authorization header is the uniform 401."""
+    response = await preview.client.post(
+        PREVIEW_URL, json={"rule": _weekly_rule()}
+    )
+    assert response.status_code == 401
+
+
+async def test_preview_refuses_panel_service_token(
+    preview: SimpleNamespace,
+) -> None:
+    """The panel service token is refused as a credential type (403)."""
+    response = await preview.client.post(
+        PREVIEW_URL,
+        json={"rule": _weekly_rule()},
+        headers={"Authorization": f"Bearer {HARNESS_PANEL_TOKEN}"},
+    )
+    assert response.status_code == 403
+    assert response.json()["detail"] == PANEL_TOKEN_REJECTION_DETAIL
+
+
+async def test_preview_refuses_non_admin_jwt(
+    preview: SimpleNamespace,
+) -> None:
+    """A valid JWT without the nestquest-admins group is 403."""
+    non_admin = make_token(groups=("some-other-group",))
+    response = await preview.client.post(
+        PREVIEW_URL,
+        json={"rule": _weekly_rule()},
+        headers={"Authorization": f"Bearer {non_admin}"},
+    )
+    assert response.status_code == 403
+    assert response.json()["detail"] == FORBIDDEN_DETAIL
+
+
+async def test_preview_admin_jwt_is_200(preview: SimpleNamespace) -> None:
+    """An admin JWT is 200 with the documented ``dates`` shape."""
+    response = await _post(
+        preview.client, {"rule": _weekly_rule(), "start_date": "2026-03-01"}
+    )
+    assert response.status_code == 200
+    assert set(response.json()) == {"dates"}
+
+
+# --- the returned dates ----------------------------------------------------
+
+
+async def test_weekly_interval_rule_from_before_its_start(
+    preview: SimpleNamespace,
+) -> None:
+    """Every other week's Tue/Fri, starting at the rule's own start_date.
+
+    The preview starts on Sun 2026-03-01, before the rule's anchor, so
+    the first date is the anchor itself; the off weeks (Mar 10-16,
+    Mar 24-30) are skipped.
+    """
+    response = await _post(
+        preview.client,
+        {"rule": _weekly_rule(), "start_date": "2026-03-01", "count": 6},
+    )
+    assert response.status_code == 200
+    assert response.json()["dates"] == [
+        "2026-03-03",
+        "2026-03-06",
+        "2026-03-17",
+        "2026-03-20",
+        "2026-03-31",
+        "2026-04-03",
+    ]
+
+
+async def test_weekly_interval_rule_from_mid_cadence(
+    preview: SimpleNamespace,
+) -> None:
+    """A start inside an on-week keeps the rule's anchor cadence."""
+    response = await _post(
+        preview.client,
+        {"rule": _weekly_rule(), "start_date": "2026-03-18", "count": 4},
+    )
+    assert response.status_code == 200
+    assert response.json()["dates"] == [
+        "2026-03-20",
+        "2026-03-31",
+        "2026-04-03",
+        "2026-04-14",
+    ]
+
+
+async def test_daily_interval_rule(preview: SimpleNamespace) -> None:
+    """Every third day from 2026-01-01, previewed from 2026-01-05."""
+    response = await _post(
+        preview.client,
+        {
+            "rule": {
+                "rule_type": "daily",
+                "interval": 3,
+                "start_date": "2026-01-01",
+            },
+            "start_date": "2026-01-05",
+            "count": 4,
+        },
+    )
+    assert response.status_code == 200
+    assert response.json()["dates"] == [
+        "2026-01-07",
+        "2026-01-10",
+        "2026-01-13",
+        "2026-01-16",
+    ]
+
+
+async def test_rule_with_end_date_stops_at_it(
+    preview: SimpleNamespace,
+) -> None:
+    """A daily rule ending 2026-05-04 yields only its four dates."""
+    response = await _post(
+        preview.client,
+        {
+            "rule": {
+                "rule_type": "daily",
+                "start_date": "2026-05-01",
+                "end_date": "2026-05-04",
+            },
+            "start_date": "2026-04-28",
+            "count": 10,
+        },
+    )
+    assert response.status_code == 200
+    assert response.json()["dates"] == [
+        "2026-05-01",
+        "2026-05-02",
+        "2026-05-03",
+        "2026-05-04",
+    ]
+
+
+async def test_monthly_day_rule_clamps_to_month_end(
+    preview: SimpleNamespace,
+) -> None:
+    """The core's month-end policy: the 31st fires on Feb 28th."""
+    response = await _post(
+        preview.client,
+        {
+            "rule": {
+                "rule_type": "monthly_day",
+                "day_of_month": 31,
+                "start_date": "2026-01-31",
+            },
+            "start_date": "2026-01-01",
+            "count": 3,
+        },
+    )
+    assert response.status_code == 200
+    assert response.json()["dates"] == [
+        "2026-01-31",
+        "2026-02-28",
+        "2026-03-31",
+    ]
+
+
+async def test_default_start_is_host_today_with_default_count(
+    preview: SimpleNamespace,
+) -> None:
+    """No start_date: ONE clock read's date; no count: ten dates."""
+    response = await _post(preview.client, {"rule": {"rule_type": "daily"}})
+    assert response.status_code == 200
+    expected = [
+        (datetime.date(2026, 9, 23) + datetime.timedelta(days=n)).isoformat()
+        for n in range(10)
+    ]
+    assert response.json()["dates"] == expected
+    assert preview.clock_reads == [PINNED_NOW]
+
+
+async def test_supplied_start_date_reads_no_clock(
+    preview: SimpleNamespace,
+) -> None:
+    """A supplied start_date is used as-is: the host clock is not read."""
+    response = await _post(
+        preview.client, {"rule": _weekly_rule(), "start_date": "2026-03-01"}
+    )
+    assert response.status_code == 200
+    assert preview.clock_reads == []
+
+
+async def test_dates_match_core_occurrences_between_over_window(
+    preview: SimpleNamespace,
+) -> None:
+    """The route's dates ARE the core's walk over the 366-day window."""
+    rule_body = {
+        "rule_type": "monthly_weekday",
+        "nth_weekday": -1,
+        "nth_weekday_weekday": 4,
+        "start_date": "2026-01-01",
+    }
+    response = await _post(
+        preview.client,
+        {"rule": rule_body, "start_date": "2026-02-10", "count": 50},
+    )
+    assert response.status_code == 200
+    core_dates = _recurrence.occurrences_between(
+        _recurrence.ScheduleRule.from_dict(rule_body),
+        "2026-02-10",
+        "2027-02-11",
+    )
+    assert response.json()["dates"] == core_dates
+    assert len(core_dates) == 12
+
+
+async def test_yearly_rule_shows_next_occurrence_within_window(
+    preview: SimpleNamespace,
+) -> None:
+    """The 366-day window always reaches a yearly rule's next date."""
+    response = await _post(
+        preview.client,
+        {
+            "rule": {
+                "rule_type": "yearly",
+                "month": 9,
+                "day_of_month": 22,
+                "start_date": "2020-09-22",
+            },
+            "start_date": "2026-09-23",
+        },
+    )
+    assert response.status_code == 200
+    assert response.json()["dates"] == ["2027-09-22"]
+
+
+async def test_start_near_calendar_end_is_422(
+    preview: SimpleNamespace,
+) -> None:
+    """A window that would reach 9999-12-31 is rejected, not clamped."""
+    response = await _post(
+        preview.client,
+        {"rule": {"rule_type": "daily"}, "start_date": "9999-12-30"},
+    )
+    assert response.status_code == 422
+    assert "too close to the end of the calendar" in response.json()["detail"]
+
+
+async def test_latest_accepted_start_date(preview: SimpleNamespace) -> None:
+    """The last start whose window ends before 9999-12-31 is accepted."""
+    response = await _post(
+        preview.client,
+        {
+            "rule": {"rule_type": "daily"},
+            "start_date": "9998-12-29",
+            "count": 1,
+        },
+    )
+    assert response.status_code == 200
+    assert response.json()["dates"] == ["9998-12-29"]
+
+
+# --- rejections: 422 -------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "rule",
+    [
+        {"rule_type": "weekly"},  # weekly without weekday_set
+        {"rule_type": "fortnightly"},  # unknown rule_type
+        {"rule_type": "daily", "interval": 0},
+        {"rule_type": "daily", "weekday_set": [1]},  # forbidden field
+        {"rule_type": "daily", "start_date": "2026-3-1"},
+        {
+            "rule_type": "daily",
+            "start_date": "2026-05-04",
+            "end_date": "2026-05-01",
+        },
+    ],
+)
+async def test_malformed_rule_is_422(
+    preview: SimpleNamespace, rule: dict[str, object]
+) -> None:
+    """A rule the core's from_dict rejects is 422, as on create/edit."""
+    response = await _post(
+        preview.client, {"rule": rule, "start_date": "2026-03-01"}
+    )
+    assert response.status_code == 422
+
+
+async def test_missing_rule_is_422(preview: SimpleNamespace) -> None:
+    """The rule is required: the body model's 422."""
+    response = await _post(preview.client, {"start_date": "2026-03-01"})
+    assert response.status_code == 422
+
+
+@pytest.mark.parametrize(
+    "start_date", ["2026-3-1", "20260301", "tomorrow", "2026-02-30", ""]
+)
+async def test_non_strict_start_date_is_422(
+    preview: SimpleNamespace, start_date: str
+) -> None:
+    """start_date must be a strict YYYY-MM-DD date (the core's check)."""
+    response = await _post(
+        preview.client, {"rule": _weekly_rule(), "start_date": start_date}
+    )
+    assert response.status_code == 422
+
+
+@pytest.mark.parametrize("count", [0, -1, 51, 1000, True, "5", 2.5])
+async def test_count_out_of_range_is_422(
+    preview: SimpleNamespace, count: object
+) -> None:
+    """count must be a strict JSON integer in 1..50."""
+    response = await _post(
+        preview.client,
+        {"rule": _weekly_rule(), "start_date": "2026-03-01", "count": count},
+    )
+    assert response.status_code == 422
+
+
+@pytest.mark.parametrize("count", [1, 50])
+async def test_count_bounds_are_inclusive(
+    preview: SimpleNamespace, count: int
+) -> None:
+    """count 1 and 50 are accepted and truncate the list exactly."""
+    response = await _post(
+        preview.client,
+        {
+            "rule": {"rule_type": "daily"},
+            "start_date": "2026-01-01",
+            "count": count,
+        },
+    )
+    assert response.status_code == 200
+    assert len(response.json()["dates"]) == count