Feature 11: Settings home and Admin AI assistant (#86)

Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com>
2026-10-06 12:45:05 -04:00
parent f25b28b39b
commit fcbdebd6e8
54 changed files with 6712 additions and 89 deletions
@@ -0,0 +1,313 @@
+/* Admin · AI assistant, handoff mock 1o. */
+.page {
+  box-sizing: border-box;
+  min-height: 100%;
+  max-width: 560px;
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  padding-top: 6px;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.kicker {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--color-accent-700);
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 28px;
+  font-weight: 400;
+}
+
+.loading {
+  height: 320px;
+  border-radius: 26px;
+}
+
+.columns {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  gap: 10px;
+}
+
+.model {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+}
+
+.label {
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+}
+
+.mono {
+  font-family: var(--font-mono);
+}
+
+.hint,
+.note,
+.verified,
+.error,
+.status {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 13px;
+  line-height: 1.4;
+}
+
+.hint,
+.note {
+  color: var(--color-neutral-700);
+}
+
+.verified {
+  font-weight: 700;
+  color: var(--color-accent-2-800);
+}
+
+.error {
+  font-weight: 700;
+  color: var(--color-accent-700);
+}
+
+.status {
+  color: var(--color-accent-2-800);
+}
+
+.status:empty {
+  display: none;
+}
+
+.key {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.keyRow {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: 56px;
+  padding: 0 6px 0 20px;
+  border: 1px solid var(--color-neutral-300);
+  border-radius: var(--radius-pill);
+  background: var(--color-surface);
+}
+
+.keyValue {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  font-family: var(--font-mono);
+  font-size: 15px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.replace {
+  flex: none;
+  min-width: 44px;
+  min-height: 44px;
+  padding: 0 18px;
+  border: 0;
+  border-radius: var(--radius-pill);
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.replace:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.keyStatus {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0 8px;
+}
+
+.link {
+  min-width: 44px;
+  min-height: 44px;
+  padding: 0 4px;
+  border: 0;
+  background: transparent;
+  color: var(--color-accent-700);
+  font-family: var(--font-body);
+  font-size: 13px;
+  font-weight: 700;
+  text-decoration: underline;
+  cursor: pointer;
+}
+
+.temperature {
+  display: flex;
+  flex-direction: column;
+}
+
+.temperatureHeader {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+}
+
+.value {
+  font-family: var(--font-body);
+  font-size: 15px;
+  font-weight: 700;
+}
+
+.ends {
+  display: flex;
+  justify-content: space-between;
+  font-family: var(--font-body);
+  font-size: 12px;
+  color: var(--color-neutral-700);
+}
+
+.prompt {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.textarea {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 150px;
+  padding: 14px 18px;
+  border: 1px solid var(--color-neutral-300);
+  border-radius: 22px;
+  background: var(--color-surface);
+  color: var(--color-text);
+  font-family: var(--font-mono);
+  font-size: 12px;
+  line-height: 1.6;
+  resize: vertical;
+}
+
+.actions {
+  /* Mock 1o anchors Reset and Save changes at the bottom of the screen. */
+  margin-top: auto;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 2fr);
+  gap: 10px;
+  padding-top: 6px;
+}
+
+.reset,
+.save {
+  min-height: 52px;
+}
+
+.sheet {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  max-width: 560px;
+  margin: 0 auto;
+}
+
+.sheetTitle {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 22px;
+  font-weight: 400;
+}
+
+.sheetText {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 14px;
+  line-height: 1.45;
+  color: var(--color-neutral-700);
+}
+
+.sheetActions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+}
+
+/* Recipe search card, below the AI assistant's actions. */
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  border: 1px solid var(--color-neutral-300);
+}
+
+.cardTitle {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 22px;
+  font-weight: 400;
+}
+
+.cardLoading {
+  height: 160px;
+  border-radius: var(--radius-lg);
+}
+
+.cardActions {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 2fr);
+  gap: 10px;
+}
+
+.cardActions > button {
+  min-height: 52px;
+}
+
+.cardHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+/* AI assistant card on the desktop settings (mock 2e): the card grows to
+   fill its column and the system prompt grows to fill the card. */
+.fill {
+  flex: 1;
+  gap: 18px;
+}
+
+.fill .prompt,
+.fill .textarea {
+  flex: 1;
+}
+
+.fill .textarea {
+  resize: none;
+}
+
+/* A form locked while its save or prompt reset is pending, so no edit is
+   made that the response would then replace. It lays out as if it were not
+   there. */
+.lock {
+  display: contents;
+}
@@ -0,0 +1,782 @@
+import { QueryClientProvider } from '@tanstack/react-query'
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+import { Route, Routes, useLocation } from 'react-router'
+import { afterEach, describe, expect, it, vi, type Mock } from 'vitest'
+import { ApiProvider, createApiClient, createQueryClient, createVerifiedSession } from '../api/index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
+import { AI_SETTINGS, RECIPE_SEARCH_SETTINGS } from '../test/ApiProviders.tsx'
+import { InDataRouter } from '../test/dataRouter.tsx'
+import { errorResponse, fakeLocation, jsonResponse, ME } from '../test/fetchStub.ts'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { AISettingsPage, formatVerifiedDate } from './AISettingsPage.tsx'
+import { maskedKey } from './api.ts'
+
+const MODELS = {
+  models: [
+    { id: 'claude-sonnet-4-5', display_name: 'Claude Sonnet' },
+    { id: 'claude-haiku-4-5', display_name: 'Claude Haiku' },
+  ],
+}
+
+const DEFAULT_PROMPT = 'You are MealQuest, the default persona.'
+
+type Responder = (body: unknown) => Response | Promise<Response>
+
+// stubAPI answers "METHOD path" from responders, each called with the
+// request's decoded JSON body; GET /settings/ai and /settings/ai/models
+// answer AI_SETTINGS and MODELS unless overridden. Any other request fails
+// the test.
+function stubAPI(responders: Record<string, Responder> = {}): Mock<typeof fetch> {
+  const all: Record<string, Responder> = {
+    'GET /api/v1/me': () => jsonResponse(200, ME),
+    'GET /api/v1/settings/ai': () => jsonResponse(200, AI_SETTINGS),
+    'GET /api/v1/settings/ai/models': () => jsonResponse(200, MODELS),
+    'GET /api/v1/settings/recipe-search': () => jsonResponse(200, RECIPE_SEARCH_SETTINGS),
+    ...responders,
+  }
+  const fetchMock = vi.fn<typeof fetch>((input, init) => {
+    const key = `${init?.method ?? 'GET'} ${String(input)}`
+    const respond = Object.hasOwn(all, key) ? all[key] : undefined
+    if (respond === undefined) throw new Error(`unexpected fetch: ${key}`)
+    const body = typeof init?.body === 'string' ? (JSON.parse(init.body) as unknown) : undefined
+    return Promise.resolve(respond(body))
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+// sent lists the requests other than GETs, as "METHOD path" and body.
+function sent(fetchMock: Mock<typeof fetch>) {
+  return fetchMock.mock.calls
+    .filter(([, init]) => (init?.method ?? 'GET') !== 'GET')
+    .map(([input, init]) => ({
+      request: `${init?.method} ${String(input)}`,
+      body: typeof init?.body === 'string' ? (JSON.parse(init.body) as unknown) : undefined,
+    }))
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+function CurrentPath() {
+  return <p data-testid="path">{useLocation().pathname}</p>
+}
+
+// renderPage loads /me (for the CSRF token every write needs) and renders
+// the page at /settings/ai in a data router, so its leave guard works.
+async function renderPage() {
+  const api = createApiClient(fakeLocation('/settings/ai'), createNetworkStatus(window), createVerifiedSession(localStorage))
+  await api.loadMe()
+  render(
+    <ApiProvider client={api}>
+      <QueryClientProvider client={createQueryClient()}>
+        <InDataRouter path="/settings/ai">
+          <Routes>
+            <Route path="/settings/ai" element={<AISettingsPage />} />
+            <Route path="*" element={<CurrentPath />} />
+          </Routes>
+        </InDataRouter>
+      </QueryClientProvider>
+    </ApiProvider>,
+  )
+  await screen.findByRole('option', { name: 'Claude Sonnet' })
+}
+
+const provider = () => screen.getByRole('combobox', { name: 'Provider' })
+const model = () => screen.getByRole('combobox', { name: 'Model' })
+const prompt = () => screen.getByRole('textbox', { name: 'System prompt' })
+const slider = () => screen.getByRole('slider', { name: 'Creativity (temperature)' })
+const save = () => screen.getByRole('button', { name: 'Save changes' })
+
+describe('AISettingsPage', () => {
+  it('loads the settings as mock 1o lays them out', async () => {
+    stubAPI()
+    await renderPage()
+    expect(screen.getByRole('button', { name: 'Back to Settings' })).toBeInTheDocument()
+    expect(screen.getByText('Settings · Admin')).toBeInTheDocument()
+    expect(screen.getByRole('heading', { level: 1, name: 'AI assistant' })).toBeInTheDocument()
+    expect(provider()).toHaveValue('anthropic')
+    expect(within(provider()).getByRole('option', { selected: true })).toHaveTextContent('Anthropic')
+    expect(model()).toHaveValue('claude-sonnet-4-5')
+    expect(within(model()).getAllByRole('option').map((o) => o.textContent)).toEqual([
+      'Claude Sonnet',
+      'Claude Haiku',
+      'Type a model id',
+    ])
+    expect(screen.getByText('••••••••3f9a')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Replace' })).toBeInTheDocument()
+    expect(screen.getByText('Verified · Oct 1')).toBeInTheDocument()
+    expect(slider()).toHaveValue('0.7')
+    expect(slider()).toHaveAttribute('step', '0.1')
+    expect(screen.getByText('0.7')).toBeInTheDocument()
+    expect(screen.getByText('Familiar')).toBeInTheDocument()
+    expect(screen.getByText('Adventurous')).toBeInTheDocument()
+    expect(prompt()).toHaveValue(AI_SETTINGS.system_prompt)
+    expect(screen.getByRole('button', { name: 'Reset' })).toBeEnabled()
+    expect(save()).toBeDisabled()
+  })
+
+  it('reports a load failure with a retry', async () => {
+    stubAPI({ 'GET /api/v1/settings/ai': () => errorResponse(500, 'internal') })
+    const api = createApiClient(fakeLocation('/settings/ai'), createNetworkStatus(window), createVerifiedSession(localStorage))
+    render(
+      <ApiProvider client={api}>
+        <QueryClientProvider client={createQueryClient()}>
+          <InDataRouter path="/settings/ai">
+            <AISettingsPage />
+          </InDataRouter>
+        </QueryClientProvider>
+      </ApiProvider>,
+    )
+    expect(await screen.findByRole('alert')).toHaveTextContent('AI settings could not load: internal message')
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeInTheDocument()
+  })
+
+  it('saves only the edited fields', async () => {
+    const fetchMock = stubAPI({
+      'PATCH /api/v1/settings/ai': (body) => jsonResponse(200, { ...AI_SETTINGS, ...(body as object) }),
+    })
+    await renderPage()
+    fireEvent.change(model(), { target: { value: 'claude-haiku-4-5' } })
+    fireEvent.change(slider(), { target: { value: '0.4' } })
+    expect(screen.getByText('0.4')).toBeInTheDocument()
+    fireEvent.change(prompt(), { target: { value: 'Keep it cozy.' } })
+    expect(save()).toBeEnabled()
+    fireEvent.click(save())
+
+    expect(await screen.findByText('Changes saved.')).toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([
+      {
+        request: 'PATCH /api/v1/settings/ai',
+        body: { model: 'claude-haiku-4-5', temperature: 0.4, system_prompt: 'Keep it cozy.' },
+      },
+    ])
+    expect(save()).toBeDisabled()
+    expect(model()).toHaveValue('claude-haiku-4-5')
+  })
+
+  it('saves a typed model id', async () => {
+    const fetchMock = stubAPI({
+      'PATCH /api/v1/settings/ai': (body) => jsonResponse(200, { ...AI_SETTINGS, ...(body as object) }),
+    })
+    await renderPage()
+    expect(screen.queryByRole('textbox', { name: 'Model id' })).not.toBeInTheDocument()
+    fireEvent.change(model(), { target: { value: within(model()).getByRole('option', { name: 'Type a model id' }).getAttribute('value') } })
+    fireEvent.change(screen.getByRole('textbox', { name: 'Model id' }), { target: { value: 'claude-opus-5-5' } })
+    fireEvent.click(save())
+    await screen.findByText('Changes saved.')
+    expect(sent(fetchMock)).toEqual([{ request: 'PATCH /api/v1/settings/ai', body: { model: 'claude-opus-5-5' } }])
+  })
+
+  it('explains that a stored key must be removed before switching provider', async () => {
+    stubAPI({
+      'PATCH /api/v1/settings/ai': () =>
+        jsonResponse(400, {
+          error: {
+            code: 'invalid_settings',
+            message: 'invalid AI settings: provider: cannot change while an API key is stored: remove the key first',
+            retryable: false,
+          },
+        }),
+    })
+    await renderPage()
+    fireEvent.change(provider(), { target: { value: 'openai' } })
+    expect(screen.getByText(/An API key is stored\. Remove it \(Replace → Remove key\)/)).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Replace' })).toBeEnabled()
+    fireEvent.change(screen.getByRole('textbox', { name: 'Model id' }), { target: { value: 'gpt-5' } })
+    fireEvent.click(save())
+    const alert = await screen.findByRole('alert')
+    expect(alert).toHaveTextContent('Not saved: invalid AI settings: provider: cannot change while an API key is stored')
+    expect(alert).toHaveTextContent('Remove it (Replace → Remove key) before changing the provider or base URL.')
+  })
+
+  it('gives the same guidance when a stored key locks the base URL', async () => {
+    stubAPI({
+      'GET /api/v1/settings/ai': () =>
+        jsonResponse(200, { ...AI_SETTINGS, provider: 'openai_compatible', base_url: 'https://llm.example.com/v1' }),
+      'PATCH /api/v1/settings/ai': () =>
+        jsonResponse(400, {
+          error: {
+            code: 'invalid_settings',
+            message: 'invalid AI settings: base_url: cannot change while an API key is stored: remove the key first',
+            retryable: false,
+          },
+        }),
+    })
+    await renderPage()
+    fireEvent.change(screen.getByRole('textbox', { name: 'Base URL' }), { target: { value: 'https://other.example.com/v1' } })
+    expect(screen.getByText(/An API key is stored\. Remove it/)).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Replace' })).toBeEnabled()
+    fireEvent.click(save())
+    expect(await screen.findByRole('alert')).toHaveTextContent(
+      'Remove it (Replace → Remove key) before changing the provider or base URL.',
+    )
+  })
+
+  it('recovers a provider switch by removing the stored key, without undoing the switch', async () => {
+    const fetchMock = stubAPI({
+      'PUT /api/v1/settings/ai/api-key': () =>
+        jsonResponse(200, { ...AI_SETTINGS, api_key_last4: null, key_verified_at: null }),
+      'PATCH /api/v1/settings/ai': (body) =>
+        jsonResponse(200, { ...AI_SETTINGS, api_key_last4: null, key_verified_at: null, ...(body as object) }),
+    })
+    await renderPage()
+    fireEvent.change(provider(), { target: { value: 'ollama' } })
+    fireEvent.change(screen.getByRole('textbox', { name: 'Base URL' }), { target: { value: 'http://localhost:11434' } })
+    fireEvent.change(screen.getByRole('textbox', { name: 'Model id' }), { target: { value: 'llama3.2' } })
+    // The stored key stays in view, and removable, while Ollama is chosen.
+    expect(screen.getByText('••••••••3f9a')).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Replace' }))
+    fireEvent.click(within(screen.getByRole('dialog')).getByRole('button', { name: 'Remove key' }))
+
+    expect(await screen.findByText('Ollama takes no API key.')).toBeInTheDocument()
+    expect(screen.queryByText(/An API key is stored/)).not.toBeInTheDocument()
+    expect(provider()).toHaveValue('ollama')
+    fireEvent.click(save())
+    expect(await screen.findByText('Changes saved.')).toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([
+      { request: 'PUT /api/v1/settings/ai/api-key', body: { api_key: '' } },
+      {
+        request: 'PATCH /api/v1/settings/ai',
+        body: { provider: 'ollama', base_url: 'http://localhost:11434', model: 'llama3.2' },
+      },
+    ])
+  })
+
+  it('replaces the key in a sheet, then verifies it', async () => {
+    const verifiedAt = '2026-10-06T14:00:00.000Z'
+    const fetchMock = stubAPI({
+      'PUT /api/v1/settings/ai/api-key': () =>
+        jsonResponse(200, { ...AI_SETTINGS, api_key_last4: 'b7c1', key_verified_at: null }),
+      'POST /api/v1/settings/ai/verify': () =>
+        jsonResponse(200, { ...AI_SETTINGS, api_key_last4: 'b7c1', key_verified_at: verifiedAt }),
+    })
+    await renderPage()
+    fireEvent.click(screen.getByRole('button', { name: 'Replace' }))
+    const sheet = screen.getByRole('dialog', { name: 'Replace API key' })
+    const input = within(sheet).getByLabelText('API key')
+    expect(input).toHaveAttribute('type', 'password')
+    fireEvent.change(input, { target: { value: 'sk-ant-secret-b7c1' } })
+    fireEvent.click(within(sheet).getByRole('button', { name: 'Save and verify' }))
+
+    expect(await screen.findByText(`Verified · ${formatVerifiedDate(verifiedAt)}`)).toBeInTheDocument()
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+    expect(screen.getByText('••••••••b7c1')).toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([
+      { request: 'PUT /api/v1/settings/ai/api-key', body: { api_key: 'sk-ant-secret-b7c1' } },
+      { request: 'POST /api/v1/settings/ai/verify', body: undefined },
+    ])
+    expect(document.body).not.toHaveTextContent('sk-ant-secret-b7c1')
+  })
+
+  it('still verifies the key when the sheet is dismissed while it is being stored', async () => {
+    let answerPut: (response: Response) => void = () => {
+      throw new Error('PUT not sent')
+    }
+    const fetchMock = stubAPI({
+      'PUT /api/v1/settings/ai/api-key': () => new Promise<Response>((resolve) => (answerPut = resolve)),
+      'POST /api/v1/settings/ai/verify': () =>
+        jsonResponse(200, { ...AI_SETTINGS, api_key_last4: 'b7c1', key_verified_at: '2026-10-06T14:00:00.000Z' }),
+    })
+    await renderPage()
+    fireEvent.click(screen.getByRole('button', { name: 'Replace' }))
+    const sheet = screen.getByRole('dialog', { name: 'Replace API key' })
+    fireEvent.change(within(sheet).getByLabelText('API key'), { target: { value: 'sk-ant-secret-b7c1' } })
+    fireEvent.click(within(sheet).getByRole('button', { name: 'Save and verify' }))
+    await waitFor(() => expect(within(sheet).getByRole('button', { name: 'Saving…' })).toBeDisabled())
+    fireEvent.keyDown(sheet, { key: 'Escape' })
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Saving…' })).toBeDisabled()
+
+    act(() => answerPut(jsonResponse(200, { ...AI_SETTINGS, api_key_last4: 'b7c1', key_verified_at: null })))
+    expect(await screen.findByText('Verified · Oct 6')).toBeInTheDocument()
+    expect(screen.getByText('••••••••b7c1')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Replace' })).toBeEnabled()
+    expect(sent(fetchMock)).toEqual([
+      { request: 'PUT /api/v1/settings/ai/api-key', body: { api_key: 'sk-ant-secret-b7c1' } },
+      { request: 'POST /api/v1/settings/ai/verify', body: undefined },
+    ])
+  })
+
+  it('shows the verify error and verifies again on request', async () => {
+    let verifyCalls = 0
+    stubAPI({
+      'PUT /api/v1/settings/ai/api-key': () =>
+        jsonResponse(200, { ...AI_SETTINGS, api_key_last4: 'b7c1', key_verified_at: null }),
+      'POST /api/v1/settings/ai/verify': () => {
+        verifyCalls++
+        return verifyCalls === 1
+          ? errorResponse(502, 'auth_failed')
+          : jsonResponse(200, { ...AI_SETTINGS, api_key_last4: 'b7c1' })
+      },
+    })
+    await renderPage()
+    fireEvent.click(screen.getByRole('button', { name: 'Replace' }))
+    const sheet = screen.getByRole('dialog', { name: 'Replace API key' })
+    fireEvent.change(within(sheet).getByLabelText('API key'), { target: { value: 'sk-wrong-b7c1' } })
+    fireEvent.click(within(sheet).getByRole('button', { name: 'Save and verify' }))
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('Verification failed: the provider rejected this key.')
+    expect(screen.queryByText(/^Verified ·/)).not.toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Try again' }))
+    expect(await screen.findByText('Verified · Oct 1')).toBeInTheDocument()
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+
+  it('shows a refused key in the sheet', async () => {
+    stubAPI({
+      'PUT /api/v1/settings/ai/api-key': () =>
+        jsonResponse(400, {
+          error: { code: 'invalid_settings', message: 'api_key: must be at least 8 characters', retryable: false },
+        }),
+    })
+    await renderPage()
+    fireEvent.click(screen.getByRole('button', { name: 'Replace' }))
+    const sheet = screen.getByRole('dialog', { name: 'Replace API key' })
+    fireEvent.change(within(sheet).getByLabelText('API key'), { target: { value: 'short' } })
+    fireEvent.click(within(sheet).getByRole('button', { name: 'Save and verify' }))
+    expect(await within(sheet).findByRole('alert')).toHaveTextContent(
+      'The key was not stored: api_key: must be at least 8 characters',
+    )
+  })
+
+  it('removes the stored key from the sheet', async () => {
+    const fetchMock = stubAPI({
+      'PUT /api/v1/settings/ai/api-key': () =>
+        jsonResponse(200, { ...AI_SETTINGS, api_key_last4: null, key_verified_at: null }),
+    })
+    await renderPage()
+    fireEvent.click(screen.getByRole('button', { name: 'Replace' }))
+    fireEvent.click(within(screen.getByRole('dialog')).getByRole('button', { name: 'Remove key' }))
+    expect(await screen.findByText('No key stored')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Add key' })).toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([{ request: 'PUT /api/v1/settings/ai/api-key', body: { api_key: '' } }])
+  })
+
+  it('resets the system prompt after confirming', async () => {
+    const fetchMock = stubAPI({
+      'POST /api/v1/settings/ai/reset-prompt': () => jsonResponse(200, { ...AI_SETTINGS, system_prompt: DEFAULT_PROMPT }),
+    })
+    await renderPage()
+    fireEvent.click(screen.getByRole('button', { name: 'Reset' }))
+    const confirm = screen.getByRole('dialog', { name: 'Reset the system prompt?' })
+    fireEvent.click(within(confirm).getByRole('button', { name: 'Cancel' }))
+    expect(sent(fetchMock)).toEqual([])
+
+    fireEvent.click(screen.getByRole('button', { name: 'Reset' }))
+    fireEvent.click(within(screen.getByRole('dialog')).getByRole('button', { name: 'Reset prompt' }))
+    await waitFor(() => expect(prompt()).toHaveValue(DEFAULT_PROMPT))
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([{ request: 'POST /api/v1/settings/ai/reset-prompt', body: undefined }])
+    expect(save()).toBeDisabled()
+  })
+
+  it('asks before leaving with unsaved changes', async () => {
+    stubAPI()
+    await renderPage()
+    fireEvent.change(prompt(), { target: { value: 'Unsaved.' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Back to Settings' }))
+    const confirm = await screen.findByRole('dialog', { name: 'Leave without saving?' })
+    fireEvent.click(within(confirm).getByRole('button', { name: 'Keep editing' }))
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+    expect(prompt()).toHaveValue('Unsaved.')
+
+    fireEvent.click(screen.getByRole('button', { name: 'Back to Settings' }))
+    fireEvent.click(within(await screen.findByRole('dialog')).getByRole('button', { name: 'Leave' }))
+    expect(await screen.findByTestId('path')).toHaveTextContent('/settings')
+  })
+
+  it('leaves without asking when nothing changed', async () => {
+    stubAPI()
+    await renderPage()
+    fireEvent.click(screen.getByRole('button', { name: 'Back to Settings' }))
+    expect(await screen.findByTestId('path')).toHaveTextContent('/settings')
+  })
+
+  it('guards a page unload only while there are unsaved changes', async () => {
+    stubAPI()
+    await renderPage()
+    const unload = () => {
+      const event = new Event('beforeunload', { cancelable: true })
+      act(() => void window.dispatchEvent(event))
+      return event.defaultPrevented
+    }
+    expect(unload()).toBe(false)
+    fireEvent.change(slider(), { target: { value: '0.2' } })
+    expect(unload()).toBe(true)
+  })
+
+  it('locks the form while a save is pending, and guards leaving until the save lands', async () => {
+    let answer: (response: Response) => void = () => {}
+    stubAPI({ 'PATCH /api/v1/settings/ai': () => new Promise<Response>((resolve) => (answer = resolve)) })
+    await renderPage()
+    const unload = () => {
+      const event = new Event('beforeunload', { cancelable: true })
+      act(() => void window.dispatchEvent(event))
+      return event.defaultPrevented
+    }
+    fireEvent.change(prompt(), { target: { value: 'Keep it cozy.' } })
+    fireEvent.click(save())
+
+    expect(await screen.findByRole('button', { name: 'Saving…' })).toBeDisabled()
+    for (const field of [provider(), model(), slider(), prompt()]) expect(field).toBeDisabled()
+    expect(screen.getByRole('button', { name: 'Reset' })).toBeDisabled()
+    expect(unload()).toBe(true)
+
+    answer(jsonResponse(200, { ...AI_SETTINGS, system_prompt: 'Keep it cozy.' }))
+    expect(await screen.findByText('Changes saved.')).toBeInTheDocument()
+    expect(prompt()).toBeEnabled()
+    expect(prompt()).toHaveValue('Keep it cozy.')
+    await waitFor(() => expect(unload()).toBe(false))
+  })
+
+  it('locks the form while a prompt reset is pending, even with the sheet closed', async () => {
+    let answer: (response: Response) => void = () => {}
+    stubAPI({
+      'POST /api/v1/settings/ai/reset-prompt': () => new Promise<Response>((resolve) => (answer = resolve)),
+    })
+    await renderPage()
+    const unload = () => {
+      const event = new Event('beforeunload', { cancelable: true })
+      act(() => void window.dispatchEvent(event))
+      return event.defaultPrevented
+    }
+    fireEvent.change(slider(), { target: { value: '0.2' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Reset' }))
+    const confirm = screen.getByRole('dialog', { name: 'Reset the system prompt?' })
+    fireEvent.click(within(confirm).getByRole('button', { name: 'Reset prompt' }))
+    expect(await within(confirm).findByRole('button', { name: 'Resetting…' })).toBeDisabled()
+    fireEvent.click(within(confirm).getByRole('button', { name: 'Cancel' }))
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+
+    for (const field of [provider(), model(), slider(), prompt()]) expect(field).toBeDisabled()
+    expect(screen.getByRole('button', { name: 'Reset' })).toBeDisabled()
+    expect(save()).toBeDisabled()
+    expect(unload()).toBe(true)
+
+    answer(jsonResponse(200, { ...AI_SETTINGS, system_prompt: DEFAULT_PROMPT }))
+    await waitFor(() => expect(prompt()).toBeEnabled())
+    expect(prompt()).toHaveValue(DEFAULT_PROMPT)
+    expect(slider()).toHaveValue('0.2')
+    expect(unload()).toBe(true)
+    fireEvent.change(prompt(), { target: { value: 'After the reset.' } })
+    expect(prompt()).toHaveValue('After the reset.')
+  })
+
+  it('keeps 44 px tap targets', async () => {
+    stubAPI()
+    await renderPage()
+    for (const control of [
+      screen.getByRole('button', { name: 'Back to Settings' }),
+      screen.getByRole('button', { name: 'Replace' }),
+      provider(),
+      model(),
+      slider(),
+      screen.getByRole('button', { name: 'Reset' }),
+      save(),
+    ]) {
+      expectMinHitArea(control)
+    }
+  })
+})
+
+// apiError is an API error response carrying message.
+function apiError(status: number, code: string, message: string): Response {
+  return jsonResponse(status, { error: { code, message, retryable: false } })
+}
+
+const BRAVE_SETTINGS = { ...RECIPE_SEARCH_SETTINGS, provider: 'brave', api_key_set: true, api_key_last4: 'b7c2' }
+
+describe('Recipe search card', () => {
+  const card = () => screen.getByRole('region', { name: 'Recipe search' })
+  const searxng = () => within(card()).getByRole('radio', { name: 'SearXNG' })
+  const brave = () => within(card()).getByRole('radio', { name: 'Brave' })
+  const url = () => within(card()).getByRole('textbox', { name: 'SearXNG URL' })
+  const saveSearch = () => within(card()).getByRole('button', { name: 'Save recipe search' })
+  const testSearch = () => within(card()).getByRole('button', { name: 'Test' })
+
+  async function renderCard() {
+    await renderPage()
+    await within(card()).findByRole('radiogroup', { name: 'Recipe search provider' })
+  }
+
+  // addKey enters key in the Brave key sheet.
+  function addKey(button: string, key: string) {
+    fireEvent.click(within(card()).getByRole('button', { name: button }))
+    const sheet = screen.getByRole('dialog')
+    fireEvent.change(within(sheet).getByLabelText('Brave API key'), { target: { value: key } })
+    fireEvent.click(within(sheet).getByRole('button', { name: 'Use this key' }))
+  }
+
+  it('shows the saved SearXNG URL', async () => {
+    stubAPI()
+    await renderCard()
+    expect(searxng()).toHaveAttribute('aria-checked', 'true')
+    expect(url()).toHaveValue('http://searxng:8080')
+    expect(within(card()).queryByText('Brave API key')).not.toBeInTheDocument()
+    expect(saveSearch()).toBeDisabled()
+    expect(testSearch()).toBeEnabled()
+  })
+
+  const UNCONFIGURED = {
+    provider: null,
+    base_url: null,
+    default_base_url: 'http://searxng:8080',
+    api_key_set: false,
+    api_key_last4: null,
+    updated_at: null,
+  }
+
+  it('starts on SearXNG with the deployment\'s URL before recipe search is set up, and saves it', async () => {
+    const fetchMock = stubAPI({
+      'GET /api/v1/settings/recipe-search': () => jsonResponse(200, UNCONFIGURED),
+      'PATCH /api/v1/settings/recipe-search': (body) =>
+        jsonResponse(200, { ...RECIPE_SEARCH_SETTINGS, ...(body as object) }),
+    })
+    await renderCard()
+    expect(searxng()).toHaveAttribute('aria-checked', 'true')
+    expect(url()).toHaveValue('http://searxng:8080')
+    expect(testSearch()).toBeDisabled()
+    expect(saveSearch()).toBeEnabled()
+    fireEvent.click(saveSearch())
+    expect(await within(card()).findByText('Recipe search saved.')).toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([
+      {
+        request: 'PATCH /api/v1/settings/recipe-search',
+        body: { provider: 'searxng', base_url: 'http://searxng:8080' },
+      },
+    ])
+  })
+
+  it('starts with an empty URL when the deployment names no SearXNG', async () => {
+    stubAPI({
+      'GET /api/v1/settings/recipe-search': () => jsonResponse(200, { ...UNCONFIGURED, default_base_url: null }),
+    })
+    await renderCard()
+    expect(url()).toHaveValue('')
+  })
+
+  it('shows the saved URL, not the deployment\'s', async () => {
+    stubAPI({
+      'GET /api/v1/settings/recipe-search': () =>
+        jsonResponse(200, { ...RECIPE_SEARCH_SETTINGS, base_url: 'https://search.example' }),
+    })
+    await renderCard()
+    expect(url()).toHaveValue('https://search.example')
+    expect(saveSearch()).toBeDisabled()
+  })
+
+  it('switches providers, keeping each provider\'s field', async () => {
+    stubAPI()
+    await renderCard()
+    fireEvent.change(url(), { target: { value: 'https://search.example' } })
+    fireEvent.click(brave())
+    expect(brave()).toHaveAttribute('aria-checked', 'true')
+    expect(within(card()).queryByRole('textbox', { name: 'SearXNG URL' })).not.toBeInTheDocument()
+    expect(within(card()).getByText('No key stored')).toBeInTheDocument()
+    expect(within(card()).getByRole('button', { name: 'Add key' })).toBeInTheDocument()
+
+    fireEvent.click(searxng())
+    expect(url()).toHaveValue('https://search.example')
+  })
+
+  it('saves a new SearXNG URL', async () => {
+    const fetchMock = stubAPI({
+      'PATCH /api/v1/settings/recipe-search': (body) =>
+        jsonResponse(200, { ...RECIPE_SEARCH_SETTINGS, ...(body as object) }),
+    })
+    await renderCard()
+    fireEvent.change(url(), { target: { value: 'https://search.example' } })
+    expect(testSearch()).toBeDisabled()
+    expect(within(card()).getByText('Save your changes to test them.')).toBeInTheDocument()
+    fireEvent.click(saveSearch())
+    expect(await within(card()).findByText('Recipe search saved.')).toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([
+      { request: 'PATCH /api/v1/settings/recipe-search', body: { base_url: 'https://search.example' } },
+    ])
+    expect(saveSearch()).toBeDisabled()
+    expect(testSearch()).toBeEnabled()
+  })
+
+  it('saves a switch to Brave with its key, then shows only the key\'s last four characters', async () => {
+    const fetchMock = stubAPI({ 'PATCH /api/v1/settings/recipe-search': () => jsonResponse(200, BRAVE_SETTINGS) })
+    await renderCard()
+    fireEvent.click(brave())
+    addKey('Add key', 'BSA-secret-key-b7c2')
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+    expect(within(card()).getByText('••••••••b7c2')).toBeInTheDocument()
+    expect(within(card()).getByText('New key not saved yet')).toBeInTheDocument()
+    expect(document.body).not.toHaveTextContent('BSA-secret-key-b7c2')
+
+    fireEvent.click(saveSearch())
+    expect(await within(card()).findByText('Recipe search saved.')).toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([
+      { request: 'PATCH /api/v1/settings/recipe-search', body: { provider: 'brave', api_key: 'BSA-secret-key-b7c2' } },
+    ])
+    expect(within(card()).getByText('••••••••b7c2')).toBeInTheDocument()
+    expect(within(card()).queryByText('New key not saved yet')).not.toBeInTheDocument()
+    expect(within(card()).getByRole('button', { name: 'Replace' })).toBeInTheDocument()
+    expect(document.body).not.toHaveTextContent('BSA-secret-key-b7c2')
+  })
+
+  it('masks a stored Brave key and replaces it', async () => {
+    const fetchMock = stubAPI({
+      'GET /api/v1/settings/recipe-search': () => jsonResponse(200, BRAVE_SETTINGS),
+      'PATCH /api/v1/settings/recipe-search': () => jsonResponse(200, { ...BRAVE_SETTINGS, api_key_last4: '9d0e' }),
+    })
+    await renderCard()
+    expect(brave()).toHaveAttribute('aria-checked', 'true')
+    expect(within(card()).getByText('••••••••b7c2')).toBeInTheDocument()
+    expect(saveSearch()).toBeDisabled()
+
+    addKey('Replace', 'BSA-other-key-9d0e')
+    fireEvent.click(within(card()).getByRole('button', { name: 'Discard' }))
+    expect(within(card()).getByText('••••••••b7c2')).toBeInTheDocument()
+    expect(saveSearch()).toBeDisabled()
+
+    addKey('Replace', 'BSA-other-key-9d0e')
+    fireEvent.click(saveSearch())
+    expect(await within(card()).findByText('••••••••9d0e')).toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([
+      { request: 'PATCH /api/v1/settings/recipe-search', body: { api_key: 'BSA-other-key-9d0e' } },
+    ])
+  })
+
+  it('reports a save the server refuses', async () => {
+    stubAPI({
+      'PATCH /api/v1/settings/recipe-search': () =>
+        apiError(400, 'invalid_settings', 'invalid recipe search settings: api_key: must be at least 8 characters'),
+    })
+    await renderCard()
+    fireEvent.click(brave())
+    addKey('Add key', 'short')
+    fireEvent.click(saveSearch())
+    expect(await within(card()).findByRole('alert')).toHaveTextContent(
+      'Not saved: invalid recipe search settings: api_key: must be at least 8 characters.',
+    )
+  })
+
+  it('shows how many recipes the test found', async () => {
+    const fetchMock = stubAPI({
+      'POST /api/v1/settings/recipe-search/test': () =>
+        jsonResponse(200, { query: 'chicken tikka masala', count: 12 }),
+    })
+    await renderCard()
+    fireEvent.click(testSearch())
+    expect(await within(card()).findByText("Found 12 recipes for 'chicken tikka masala'")).toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([{ request: 'POST /api/v1/settings/recipe-search/test', body: undefined }])
+  })
+
+  it('shows the error when the test fails', async () => {
+    stubAPI({
+      'POST /api/v1/settings/recipe-search/test': () =>
+        apiError(502, 'search_failed', 'recipes: SearXNG answered 403 Forbidden'),
+    })
+    await renderCard()
+    fireEvent.click(testSearch())
+    expect(await within(card()).findByRole('alert')).toHaveTextContent(
+      'Test failed: recipes: SearXNG answered 403 Forbidden',
+    )
+  })
+
+  it('clears a test result when the settings are edited', async () => {
+    stubAPI({
+      'POST /api/v1/settings/recipe-search/test': () =>
+        jsonResponse(200, { query: 'chicken tikka masala', count: 12 }),
+    })
+    await renderCard()
+    fireEvent.click(testSearch())
+    expect(await within(card()).findByText("Found 12 recipes for 'chicken tikka masala'")).toBeInTheDocument()
+    fireEvent.change(url(), { target: { value: 'https://search.example' } })
+    expect(within(card()).getByText('Save your changes to test them.')).toBeInTheDocument()
+    expect(within(card()).queryByText(/Found 12 recipes/)).not.toBeInTheDocument()
+  })
+
+  it('clears a test error when the settings are edited', async () => {
+    stubAPI({
+      'POST /api/v1/settings/recipe-search/test': () =>
+        apiError(502, 'search_failed', 'recipes: SearXNG answered 403 Forbidden'),
+    })
+    await renderCard()
+    fireEvent.click(testSearch())
+    expect(await within(card()).findByRole('alert')).toHaveTextContent('Test failed')
+    fireEvent.click(brave())
+    expect(within(card()).getByText('Save your changes to test them.')).toBeInTheDocument()
+    expect(within(card()).queryByRole('alert')).not.toBeInTheDocument()
+  })
+
+  it('asks before leaving with an unsaved recipe search change', async () => {
+    stubAPI()
+    await renderCard()
+    fireEvent.change(url(), { target: { value: 'https://search.example' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Back to Settings' }))
+    expect(await screen.findByRole('dialog', { name: 'Leave without saving?' })).toBeInTheDocument()
+  })
+
+  it('does not count the suggested SearXNG URL as an unsaved change until it is edited', async () => {
+    stubAPI({ 'GET /api/v1/settings/recipe-search': () => jsonResponse(200, UNCONFIGURED) })
+    await renderCard()
+    const unload = () => {
+      const event = new Event('beforeunload', { cancelable: true })
+      act(() => void window.dispatchEvent(event))
+      return event.defaultPrevented
+    }
+    expect(saveSearch()).toBeEnabled()
+    expect(unload()).toBe(false)
+    fireEvent.change(url(), { target: { value: 'https://search.example' } })
+    expect(unload()).toBe(true)
+    fireEvent.change(url(), { target: { value: 'http://searxng:8080' } })
+    expect(unload()).toBe(false)
+  })
+
+  it('leaves the untouched first-use card without asking', async () => {
+    stubAPI({ 'GET /api/v1/settings/recipe-search': () => jsonResponse(200, UNCONFIGURED) })
+    await renderCard()
+    fireEvent.click(screen.getByRole('button', { name: 'Back to Settings' }))
+    expect(await screen.findByTestId('path')).toHaveTextContent('/settings')
+  })
+
+  it('locks the card while a save is pending, and guards leaving until the save lands', async () => {
+    let answer: (response: Response) => void = () => {}
+    stubAPI({ 'PATCH /api/v1/settings/recipe-search': () => new Promise<Response>((resolve) => (answer = resolve)) })
+    await renderCard()
+    const unload = () => {
+      const event = new Event('beforeunload', { cancelable: true })
+      act(() => void window.dispatchEvent(event))
+      return event.defaultPrevented
+    }
+    fireEvent.change(url(), { target: { value: 'https://search.example' } })
+    fireEvent.click(saveSearch())
+
+    expect(await within(card()).findByRole('button', { name: 'Saving…' })).toBeDisabled()
+    for (const field of [url(), searxng(), brave()]) expect(field).toBeDisabled()
+    expect(unload()).toBe(true)
+
+    answer(jsonResponse(200, { ...RECIPE_SEARCH_SETTINGS, base_url: 'https://search.example' }))
+    expect(await within(card()).findByText('Recipe search saved.')).toBeInTheDocument()
+    expect(url()).toBeEnabled()
+    expect(url()).toHaveValue('https://search.example')
+    await waitFor(() => expect(unload()).toBe(false))
+  })
+
+  it('keeps 44 px tap targets', async () => {
+    stubAPI({ 'GET /api/v1/settings/recipe-search': () => jsonResponse(200, BRAVE_SETTINGS) })
+    await renderCard()
+    for (const control of [
+      searxng(),
+      brave(),
+      within(card()).getByRole('button', { name: 'Replace' }),
+      testSearch(),
+      saveSearch(),
+    ]) {
+      expectMinHitArea(control)
+    }
+  })
+})
+
+describe('maskedKey', () => {
+  it('shows only the last four characters', () => {
+    expect(maskedKey('3f9a')).toBe('••••••••3f9a')
+  })
+})
@@ -0,0 +1,546 @@
+import { ChevronLeft } from 'lucide-react'
+import { useEffect, useId, useState, type ReactNode } from 'react'
+import { useNavigate } from 'react-router'
+import { ApiError } from '../api/index.ts'
+import { Button } from '../ui/Button.tsx'
+import { Card } from '../ui/Card.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { IconButton } from '../ui/IconButton.tsx'
+import { Select } from '../ui/Select.tsx'
+import { Sheet } from '../ui/Sheet.tsx'
+import { Skeleton } from '../ui/Skeleton.tsx'
+import { Slider } from '../ui/Slider.tsx'
+import { Tag } from '../ui/Tag.tsx'
+import { TextInput } from '../ui/TextInput.tsx'
+import {
+  aiKeyPolicy,
+  aiProviderLabels,
+  maskedKey,
+  providersWithBaseURL,
+  useAIModels,
+  useAISettings,
+  useResetAIPrompt,
+  useSaveAISettings,
+  useSetAIKey,
+  useVerifyAIKey,
+  type AIProvider,
+  type AISettings,
+  type AISettingsPatch,
+} from './api.ts'
+import styles from './AISettingsPage.module.css'
+import { Confirm, LeaveGuard } from './LeaveGuard.tsx'
+import { RecipeSearchCard } from './RecipeSearchCard.tsx'
+
+// TYPE_MODEL is the Model dropdown's "Type a model id" option.
+const TYPE_MODEL = '\u0000type'
+
+// Admin · AI assistant (handoff mock 1o). Provider, model, temperature and
+// system prompt are edited as a draft and saved together; the API key is
+// stored (and verified) on its own, straight away. The client only ever
+// sees the key's last four characters. Recipe search is its own card, saved
+// on its own.
+export function AISettingsPage() {
+  const [aiDirty, setAIDirty] = useState(false)
+  const [recipeSearchDirty, setRecipeSearchDirty] = useState(false)
+  return (
+    <div className={styles.page}>
+      <Header />
+      <AIAssistantSettings onDirtyChange={setAIDirty} />
+      <RecipeSearchCard onDirtyChange={setRecipeSearchDirty} />
+      <LeaveGuard dirty={aiDirty || recipeSearchDirty} />
+    </div>
+  )
+}
+
+type AISettingsProps = {
+  // Called with whether the form holds unsaved changes.
+  onDirtyChange: (dirty: boolean) => void
+}
+
+// AIAssistantCard is the AI assistant's fields as a card, for the desktop
+// settings (handoff mock 2e): the system prompt grows to fill the card.
+export function AIAssistantCard({ onDirtyChange }: AISettingsProps) {
+  const titleId = useId()
+  return (
+    <Card className={`${styles.card} ${styles.fill}`} aria-labelledby={titleId} role="region">
+      <div className={styles.cardHeader}>
+        <h2 id={titleId} className={styles.cardTitle}>
+          AI assistant
+        </h2>
+        <Tag>Admin</Tag>
+      </div>
+      <AIAssistantSettings onDirtyChange={onDirtyChange} />
+    </Card>
+  )
+}
+
+// AIAssistantSettings is the AI assistant's form once its settings load.
+function AIAssistantSettings({ onDirtyChange }: AISettingsProps) {
+  const settings = useAISettings()
+  return (
+    <>
+      {settings.isPending && <Skeleton className={styles.loading} />}
+      {settings.isError && (
+        <ErrorBanner onRetry={() => void settings.refetch()}>
+          AI settings could not load: {settings.error.message}
+        </ErrorBanner>
+      )}
+      {settings.isSuccess && <AISettingsForm saved={settings.data} onDirtyChange={onDirtyChange} />}
+    </>
+  )
+}
+
+function Header() {
+  const navigate = useNavigate()
+  return (
+    <header className={styles.header}>
+      <IconButton label="Back to Settings" onClick={() => void navigate('/settings')}>
+        <Icon icon={ChevronLeft} size="nav" />
+      </IconButton>
+      <div>
+        <p className={styles.kicker}>Settings · Admin</p>
+        <h1 className={styles.title}>AI assistant</h1>
+      </div>
+    </header>
+  )
+}
+
+type Draft = {
+  provider: AIProvider
+  base_url: string
+  model: string
+  temperature: number
+  system_prompt: string
+}
+
+function draftOf(saved: AISettings): Draft {
+  return {
+    provider: saved.provider,
+    base_url: saved.base_url,
+    model: saved.model,
+    temperature: saved.temperature,
+    system_prompt: saved.system_prompt ?? '',
+  }
+}
+
+// patchOf is the PATCH body for the fields draft changes.
+function patchOf(saved: AISettings, draft: Draft): AISettingsPatch {
+  const before = draftOf(saved)
+  const patch: AISettingsPatch = {}
+  if (draft.provider !== before.provider) patch.provider = draft.provider
+  if (draft.base_url !== before.base_url) patch.base_url = draft.base_url
+  if (draft.model !== before.model) patch.model = draft.model
+  if (draft.temperature !== before.temperature) patch.temperature = draft.temperature
+  if (draft.system_prompt !== before.system_prompt) patch.system_prompt = draft.system_prompt
+  return patch
+}
+
+type AISettingsFormProps = AISettingsProps & {
+  saved: AISettings
+}
+
+function AISettingsForm({ saved, onDirtyChange }: AISettingsFormProps) {
+  const [draft, setDraft] = useState(() => draftOf(saved))
+  const [typingModel, setTypingModel] = useState(false)
+  const [confirmingReset, setConfirmingReset] = useState(false)
+  const save = useSaveAISettings()
+  const resetPrompt = useResetAIPrompt()
+  const patch = patchOf(saved, draft)
+  const dirty = Object.keys(patch).length > 0
+  const providerChanged = draft.provider !== saved.provider
+  // The server keeps a stored key's provider and base URL fixed until the
+  // key is removed.
+  const keyLocked = saved.api_key_last4 !== null && (providerChanged || draft.base_url !== saved.base_url)
+  const temperatureId = useId()
+  // The model list is the saved provider's, so it is asked for only while
+  // that provider is chosen and has the key it needs.
+  const canList =
+    !providerChanged && (aiKeyPolicy[saved.provider] !== 'required' || saved.api_key_last4 !== null)
+  const models = useAIModels(canList)
+  const listed = canList && models.isSuccess ? models.data : []
+  const typedModel = typingModel || !(draft.model === '' || listed.some((m) => m.id === draft.model))
+
+  useEffect(() => {
+    onDirtyChange(dirty)
+  }, [dirty, onDirtyChange])
+  useEffect(() => () => onDirtyChange(false), [onDirtyChange])
+
+  function edit(change: Partial<Draft>) {
+    save.reset()
+    setDraft((current) => ({ ...current, ...change }))
+  }
+
+  function chooseProvider(provider: AIProvider) {
+    setTypingModel(provider !== saved.provider)
+    if (provider === saved.provider) {
+      edit({ provider, base_url: saved.base_url, model: saved.model })
+      return
+    }
+    // A fixed-URL preset refuses any other base URL, and the old model is
+    // another provider's: the household types the new one.
+    edit({ provider, base_url: providersWithBaseURL.has(provider) ? draft.base_url : '', model: '' })
+  }
+
+  function onSave() {
+    save.mutate(patch, {
+      onSuccess: (settings) => {
+        setDraft(draftOf(settings))
+        setTypingModel(false)
+      },
+    })
+  }
+
+  function onConfirmReset() {
+    resetPrompt.mutate(undefined, {
+      onSuccess: (settings) => {
+        setDraft((current) => ({ ...current, system_prompt: settings.system_prompt ?? '' }))
+        setConfirmingReset(false)
+      },
+    })
+  }
+
+  return (
+    <fieldset className={styles.lock} disabled={save.isPending || resetPrompt.isPending}>
+      <div className={styles.columns}>
+        <Select
+          label="Provider"
+          value={draft.provider}
+          onChange={(event) => chooseProvider(event.target.value as AIProvider)}
+        >
+          {Object.entries(aiProviderLabels).map(([value, label]) => (
+            <option key={value} value={value}>
+              {label}
+            </option>
+          ))}
+        </Select>
+        <div className={styles.model}>
+          <Select
+            label="Model"
+            value={typedModel ? TYPE_MODEL : draft.model}
+            onChange={(event) => {
+              const model = event.target.value
+              setTypingModel(model === TYPE_MODEL)
+              if (model !== TYPE_MODEL) edit({ model })
+            }}
+          >
+            {!typedModel && draft.model === '' && (
+              <option value="" disabled>
+                Choose a model
+              </option>
+            )}
+            {listed.map((model) => (
+              <option key={model.id} value={model.id}>
+                {model.display_name}
+              </option>
+            ))}
+            <option value={TYPE_MODEL}>Type a model id</option>
+          </Select>
+          {canList && models.isPending && <p className={styles.note}>Loading models…</p>}
+          {canList && models.isError && <p className={styles.note}>Model list unavailable: {models.error.message}</p>}
+          {!canList && !providerChanged && (
+            <p className={styles.note}>Add the API key to choose from the provider's models.</p>
+          )}
+        </div>
+      </div>
+      {keyLocked && <p className={styles.hint}>{keyLockedGuidance}</p>}
+      {typedModel && (
+        <TextInput
+          label="Model id"
+          className={styles.mono}
+          value={draft.model}
+          placeholder="e.g. claude-sonnet-4-5"
+          autoComplete="off"
+          spellCheck={false}
+          onChange={(event) => edit({ model: event.target.value })}
+        />
+      )}
+      {providersWithBaseURL.has(draft.provider) && (
+        <TextInput
+          label="Base URL"
+          type="url"
+          className={styles.mono}
+          value={draft.base_url}
+          placeholder="https://"
+          autoComplete="off"
+          spellCheck={false}
+          onChange={(event) => edit({ base_url: event.target.value })}
+        />
+      )}
+      <APIKey saved={saved} draftProvider={draft.provider} />
+
+      <div className={styles.temperature}>
+        <div className={styles.temperatureHeader}>
+          <span id={temperatureId} className={styles.label}>
+            Creativity (temperature)
+          </span>
+          <output htmlFor={temperatureId} className={styles.value}>
+            {draft.temperature.toFixed(1)}
+          </output>
+        </div>
+        <Slider
+          aria-labelledby={temperatureId}
+          aria-valuetext={`${draft.temperature.toFixed(1)}, from Familiar (0) to Adventurous (1)`}
+          value={draft.temperature}
+          min={0}
+          max={1}
+          step={0.1}
+          onChange={(event) => edit({ temperature: Math.round(Number(event.target.value) * 10) / 10 })}
+        />
+        <div className={styles.ends} aria-hidden="true">
+          <span>Familiar</span>
+          <span>Adventurous</span>
+        </div>
+      </div>
+
+      <PromptField value={draft.system_prompt} onChange={(system_prompt) => edit({ system_prompt })} />
+
+      <div className={styles.status} role="status">
+        {save.isSuccess && !dirty && 'Changes saved.'}
+      </div>
+      {save.isError && <p className={styles.error} role="alert">{saveErrorMessage(save.error)}</p>}
+      {resetPrompt.isError && !confirmingReset && (
+        <p className={styles.error} role="alert">
+          The system prompt was not reset: {resetPrompt.error.message}
+        </p>
+      )}
+
+      <div className={styles.actions}>
+        <Button variant="outline" className={styles.reset} onClick={() => setConfirmingReset(true)}>
+          Reset
+        </Button>
+        <Button className={styles.save} disabled={!dirty || save.isPending} onClick={onSave}>
+          {save.isPending ? 'Saving…' : 'Save changes'}
+        </Button>
+      </div>
+
+      <Confirm
+        open={confirmingReset}
+        title="Reset the system prompt?"
+        confirmLabel={resetPrompt.isPending ? 'Resetting…' : 'Reset prompt'}
+        busy={resetPrompt.isPending}
+        error={resetPrompt.isError ? `The system prompt was not reset: ${resetPrompt.error.message}` : null}
+        onCancel={() => setConfirmingReset(false)}
+        onConfirm={onConfirmReset}
+      >
+        This restores MealQuest's default system prompt for everyone in the household.
+      </Confirm>
+    </fieldset>
+  )
+}
+
+// formatVerifiedDate turns key_verified_at into the handoff's "Oct 1".
+export function formatVerifiedDate(timestamp: string): string {
+  const date = new Date(timestamp)
+  if (Number.isNaN(date.getTime())) throw new Error(`key_verified_at "${timestamp}" is not a timestamp`)
+  return new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric' }).format(date)
+}
+
+// keyLockedGuidance is how to change the provider or base URL while a key
+// is stored.
+const keyLockedGuidance =
+  'An API key is stored. Remove it (Replace → Remove key) before changing the provider or base URL.'
+
+// APIKey stays mounted whatever provider the draft names, so a key stored
+// (and the verify that follows it) completes even if the household changes
+// the provider meanwhile, and a stored key can always be removed.
+function APIKey({ saved, draftProvider }: { saved: AISettings; draftProvider: AIProvider }) {
+  const [replacing, setReplacing] = useState(false)
+  const [key, setKey] = useState('')
+  const store = useSetAIKey()
+  const verify = useVerifyAIKey()
+  const labelId = useId()
+  const sheetTitleId = useId()
+  const last4 = saved.api_key_last4
+  const providerChanged = draftProvider !== saved.provider
+
+  function open() {
+    store.reset()
+    setReplacing(true)
+  }
+
+  // close keeps the store mutation: a key already sent is still stored and
+  // verified after the sheet is dismissed.
+  function close() {
+    setReplacing(false)
+    setKey('')
+  }
+
+  function onStore() {
+    verify.reset()
+    store.mutate(key, {
+      onSuccess: () => {
+        close()
+        verify.mutate(undefined)
+      },
+    })
+  }
+
+  function onRemove() {
+    verify.reset()
+    store.mutate('', { onSuccess: close })
+  }
+
+  const storeError = store.isError && (
+    <p className={styles.error} role="alert">
+      The key was not stored: {store.error.message}
+    </p>
+  )
+
+  if (last4 === null && aiKeyPolicy[draftProvider] === 'none') {
+    return (
+      <div className={styles.key}>
+        <p className={styles.hint}>{aiProviderLabels[draftProvider]} takes no API key.</p>
+        {!replacing && storeError}
+      </div>
+    )
+  }
+
+  return (
+    <div className={styles.key}>
+      <span id={labelId} className={styles.label}>
+        API key
+      </span>
+      <div className={styles.keyRow} role="group" aria-labelledby={labelId}>
+        <span className={styles.keyValue}>{last4 === null ? 'No key stored' : maskedKey(last4)}</span>
+        <button
+          type="button"
+          className={styles.replace}
+          disabled={store.isPending || (last4 === null && providerChanged)}
+          onClick={open}
+        >
+          {store.isPending ? 'Saving…' : last4 === null ? 'Add key' : 'Replace'}
+        </button>
+      </div>
+      {last4 === null && providerChanged && (
+        <p className={styles.note}>Save the provider change before adding its key.</p>
+      )}
+      {!replacing && storeError}
+      <KeyStatus saved={saved} verify={verify} />
+
+      <Sheet open={replacing} onClose={close} aria-labelledby={sheetTitleId}>
+        <form
+          className={styles.sheet}
+          onSubmit={(event) => {
+            event.preventDefault()
+            onStore()
+          }}
+        >
+          <h2 id={sheetTitleId} className={styles.sheetTitle}>
+            {last4 === null ? 'Add API key' : 'Replace API key'}
+          </h2>
+          <p className={styles.sheetText}>
+            The key is stored on the server for {aiProviderLabels[saved.provider]}. This device only ever sees its
+            last four characters.
+          </p>
+          <TextInput
+            label="API key"
+            type="password"
+            className={styles.mono}
+            value={key}
+            autoComplete="off"
+            spellCheck={false}
+            onChange={(event) => setKey(event.target.value)}
+          />
+          {storeError}
+          <div className={styles.sheetActions}>
+            {last4 !== null && (
+              <Button variant="outline" disabled={store.isPending} onClick={onRemove}>
+                Remove key
+              </Button>
+            )}
+            <Button type="submit" disabled={key === '' || store.isPending}>
+              {store.isPending ? 'Saving…' : 'Save and verify'}
+            </Button>
+          </div>
+        </form>
+      </Sheet>
+    </div>
+  )
+}
+
+type KeyStatusProps = {
+  saved: AISettings
+  verify: ReturnType<typeof useVerifyAIKey>
+}
+
+// KeyStatus is the line under the key: verifying, the verify error, when it
+// was verified, or that it has not been.
+function KeyStatus({ saved, verify }: KeyStatusProps) {
+  if (saved.api_key_last4 === null) return null
+  if (verify.isPending) return <p className={styles.note}>Verifying…</p>
+  if (verify.isError) {
+    return (
+      <div className={styles.keyStatus}>
+        <p className={styles.error} role="alert">
+          {verifyErrorMessage(verify.error)}
+        </p>
+        <VerifyButton verify={verify}>Try again</VerifyButton>
+      </div>
+    )
+  }
+  if (saved.key_verified_at !== null) {
+    return <p className={styles.verified}>Verified · {formatVerifiedDate(saved.key_verified_at)}</p>
+  }
+  return (
+    <div className={styles.keyStatus}>
+      <p className={styles.note}>Not verified yet</p>
+      <VerifyButton verify={verify}>Verify</VerifyButton>
+    </div>
+  )
+}
+
+function VerifyButton({ verify, children }: { verify: KeyStatusProps['verify']; children: ReactNode }) {
+  return (
+    <button type="button" className={styles.link} onClick={() => verify.mutate(undefined)}>
+      {children}
+    </button>
+  )
+}
+
+// verifyErrorMessage says why POST /settings/ai/verify failed, by the
+// error code the server names (internal/server/aisettings.go).
+export function verifyErrorMessage(error: Error): string {
+  if (!(error instanceof ApiError)) return `Verification failed: ${error.message}`
+  switch (error.code) {
+    case 'auth_failed':
+      return 'Verification failed: the provider rejected this key.'
+    case 'rate_limited':
+      return 'Verification failed: the provider is rate limiting requests. Try again shortly.'
+    case 'timeout':
+      return 'Verification failed: the provider did not answer in time.'
+    case 'settings_changed':
+      return 'Verification failed: the settings changed while verifying. Try again.'
+    default:
+      return `Verification failed: ${error.message}`
+  }
+}
+
+// saveErrorMessage says why a save failed. The server refuses to move a
+// stored key to another provider or base URL; it names how to fix that.
+function saveErrorMessage(error: Error): string {
+  if (error instanceof ApiError && error.code === 'invalid_settings') {
+    const guidance = error.message.includes('while an API key is stored') ? ` ${keyLockedGuidance}` : ''
+    return `Not saved: ${error.message}.${guidance}`
+  }
+  return `Not saved: ${error.message}`
+}
+
+function PromptField({ value, onChange }: { value: string; onChange: (value: string) => void }) {
+  const id = useId()
+  return (
+    <div className={styles.prompt}>
+      <label htmlFor={id} className={styles.label}>
+        System prompt
+      </label>
+      <textarea
+        id={id}
+        className={styles.textarea}
+        value={value}
+        rows={8}
+        spellCheck={false}
+        onChange={(event) => onChange(event.target.value)}
+      />
+    </div>
+  )
+}
@@ -0,0 +1,237 @@
+/* Settings · Household. */
+.page {
+  box-sizing: border-box;
+  min-height: 100%;
+  max-width: 560px;
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  padding-top: 6px;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.kicker {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--color-accent-700);
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 28px;
+  font-weight: 400;
+}
+
+.shared {
+  margin: 0;
+  padding: 14px 16px;
+  border-radius: 26px;
+  background: var(--color-accent-2-100);
+  color: var(--color-accent-2-900);
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+}
+
+.loading {
+  height: 420px;
+  border-radius: 26px;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  border: 1px solid var(--color-neutral-300);
+}
+
+.cardTitle {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 22px;
+  font-weight: 400;
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-width: 0;
+}
+
+.groupLabel {
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--color-neutral-700);
+}
+
+.columns {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  gap: 10px;
+  align-items: end;
+}
+
+.time {
+  width: 100%;
+}
+
+/* Beside a day dropdown, a time matches its height. */
+.pairedTime {
+  height: 56px;
+}
+
+.hint,
+.error,
+.status {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 13px;
+  line-height: 1.4;
+}
+
+.hint {
+  color: var(--color-neutral-700);
+}
+
+.error {
+  font-weight: 700;
+  color: var(--color-accent-700);
+}
+
+.errors {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.status {
+  color: var(--color-accent-2-800);
+}
+
+.status:empty {
+  display: none;
+}
+
+.zoneRow {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: 56px;
+  padding: 0 6px 0 20px;
+  border: 1px solid var(--color-neutral-300);
+  border-radius: var(--radius-pill);
+  background: var(--color-surface);
+}
+
+.zoneValue {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: 0 8px;
+}
+
+.zoneName {
+  min-width: 0;
+  overflow: hidden;
+  font-family: var(--font-body);
+  font-size: 15px;
+  font-weight: 700;
+  text-overflow: ellipsis;
+}
+
+.offset {
+  font-family: var(--font-mono);
+  font-size: 13px;
+  color: var(--color-neutral-700);
+}
+
+.change {
+  flex: none;
+  min-width: 44px;
+  min-height: 44px;
+  padding: 0 18px;
+  border: 0;
+  border-radius: var(--radius-pill);
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.actions {
+  margin-top: auto;
+  display: grid;
+  padding-top: 6px;
+}
+
+.save {
+  min-height: 52px;
+}
+
+.sheet {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  max-width: 560px;
+  margin: 0 auto;
+}
+
+.zoneList {
+  max-height: 50vh;
+  margin: 0;
+  padding: 0;
+  overflow-y: auto;
+  list-style: none;
+}
+
+.zoneOption {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  min-width: 44px;
+  min-height: 48px;
+  padding: 0 16px;
+  border: 0;
+  border-radius: var(--radius-pill);
+  background: transparent;
+  color: var(--color-text);
+  text-align: start;
+  cursor: pointer;
+}
+
+.zoneOption .zoneName {
+  flex: 1;
+}
+
+.zoneOption[aria-pressed='true'] {
+  background: var(--color-accent-2-100);
+  color: var(--color-accent-2-900);
+}
+
+.check {
+  flex: none;
+}
+
+/* A form locked while its save is pending, so no edit is made that the
+   saved settings would then replace. It lays out as if it were not there. */
+.lock {
+  display: contents;
+}
@@ -0,0 +1,394 @@
+import { QueryClientProvider } from '@tanstack/react-query'
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+import { Route, Routes, useLocation } from 'react-router'
+import { afterEach, describe, expect, it, vi, type Mock } from 'vitest'
+import { ApiProvider, ApiError, createApiClient, createQueryClient, createVerifiedSession } from '../api/index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
+import { HOUSEHOLD_SETTINGS } from '../test/ApiProviders.tsx'
+import { InDataRouter } from '../test/dataRouter.tsx'
+import { errorResponse, fakeLocation, jsonResponse, ME } from '../test/fetchStub.ts'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { householdSettingsProblems } from './api.ts'
+import { HouseholdSettingsPage } from './HouseholdSettingsPage.tsx'
+import { matchesZone, utcOffset, zoneLabel } from './timezones.ts'
+
+type Responder = (body: unknown) => Response | Promise<Response>
+
+// stubAPI answers "METHOD path" from responders, each called with the
+// request's decoded JSON body; GET /settings/household answers
+// HOUSEHOLD_SETTINGS unless overridden. Any other request fails the test.
+function stubAPI(responders: Record<string, Responder> = {}): Mock<typeof fetch> {
+  const all: Record<string, Responder> = {
+    'GET /api/v1/me': () => jsonResponse(200, ME),
+    'GET /api/v1/settings/household': () => jsonResponse(200, HOUSEHOLD_SETTINGS),
+    ...responders,
+  }
+  const fetchMock = vi.fn<typeof fetch>((input, init) => {
+    const key = `${init?.method ?? 'GET'} ${String(input)}`
+    const respond = Object.hasOwn(all, key) ? all[key] : undefined
+    if (respond === undefined) throw new Error(`unexpected fetch: ${key}`)
+    const body = typeof init?.body === 'string' ? (JSON.parse(init.body) as unknown) : undefined
+    return Promise.resolve(respond(body))
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+// sent lists the requests other than GETs, as "METHOD path" and body.
+function sent(fetchMock: Mock<typeof fetch>) {
+  return fetchMock.mock.calls
+    .filter(([, init]) => (init?.method ?? 'GET') !== 'GET')
+    .map(([input, init]) => ({
+      request: `${init?.method} ${String(input)}`,
+      body: typeof init?.body === 'string' ? (JSON.parse(init.body) as unknown) : undefined,
+    }))
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+function CurrentPath() {
+  return <p data-testid="path">{useLocation().pathname}</p>
+}
+
+// renderPage loads /me (for the CSRF token every write needs) and renders
+// the page at /settings/household in a data router, so its leave guard works.
+async function renderPage() {
+  const api = createApiClient(
+    fakeLocation('/settings/household'),
+    createNetworkStatus(window),
+    createVerifiedSession(localStorage),
+  )
+  await api.loadMe()
+  render(
+    <ApiProvider client={api}>
+      <QueryClientProvider client={createQueryClient()}>
+        <InDataRouter path="/settings/household">
+          <Routes>
+            <Route path="/settings/household" element={<HouseholdSettingsPage />} />
+            <Route path="*" element={<CurrentPath />} />
+          </Routes>
+        </InDataRouter>
+      </QueryClientProvider>
+    </ApiProvider>,
+  )
+  await screen.findByLabelText('Dinner time')
+}
+
+const save = () => screen.getByRole('button', { name: 'Save changes' })
+const input = (name: string) => screen.getByLabelText(name)
+const zoneGroup = () => screen.getByRole('group', { name: 'Time zone' })
+
+describe('HouseholdSettingsPage', () => {
+  it('loads every household setting with plain-word copy', async () => {
+    stubAPI()
+    await renderPage()
+    expect(screen.getByRole('button', { name: 'Back to Settings' })).toBeInTheDocument()
+    expect(screen.getByRole('heading', { level: 1, name: 'Household' })).toBeInTheDocument()
+    expect(screen.getByText('Changes apply to everyone in the household.')).toBeInTheDocument()
+
+    expect(zoneGroup()).toHaveTextContent('America / New York')
+    expect(zoneGroup()).toHaveTextContent(utcOffset('America/New_York', new Date()))
+    expect(input('Dinner time')).toHaveValue('17:30')
+    expect(input('Dinner time')).toHaveAccessibleDescription(/crock-pot dinners count back from it/)
+    expect(input('Day-of reminder')).toHaveValue('16:30')
+    expect(input('Rotation check')).toHaveValue('09:00')
+    expect(input('Rotation check')).toHaveAccessibleDescription(/When we ask whether to keep a new dinner/)
+    expect(input('Plan draft day')).toHaveValue('5')
+    expect(within(input('Plan draft day')).getByRole('option', { selected: true })).toHaveTextContent('Friday')
+    expect(input('Plan draft time')).toHaveValue('09:00')
+    expect(input('New suggestions day')).toHaveValue('0')
+    expect(input('New suggestions time')).toHaveValue('08:00')
+    expect(input('Google Chat Supply run day')).toHaveValue('6')
+    expect(input('Google Chat Supply run time')).toHaveValue('08:00')
+    expect(input('Google Chat Supply run time')).toHaveAccessibleDescription(/Supply run is sent to your Google Chat/)
+    expect(save()).toBeDisabled()
+  })
+
+  it('reports a load failure with a retry', async () => {
+    stubAPI({ 'GET /api/v1/settings/household': () => errorResponse(500, 'internal') })
+    const api = createApiClient(
+      fakeLocation('/settings/household'),
+      createNetworkStatus(window),
+      createVerifiedSession(localStorage),
+    )
+    render(
+      <ApiProvider client={api}>
+        <QueryClientProvider client={createQueryClient()}>
+          <InDataRouter path="/settings/household">
+            <HouseholdSettingsPage />
+          </InDataRouter>
+        </QueryClientProvider>
+      </ApiProvider>,
+    )
+    expect(await screen.findByRole('alert')).toHaveTextContent('Household settings could not load: internal message')
+    expect(screen.getByRole('button', { name: 'Retry' })).toBeInTheDocument()
+  })
+
+  it('saves only the edited fields', async () => {
+    const fetchMock = stubAPI({
+      'PATCH /api/v1/settings/household': (body) => jsonResponse(200, { ...HOUSEHOLD_SETTINGS, ...(body as object) }),
+    })
+    await renderPage()
+    fireEvent.change(input('Dinner time'), { target: { value: '18:15' } })
+    fireEvent.change(input('Rotation check'), { target: { value: '10:00' } })
+    fireEvent.change(input('Plan draft day'), { target: { value: '4' } })
+    fireEvent.change(input('Google Chat Supply run time'), { target: { value: '07:30' } })
+    // Changed and changed back: not sent.
+    fireEvent.change(input('Day-of reminder'), { target: { value: '16:00' } })
+    fireEvent.change(input('Day-of reminder'), { target: { value: '16:30' } })
+    fireEvent.click(save())
+
+    expect(await screen.findByText('Changes saved.')).toBeInTheDocument()
+    expect(sent(fetchMock)).toEqual([
+      {
+        request: 'PATCH /api/v1/settings/household',
+        body: { dinner_time: '18:15', review_time: '10:00', plan_draft_dow: 4, chat_autosend_time: '07:30' },
+      },
+    ])
+    expect(input('Dinner time')).toHaveValue('18:15')
+    expect(save()).toBeDisabled()
+  })
+
+  it('chooses a time zone from the searchable list', async () => {
+    const fetchMock = stubAPI({
+      'PATCH /api/v1/settings/household': (body) => jsonResponse(200, { ...HOUSEHOLD_SETTINGS, ...(body as object) }),
+    })
+    await renderPage()
+    fireEvent.click(within(zoneGroup()).getByRole('button', { name: 'Change' }))
+    const sheet = screen.getByRole('dialog', { name: 'Choose a time zone' })
+    const list = within(sheet).getByRole('list', { name: 'Time zones' })
+    expect(within(list).getByRole('button', { pressed: true })).toHaveAccessibleName(
+      `America / New York, ${utcOffset('America/New_York', new Date())}`,
+    )
+
+    fireEvent.change(within(sheet).getByRole('searchbox', { name: 'Search time zones' }), {
+      target: { value: 'los angeles' },
+    })
+    const options = within(list).getAllByRole('button')
+    expect(options).toHaveLength(1)
+    expect(within(sheet).getByText('1 time zone')).toBeInTheDocument()
+    expect(options[0]).toHaveAccessibleName(`America / Los Angeles, ${utcOffset('America/Los_Angeles', new Date())}`)
+    fireEvent.click(options[0]!)
+
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument()
+    expect(zoneGroup()).toHaveTextContent('America / Los Angeles')
+    fireEvent.click(save())
+    await screen.findByText('Changes saved.')
+    expect(sent(fetchMock)).toEqual([
+      { request: 'PATCH /api/v1/settings/household', body: { timezone: 'America/Los_Angeles' } },
+    ])
+  })
+
+  it('offers the UTC zones the browser list leaves out', async () => {
+    expect(Intl.supportedValuesOf('timeZone')).not.toContain('Etc/UTC')
+    const fetchMock = stubAPI({
+      'PATCH /api/v1/settings/household': (body) => jsonResponse(200, { ...HOUSEHOLD_SETTINGS, ...(body as object) }),
+    })
+    await renderPage()
+    expect(zoneGroup()).toHaveTextContent('America / New York')
+    fireEvent.click(within(zoneGroup()).getByRole('button', { name: 'Change' }))
+    const sheet = screen.getByRole('dialog', { name: 'Choose a time zone' })
+    const list = within(sheet).getByRole('list', { name: 'Time zones' })
+    fireEvent.change(within(sheet).getByRole('searchbox', { name: 'Search time zones' }), {
+      target: { value: 'utc' },
+    })
+    expect(within(list).getByRole('button', { name: 'UTC, UTC+00:00' })).toBeInTheDocument()
+    fireEvent.click(within(list).getByRole('button', { name: 'Etc / UTC, UTC+00:00' }))
+
+    expect(zoneGroup()).toHaveTextContent('Etc / UTC')
+    fireEvent.click(save())
+    await screen.findByText('Changes saved.')
+    expect(sent(fetchMock)).toEqual([
+      { request: 'PATCH /api/v1/settings/household', body: { timezone: 'Etc/UTC' } },
+    ])
+  })
+
+  it('keeps offering a saved zone the browser list leaves out after another is chosen', async () => {
+    expect(Intl.supportedValuesOf('timeZone')).not.toContain('US/Eastern')
+    stubAPI({
+      'GET /api/v1/settings/household': () => jsonResponse(200, { ...HOUSEHOLD_SETTINGS, timezone: 'US/Eastern' }),
+    })
+    await renderPage()
+    const search = (value: string) =>
+      fireEvent.change(screen.getByRole('searchbox', { name: 'Search time zones' }), { target: { value } })
+    const option = (name: RegExp) =>
+      within(screen.getByRole('list', { name: 'Time zones' })).getByRole('button', { name })
+
+    fireEvent.click(within(zoneGroup()).getByRole('button', { name: 'Change' }))
+    search('los angeles')
+    fireEvent.click(option(/^America \/ Los Angeles,/))
+    expect(zoneGroup()).toHaveTextContent('America / Los Angeles')
+
+    fireEvent.click(within(zoneGroup()).getByRole('button', { name: 'Change' }))
+    search('us eastern')
+    fireEvent.click(option(/^US \/ Eastern,/))
+    expect(zoneGroup()).toHaveTextContent('US / Eastern')
+    expect(save()).toBeDisabled()
+  })
+
+  it('says when no time zone matches the search', async () => {
+    stubAPI()
+    await renderPage()
+    fireEvent.click(within(zoneGroup()).getByRole('button', { name: 'Change' }))
+    const sheet = screen.getByRole('dialog', { name: 'Choose a time zone' })
+    fireEvent.change(within(sheet).getByRole('searchbox'), { target: { value: 'Atlantis' } })
+    expect(within(sheet).getByText('No time zone matches.')).toBeInTheDocument()
+    expect(within(sheet).queryAllByRole('listitem')).toHaveLength(0)
+  })
+
+  it('shows the API validation errors beside their fields', async () => {
+    stubAPI({
+      'PATCH /api/v1/settings/household': () =>
+        jsonResponse(400, {
+          error: {
+            code: 'invalid_settings',
+            message:
+              'invalid household settings: timezone: unknown time zone "Mars/Olympus" (want an IANA zone such as America/New_York); dinner_time: invalid time "" (want 24-hour HH:MM, 00:00-23:59)',
+            retryable: false,
+          },
+        }),
+    })
+    await renderPage()
+    fireEvent.change(input('Dinner time'), { target: { value: '' } })
+    fireEvent.click(save())
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('Not saved: fix the settings marked below their fields.')
+    expect(input('Dinner time')).toHaveAttribute('aria-invalid', 'true')
+    expect(input('Dinner time')).toHaveAccessibleDescription(/^invalid time "" \(want 24-hour HH:MM, 00:00-23:59\)/)
+    expect(zoneGroup()).toHaveAccessibleDescription(
+      'unknown time zone "Mars/Olympus" (want an IANA zone such as America/New_York)',
+    )
+    expect(input('Day-of reminder')).toHaveAttribute('aria-invalid', 'false')
+
+    // Editing again clears the refused save's errors.
+    fireEvent.change(input('Dinner time'), { target: { value: '18:00' } })
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+    expect(input('Dinner time')).toHaveAttribute('aria-invalid', 'false')
+  })
+
+  it('shows an error that names no field as a whole-form error', async () => {
+    stubAPI({ 'PATCH /api/v1/settings/household': () => errorResponse(500, 'internal') })
+    await renderPage()
+    fireEvent.change(input('Dinner time'), { target: { value: '18:00' } })
+    fireEvent.click(save())
+    expect(await screen.findByRole('alert')).toHaveTextContent('Not saved: internal message')
+    expect(input('Dinner time')).toHaveValue('18:00')
+    expect(save()).toBeEnabled()
+  })
+
+  it('asks before leaving with unsaved changes', async () => {
+    stubAPI()
+    await renderPage()
+    fireEvent.change(input('New suggestions time'), { target: { value: '07:00' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Back to Settings' }))
+    const confirm = await screen.findByRole('dialog', { name: 'Leave without saving?' })
+    fireEvent.click(within(confirm).getByRole('button', { name: 'Keep editing' }))
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+    expect(input('New suggestions time')).toHaveValue('07:00')
+
+    fireEvent.click(screen.getByRole('button', { name: 'Back to Settings' }))
+    fireEvent.click(within(await screen.findByRole('dialog')).getByRole('button', { name: 'Leave' }))
+    expect(await screen.findByTestId('path')).toHaveTextContent('/settings')
+  })
+
+  it('locks the form while a save is pending, and guards leaving until the save lands', async () => {
+    let answer: (response: Response) => void = () => {}
+    stubAPI({
+      'PATCH /api/v1/settings/household': () => new Promise<Response>((resolve) => (answer = resolve)),
+    })
+    await renderPage()
+    const unload = () => {
+      const event = new Event('beforeunload', { cancelable: true })
+      act(() => void window.dispatchEvent(event))
+      return event.defaultPrevented
+    }
+    fireEvent.change(input('Dinner time'), { target: { value: '18:15' } })
+    fireEvent.click(save())
+
+    expect(await screen.findByRole('button', { name: 'Saving…' })).toBeDisabled()
+    for (const field of ['Dinner time', 'Day-of reminder', 'Plan draft day', 'Google Chat Supply run time']) {
+      expect(input(field)).toBeDisabled()
+    }
+    expect(screen.getByRole('button', { name: 'Change' })).toBeDisabled()
+    expect(unload()).toBe(true)
+
+    answer(jsonResponse(200, { ...HOUSEHOLD_SETTINGS, dinner_time: '18:15' }))
+    expect(await screen.findByText('Changes saved.')).toBeInTheDocument()
+    expect(input('Dinner time')).toBeEnabled()
+    expect(input('Dinner time')).toHaveValue('18:15')
+    await waitFor(() => expect(unload()).toBe(false))
+  })
+
+  it('leaves without asking when nothing changed', async () => {
+    stubAPI()
+    await renderPage()
+    fireEvent.click(screen.getByRole('button', { name: 'Back to Settings' }))
+    expect(await screen.findByTestId('path')).toHaveTextContent('/settings')
+  })
+
+  it('keeps 44 px tap targets', async () => {
+    stubAPI()
+    await renderPage()
+    for (const control of [
+      screen.getByRole('button', { name: 'Back to Settings' }),
+      within(zoneGroup()).getByRole('button', { name: 'Change' }),
+      input('Dinner time'),
+      input('Plan draft day'),
+      input('Plan draft time'),
+      save(),
+    ]) {
+      expectMinHitArea(control)
+    }
+    fireEvent.click(within(zoneGroup()).getByRole('button', { name: 'Change' }))
+    expectMinHitArea(within(screen.getByRole('dialog')).getAllByRole('button', { pressed: true })[0]!)
+  })
+})
+
+describe('householdSettingsProblems', () => {
+  it('reads each field the server names', () => {
+    const error = new ApiError(
+      400,
+      'invalid_settings',
+      'invalid household settings: plan_draft_dow: invalid day of the week 9 (want 0-6, Sunday = 0); review_time: invalid time "9" (want 24-hour HH:MM, 00:00-23:59)',
+      false,
+    )
+    expect(householdSettingsProblems(error)).toEqual({
+      fields: {
+        plan_draft_dow: 'invalid day of the week 9 (want 0-6, Sunday = 0)',
+        review_time: 'invalid time "9" (want 24-hour HH:MM, 00:00-23:59)',
+      },
+      other: [],
+    })
+  })
+
+  it('keeps a problem naming no field, and any other error, whole', () => {
+    expect(
+      householdSettingsProblems(
+        new ApiError(400, 'invalid_settings', 'invalid household settings: settings: no settings to change', false),
+      ),
+    ).toEqual({ fields: {}, other: ['settings: no settings to change'] })
+    expect(
+      householdSettingsProblems(new ApiError(400, 'invalid_request', 'plan_draft_dow: want a JSON int', false)),
+    ).toEqual({ fields: {}, other: ['plan_draft_dow: want a JSON int'] })
+  })
+})
+
+describe('time zones', () => {
+  it('formats the UTC offset', () => {
+    const winter = new Date('2026-01-15T12:00:00Z')
+    expect(utcOffset('America/New_York', winter)).toBe('UTC-05:00')
+    expect(utcOffset('Asia/Kolkata', winter)).toBe('UTC+05:30')
+    expect(utcOffset('UTC', winter)).toBe('UTC+00:00')
+  })
+
+  it('matches every search word against the name and offset', () => {
+    const option = { zone: 'America/Argentina/Buenos_Aires', offset: 'UTC-03:00' }
+    expect(zoneLabel(option.zone)).toBe('America / Argentina / Buenos Aires')
+    expect(matchesZone(option, 'buenos aires')).toBe(true)
+    expect(matchesZone(option, 'Buenos_Aires')).toBe(true)
+    expect(matchesZone(option, 'utc-03')).toBe(true)
+    expect(matchesZone(option, 'buenos paris')).toBe(false)
+  })
+})
@@ -0,0 +1,412 @@
+import { Check, ChevronLeft } from 'lucide-react'
+import { useEffect, useId, useMemo, useState, type ReactNode } from 'react'
+import { useNavigate } from 'react-router'
+import { Button } from '../ui/Button.tsx'
+import { Card } from '../ui/Card.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { IconButton } from '../ui/IconButton.tsx'
+import { Select } from '../ui/Select.tsx'
+import { Sheet } from '../ui/Sheet.tsx'
+import { Skeleton } from '../ui/Skeleton.tsx'
+import { TextInput } from '../ui/TextInput.tsx'
+import {
+  householdSettingsProblems,
+  useHouseholdSettings,
+  useSaveHouseholdSettings,
+  type HouseholdSettings,
+  type HouseholdSettingsField,
+  type HouseholdSettingsPatch,
+} from './api.ts'
+import styles from './HouseholdSettingsPage.module.css'
+import { LeaveGuard } from './LeaveGuard.tsx'
+import { matchesZone, timeZoneOptions, utcOffset, zoneLabel } from './timezones.ts'
+
+// Days of the week as the server counts them, from Sunday = 0.
+const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] as const
+
+// Settings · Household: the time zone and the times the household's
+// reminders and weekly AI runs happen at. Every field is edited as a draft
+// and saved together; only the changed fields are sent.
+export function HouseholdSettingsPage() {
+  const [dirty, setDirty] = useState(false)
+  return (
+    <div className={styles.page}>
+      <Header />
+      <p className={styles.shared}>Changes apply to everyone in the household.</p>
+      <HouseholdSettingsSections onDirtyChange={setDirty} />
+      <LeaveGuard dirty={dirty} />
+    </div>
+  )
+}
+
+type HouseholdSettingsProps = {
+  // Called with whether the form holds unsaved changes.
+  onDirtyChange: (dirty: boolean) => void
+}
+
+// HouseholdSettingsSections is the screen's form once its settings load,
+// without the screen's header, so the desktop settings (mock 2e) can embed
+// it.
+export function HouseholdSettingsSections({ onDirtyChange }: HouseholdSettingsProps) {
+  const settings = useHouseholdSettings()
+  return (
+    <>
+      {settings.isPending && <Skeleton className={styles.loading} />}
+      {settings.isError && (
+        <ErrorBanner onRetry={() => void settings.refetch()}>
+          Household settings could not load: {settings.error.message}
+        </ErrorBanner>
+      )}
+      {settings.isSuccess && <HouseholdSettingsForm saved={settings.data} onDirtyChange={onDirtyChange} />}
+    </>
+  )
+}
+
+function Header() {
+  const navigate = useNavigate()
+  return (
+    <header className={styles.header}>
+      <IconButton label="Back to Settings" onClick={() => void navigate('/settings')}>
+        <Icon icon={ChevronLeft} size="nav" />
+      </IconButton>
+      <div>
+        <p className={styles.kicker}>Settings</p>
+        <h1 className={styles.title}>Household</h1>
+      </div>
+    </header>
+  )
+}
+
+// patchOf is the PATCH body for the fields draft changes.
+function patchOf(saved: HouseholdSettings, draft: HouseholdSettings): HouseholdSettingsPatch {
+  const patch: Record<string, string | number> = {}
+  for (const field of Object.keys(saved) as HouseholdSettingsField[]) {
+    if (draft[field] !== saved[field]) patch[field] = draft[field]
+  }
+  return patch as HouseholdSettingsPatch
+}
+
+type HouseholdSettingsFormProps = HouseholdSettingsProps & {
+  saved: HouseholdSettings
+}
+
+function HouseholdSettingsForm({ saved, onDirtyChange }: HouseholdSettingsFormProps) {
+  const [draft, setDraft] = useState(saved)
+  const save = useSaveHouseholdSettings()
+  const patch = patchOf(saved, draft)
+  const dirty = Object.keys(patch).length > 0
+  const problems = save.isError ? householdSettingsProblems(save.error) : { fields: {}, other: [] }
+
+  useEffect(() => {
+    onDirtyChange(dirty)
+  }, [dirty, onDirtyChange])
+  useEffect(() => () => onDirtyChange(false), [onDirtyChange])
+
+  function edit(change: Partial<HouseholdSettings>) {
+    save.reset()
+    setDraft((current) => ({ ...current, ...change }))
+  }
+
+  function onSave() {
+    save.mutate(patch, { onSuccess: setDraft })
+  }
+
+  return (
+    <fieldset className={styles.lock} disabled={save.isPending}>
+      <Section title="Time zone">
+        <TimeZoneField
+          value={draft.timezone}
+          saved={saved.timezone}
+          onChange={(timezone) => edit({ timezone })}
+          error={problems.fields.timezone}
+        />
+        <p className={styles.hint}>Every time on this screen is in this zone.</p>
+      </Section>
+
+      <Section title="Dinner">
+        <TimeField
+          draft={draft}
+          edit={edit}
+          problems={problems.fields}
+          name="dinner_time"
+          label="Dinner time"
+          hint="When dinner is on the table. Calendar events start then, and crock-pot dinners count back from it to show when to start."
+        />
+        <TimeField
+          draft={draft}
+          edit={edit}
+          problems={problems.fields}
+          name="reminder_time"
+          label="Day-of reminder"
+          hint="When we remind you what's for dinner tonight."
+        />
+        <TimeField
+          draft={draft}
+          edit={edit}
+          problems={problems.fields}
+          name="review_time"
+          label="Rotation check"
+          hint="When we ask whether to keep a new dinner: the day after you try a Quest-log dinner, we ask “Keep it in rotation?”"
+        />
+      </Section>
+
+      <Section title="Every week">
+        <DayTimeField
+          draft={draft}
+          edit={edit}
+          problems={problems.fields}
+          day="plan_draft_dow"
+          time="plan_draft_time"
+          label="Plan draft"
+          hint="When the AI drafts next week's plan on the Draft board for you to adjust."
+        />
+        <DayTimeField
+          draft={draft}
+          edit={edit}
+          problems={problems.fields}
+          day="suggestions_dow"
+          time="suggestions_time"
+          label="New suggestions"
+          hint="When a fresh batch of Side quests arrives to swipe through."
+        />
+        <DayTimeField
+          draft={draft}
+          edit={edit}
+          problems={problems.fields}
+          day="chat_autosend_dow"
+          time="chat_autosend_time"
+          label="Google Chat Supply run"
+          hint="When the week's Supply run is sent to your Google Chat space."
+        />
+      </Section>
+
+      <div className={styles.status} role="status">
+        {save.isSuccess && !dirty && 'Changes saved.'}
+      </div>
+      {save.isError && (
+        <div className={styles.errors} role="alert">
+          {Object.keys(problems.fields).length > 0 && (
+            <p className={styles.error}>Not saved: fix the settings marked below their fields.</p>
+          )}
+          {problems.other.map((reason) => (
+            <p key={reason} className={styles.error}>
+              Not saved: {reason}
+            </p>
+          ))}
+        </div>
+      )}
+
+      <div className={styles.actions}>
+        <Button className={styles.save} disabled={!dirty || save.isPending} onClick={onSave}>
+          {save.isPending ? 'Saving…' : 'Save changes'}
+        </Button>
+      </div>
+    </fieldset>
+  )
+}
+
+function Section({ title, children }: { title: string; children: ReactNode }) {
+  const titleId = useId()
+  return (
+    <Card role="region" aria-labelledby={titleId} className={styles.card}>
+      <h2 id={titleId} className={styles.cardTitle}>
+        {title}
+      </h2>
+      {children}
+    </Card>
+  )
+}
+
+function FieldError({ id, error }: { id: string; error: string | undefined }) {
+  if (error === undefined) return null
+  return (
+    <p id={id} className={styles.error}>
+      {error}
+    </p>
+  )
+}
+
+type FieldProps = {
+  draft: HouseholdSettings
+  edit: (change: Partial<HouseholdSettings>) => void
+  problems: Partial<Record<HouseholdSettingsField, string>>
+  label: string
+  hint: string
+}
+
+type TimeFieldProps = FieldProps & { name: 'dinner_time' | 'reminder_time' | 'review_time' }
+
+function TimeField({ draft, edit, problems, name, label, hint }: TimeFieldProps) {
+  const hintId = useId()
+  const errorId = useId()
+  const error = problems[name]
+  return (
+    <div className={styles.field}>
+      <TextInput
+        label={label}
+        type="time"
+        className={styles.time}
+        value={draft[name]}
+        aria-invalid={error !== undefined}
+        aria-describedby={error === undefined ? hintId : `${errorId} ${hintId}`}
+        onChange={(event) => edit({ [name]: event.target.value })}
+      />
+      <FieldError id={errorId} error={error} />
+      <p id={hintId} className={styles.hint}>
+        {hint}
+      </p>
+    </div>
+  )
+}
+
+type DayTimeFieldProps = FieldProps & {
+  day: 'plan_draft_dow' | 'suggestions_dow' | 'chat_autosend_dow'
+  time: 'plan_draft_time' | 'suggestions_time' | 'chat_autosend_time'
+}
+
+function DayTimeField({ draft, edit, problems, day, time, label, hint }: DayTimeFieldProps) {
+  const hintId = useId()
+  const dayErrorId = useId()
+  const timeErrorId = useId()
+  const dayError = problems[day]
+  const timeError = problems[time]
+  return (
+    <div className={styles.field} role="group" aria-label={label}>
+      <div className={styles.columns}>
+        <Select
+          label={`${label} day`}
+          value={draft[day]}
+          aria-invalid={dayError !== undefined}
+          aria-describedby={dayError === undefined ? hintId : `${dayErrorId} ${hintId}`}
+          onChange={(event) => edit({ [day]: Number(event.target.value) })}
+        >
+          {days.map((name, index) => (
+            <option key={name} value={index}>
+              {name}
+            </option>
+          ))}
+        </Select>
+        <TextInput
+          label={`${label} time`}
+          type="time"
+          className={`${styles.time} ${styles.pairedTime}`}
+          value={draft[time]}
+          aria-invalid={timeError !== undefined}
+          aria-describedby={timeError === undefined ? hintId : `${timeErrorId} ${hintId}`}
+          onChange={(event) => edit({ [time]: event.target.value })}
+        />
+      </div>
+      <FieldError id={dayErrorId} error={dayError} />
+      <FieldError id={timeErrorId} error={timeError} />
+      <p id={hintId} className={styles.hint}>
+        {hint}
+      </p>
+    </div>
+  )
+}
+
+type TimeZoneFieldProps = {
+  value: string
+  saved: string
+  onChange: (zone: string) => void
+  error: string | undefined
+}
+
+// TimeZoneField shows the chosen zone and its current UTC offset; Change
+// opens a searchable list of every IANA zone.
+function TimeZoneField({ value, saved, onChange, error }: TimeZoneFieldProps) {
+  const [open, setOpen] = useState(false)
+  const labelId = useId()
+  const errorId = useId()
+  const offset = useMemo(() => utcOffset(value, new Date()), [value])
+  return (
+    <div className={styles.field}>
+      <span id={labelId} className={styles.groupLabel}>
+        Time zone
+      </span>
+      <div
+        className={styles.zoneRow}
+        role="group"
+        aria-labelledby={labelId}
+        aria-describedby={error === undefined ? undefined : errorId}
+      >
+        <span className={styles.zoneValue}>
+          <span className={styles.zoneName}>{zoneLabel(value)}</span>
+          <span className={styles.offset}>{offset}</span>
+        </span>
+        <button type="button" className={styles.change} onClick={() => setOpen(true)}>
+          Change
+        </button>
+      </div>
+      <FieldError id={errorId} error={error} />
+      {open && (
+        <TimeZoneSheet
+          value={value}
+          saved={saved}
+          onClose={() => setOpen(false)}
+          onChoose={(zone) => {
+            onChange(zone)
+            setOpen(false)
+          }}
+        />
+      )}
+    </div>
+  )
+}
+
+type TimeZoneSheetProps = {
+  value: string
+  // The saved zone, offered even after another is chosen.
+  saved: string
+  onClose: () => void
+  onChoose: (zone: string) => void
+}
+
+function TimeZoneSheet({ value, saved, onClose, onChoose }: TimeZoneSheetProps) {
+  const [search, setSearch] = useState('')
+  const titleId = useId()
+  const options = useMemo(() => timeZoneOptions([saved, value], new Date()), [saved, value])
+  const shown = options.filter((option) => matchesZone(option, search))
+  return (
+    <Sheet open onClose={onClose} aria-labelledby={titleId}>
+      <div className={styles.sheet}>
+        <h2 id={titleId} className={styles.cardTitle}>
+          Choose a time zone
+        </h2>
+        <TextInput
+          label="Search time zones"
+          type="search"
+          value={search}
+          placeholder="City, region or UTC offset"
+          autoComplete="off"
+          spellCheck={false}
+          onChange={(event) => setSearch(event.target.value)}
+        />
+        <p className={styles.hint} role="status">
+          {shown.length === 0 ? 'No time zone matches.' : `${shown.length} ${shown.length === 1 ? 'time zone' : 'time zones'}`}
+        </p>
+        <ul className={styles.zoneList} aria-label="Time zones">
+          {shown.map((option) => {
+            const current = option.zone === value
+            return (
+              <li key={option.zone}>
+                <button
+                  type="button"
+                  className={styles.zoneOption}
+                  aria-pressed={current}
+                  aria-label={`${zoneLabel(option.zone)}, ${option.offset}`}
+                  onClick={() => onChoose(option.zone)}
+                >
+                  <span className={styles.zoneName}>{zoneLabel(option.zone)}</span>
+                  <span className={styles.offset}>{option.offset}</span>
+                  {current && <Icon icon={Check} className={styles.check} />}
+                </button>
+              </li>
+            )
+          })}
+        </ul>
+      </div>
+    </Sheet>
+  )
+}
@@ -0,0 +1,38 @@
+/* The confirm sheet the settings screens share. */
+.sheet {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  max-width: 560px;
+  margin: 0 auto;
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 22px;
+  font-weight: 400;
+}
+
+.text {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 14px;
+  line-height: 1.45;
+  color: var(--color-neutral-700);
+}
+
+.error {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 13px;
+  font-weight: 700;
+  line-height: 1.4;
+  color: var(--color-accent-700);
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 10px;
+}
@@ -0,0 +1,80 @@
+import { useEffect, useId, type ReactNode } from 'react'
+import { useBlocker } from 'react-router'
+import { Button } from '../ui/Button.tsx'
+import { Sheet } from '../ui/Sheet.tsx'
+import styles from './LeaveGuard.module.css'
+
+// LeaveGuard asks before leaving the screen with unsaved changes.
+export function LeaveGuard({ dirty }: { dirty: boolean }) {
+  const blocker = useBlocker(
+    ({ currentLocation, nextLocation }) => dirty && currentLocation.pathname !== nextLocation.pathname,
+  )
+  useEffect(() => {
+    if (!dirty) return
+    const onBeforeUnload = (event: BeforeUnloadEvent) => event.preventDefault()
+    window.addEventListener('beforeunload', onBeforeUnload)
+    return () => window.removeEventListener('beforeunload', onBeforeUnload)
+  }, [dirty])
+  return (
+    <Confirm
+      open={blocker.state === 'blocked'}
+      title="Leave without saving?"
+      confirmLabel="Leave"
+      cancelLabel="Keep editing"
+      onCancel={() => blocker.reset?.()}
+      onConfirm={() => blocker.proceed?.()}
+    >
+      Your changes on this screen have not been saved.
+    </Confirm>
+  )
+}
+
+type ConfirmProps = {
+  open: boolean
+  title: string
+  children: ReactNode
+  confirmLabel: string
+  cancelLabel?: string
+  busy?: boolean
+  error?: string | null
+  onCancel: () => void
+  onConfirm: () => void
+}
+
+// Confirm is a sheet asking the household to confirm one action.
+export function Confirm({
+  open,
+  title,
+  children,
+  confirmLabel,
+  cancelLabel = 'Cancel',
+  busy = false,
+  error = null,
+  onCancel,
+  onConfirm,
+}: ConfirmProps) {
+  const titleId = useId()
+  return (
+    <Sheet open={open} onClose={onCancel} aria-labelledby={titleId}>
+      <div className={styles.sheet}>
+        <h2 id={titleId} className={styles.title}>
+          {title}
+        </h2>
+        <p className={styles.text}>{children}</p>
+        {error !== null && (
+          <p className={styles.error} role="alert">
+            {error}
+          </p>
+        )}
+        <div className={styles.actions}>
+          <Button variant="outline" onClick={onCancel}>
+            {cancelLabel}
+          </Button>
+          <Button disabled={busy} onClick={onConfirm}>
+            {confirmLabel}
+          </Button>
+        </div>
+      </div>
+    </Sheet>
+  )
+}
@@ -0,0 +1,275 @@
+import { useEffect, useId, useState } from 'react'
+import { ApiError } from '../api/index.ts'
+import { Button } from '../ui/Button.tsx'
+import { Card } from '../ui/Card.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { Segmented } from '../ui/Segmented.tsx'
+import { Sheet } from '../ui/Sheet.tsx'
+import { Skeleton } from '../ui/Skeleton.tsx'
+import { TextInput } from '../ui/TextInput.tsx'
+import {
+  maskedKey,
+  recipeSearchProviderLabels,
+  useRecipeSearchSettings,
+  useSaveRecipeSearchSettings,
+  useTestRecipeSearch,
+  type RecipeSearchProvider,
+  type RecipeSearchSettings,
+  type RecipeSearchSettingsPatch,
+} from './api.ts'
+import styles from './AISettingsPage.module.css'
+
+const providerOptions = Object.entries(recipeSearchProviderLabels).map(([value, label]) => ({
+  value: value as RecipeSearchProvider,
+  label,
+}))
+
+type RecipeSearchCardProps = {
+  // Called with whether the card holds unsaved changes.
+  onDirtyChange: (dirty: boolean) => void
+}
+
+// RecipeSearchCard is where recipes are searched for: a SearXNG instance or
+// Brave. The provider, SearXNG URL and a new Brave key are edited as a draft
+// and saved together; the client only ever sees the stored key's last four
+// characters. Test searches with the saved settings.
+export function RecipeSearchCard({ onDirtyChange }: RecipeSearchCardProps) {
+  const settings = useRecipeSearchSettings()
+  const titleId = useId()
+  return (
+    <Card className={styles.card} aria-labelledby={titleId} role="region">
+      <h2 id={titleId} className={styles.cardTitle}>
+        Recipe search
+      </h2>
+      <p className={styles.hint}>Where MealQuest looks for real recipes behind each Side quest.</p>
+      {settings.isPending && <Skeleton className={styles.cardLoading} />}
+      {settings.isError && (
+        <ErrorBanner onRetry={() => void settings.refetch()}>
+          Recipe search settings could not load: {settings.error.message}
+        </ErrorBanner>
+      )}
+      {settings.isSuccess && <RecipeSearchForm saved={settings.data} onDirtyChange={onDirtyChange} />}
+    </Card>
+  )
+}
+
+type Draft = {
+  provider: RecipeSearchProvider
+  base_url: string
+  // A new Brave key to store, null when the stored one stays.
+  api_key: string | null
+}
+
+// draftOf starts a household that has not set up recipe search on SearXNG,
+// the sidecar every deployment runs. With no URL saved the field holds the
+// deployment's SearXNG URL, which saving stores.
+function draftOf(saved: RecipeSearchSettings): Draft {
+  return {
+    provider: saved.provider ?? 'searxng',
+    base_url: saved.base_url ?? saved.default_base_url ?? '',
+    api_key: null,
+  }
+}
+
+// patchOf is the PATCH body for what draft changes. Only the chosen
+// provider's field is sent: the other provider's is left as it is.
+function patchOf(saved: RecipeSearchSettings, draft: Draft): RecipeSearchSettingsPatch {
+  const patch: RecipeSearchSettingsPatch = {}
+  if (draft.provider !== saved.provider) patch.provider = draft.provider
+  if (draft.provider === 'searxng' && draft.base_url !== (saved.base_url ?? '')) patch.base_url = draft.base_url
+  if (draft.provider === 'brave' && draft.api_key !== null) patch.api_key = draft.api_key
+  return patch
+}
+
+function sameDraft(a: Draft, b: Draft): boolean {
+  return a.provider === b.provider && a.base_url === b.base_url && a.api_key === b.api_key
+}
+
+function RecipeSearchForm({ saved, onDirtyChange }: { saved: RecipeSearchSettings } & RecipeSearchCardProps) {
+  const [draft, setDraft] = useState(() => draftOf(saved))
+  const save = useSaveRecipeSearchSettings()
+  const test = useTestRecipeSearch()
+  const patch = patchOf(saved, draft)
+  const dirty = Object.keys(patch).length > 0
+  // Only the household's own edits are unsaved changes. Before recipe search
+  // is set up the untouched draft already differs from what is saved — it
+  // suggests SearXNG and the deployment's URL — but leaving it loses nothing.
+  const edited = dirty && !sameDraft(draft, draftOf(saved))
+
+  useEffect(() => {
+    onDirtyChange(edited)
+  }, [edited, onDirtyChange])
+  useEffect(() => () => onDirtyChange(false), [onDirtyChange])
+
+  // An edit clears the last save and test results: they describe the saved
+  // settings, not the draft.
+  function edit(change: Partial<Draft>) {
+    save.reset()
+    test.reset()
+    setDraft((current) => ({ ...current, ...change }))
+  }
+
+  function onSave() {
+    save.mutate(patch, {
+      onSuccess: (settings) => {
+        setDraft(draftOf(settings))
+        test.reset()
+      },
+    })
+  }
+
+  return (
+    <fieldset className={styles.lock} disabled={save.isPending}>
+      <Segmented
+        label="Recipe search provider"
+        options={providerOptions}
+        value={draft.provider}
+        onValueChange={(provider) => edit({ provider })}
+      />
+      {draft.provider === 'searxng' ? (
+        <TextInput
+          label="SearXNG URL"
+          type="url"
+          className={styles.mono}
+          value={draft.base_url}
+          placeholder="https://"
+          autoComplete="off"
+          spellCheck={false}
+          onChange={(event) => edit({ base_url: event.target.value })}
+        />
+      ) : (
+        <BraveKey
+          last4={saved.api_key_last4}
+          newKey={draft.api_key}
+          onKey={(api_key) => edit({ api_key })}
+        />
+      )}
+
+      <div className={styles.status} role="status">
+        {save.isSuccess && !dirty && 'Recipe search saved.'}
+        {test.isSuccess && `Found ${test.data.count} ${test.data.count === 1 ? 'recipe' : 'recipes'} for '${test.data.query}'`}
+      </div>
+      {save.isError && (
+        <p className={styles.error} role="alert">
+          {saveErrorMessage(save.error)}
+        </p>
+      )}
+      {test.isError && (
+        <p className={styles.error} role="alert">
+          {testErrorMessage(test.error)}
+        </p>
+      )}
+      {dirty && saved.provider !== null && <p className={styles.note}>Save your changes to test them.</p>}
+
+      <div className={styles.cardActions}>
+        <Button
+          variant="outline"
+          disabled={dirty || saved.provider === null || test.isPending}
+          onClick={() => test.mutate()}
+        >
+          {test.isPending ? 'Testing…' : 'Test'}
+        </Button>
+        <Button disabled={!dirty || save.isPending} onClick={onSave}>
+          {save.isPending ? 'Saving…' : 'Save recipe search'}
+        </Button>
+      </div>
+    </fieldset>
+  )
+}
+
+type BraveKeyProps = {
+  last4: string | null
+  newKey: string | null
+  onKey: (key: string | null) => void
+}
+
+// BraveKey shows the stored key masked, or the new one waiting to be saved,
+// and takes a new key in a sheet. The key is sent only when the card is
+// saved.
+function BraveKey({ last4, newKey, onKey }: BraveKeyProps) {
+  const [replacing, setReplacing] = useState(false)
+  const [key, setKey] = useState('')
+  const labelId = useId()
+  const sheetTitleId = useId()
+
+  function close() {
+    setReplacing(false)
+    setKey('')
+  }
+
+  let shown = 'No key stored'
+  if (newKey !== null) shown = maskedKey(newKey.slice(-4))
+  else if (last4 !== null) shown = maskedKey(last4)
+
+  return (
+    <div className={styles.key}>
+      <span id={labelId} className={styles.label}>
+        Brave API key
+      </span>
+      <div className={styles.keyRow} role="group" aria-labelledby={labelId}>
+        <span className={styles.keyValue}>{shown}</span>
+        <button type="button" className={styles.replace} onClick={() => setReplacing(true)}>
+          {last4 === null && newKey === null ? 'Add key' : 'Replace'}
+        </button>
+      </div>
+      {newKey !== null && (
+        <div className={styles.keyStatus}>
+          <p className={styles.note}>New key not saved yet</p>
+          <button type="button" className={styles.link} onClick={() => onKey(null)}>
+            Discard
+          </button>
+        </div>
+      )}
+
+      <Sheet open={replacing} onClose={close} aria-labelledby={sheetTitleId}>
+        <form
+          className={styles.sheet}
+          onSubmit={(event) => {
+            event.preventDefault()
+            onKey(key)
+            close()
+          }}
+        >
+          <h2 id={sheetTitleId} className={styles.sheetTitle}>
+            {last4 === null ? 'Add Brave API key' : 'Replace Brave API key'}
+          </h2>
+          <p className={styles.sheetText}>
+            The key is stored on the server when you save recipe search. This device only ever sees its last four
+            characters.
+          </p>
+          <TextInput
+            label="Brave API key"
+            type="password"
+            className={styles.mono}
+            value={key}
+            autoComplete="off"
+            spellCheck={false}
+            onChange={(event) => setKey(event.target.value)}
+          />
+          <div className={styles.sheetActions}>
+            <Button variant="outline" onClick={close}>
+              Cancel
+            </Button>
+            <Button type="submit" disabled={key === ''}>
+              Use this key
+            </Button>
+          </div>
+        </form>
+      </Sheet>
+    </div>
+  )
+}
+
+function saveErrorMessage(error: Error): string {
+  if (error instanceof ApiError && error.code === 'invalid_settings') return `Not saved: ${error.message}.`
+  return `Not saved: ${error.message}`
+}
+
+// testErrorMessage says why POST /settings/recipe-search/test failed, by
+// the error code the server names (internal/server/recipesearch.go).
+function testErrorMessage(error: Error): string {
+  if (error instanceof ApiError && error.code === 'not_configured') {
+    return 'Test failed: recipe search is not set up yet.'
+  }
+  return `Test failed: ${error.message}`
+}
@@ -0,0 +1,153 @@
+/* Settings home, handoff mock 1p. */
+.page {
+  max-width: 560px;
+  display: flex;
+  flex-direction: column;
+}
+
+.title {
+  margin: 0;
+  padding-top: 6px;
+  font-family: var(--font-heading);
+  font-size: 28px;
+  font-weight: 400;
+}
+
+.banner {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-top: 14px;
+  padding: 14px 16px;
+  border-radius: 26px;
+  background: var(--color-accent-2-100);
+  color: var(--color-accent-2-900);
+}
+
+.avatar {
+  flex: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 44px;
+  height: 44px;
+  border-radius: 50%;
+  background: var(--color-accent-2-300);
+  color: var(--color-accent-2-900);
+  font-family: var(--font-heading);
+  font-size: 18px;
+}
+
+.bannerText {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 13px;
+  line-height: 1.35;
+}
+
+.bannerTitle {
+  font-size: 15px;
+  font-weight: 700;
+}
+
+.alert {
+  margin-top: 14px;
+}
+
+.groupLabel {
+  margin: 0;
+  padding: 18px 4px 8px;
+  font-family: var(--font-body);
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--color-neutral-700);
+}
+
+.group {
+  padding: 0;
+  border-radius: 26px;
+}
+
+.admin {
+  box-shadow: inset 0 0 0 2px var(--color-accent-300);
+}
+
+.rows {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* Rows in one card are split by a hairline inset to the row padding. */
+.item + .item {
+  border-top: 1px solid var(--color-neutral-300);
+  margin: 0 16px;
+}
+
+.item + .item .row {
+  padding-left: 0;
+  padding-right: 0;
+}
+
+.row {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  min-width: 44px;
+  min-height: 44px;
+  padding: 14px 16px;
+  border-radius: 26px;
+  color: var(--color-text);
+  text-decoration: none;
+}
+
+.icon {
+  flex: none;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 38px;
+  height: 38px;
+  border-radius: 50%;
+  background: var(--color-bg);
+}
+
+.icon svg {
+  width: 18px;
+  height: 18px;
+}
+
+.body {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  font-family: var(--font-body);
+}
+
+.rowTitle {
+  font-size: 15px;
+  font-weight: 700;
+}
+
+.status {
+  font-size: 12px;
+  color: var(--color-neutral-700);
+}
+
+.statusSkeleton {
+  width: 60%;
+  height: 12px;
+  margin-top: 3px;
+  background: var(--color-neutral-300);
+}
+
+.tag {
+  flex: none;
+}
@@ -0,0 +1,267 @@
+import { QueryClientProvider } from '@tanstack/react-query'
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import { Route, Routes, useLocation } from 'react-router'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ApiProvider, createApiClient, createQueryClient, createVerifiedSession } from '../api/index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
+import { AI_SETTINGS, HOUSEHOLD_SETTINGS, SETTINGS_API } from '../test/ApiProviders.tsx'
+import { declaredStyle } from '../test/cssRules.ts'
+import { InDataRouter } from '../test/dataRouter.tsx'
+import { errorResponse, fakeLocation, jsonResponse, stubFetchByPath } from '../test/fetchStub.ts'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { mockViewport } from '../test/matchMedia.ts'
+import { formatClockTime, modelDisplayName } from './api.ts'
+import { SettingsPage } from './SettingsPage.tsx'
+
+const HOUSEHOLD = HOUSEHOLD_SETTINGS
+const AI = AI_SETTINGS
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  Reflect.deleteProperty(window, 'matchMedia')
+})
+
+const REGULARS_PATH = '/api/v1/dinners?status=regular'
+const CALENDAR_PATH = '/api/v1/settings/calendar'
+const NOTIFICATIONS_PATH = '/api/v1/settings/notifications'
+
+// stubSettings answers as today's server does (see SETTINGS_API), with
+// overrides for the paths a test changes.
+function stubSettings(overrides: Record<string, () => Response> = {}) {
+  return stubFetchByPath({
+    ...SETTINGS_API,
+    '/api/v1/settings/household': () => jsonResponse(200, HOUSEHOLD),
+    '/api/v1/settings/ai': () => jsonResponse(200, AI),
+    ...overrides,
+  })
+}
+
+function CurrentPath() {
+  return <p data-testid="path">{useLocation().pathname}</p>
+}
+
+// renderSettings renders the settings home on a 390 px phone (mock 1p) in a
+// data router (the hidden sub-tabs' leave guard needs one);
+// SettingsTabs.test.tsx covers 768 px and up.
+function renderSettings() {
+  mockViewport(390)
+  const api = createApiClient(fakeLocation('/settings'), createNetworkStatus(window), createVerifiedSession(localStorage))
+  return render(
+    <ApiProvider client={api}>
+      <QueryClientProvider client={createQueryClient()}>
+        <InDataRouter path="/settings">
+          <Routes>
+            <Route path="/settings" element={<SettingsPage />} />
+            <Route path="*" element={<CurrentPath />} />
+          </Routes>
+        </InDataRouter>
+      </QueryClientProvider>
+    </ApiProvider>,
+  )
+}
+
+function row(name: string) {
+  return screen.getByRole('link', { name: new RegExp(`^${name}`) })
+}
+
+describe('SettingsPage', () => {
+  it('renders the title and the shared household banner', async () => {
+    stubSettings()
+    renderSettings()
+    expect(screen.getByRole('heading', { level: 1, name: 'Settings' })).toBeInTheDocument()
+    expect(screen.getByText('Our kitchen')).toBeInTheDocument()
+    expect(screen.getByText('Shared household · changes apply to everyone')).toBeInTheDocument()
+    expect(await screen.findByText('Anthropic · Claude Sonnet')).toBeInTheDocument()
+  })
+
+  it('groups the rows under Household, Alerts and Admin', async () => {
+    stubSettings()
+    renderSettings()
+    const group = (name: string) => within(screen.getByRole('region', { name }))
+    expect(group('Household').getAllByRole('link').map((link) => link.getAttribute('href'))).toEqual([
+      '/settings/regulars',
+      '/settings/calendar',
+      '/settings/household',
+    ])
+    expect(group('Alerts').getByRole('link')).toHaveAttribute('href', '/settings/notifications')
+    expect(group('Admin').getByRole('link')).toHaveAttribute('href', '/settings/ai')
+    await screen.findByText('Anthropic · Claude Sonnet')
+  })
+
+  it('reads every status line from the server', async () => {
+    const fetchMock = stubSettings()
+    renderSettings()
+    expect(await screen.findByText('America/New_York · Dinner at 5:30 pm')).toBeInTheDocument()
+    expect(within(row('AI assistant')).getByText('Anthropic · Claude Sonnet')).toBeInTheDocument()
+    expect(within(row('Household')).getByText('America/New_York · Dinner at 5:30 pm')).toBeInTheDocument()
+    expect(fetchMock.mock.calls.map(([input]) => String(input)).sort()).toEqual([
+      REGULARS_PATH,
+      '/api/v1/settings/ai',
+      '/api/v1/settings/ai/models',
+      CALENDAR_PATH,
+      '/api/v1/settings/household',
+      NOTIFICATIONS_PATH,
+      '/api/v1/settings/recipe-search',
+    ])
+  })
+
+  it('shows the not-yet-available states while the server has no endpoint for them', async () => {
+    stubSettings()
+    renderSettings()
+    expect(await within(row('Regular dinners')).findByText('Rotation count unavailable')).toBeInTheDocument()
+    expect(await within(row('Google Calendar')).findByText('Not connected')).toBeInTheDocument()
+    expect(
+      await within(row('Notifications & Google Chat')).findByText('Push off · Google Chat not connected'),
+    ).toBeInTheDocument()
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+
+  it('shows the Regulars on rotation, the connected calendar and the notifications once served', async () => {
+    stubSettings({
+      [REGULARS_PATH]: () => jsonResponse(200, { dinners: Array.from({ length: 7 }, (_, i) => ({ id: `d${i}` })) }),
+      [CALENDAR_PATH]: () => jsonResponse(200, { connected: true, calendar_name: 'Dinners calendar' }),
+      [NOTIFICATIONS_PATH]: () => jsonResponse(200, { push: true, chat_space: 'Dinner Crew space' }),
+    })
+    renderSettings()
+    expect(await within(row('Regular dinners')).findByText('7 on rotation')).toBeInTheDocument()
+    expect(await within(row('Google Calendar')).findByText('Connected · Dinners calendar')).toBeInTheDocument()
+    expect(
+      await within(row('Notifications & Google Chat')).findByText('Push on · Dinner Crew space'),
+    ).toBeInTheDocument()
+  })
+
+  it('shows no Regulars, a disconnected calendar and push off with no Google Chat space', async () => {
+    stubSettings({
+      [REGULARS_PATH]: () => jsonResponse(200, { dinners: [] }),
+      [CALENDAR_PATH]: () => jsonResponse(200, { connected: false }),
+      [NOTIFICATIONS_PATH]: () => jsonResponse(200, { push: false, chat_space: null }),
+    })
+    renderSettings()
+    expect(await within(row('Regular dinners')).findByText('None on rotation yet')).toBeInTheDocument()
+    expect(await within(row('Google Calendar')).findByText('Not connected')).toBeInTheDocument()
+    expect(
+      await within(row('Notifications & Google Chat')).findByText('Push off · Google Chat not connected'),
+    ).toBeInTheDocument()
+  })
+
+  it('reports a status endpoint failure other than a missing endpoint', async () => {
+    stubSettings({ [CALENDAR_PATH]: () => errorResponse(500, 'internal') })
+    renderSettings()
+    expect(await screen.findByRole('alert')).toHaveTextContent('Settings could not load: internal message')
+    expect(row('Google Calendar')).toHaveAccessibleName('Google Calendar')
+  })
+
+  it('refuses a connected calendar without a name', async () => {
+    stubSettings({ [CALENDAR_PATH]: () => jsonResponse(200, { connected: true }) })
+    renderSettings()
+    expect(await screen.findByRole('alert')).toHaveTextContent('response is not a calendar status')
+  })
+
+  it('shows another provider and model as the settings name them', async () => {
+    stubSettings({
+      '/api/v1/settings/ai': () => jsonResponse(200, { ...AI, provider: 'openai_compatible', model: 'llama3.1:8b' }),
+    })
+    renderSettings()
+    expect(await screen.findByText('OpenAI-compatible · llama3.1:8b')).toBeInTheDocument()
+  })
+
+  it('says no model is chosen for the seeded AI settings', async () => {
+    stubSettings({ '/api/v1/settings/ai': () => jsonResponse(200, { ...AI, model: '' }) })
+    renderSettings()
+    expect(await within(row('AI assistant')).findByText('Anthropic · No model chosen')).toBeInTheDocument()
+  })
+
+  it('marks the AI assistant row Admin and rings its card in grape-300', async () => {
+    stubSettings()
+    renderSettings()
+    expect(within(row('AI assistant')).getByText('Admin')).toBeInTheDocument()
+    const adminCard = screen.getByRole('region', { name: 'Admin' }).querySelector('ul')!.parentElement!
+    expect(declaredStyle(adminCard).boxShadow).toBe('inset 0 0 0 2px var(--color-accent-300)')
+    const householdCard = screen.getByRole('region', { name: 'Household' }).querySelector('ul')!.parentElement!
+    expect(declaredStyle(householdCard).boxShadow).toBe('')
+    await screen.findByText('Anthropic · Claude Sonnet')
+  })
+
+  it.each([
+    ['Regular dinners', '/settings/regulars'],
+    ['Google Calendar', '/settings/calendar'],
+    ['Household', '/settings/household'],
+    ['Notifications & Google Chat', '/settings/notifications'],
+    ['AI assistant', '/settings/ai'],
+  ])('the %s row navigates to %s', async (name, path) => {
+    stubSettings()
+    renderSettings()
+    await screen.findByText('Anthropic · Claude Sonnet')
+    fireEvent.click(row(name))
+    expect(screen.getByTestId('path')).toHaveTextContent(path)
+  })
+
+  it('gives every row a tap target of at least 44 px', async () => {
+    stubSettings()
+    renderSettings()
+    await screen.findByText('Anthropic · Claude Sonnet')
+    for (const link of screen.getAllByRole('link')) expectMinHitArea(link)
+  })
+
+  it('reports a failed status with a retry that loads it', async () => {
+    let householdCalls = 0
+    stubSettings({
+      '/api/v1/settings/household': () => {
+        householdCalls += 1
+        return householdCalls === 1 ? errorResponse(500, 'internal') : jsonResponse(200, HOUSEHOLD)
+      },
+    })
+    renderSettings()
+    expect(await screen.findByRole('alert')).toHaveTextContent('Settings could not load: internal message')
+    expect(screen.getByText('Anthropic · Claude Sonnet')).toBeInTheDocument()
+    expect(row('Household')).toHaveAccessibleName('Household')
+
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }))
+    expect(await screen.findByText('America/New_York · Dinner at 5:30 pm')).toBeInTheDocument()
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument()
+  })
+
+  it('refuses an AI provider it has no name for', async () => {
+    stubSettings({ '/api/v1/settings/ai': () => jsonResponse(200, { ...AI, provider: 'mystery', model: 'm1' }) })
+    renderSettings()
+    expect(await screen.findByRole('alert')).toHaveTextContent('unknown AI provider "mystery"')
+    expect(row('AI assistant')).toHaveAccessibleName('AI assistant Admin')
+  })
+
+  it('refuses a dinner time that is not HH:MM', async () => {
+    stubSettings({
+      '/api/v1/settings/household': () => jsonResponse(200, { ...HOUSEHOLD, timezone: 'UTC', dinner_time: '5:30pm' }),
+    })
+    renderSettings()
+    expect(await screen.findByRole('alert')).toHaveTextContent('dinner_time "5:30pm" is not HH:MM')
+  })
+})
+
+describe('modelDisplayName', () => {
+  it.each([
+    ['claude-sonnet-4-5', 'Claude Sonnet'],
+    ['claude-opus-4-1-20250805', 'Claude Opus'],
+    ['claude-3-5-haiku-20241022', 'Claude Haiku'],
+    ['claude-fable-5-1', 'Claude Fable'],
+    ['gpt-4o', 'gpt-4o'],
+    ['anthropic/claude-sonnet-4.5', 'anthropic/claude-sonnet-4.5'],
+  ])('names %s %s', (model, name) => {
+    expect(modelDisplayName(model)).toBe(name)
+  })
+})
+
+describe('formatClockTime', () => {
+  it.each([
+    ['00:05', '12:05 am'],
+    ['09:00', '9:00 am'],
+    ['12:00', '12:00 pm'],
+    ['17:30', '5:30 pm'],
+    ['23:59', '11:59 pm'],
+  ])('formats %s as %s', (time, formatted) => {
+    expect(formatClockTime(time)).toBe(formatted)
+  })
+
+  it('refuses a time that is not HH:MM', () => {
+    expect(() => formatClockTime('24:00')).toThrow('not a 24-hour HH:MM time')
+  })
+})
@@ -0,0 +1,167 @@
+import type { UseQueryResult } from '@tanstack/react-query'
+import type { LucideIcon } from 'lucide-react'
+import { Bell, Calendar, ChevronRight, Crosshair, Heart, House } from 'lucide-react'
+import { useId, type ReactNode } from 'react'
+import { Link } from 'react-router'
+import { Card } from '../ui/Card.tsx'
+import { ErrorBanner } from '../ui/ErrorBanner.tsx'
+import { Icon } from '../ui/Icon.tsx'
+import { Skeleton } from '../ui/Skeleton.tsx'
+import { Tag } from '../ui/Tag.tsx'
+import { useBreakpoint } from '../shell/useBreakpoint.ts'
+import {
+  aiStatus,
+  calendarStatus,
+  formatClockTime,
+  notificationsStatus,
+  regularDinnersStatus,
+  useAISettings,
+  useCalendarStatus,
+  useHouseholdSettings,
+  useNotificationsStatus,
+  useRegularDinnersCount,
+} from './api.ts'
+import styles from './SettingsPage.module.css'
+import { SettingsTabs } from './SettingsTabs.tsx'
+
+// Settings home: the list of settings pages on mobile (mock 1p), one page
+// with sub-tabs from 768 px (mock 2e). The sub-tabs stay mounted, hidden, on
+// mobile, so an unsaved draft survives the viewport crossing 768 px and its
+// leave guard keeps asking before the list navigates away.
+export function SettingsPage() {
+  const mobile = useBreakpoint() === 'mobile'
+  return (
+    <>
+      {mobile && <SettingsList />}
+      <SettingsTabs hidden={mobile} />
+    </>
+  )
+}
+
+// The mobile settings list (handoff mock 1p). Each row opens its settings
+// page and shows a live status line. Regular dinners, Google Calendar and
+// Notifications & Google Chat read endpoints their features have not served
+// yet; until then each shows its not-yet-available state (see api.ts).
+function SettingsList() {
+  const household = useHouseholdSettings()
+  const ai = useAISettings()
+  const regulars = useRegularDinnersCount()
+  const calendar = useCalendarStatus()
+  const notifications = useNotificationsStatus()
+  const failed = [regulars, calendar, household, notifications, ai].filter((query) => query.isError)
+
+  return (
+    <div className={styles.page}>
+      <h1 className={styles.title}>Settings</h1>
+      <div className={styles.banner}>
+        <span className={styles.avatar} aria-hidden="true">
+          K
+        </span>
+        <p className={styles.bannerText}>
+          <strong className={styles.bannerTitle}>Our kitchen</strong>
+          <span>Shared household · changes apply to everyone</span>
+        </p>
+      </div>
+      {failed.length > 0 && (
+        <div className={styles.alert}>
+          <ErrorBanner onRetry={() => failed.forEach((query) => void query.refetch())}>
+            Settings could not load: {failed.map((query) => query.error?.message).join('; ')}
+          </ErrorBanner>
+        </div>
+      )}
+      <Group label="Household">
+        <SettingsRow
+          to="/settings/regulars"
+          icon={Heart}
+          title="Regular dinners"
+          status={status(regulars, regularDinnersStatus)}
+        />
+        <SettingsRow
+          to="/settings/calendar"
+          icon={Calendar}
+          title="Google Calendar"
+          status={status(calendar, calendarStatus)}
+        />
+        <SettingsRow
+          to="/settings/household"
+          icon={House}
+          title="Household"
+          status={status(household, (s) => `${s.timezone} · Dinner at ${formatClockTime(s.dinner_time)}`)}
+        />
+      </Group>
+      <Group label="Alerts">
+        <SettingsRow
+          to="/settings/notifications"
+          icon={Bell}
+          title="Notifications & Google Chat"
+          status={status(notifications, notificationsStatus)}
+        />
+      </Group>
+      <Group label="Admin" admin>
+        <SettingsRow
+          to="/settings/ai"
+          icon={Crosshair}
+          title="AI assistant"
+          status={status(ai, aiStatus)}
+          tag={<Tag className={styles.tag}>Admin</Tag>}
+        />
+      </Group>
+    </div>
+  )
+}
+
+// status is a row's status line: a skeleton while its query loads, the
+// formatted data once it has, and nothing when it failed (the error banner
+// says why).
+function status<T>(query: UseQueryResult<T>, format: (data: T) => string): ReactNode {
+  if (query.isPending) return <Skeleton className={styles.statusSkeleton} />
+  if (query.isError) return null
+  return format(query.data)
+}
+
+type GroupProps = {
+  label: string
+  // The Admin group's card carries the grape-300 inset ring.
+  admin?: boolean
+  children: ReactNode
+}
+
+function Group({ label, admin = false, children }: GroupProps) {
+  const id = useId()
+  return (
+    <section aria-labelledby={id}>
+      <h2 id={id} className={styles.groupLabel}>
+        {label}
+      </h2>
+      <Card className={[styles.group, admin && styles.admin].filter(Boolean).join(' ')}>
+        <ul className={styles.rows}>{children}</ul>
+      </Card>
+    </section>
+  )
+}
+
+type SettingsRowProps = {
+  to: string
+  icon: LucideIcon
+  title: string
+  status?: ReactNode
+  tag?: ReactNode
+}
+
+function SettingsRow({ to, icon, title, status, tag }: SettingsRowProps) {
+  return (
+    <li className={styles.item}>
+      <Link to={to} className={styles.row}>
+        <span className={styles.icon}>
+          <Icon icon={icon} />
+        </span>
+        <span className={styles.body}>
+          <span className={styles.rowTitle}>{title}</span>
+          {status && <span className={styles.status}>{status}</span>}
+        </span>
+        {tag}
+        <Icon icon={ChevronRight} />
+      </Link>
+    </li>
+  )
+}
@@ -0,0 +1,118 @@
+/* Settings at tablet and desktop widths, handoff mock 2e. */
+.page {
+  box-sizing: border-box;
+  min-height: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+.header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  gap: 14px;
+}
+
+.heading {
+  flex: 1;
+  min-width: 0;
+}
+
+.title {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 40px;
+  font-weight: 400;
+  line-height: 1.1;
+}
+
+.shared {
+  margin: 6px 0 0;
+  font-family: var(--font-body);
+  font-size: 14px;
+  color: var(--color-neutral-800);
+}
+
+.tabs {
+  display: flex;
+  gap: 6px;
+}
+
+.tab {
+  min-width: 44px;
+  min-height: 44px;
+  padding: 0 16px;
+  border: 0;
+  border-radius: var(--radius-pill);
+  background: transparent;
+  color: var(--color-text);
+  font-family: var(--font-body);
+  font-size: 14px;
+  font-weight: 700;
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.selected {
+  background: var(--color-text);
+  color: var(--color-bg);
+}
+
+/* A page's or panel's display would override the hidden attribute. */
+.page[hidden],
+.single[hidden],
+.columns[hidden] {
+  display: none;
+}
+
+.single {
+  max-width: 560px;
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+}
+
+/* Notifications on the left; the AI assistant and Recipe search on the
+   right, the AI assistant card growing to fill the column. */
+.columns {
+  flex: 1;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1.15fr);
+  align-items: stretch;
+  gap: 20px;
+}
+
+.column {
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+/* Mock 2e's cards: 24 px padding, 30 px corners. */
+.column > * {
+  padding: 24px;
+  border-radius: 30px;
+}
+
+.placeholder {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.cardTitle {
+  margin: 0;
+  font-family: var(--font-heading);
+  font-size: 22px;
+  font-weight: 400;
+}
+
+.hint {
+  margin: 0;
+  font-family: var(--font-body);
+  font-size: 14px;
+  line-height: 1.45;
+  color: var(--color-neutral-700);
+}
@@ -0,0 +1,193 @@
+import { QueryClientProvider } from '@tanstack/react-query'
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi, type Mock } from 'vitest'
+import { ApiProvider, createApiClient, createQueryClient, createVerifiedSession } from '../api/index.ts'
+import { createNetworkStatus } from '../pwa/networkStatus.ts'
+import { AI_MODELS, AI_SETTINGS, HOUSEHOLD_SETTINGS, RECIPE_SEARCH_SETTINGS } from '../test/ApiProviders.tsx'
+import { InDataRouter } from '../test/dataRouter.tsx'
+import { errorResponse, fakeLocation, jsonResponse, ME } from '../test/fetchStub.ts'
+import { expectMinHitArea } from '../test/hitArea.ts'
+import { mockViewport } from '../test/matchMedia.ts'
+import { SettingsPage } from './SettingsPage.tsx'
+
+type Responder = (body: unknown) => Response
+
+// stubAPI answers "METHOD path" from responders, each called with the
+// request's decoded JSON body; the settings the page loads answer their
+// fixtures unless overridden. Any other request fails the test.
+function stubAPI(responders: Record<string, Responder> = {}): Mock<typeof fetch> {
+  const all: Record<string, Responder> = {
+    'GET /api/v1/me': () => jsonResponse(200, ME),
+    'GET /api/v1/settings/household': () => jsonResponse(200, HOUSEHOLD_SETTINGS),
+    'GET /api/v1/settings/ai': () => jsonResponse(200, AI_SETTINGS),
+    'GET /api/v1/settings/ai/models': () => jsonResponse(200, AI_MODELS),
+    'GET /api/v1/settings/recipe-search': () => jsonResponse(200, RECIPE_SEARCH_SETTINGS),
+    ...responders,
+  }
+  const fetchMock = vi.fn<typeof fetch>((input, init) => {
+    const key = `${init?.method ?? 'GET'} ${String(input)}`
+    const respond = Object.hasOwn(all, key) ? all[key] : undefined
+    if (respond === undefined) throw new Error(`unexpected fetch: ${key}`)
+    const body = typeof init?.body === 'string' ? (JSON.parse(init.body) as unknown) : undefined
+    return Promise.resolve(respond(body))
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  Reflect.deleteProperty(window, 'matchMedia')
+})
+
+// renderAt renders /settings at width px in a data router (the page's leave
+// guard needs one), after loading /me for the CSRF token writes need.
+// It returns the function that resizes the viewport.
+async function renderAt(width: number) {
+  const resize = mockViewport(width)
+  const api = createApiClient(fakeLocation('/settings'), createNetworkStatus(window), createVerifiedSession(localStorage))
+  await api.loadMe()
+  render(
+    <ApiProvider client={api}>
+      <QueryClientProvider client={createQueryClient()}>
+        <InDataRouter path="/settings">
+          <SettingsPage />
+        </InDataRouter>
+      </QueryClientProvider>
+    </ApiProvider>,
+  )
+  return resize
+}
+
+const tab = (name: string) => screen.getByRole('tab', { name })
+// panel is the panel a tab controls, shown or hidden.
+function panel(name: string): HTMLElement {
+  const id = tab(name).getAttribute('aria-controls')
+  const element = id === null ? null : document.getElementById(id)
+  if (element === null) throw new Error(`tab "${name}" controls no panel`)
+  expect(element).toHaveAttribute('role', 'tabpanel')
+  return element
+}
+
+describe.each([1440, 1180])('SettingsPage at %i px (mock 2e)', (width) => {
+  it('shows the title, the shared line and the sub-tabs, Notifications & AI first', async () => {
+    stubAPI()
+    await renderAt(width)
+    expect(screen.getByRole('heading', { level: 1, name: 'Settings' })).toBeInTheDocument()
+    expect(screen.getByText('Changes apply to everyone in the household.')).toBeInTheDocument()
+    expect(screen.queryByRole('link')).not.toBeInTheDocument()
+    const tabs = within(screen.getByRole('tablist', { name: 'Settings sections' })).getAllByRole('tab')
+    expect(tabs.map((t) => t.textContent)).toEqual(['Household', 'Regular dinners', 'Notifications & AI'])
+    expect(tab('Notifications & AI')).toHaveAttribute('aria-selected', 'true')
+    tabs.forEach(expectMinHitArea)
+
+    const columns = panel('Notifications & AI')
+    expect(columns).toBeVisible()
+    const [left, right] = Array.from(columns.children)
+    expect(within(left as HTMLElement).getByRole('region', { name: 'Notifications & Google Chat' })).toBeInTheDocument()
+    const ai = within(right as HTMLElement).getByRole('region', { name: 'AI assistant' })
+    expect(within(ai).getByText('Admin')).toBeInTheDocument()
+    expect(await within(ai).findByRole('combobox', { name: 'Provider' })).toHaveValue('anthropic')
+    expect(within(ai).getByRole('textbox', { name: 'System prompt' })).toHaveValue(AI_SETTINGS.system_prompt)
+    expect(within(right as HTMLElement).getByRole('region', { name: 'Recipe search' })).toBeInTheDocument()
+  })
+
+  it('switches tabs by click and by arrow keys', async () => {
+    stubAPI()
+    await renderAt(width)
+
+    fireEvent.click(tab('Household'))
+    expect(tab('Household')).toHaveAttribute('aria-selected', 'true')
+    expect(panel('Household')).toBeVisible()
+    expect(panel('Notifications & AI')).not.toBeVisible()
+    expect(await within(panel('Household')).findByRole('button', { name: 'Save changes' })).toBeInTheDocument()
+
+    fireEvent.keyDown(tab('Household'), { key: 'ArrowRight' })
+    expect(tab('Regular dinners')).toHaveAttribute('aria-selected', 'true')
+    expect(tab('Regular dinners')).toHaveFocus()
+    expect(panel('Regular dinners')).toBeVisible()
+    expect(within(panel('Regular dinners')).getByRole('region', { name: 'Regular dinners' })).toBeInTheDocument()
+    expect(panel('Household')).not.toBeVisible()
+
+    fireEvent.keyDown(tab('Regular dinners'), { key: 'End' })
+    expect(tab('Notifications & AI')).toHaveAttribute('aria-selected', 'true')
+    fireEvent.keyDown(tab('Notifications & AI'), { key: 'ArrowRight' })
+    expect(tab('Household')).toHaveAttribute('aria-selected', 'true')
+    expect(tab('Household')).toHaveFocus()
+  })
+
+  it('saves the AI assistant card through the AI settings API', async () => {
+    const fetchMock = stubAPI({
+      'PATCH /api/v1/settings/ai': (body) => jsonResponse(200, { ...AI_SETTINGS, ...(body as object) }),
+    })
+    await renderAt(width)
+    const ai = within(screen.getByRole('region', { name: 'AI assistant' }))
+    const prompt = await ai.findByRole('textbox', { name: 'System prompt' })
+    const save = ai.getByRole('button', { name: 'Save changes' })
+    expect(save).toBeDisabled()
+
+    fireEvent.change(prompt, { target: { value: 'Plan dinners for us.' } })
+    fireEvent.click(save)
+    expect(await ai.findByText('Changes saved.')).toBeInTheDocument()
+
+    const writes = fetchMock.mock.calls.filter(([, init]) => (init?.method ?? 'GET') !== 'GET')
+    expect(writes.map(([input, init]) => [init?.method, String(input), init?.body])).toEqual([
+      ['PATCH', '/api/v1/settings/ai', JSON.stringify({ system_prompt: 'Plan dinners for us.' })],
+    ])
+    expect(prompt).toHaveValue('Plan dinners for us.')
+    expect(save).toBeDisabled()
+  })
+
+  it('keeps an unsaved draft while another tab is shown', async () => {
+    stubAPI()
+    await renderAt(width)
+    const prompt = await screen.findByRole('textbox', { name: 'System prompt' })
+    fireEvent.change(prompt, { target: { value: 'A draft' } })
+
+    fireEvent.click(tab('Household'))
+    fireEvent.click(tab('Notifications & AI'))
+    expect(screen.getByRole('textbox', { name: 'System prompt' })).toHaveValue('A draft')
+  })
+})
+
+describe('SettingsPage across the 768 px breakpoint', () => {
+  it('shows the mobile list below 768 px and the sub-tabs from 768 px', async () => {
+    stubAPI({
+      'GET /api/v1/dinners?status=regular': () => errorResponse(404, 'not_found'),
+      'GET /api/v1/settings/calendar': () => errorResponse(404, 'not_found'),
+      'GET /api/v1/settings/notifications': () => errorResponse(404, 'not_found'),
+    })
+    const resize = await renderAt(767)
+    expect(screen.getByRole('link', { name: /^AI assistant/ })).toHaveAttribute('href', '/settings/ai')
+    expect(screen.queryByRole('tablist')).not.toBeInTheDocument()
+
+    resize(768)
+    expect(screen.getByRole('tablist', { name: 'Settings sections' })).toBeInTheDocument()
+    expect(screen.queryByRole('link')).not.toBeInTheDocument()
+  })
+
+  it('keeps an unsaved draft and its leave guard across 1180 px, 390 px and back', async () => {
+    stubAPI({
+      'GET /api/v1/dinners?status=regular': () => errorResponse(404, 'not_found'),
+      'GET /api/v1/settings/calendar': () => errorResponse(404, 'not_found'),
+      'GET /api/v1/settings/notifications': () => errorResponse(404, 'not_found'),
+    })
+    const resize = await renderAt(1180)
+    fireEvent.change(await screen.findByRole('textbox', { name: 'System prompt' }), {
+      target: { value: 'A draft' },
+    })
+
+    resize(390)
+    expect(screen.queryByRole('tablist')).not.toBeInTheDocument()
+    fireEvent.click(screen.getByRole('link', { name: /^AI assistant/ }))
+    const confirm = await screen.findByRole('dialog', { name: 'Leave without saving?' })
+    fireEvent.click(within(confirm).getByRole('button', { name: 'Keep editing' }))
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument())
+
+    resize(1180)
+    expect(screen.getByRole('textbox', { name: 'System prompt' })).toHaveValue('A draft')
+    const unload = new Event('beforeunload', { cancelable: true })
+    window.dispatchEvent(unload)
+    expect(unload.defaultPrevented).toBe(true)
+  })
+})
@@ -0,0 +1,138 @@
+import { useId, useRef, useState, type KeyboardEvent, type ReactNode } from 'react'
+import { Card } from '../ui/Card.tsx'
+import { AIAssistantCard } from './AISettingsPage.tsx'
+import { HouseholdSettingsSections } from './HouseholdSettingsPage.tsx'
+import { LeaveGuard } from './LeaveGuard.tsx'
+import { RecipeSearchCard } from './RecipeSearchCard.tsx'
+import styles from './SettingsTabs.module.css'
+
+type Tab = 'household' | 'regulars' | 'notifications-ai'
+
+const tabs: readonly { value: Tab; label: string }[] = [
+  { value: 'household', label: 'Household' },
+  { value: 'regulars', label: 'Regular dinners' },
+  { value: 'notifications-ai', label: 'Notifications & AI' },
+]
+
+const step: Record<string, number> = { ArrowRight: 1, ArrowLeft: -1 }
+
+// Settings at tablet and desktop widths (handoff mock 2e): one page with
+// sub-tabs instead of the mobile list. Every tab stays mounted while hidden,
+// so a draft survives switching tabs, and one leave guard covers them all.
+// hidden hides the page but keeps it mounted, drafts and leave guard included.
+export function SettingsTabs({ hidden = false }: { hidden?: boolean }) {
+  const [tab, setTab] = useState<Tab>('notifications-ai')
+  const [householdDirty, setHouseholdDirty] = useState(false)
+  const [aiDirty, setAIDirty] = useState(false)
+  const [recipeSearchDirty, setRecipeSearchDirty] = useState(false)
+  const refs = useRef<(HTMLButtonElement | null)[]>([])
+  const id = useId()
+  const tabId = (value: Tab) => `${id}-tab-${value}`
+  const panelId = (value: Tab) => `${id}-panel-${value}`
+
+  // Arrow keys move between the tabs, wrapping at the ends; Home and End
+  // jump to the first and last. Moving selects the tab.
+  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    const selected = tabs.findIndex((t) => t.value === tab)
+    const delta = step[event.key]
+    let next: number
+    if (delta !== undefined) next = (selected + delta + tabs.length) % tabs.length
+    else if (event.key === 'Home') next = 0
+    else if (event.key === 'End') next = tabs.length - 1
+    else return
+    const nextTab = tabs[next]
+    if (!nextTab) throw new Error(`Settings tabs: no tab at index ${next}`)
+    event.preventDefault()
+    setTab(nextTab.value)
+    refs.current[next]?.focus()
+  }
+
+  function panel(value: Tab, className: string | undefined, children: ReactNode) {
+    return (
+      <div
+        id={panelId(value)}
+        role="tabpanel"
+        aria-labelledby={tabId(value)}
+        hidden={tab !== value}
+        className={className}
+      >
+        {children}
+      </div>
+    )
+  }
+
+  return (
+    <div className={styles.page} hidden={hidden}>
+      <header className={styles.header}>
+        <div className={styles.heading}>
+          <h1 className={styles.title}>Settings</h1>
+          <p className={styles.shared}>Changes apply to everyone in the household.</p>
+        </div>
+        <div role="tablist" aria-label="Settings sections" className={styles.tabs} onKeyDown={onKeyDown}>
+          {tabs.map(({ value, label }, index) => (
+            <button
+              key={value}
+              ref={(el) => {
+                refs.current[index] = el
+              }}
+              id={tabId(value)}
+              type="button"
+              role="tab"
+              aria-selected={tab === value}
+              aria-controls={panelId(value)}
+              tabIndex={tab === value ? 0 : -1}
+              className={tab === value ? `${styles.tab} ${styles.selected}` : styles.tab}
+              onClick={() => setTab(value)}
+            >
+              {label}
+            </button>
+          ))}
+        </div>
+      </header>
+
+      {panel('household', styles.single, <HouseholdSettingsSections onDirtyChange={setHouseholdDirty} />)}
+
+      {panel(
+        'regulars',
+        styles.single,
+        // TODO(Feature 12): embed the Regular dinners screen here once Feature
+        // 12 builds it.
+        <Placeholder title="Regular dinners">Managing the household's Regulars arrives in a later update.</Placeholder>,
+      )}
+
+      {panel(
+        'notifications-ai',
+        styles.columns,
+        <>
+          <div className={styles.column}>
+            {/* TODO(Feature 19): the Notifications matrix and Google Chat
+                webhook cards replace this placeholder. */}
+            <Placeholder title="Notifications & Google Chat">
+              Notification and Google Chat webhook settings arrive in a later update.
+            </Placeholder>
+          </div>
+          <div className={styles.column}>
+            <AIAssistantCard onDirtyChange={setAIDirty} />
+            <RecipeSearchCard onDirtyChange={setRecipeSearchDirty} />
+          </div>
+        </>,
+      )}
+
+      <LeaveGuard dirty={householdDirty || aiDirty || recipeSearchDirty} />
+    </div>
+  )
+}
+
+// Placeholder is a neutral card holding a section's place until the feature
+// that owns it renders it.
+function Placeholder({ title, children }: { title: string; children: ReactNode }) {
+  const titleId = useId()
+  return (
+    <Card className={styles.placeholder} aria-labelledby={titleId} role="region">
+      <h2 id={titleId} className={styles.cardTitle}>
+        {title}
+      </h2>
+      <p className={styles.hint}>{children}</p>
+    </Card>
+  )
+}
@@ -0,0 +1,546 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { ApiError, useApi, type ApiClient } from '../api/index.ts'
+import { isRecord } from '../api/errors.ts'
+
+export const HOUSEHOLD_SETTINGS_PATH = '/api/v1/settings/household'
+export const AI_SETTINGS_PATH = '/api/v1/settings/ai'
+export const AI_MODELS_PATH = '/api/v1/settings/ai/models'
+export const AI_KEY_PATH = '/api/v1/settings/ai/api-key'
+export const AI_VERIFY_PATH = '/api/v1/settings/ai/verify'
+export const AI_RESET_PROMPT_PATH = '/api/v1/settings/ai/reset-prompt'
+export const RECIPE_SEARCH_PATH = '/api/v1/settings/recipe-search'
+export const RECIPE_SEARCH_TEST_PATH = '/api/v1/settings/recipe-search/test'
+// TODO(Feature 12): GET /api/v1/dinners?status=regular is Feature 12's
+// dinners read API. Until it lands the server answers 404 and the Regular
+// dinners row says the count is unavailable.
+export const REGULAR_DINNERS_PATH = '/api/v1/dinners?status=regular'
+// TODO(Feature 16): the Google Calendar integration status. Until Feature 16
+// serves it the server answers 404, which is the truth: not connected.
+export const CALENDAR_STATUS_PATH = '/api/v1/settings/calendar'
+// TODO(notifications feature): the Web Push and Google Chat status. Until it
+// is served the server answers 404, which is the truth: push is off and no
+// Google Chat space is connected.
+export const NOTIFICATIONS_STATUS_PATH = '/api/v1/settings/notifications'
+
+// HouseholdSettings is the part of GET /api/v1/settings/household the
+// settings pages read. Times are zero-padded 24-hour HH:MM in timezone; days
+// of the week count from Sunday = 0.
+export type HouseholdSettings = {
+  timezone: string
+  dinner_time: string
+  reminder_time: string
+  // The rotation check: when the household is asked "Keep it in rotation?".
+  review_time: string
+  plan_draft_dow: number
+  plan_draft_time: string
+  suggestions_dow: number
+  suggestions_time: string
+  chat_autosend_dow: number
+  chat_autosend_time: string
+}
+
+// HouseholdSettingsPatch is the PATCH /api/v1/settings/household body: only
+// the fields that change.
+export type HouseholdSettingsPatch = Partial<HouseholdSettings>
+
+export type HouseholdSettingsField = keyof HouseholdSettings
+
+const householdTimeFields = [
+  'dinner_time',
+  'reminder_time',
+  'review_time',
+  'plan_draft_time',
+  'suggestions_time',
+  'chat_autosend_time',
+] as const satisfies readonly HouseholdSettingsField[]
+
+const householdDayFields = [
+  'plan_draft_dow',
+  'suggestions_dow',
+  'chat_autosend_dow',
+] as const satisfies readonly HouseholdSettingsField[]
+
+const householdFields: readonly HouseholdSettingsField[] = ['timezone', ...householdTimeFields, ...householdDayFields]
+
+// aiProviderLabels names every AI provider preset the server accepts
+// (internal/ai/llm/presets) as the household reads it.
+export const aiProviderLabels = {
+  anthropic: 'Anthropic',
+  openai: 'OpenAI',
+  openrouter: 'OpenRouter',
+  xai: 'xAI',
+  ollama: 'Ollama',
+  openai_compatible: 'OpenAI-compatible',
+} as const
+
+export type AIProvider = keyof typeof aiProviderLabels
+
+// providersWithBaseURL are the presets with no fixed API root: the
+// household supplies its base URL.
+export const providersWithBaseURL: ReadonlySet<AIProvider> = new Set(['ollama', 'openai_compatible'])
+
+// aiKeyPolicy is whether each preset needs an API key, may take one, or
+// takes none (internal/ai/llm/presets).
+export const aiKeyPolicy: Record<AIProvider, 'required' | 'optional' | 'none'> = {
+  anthropic: 'required',
+  openai: 'required',
+  openrouter: 'required',
+  xai: 'required',
+  ollama: 'none',
+  openai_compatible: 'optional',
+}
+
+// AISettings is GET /api/v1/settings/ai. The API key itself is never sent:
+// only its last four characters, null when none is stored.
+export type AISettings = {
+  provider: AIProvider
+  base_url: string
+  model: string
+  temperature: number
+  // Null when none is stored.
+  system_prompt: string | null
+  api_key_last4: string | null
+  // When the stored key was last verified, null when it has not been.
+  key_verified_at: string | null
+  updated_at: string
+}
+
+// AISettingsPatch is the PATCH /api/v1/settings/ai body: only the fields
+// that change.
+export type AISettingsPatch = Partial<Pick<AISettings, 'provider' | 'base_url' | 'model' | 'temperature'>> & {
+  system_prompt?: string
+}
+
+// AIModel is one model GET /api/v1/settings/ai/models lists.
+export type AIModel = { id: string; display_name: string }
+
+function isAIProvider(value: string): value is AIProvider {
+  return Object.hasOwn(aiProviderLabels, value)
+}
+
+function isStringOrNull(value: unknown): value is string | null {
+  return value === null || typeof value === 'string'
+}
+
+// parseAISettings refuses a body that is not the AI settings, or names a
+// provider this client has no name for, so the settings never show a value
+// the household cannot read.
+function parseAISettings(where: string, body: unknown): AISettings {
+  if (
+    !isRecord(body) ||
+    typeof body.provider !== 'string' ||
+    typeof body.base_url !== 'string' ||
+    typeof body.model !== 'string' ||
+    typeof body.temperature !== 'number' ||
+    !isStringOrNull(body.system_prompt) ||
+    !isStringOrNull(body.api_key_last4) ||
+    !isStringOrNull(body.key_verified_at) ||
+    typeof body.updated_at !== 'string'
+  ) {
+    throw new Error(`${where}: response is not the AI settings`)
+  }
+  if (!isAIProvider(body.provider)) throw new Error(`${where}: unknown AI provider "${body.provider}"`)
+  return {
+    provider: body.provider,
+    base_url: body.base_url,
+    model: body.model,
+    temperature: body.temperature,
+    system_prompt: body.system_prompt,
+    api_key_last4: body.api_key_last4,
+    key_verified_at: body.key_verified_at,
+    updated_at: body.updated_at,
+  }
+}
+
+const AI_SETTINGS_KEY = ['settings', 'ai'] as const
+const AI_MODELS_KEY = ['settings', 'ai', 'models'] as const
+
+export function useAISettings() {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: AI_SETTINGS_KEY,
+    queryFn: async () => parseAISettings(`GET ${AI_SETTINGS_PATH}`, await apiFetch<unknown>(AI_SETTINGS_PATH)),
+  })
+}
+
+// useAIModels is the saved provider's live model list. Without a usable
+// provider (no key yet, say) it fails with the server's 409 not_configured.
+export function useAIModels(enabled: boolean) {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: AI_MODELS_KEY,
+    enabled,
+    queryFn: async () => {
+      const body = await apiFetch<unknown>(AI_MODELS_PATH)
+      const models = isRecord(body) ? body.models : undefined
+      if (
+        !Array.isArray(models) ||
+        !models.every((m) => isRecord(m) && typeof m.id === 'string' && typeof m.display_name === 'string')
+      ) {
+        throw new Error(`GET ${AI_MODELS_PATH}: response is not a model list`)
+      }
+      return models as AIModel[]
+    },
+  })
+}
+
+// useAISettingsMutation sends one AI settings change and stores the
+// settings the server answers with. A change that can alter which models
+// the provider offers refetches the model list.
+function useAISettingsMutation<V>(path: string, method: 'POST' | 'PUT' | 'PATCH', body: (variables: V) => unknown) {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: async (variables: V) =>
+      parseAISettings(`${method} ${path}`, await apiFetch<unknown>(path, { method, body: body(variables) })),
+    onSuccess: (settings) => {
+      const before = queryClient.getQueryData<AISettings>(AI_SETTINGS_KEY)
+      queryClient.setQueryData(AI_SETTINGS_KEY, settings)
+      if (
+        before === undefined ||
+        before.provider !== settings.provider ||
+        before.base_url !== settings.base_url ||
+        before.api_key_last4 !== settings.api_key_last4 ||
+        before.key_verified_at !== settings.key_verified_at
+      ) {
+        void queryClient.invalidateQueries({ queryKey: AI_MODELS_KEY })
+      }
+    },
+  })
+}
+
+export function useSaveAISettings() {
+  return useAISettingsMutation(AI_SETTINGS_PATH, 'PATCH', (patch: AISettingsPatch) => patch)
+}
+
+// useSetAIKey stores a new API key; an empty key removes the stored one.
+export function useSetAIKey() {
+  return useAISettingsMutation(AI_KEY_PATH, 'PUT', (apiKey: string) => ({ api_key: apiKey }))
+}
+
+export function useVerifyAIKey() {
+  return useAISettingsMutation(AI_VERIFY_PATH, 'POST', () => undefined)
+}
+
+export function useResetAIPrompt() {
+  return useAISettingsMutation(AI_RESET_PROMPT_PATH, 'POST', () => undefined)
+}
+
+// recipeSearchProviderLabels names every recipe search provider the server
+// accepts (internal/recipes/searchsettings.go).
+export const recipeSearchProviderLabels = {
+  searxng: 'SearXNG',
+  brave: 'Brave',
+} as const
+
+export type RecipeSearchProvider = keyof typeof recipeSearchProviderLabels
+
+// RecipeSearchSettings is GET /api/v1/settings/recipe-search. The Brave API
+// key itself is never sent: only whether one is stored and its last four
+// characters.
+export type RecipeSearchSettings = {
+  // Null until recipe search is first set up.
+  provider: RecipeSearchProvider | null
+  // The saved SearXNG instance's URL, null when none is set.
+  base_url: string | null
+  // The deployment's SearXNG URL (MEALQUEST_SEARXNG_URL) to suggest while
+  // base_url is null; null when the deployment names none. Only saving
+  // base_url stores a URL.
+  default_base_url: string | null
+  api_key_set: boolean
+  api_key_last4: string | null
+  updated_at: string | null
+}
+
+// RecipeSearchSettingsPatch is the PATCH /api/v1/settings/recipe-search
+// body: only the fields that change. api_key is the Brave key in plain text.
+export type RecipeSearchSettingsPatch = {
+  provider?: RecipeSearchProvider
+  base_url?: string
+  api_key?: string
+}
+
+// RecipeSearchTest is POST /api/v1/settings/recipe-search/test: how many
+// recipes the saved provider found for query.
+export type RecipeSearchTest = { query: string; count: number }
+
+function isRecipeSearchProvider(value: string): value is RecipeSearchProvider {
+  return Object.hasOwn(recipeSearchProviderLabels, value)
+}
+
+function parseRecipeSearchSettings(where: string, body: unknown): RecipeSearchSettings {
+  if (
+    !isRecord(body) ||
+    !isStringOrNull(body.provider) ||
+    !isStringOrNull(body.base_url) ||
+    !isStringOrNull(body.default_base_url) ||
+    typeof body.api_key_set !== 'boolean' ||
+    !isStringOrNull(body.api_key_last4) ||
+    !isStringOrNull(body.updated_at)
+  ) {
+    throw new Error(`${where}: response is not the recipe search settings`)
+  }
+  if (body.provider !== null && !isRecipeSearchProvider(body.provider)) {
+    throw new Error(`${where}: unknown recipe search provider "${body.provider}"`)
+  }
+  return {
+    provider: body.provider,
+    base_url: body.base_url,
+    default_base_url: body.default_base_url,
+    api_key_set: body.api_key_set,
+    api_key_last4: body.api_key_last4,
+    updated_at: body.updated_at,
+  }
+}
+
+const RECIPE_SEARCH_KEY = ['settings', 'recipe-search'] as const
+
+export function useRecipeSearchSettings() {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: RECIPE_SEARCH_KEY,
+    queryFn: async () =>
+      parseRecipeSearchSettings(`GET ${RECIPE_SEARCH_PATH}`, await apiFetch<unknown>(RECIPE_SEARCH_PATH)),
+  })
+}
+
+export function useSaveRecipeSearchSettings() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: async (patch: RecipeSearchSettingsPatch) =>
+      parseRecipeSearchSettings(
+        `PATCH ${RECIPE_SEARCH_PATH}`,
+        await apiFetch<unknown>(RECIPE_SEARCH_PATH, { method: 'PATCH', body: patch }),
+      ),
+    onSuccess: (settings) => queryClient.setQueryData(RECIPE_SEARCH_KEY, settings),
+  })
+}
+
+// useTestRecipeSearch searches with the saved settings.
+export function useTestRecipeSearch() {
+  const { apiFetch } = useApi()
+  return useMutation({
+    mutationFn: async () => {
+      const body = await apiFetch<unknown>(RECIPE_SEARCH_TEST_PATH, { method: 'POST' })
+      if (!isRecord(body) || typeof body.query !== 'string' || typeof body.count !== 'number') {
+        throw new Error(`POST ${RECIPE_SEARCH_TEST_PATH}: response is not a search test result`)
+      }
+      return { query: body.query, count: body.count } satisfies RecipeSearchTest
+    },
+  })
+}
+
+const clockTime = /^([01][0-9]|2[0-3]):([0-5][0-9])$/
+
+// parseHouseholdSettings refuses a body that is not the household settings,
+// or has a time that is not HH:MM, so formatClockTime never sees one.
+function parseHouseholdSettings(where: string, body: unknown): HouseholdSettings {
+  if (!isRecord(body) || typeof body.timezone !== 'string') {
+    throw new Error(`${where}: response is not the household settings`)
+  }
+  const times = {} as Record<(typeof householdTimeFields)[number], string>
+  for (const field of householdTimeFields) {
+    const value = body[field]
+    if (typeof value !== 'string' || !clockTime.test(value)) {
+      throw new Error(`${where}: ${field} ${JSON.stringify(value)} is not HH:MM`)
+    }
+    times[field] = value
+  }
+  const days = {} as Record<(typeof householdDayFields)[number], number>
+  for (const field of householdDayFields) {
+    const value = body[field]
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 6) {
+      throw new Error(`${where}: ${field} ${JSON.stringify(value)} is not a day of the week (0-6)`)
+    }
+    days[field] = value
+  }
+  return { timezone: body.timezone, ...times, ...days }
+}
+
+const HOUSEHOLD_SETTINGS_KEY = ['settings', 'household'] as const
+
+export function useHouseholdSettings() {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: HOUSEHOLD_SETTINGS_KEY,
+    queryFn: async () =>
+      parseHouseholdSettings(`GET ${HOUSEHOLD_SETTINGS_PATH}`, await apiFetch<unknown>(HOUSEHOLD_SETTINGS_PATH)),
+  })
+}
+
+export function useSaveHouseholdSettings() {
+  const { apiFetch } = useApi()
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: async (patch: HouseholdSettingsPatch) =>
+      parseHouseholdSettings(
+        `PATCH ${HOUSEHOLD_SETTINGS_PATH}`,
+        await apiFetch<unknown>(HOUSEHOLD_SETTINGS_PATH, { method: 'PATCH', body: patch }),
+      ),
+    onSuccess: (settings) => queryClient.setQueryData(HOUSEHOLD_SETTINGS_KEY, settings),
+  })
+}
+
+// HouseholdSettingsProblems is a refused household settings save: the reason
+// for each field the server named, and any reasons that name no field.
+export type HouseholdSettingsProblems = {
+  fields: Partial<Record<HouseholdSettingsField, string>>
+  other: string[]
+}
+
+const invalidHouseholdPrefix = 'invalid household settings: '
+
+// A problem starts with a field name and ": " (internal/household
+// ValidationError.Error joins them with "; ").
+const problemStart = /; (?=[a-z_]+: )/
+
+// householdSettingsProblems reads the server's invalid_settings error into
+// the problems it lists. Any other error is one problem naming no field.
+export function householdSettingsProblems(error: Error): HouseholdSettingsProblems {
+  const problems: HouseholdSettingsProblems = { fields: {}, other: [] }
+  if (
+    !(error instanceof ApiError) ||
+    error.code !== 'invalid_settings' ||
+    !error.message.startsWith(invalidHouseholdPrefix)
+  ) {
+    problems.other.push(error.message)
+    return problems
+  }
+  for (const problem of error.message.slice(invalidHouseholdPrefix.length).split(problemStart)) {
+    const colon = problem.indexOf(': ')
+    const field = problem.slice(0, colon)
+    if (colon !== -1 && (householdFields as readonly string[]).includes(field)) {
+      problems.fields[field as HouseholdSettingsField] = problem.slice(colon + 2)
+    } else {
+      problems.other.push(problem)
+    }
+  }
+  return problems
+}
+
+// aiStatus is the AI assistant row's status line: the provider and the
+// model's display name, or that no model is chosen yet (the seed).
+export function aiStatus(settings: Pick<AISettings, 'provider' | 'model'>): string {
+  const provider = aiProviderLabels[settings.provider]
+  if (settings.model === '') return `${provider} · No model chosen`
+  return `${provider} · ${modelDisplayName(settings.model)}`
+}
+
+// Claude model ids, current ("claude-sonnet-4-5") and older
+// ("claude-3-5-sonnet-20241022"), name their family.
+const claudeModel = /^claude-(?:[0-9-]+-)?(opus|sonnet|haiku|fable)(?:-|$)/
+const claudeFamilies: Record<string, string> = { opus: 'Opus', sonnet: 'Sonnet', haiku: 'Haiku', fable: 'Fable' }
+
+// modelDisplayName names a model as the handoff does ("Claude Sonnet"); a
+// model with no known family is shown by its id.
+export function modelDisplayName(model: string): string {
+  const family = claudeModel.exec(model)?.[1]
+  return family === undefined ? model : `Claude ${claudeFamilies[family]}`
+}
+
+// fetchUnlessAbsent GETs path and parses it, or returns null when the server
+// has no such endpoint yet (404 not_found). Every other failure is an error.
+async function fetchUnlessAbsent<T>(
+  apiFetch: ApiClient['apiFetch'],
+  path: string,
+  parse: (body: unknown) => T,
+): Promise<T | null> {
+  let body: unknown
+  try {
+    body = await apiFetch<unknown>(path)
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404 && error.code === 'not_found') return null
+    throw error
+  }
+  return parse(body)
+}
+
+// useRegularDinnersCount is how many Regulars the household has, or null
+// while the dinners read API does not exist.
+export function useRegularDinnersCount() {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: ['dinners', 'regular', 'count'],
+    queryFn: () =>
+      fetchUnlessAbsent(apiFetch, REGULAR_DINNERS_PATH, (body) => {
+        if (!isRecord(body) || !Array.isArray(body.dinners)) {
+          throw new Error(`GET ${REGULAR_DINNERS_PATH}: response has no dinners list`)
+        }
+        return body.dinners.length
+      }),
+  })
+}
+
+export function regularDinnersStatus(count: number | null): string {
+  if (count === null) return 'Rotation count unavailable'
+  if (count === 0) return 'None on rotation yet'
+  return `${count} on rotation`
+}
+
+// CalendarStatus is the Google Calendar integration status; calendar_name
+// is the connected calendar's name.
+export type CalendarStatus = { connected: false } | { connected: true; calendar_name: string }
+
+export function useCalendarStatus() {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: ['settings', 'calendar'],
+    queryFn: () =>
+      fetchUnlessAbsent(apiFetch, CALENDAR_STATUS_PATH, (body): CalendarStatus => {
+        if (isRecord(body) && body.connected === false) return { connected: false }
+        if (isRecord(body) && body.connected === true && typeof body.calendar_name === 'string') {
+          return { connected: true, calendar_name: body.calendar_name }
+        }
+        throw new Error(`GET ${CALENDAR_STATUS_PATH}: response is not a calendar status`)
+      }),
+  })
+}
+
+export function calendarStatus(status: CalendarStatus | null): string {
+  if (status === null || !status.connected) return 'Not connected'
+  return `Connected · ${status.calendar_name}`
+}
+
+// NotificationsStatus is whether Web Push is on and the connected Google
+// Chat space's name, null when none is.
+export type NotificationsStatus = { push: boolean; chat_space: string | null }
+
+export function useNotificationsStatus() {
+  const { apiFetch } = useApi()
+  return useQuery({
+    queryKey: ['settings', 'notifications'],
+    queryFn: () =>
+      fetchUnlessAbsent(apiFetch, NOTIFICATIONS_STATUS_PATH, (body): NotificationsStatus => {
+        if (
+          !isRecord(body) ||
+          typeof body.push !== 'boolean' ||
+          (body.chat_space !== null && typeof body.chat_space !== 'string')
+        ) {
+          throw new Error(`GET ${NOTIFICATIONS_STATUS_PATH}: response is not a notifications status`)
+        }
+        return { push: body.push, chat_space: body.chat_space }
+      }),
+  })
+}
+
+// notificationsStatus is the handoff's "Push on · Dinner Crew space".
+export function notificationsStatus(status: NotificationsStatus | null): string {
+  const push = status?.push === true ? 'Push on' : 'Push off'
+  return `${push} · ${status?.chat_space ?? 'Google Chat not connected'}`
+}
+
+// maskedKey shows a stored key as dots and its last four characters, all
+// the client ever knows of it.
+export function maskedKey(last4: string): string {
+  return `••••••••${last4}`
+}
+
+// formatClockTime turns a 24-hour HH:MM time into the handoff's "5:30 pm".
+export function formatClockTime(time: string): string {
+  const match = clockTime.exec(time)
+  if (match === null) throw new Error(`not a 24-hour HH:MM time: "${time}"`)
+  const hours = Number(match[1])
+  const suffix = hours < 12 ? 'am' : 'pm'
+  return `${hours % 12 === 0 ? 12 : hours % 12}:${match[2]} ${suffix}`
+}
@@ -0,0 +1,46 @@
+// The IANA time zones the browser knows, with their current UTC offsets, for
+// the household time zone picker.
+
+export type TimeZoneOption = {
+  zone: string
+  // "UTC-04:00"; "UTC+00:00" for UTC itself.
+  offset: string
+}
+
+// utcOffset is zone's offset from UTC at instant, as "UTC+05:30".
+export function utcOffset(zone: string, instant: Date): string {
+  const name = new Intl.DateTimeFormat('en-US', { timeZone: zone, timeZoneName: 'longOffset' })
+    .formatToParts(instant)
+    .find((part) => part.type === 'timeZoneName')?.value
+  if (name === undefined) throw new Error(`no UTC offset for time zone "${zone}"`)
+  if (name === 'GMT') return 'UTC+00:00'
+  if (!/^GMT[+-]\d\d:\d\d$/.test(name)) throw new Error(`time zone "${zone}" has an unreadable offset "${name}"`)
+  return `UTC${name.slice(3)}`
+}
+
+// Zones the server accepts that Intl.supportedValuesOf('timeZone') leaves
+// out: it lists only canonical zones, and UTC is not one of them.
+const unlistedZones = ['UTC', 'Etc/UTC', 'GMT', 'Etc/GMT']
+
+// timeZoneOptions lists every zone the browser supports, the unlisted UTC
+// zones, and kept (the saved and chosen zones, which may be aliases the
+// list leaves out), sorted by name.
+export function timeZoneOptions(kept: string[], instant: Date): TimeZoneOption[] {
+  const zones = new Set([...Intl.supportedValuesOf('timeZone'), ...unlistedZones, ...kept])
+  return [...zones].sort().map((zone) => ({ zone, offset: utcOffset(zone, instant) }))
+}
+
+// zoneLabel reads a zone as words: "America/Argentina/Buenos_Aires" is
+// "America / Argentina / Buenos Aires".
+export function zoneLabel(zone: string): string {
+  return zone.replaceAll('_', ' ').replaceAll('/', ' / ')
+}
+
+// matchesZone is whether every word of the search text is in option's name
+// or offset, in any case.
+export function matchesZone(option: TimeZoneOption, search: string): boolean {
+  const needle = search.trim().toLowerCase()
+  if (needle === '') return true
+  const haystack = `${option.zone} ${zoneLabel(option.zone)} ${option.offset}`.toLowerCase()
+  return needle.split(/\s+/).every((word) => haystack.includes(word))
+}