Add the admin Today tab (compact design)

Render ADMIN-SPEC §2.1-2.6 from GET /api/v1/admin/snapshot: header with
cycle day, the Done/Remaining/Overdue stat row, child rows with progress
and away state, the needs-attention list, and the admin-only Undo
permission note. The scroll column ends with 92px bottom padding, and
loading and error states never leave the panel blank.

Mark done / Undo render per spec but are not wired (task e57facc2).
The override pill and "from panel" actor are omitted: the snapshot
carries neither field.

Task: e0a2b862-8c1e-4d5b-95ad-48b460bfeaa0

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

admin/.env.example

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

admin/.gitignore

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

admin/index.html

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

admin/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "nestquest-admin",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@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",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.5",
+    "vitest": "^3.2.4"
+  }
+}

admin/public/manifest.webmanifest

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

admin/public/sw.js

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

admin/scripts/generate-icons.mjs

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

admin/src/App.css

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

admin/src/App.test.tsx

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

admin/src/App.tsx

@@ -0,0 +1,57 @@
+import { useState } from "react";
+import "./App.css";
+import TodayTab from "./today/TodayTab";
+
+const TABS = [
+  { id: "today", label: "Today" },
+  { id: "tasks", label: "Tasks" },
+  { id: "schedule", label: "Schedule" },
+  { id: "history", label: "History" },
+] as const;
+
+type TabId = (typeof TABS)[number]["id"];
+
+export default function App() {
+  const [active, setActive] = useState<TabId>("today");
+  // 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>
+  );
+}

admin/src/AppRoutes.test.tsx

@@ -0,0 +1,73 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import AppRoutes from "./AppRoutes";
+import { storeTokens } from "./auth/oidc";
+import { config } from "./config";
+
+// The bundled config reads real env at import time; seed the shared module's
+// clientId directly so AppRoutes sees a configured app in these tests.
+(config as { clientId: string | undefined }).clientId = "test-client-id";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("AppRoutes auth gating", () => {
+  afterEach(() => {
+    cleanup();
+    sessionStorage.clear();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    window.history.replaceState({}, "", "/");
+  });
+
+  it("renders the login screen when unauthenticated at /", () => {
+    render(<AppRoutes />);
+    expect(screen.getByTestId("login-screen")).toBeTruthy();
+    expect(
+      screen.getByRole("button", { name: /sign in with authentik/i }),
+    ).toBeTruthy();
+  });
+
+  it("renders the four-tab shell after a successful authenticated probe", async () => {
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    const fetchMock = vi.fn().mockResolvedValue(jsonResponse([]));
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(<AppRoutes />);
+
+    await waitFor(() => {
+      expect(screen.getByRole("heading", { name: "NestQuest Admin" })).toBeTruthy();
+    });
+    for (const label of ["Today", "Tasks", "Schedule", "History"]) {
+      expect(screen.getByRole("tab", { name: label })).toBeTruthy();
+    }
+  });
+
+  it("renders the explicit refusal when the API answers 403", async () => {
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    const fetchMock = vi.fn().mockResolvedValue(new Response("", { status: 403 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    render(<AppRoutes />);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("refusal-screen")).toBeTruthy();
+    });
+    expect(screen.getByText(/not in the nestquest-admins group/i)).toBeTruthy();
+  });
+
+  it("shows the configuration error screen when the client id is missing", () => {
+    const original = config.clientId;
+    (config as { clientId: string | undefined }).clientId = undefined;
+    try {
+      render(<AppRoutes />);
+      expect(screen.getByTestId("config-error-screen")).toBeTruthy();
+    } finally {
+      (config as { clientId: string | undefined }).clientId = original;
+    }
+  });
+});

admin/src/AppRoutes.tsx

@@ -0,0 +1,176 @@
+/**
+ * Minimal path-based routing without react-router-dom: the app only needs two
+ * paths (`/` shell and `/auth/callback`), so a tiny window.location switch is
+ * enough and keeps the bundle small. Change screens listen to popstate.
+ */
+import { useEffect, useState } from "react";
+import { ConfigError, config } from "./config";
+import {
+  AuthError,
+  buildAuthorizeUrl,
+  clearAuth,
+  handleCallback,
+  isAuthenticated,
+} from "./auth/oidc";
+import { ApiForbiddenError, apiFetch } from "./api/client";
+import AdminShell from "./App";
+
+type Screen =
+  | { kind: "loading" }
+  | { kind: "login" }
+  | { kind: "config-error"; message: string }
+  | { kind: "auth-error"; message: string }
+  | { kind: "refusal"; message: string }
+  | { kind: "app" };
+
+function currentPath(): string {
+  return window.location.pathname.replace(/\/+$/, "") || "/";
+}
+
+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.
+  try {
+    await apiFetch("/api/v1/children", {}, config);
+    setScreen({ kind: "app" });
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      setScreen({ kind: "config-error", message: error.message });
+      return;
+    }
+    if (error instanceof ApiForbiddenError) {
+      setScreen({ kind: "refusal", message: error.message });
+      return;
+    }
+    // Network or other failures still allow the shell to render; API screens
+    // handle their own errors in later tasks.
+    setScreen({ kind: "app" });
+  }
+}
+
+function LoginScreen({ onLogin }: { onLogin: () => void }) {
+  return (
+    <div className="admin-login" data-testid="login-screen">
+      <h1 className="admin-title">NestQuest Admin</h1>
+      <p className="admin-subline">Sign in to continue</p>
+      <button type="button" className="admin-login-button" onClick={onLogin}>
+        Sign in with Authentik
+      </button>
+    </div>
+  );
+}
+
+export default function AppRoutes() {
+  const [screen, setScreen] = useState<Screen>({ kind: "loading" });
+
+  useEffect(() => {
+    // Re-evaluate on navigation (popstate) — routing is path based.
+    const onPop = () => setScreen({ kind: "loading" });
+    window.addEventListener("popstate", onPop);
+    return () => window.removeEventListener("popstate", onPop);
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    const path = currentPath();
+
+    if (!config.clientId) {
+      setScreen({
+        kind: "config-error",
+        message:
+          "Missing VITE_AUTHENTIK_CLIENT_ID configuration. Set it in your .env before building the admin PWA.",
+      });
+      return;
+    }
+
+    if (path === "/auth/callback") {
+      (async () => {
+        try {
+          await handleCallback(window.location.search, config);
+          if (cancelled) return;
+          window.history.replaceState({}, "", "/");
+          await probeApi((next) => !cancelled && setScreen(next));
+        } catch (error) {
+          if (cancelled) return;
+          const message =
+            error instanceof AuthError || error instanceof Error
+              ? error.message
+              : "Authentication failed.";
+          setScreen({ kind: "auth-error", message });
+        }
+      })();
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    if (isAuthenticated()) {
+      void probeApi((next) => !cancelled && setScreen(next));
+    } else {
+      setScreen({ kind: "login" });
+    }
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const startLogin = async () => {
+    try {
+      const url = await buildAuthorizeUrl(config);
+      window.location.assign(url);
+    } catch (error) {
+      setScreen({
+        kind: "config-error",
+        message: error instanceof Error ? error.message : "Login failed.",
+      });
+    }
+  };
+
+  switch (screen.kind) {
+    case "loading":
+      return (
+        <div className="admin-loading" role="status" data-testid="loading-screen">
+          Loading…
+        </div>
+      );
+    case "login":
+      return <LoginScreen onLogin={startLogin} />;
+    case "config-error":
+      return (
+        <div className="admin-error" role="alert" data-testid="config-error-screen">
+          <h1>Configuration error</h1>
+          <p>{screen.message}</p>
+        </div>
+      );
+    case "auth-error":
+      return (
+        <div className="admin-error" role="alert" data-testid="auth-error-screen">
+          <h1>Sign-in failed</h1>
+          <p>{screen.message}</p>
+          <button
+            type="button"
+            onClick={() => {
+              clearAuth();
+              window.history.replaceState({}, "", "/");
+              setScreen({ kind: "loading" });
+            }}
+          >
+            Try again
+          </button>
+        </div>
+      );
+    case "refusal":
+      return (
+        <div className="admin-refusal" role="alert" data-testid="refusal-screen">
+          <h1>Access refused</h1>
+          <p>{screen.message}</p>
+          <button type="button" onClick={() => { clearAuth(); window.history.replaceState({}, "", "/"); setScreen({ kind: "login" }); }}>
+            Sign out
+          </button>
+        </div>
+      );
+    case "app":
+      return <AdminShell />;
+  }
+}

admin/src/api/client.test.ts

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

admin/src/api/client.ts

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

admin/src/api/snapshot.ts

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

admin/src/auth/oidc.test.ts

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

admin/src/auth/oidc.ts

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

admin/src/auth/pkce.test.ts

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

admin/src/auth/pkce.ts

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

admin/src/config.test.ts

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

admin/src/config.ts

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

admin/src/index.css

@@ -0,0 +1,60 @@
+/* NestQuest Admin — global tokens + base.
+   Plain CubeCraft styling, mobile-first, 390x844 reference
+   (design/ADMIN-SPEC.md). Values mirror design/tokens/nestquest-admin-tokens.css,
+   re-scoped to :root for the standalone PWA. */
+
+:root {
+  --nq-brand-blue: #3b3ab8;
+  --nq-brand-purple: #a035cc;
+  --nq-brand-gradient: linear-gradient(135deg, var(--nq-brand-blue), var(--nq-brand-purple));
+  --nq-brand-gradient-h: linear-gradient(90deg, var(--nq-brand-blue), var(--nq-brand-purple));
+
+  --nq-a-page: #f4f4f6;
+  --nq-a-surface: #ffffff;
+  --nq-a-border: #e4e4ea;
+  --nq-a-divider: #ededf1;
+
+  --nq-a-ink: #18181d;
+  --nq-a-ink-secondary: #52525e;
+  --nq-a-ink-tertiary: #70707e;
+
+  --nq-a-success: #15803d;
+  --nq-a-danger: #dc2626;
+  --nq-a-danger-strong: #b91c1c;
+  --nq-a-info-bg: #dbeafe;
+  --nq-a-info-ink: #1e3a8a;
+  --nq-a-info-icon: #1d4ed8;
+
+  --nq-a-font: Nunito, system-ui, sans-serif;
+  --nq-a-size-screen: 24px;
+  --nq-a-size-stat: 22px;
+  --nq-a-size-meta: 11px;
+
+  --nq-a-density-gap: 10px;
+  --nq-a-density-card-pad: 13px;
+  --nq-a-density-row-pad: 11px 13px;
+  --nq-a-density-radius: 8px;
+
+  --nq-a-tabbar-height: 70px;
+  --nq-a-tap-min: 44px;
+  --nq-a-radius-pill: 9999px;
+  --nq-a-progress-height: 6px;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  margin: 0;
+  height: 100%;
+}
+
+body {
+  font-family: var(--nq-a-font);
+  background: var(--nq-a-page);
+  color: var(--nq-a-ink);
+  -webkit-font-smoothing: antialiased;
+}

admin/src/main.tsx

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

admin/src/pwa/pwa.test.ts

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

admin/src/pwa/register.ts

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

admin/src/today/TodayTab.css

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

admin/src/today/TodayTab.test.tsx

@@ -0,0 +1,223 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+import TodayTab, { PERMISSION_NOTE } from "./TodayTab";
+import type { AdminSnapshot, SnapshotInstance } from "../api/snapshot";
+import { storeTokens } from "../auth/oidc";
+
+function instance(overrides: Partial<SnapshotInstance>): SnapshotInstance {
+  return {
+    id: 0,
+    definition_id: 1,
+    child_id: 1,
+    title: "Quest",
+    icon: null,
+    window: "morning",
+    due_time: null,
+    state: "open",
+    overdue: false,
+    completed_at: null,
+    on_time: null,
+    ...overrides,
+  };
+}
+
+const SNAPSHOT: AdminSnapshot = {
+  today_iso: "2026-09-23",
+  cycle_day: 5,
+  children: [
+    {
+      child_id: 1,
+      child_name: "Declan",
+      present: true,
+      next_present: null,
+      due_today: 7,
+      completed_today: 3,
+      remaining_today: 4,
+      completion_pct: 43,
+      instances: [
+        instance({ id: 11, title: "Brush teeth", due_time: "07:30", overdue: true }),
+        instance({
+          id: 12,
+          title: "Make bed",
+          state: "completed",
+          completed_at: "2026-09-23T11:04:00Z",
+          on_time: true,
+        }),
+        instance({ id: 13, title: "Homework", window: "afternoon", due_time: "16:00" }),
+        // Overdue but already completed: not counted as overdue.
+        instance({
+          id: 14,
+          title: "Pack bag",
+          state: "completed",
+          overdue: true,
+          completed_at: "2026-09-23T10:00:00Z",
+          on_time: false,
+        }),
+      ],
+    },
+    {
+      child_id: 2,
+      child_name: "Maeve",
+      present: true,
+      next_present: null,
+      due_today: 4,
+      completed_today: 4,
+      remaining_today: 0,
+      completion_pct: 100,
+      instances: [],
+    },
+    {
+      child_id: 3,
+      child_name: "Rory",
+      present: false,
+      next_present: "2026-10-01",
+      due_today: 0,
+      completed_today: 0,
+      remaining_today: 0,
+      completion_pct: 0,
+      instances: [],
+    },
+  ],
+};
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+async function renderReady() {
+  fetchMock.mockResolvedValue(jsonResponse(SNAPSHOT));
+  render(<TodayTab />);
+  await screen.findByText("Declan");
+}
+
+describe("TodayTab", () => {
+  beforeAll(() => {
+    // A negative-offset zone: `new Date("2026-09-23")` would read as Sep 22 here.
+    vi.stubEnv("TZ", "America/Los_Angeles");
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+  });
+
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("fetches the admin snapshot with the Bearer token", async () => {
+    await renderReady();
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toMatch(/\/api\/v1\/admin\/snapshot$/);
+    expect(init.headers.Authorization).toBe("Bearer at-123");
+  });
+
+  it("header shows the weekday, date and cycle day", async () => {
+    await renderReady();
+    expect(screen.getByRole("heading", { name: "Today" })).toBeTruthy();
+    expect(screen.getByText("Wednesday, September 23 · cycle day 5 of 14")).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Settings" })).toBeTruthy();
+  });
+
+  it("stat row shows done, remaining and overdue totals", async () => {
+    await renderReady();
+    expect(screen.getByTestId("stat-done").textContent).toBe("7Done");
+    expect(screen.getByTestId("stat-remaining").textContent).toBe("4Remaining");
+    expect(screen.getByTestId("stat-overdue").textContent).toBe("1Overdue");
+  });
+
+  it("present child row shows progress meta and fill", async () => {
+    await renderReady();
+    const row = screen.getByTestId("child-1");
+    expect(within(row).getByText("3 of 7 · 1 overdue")).toBeTruthy();
+    const bar = within(row).getByRole("progressbar");
+    expect(bar.getAttribute("aria-valuenow")).toBe("43");
+    expect((bar.firstElementChild as HTMLElement).style.width).toBe("43%");
+    expect(row.className).not.toContain("today-child--away");
+  });
+
+  it("all-done child renders the success state", async () => {
+    await renderReady();
+    const meta = within(screen.getByTestId("child-2")).getByText("4 of 4 · all done");
+    expect(meta.className).toContain("today-child-meta--done");
+  });
+
+  it("away child shows the return date and the flat avatar", async () => {
+    await renderReady();
+    const row = screen.getByTestId("child-3");
+    expect(within(row).getByText("Away · returns Oct 1")).toBeTruthy();
+    expect(row.className).toContain("today-child--away");
+    expect(within(row).getByTestId("child-avatar").textContent).toBe("R");
+  });
+
+  it("needs-attention lists overdue and completed rows with their actions", async () => {
+    await renderReady();
+    const list = screen.getByRole("list", { name: "Needs attention" });
+    const overdue = within(list).getByTestId("attention-11");
+    expect(within(overdue).getByText("Brush teeth · Declan")).toBeTruthy();
+    expect(within(overdue).getByText("Overdue since 7:30 AM")).toBeTruthy();
+    expect(within(overdue).getByRole("button", { name: "Mark done" })).toBeTruthy();
+
+    const completed = within(list).getByTestId("attention-12");
+    expect(within(completed).getByText("Make bed · Declan")).toBeTruthy();
+    // 11:04Z is 4:04 AM in Los Angeles (PDT).
+    expect(within(completed).getByText("Completed 4:04 AM")).toBeTruthy();
+    expect(within(completed).getByRole("button", { name: "Undo" })).toBeTruthy();
+
+    // Open, not-overdue instances do not need attention.
+    expect(within(list).queryByTestId("attention-13")).toBeNull();
+    // No actor in the payload, so no "from panel".
+    expect(list.textContent).not.toContain("from panel");
+  });
+
+  it("permission note carries the exact copy", async () => {
+    await renderReady();
+    expect(PERMISSION_NOTE).toBe(
+      "Undo is admin-only. A panel tap can never reverse a completion.",
+    );
+    expect(screen.getByTestId("permission-note").textContent).toBe(PERMISSION_NOTE);
+  });
+
+  it("scroll column ends with 92px bottom padding", async () => {
+    await renderReady();
+    expect(screen.getByTestId("today-scroll").style.paddingBottom).toBe("92px");
+  });
+
+  it("shows a loading state while the snapshot is in flight", () => {
+    fetchMock.mockReturnValue(new Promise<Response>(() => {}));
+    render(<TodayTab />);
+    expect(screen.getByTestId("today-loading").textContent).toContain("Loading");
+    expect(screen.getByTestId("today-scroll").style.paddingBottom).toBe("92px");
+  });
+
+  it("shows an error state on a failed fetch and retries", async () => {
+    fetchMock.mockResolvedValueOnce(new Response("boom", { status: 500 }));
+    render(<TodayTab />);
+    const error = await screen.findByTestId("today-error");
+    expect(error.getAttribute("role")).toBe("alert");
+    expect(error.textContent).toContain("could not be loaded");
+
+    fetchMock.mockResolvedValueOnce(jsonResponse(SNAPSHOT));
+    fireEvent.click(screen.getByRole("button", { name: "Try again" }));
+    expect(await screen.findByText("Declan")).toBeTruthy();
+  });
+
+  it("shows the refusal message when the API answers 403", async () => {
+    fetchMock.mockResolvedValueOnce(new Response("", { status: 403 }));
+    render(<TodayTab />);
+    const error = await screen.findByTestId("today-error");
+    expect(error.textContent).toContain("nestquest-admins");
+  });
+});

admin/src/today/TodayTab.tsx

@@ -0,0 +1,277 @@
+/**
+ * Today tab — compact density (design/ADMIN-SPEC.md §2.1–2.3, §2.5–2.6).
+ */
+import { useEffect, useState } from "react";
+import {
+  fetchSnapshot,
+  type AdminSnapshot,
+  type SnapshotChild,
+  type SnapshotInstance,
+} from "../api/snapshot";
+import { ApiForbiddenError } from "../api/client";
+import {
+  formatClockTime,
+  formatDueTime,
+  formatLongDate,
+  formatShortDate,
+} from "./format";
+import {
+  AlertCircleGlyph,
+  CheckCircleGlyph,
+  InfoGlyph,
+  SettingsGlyph,
+} from "./glyphs";
+import "./TodayTab.css";
+
+const CYCLE_LENGTH_DAYS = 14;
+
+/** ADMIN-SPEC §1: every scroll column ends with 92px so content clears the tab bar. */
+export const SCROLL_BOTTOM_PADDING = "92px";
+
+export const PERMISSION_NOTE =
+  "Undo is admin-only. A panel tap can never reverse a completion.";
+
+type LoadState =
+  | { kind: "loading" }
+  | { kind: "error"; message: string }
+  | { kind: "ready"; snapshot: AdminSnapshot };
+
+function isOverdueOpen(instance: SnapshotInstance): boolean {
+  return instance.overdue && instance.state === "open";
+}
+
+function ScreenHeader({ sub }: { sub: string }) {
+  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">
+        <SettingsGlyph />
+      </button>
+    </header>
+  );
+}
+
+function StatRow({ snapshot }: { snapshot: AdminSnapshot }) {
+  const done = snapshot.children.reduce((sum, c) => sum + c.completed_today, 0);
+  const remaining = snapshot.children.reduce((sum, c) => sum + c.remaining_today, 0);
+  const overdue = snapshot.children.reduce(
+    (sum, c) => sum + c.instances.filter(isOverdueOpen).length,
+    0,
+  );
+  const stats = [
+    { key: "done", label: "Done", value: done },
+    { key: "remaining", label: "Remaining", value: remaining },
+    { key: "overdue", label: "Overdue", value: overdue },
+  ];
+  return (
+    <div className="today-stats">
+      {stats.map((stat) => (
+        <div key={stat.key} className="today-stat" data-testid={`stat-${stat.key}`}>
+          <div className={`today-stat-value today-stat-value--${stat.key}`}>
+            {stat.value}
+          </div>
+          <div className="today-stat-label">{stat.label}</div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function ChildRow({ child }: { child: SnapshotChild }) {
+  const overdue = child.instances.filter(isOverdueOpen).length;
+  const allDone = child.due_today > 0 && child.completed_today === child.due_today;
+  let meta: string;
+  let metaClass = "today-child-meta";
+  if (!child.present) {
+    meta = child.next_present
+      ? `Away · returns ${formatShortDate(child.next_present)}`
+      : "Away";
+  } else if (allDone) {
+    meta = `${child.completed_today} of ${child.due_today} · all done`;
+    metaClass += " today-child-meta--done";
+  } else {
+    meta = `${child.completed_today} of ${child.due_today} · ${overdue} overdue`;
+  }
+  const pct = Math.max(0, Math.min(100, child.completion_pct));
+  // ADMIN-SPEC §2.3 also asks for a lowercase `override` pill when an absence
+  // comes from a presence override. The snapshot carries no field saying
+  // where an absence came from, so the pill is omitted rather than guessed.
+  return (
+    <li
+      className={child.present ? "today-child" : "today-child today-child--away"}
+      data-testid={`child-${child.child_id}`}
+    >
+      <span className="today-avatar" data-testid="child-avatar" aria-hidden="true">
+        {child.child_name.charAt(0).toUpperCase()}
+      </span>
+      <div className="today-child-text">
+        <div className="today-child-name">{child.child_name}</div>
+        <div className={metaClass}>{meta}</div>
+      </div>
+      <div
+        className="today-progress"
+        role="progressbar"
+        aria-label={`${child.child_name} progress`}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-valuenow={pct}
+      >
+        <div className="today-progress-fill" style={{ width: `${pct}%` }} />
+      </div>
+    </li>
+  );
+}
+
+interface AttentionItem {
+  instance: SnapshotInstance;
+  childName: string;
+}
+
+function attentionItems(snapshot: AdminSnapshot): AttentionItem[] {
+  const all = snapshot.children.flatMap((child) =>
+    child.instances.map((instance) => ({ instance, childName: child.child_name })),
+  );
+  const overdue = all.filter((item) => isOverdueOpen(item.instance));
+  const completed = all
+    .filter((item) => item.instance.state === "completed" && item.instance.completed_at)
+    .sort((a, b) =>
+      (b.instance.completed_at ?? "").localeCompare(a.instance.completed_at ?? ""),
+    );
+  return [...overdue, ...completed];
+}
+
+function AttentionRow({ item }: { item: AttentionItem }) {
+  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.
+  return (
+    <li className="today-event" data-testid={`attention-${instance.id}`}>
+      <span
+        className={overdue ? "today-event-glyph today-event-glyph--overdue" : "today-event-glyph"}
+      >
+        {overdue ? <AlertCircleGlyph /> : <CheckCircleGlyph />}
+      </span>
+      <div className="today-event-text">
+        <div className="today-event-title">
+          {instance.title} · {childName}
+        </div>
+        {overdue ? (
+          <div className="today-event-meta today-event-meta--overdue">
+            {instance.due_time
+              ? `Overdue since ${formatDueTime(instance.due_time)}`
+              : "Overdue"}
+          </div>
+        ) : (
+          // The snapshot carries no completion actor, so "from panel" is not printed.
+          <div className="today-event-meta">
+            Completed {formatClockTime(instance.completed_at as string)}
+          </div>
+        )}
+      </div>
+      <button
+        type="button"
+        className={overdue ? "today-action today-action--done" : "today-action today-action--undo"}
+      >
+        {overdue ? "Mark done" : "Undo"}
+      </button>
+    </li>
+  );
+}
+
+function PermissionNote() {
+  return (
+    <div className="today-note" data-testid="permission-note">
+      <span className="today-note-glyph">
+        <InfoGlyph />
+      </span>
+      <span>{PERMISSION_NOTE}</span>
+    </div>
+  );
+}
+
+export default function TodayTab() {
+  const [state, setState] = useState<LoadState>({ kind: "loading" });
+  const [attempt, setAttempt] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    setState({ kind: "loading" });
+    fetchSnapshot()
+      .then((snapshot) => {
+        if (!cancelled) setState({ kind: "ready", snapshot });
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        const message =
+          error instanceof ApiForbiddenError
+            ? error.message
+            : "Today's snapshot could not be loaded. Check your connection and try again.";
+        setState({ kind: "error", message });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [attempt]);
+
+  let sub = "";
+  let body;
+  if (state.kind === "loading") {
+    body = (
+      <div className="today-status" role="status" data-testid="today-loading">
+        Loading today…
+      </div>
+    );
+  } else if (state.kind === "error") {
+    body = (
+      <div className="today-status today-status--error" role="alert" data-testid="today-error">
+        <p>{state.message}</p>
+        <button type="button" className="today-retry" onClick={() => setAttempt((n) => n + 1)}>
+          Try again
+        </button>
+      </div>
+    );
+  } else {
+    const { snapshot } = state;
+    sub = `${formatLongDate(snapshot.today_iso)} · cycle day ${snapshot.cycle_day} of ${CYCLE_LENGTH_DAYS}`;
+    const attention = attentionItems(snapshot);
+    body = (
+      <>
+        <StatRow snapshot={snapshot} />
+        <ul className="today-card today-list" aria-label="Children">
+          {snapshot.children.map((child) => (
+            <ChildRow key={child.child_id} child={child} />
+          ))}
+        </ul>
+        <h3 className="today-section-label">Needs attention</h3>
+        {attention.length > 0 ? (
+          <ul className="today-card today-list" aria-label="Needs attention">
+            {attention.map((item) => (
+              <AttentionRow key={item.instance.id} item={item} />
+            ))}
+          </ul>
+        ) : (
+          <div className="today-card today-empty">Nothing needs attention.</div>
+        )}
+        <PermissionNote />
+      </>
+    );
+  }
+
+  return (
+    <div className="today-screen">
+      <ScreenHeader sub={sub} />
+      <div
+        className="today-scroll"
+        data-testid="today-scroll"
+        style={{ paddingBottom: SCROLL_BOTTOM_PADDING }}
+      >
+        {body}
+      </div>
+    </div>
+  );
+}

admin/src/today/format.ts

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

admin/src/today/glyphs.tsx

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

admin/tsconfig.json

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

admin/vite-sw-plugin.ts

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

admin/vite.config.ts

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

api/routes_admin.py

@@ -251,7 +251,7 @@ import datetime
 from typing import Annotated, Literal, NoReturn
 
 from fastapi import APIRouter, Depends, HTTPException, Request, Response
-from pydantic import BaseModel, StrictBool, field_validator, model_validator
+from pydantic import BaseModel, field_validator, model_validator
 
 from api import transitions as api_transitions
 from api.auth import require_admin
@@ -363,18 +363,11 @@ class AdminQuestDefinitionResponse(BaseModel):
     description: str | None
     icon: str | None
     is_active: bool
-    skip_on_away: bool
     rule: AdminRuleResponse
     assignees: list[AdminAssigneeResponse]
     windows: list[AdminDefinitionWindowResponse]
 
 
-class AdminQuestDefinitionListResponse(BaseModel):
-    """The definitions list: every definition, active AND inactive, by id."""
-
-    definitions: list[AdminQuestDefinitionResponse]
-
-
 class AdminChildCreateRequest(BaseModel):
     """The body of ``POST /api/v1/admin/children``.
 
@@ -451,9 +444,8 @@ class AdminQuestDefinitionCreateRequest(BaseModel):
     ``title``, ``rule``, ``assignee_child_ids`` and ``windows`` are
     required (the core rejects an empty title, a non-list or empty
     assignee/window list, and unknown window names); ``description``
-    and ``icon`` are optional and default to NULL through the core, and
-    ``skip_on_away`` is optional and defaults to true (no instance on a
-    date the child is absent).  ``windows`` entries are a window name (``morning``) or a two-item
+    and ``icon`` are optional and default to NULL through the core.
+    ``windows`` entries are a window name (``morning``) or a two-item
     ``[window, due_time]`` pair whose due time is a strict 24-hour
     HH:MM (or ``null`` for none) — both forms the core normalizes.
     """
@@ -464,7 +456,6 @@ class AdminQuestDefinitionCreateRequest(BaseModel):
     windows: list[str | tuple[str, str | None]]
     description: str | None = None
     icon: str | None = None
-    skip_on_away: StrictBool = True
 
 
 class AdminQuestDefinitionEditRequest(BaseModel):
@@ -479,8 +470,7 @@ class AdminQuestDefinitionEditRequest(BaseModel):
     ``rule`` or ``windows`` is passed and rejected by the core.  A
     supplied ``windows`` list REPLACES the whole window set, and
     ``assignees`` are deliberately absent — assignment is not settable
-    through this route.  An omitted (or ``null``) ``skip_on_away``
-    keeps the stored value.
+    through this route.
     """
 
     title: str | None = None
@@ -488,7 +478,6 @@ class AdminQuestDefinitionEditRequest(BaseModel):
     icon: str | None = None
     rule: AdminRuleRequest | None = None
     windows: list[str | tuple[str, str | None]] | None = None
-    skip_on_away: StrictBool | None = None
 
 
 class AdminQuestDefinitionActiveRequest(BaseModel):
@@ -968,7 +957,6 @@ def _quest_definition_response(
         description=bundle.definition.description,
         icon=bundle.definition.icon,
         is_active=bundle.definition.is_active,
-        skip_on_away=bundle.definition.skip_on_away,
         rule=_rule_response(bundle.rule),
         assignees=[
             AdminAssigneeResponse(id=child.id, display_name=child.display_name)
@@ -1180,32 +1168,6 @@ async def admin_reorder_children(
     return {"status": "ok"}
 
 
-@router.get(
-    "/quest-definitions",
-    summary="List quest definitions",
-    response_model=AdminQuestDefinitionListResponse,
-)
-async def admin_list_quest_definitions(
-    request: Request,
-) -> AdminQuestDefinitionListResponse:
-    """Return every quest definition in rising id order.
-
-    Requires a valid admin JWT (the router's shared
-    :func:`~api.auth.require_admin` dependency — the ONE check; this
-    handler performs NO auth of its own).  Thin adapter: one
-    :func:`nestquest_core.quest_definitions.list_all_definitions` call,
-    active AND inactive definitions included (the admin screen manages
-    both), each serialized exactly as the create/edit responses are.
-    """
-    state: DatabaseState = request.app.state.db
-    bundles = await core_quest_definitions.list_all_definitions(
-        state.database
-    )
-    return AdminQuestDefinitionListResponse(
-        definitions=[_quest_definition_response(bundle) for bundle in bundles]
-    )
-
-
 @router.post(
     "/quest-definitions",
     summary="Create a quest definition",
@@ -1240,7 +1202,6 @@ async def admin_create_quest_definition(
             body.windows,
             description=body.description,
             icon=body.icon,
-            skip_on_away=body.skip_on_away,
         )
     except ValueError as error:
         _raise_quest_definition_error(error)

custom_components/nestquest/core/dao_rules.py

@@ -105,19 +105,6 @@ 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``."""
@@ -165,7 +152,6 @@ class QuestDefinitionRecord:
     due_time: str | None
     is_active: bool
     created_at: str
-    skip_on_away: bool
 
 
 @dataclass(frozen=True)
@@ -201,7 +187,7 @@ _RULE_COLUMNS = (
 )
 _DEFINITION_COLUMNS = (
     "id, title, description, icon, schedule_rule_id, due_time, "
-    "is_active, created_at, skip_on_away"
+    "is_active, created_at"
 )
 _WINDOW_COLUMNS = "definition_id, window, due_time"
 
@@ -230,7 +216,6 @@ 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]),
     )
 
 
@@ -647,7 +632,6 @@ 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.
 
@@ -660,7 +644,6 @@ 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)
@@ -669,8 +652,7 @@ class QuestDefinitionsDao:
                 result = await self._database.execute(
                     "INSERT INTO quest_definitions (title, description, "
                     "icon, schedule_rule_id, due_time, is_active, "
-                    "created_at, skip_on_away) "
-                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                    "created_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
                     (
                         title,
                         description,
@@ -679,7 +661,6 @@ class QuestDefinitionsDao:
                         due_time,
                         int(is_active),
                         created_at,
-                        skip_on_away_value,
                     ),
                 )
                 definition_id = result.lastrowid
@@ -703,7 +684,6 @@ class QuestDefinitionsDao:
         *,
         description: str | None = None,
         icon: str | None = None,
-        skip_on_away: bool = True,
     ) -> QuestDefinitionSnapshot:
         """Insert a rule, definition, assignees and windows atomically.
 
@@ -733,7 +713,6 @@ 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:
@@ -742,18 +721,8 @@ class QuestDefinitionsDao:
                 result = await self._database.execute(
                     "INSERT INTO quest_definitions (title, description, "
                     "icon, schedule_rule_id, due_time, is_active, "
-                    "created_at, skip_on_away) "
-                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
-                    (
-                        title,
-                        description,
-                        icon,
-                        rule_id,
-                        None,
-                        1,
-                        created_at,
-                        skip_on_away_value,
-                    ),
+                    "created_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    (title, description, icon, rule_id, None, 1, created_at),
                 )
                 definition_id = result.lastrowid
                 for child_id in assignee_child_ids:
@@ -795,7 +764,6 @@ 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,
     ) -> QuestDefinitionSnapshot:
         """Edit a definition's metadata, rule and windows atomically.
 
@@ -806,10 +774,9 @@ class QuestDefinitionsDao:
         ``_UNSET`` meaning "leave this field alone"; ``None`` writes SQL
         NULL so optional metadata (description, icon) can be cleared.
 
-        - ``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).
+        - ``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).
         - ``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
@@ -825,8 +792,6 @@ class QuestDefinitionsDao:
         does not exist.  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)
@@ -844,9 +809,6 @@ 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(
@@ -945,13 +907,6 @@ 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]:
@@ -996,18 +951,6 @@ 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.
 
@@ -1047,16 +990,13 @@ 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).  ``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
+        (description, icon, due_time).  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
@@ -1073,9 +1013,6 @@ 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)

custom_components/nestquest/core/materialize.py

@@ -18,8 +18,7 @@ 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 (or every assignee, when the definition's
-  ``skip_on_away`` is off) and each declared window, one instance is
+  ``is_present`` on that date 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).
@@ -209,8 +208,7 @@ async def materialize(
 
     definitions = [
         (snapshot.definition.id, _decode_rule(snapshot),
-         snapshot.assignees, snapshot.windows,
-         snapshot.definition.skip_on_away)
+         snapshot.assignees, snapshot.windows)
         for snapshot in snapshots
     ]
 
@@ -231,15 +229,13 @@ async def materialize(
     cursor = start
     while cursor <= end:
         iso = cursor.isoformat()
-        for (
-            definition_id, rule, assignees, windows, skip_on_away
-        ) in definitions:
+        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 skip_on_away and not engine.is_present(child.id, cursor):
+                if not engine.is_present(child.id, cursor):
                     continue
                 for window in windows:
                     written = await instances.upsert_if_valid(

custom_components/nestquest/core/migrations.py

@@ -30,9 +30,8 @@ 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).  Migration 8 adds the ``skip_on_away``
-column to ``quest_definitions`` (Feature 22), defaulting to 1.  Each
-callable migration runs inside its own transaction
+missed-sweep watermark).  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.
 
@@ -401,28 +400,6 @@ 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.)
@@ -446,10 +423,6 @@ 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,
 ]
 
 

custom_components/nestquest/core/quest_definitions.py

@@ -191,17 +191,6 @@ 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.
 
@@ -223,7 +212,6 @@ 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.
 
@@ -243,7 +231,6 @@ async def create_quest_definition(
     window_specs = _normalize_windows(windows)
     description_value = _validate_text(description, "description")
     icon_value = _validate_text(icon, "icon")
-    skip_on_away_value = _validate_skip_on_away(skip_on_away)
 
     storage = schedule_rule_to_storage(rule)
     dao = QuestDefinitionsDao(database)
@@ -256,7 +243,6 @@ 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
@@ -285,7 +271,6 @@ 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,
     today: datetime.date | None = None,
     horizon_days: int | None = None,
 ) -> CreatedQuestDefinition:
@@ -300,9 +285,7 @@ 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.  A provided
-    ``skip_on_away`` (a real bool) replaces the stored flag; ``None``
-    leaves it unchanged.  Assignment is NOT
+    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.
 
@@ -348,10 +331,6 @@ async def edit_quest_definition(
     if windows is not _UNSET:
         window_specs = _normalize_windows(windows)
 
-    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(
@@ -361,7 +340,6 @@ async def edit_quest_definition(
             icon=icon_value,
             rule=rule_storage,
             windows=window_specs,
-            skip_on_away=skip_on_away_value,
         )
     except ValueError as error:
         # The DAO's missing-definition error names only the id; re-raise
@@ -580,21 +558,6 @@ 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

@@ -257,8 +257,7 @@ 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,
-    skip_on_away INTEGER NOT NULL DEFAULT 1 CHECK (skip_on_away IN (0, 1))
+    created_at TEXT NOT NULL
 )"""
 
 SCHEMA_V1_QUEST_DEFINITIONS_DDL: list[str] = [

tests/test_api_admin_questdef.py

@@ -215,7 +215,6 @@ async def test_create_persists_definition_with_assignees_and_windows(
         "description",
         "icon",
         "is_active",
-        "skip_on_away",
         "rule",
         "assignees",
         "windows",
@@ -224,7 +223,6 @@ async def test_create_persists_definition_with_assignees_and_windows(
     assert payload["description"] == "Put everything back where it belongs."
     assert payload["icon"] == "toy-box"
     assert payload["is_active"] is True
-    assert payload["skip_on_away"] is True
     assert payload["rule"] == _weekly_rule_dict()
     assert {a["id"]: a["display_name"] for a in payload["assignees"]} == {
         ada: "Ada",
@@ -523,130 +521,9 @@ async def test_edit_rejections_are_422_and_change_nothing(
     }
 
 
-@pytest.mark.parametrize("coercible", [0, 1, "true", "false"])
-async def test_create_rejects_coercible_skip_on_away_and_persists_nothing(
-    admin_questdefs: SimpleNamespace, coercible: object
-) -> None:
-    """A numeric or string skip_on_away is 422, not coerced to a bool."""
-    client = admin_questdefs.client
-    dao = _dao_rules.QuestDefinitionsDao(admin_questdefs.database)
-    ada = (await _create_children(client, ("Ada",)))[0]
-    existing = await client.post(
-        "/api/v1/admin/quest-definitions",
-        json={
-            "title": "Feed the cat",
-            "rule": _weekly_rule_body(),
-            "assignee_child_ids": [ada],
-            "windows": ["morning"],
-            "skip_on_away": False,
-        },
-        headers=_admin_headers(),
-    )
-    assert existing.status_code == 201
-    existing_id = existing.json()["id"]
-
-    response = await client.post(
-        "/api/v1/admin/quest-definitions",
-        json={
-            "title": "Tidy the den",
-            "rule": _weekly_rule_body(),
-            "assignee_child_ids": [ada],
-            "windows": ["morning"],
-            "skip_on_away": coercible,
-        },
-        headers=_admin_headers(),
-    )
-    assert response.status_code == 422
-    assert set(await _definitions_by_id(admin_questdefs.database)) == {
-        existing_id
-    }
-    assert (await dao.get(existing_id)).skip_on_away is False
-
-
-@pytest.mark.parametrize("coercible", [0, 1, "true", "false"])
-async def test_edit_rejects_coercible_skip_on_away_and_changes_nothing(
-    admin_questdefs: SimpleNamespace, coercible: object
-) -> None:
-    """A numeric or string skip_on_away edit is 422; the flag is kept."""
-    client = admin_questdefs.client
-    dao = _dao_rules.QuestDefinitionsDao(admin_questdefs.database)
-    ada = (await _create_children(client, ("Ada",)))[0]
-    definition_id = (await _create_definition(client, [ada])).json()["id"]
-    # Start from each stored value so a coerced write would be visible.
-    for stored in (True, False):
-        set_flag = await client.patch(
-            f"/api/v1/admin/quest-definitions/{definition_id}",
-            json={"skip_on_away": stored},
-            headers=_admin_headers(),
-        )
-        assert set_flag.status_code == 200
-
-        response = await client.patch(
-            f"/api/v1/admin/quest-definitions/{definition_id}",
-            json={"skip_on_away": coercible, "title": "Renamed"},
-            headers=_admin_headers(),
-        )
-        assert response.status_code == 422
-        stored_definition = await dao.get(definition_id)
-        assert stored_definition.skip_on_away is stored
-        assert stored_definition.title == "Tidy the den"
-
-
 # --- set_active -------------------------------------------------------------
 
 
-async def test_edit_toggles_skip_on_away_and_omission_keeps_it(
-    admin_questdefs: SimpleNamespace,
-) -> None:
-    """A supplied skip_on_away persists; an edit omitting it keeps it."""
-    client = admin_questdefs.client
-    dao = _dao_rules.QuestDefinitionsDao(admin_questdefs.database)
-    ada = (await _create_children(client, ("Ada",)))[0]
-    created = await _create_definition(client, [ada])
-    assert created.status_code == 201
-    definition_id = created.json()["id"]
-    assert created.json()["skip_on_away"] is True
-
-    toggled_off = await client.patch(
-        f"/api/v1/admin/quest-definitions/{definition_id}",
-        json={"skip_on_away": False},
-        headers=_admin_headers(),
-    )
-    assert toggled_off.status_code == 200
-    assert toggled_off.json()["skip_on_away"] is False
-    assert (await dao.get(definition_id)).skip_on_away is False
-
-    # An edit that omits the flag leaves the stored False untouched.
-    renamed = await client.patch(
-        f"/api/v1/admin/quest-definitions/{definition_id}",
-        json={"title": "Tidy the den properly"},
-        headers=_admin_headers(),
-    )
-    assert renamed.status_code == 200
-    assert renamed.json()["skip_on_away"] is False
-    stored = await dao.get(definition_id)
-    assert stored.title == "Tidy the den properly"
-    assert stored.skip_on_away is False
-
-    toggled_on = await client.patch(
-        f"/api/v1/admin/quest-definitions/{definition_id}",
-        json={"skip_on_away": True},
-        headers=_admin_headers(),
-    )
-    assert toggled_on.status_code == 200
-    assert toggled_on.json()["skip_on_away"] is True
-    assert (await dao.get(definition_id)).skip_on_away is True
-
-    # A non-boolean value is a malformed body: 422, nothing changes.
-    rejected = await client.patch(
-        f"/api/v1/admin/quest-definitions/{definition_id}",
-        json={"skip_on_away": "sometimes"},
-        headers=_admin_headers(),
-    )
-    assert rejected.status_code == 422
-    assert (await dao.get(definition_id)).skip_on_away is True
-
-
 async def test_set_active_toggles_the_flag_and_the_definition_survives(
     admin_questdefs: SimpleNamespace,
 ) -> None:

tests/test_api_admin_questdef_list.py

@@ -1,299 +0,0 @@
-"""Admin-plane quest-definition LIST route tests (task d4667573).
-
-``GET /api/v1/admin/quest-definitions`` 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.
-
-- An admin JWT lists EVERY definition — active AND inactive — in rising
-  id order, each in the same documented shape as the create/edit
-  responses (id, title, description, icon, is_active, rule, assignees,
-  windows).
-- An empty household lists nothing: 200 with an empty list.
-- Authentication runs through the router's ONE ``require_admin``
-  dependency: an absent credential is 401, the panel service token is
-  refused outright (403, the credential-type detail), and a JWT without
-  the nestquest-admins group is 403.
-"""
-from __future__ import annotations
-
-from types import SimpleNamespace
-
-import pytest
-
-from tests.admin_jwt_harness import (
-    ADMIN_KEY,
-    KID,
-    AdminRunner,
-    jwks_for,
-    make_token,
-)
-
-#: The admin list route under test.
-LIST_PATH = "/api/v1/admin/quest-definitions"
-
-#: 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"
-)
-
-
-def _admin_headers() -> dict[str, str]:
-    """The Authorization header of a valid nestquest-admins JWT."""
-    return {"Authorization": f"Bearer {make_token()}"}
-
-
-@pytest.fixture
-async def admin_client(temp_db_path: str) -> SimpleNamespace:
-    """An admin-plane app client over a fresh (empty) household."""
-    runner = AdminRunner(temp_db_path, jwks_for(ADMIN_KEY, KID))
-    async with runner as client:
-        yield client
-
-
-async def _seed_active_and_inactive(client: object) -> tuple[int, int, int]:
-    """Seed one child, an ACTIVE definition and an INACTIVE one.
-
-    Returns ``(child_id, active_id, inactive_id)``.  Seeded through the
-    admin routes so the rows are exactly what the admin plane writes.
-    """
-    child = await client.post(
-        "/api/v1/admin/children",
-        json={"display_name": "Ada"},
-        headers=_admin_headers(),
-    )
-    assert child.status_code == 201
-    child_id = child.json()["id"]
-
-    active = await client.post(
-        LIST_PATH,
-        json={
-            "title": "Tidy the den",
-            "rule": {
-                "rule_type": "weekly",
-                "interval": 1,
-                "weekday_set": [0, 2],
-                "start_date": "2026-03-02",
-            },
-            "assignee_child_ids": [child_id],
-            "windows": ["morning", ["evening", "19:30"]],
-            "description": "Put everything back where it belongs.",
-            "icon": "toy-box",
-        },
-        headers=_admin_headers(),
-    )
-    assert active.status_code == 201
-
-    inactive = await client.post(
-        LIST_PATH,
-        json={
-            "title": "Water the plants",
-            "rule": {
-                "rule_type": "daily",
-                "interval": 1,
-                "start_date": "2026-03-01",
-            },
-            "assignee_child_ids": [child_id],
-            "windows": ["afternoon"],
-        },
-        headers=_admin_headers(),
-    )
-    assert inactive.status_code == 201
-    inactive_id = inactive.json()["id"]
-    deactivated = await client.patch(
-        f"{LIST_PATH}/{inactive_id}/active",
-        json={"is_active": False},
-        headers=_admin_headers(),
-    )
-    assert deactivated.status_code == 200
-
-    return child_id, active.json()["id"], inactive_id
-
-
-async def test_admin_lists_active_and_inactive_definitions_with_full_shape(
-    admin_client: object,
-) -> None:
-    """Both definitions come back, by rising id, in the documented shape."""
-    child_id, active_id, inactive_id = await _seed_active_and_inactive(
-        admin_client
-    )
-
-    response = await admin_client.get(LIST_PATH, headers=_admin_headers())
-
-    assert response.status_code == 200
-    assert response.json() == {
-        "definitions": [
-            {
-                "id": active_id,
-                "title": "Tidy the den",
-                "description": "Put everything back where it belongs.",
-                "icon": "toy-box",
-                "is_active": True,
-                "skip_on_away": True,
-                "rule": {
-                    "rule_type": "weekly",
-                    "interval": 1,
-                    "weekday_set": [0, 2],
-                    "day_of_month": None,
-                    "nth_weekday": None,
-                    "nth_weekday_weekday": None,
-                    "month": None,
-                    "start_date": "2026-03-02",
-                    "end_date": None,
-                },
-                "assignees": [{"id": child_id, "display_name": "Ada"}],
-                "windows": [
-                    {"window": "morning", "due_time": None},
-                    {"window": "evening", "due_time": "19:30"},
-                ],
-            },
-            {
-                "id": inactive_id,
-                "title": "Water the plants",
-                "description": None,
-                "icon": None,
-                "is_active": False,
-                "skip_on_away": True,
-                "rule": {
-                    "rule_type": "daily",
-                    "interval": 1,
-                    "weekday_set": None,
-                    "day_of_month": None,
-                    "nth_weekday": None,
-                    "nth_weekday_weekday": None,
-                    "month": None,
-                    "start_date": "2026-03-01",
-                    "end_date": None,
-                },
-                "assignees": [{"id": child_id, "display_name": "Ada"}],
-                "windows": [{"window": "afternoon", "due_time": None}],
-            },
-        ]
-    }
-
-
-async def test_list_items_match_the_create_response_shape(
-    admin_client: object,
-) -> None:
-    """Each listed item is exactly what the create route returned."""
-    child = await admin_client.post(
-        "/api/v1/admin/children",
-        json={"display_name": "Ben"},
-        headers=_admin_headers(),
-    )
-    created = await admin_client.post(
-        LIST_PATH,
-        json={
-            "title": "Feed the cat",
-            "rule": {
-                "rule_type": "daily",
-                "interval": 1,
-                "start_date": "2026-03-01",
-            },
-            "assignee_child_ids": [child.json()["id"]],
-            "windows": ["morning"],
-        },
-        headers=_admin_headers(),
-    )
-    assert created.status_code == 201
-
-    response = await admin_client.get(LIST_PATH, headers=_admin_headers())
-
-    assert response.status_code == 200
-    assert response.json() == {"definitions": [created.json()]}
-
-
-async def test_skip_on_away_round_trips_true_and_false_through_list(
-    admin_client: object,
-) -> None:
-    """skip_on_away posted true, false, or omitted lists back as stored."""
-    child = await admin_client.post(
-        "/api/v1/admin/children",
-        json={"display_name": "Cleo"},
-        headers=_admin_headers(),
-    )
-    child_id = child.json()["id"]
-
-    async def create(title: str, extra: dict[str, object]) -> dict:
-        response = await admin_client.post(
-            LIST_PATH,
-            json={
-                "title": title,
-                "rule": {
-                    "rule_type": "daily",
-                    "interval": 1,
-                    "start_date": "2026-03-01",
-                },
-                "assignee_child_ids": [child_id],
-                "windows": ["morning"],
-                **extra,
-            },
-            headers=_admin_headers(),
-        )
-        assert response.status_code == 201
-        return response.json()
-
-    skipping = await create("Skip when away", {"skip_on_away": True})
-    keeping = await create("Keep when away", {"skip_on_away": False})
-    defaulted = await create("Default", {})
-    assert skipping["skip_on_away"] is True
-    assert keeping["skip_on_away"] is False
-    assert defaulted["skip_on_away"] is True
-
-    response = await admin_client.get(LIST_PATH, headers=_admin_headers())
-
-    assert response.status_code == 200
-    listed = {item["id"]: item for item in response.json()["definitions"]}
-    assert listed[skipping["id"]]["skip_on_away"] is True
-    assert listed[keeping["id"]]["skip_on_away"] is False
-    assert listed[defaulted["id"]]["skip_on_away"] is True
-    assert response.json() == {"definitions": [skipping, keeping, defaulted]}
-
-
-async def test_empty_household_lists_no_definitions(
-    admin_client: object,
-) -> None:
-    """With no definitions stored the list is 200 and empty."""
-    response = await admin_client.get(LIST_PATH, headers=_admin_headers())
-
-    assert response.status_code == 200
-    assert response.json() == {"definitions": []}
-
-
-async def test_list_without_credentials_is_401(admin_client: object) -> None:
-    """An absent credential is the uniform 401."""
-    response = await admin_client.get(LIST_PATH)
-
-    assert response.status_code == 401
-
-
-async def test_list_with_panel_service_token_is_403(
-    admin_client: object,
-) -> None:
-    """The panel service token is refused outright, never a JWT."""
-    response = await admin_client.get(
-        LIST_PATH,
-        headers={"Authorization": f"Bearer {HARNESS_PANEL_TOKEN}"},
-    )
-
-    assert response.status_code == 403
-    assert response.json()["detail"] == PANEL_TOKEN_REJECTION_DETAIL
-
-
-async def test_list_with_non_admin_jwt_is_403(admin_client: object) -> None:
-    """A valid JWT without the nestquest-admins group is 403."""
-    non_admin = make_token(groups=("some-other-group",))
-    response = await admin_client.get(
-        LIST_PATH, headers={"Authorization": f"Bearer {non_admin}"}
-    )
-
-    assert response.status_code == 403
-    assert response.json()["detail"] == FORBIDDEN_DETAIL

tests/test_dao_rules.py

@@ -847,7 +847,6 @@ def test_definition_update_cannot_change_assignee_or_active(
             "description",
             "icon",
             "due_time",
-            "skip_on_away",
         }
         assert await definitions.update(
             definition.id, title="A2"
@@ -863,72 +862,6 @@ def test_definition_update_cannot_change_assignee_or_active(
     _with_db(tmp_path, "definition-update-shape.db")(_body)
 
 
-def test_definition_update_toggles_skip_on_away_and_omission_keeps_it(
-    tmp_path,
-) -> None:
-    async def _body(database, rules, definitions, children, child):
-        rule = await rules.create("daily", "2026-09-14")
-        definition = await definitions.create("A", rule.id, NOW)
-        assert definition.skip_on_away is True
-        assert await definitions.update(
-            definition.id, skip_on_away=False
-        ) == 1
-        assert (await definitions.get(definition.id)).skip_on_away is False
-        # Omitting the flag (None) leaves the stored False untouched.
-        assert await definitions.update(definition.id, title="A2") == 1
-        kept = await definitions.get(definition.id)
-        assert kept.title == "A2"
-        assert kept.skip_on_away is False
-        assert await definitions.update(definition.id) == 0
-        assert await definitions.update(
-            definition.id, skip_on_away=True
-        ) == 1
-        assert (await definitions.get(definition.id)).skip_on_away is True
-
-    _with_db(tmp_path, "definition-update-skip-on-away.db")(_body)
-
-
-@pytest.mark.parametrize("bad", [2, -1, 0.0, 1.5, "1", "true", b"\x01"])
-def test_skip_on_away_rejected_unless_zero_or_one_at_every_write(
-    tmp_path, bad
-) -> None:
-    """Every DAO entry point taking the flag rejects non-0/1 values.
-
-    This is the only guard on migrated databases, whose column was
-    added without the fresh-schema CHECK constraint.
-    """
-    async def _body(database, rules, definitions, children, child):
-        rule = await rules.create("daily", "2026-09-14")
-        definition = await definitions.create("A", rule.id, NOW)
-        with pytest.raises(ValueError, match="skip_on_away must be 0 or 1"):
-            await definitions.create("B", rule.id, NOW, skip_on_away=bad)
-        with pytest.raises(ValueError, match="skip_on_away must be 0 or 1"):
-            await definitions.create_with_rule_and_windows(
-                "C",
-                schedule_rule_to_storage(
-                    ScheduleRule(
-                        rule_type=RuleType.DAILY, start_date="2026-09-14"
-                    )
-                ),
-                NOW,
-                [child.id],
-                [("morning", None)],
-                skip_on_away=bad,
-            )
-        with pytest.raises(ValueError, match="skip_on_away must be 0 or 1"):
-            await definitions.edit_definition(
-                definition.id, title="A2", skip_on_away=bad
-            )
-        with pytest.raises(ValueError, match="skip_on_away must be 0 or 1"):
-            await definitions.update(
-                definition.id, title="A2", skip_on_away=bad
-            )
-        stored = await definitions.list_all()
-        assert [(d.title, d.skip_on_away) for d in stored] == [("A", True)]
-
-    _with_db(tmp_path, "definition-skip-on-away-invalid.db")(_body)
-
-
 def test_definition_update_no_fields_returns_zero(tmp_path) -> None:
     async def _body(database, rules, definitions, children, child):
         rule = await rules.create("daily", "2026-09-14")

tests/test_materialize.py

@@ -657,133 +657,6 @@ def test_materialize_honours_overrides(tmp_path) -> None:
     _with_db(tmp_path, "materialize-override.db")(_body)
 
 
-async def _absent_midweek_setup(database, skip_on_away: bool):
-    """One child absent on days 2..4 of a future week, one daily quest.
-
-    Returns ``(child_id, definition_id, start, end_iso, absent_dates)``.
-    """
-    from custom_components.nestquest.core.dao_presence import (
-        PresenceOverridesDao,
-    )
-
-    child = await ChildrenDao(database).create("Ada", NOW)
-    start = _future_monday()
-    end_iso = (start + datetime.timedelta(days=6)).isoformat()
-    absent = {
-        (start + datetime.timedelta(days=offset)).isoformat()
-        for offset in (2, 3, 4)
-    }
-    await PresenceOverridesDao(database).create(
-        child.id, min(absent), max(absent), False, note="away"
-    )
-    created = await create_quest_definition(
-        database,
-        "Daily chore",
-        ScheduleRule(rule_type=RuleType.DAILY, start_date=start.isoformat()),
-        [child.id],
-        ["morning"],
-        skip_on_away=skip_on_away,
-    )
-    assert created.definition.skip_on_away is skip_on_away
-    return child.id, created.definition.id, start, end_iso, absent
-
-
-def test_materialize_skip_on_away_true_skips_absent_dates(tmp_path) -> None:
-    async def _body(database):
-        child_id, _, start, end_iso, absent = await _absent_midweek_setup(
-            database, skip_on_away=True
-        )
-        count = await materialize(database, start.isoformat(), end_iso)
-        records = await QuestInstancesDao(database).list_by_date_range(
-            child_id, start.isoformat(), end_iso
-        )
-        due_dates = {record.due_date for record in records}
-        assert count == 4
-        assert due_dates.isdisjoint(absent)
-        assert len(due_dates) == 4
-
-    _with_db(tmp_path, "skip-on-away-true.db")(_body)
-
-
-def test_materialize_skip_on_away_false_generates_absent_dates(
-    tmp_path,
-) -> None:
-    async def _body(database):
-        child_id, _, start, end_iso, absent = await _absent_midweek_setup(
-            database, skip_on_away=False
-        )
-        count = await materialize(database, start.isoformat(), end_iso)
-        records = await QuestInstancesDao(database).list_by_date_range(
-            child_id, start.isoformat(), end_iso
-        )
-        due_dates = {record.due_date for record in records}
-        assert count == 7
-        assert absent <= due_dates
-        assert len(due_dates) == 7
-
-    _with_db(tmp_path, "skip-on-away-false.db")(_body)
-
-
-def test_edit_skip_on_away_regenerates_absent_dates(tmp_path) -> None:
-    """Toggling the flag through the edit path rebuilds future instances."""
-    async def _body(database):
-        child_id, definition_id, start, end_iso, absent = (
-            await _absent_midweek_setup(database, skip_on_away=True)
-        )
-        await materialize(database, start.isoformat(), end_iso)
-        dao = QuestInstancesDao(database)
-
-        async def due_dates() -> set[str]:
-            records = await dao.list_by_date_range(
-                child_id, start.isoformat(), end_iso
-            )
-            return {record.due_date for record in records}
-
-        assert (await due_dates()).isdisjoint(absent)
-
-        edited = await edit_quest_definition(
-            database, definition_id, skip_on_away=False
-        )
-        assert edited.definition.skip_on_away is False
-        assert absent <= await due_dates()
-
-        # None leaves the stored flag unchanged.
-        unchanged = await edit_quest_definition(
-            database, definition_id, title="Daily chore (renamed)"
-        )
-        assert unchanged.definition.skip_on_away is False
-
-        edited = await edit_quest_definition(
-            database, definition_id, skip_on_away=True
-        )
-        assert edited.definition.skip_on_away is True
-        assert (await due_dates()).isdisjoint(absent)
-
-    _with_db(tmp_path, "skip-on-away-edit.db")(_body)
-
-
-def test_skip_on_away_rejects_non_bool(tmp_path) -> None:
-    async def _body(database):
-        child = await ChildrenDao(database).create("Ada", NOW)
-        rule = ScheduleRule(rule_type=RuleType.DAILY, start_date="2026-01-01")
-        with pytest.raises(ValueError, match="skip_on_away must be a real bool"):
-            await create_quest_definition(
-                database, "Chore", rule, [child.id], ["morning"],
-                skip_on_away=1,
-            )
-        created = await create_quest_definition(
-            database, "Chore", rule, [child.id], ["morning"]
-        )
-        with pytest.raises(ValueError, match="skip_on_away must be a real bool"):
-            await edit_quest_definition(
-                database, created.definition.id, skip_on_away="false"
-            )
-        stored = await QuestDefinitionsDao(database).get(created.definition.id)
-        assert stored.skip_on_away is True
-
-    _with_db(tmp_path, "skip-on-away-validation.db")(_body)
-
-
 def test_materialize_rejects_malformed_or_inverted_bounds(tmp_path) -> None:
     async def _body(database):
         start = (_future_monday()).isoformat()

tests/test_migrations.py

@@ -153,9 +153,7 @@ def test_migration_list_shape() -> None:
     migration 3 brings pre-D-008 definitions to the multi-assignee
     model, migration 4 adds the windows table, migration 5 rebuilds
     quest_instances onto the widened (definition, child, date, window)
-    key, migration 6 adds actor_child_id to completion_events,
-    migration 7 adds the meta_state table and migration 8 adds
-    skip_on_away to quest_definitions.
+    key, and migration 6 adds actor_child_id to completion_events.
     """
     assert MIGRATIONS[0] == SCHEMA_V1_STATEMENTS
     assert callable(MIGRATIONS[1])
@@ -164,8 +162,7 @@ def test_migration_list_shape() -> None:
     assert callable(MIGRATIONS[4])
     assert callable(MIGRATIONS[5])
     assert MIGRATIONS[6] == SCHEMA_V7_META_STATE_DDL
-    assert callable(MIGRATIONS[7])
-    assert len(MIGRATIONS) == 8
+    assert len(MIGRATIONS) == 7
 
 
 # ---------------------------------------------------------------------------
@@ -567,13 +564,6 @@ def test_v2_definitions_rebuilt_to_multi_assignee(tmp_path) -> None:
             database.fetch_all("PRAGMA table_info(quest_definitions)")
         )
         assert "child_id" not in {c[1] for c in columns}
-        # The rebuilt row reads the pre-flag behaviour: skip on away.
-        skip = _run(
-            database.fetch_one(
-                "SELECT skip_on_away FROM quest_definitions WHERE id = 1"
-            )
-        )
-        assert skip == (1,)
         # The single assignee moved into the assignees table.
         assignees = _run(
             database.fetch_all(
@@ -647,87 +637,6 @@ def test_v2_definitions_rebuilt_to_multi_assignee(tmp_path) -> None:
         _run(database.close())
 
 
-# ---------------------------------------------------------------------------
-# Migration 8: skip_on_away on quest_definitions (Feature 22)
-# ---------------------------------------------------------------------------
-
-
-def _seed_v7_database(database) -> None:
-    """Build a genuine version-7 database holding one definition.
-
-    Migrations 1..7 run first; the fresh v1 DDL already carries
-    ``skip_on_away`` (canonical shape), so the column is dropped to
-    reproduce the exact pre-migration-8 table a shipped v7 file holds,
-    and a definition row is written through that old column list.
-    """
-    assert _migrate(database, MIGRATIONS[:7]) == 7
-    _run(
-        database.execute(
-            "ALTER TABLE quest_definitions DROP COLUMN skip_on_away"
-        )
-    )
-    columns = _run(database.fetch_all("PRAGMA table_info(quest_definitions)"))
-    assert "skip_on_away" not in {c[1] for c in columns}
-    _run(
-        database.execute(
-            "INSERT INTO schedule_rules (id, rule_type, interval, "
-            "start_date) VALUES (1, 'daily', 1, '2026-09-01')"
-        )
-    )
-    _run(
-        database.execute(
-            "INSERT INTO quest_definitions (id, title, schedule_rule_id, "
-            "is_active, created_at) VALUES (1, 'Dishes', 1, 1, "
-            "'2026-09-01T00:00:00+00:00')"
-        )
-    )
-
-
-def test_v7_definitions_gain_skip_on_away_defaulting_true(tmp_path) -> None:
-    from custom_components.nestquest.core.dao_rules import (
-        QuestDefinitionsDao,
-    )
-
-    database = _open_db(tmp_path / "v7-upgrade.db")
-    try:
-        _seed_v7_database(database)
-        before = _version(database)
-        assert before == 7
-
-        final = _migrate(database)
-
-        assert final == before + 1
-        assert _version(database) == before + 1
-        columns = {
-            c[1]: c
-            for c in _run(
-                database.fetch_all("PRAGMA table_info(quest_definitions)")
-            )
-        }
-        assert "skip_on_away" in columns
-        # (cid, name, type, notnull, dflt_value, pk)
-        assert columns["skip_on_away"][2:5] == ("INTEGER", 1, "1")
-        record = _run(QuestDefinitionsDao(database).get(1))
-        assert record is not None
-        assert record.title == "Dishes"
-        assert record.skip_on_away is True
-    finally:
-        _run(database.close())
-
-
-def test_skip_on_away_migration_is_noop_on_fresh_schema(tmp_path) -> None:
-    """A fresh file already has the column; step 8 only stamps."""
-    database = _open_db(tmp_path / "fresh-v8.db")
-    try:
-        assert _migrate(database) == len(MIGRATIONS)
-        columns = _run(
-            database.fetch_all("PRAGMA table_info(quest_definitions)")
-        )
-        assert [c[1] for c in columns].count("skip_on_away") == 1
-    finally:
-        _run(database.close())
-
-
 # ---------------------------------------------------------------------------
 # Idempotence: second start is a no-op
 # ---------------------------------------------------------------------------

tests/test_schema.py

@@ -322,7 +322,6 @@ def test_quest_definitions_columns_types_and_constraints(tmp_path) -> None:
             ("due_time", "TEXT", 0, None, 0),
             ("is_active", "INTEGER", 1, "1", 0),
             ("created_at", "TEXT", 1, None, 0),
-            ("skip_on_away", "INTEGER", 1, "1", 0),
         ]
     finally:
         _run(database.close())
@@ -634,30 +633,6 @@ def test_schedule_rules_rule_type_check_enforced(tmp_path) -> None:
         _run(database.close())
 
 
-@pytest.mark.parametrize("bad_flag", [2, -1])
-def test_quest_definitions_skip_on_away_check_enforced(
-    tmp_path, bad_flag
-) -> None:
-    database = _open_db(tmp_path / f"skip-on-away-{bad_flag}.db")
-    try:
-        _apply(database)
-        _child(database)
-        _insert_rule(database)
-        with pytest.raises(sqlite3.IntegrityError, match="CHECK"):
-            _insert_definition(database, skip_on_away=bad_flag)
-        definition_id = _insert_definition(database, skip_on_away=0)
-        with pytest.raises(sqlite3.IntegrityError, match="CHECK"):
-            _run(
-                database.execute(
-                    "UPDATE quest_definitions SET skip_on_away = ? "
-                    "WHERE id = ?",
-                    (bad_flag, definition_id),
-                )
-            )
-    finally:
-        _run(database.close())
-
-
 def test_schedule_rules_interval_zero_fails(tmp_path) -> None:
     database = _open_db(tmp_path / "interval-zero.db")
     try: