chore: release v1.20.0 (#434)

Fixes multiple security vulnerabilities: CVE-2026-1525, CVE-2026-1528, CVE-2026-2581, CVE-2026-1527, CVE-2026-2229, CVE-2026-1526

.env.example

@@ -12,6 +12,7 @@ PGID=1000
 PORT=3000
 CORS_ORIGINS=http://localhost:4174
 LOG_LEVEL=warn
+
 # Levels: debug, info, warn, error, silent
 # Controls: backend Fastify logging, frontend nginx access logs (Docker),
 #           and frontend browser console (via build-time injection)
@@ -28,6 +29,14 @@ LOG_LEVEL=warn
 # Increase for development/testing environments
 # RATE_LIMIT_MAX=100
 
+# API documentation UI + OpenAPI JSON
+# Default behavior: enabled outside production, disabled in production
+# When enabled, docs are available on /docs and /docs/json.
+# Recommended:
+#   development/staging: OPENAPI_DOCS_ENABLED=true
+#   production: leave unset, or set OPENAPI_DOCS_ENABLED=false
+# OPENAPI_DOCS_ENABLED=true
+
 # Timezone for scheduled reminders (e.g., Europe/Berlin, America/New_York)
 TZ=Europe/Berlin
 
@@ -113,12 +122,14 @@ EXPIRY_WARNING_DAYS=30            # Days before expiry to show yellow warning
 # DEFAULT_NOTIFICATION_EMAIL=
 # DEFAULT_EMAIL_STOCK_REMINDERS=true
 # DEFAULT_EMAIL_INTAKE_REMINDERS=true
+# DEFAULT_EMAIL_PRESCRIPTION_REMINDERS=true
 
 # Push notifications (ntfy/gotify via Shoutrrr)
 # DEFAULT_SHOUTRRR_ENABLED=false
 # DEFAULT_SHOUTRRR_URL=
 # DEFAULT_SHOUTRRR_STOCK_REMINDERS=true
 # DEFAULT_SHOUTRRR_INTAKE_REMINDERS=true
+# DEFAULT_SHOUTRRR_PRESCRIPTION_REMINDERS=true
 
 # Repeat/nagging reminders for missed doses
 # DEFAULT_REPEAT_REMINDERS_ENABLED=false
@@ -137,4 +148,6 @@ EXPIRY_WARNING_DAYS=30            # Days before expiry to show yellow warning
 # UI defaults
 # DEFAULT_LANGUAGE=en              # en or de
 # DEFAULT_STOCK_CALCULATION_MODE=automatic  # automatic or manual
-# DEFAULT_SHARE_STOCK_STATUS=true  # Show stock status on shared schedule links
+# DEFAULT_SHARE_STOCK_STATUS=true  # Show stock status on shared schedule links
+# DEFAULT_UPCOMING_TODAY_ONLY=false
+# DEFAULT_SHARE_SCHEDULE_TODAY_ONLY=false

.github/CODEOWNERS

@@ -0,0 +1,11 @@
+# MedAssist ownership
+# This routes review requests automatically to the maintainer.
+
+* @DanielVolz
+
+# Explicit domains for clarity
+/backend/ @DanielVolz
+/frontend/ @DanielVolz
+/.github/ @DanielVolz
+/doku/ @DanielVolz
+/docs/ @DanielVolz

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,6 +1,9 @@
-name: 🐛 Bug Report
+name: Bug Report
 description: Report a bug or unexpected behavior
+title: "[Bug]: "
 labels: ["bug", "triage"]
+assignees:
+  - DanielVolz
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1 @@
 blank_issues_enabled: true
-contact_links:
-  - name: 💬 Discussions
-    url: https://github.com/DanielVolz/medassist-ng/discussions
-    about: Ask questions or share ideas in Discussions
-  - name: 📖 Documentation
-    url: https://github.com/DanielVolz/medassist-ng#readme
-    about: Check the README for setup and usage instructions

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,5 +1,6 @@
-name: ✨ Feature Request
+name: Feature Request
 description: Suggest a new feature or improvement
+title: "[Feature]: "
 labels: ["enhancement", "triage"]
 body:
   - type: markdown

.github/agents/release-manager.agent.md

@@ -15,11 +15,14 @@ You are the release manager for **MedAssist-ng**. Your job is to guide code from
 - **Do EXACTLY what the user asks — nothing more.** If the user says "create a PR and merge to main", do only that. Do NOT also start a release. If the user says "do a release", do only the release. Never chain additional steps the user did not request.
 - **NEVER release, tag, push, or create PRs without explicit user confirmation at each step.** Always present your plan and wait for approval.
 - **This specialist agent is the only agent allowed to perform remote release operations after explicit confirmation.**
+- **Use GitHub MCP for all GitHub remote operations. Never use `gh` CLI.** Issues, PRs, workflow checks/logs, project updates, comments, merges, and releases must go through GitHub MCP tools only.
 - **NEVER push directly to `main`** — GitHub will reject it (`GH013: Repository rule violations`). All changes go through Pull Requests.
 - **NEVER skip CI checks.** Wait for all status checks to pass before merging.
 - **Testing ownership belongs to `@testing-manager`**. Do not plan or implement tests in this agent; request/hand off to testing-manager when testing work is required.
 - **Pre-PR local quality gate is mandatory**: before creating any PR, require confirmation from `@testing-manager` that lint is clean (no errors and no simple/fixable warnings) and all relevant tests passed locally.
 - **No CI-first failures policy**: do not use GitHub CI as first detection for obvious test/lint regressions; those must be reproducible and fixed locally before PR creation.
+- **Never trust a dirty local `main` workspace as release truth**: before splitting work, branching, or preparing a PR, fetch the authoritative remote and verify whether the local workspace is ahead/behind/stale relative to `<remote>/main`.
+- **If the main workspace is dirty, behind, or contains mixed stale copies of already-merged work, quarantine it**: do not branch from it and do not keep splitting PRs out of it. Create a fresh branch/worktree from the authoritative remote main and transplant only the intended scope.
 - **Track all work in the GitHub Project board.** Every PR should reference an issue. Move issues through the board as work progresses.
 - **ALWAYS verify Project board status after merge.** The `project-auto-done.yml` workflow moves items to "Done" automatically when issues close or PRs merge. Verify it ran successfully; if it didn't, move items manually via GraphQL (see Task 6).
 
@@ -48,15 +51,24 @@ This repository intentionally uses only two operational agents for CI/CD handoff
 - During active PR/release work, `@release-manager` must keep all relevant current workflows in view until completion.
 - If a failing workflow is testing-related (`test.yml` or `e2e.yml`), immediately hand off diagnosis/fix to `@testing-manager`.
 
-## GitHub CLI Safety (Non-Interactive Only)
+## GitHub Operations (GitHub MCP Only)
 
-- Never use `gh` commands that can open an interactive pager and block execution (requiring `q`).
-- Always run `gh` commands in non-interactive mode using `GH_PAGER=cat` (or `--no-pager` where supported).
-- Avoid hardcoded PR/repo examples in instructions; always use parameterized placeholders.
-- Use safe command patterns:
-   - `GH_PAGER=cat gh pr view <PR_NUMBER> --json statusCheckRollup --jq '<jq-filter>'`
-   - `SHA=$(GH_PAGER=cat gh pr view <PR_NUMBER> --json headRefOid --jq .headRefOid)`
-   - `GH_PAGER=cat gh api repos/<owner>/<repo>/commits/$SHA/check-runs --jq '<jq-filter>'`
+- Never use `gh` CLI in this agent.
+- Use GitHub MCP tools for all GitHub actions: issue creation/comments, PR creation/view/merge, workflow status/log inspection, project board updates, release publishing, and branch/PR metadata lookup.
+- Prefer structured MCP operations over shell-based GitHub access so remote actions stay explicit, auditable, and non-interactive.
+
+## Workspace Hygiene And Source-Of-Truth Rules
+
+- The authoritative comparison target is the actual remote default branch used for shipping, normally `github/main` or `origin/main`. Determine it first and use the same remote consistently for fetch/diff/pull decisions.
+- Before any PR split or branch creation, run a source-of-truth audit:
+   1. fetch the authoritative remote
+   2. inspect `git status`
+   3. compare local `main` against `<remote>/main`
+   4. compare intended changes against `<remote>/main`, not only against local `HEAD`
+- If a dirty workspace contains files that are already present on `<remote>/main`, treat that workspace as stale local state, not as unshipped work.
+- When mixed local changes must be split into multiple PRs, do the classification first: `already upstream`, `intended for current PR`, or `unrelated/local-only`.
+- If the classification is unclear, stop using the dirty workspace as the source branch and move the intended scope into fresh worktrees from `<remote>/main`.
+- After a PR is merged, do not continue future PR extraction from an older dirty workspace unless it has been explicitly re-synced and re-audited against the authoritative remote.
 
 ---
 
@@ -121,10 +133,13 @@ When code changes (features or bug fixes) are complete:
 
 ### Step 1: Verify Readiness
 
-1. Check for uncommitted changes: `git status`
-2. Confirm testing has been completed by `@testing-manager`.
-3. Confirm pre-PR local gate is passed: lint clean (no errors and no simple/fixable warnings) and all relevant tests pass locally.
-4. Only after local gate is confirmed, proceed to push/create PR and then monitor CI.
+1. Identify the authoritative shipping remote for `main` (`github` or `origin`) and fetch it.
+2. Check for uncommitted changes: `git status`.
+3. Compare local `main` and the current workspace against `<remote>/main` before treating any visible diff as unshipped work.
+4. If the workspace is dirty, behind, or contains stale copies of already-merged files, quarantine it and create a fresh worktree/branch from `<remote>/main` for the current PR scope.
+5. Confirm testing has been completed by `@testing-manager`.
+6. Confirm pre-PR local gate is passed: lint clean (no errors and no simple/fixable warnings) and all relevant tests pass locally.
+7. Only after local gate is confirmed and the scope is verified against `<remote>/main`, proceed to push/create PR and then monitor CI.
 
 ### Step 2: Create Feature Branch
 
@@ -132,11 +147,13 @@ When code changes (features or bug fixes) are complete:
    - Bug fix: `fix/short-description` (e.g., `fix/stock-correction-consumption`)
    - Feature: `feat/short-description` (e.g., `feat/refill-tracking`)
    - Chore: `chore/short-description`
-2. Create and switch to the branch:
+2. Create the branch from a clean base that matches `<remote>/main`. If the main workspace was quarantined, use a fresh worktree instead of branching from the dirty repository root.
+3. Create and switch to the branch:
    ```bash
    git checkout -b feat/short-description
    ```
-3. Stage and commit changes with a conventional commit message:
+4. Move only the intended scope into that branch/worktree. Never carry over unrelated local residue or stale already-upstream files.
+5. Stage and commit changes with a conventional commit message:
    ```bash
    git add .
    git commit -m "fix: short description of what was fixed"
@@ -150,35 +167,24 @@ When code changes (features or bug fixes) are complete:
    ```bash
    git push -u origin feat/short-description
    ```
-3. Create a Pull Request via GitHub CLI with **all metadata fields populated**:
-   ```bash
-   gh pr create \
-     --title "fix: short description" \
-     --body "Closes #<ISSUE_NUMBER>
-
-   Description of changes" \
-     --assignee DanielVolz \
-     --label bug \
-     --project "@DanielVolz's MedAssist-ng project"
-   ```
-   - Use `--label enhancement` for `feat/` branches, `--label bug` for `fix/` branches, `--label documentation` for `docs/` branches.
+3. Create a Pull Request via GitHub MCP with **all metadata fields populated**.
+    - Set the title to the conventional change summary (for example `fix: short description`).
+    - Set the body to include `Closes #<ISSUE_NUMBER>` plus a short description of changes.
+    - Set assignee to `DanielVolz`.
+    - Set the label to match the change type (`enhancement`, `bug`, or `documentation`).
+    - Link the PR to `@DanielVolz's MedAssist-ng project`.
    - Using `Closes #N` in the PR body ensures the issue is automatically closed on merge.
-   - The `--project` flag links the PR to the Project board.
+   - Always add an explicit issue comment with the PR link and short fix summary (do not rely on auto-close event only).
 4. **Present the PR URL to the user and wait for confirmation.**
 
 ### Step 4: Wait for CI and Merge
 
-1. Monitor CI status:
-   ```bash
-   gh pr checks <PR_NUMBER> --watch
-   ```
+1. Monitor CI status via GitHub MCP until all required checks complete.
    Required checks: all repository-required checks must pass.
 2. If CI fails: analyze the failure, fix it, push again, and re-check.
-3. Once CI is green, **ask the user for merge confirmation**, then:
-   ```bash
-   gh pr merge <PR_NUMBER> --squash --delete-branch
-   ```
-4. Switch back to main and pull:
+3. Once CI is green, **ask the user for merge confirmation**, then merge the PR via GitHub MCP using squash merge and branch deletion.
+4. Re-sync the authoritative local `main` before using it again as a source of truth for any next PR or release step. Do not continue from a previously dirty workspace without another source-of-truth audit.
+5. Switch back to main and pull:
    ```bash
    git checkout main
    git pull origin main
@@ -247,6 +253,8 @@ The script performs these steps in order:
 6. Merges the PR (squash + delete branch)
 7. Creates a signed tag `vX.Y.Z` and pushes it
 
+**Release precondition:** never start the release flow from a dirty or stale mixed workspace. If the repository root contains unrelated/stale diffs, first switch to a clean base that matches the authoritative remote main.
+
 **The script auto-detects the git remote** (`origin` or `github`) and uses it consistently.
 
 **CI wait behavior:** GitHub Actions can take 10-30 seconds before checks appear on a new PR. The script waits 20 seconds initially, then polls every 15 seconds until checks are registered, then watches them to completion. Maximum wait is 10 minutes.
@@ -391,10 +399,7 @@ Existing installations need to:
 
 ### Step 3: Publish
 
-Present the release notes to the user. They will copy them to the GitHub release page or ask you to publish via:
-```bash
-gh release create vX.Y.Z --title "vX.Y.Z" --notes "RELEASE_NOTES_HERE"
-```
+Present the release notes to the user. They will copy them to the GitHub release page or ask you to publish the release via GitHub MCP.
 
 ---
 
@@ -444,30 +449,15 @@ All work is tracked in the [GitHub Project board](https://github.com/users/Danie
 
 ### Workflow During PRs
 
-1. **Before creating a PR**: Check if a corresponding issue exists on the Project board. If not, create one:
-   ```bash
-   gh issue create --title "fix: description" --label bug
-   ```
+1. **Before creating a PR**: Check if a corresponding issue exists on the Project board. If not, create one via GitHub MCP with the appropriate label.
    Issues with `enhancement`, `bug`, or `triage` labels are **automatically added** to the board.
 
 2. **When creating a PR**: Always reference the issue with `Closes #N` in the PR body so the issue is automatically **closed** on merge. Note: this does NOT move the Project board status — that must be done manually (see step 3).
+   Also add a direct issue comment with the PR link and a one-line summary for clear issue-thread traceability.
 
-3. **After merge — verify automation**: The `project-auto-done.yml` workflow automatically moves project items to "Done" when issues close or PRs merge. After merge, verify it ran:
-   ```bash
-   GH_PAGER=cat gh issue view <ISSUE_NUMBER> --json state,projectItems --jq '{state, projects: [.projectItems[] | {title: .title, status: .status.name}]}'
-   ```
+3. **After merge — verify automation**: The `project-auto-done.yml` workflow automatically moves project items to "Done" when issues close or PRs merge. After merge, verify issue/project status via GitHub MCP.
 
-   **Manual fallback** — if the workflow fails or the item wasn't moved, use GraphQL:
-   ```bash
-   GH_PAGER=cat gh api graphql -f query='mutation {
-     updateProjectV2ItemFieldValue(input: {
-       projectId: "PVT_kwHOADH82s4BO2OT"
-       itemId: "<ITEM_ID>"
-       fieldId: "PVTSSF_lAHOADH82s4BO2OTzg9bdkE"
-       value: { singleSelectOptionId: "ca45af98" }
-     }) { projectV2Item { id } }
-   }'
-   ```
+    **Manual fallback** — if the workflow fails or the item wasn't moved, use GitHub MCP GraphQL/project mutation support with the project/item/field IDs below.
 
    **Known Project field IDs (Status):**
    | Status | Option ID |

.github/agents/testing-manager.agent.md

@@ -21,6 +21,7 @@ You are the testing manager for **MedAssist-ng**. Your job is to ensure every fe
 - **Playwright must disable auto-open reports**: Always prefix Playwright runs with `PLAYWRIGHT_HTML_OPEN=never`.
 - **Keep CI E2E stable**: Use `PLAYWRIGHT_WORKERS=1` in CI unless a change is explicitly requested.
 - **Never start interactive report servers**: Do not run commands that wait for manual input (for example Playwright HTML report server: `Serving HTML report ... Press Ctrl+C to quit`). Always use finite, non-interactive commands and reporters.
+- **Use GitHub MCP for all GitHub workflow/PR inspection. Never use `gh` CLI.** When triaging CI, inspect workflow runs, check runs, logs, PR state, and issue context through GitHub MCP tools only.
 - **No remote git operations**: Do not push, merge, create PRs, tags, or releases. Hand over to `@release-manager` when ready.
 - **Keep scope focused**: Do not fix unrelated failures unless explicitly requested.
 - **Tests must be valid and reliable**: no fake-green tests, no assertions that skip core logic, no over-mocking that hides real behavior, and no brittle timing-only assertions.
@@ -37,6 +38,7 @@ You are the testing manager for **MedAssist-ng**. Your job is to ensure every fe
 - **Backend unit/integration**: Vitest 4 + v8 coverage (`backend/src/test/*.test.ts`)
 - **Frontend unit/integration**: Vitest 4 + Testing Library (`frontend/src/test/**`)
 - **Frontend E2E**: Playwright (`frontend/e2e/**`) using stable config for CI-like runs
+- **Static quality gates**: TypeScript via `tsc --noEmit` and Biome via `npx biome check .`
 
 Primary locations:
 
@@ -44,14 +46,24 @@ Primary locations:
 - Frontend tests: `frontend/src/test/**`
 - Playwright E2E: `frontend/e2e/**`
 
+## Testing Strategy Defaults
+
+- **Default to targeted validation, not shotgun runs**: start with the smallest test command that exercises the changed behavior.
+- **Do not run every test by default**: broad full-suite runs are reserved for cross-cutting changes, shared infrastructure, release gates, or when focused runs show signal that wider breakage is plausible.
+- **Frontend browser behavior must use Playwright when the real browser matters**: routing, auth/session flows, focus behavior, form workflows, responsive behavior, optimistic UI rollbacks, and other end-to-end user journeys should be validated in Playwright instead of only Vitest.
+- **Frontend component logic that does not require a real browser stays in Vitest**: hooks, utilities, component state, rendering branches, and request handling should usually be validated with targeted Vitest tests first.
+- **Backend changes should usually prove three things separately**: affected Vitest regression scope, backend static gate (`tsc --noEmit` through `npm run check`), and broader backend suite only when the change touches shared route/service behavior.
+- **Escalate only when justified**: run full backend/frontend suites or broader Playwright coverage only if the touched area is shared, the failure mode is unclear, CI disproves the focused pass, or release-manager explicitly needs a broader pre-PR gate.
+
 ## Required Test Workflow
 
 1. Identify changed behavior and expected outcomes.
-2. Add/update tests near the affected feature.
-3. Run the smallest relevant subset first.
-4. Expand to broader suites if subset passes.
-5. Run lint + required local test/build gates before PR handoff.
-6. Report what was run, what passed, and any remaining known failures.
+2. Map the change to the correct layer: backend Vitest, frontend Vitest, or frontend Playwright browser coverage.
+3. Add/update tests near the affected feature.
+4. Run the smallest relevant subset first.
+5. Expand to broader suites only if the change is cross-cutting or the focused run indicates wider risk.
+6. Run lint + required local test/build gates before PR handoff.
+7. Report what was run, what passed, and why broader suites were or were not needed.
 
 ## Lint and Quality Gates
 
@@ -60,6 +72,7 @@ Primary locations:
 - If lint fails, fix root causes first, then re-run affected tests.
 - Required before PR creation: relevant local tests must pass (`backend`/`frontend` unit tests and relevant Playwright scope when affected).
 - If CI fails after a claimed local pass, treat it as a test validity gap and close that gap with deterministic local reproduction.
+- Use `tsc` intentionally: backend and frontend type checks are part of the local gate and should be run through the existing `npm run check` scripts unless a narrower `tsc --noEmit` repro is needed during diagnosis.
 
 Recommended commands:
 
@@ -74,24 +87,36 @@ cd frontend && npm run check
 ### Backend
 
 ```bash
+cd backend && npx tsc --version
+cd backend && npx vitest --version
+cd backend && CI=true npm run test:run -- src/test/doses.test.ts
 cd backend && CI=true npm run test:run
 cd backend && CI=true npm run test:coverage
+cd backend && CI=true npm run test:run -- src/test/doses.test.ts src/test/integration.test.ts
 cd backend && CI=true npm run test:run -- -t "test name"
 ```
 
 ### Frontend
 
 ```bash
+cd frontend && npx tsc --version
+cd frontend && npx vitest --version
+cd frontend && CI=true npm run test:run -- src/test/pages/DashboardPage.test.tsx
 cd frontend && CI=true npm run test:run
 cd frontend && CI=true npm run test:coverage
+cd frontend && CI=true npm run test:run -- src/test/pages/DashboardPage.test.tsx src/test/hooks/useDoses.test.ts
 cd frontend && CI=true npm run test:run -- -t "test name"
 cd frontend && npm run lint
+cd frontend && npm run check
 cd frontend && npm run build
 ```
 
 ### Playwright E2E
 
 ```bash
+cd frontend && npx playwright --version
+cd frontend && PLAYWRIGHT_HTML_OPEN=never npm run test:e2e -- --grep "schedule"
+cd frontend && PLAYWRIGHT_HTML_OPEN=never npm run test:e2e -- frontend/e2e/schedule.spec.ts
 cd frontend && PLAYWRIGHT_HTML_OPEN=never npm run test:e2e
 cd frontend && PLAYWRIGHT_HTML_OPEN=never PLAYWRIGHT_WORKERS=1 npm run test:e2e -- --workers=1
 cd frontend && PLAYWRIGHT_HTML_OPEN=never PLAYWRIGHT_WORKERS=4 npm run test:e2e:local
@@ -113,8 +138,16 @@ cd frontend && PLAYWRIGHT_HTML_OPEN=never npm run test:e2e -- --project=chromium
 - Use stable selectors and explicit assertions.
 - Avoid flaky timing assumptions; prefer waiting for concrete UI states.
 - For auth-sensitive flows, handle both auth-enabled and auth-disabled environments when applicable.
-- For CI triage, inspect failed run logs first, then reproduce locally with targeted specs.
+- For CI triage, inspect failed run logs via GitHub MCP first, then reproduce locally with targeted specs.
 - Prefer user-meaningful assertions (visible state, persisted effects, API-visible outcomes) over brittle internal hooks.
+- Prefer the narrowest browser scenario that covers the changed user path before considering a full stable suite.
+
+## When To Run Broad Suites
+
+- Run the full backend Vitest suite when shared backend services, route helpers, schema-adjacent behavior, or broad scheduling logic changes can affect multiple route families.
+- Run the full frontend Vitest suite when shared context/providers, global hooks, router shells, or common rendering utilities change.
+- Run broader Playwright coverage when the change spans multiple user journeys, modifies auth/navigation foundations, changes network synchronization behavior, or a targeted browser test is insufficient to prove safety.
+- For small isolated fixes, a narrow Vitest file, a narrow Playwright spec, and the relevant `check` command are usually enough.
 
 ## Test Validity Checklist
 

.github/workflows/close-inactive-issues.yml

@@ -0,0 +1,27 @@
+name: Close inactive issues
+
+on:
+  schedule:
+    - cron: "30 1 * * *"
+  workflow_dispatch:
+
+jobs:
+  close-issues:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Mark and close stale issues
+        uses: actions/stale@v10
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          days-before-issue-stale: 30
+          days-before-issue-close: 14
+          stale-issue-label: stale
+          stale-issue-message: "This issue is stale because it has been open for 30 days with no activity."
+          close-issue-message: "This issue was closed because it has been inactive for 14 days since being marked as stale."
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+          exempt-issue-labels: pinned,security
+          operations-per-run: 200

.github/workflows/docker-build.yml

@@ -13,9 +13,18 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Image tag (leave empty for "latest")'
+        description: 'Image/release tag (e.g. v1.19.1 or latest)'
         required: false
         default: ''
+      create_release:
+        description: 'Create GitHub release entry (requires tag starting with v)'
+        required: false
+        default: false
+        type: boolean
+
+concurrency:
+  group: docker-build-${{ github.ref }}
+  cancel-in-progress: true
 
 # Default minimal permissions
 permissions:
@@ -54,10 +63,10 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Log in to Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -65,7 +74,7 @@ jobs:
 
       - name: Extract metadata
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
           images: ${{ env.REGISTRY }}/${{ github.repository_owner }}/medassist-ng-${{ matrix.image }}
           tags: |
@@ -76,7 +85,7 @@ jobs:
             type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
 
       - name: Build and push
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
         with:
           context: ${{ matrix.context }}
           push: true
@@ -89,12 +98,12 @@ jobs:
           sbom: false
 
   # =============================================================================
-  # Create GitHub Release (only on tag push)
+  # Create GitHub Release (on tag push or manual dispatch with create_release)
   # =============================================================================
   create-release:
     runs-on: ubuntu-latest
     needs: build-and-push
-    if: startsWith(github.ref, 'refs/tags/v')
+    if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && github.event.inputs.create_release == 'true')
     permissions:
       contents: write
     
@@ -104,10 +113,31 @@ jobs:
         with:
           fetch-depth: 0  # Fetch all history for changelog generation
 
+      - name: Resolve current tag
+        id: current_tag
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            CURRENT_TAG="${{ github.event.inputs.tag }}"
+          else
+            CURRENT_TAG="${GITHUB_REF#refs/tags/}"
+          fi
+
+          if [ -z "$CURRENT_TAG" ]; then
+            echo "Release tag is required. Provide workflow_dispatch input 'tag'."
+            exit 1
+          fi
+
+          if [[ "$CURRENT_TAG" != v* ]]; then
+            echo "Release tag must start with 'v' (example: v1.19.1)."
+            exit 1
+          fi
+
+          echo "value=$CURRENT_TAG" >> "$GITHUB_OUTPUT"
+
       - name: Check if release exists
         id: check_release
         run: |
-          CURRENT_TAG=${GITHUB_REF#refs/tags/}
+          CURRENT_TAG="${{ steps.current_tag.outputs.value }}"
           if gh release view "$CURRENT_TAG" &>/dev/null; then
             echo "exists=true" >> $GITHUB_OUTPUT
             echo "Release $CURRENT_TAG already exists, skipping creation"
@@ -121,25 +151,36 @@ jobs:
         if: steps.check_release.outputs.exists == 'false'
         id: prev_tag
         run: |
-          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          CURRENT_TAG="${{ steps.current_tag.outputs.value }}"
+
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            PREV_TAG=$(git tag --sort=-v:refname | grep '^v' | grep -vx "$CURRENT_TAG" | head -1 || true)
+          else
+            PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          fi
+
           echo "tag=${PREV_TAG}" >> $GITHUB_OUTPUT
 
       - name: Generate changelog
         if: steps.check_release.outputs.exists == 'false'
         id: changelog
         run: |
-          CURRENT_TAG=${GITHUB_REF#refs/tags/}
+          CURRENT_TAG="${{ steps.current_tag.outputs.value }}"
           PREV_TAG="${{ steps.prev_tag.outputs.tag }}"
           
-          echo "## What's Changed" > changelog.md
+          echo "## What's New" > changelog.md
+          echo "" >> changelog.md
+          echo "This release includes updates and fixes shipped with ${CURRENT_TAG}." >> changelog.md
+          echo "" >> changelog.md
+          echo "### Highlights" >> changelog.md
           echo "" >> changelog.md
           
           if [ -n "$PREV_TAG" ]; then
-            # Get commits between tags
-            git log ${PREV_TAG}..${CURRENT_TAG} --pretty=format:"* %s (%h)" --no-merges >> changelog.md
+            echo "Changes from ${PREV_TAG} to ${CURRENT_TAG}:" >> changelog.md
+            git log ${PREV_TAG}..${CURRENT_TAG} --pretty=format:"- %s (%h)" --no-merges >> changelog.md
           else
-            # First release - get recent commits
-            git log -20 --pretty=format:"* %s (%h)" --no-merges >> changelog.md
+            echo "Recent shipped commits:" >> changelog.md
+            git log -20 --pretty=format:"- %s (%h)" --no-merges >> changelog.md
           fi
           
           echo "" >> changelog.md
@@ -157,6 +198,8 @@ jobs:
         if: steps.check_release.outputs.exists == 'false'
         uses: softprops/action-gh-release@v2
         with:
+          tag_name: ${{ steps.current_tag.outputs.value }}
+          target_commitish: ${{ github.sha }}
           body_path: changelog.md
           generate_release_notes: false
           draft: false

.github/workflows/e2e.yml

@@ -3,18 +3,33 @@ name: E2E Tests
 on:
   pull_request:
     branches: [main]
-    paths:
-      - 'frontend/**'
-      - 'backend/**'
-      - '.github/workflows/e2e.yml'
 
 # Minimal permissions for security
 permissions:
   contents: read
 
 jobs:
+  changes:
+    name: Detect E2E relevance
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      e2e_relevant: ${{ steps.filter.outputs.e2e_relevant }}
+    steps:
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            e2e_relevant:
+              - 'frontend/**'
+              - 'backend/**'
+
   e2e:
     name: Playwright E2E
+    needs: changes
+    if: needs.changes.outputs.e2e_relevant == 'true'
     runs-on: ubuntu-latest
     timeout-minutes: 15
     permissions:

.github/workflows/sync-project-fields.yml

@@ -0,0 +1,144 @@
+name: Sync Project Fields
+
+on:
+  issues:
+    types: [opened, labeled, unlabeled, reopened]
+
+permissions: {}
+
+jobs:
+  sync-fields:
+    name: Sync Type/Priority fields from labels
+    runs-on: ubuntu-latest
+    steps:
+      - name: Sync fields
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}
+          script: |
+            const projectId = 'PVT_kwHOADH82s4BO2OT';
+            const issueNodeId = context.payload.issue.node_id;
+            const issueNumber = context.payload.issue.number;
+            const labels = (context.payload.issue.labels || []).map(l => l.name.toLowerCase());
+
+            const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+            const getProjectItem = async () => {
+              const data = await github.graphql(`
+                query($nodeId: ID!) {
+                  node(id: $nodeId) {
+                    ... on Issue {
+                      projectItems(first: 20) {
+                        nodes {
+                          id
+                          project { id }
+                        }
+                      }
+                    }
+                  }
+                }
+              `, { nodeId: issueNodeId });
+
+              const items = data.node?.projectItems?.nodes || [];
+              return items.find(item => item.project.id === projectId) || null;
+            };
+
+            let projectItem = await getProjectItem();
+
+            // add-to-project may run in parallel; retry briefly before giving up
+            for (let i = 0; !projectItem && i < 6; i++) {
+              console.log(`Issue #${issueNumber} not in project yet. Retry ${i + 1}/6...`);
+              await sleep(10000);
+              projectItem = await getProjectItem();
+            }
+
+            if (!projectItem) {
+              console.log(`Issue #${issueNumber} is not in project board. Skipping field sync.`);
+              return;
+            }
+
+            const fieldsData = await github.graphql(`
+              query($projectId: ID!) {
+                node(id: $projectId) {
+                  ... on ProjectV2 {
+                    fields(first: 50) {
+                      nodes {
+                        ... on ProjectV2SingleSelectField {
+                          id
+                          name
+                          options {
+                            id
+                            name
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            `, { projectId });
+
+            const singleSelectFields = fieldsData.node?.fields?.nodes || [];
+            const byName = new Map(singleSelectFields.map(f => [f.name, f]));
+
+            const typeField = byName.get('Type');
+            const priorityField = byName.get('Priority');
+
+            if (!typeField && !priorityField) {
+              console.log('Neither Type nor Priority field found. Nothing to update.');
+              return;
+            }
+
+            const pickOptionId = (field, optionName) => {
+              if (!field || !optionName) return null;
+              const opt = (field.options || []).find(o => o.name.toLowerCase() === optionName.toLowerCase());
+              return opt?.id || null;
+            };
+
+            let typeName = null;
+            if (labels.includes('bug')) typeName = 'Bug';
+            else if (labels.includes('enhancement')) typeName = 'Feature';
+            else if (labels.includes('documentation')) typeName = 'Documentation';
+
+            let priorityName = null;
+            if (labels.includes('priority/high')) priorityName = 'High';
+            else if (labels.includes('priority/low')) priorityName = 'Low';
+            else if (labels.includes('priority/medium')) priorityName = 'Medium';
+            else if (labels.includes('triage')) priorityName = 'Medium';
+
+            const updates = [];
+            const typeOptionId = pickOptionId(typeField, typeName);
+            if (typeField && typeOptionId) {
+              updates.push({ fieldId: typeField.id, optionId: typeOptionId, fieldName: 'Type', valueName: typeName });
+            }
+
+            const priorityOptionId = pickOptionId(priorityField, priorityName);
+            if (priorityField && priorityOptionId) {
+              updates.push({ fieldId: priorityField.id, optionId: priorityOptionId, fieldName: 'Priority', valueName: priorityName });
+            }
+
+            for (const update of updates) {
+              await github.graphql(`
+                mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+                  updateProjectV2ItemFieldValue(input: {
+                    projectId: $projectId
+                    itemId: $itemId
+                    fieldId: $fieldId
+                    value: { singleSelectOptionId: $optionId }
+                  }) {
+                    projectV2Item { id }
+                  }
+                }
+              `, {
+                projectId,
+                itemId: projectItem.id,
+                fieldId: update.fieldId,
+                optionId: update.optionId
+              });
+
+              console.log(`Issue #${issueNumber}: set ${update.fieldName} = ${update.valueName}`);
+            }
+
+            if (updates.length === 0) {
+              console.log(`Issue #${issueNumber}: no matching field updates for labels [${labels.join(', ')}]`);
+            }

.github/workflows/weekly-triage-report.yml

@@ -0,0 +1,77 @@
+name: Weekly Triage Report
+
+on:
+  schedule:
+    - cron: '0 7 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  weekly-report:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build weekly summary
+        id: summary
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+
+            const since = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString().split('T')[0];
+            const weekLabel = new Date().toISOString().split('T')[0];
+
+            const q = async (query) => {
+              const res = await github.rest.search.issuesAndPullRequests({ q: query, per_page: 1 });
+              return res.data.total_count;
+            };
+
+            const openIssues = await q(`repo:${owner}/${repo} is:issue is:open`);
+            const newIssues = await q(`repo:${owner}/${repo} is:issue created:>=${since}`);
+            const bugs = await q(`repo:${owner}/${repo} is:issue is:open label:bug`);
+            const enhancements = await q(`repo:${owner}/${repo} is:issue is:open label:enhancement`);
+            const triage = await q(`repo:${owner}/${repo} is:issue is:open label:triage`);
+            const stale = await q(`repo:${owner}/${repo} is:issue is:open label:stale`);
+            const unassigned = await q(`repo:${owner}/${repo} is:issue is:open no:assignee`);
+
+            const body = [
+              `## Weekly Triage Report (${weekLabel})`,
+              '',
+              `- Open issues: **${openIssues}**`,
+              `- New issues (last 7 days): **${newIssues}**`,
+              `- Open bugs: **${bugs}**`,
+              `- Open enhancements: **${enhancements}**`,
+              `- In triage: **${triage}**`,
+              `- Stale: **${stale}**`,
+              `- Unassigned: **${unassigned}**`,
+              '',
+              '### Quick Links',
+              `- Triage queue: https://github.com/${owner}/${repo}/issues?q=is%3Aissue+is%3Aopen+label%3Atriage`,
+              `- Stale issues: https://github.com/${owner}/${repo}/issues?q=is%3Aissue+is%3Aopen+label%3Astale`,
+              `- Unassigned issues: https://github.com/${owner}/${repo}/issues?q=is%3Aissue+is%3Aopen+no%3Aassignee`,
+            ].join('\n');
+
+            core.setOutput('title', `Weekly Triage Report - ${weekLabel}`);
+            core.setOutput('body', body);
+
+      - name: Publish report issue
+        uses: actions/github-script@v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const title = `${{ steps.summary.outputs.title }}`;
+            const body = `${{ steps.summary.outputs.body }}`;
+
+            await github.rest.issues.create({
+              owner,
+              repo,
+              title,
+              body,
+              labels: ['triage']
+            });

.gitignore

@@ -83,4 +83,8 @@ Thumbs.db
 AGENTS.md
 docs/TECH_STACK.md
 doku/
-plan/
+doku/memory_notes.md
+doku/report.md
+plan/
+.copilot-tracking/
+.playwright-cli/

.vscode/tasks.json

@@ -1,49 +1,88 @@
 {
-  "version": "2.0.0",
-  "tasks": [
-    {
-      "label": "E2E stable",
-      "type": "shell",
-      "command": "npm",
-      "args": ["run", "test:e2e"],
-      "options": {
-        "cwd": "${workspaceFolder}/frontend"
-      },
-      "group": "test",
-      "problemMatcher": []
-    },
-    {
-      "label": "E2E stable + merged video",
-      "type": "shell",
-      "command": "npm",
-      "args": ["run", "test:e2e:with-video"],
-      "options": {
-        "cwd": "${workspaceFolder}/frontend"
-      },
-      "group": "test",
-      "problemMatcher": []
-    },
-    {
-      "label": "E2E all browsers",
-      "type": "shell",
-      "command": "npm",
-      "args": ["run", "test:e2e:all"],
-      "options": {
-        "cwd": "${workspaceFolder}/frontend"
-      },
-      "group": "test",
-      "problemMatcher": []
-    },
-    {
-      "label": "E2E all browsers + merged video",
-      "type": "shell",
-      "command": "npm",
-      "args": ["run", "test:e2e:all:with-video"],
-      "options": {
-        "cwd": "${workspaceFolder}/frontend"
-      },
-      "group": "test",
-      "problemMatcher": []
-    }
-  ]
-}
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"label": "E2E stable",
+			"type": "shell",
+			"command": "npm",
+			"args": [
+				"run",
+				"test:e2e"
+			],
+			"options": {
+				"cwd": "${workspaceFolder}/frontend"
+			},
+			"group": "test",
+			"problemMatcher": []
+		},
+		{
+			"label": "E2E stable + merged video",
+			"type": "shell",
+			"command": "npm",
+			"args": [
+				"run",
+				"test:e2e:with-video"
+			],
+			"options": {
+				"cwd": "${workspaceFolder}/frontend"
+			},
+			"group": "test",
+			"problemMatcher": []
+		},
+		{
+			"label": "E2E all browsers",
+			"type": "shell",
+			"command": "npm",
+			"args": [
+				"run",
+				"test:e2e:all"
+			],
+			"options": {
+				"cwd": "${workspaceFolder}/frontend"
+			},
+			"group": "test",
+			"problemMatcher": []
+		},
+		{
+			"label": "E2E all browsers + merged video",
+			"type": "shell",
+			"command": "npm",
+			"args": [
+				"run",
+				"test:e2e:all:with-video"
+			],
+			"options": {
+				"cwd": "${workspaceFolder}/frontend"
+			},
+			"group": "test",
+			"problemMatcher": []
+		},
+		{
+			"label": "E2E stable non-interactive",
+			"type": "shell",
+			"command": "cd frontend && PLAYWRIGHT_HTML_OPEN=never PLAYWRIGHT_WORKERS=1 npm run test:e2e -- --workers=1",
+			"isBackground": false,
+			"group": "test"
+		},
+		{
+			"label": "Targeted frontend vitest",
+			"type": "shell",
+			"command": "cd frontend && npm test -- --run src/test/context/AppContext.test.tsx src/test/utils/schedule.test.ts",
+			"isBackground": false,
+			"group": "test"
+		},
+		{
+			"label": "Focused frontend shared schedule test",
+			"type": "shell",
+			"command": "cd frontend && npm run test:run -- --maxWorkers=1 src/test/components/SharedSchedule.test.tsx",
+			"isBackground": false,
+			"group": "test"
+		},
+		{
+			"label": "PR3 targeted validation",
+			"type": "shell",
+			"command": "git --no-pager diff --check -- .github/agents/release-manager.agent.md .github/agents/testing-manager.agent.md .gitignore .vscode/tasks.json && node -e \"JSON.parse(require('fs').readFileSync('.vscode/tasks.json','utf8')); console.log('tasks.json valid')\"",
+			"isBackground": false
+		}
+	]
+}

README.md

@@ -18,8 +18,8 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/Backend_Tests-577%2F577-brightgreen?logo=vitest" alt="Backend Tests 454/454" />
-  <img src="https://img.shields.io/badge/Frontend_Tests-777%2F777-brightgreen?logo=vitest" alt="Frontend Tests 611/611" />
+  <img src="https://img.shields.io/badge/Backend_Tests-618%2F618-brightgreen?logo=vitest" alt="Backend Tests 454/454" />
+  <img src="https://img.shields.io/badge/Frontend_Tests-807%2F807-brightgreen?logo=vitest" alt="Frontend Tests 611/611" />
 </p>
 
 ### 🤖 AI-Generated Code
@@ -120,10 +120,10 @@ Share your medication schedule with others via a public link.
 </details>
 
 ### Smart Inventory
-- Track exact stock: packs, blisters, bottles, and loose pills
+- Track exact stock with package profiles (blister, bottle, tube, liquid container)
 - Display remaining days of supply
 - Automatic calculation based on intake schedule
-- Manual stock correction supports partial blisters and loose pills
+- Manual stock correction supports profile-specific stock semantics (sealed units + loose stock for blister, amount-based stock for bottle/tube/liquid)
 
 ### Medication Refill
 - One-click refill with pack or loose pill options
@@ -141,7 +141,7 @@ Share your medication schedule with others via a public link.
 - Intake reminders via push notifications
 
 ### Trip Planner
-- Calculate how many pills you need for a trip or date range
+- Calculate medication demand for a trip or date range with package-aware units
 - Plan ahead for vacations, business trips, or hospital stays
 - Send demand reports via email or push notification
 
@@ -152,6 +152,7 @@ Share your medication schedule with others via a public link.
 ### Multi-Person Support
 - Manage medications for multiple people
 - Share schedules via link. Recipients can mark doses as taken, you see it live
+- Optionally embed the medication overview directly on shared links via a settings toggle
 
 ### Data Export & Import
 - Export all your data (medications, dose history, settings) as JSON
@@ -177,7 +178,7 @@ The easiest way to deploy MedAssist-ng is with Docker Compose:
 git clone https://github.com/DanielVolz/medassist-ng.git
 cd medassist-ng
 cp .env.example .env
-docker compose up -d
+docker compose -p medassist-ng up -d
 ```
 
 Open `http://localhost:4174` and start tracking your medications.
@@ -195,8 +196,23 @@ All configuration is done via environment variables in `.env`. Copy `.env.exampl
 | `PORT` | `3000` | Backend API port |
 | `CORS_ORIGINS` | `http://localhost:4174` | Allowed origins for CORS |
 | `LOG_LEVEL` | `info` | Log verbosity (`debug`, `info`, `warn`, `error`, `silent`). At `info` (default), high-frequency polling endpoints are suppressed. Set `debug` to see all requests. |
+| `OPENAPI_DOCS_ENABLED` | `auto` | Enables API docs in non-production by default. Set explicitly to `true`/`false` to override. |
 | `TZ` | `Europe/Berlin` | Timezone for scheduled reminders |
 
+Recommended values for API docs by environment:
+
+| Environment | Recommendation |
+|-------------|----------------|
+| Development | `OPENAPI_DOCS_ENABLED=true` |
+| Staging/Test | `OPENAPI_DOCS_ENABLED=true` |
+| Production | leave it unset, or set `OPENAPI_DOCS_ENABLED=false` |
+
+Notes:
+
+- If `OPENAPI_DOCS_ENABLED` is not set, docs are enabled outside production and disabled in production.
+- If `OPENAPI_DOCS_ENABLED=true`, docs are available on `/docs` and `/docs/json`.
+- If `OPENAPI_DOCS_ENABLED=false`, only the docs are disabled. The API still works normally.
+
 ### Authentication
 
 | Variable | Default | Description |
@@ -211,6 +227,43 @@ All configuration is done via environment variables in `.env`. Copy `.env.exampl
 
 Generate secrets with: `openssl rand -hex 32`
 
+### API Keys (Programmatic API Access)
+
+When `AUTH_ENABLED=true`, you can create personal API keys and call protected endpoints with:
+
+```bash
+Authorization: Bearer ma_...
+```
+
+Available scopes:
+
+- `read`: read-only access (`GET`, `HEAD`, `OPTIONS`)
+- `write`: read + write access
+
+Essential notes:
+
+- Create keys in the app when authentication is enabled.
+- The token is shown only once after creation.
+- Creating a new key automatically deactivates previously active keys for the same user.
+- API keys are stored hashed in the database.
+
+Example usage:
+
+```bash
+curl http://localhost:3000/settings \
+  -H "Authorization: Bearer ma_..."
+```
+
+API reference:
+
+- Interactive docs: `/docs`
+- OpenAPI JSON: `/docs/json`
+- With the bundled frontend ingress, these paths work on the normal app URL as well, for example `http://localhost:4174/docs` when docs are enabled.
+- Key management endpoints for authenticated users:
+  - `GET /auth/api-keys`
+  - `POST /auth/api-keys`
+  - `DELETE /auth/api-keys/:id`
+
 ### OIDC / SSO
 
 | Variable | Default | Description |
@@ -267,9 +320,9 @@ Configure push notifications in Settings → Push, or set defaults via environme
 
 These defaults are applied when a new user is created. Once a user saves settings in the app, their values take precedence.
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `DEFAULT_SHARE_STOCK_STATUS` | `true` | Show stock status (Normal/Low/Critical) on shared schedule links |
+Complete list and details:
+
+- [docs/DEFAULT_USER_SETTINGS.md](docs/DEFAULT_USER_SETTINGS.md)
 
 #### URL Examples
 
@@ -309,30 +362,22 @@ For all services and options, see the [Shoutrrr documentation](https://containrr
 # Development
 
 ```bash
-docker compose -f docker-compose.dev.yml up
+docker compose -p medassist-dev -f docker-compose.dev.yml up
 ```
 
 - Frontend: `http://localhost:5173` (hot reload)
 - Backend: `http://localhost:3000`
+- API docs UI: `http://localhost:3000/docs` (when docs are enabled)
+- OpenAPI JSON: `http://localhost:3000/docs/json` (when docs are enabled)
 
-Playwright E2E recommendations:
+Useful local commands:
 
 ```bash
-cd frontend
-npm run test:e2e:local      # local run with PLAYWRIGHT_WORKERS=4
-npm run test:e2e:all:local  # local all-browser run with PLAYWRIGHT_WORKERS=4
+npm run lint
+cd backend && npm run test:run
+cd frontend && npm run test:run
 ```
 
-- CI stays at `PLAYWRIGHT_WORKERS=1` for stability.
-- Data-heavy specs remain sequential via the `chromium-data` project config.
-
-# Dependency Updates
-
-- Dependabot checks dependencies weekly for `frontend`, `backend`, repository root tooling, and GitHub Actions.
-- Minor and patch updates are grouped to reduce PR noise.
-- Dependabot minor/patch PRs are configured for auto-merge after required CI checks pass.
-- Major updates still require manual review before merge.
-
 # Acknowledgements
 
 This project was inspired by [MedAssist](https://github.com/njic/medassist) by njic.

backend/drizzle/0012_add_api_keys_and_package_amount_columns.sql

@@ -0,0 +1,18 @@
+CREATE TABLE `api_keys` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`user_id` integer NOT NULL,
+	`name` text(100) NOT NULL,
+	`key_hash` text(128) NOT NULL,
+	`token_prefix` text(24) DEFAULT '' NOT NULL,
+	`scope` text(10) DEFAULT 'write' NOT NULL,
+	`is_active` integer DEFAULT true NOT NULL,
+	`last_used_at` integer,
+	`expires_at` integer,
+	`created_at` integer DEFAULT CURRENT_TIMESTAMP NOT NULL,
+	`updated_at` integer DEFAULT CURRENT_TIMESTAMP NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `api_keys_key_hash_unique` ON `api_keys` (`key_hash`);--> statement-breakpoint
+ALTER TABLE `medications` ADD `package_amount_value` integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE `medications` ADD `package_amount_unit` text(10) DEFAULT 'ml' NOT NULL;

backend/drizzle/0013_add_share_medication_overview.sql

@@ -0,0 +1 @@
+ALTER TABLE `user_settings` ADD `share_medication_overview` integer DEFAULT false NOT NULL;

backend/drizzle/meta/_journal.json

@@ -76,14 +76,28 @@
       "idx": 10,
       "version": "6",
       "when": 1771694832866,
-      "tag": "0010_mean_spot",
+      "tag": "0010_add_dose_tracking_taken_source",
       "breakpoints": true
     },
     {
       "idx": 11,
       "version": "6",
       "when": 1772219947541,
-      "tag": "0011_stiff_randall_flagg",
+      "tag": "0011_add_medication_form_lifecycle_columns",
+      "breakpoints": true
+    },
+    {
+      "idx": 12,
+      "version": "6",
+      "when": 1772881208026,
+      "tag": "0012_add_api_keys_and_package_amount_columns",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "6",
+      "when": 1773348659979,
+      "tag": "0013_add_share_medication_overview",
       "breakpoints": true
     }
   ]

backend/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "medassist-ng-backend",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "medassist-ng-backend",
-      "version": "1.18.1",
+      "version": "1.19.0",
       "dependencies": {
         "@fastify/cookie": "^11.0.2",
         "@fastify/cors": "^11.2.0",
@@ -16,19 +16,21 @@
         "@fastify/rate-limit": "^10.3.0",
         "@fastify/sensible": "^6.0.4",
         "@fastify/static": "^9.0.0",
+        "@fastify/swagger": "^9.7.0",
+        "@fastify/swagger-ui": "^5.2.5",
         "@libsql/client": "^0.17.0",
         "argon2": "^0.44.0",
         "dotenv": "^17.3.1",
         "drizzle-orm": "^0.45.1",
-        "fastify": "^5.7.4",
+        "fastify": "^5.8.2",
         "nodemailer": "^8.0.1",
         "openid-client": "^6.8.2",
         "sharp": "^0.34.5",
         "zod": "^3.23.8"
       },
       "devDependencies": {
-        "@biomejs/biome": "^2.4.4",
-        "@types/node": "^25.3.3",
+        "@biomejs/biome": "^2.4.6",
+        "@types/node": "^25.3.5",
         "@types/nodemailer": "^7.0.11",
         "@types/supertest": "^7.2.0",
         "@vitest/coverage-v8": "^4.0.18",
@@ -101,9 +103,9 @@
       }
     },
     "node_modules/@biomejs/biome": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.4.4.tgz",
-      "integrity": "sha512-tigwWS5KfJf0cABVd52NVaXyAVv4qpUXOWJ1rxFL8xF1RVoeS2q/LK+FHgYoKMclJCuRoCWAPy1IXaN9/mS61Q==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.4.6.tgz",
+      "integrity": "sha512-QnHe81PMslpy3mnpL8DnO2M4S4ZnYPkjlGCLWBZT/3R9M6b5daArWMMtEfP52/n174RKnwRIf3oT8+wc9ihSfQ==",
       "dev": true,
       "license": "MIT OR Apache-2.0",
       "bin": {
@@ -117,20 +119,20 @@
         "url": "https://opencollective.com/biome"
       },
       "optionalDependencies": {
-        "@biomejs/cli-darwin-arm64": "2.4.4",
-        "@biomejs/cli-darwin-x64": "2.4.4",
-        "@biomejs/cli-linux-arm64": "2.4.4",
-        "@biomejs/cli-linux-arm64-musl": "2.4.4",
-        "@biomejs/cli-linux-x64": "2.4.4",
-        "@biomejs/cli-linux-x64-musl": "2.4.4",
-        "@biomejs/cli-win32-arm64": "2.4.4",
-        "@biomejs/cli-win32-x64": "2.4.4"
+        "@biomejs/cli-darwin-arm64": "2.4.6",
+        "@biomejs/cli-darwin-x64": "2.4.6",
+        "@biomejs/cli-linux-arm64": "2.4.6",
+        "@biomejs/cli-linux-arm64-musl": "2.4.6",
+        "@biomejs/cli-linux-x64": "2.4.6",
+        "@biomejs/cli-linux-x64-musl": "2.4.6",
+        "@biomejs/cli-win32-arm64": "2.4.6",
+        "@biomejs/cli-win32-x64": "2.4.6"
       }
     },
     "node_modules/@biomejs/cli-darwin-arm64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.4.tgz",
-      "integrity": "sha512-jZ+Xc6qvD6tTH5jM6eKX44dcbyNqJHssfl2nnwT6vma6B1sj7ZLTGIk6N5QwVBs5xGN52r3trk5fgd3sQ9We9A==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.6.tgz",
+      "integrity": "sha512-NW18GSyxr+8sJIqgoGwVp5Zqm4SALH4b4gftIA0n62PTuBs6G2tHlwNAOj0Vq0KKSs7Sf88VjjmHh0O36EnzrQ==",
       "cpu": [
         "arm64"
       ],
@@ -145,9 +147,9 @@
       }
     },
     "node_modules/@biomejs/cli-darwin-x64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.4.4.tgz",
-      "integrity": "sha512-Dh1a/+W+SUCXhEdL7TiX3ArPTFCQKJTI1mGncZNWfO+6suk+gYA4lNyJcBB+pwvF49uw0pEbUS49BgYOY4hzUg==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.4.6.tgz",
+      "integrity": "sha512-4uiE/9tuI7cnjtY9b07RgS7gGyYOAfIAGeVJWEfeCnAarOAS7qVmuRyX6d7JTKw28/mt+rUzMasYeZ+0R/U1Mw==",
       "cpu": [
         "x64"
       ],
@@ -162,9 +164,9 @@
       }
     },
     "node_modules/@biomejs/cli-linux-arm64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.4.4.tgz",
-      "integrity": "sha512-V/NFfbWhsUU6w+m5WYbBenlEAz8eYnSqRMDMAW3K+3v0tYVkNyZn8VU0XPxk/lOqNXLSCCrV7FmV/u3SjCBShg==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.4.6.tgz",
+      "integrity": "sha512-kMLaI7OF5GN1Q8Doymjro1P8rVEoy7BKQALNz6fiR8IC1WKduoNyteBtJlHT7ASIL0Cx2jR6VUOBIbcB1B8pew==",
       "cpu": [
         "arm64"
       ],
@@ -179,9 +181,9 @@
       }
     },
     "node_modules/@biomejs/cli-linux-arm64-musl": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.4.4.tgz",
-      "integrity": "sha512-+sPAXq3bxmFwhVFJnSwkSF5Rw2ZAJMH3MF6C9IveAEOdSpgajPhoQhbbAK12SehN9j2QrHpk4J/cHsa/HqWaYQ==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.4.6.tgz",
+      "integrity": "sha512-F/JdB7eN22txiTqHM5KhIVt0jVkzZwVYrdTR1O3Y4auBOQcXxHK4dxULf4z43QyZI5tsnQJrRBHZy7wwtL+B3A==",
       "cpu": [
         "arm64"
       ],
@@ -196,9 +198,9 @@
       }
     },
     "node_modules/@biomejs/cli-linux-x64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.4.4.tgz",
-      "integrity": "sha512-R4+ZCDtG9kHArasyBO+UBD6jr/FcFCTH8QkNTOCu0pRJzCWyWC4EtZa2AmUZB5h3e0jD7bRV2KvrENcf8rndBg==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.4.6.tgz",
+      "integrity": "sha512-oHXmUFEoH8Lql1xfc3QkFLiC1hGR7qedv5eKNlC185or+o4/4HiaU7vYODAH3peRCfsuLr1g6v2fK9dFFOYdyw==",
       "cpu": [
         "x64"
       ],
@@ -213,9 +215,9 @@
       }
     },
     "node_modules/@biomejs/cli-linux-x64-musl": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.4.4.tgz",
-      "integrity": "sha512-gGvFTGpOIQDb5CQ2VC0n9Z2UEqlP46c4aNgHmAMytYieTGEcfqhfCFnhs6xjt0S3igE6q5GLuIXtdQt3Izok+g==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.4.6.tgz",
+      "integrity": "sha512-C9s98IPDu7DYarjlZNuzJKTjVHN03RUnmHV5htvqsx6vEUXCDSJ59DNwjKVD5XYoSS4N+BYhq3RTBAL8X6svEg==",
       "cpu": [
         "x64"
       ],
@@ -230,9 +232,9 @@
       }
     },
     "node_modules/@biomejs/cli-win32-arm64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.4.4.tgz",
-      "integrity": "sha512-trzCqM7x+Gn832zZHgr28JoYagQNX4CZkUZhMUac2YxvvyDRLJDrb5m9IA7CaZLlX6lTQmADVfLEKP1et1Ma4Q==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.4.6.tgz",
+      "integrity": "sha512-xzThn87Pf3YrOGTEODFGONmqXpTwUNxovQb72iaUOdcw8sBSY3+3WD8Hm9IhMYLnPi0n32s3L3NWU6+eSjfqFg==",
       "cpu": [
         "arm64"
       ],
@@ -247,9 +249,9 @@
       }
     },
     "node_modules/@biomejs/cli-win32-x64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.4.tgz",
-      "integrity": "sha512-gnOHKVPFAAPrpoPt2t+Q6FZ7RPry/FDV3GcpU53P3PtLNnQjBmKyN2Vh/JtqXet+H4pme8CC76rScwdjDcT1/A==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.6.tgz",
+      "integrity": "sha512-7++XhnsPlr1HDbor5amovPjOH6vsrFOCdp93iKXhFn6bcMUI6soodj3WWKfgEO6JosKU1W5n3uky3WW9RlRjTg==",
       "cpu": [
         "x64"
       ],
@@ -1512,6 +1514,52 @@
         "glob": "^13.0.0"
       }
     },
+    "node_modules/@fastify/swagger": {
+      "version": "9.7.0",
+      "resolved": "https://registry.npmjs.org/@fastify/swagger/-/swagger-9.7.0.tgz",
+      "integrity": "sha512-Vp1SC1GC2Hrkd3faFILv86BzUNyFz5N4/xdExqtCgkGASOzn/x+eMe4qXIGq7cdT6wif/P/oa6r1Ruqx19paZA==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "fastify-plugin": "^5.0.0",
+        "json-schema-resolver": "^3.0.0",
+        "openapi-types": "^12.1.3",
+        "rfdc": "^1.3.1",
+        "yaml": "^2.4.2"
+      }
+    },
+    "node_modules/@fastify/swagger-ui": {
+      "version": "5.2.5",
+      "resolved": "https://registry.npmjs.org/@fastify/swagger-ui/-/swagger-ui-5.2.5.tgz",
+      "integrity": "sha512-ky3I0LAkXKX/prwSDpoQ3kscBKsj2Ha6Gp1/JfgQSqyx0bm9F2bE//XmGVGj2cR9l5hUjZYn60/hqn7e+OLgWQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@fastify/static": "^9.0.0",
+        "fastify-plugin": "^5.0.0",
+        "openapi-types": "^12.1.3",
+        "rfdc": "^1.3.1",
+        "yaml": "^2.4.1"
+      }
+    },
     "node_modules/@img/colour": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.0.0.tgz",
@@ -2625,9 +2673,9 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "25.3.3",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.3.3.tgz",
-      "integrity": "sha512-DpzbrH7wIcBaJibpKo9nnSQL0MTRdnWttGyE5haGwK86xgMOkFLp7vEyfQPGLOJh5wNYiJ3V9PmUMDhV9u8kkQ==",
+      "version": "25.3.5",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.3.5.tgz",
+      "integrity": "sha512-oX8xrhvpiyRCQkG1MFchB09f+cXftgIXb3a7UUa4Y3wpmZPw5tyZGTLWhlESOLq1Rq6oDlc8npVU2/9xiCuXMA==",
       "license": "MIT",
       "dependencies": {
         "undici-types": "~7.18.0"
@@ -3183,7 +3231,6 @@
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
       "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "ms": "^2.1.3"
@@ -4156,9 +4203,9 @@
       }
     },
     "node_modules/fastify": {
-      "version": "5.7.4",
-      "resolved": "https://registry.npmjs.org/fastify/-/fastify-5.7.4.tgz",
-      "integrity": "sha512-e6l5NsRdaEP8rdD8VR0ErJASeyaRbzXYpmkrpr2SuvuMq6Si3lvsaVy5C+7gLanEkvjpMDzBXWE5HPeb/hgTxA==",
+      "version": "5.8.2",
+      "resolved": "https://registry.npmjs.org/fastify/-/fastify-5.8.2.tgz",
+      "integrity": "sha512-lZmt3navvZG915IE+f7/TIVamxIwmBd+OMB+O9WBzcpIwOo6F0LTh0sluoMFk5VkrKTvvrwIaoJPkir4Z+jtAg==",
       "funding": [
         {
           "type": "github",
@@ -4180,7 +4227,7 @@
         "fast-json-stringify": "^6.0.0",
         "find-my-way": "^9.0.0",
         "light-my-request": "^6.0.0",
-        "pino": "^10.1.0",
+        "pino": "^9.14.0 || ^10.1.0",
         "process-warning": "^5.0.0",
         "rfdc": "^1.3.1",
         "secure-json-parse": "^4.0.0",
@@ -4695,6 +4742,23 @@
         "dequal": "^2.0.3"
       }
     },
+    "node_modules/json-schema-resolver": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-resolver/-/json-schema-resolver-3.0.0.tgz",
+      "integrity": "sha512-HqMnbz0tz2DaEJ3ntsqtx3ezzZyDE7G56A/pPY/NGmrPu76UzsWquOpHFRAf5beTNXoH2LU5cQePVvRli1nchA==",
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.1.1",
+        "fast-uri": "^3.0.5",
+        "rfdc": "^1.1.4"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/Eomm/json-schema-resolver?sponsor=1"
+      }
+    },
     "node_modules/json-schema-traverse": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
@@ -4936,7 +5000,6 @@
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
       "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/nanoid": {
@@ -5083,6 +5146,12 @@
         "wrappy": "1"
       }
     },
+    "node_modules/openapi-types": {
+      "version": "12.1.3",
+      "resolved": "https://registry.npmjs.org/openapi-types/-/openapi-types-12.1.3.tgz",
+      "integrity": "sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==",
+      "license": "MIT"
+    },
     "node_modules/openid-client": {
       "version": "6.8.2",
       "resolved": "https://registry.npmjs.org/openid-client/-/openid-client-6.8.2.tgz",
@@ -6207,6 +6276,21 @@
         "node": ">=0.4"
       }
     },
+    "node_modules/yaml": {
+      "version": "2.8.2",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz",
+      "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    },
     "node_modules/zod": {
       "version": "3.25.76",
       "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",

backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medassist-ng-backend",
-  "version": "1.18.2",
+  "version": "1.20.0",
   "private": true,
   "type": "module",
   "scripts": {
@@ -25,19 +25,21 @@
     "@fastify/rate-limit": "^10.3.0",
     "@fastify/sensible": "^6.0.4",
     "@fastify/static": "^9.0.0",
+    "@fastify/swagger": "^9.7.0",
+    "@fastify/swagger-ui": "^5.2.5",
     "@libsql/client": "^0.17.0",
     "argon2": "^0.44.0",
     "dotenv": "^17.3.1",
     "drizzle-orm": "^0.45.1",
-    "fastify": "^5.7.4",
+    "fastify": "^5.8.2",
     "nodemailer": "^8.0.1",
     "openid-client": "^6.8.2",
     "sharp": "^0.34.5",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
-    "@types/node": "^25.3.3",
+    "@biomejs/biome": "^2.4.6",
+    "@types/node": "^25.3.5",
     "@types/nodemailer": "^7.0.11",
     "@types/supertest": "^7.2.0",
     "@vitest/coverage-v8": "^4.0.18",

backend/src/db/db-utils.ts

@@ -149,6 +149,8 @@ export async function runAlterMigrations(client: Client): Promise<{ success: boo
 		`ALTER TABLE user_settings ADD COLUMN last_stock_reminder_med_names text`,
 		// Added for share stock visibility toggle
 		`ALTER TABLE user_settings ADD COLUMN share_stock_status integer NOT NULL DEFAULT 1`,
+		// Added for integrated share overview visibility on shared links
+		`ALTER TABLE user_settings ADD COLUMN share_medication_overview integer NOT NULL DEFAULT 0`,
 		// Added for timeline visibility toggles (dashboard + shared schedule)
 		`ALTER TABLE user_settings ADD COLUMN upcoming_today_only integer NOT NULL DEFAULT 0`,
 		`ALTER TABLE user_settings ADD COLUMN share_schedule_today_only integer NOT NULL DEFAULT 0`,
@@ -189,7 +191,21 @@ export async function runAlterMigrations(client: Client): Promise<{ success: boo
       packs_added INTEGER NOT NULL DEFAULT 0,
       loose_pills_added INTEGER NOT NULL DEFAULT 0,
       refill_date INTEGER NOT NULL DEFAULT (strftime('%s','now'))
-    )`,
+	    )`,
+		// Added in v1.20.x - API key authentication for programmatic access
+		`CREATE TABLE IF NOT EXISTS api_keys (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+			name TEXT NOT NULL,
+			key_hash TEXT NOT NULL UNIQUE,
+			token_prefix TEXT NOT NULL DEFAULT '',
+			scope TEXT NOT NULL DEFAULT 'write',
+			is_active INTEGER NOT NULL DEFAULT 1,
+			last_used_at INTEGER,
+			expires_at INTEGER,
+			created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')),
+			updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now'))
+		)`,
 	];
 
 	for (const sql of createTableMigrations) {
@@ -207,6 +223,9 @@ export async function runAlterMigrations(client: Client): Promise<{ success: boo
 	const createIndexMigrations = [
 		// Added in v1.6.x - case-insensitive unique usernames
 		`CREATE UNIQUE INDEX IF NOT EXISTS users_username_lower_unique ON users(lower(username))`,
+		// Added in v1.20.x - fast API key lookup and ownership filtering
+		`CREATE UNIQUE INDEX IF NOT EXISTS api_keys_key_hash_unique ON api_keys(key_hash)`,
+		`CREATE INDEX IF NOT EXISTS api_keys_user_id_idx ON api_keys(user_id)`,
 	];
 
 	for (const sql of createIndexMigrations) {

backend/src/db/schema.ts

@@ -109,6 +109,8 @@ export const userSettings = sqliteTable("user_settings", {
 	stockCalculationMode: text("stock_calculation_mode", { length: 20 }).notNull().default("automatic"),
 	// Whether shared schedule links show stock status (Critical/Low/Normal) to intake users
 	shareStockStatus: integer("share_stock_status", { mode: "boolean" }).notNull().default(true),
+	// Whether shared schedule links also embed the medication overview section
+	shareMedicationOverview: integer("share_medication_overview", { mode: "boolean" }).notNull().default(false),
 	// UI timeline visibility preferences
 	upcomingTodayOnly: integer("upcoming_today_only", { mode: "boolean" }).notNull().default(false),
 	shareScheduleTodayOnly: integer("share_schedule_today_only", { mode: "boolean" }).notNull().default(false),
@@ -146,6 +148,25 @@ export const refreshTokens = sqliteTable("refresh_tokens", {
 	createdAt: integer("created_at", { mode: "timestamp" }).notNull().default(sql`CURRENT_TIMESTAMP`),
 });
 
+// =============================================================================
+// API Keys - Personal access tokens for programmatic API access
+// =============================================================================
+export const apiKeys = sqliteTable("api_keys", {
+	id: integer("id").primaryKey({ autoIncrement: true }),
+	userId: integer("user_id")
+		.notNull()
+		.references(() => users.id, { onDelete: "cascade" }),
+	name: text("name", { length: 100 }).notNull(),
+	keyHash: text("key_hash", { length: 128 }).notNull().unique(),
+	tokenPrefix: text("token_prefix", { length: 24 }).notNull().default(""),
+	scope: text("scope", { length: 10 }).notNull().default("write"), // 'read' | 'write'
+	isActive: integer("is_active", { mode: "boolean" }).notNull().default(true),
+	lastUsedAt: integer("last_used_at", { mode: "timestamp" }),
+	expiresAt: integer("expires_at", { mode: "timestamp" }),
+	createdAt: integer("created_at", { mode: "timestamp" }).notNull().default(sql`CURRENT_TIMESTAMP`),
+	updatedAt: integer("updated_at", { mode: "timestamp" }).notNull().default(sql`CURRENT_TIMESTAMP`),
+});
+
 // =============================================================================
 // Share Tokens - For public schedule sharing by takenBy person
 // =============================================================================

backend/src/index.ts

@@ -10,10 +10,13 @@ import fastifyMultipart from "@fastify/multipart";
 import rateLimit from "@fastify/rate-limit";
 import sensible from "@fastify/sensible";
 import fastifyStatic from "@fastify/static";
+import fastifySwagger from "@fastify/swagger";
+import fastifySwaggerUi from "@fastify/swagger-ui";
 import Fastify, { type FastifyInstance } from "fastify";
 import { migrationsReady } from "./db/client.js";
 import { getDataDir } from "./db/db-utils.js";
 import { env } from "./plugins/env.js";
+import { apiKeyRoutes } from "./routes/api-keys.js";
 import { authRoutes } from "./routes/auth.js";
 import { doseRoutes } from "./routes/doses.js";
 import { exportRoutes } from "./routes/export.js";
@@ -27,6 +30,7 @@ import { settingsRoutes } from "./routes/settings.js";
 import { shareRoutes } from "./routes/share.js";
 import { startIntakeReminderScheduler } from "./services/intake-reminder-scheduler.js";
 import { startReminderScheduler } from "./services/reminder-scheduler.js";
+import { documentationSchemaAjv } from "./utils/documentation-schema-keywords.js";
 
 // Re-export utilities from server-config for external use
 export {
@@ -58,12 +62,13 @@ function sanitizeCorrelationId(headers: IncomingHttpHeaders): string | null {
 }
 
 function buildLoggerOptions(level: string) {
+	const runtimeEnv = process.env.NODE_ENV ?? "production";
 	const base = {
 		level,
 		timestamp: () => `,"time":"${new Date().toISOString()}"`,
 	};
 	// Human-readable logs in development, structured JSON in production/test
-	if (process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test") {
+	if (runtimeEnv === "development") {
 		return {
 			...base,
 			transport: { target: "pino-pretty", options: { translateTime: "SYS:yyyy-mm-dd HH:MM:ss.l" } },
@@ -72,6 +77,55 @@ function buildLoggerOptions(level: string) {
 	return base;
 }
 
+async function registerApiDocs(app: FastifyInstance, enabled: boolean) {
+	if (!enabled) return;
+
+	await app.register(fastifySwagger, {
+		openapi: {
+			openapi: "3.0.3",
+			info: {
+				title: "MedAssist-ng API",
+				description: "MedAssist-ng backend API",
+				version: process.env.npm_package_version ?? "dev",
+			},
+			servers: [{ url: "/", description: "Current server" }],
+			tags: [
+				{ name: "health", description: "Service health endpoints" },
+				{ name: "auth", description: "Authentication and profile endpoints" },
+				{ name: "api-keys", description: "Programmatic API key management" },
+				{ name: "settings", description: "User settings and notification test endpoints" },
+			],
+			components: {
+				securitySchemes: {
+					bearerAuth: {
+						type: "http",
+						scheme: "bearer",
+						bearerFormat: "API key or JWT",
+						description: "Use Authorization: Bearer ma_... (API key) or a JWT token.",
+					},
+					cookieAuth: {
+						type: "apiKey",
+						in: "cookie",
+						name: "access_token",
+						description: "Session cookie set by login.",
+					},
+				},
+			},
+		},
+		hideUntagged: false,
+	});
+
+	await app.register(fastifySwaggerUi, {
+		routePrefix: "/docs",
+		staticCSP: true,
+		transformSpecificationClone: true,
+		uiConfig: {
+			docExpansion: "list",
+			deepLinking: false,
+		},
+	});
+}
+
 /** Create and configure Fastify app (without starting) */
 export async function createApp(options?: {
 	logLevel?: string;
@@ -84,6 +138,7 @@ export async function createApp(options?: {
 	refreshTtlDays?: number;
 	isProduction?: boolean;
 	imagesDir?: string;
+	openApiDocsEnabled?: boolean;
 }): Promise<FastifyInstance> {
 	const opts = {
 		logLevel: options?.logLevel ?? "info",
@@ -96,11 +151,13 @@ export async function createApp(options?: {
 		refreshTtlDays: options?.refreshTtlDays ?? 7,
 		isProduction: options?.isProduction ?? false,
 		imagesDir: options?.imagesDir ?? resolve(getDataDir(), "images"),
+		openApiDocsEnabled: options?.openApiDocsEnabled ?? false,
 	};
 
 	const app = Fastify({
 		logger: buildLoggerOptions(opts.logLevel),
 		genReqId: (request) => sanitizeCorrelationId(request.headers) ?? randomUUID(),
+		ajv: documentationSchemaAjv,
 	});
 
 	app.addHook("onRequest", (request, reply, done) => {
@@ -132,6 +189,7 @@ export async function createApp(options?: {
 	await app.register(jwt, jwtConfig);
 
 	await app.register(fastifyMultipart, { limits: { fileSize: 10 * 1024 * 1024 } });
+	await registerApiDocs(app, opts.openApiDocsEnabled);
 
 	// Only register static if directory exists
 	if (existsSync(opts.imagesDir)) {
@@ -145,6 +203,7 @@ export async function createApp(options?: {
 	// Register routes
 	await app.register(healthRoutes);
 	await app.register(authRoutes);
+	await app.register(apiKeyRoutes);
 	await app.register(oidcRoutes);
 	await app.register(medicationRoutes);
 	await app.register(settingsRoutes);
@@ -174,6 +233,7 @@ const imagesDir = ensureImagesDirectory();
 const app = Fastify({
 	logger: buildLoggerOptions(env.LOG_LEVEL),
 	genReqId: (request) => sanitizeCorrelationId(request.headers) ?? randomUUID(),
+	ajv: documentationSchemaAjv,
 });
 
 app.addHook("onRequest", (request, reply, done) => {
@@ -215,6 +275,7 @@ const jwtConfig = getJwtConfig(env.AUTH_ENABLED, env.JWT_SECRET);
 await app.register(jwt, jwtConfig);
 
 await app.register(fastifyMultipart, { limits: { fileSize: 10 * 1024 * 1024 } }); // 10MB limit
+await registerApiDocs(app, env.OPENAPI_DOCS_ENABLED);
 await app.register(fastifyStatic, {
 	root: imagesDir,
 	prefix: "/images/",
@@ -223,6 +284,7 @@ await app.register(fastifyStatic, {
 
 await app.register(healthRoutes);
 await app.register(authRoutes);
+await app.register(apiKeyRoutes);
 await app.register(oidcRoutes);
 await app.register(medicationRoutes);
 await app.register(settingsRoutes);

backend/src/plugins/auth.ts

@@ -1,7 +1,8 @@
-import { count, eq, sql } from "drizzle-orm";
+import { pbkdf2Sync } from "node:crypto";
+import { and, count, eq, sql } from "drizzle-orm";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { db } from "../db/client.js";
-import { users } from "../db/schema.js";
+import { apiKeys, users } from "../db/schema.js";
 import { env } from "./env.js";
 
 // =============================================================================
@@ -82,6 +83,84 @@ export interface RequestUser {
 	username: string;
 }
 
+const READ_ONLY_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+function isMutationMethod(method: string): boolean {
+	return !READ_ONLY_METHODS.has(method.toUpperCase());
+}
+
+function getApiKeyPepper(): string {
+	return env.JWT_SECRET || env.REFRESH_SECRET || "medassist-api-key-pepper";
+}
+
+export function hashApiKeyToken(token: string): string {
+	return pbkdf2Sync(token, getApiKeyPepper(), 120_000, 64, "sha512").toString("hex");
+}
+
+function getBearerToken(request: FastifyRequest): string | null {
+	const authHeader = request.headers.authorization;
+	if (!authHeader) return null;
+
+	const [scheme, value] = authHeader.split(" ");
+	if (!scheme || !value) return null;
+	if (scheme.toLowerCase() !== "bearer") return null;
+
+	const token = value.trim();
+	return token.length > 0 ? token : null;
+}
+
+async function tryApiKeyAuth(request: FastifyRequest, reply: FastifyReply): Promise<boolean> {
+	const bearerToken = getBearerToken(request);
+	if (!bearerToken) return false;
+
+	if (!bearerToken.startsWith("ma_")) {
+		reply.status(401).send({ error: "Invalid API key", code: "INVALID_API_KEY" });
+		throw new Error("INVALID_API_KEY");
+	}
+
+	const keyHash = hashApiKeyToken(bearerToken);
+	const [keyRow] = await db
+		.select()
+		.from(apiKeys)
+		.where(and(eq(apiKeys.keyHash, keyHash), eq(apiKeys.isActive, true)));
+
+	if (!keyRow) {
+		reply.status(401).send({ error: "Invalid API key", code: "INVALID_API_KEY" });
+		throw new Error("INVALID_API_KEY");
+	}
+
+	if (keyRow.expiresAt && keyRow.expiresAt.getTime() <= Date.now()) {
+		reply.status(401).send({ error: "API key expired", code: "API_KEY_EXPIRED" });
+		throw new Error("API_KEY_EXPIRED");
+	}
+
+	const [user] = await db.select().from(users).where(eq(users.id, keyRow.userId));
+	if (!user || !user.isActive) {
+		reply.status(401).send({ error: "User not found", code: "USER_NOT_FOUND" });
+		throw new Error("USER_NOT_FOUND");
+	}
+
+	const scope = keyRow.scope === "read" ? "read" : "write";
+	if (scope === "read" && isMutationMethod(request.method)) {
+		reply.status(403).send({ error: "API key scope does not allow this operation", code: "API_KEY_SCOPE_FORBIDDEN" });
+		throw new Error("API_KEY_SCOPE_FORBIDDEN");
+	}
+
+	request.user = { id: user.id, username: user.username };
+	request.authContext = {
+		method: "api_key",
+		scope,
+		apiKeyId: keyRow.id,
+	};
+
+	await db
+		.update(apiKeys)
+		.set({ lastUsedAt: new Date(), updatedAt: new Date() })
+		.where(and(eq(apiKeys.id, keyRow.id), eq(apiKeys.userId, user.id)));
+
+	return true;
+}
+
 // =============================================================================
 // Auth Middleware Functions
 // =============================================================================
@@ -94,6 +173,28 @@ export async function optionalAuth(request: FastifyRequest, _reply: FastifyReply
 		return;
 	}
 
+	const bearerToken = getBearerToken(request);
+	if (bearerToken?.startsWith("ma_")) {
+		const keyHash = hashApiKeyToken(bearerToken);
+		const [keyRow] = await db
+			.select()
+			.from(apiKeys)
+			.where(and(eq(apiKeys.keyHash, keyHash), eq(apiKeys.isActive, true)));
+		if (!keyRow) return;
+		if (keyRow.expiresAt && keyRow.expiresAt.getTime() <= Date.now()) return;
+
+		const [userByKey] = await db.select().from(users).where(eq(users.id, keyRow.userId));
+		if (userByKey?.isActive) {
+			request.user = { id: userByKey.id, username: userByKey.username };
+			request.authContext = {
+				method: "api_key",
+				scope: keyRow.scope === "read" ? "read" : "write",
+				apiKeyId: keyRow.id,
+			};
+		}
+		return;
+	}
+
 	const token = request.cookies.access_token;
 	if (!token) {
 		return;
@@ -107,6 +208,10 @@ export async function optionalAuth(request: FastifyRequest, _reply: FastifyReply
 				id: user.id,
 				username: user.username,
 			};
+			request.authContext = {
+				method: "session",
+				scope: "write",
+			};
 		}
 	} catch {
 		// Invalid token, continue as anonymous
@@ -121,6 +226,10 @@ export async function requireAuth(request: FastifyRequest, reply: FastifyReply)
 		return;
 	}
 
+	if (await tryApiKeyAuth(request, reply)) {
+		return;
+	}
+
 	const token = request.cookies.access_token;
 	if (!token) {
 		reply.status(401).send({ error: "Authentication required", code: "AUTH_REQUIRED" });
@@ -145,11 +254,20 @@ export async function requireAuth(request: FastifyRequest, reply: FastifyReply)
 			id: user.id,
 			username: user.username,
 		};
+		request.authContext = {
+			method: "session",
+			scope: "write",
+		};
 	} catch (err: unknown) {
 		// Re-throw our own errors
 		if (
 			err instanceof Error &&
-			(err.message === "AUTH_REQUIRED" || err.message === "USER_NOT_FOUND" || err.message === "ACCOUNT_DISABLED")
+			(err.message === "AUTH_REQUIRED" ||
+				err.message === "USER_NOT_FOUND" ||
+				err.message === "ACCOUNT_DISABLED" ||
+				err.message === "INVALID_API_KEY" ||
+				err.message === "API_KEY_EXPIRED" ||
+				err.message === "API_KEY_SCOPE_FORBIDDEN")
 		) {
 			throw err;
 		}

backend/src/plugins/env.ts

@@ -14,6 +14,10 @@ const EnvSchema = z.object({
 		.default("3000"),
 	CORS_ORIGINS: z.string().default("http://localhost:5173,http://localhost:4173"),
 	LOG_LEVEL: z.string().default("info"),
+	OPENAPI_DOCS_ENABLED: z
+		.string()
+		.transform((v) => v === "true")
+		.optional(),
 
 	// ==========================================================================
 	// Auth Configuration
@@ -69,10 +73,13 @@ const EnvSchema = z.object({
 	OIDC_PROVIDER_NAME: z.string().default("SSO"), // Display name for UI button
 });
 
-export type Env = z.infer<typeof EnvSchema>;
+type ParsedEnv = z.infer<typeof EnvSchema>;
+export type Env = ParsedEnv & {
+	OPENAPI_DOCS_ENABLED: boolean;
+};
 
 // Parse and validate
-let parsed: z.infer<typeof EnvSchema>;
+let parsed: ParsedEnv;
 try {
 	parsed = EnvSchema.parse(process.env);
 } catch (err) {
@@ -154,4 +161,8 @@ if (parsed.REGISTRATION_ENABLED && !parsed.FORM_LOGIN_ENABLED) {
 	);
 }
 
-export const env = parsed;
+export const env: Env = {
+	...parsed,
+	// Docs UI/spec are enabled in non-production by default.
+	OPENAPI_DOCS_ENABLED: parsed.OPENAPI_DOCS_ENABLED ?? parsed.NODE_ENV !== "production",
+};

backend/src/routes/api-keys.ts

@@ -0,0 +1,302 @@
+import { randomBytes } from "node:crypto";
+import { and, desc, eq } from "drizzle-orm";
+import type { FastifyInstance } from "fastify";
+import { z } from "zod";
+import { db } from "../db/client.js";
+import { apiKeys } from "../db/schema.js";
+import { hashApiKeyToken, requireAuth } from "../plugins/auth.js";
+import { env } from "../plugins/env.js";
+import type { AuthUser } from "../types/fastify.js";
+
+const createApiKeySchema = z.object({
+	name: z.string().trim().min(3).max(100),
+	scope: z.enum(["read", "write"]).default("write"),
+	expiresInDays: z.number().int().min(1).max(3650).optional(),
+});
+
+const idParamSchema = z.object({
+	id: z.string().regex(/^\d+$/),
+});
+
+const protectedEndpointSecurity: ReadonlyArray<Record<string, readonly string[]>> = [
+	{ bearerAuth: [] },
+	{ cookieAuth: [] },
+];
+const genericErrorSchema = {
+	type: "object",
+	properties: {
+		error: { type: "string" },
+		code: { type: "string" },
+	},
+};
+
+const apiKeyMetadataSchema = {
+	type: "object",
+	properties: {
+		id: { type: "number" },
+		name: { type: "string" },
+		tokenPrefix: { type: "string" },
+		scope: { type: "string", enum: ["read", "write"] },
+		isActive: { type: "boolean" },
+		lastUsedAt: { type: ["string", "null"], format: "date-time" },
+		expiresAt: { type: ["string", "null"], format: "date-time" },
+		createdAt: { type: ["string", "null"], format: "date-time" },
+		updatedAt: { type: ["string", "null"], format: "date-time" },
+	},
+};
+
+function normalizeDateTime(value: unknown): string | null {
+	if (value == null) {
+		return null;
+	}
+
+	if (value instanceof Date) {
+		return Number.isNaN(value.getTime()) ? null : value.toISOString();
+	}
+
+	if (typeof value === "number") {
+		const timestampMs = value < 1_000_000_000_000 ? value * 1000 : value;
+		const date = new Date(timestampMs);
+		return Number.isNaN(date.getTime()) ? null : date.toISOString();
+	}
+
+	if (typeof value === "string") {
+		const date = new Date(value);
+		return Number.isNaN(date.getTime()) ? null : date.toISOString();
+	}
+
+	return null;
+}
+
+function serializeApiKeyMetadata<
+	T extends {
+		id: number;
+		name: string;
+		tokenPrefix: string;
+		scope: string;
+		isActive: boolean;
+		lastUsedAt: unknown;
+		expiresAt: unknown;
+		createdAt: unknown;
+		updatedAt: unknown;
+	},
+>(key: T) {
+	return {
+		id: key.id,
+		name: key.name,
+		tokenPrefix: key.tokenPrefix,
+		scope: key.scope,
+		isActive: key.isActive,
+		lastUsedAt: normalizeDateTime(key.lastUsedAt),
+		expiresAt: normalizeDateTime(key.expiresAt),
+		createdAt: normalizeDateTime(key.createdAt),
+		updatedAt: normalizeDateTime(key.updatedAt),
+	};
+}
+
+export async function apiKeyRoutes(app: FastifyInstance) {
+	app.addHook("preHandler", requireAuth);
+
+	app.get(
+		"/auth/api-keys",
+		{
+			schema: {
+				tags: ["api-keys"],
+				summary: "List API keys for the current user",
+				description: "Returns API key metadata. Raw API key tokens are never returned.",
+				security: protectedEndpointSecurity,
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							keys: {
+								type: "array",
+								items: apiKeyMetadataSchema,
+							},
+						},
+					},
+					400: genericErrorSchema,
+					401: genericErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			if (!env.AUTH_ENABLED) {
+				return reply.status(400).send({ error: "API keys are unavailable when auth is disabled" });
+			}
+
+			const authUser = request.user as unknown as AuthUser | null;
+			if (!authUser) {
+				return reply.status(401).send({ error: "User not authenticated", code: "AUTH_REQUIRED" });
+			}
+
+			const keys = await db
+				.select({
+					id: apiKeys.id,
+					name: apiKeys.name,
+					tokenPrefix: apiKeys.tokenPrefix,
+					scope: apiKeys.scope,
+					isActive: apiKeys.isActive,
+					lastUsedAt: apiKeys.lastUsedAt,
+					expiresAt: apiKeys.expiresAt,
+					createdAt: apiKeys.createdAt,
+					updatedAt: apiKeys.updatedAt,
+				})
+				.from(apiKeys)
+				.where(eq(apiKeys.userId, authUser.id))
+				.orderBy(desc(apiKeys.createdAt));
+
+			return { keys: keys.map(serializeApiKeyMetadata) };
+		}
+	);
+
+	app.post<{ Body: z.infer<typeof createApiKeySchema> }>(
+		"/auth/api-keys",
+		{
+			schema: {
+				tags: ["api-keys"],
+				summary: "Create and rotate API key",
+				description:
+					"Creates a new API key and deactivates previously active API keys for the current user. The new token is returned only once.",
+				security: protectedEndpointSecurity,
+				body: {
+					type: "object",
+					required: ["name"],
+					properties: {
+						name: { type: "string", minLength: 3, maxLength: 100 },
+						scope: { type: "string", enum: ["read", "write"], default: "write" },
+						expiresInDays: { type: "number", minimum: 1, maximum: 3650 },
+					},
+					example: {
+						name: "Home Assistant integration",
+						scope: "write",
+						expiresInDays: 365,
+					},
+				},
+				response: {
+					201: {
+						type: "object",
+						properties: {
+							key: apiKeyMetadataSchema,
+							token: { type: "string" },
+							note: { type: "string" },
+						},
+					},
+					400: { anyOf: [genericErrorSchema, { type: "object" }] },
+					401: genericErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			if (!env.AUTH_ENABLED) {
+				return reply.status(400).send({ error: "API keys are unavailable when auth is disabled" });
+			}
+
+			const parsed = createApiKeySchema.safeParse(request.body);
+			if (!parsed.success) {
+				return reply.status(400).send(parsed.error.format());
+			}
+
+			const authUser = request.user as unknown as AuthUser | null;
+			if (!authUser) {
+				return reply.status(401).send({ error: "User not authenticated", code: "AUTH_REQUIRED" });
+			}
+
+			const { name, scope, expiresInDays } = parsed.data;
+			const rawToken = `ma_${randomBytes(32).toString("hex")}`;
+			const tokenPrefix = `${rawToken.slice(0, 12)}...`;
+			const keyHash = hashApiKeyToken(rawToken);
+			const expiresAt = expiresInDays ? new Date(Date.now() + expiresInDays * 24 * 60 * 60 * 1000) : null;
+
+			// Keep a single active key per user: creating a new key invalidates old ones.
+			await db
+				.update(apiKeys)
+				.set({ isActive: false, updatedAt: new Date() })
+				.where(and(eq(apiKeys.userId, authUser.id), eq(apiKeys.isActive, true)));
+
+			const [created] = await db
+				.insert(apiKeys)
+				.values({
+					userId: authUser.id,
+					name,
+					keyHash,
+					tokenPrefix,
+					scope,
+					expiresAt,
+				})
+				.returning({
+					id: apiKeys.id,
+					name: apiKeys.name,
+					tokenPrefix: apiKeys.tokenPrefix,
+					scope: apiKeys.scope,
+					isActive: apiKeys.isActive,
+					lastUsedAt: apiKeys.lastUsedAt,
+					expiresAt: apiKeys.expiresAt,
+					createdAt: apiKeys.createdAt,
+					updatedAt: apiKeys.updatedAt,
+				});
+
+			return reply.status(201).send({
+				key: serializeApiKeyMetadata(created),
+				token: rawToken,
+				note: "Store this token now. It cannot be retrieved again.",
+			});
+		}
+	);
+
+	app.delete<{ Params: { id: string } }>(
+		"/auth/api-keys/:id",
+		{
+			schema: {
+				tags: ["api-keys"],
+				summary: "Deactivate API key",
+				description: "Deactivates one API key belonging to the current user.",
+				security: protectedEndpointSecurity,
+				params: {
+					type: "object",
+					required: ["id"],
+					properties: {
+						id: { type: "string", pattern: "^\\d+$" },
+					},
+				},
+				response: {
+					204: { type: "null" },
+					400: { anyOf: [genericErrorSchema, { type: "object" }] },
+					401: genericErrorSchema,
+					404: genericErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			if (!env.AUTH_ENABLED) {
+				return reply.status(400).send({ error: "API keys are unavailable when auth is disabled" });
+			}
+
+			const parsedParams = idParamSchema.safeParse(request.params);
+			if (!parsedParams.success) {
+				return reply.status(400).send(parsedParams.error.format());
+			}
+
+			const authUser = request.user as unknown as AuthUser | null;
+			if (!authUser) {
+				return reply.status(401).send({ error: "User not authenticated", code: "AUTH_REQUIRED" });
+			}
+
+			const keyId = Number(parsedParams.data.id);
+			const [existing] = await db
+				.select({ id: apiKeys.id, userId: apiKeys.userId })
+				.from(apiKeys)
+				.where(and(eq(apiKeys.id, keyId), eq(apiKeys.userId, authUser.id)));
+			if (!existing) {
+				return reply.status(404).send({ error: "API key not found", code: "API_KEY_NOT_FOUND" });
+			}
+
+			await db
+				.update(apiKeys)
+				.set({ isActive: false, updatedAt: new Date() })
+				.where(and(eq(apiKeys.id, keyId), eq(apiKeys.userId, authUser.id)));
+
+			return reply.status(204).send();
+		}
+	);
+}

backend/src/routes/auth.ts

@@ -85,6 +85,38 @@ const updateProfileSchema = z.object({
 		.optional(),
 });
 
+const authEndpointSecurity: ReadonlyArray<Record<string, readonly string[]>> = [{ bearerAuth: [] }, { cookieAuth: [] }];
+const authErrorSchema = {
+	type: "object",
+	properties: {
+		error: { type: "string" },
+		code: { type: "string" },
+	},
+};
+
+function normalizeDateTime(value: unknown): string | null {
+	if (value == null) {
+		return null;
+	}
+
+	if (value instanceof Date) {
+		return Number.isNaN(value.getTime()) ? null : value.toISOString();
+	}
+
+	if (typeof value === "number") {
+		const timestampMs = value < 1_000_000_000_000 ? value * 1000 : value;
+		const date = new Date(timestampMs);
+		return Number.isNaN(date.getTime()) ? null : date.toISOString();
+	}
+
+	if (typeof value === "string") {
+		const date = new Date(value);
+		return Number.isNaN(date.getTime()) ? null : date.toISOString();
+	}
+
+	return null;
+}
+
 // =============================================================================
 // Auth Routes
 // =============================================================================
@@ -99,9 +131,33 @@ export async function authRoutes(app: FastifyInstance) {
 	// GET /auth/state - Public auth state (needed before login)
 	// Exempt from rate limit - lightweight state check called frequently
 	// ---------------------------------------------------------------------------
-	app.get("/auth/state", { config: { rateLimit: false } }, async () => {
-		return getAuthState();
-	});
+	app.get(
+		"/auth/state",
+		{
+			config: { rateLimit: false },
+			schema: {
+				tags: ["auth"],
+				summary: "Get authentication state",
+				description: "Returns auth and login mode state before user login.",
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							authEnabled: { type: "boolean" },
+							registrationEnabled: { type: "boolean" },
+							formLoginEnabled: { type: "boolean" },
+							oidcEnabled: { type: "boolean" },
+							hasUsers: { type: "boolean" },
+							oidcProviderName: { type: "string" },
+						},
+					},
+				},
+			},
+		},
+		async () => {
+			return getAuthState();
+		}
+	);
 
 	// ---------------------------------------------------------------------------
 	// POST /auth/register - User registration
@@ -110,6 +166,40 @@ export async function authRoutes(app: FastifyInstance) {
 		"/auth/register",
 		{
 			config: { rateLimit: sensitiveRateLimitConfig },
+			schema: {
+				tags: ["auth"],
+				summary: "Register local user",
+				body: {
+					type: "object",
+					required: ["username", "password"],
+					properties: {
+						username: { type: "string", minLength: 3, maxLength: 50 },
+						password: { type: "string", minLength: 8, maxLength: 128 },
+					},
+					example: {
+						username: "daniel",
+						password: "correct-horse-battery-staple",
+					},
+				},
+				response: {
+					201: {
+						type: "object",
+						properties: {
+							ok: { type: "boolean" },
+							user: {
+								type: "object",
+								properties: {
+									id: { type: "number" },
+									username: { type: "string" },
+								},
+							},
+							message: { type: "string" },
+						},
+					},
+					400: authErrorSchema,
+					409: authErrorSchema,
+				},
+			},
 		},
 		async (request, reply) => {
 			// Check auth state
@@ -177,6 +267,42 @@ export async function authRoutes(app: FastifyInstance) {
 		"/auth/login",
 		{
 			config: { rateLimit: sensitiveRateLimitConfig },
+			schema: {
+				tags: ["auth"],
+				summary: "Login with username and password",
+				body: {
+					type: "object",
+					required: ["username", "password"],
+					properties: {
+						username: { type: "string" },
+						password: { type: "string" },
+						rememberMe: { type: "boolean" },
+					},
+					example: {
+						username: "daniel",
+						password: "correct-horse-battery-staple",
+						rememberMe: true,
+					},
+				},
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							ok: { type: "boolean" },
+							user: {
+								type: "object",
+								properties: {
+									id: { type: "number" },
+									username: { type: "string" },
+									avatarUrl: { type: ["string", "null"] },
+								},
+							},
+						},
+					},
+					400: authErrorSchema,
+					401: authErrorSchema,
+				},
+			},
 		},
 		async (request, reply) => {
 			const state = await getAuthState();
@@ -281,6 +407,15 @@ export async function authRoutes(app: FastifyInstance) {
 		"/auth/refresh",
 		{
 			config: { rateLimit: authRateLimitConfig },
+			schema: {
+				tags: ["auth"],
+				summary: "Refresh access token",
+				description: "Requires refresh token cookie context.",
+				response: {
+					200: { type: "object", properties: { ok: { type: "boolean" } } },
+					401: authErrorSchema,
+				},
+			},
 		},
 		async (request, reply) => {
 			const refreshTokenCookie = request.cookies.refresh_token;
@@ -350,6 +485,13 @@ export async function authRoutes(app: FastifyInstance) {
 		"/auth/logout",
 		{
 			config: { rateLimit: authRateLimitConfig },
+			schema: {
+				tags: ["auth"],
+				summary: "Logout and clear auth cookies",
+				response: {
+					200: { type: "object", properties: { ok: { type: "boolean" } } },
+				},
+			},
 		},
 		async (request, reply) => {
 			const refreshTokenCookie = request.cookies.refresh_token;
@@ -375,26 +517,56 @@ export async function authRoutes(app: FastifyInstance) {
 	// ---------------------------------------------------------------------------
 	// GET /auth/me - Get current user profile
 	// ---------------------------------------------------------------------------
-	app.get("/auth/me", { preHandler: requireAuth }, async (request, reply) => {
-		const authUser = request.user as unknown as AuthUser | null;
-		if (!authUser) {
-			return reply.status(401).send({ error: "Not authenticated" });
-		}
+	app.get(
+		"/auth/me",
+		{
+			preHandler: requireAuth,
+			schema: {
+				tags: ["auth"],
+				summary: "Get current user profile",
+				security: authEndpointSecurity,
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							id: { type: "number" },
+							username: { type: "string" },
+							avatarUrl: { type: ["string", "null"] },
+							authProvider: { type: "string" },
+							createdAt: { type: "string", format: "date-time" },
+							lastLoginAt: { type: ["string", "null"], format: "date-time" },
+						},
+					},
+					401: authErrorSchema,
+					404: authErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			const authUser = request.user as unknown as AuthUser | null;
+			if (!authUser) {
+				return reply.status(401).send({ error: "Not authenticated" });
+			}
 
-		const [user] = await db.select().from(users).where(eq(users.id, authUser.id));
-		if (!user) {
-			return reply.status(404).send({ error: "User not found" });
-		}
+			const [user] = await db.select().from(users).where(eq(users.id, authUser.id));
+			if (!user) {
+				return reply.status(404).send({ error: "User not found" });
+			}
 
-		return {
-			id: user.id,
-			username: user.username,
-			avatarUrl: user.avatarUrl,
-			authProvider: user.authProvider,
-			createdAt: user.createdAt,
-			lastLoginAt: user.lastLoginAt,
-		};
-	});
+			const createdAt =
+				normalizeDateTime(user.createdAt) ?? normalizeDateTime(user.updatedAt) ?? new Date(0).toISOString();
+			const lastLoginAt = normalizeDateTime(user.lastLoginAt);
+
+			return {
+				id: user.id,
+				username: user.username,
+				avatarUrl: user.avatarUrl,
+				authProvider: user.authProvider ?? "local",
+				createdAt,
+				lastLoginAt,
+			};
+		}
+	);
 
 	// ---------------------------------------------------------------------------
 	// PUT /auth/me - Update current user profile
@@ -404,6 +576,34 @@ export async function authRoutes(app: FastifyInstance) {
 		{
 			preHandler: requireAuth,
 			config: { rateLimit: authRateLimitConfig },
+			schema: {
+				tags: ["auth"],
+				summary: "Update current user profile",
+				security: authEndpointSecurity,
+				body: {
+					type: "object",
+					properties: {
+						currentPassword: { type: "string" },
+						newPassword: { type: "string", minLength: 8, maxLength: 128 },
+					},
+					example: {
+						currentPassword: "current-password",
+						newPassword: "new-strong-password",
+					},
+				},
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							ok: { type: "boolean" },
+							message: { type: "string" },
+						},
+					},
+					400: authErrorSchema,
+					401: authErrorSchema,
+					404: authErrorSchema,
+				},
+			},
 		},
 		async (request, reply) => {
 			const authUser = request.user as unknown as AuthUser | null;
@@ -462,6 +662,24 @@ export async function authRoutes(app: FastifyInstance) {
 		{
 			preHandler: requireAuth,
 			config: { rateLimit: authRateLimitConfig },
+			schema: {
+				tags: ["auth"],
+				summary: "Upload user avatar",
+				description: "Uploads and optimizes a profile image using multipart/form-data.",
+				security: authEndpointSecurity,
+				consumes: ["multipart/form-data"],
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							ok: { type: "boolean" },
+							avatarUrl: { type: "string" },
+						},
+					},
+					400: authErrorSchema,
+					401: authErrorSchema,
+				},
+			},
 		},
 		async (request, reply) => {
 			const authUser = request.user as unknown as AuthUser | null;
@@ -517,6 +735,16 @@ export async function authRoutes(app: FastifyInstance) {
 		{
 			preHandler: requireAuth,
 			config: { rateLimit: authRateLimitConfig },
+			schema: {
+				tags: ["auth"],
+				summary: "Delete user avatar",
+				security: authEndpointSecurity,
+				response: {
+					200: { type: "object", properties: { ok: { type: "boolean" } } },
+					401: authErrorSchema,
+					404: authErrorSchema,
+				},
+			},
 		},
 		async (request, reply) => {
 			const authUser = request.user as unknown as AuthUser | null;
@@ -547,6 +775,22 @@ export async function authRoutes(app: FastifyInstance) {
 		{
 			preHandler: requireAuth,
 			config: { rateLimit: sensitiveRateLimitConfig },
+			schema: {
+				tags: ["auth"],
+				summary: "Delete current user account",
+				description: "Deletes the current account and related data (cascade delete).",
+				security: authEndpointSecurity,
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							ok: { type: "boolean" },
+							message: { type: "string" },
+						},
+					},
+					401: authErrorSchema,
+				},
+			},
 		},
 		async (request, reply) => {
 			const authUser = request.user as unknown as AuthUser | null;

backend/src/routes/doses.ts

@@ -2,11 +2,23 @@ import { and, eq } from "drizzle-orm";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 import { db } from "../db/client.js";
-import { doseTracking, medications, shareTokens } from "../db/schema.js";
+import { doseTracking, medications, shareTokens, userSettings } from "../db/schema.js";
 import { getAnonymousUserId, requireAuth } from "../plugins/auth.js";
 import { env } from "../plugins/env.js";
+import { computeMedicationCurrentStock } from "../services/current-stock.js";
 import type { AuthUser } from "../types/fastify.js";
-import { parseIntakesJson, parseTakenByJson, personTakesMedication } from "../utils/scheduler-utils.js";
+import {
+	applyOpenApiRouteStandards,
+	genericErrorSchema,
+	tokenParamsSchema,
+	validationErrorSchema,
+} from "../utils/openapi-route-standards.js";
+import {
+	parseIntakesJson,
+	parseLocalDateTime,
+	parseTakenByJson,
+	personTakesMedication,
+} from "../utils/scheduler-utils.js";
 
 // =============================================================================
 // Validation Schemas
@@ -23,8 +35,32 @@ const dismissDosesSchema = z.object({
 	doseIds: z.array(z.string().min(1)).min(1, "At least one doseId is required"),
 });
 
+const protectedEndpointSecurity: ReadonlyArray<Record<string, readonly string[]>> = [
+	{ bearerAuth: [] },
+	{ cookieAuth: [] },
+];
+
 const doseIdPattern = /^(\d+)-(\d+)-(\d+)(?:-(.+))?$/;
 
+const doseReadResponseSchema = {
+	type: "object",
+	properties: {
+		doses: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					doseId: { type: "string" },
+					takenAt: { type: "number" },
+					markedBy: { type: ["string", "null"] },
+					takenSource: { type: "string" },
+					dismissed: { type: "boolean" },
+				},
+			},
+		},
+	},
+} as const;
+
 function maskToken(token: string): string {
 	if (token.length <= 8) return token;
 	return `${token.slice(0, 4)}...${token.slice(-4)}`;
@@ -125,43 +161,145 @@ async function validateShareDoseId(share: typeof shareTokens.$inferSelect, doseI
 	}
 
 	if (!parsedDose.personSuffix) {
-		return true;
+		return intake.takenBy === null;
 	}
 
 	return expectedPersons.includes(parsedDose.personSuffix);
 }
 
+async function isDoseOutOfStock(options: {
+	userId: number;
+	doseId: string;
+	stockCalculationMode: "automatic" | "manual";
+}): Promise<boolean> {
+	const parsedDose = parseDoseId(options.doseId);
+	if (!parsedDose) {
+		return false;
+	}
+
+	const [medication] = await db
+		.select()
+		.from(medications)
+		.where(and(eq(medications.id, parsedDose.medicationId), eq(medications.userId, options.userId)));
+
+	if (!medication) {
+		return false;
+	}
+
+	const intakes = parseIntakesJson(
+		medication.intakesJson,
+		{ usageJson: medication.usageJson, everyJson: medication.everyJson, startJson: medication.startJson },
+		medication.intakeRemindersEnabled ?? false
+	);
+	const intake = intakes[parsedDose.intakeIndex];
+
+	const scheduledOccurrenceMs = intake
+		? (() => {
+				const doseDate = new Date(parsedDose.timestampMs);
+				const intakeStart = parseLocalDateTime(intake.start);
+				return new Date(
+					doseDate.getFullYear(),
+					doseDate.getMonth(),
+					doseDate.getDate(),
+					intakeStart.getHours(),
+					intakeStart.getMinutes(),
+					intakeStart.getSeconds(),
+					intakeStart.getMilliseconds()
+				).getTime();
+			})()
+		: parsedDose.timestampMs;
+
+	const doses = await db.select().from(doseTracking).where(eq(doseTracking.userId, options.userId));
+	const stockBeforeDoseMs = Math.max(0, scheduledOccurrenceMs - 1);
+	return (
+		computeMedicationCurrentStock({
+			medication,
+			doses,
+			stockCalculationMode: options.stockCalculationMode,
+			nowMs: stockBeforeDoseMs,
+		}) <= 0
+	);
+}
+
 // =============================================================================
 // Dose Tracking Routes
 // =============================================================================
 export async function doseRoutes(app: FastifyInstance) {
+	applyOpenApiRouteStandards(app, {
+		tag: "doses",
+		protectedByDefault: false,
+		protectedPaths: [/^\/doses\/taken$/, /^\/doses\/taken\/:doseId$/, /^\/doses\/dismiss$/],
+	});
+
 	// ---------------------------------------------------------------------------
 	// GET /doses/taken - PROTECTED: Get all taken doses for the user
 	// Suppress request logs — polled every 5s by frontend
 	// ---------------------------------------------------------------------------
-	app.get("/doses/taken", { preHandler: requireAuth, logLevel: "warn" }, async (request, reply) => {
-		const userId = await getUserId(request, reply);
+	app.get(
+		"/doses/taken",
+		{
+			preHandler: requireAuth,
+			logLevel: "warn",
+			schema: {
+				tags: ["doses"],
+				security: protectedEndpointSecurity,
+				response: {
+					200: doseReadResponseSchema,
+					401: genericErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			const userId = await getUserId(request, reply);
 
-		// Get all taken doses for this user (no time limit)
-		const doses = await db.select().from(doseTracking).where(eq(doseTracking.userId, userId));
+			// Get all taken doses for this user (no time limit)
+			const doses = await db.select().from(doseTracking).where(eq(doseTracking.userId, userId));
 
-		return {
-			doses: doses.map((d) => ({
-				doseId: d.doseId,
-				takenAt: d.takenAt?.getTime() ?? Date.now(),
-				markedBy: d.markedBy,
-				takenSource: d.takenSource ?? "manual",
-				dismissed: d.dismissed ?? false,
-			})),
-		};
-	});
+			return {
+				doses: doses.map((d) => ({
+					doseId: d.doseId,
+					takenAt: d.takenAt?.getTime() ?? Date.now(),
+					markedBy: d.markedBy,
+					takenSource: d.takenSource ?? "manual",
+					dismissed: d.dismissed ?? false,
+				})),
+			};
+		}
+	);
 
 	// ---------------------------------------------------------------------------
 	// POST /doses/taken - PROTECTED: Mark a dose as taken
 	// ---------------------------------------------------------------------------
 	app.post<{ Body: z.infer<typeof markDoseSchema> }>(
 		"/doses/taken",
-		{ preHandler: requireAuth },
+		{
+			preHandler: requireAuth,
+			schema: {
+				tags: ["doses"],
+				security: protectedEndpointSecurity,
+				body: {
+					type: "object",
+					properties: {
+						doseId: { type: "string" },
+					},
+					example: {
+						doseId: "1:2026-03-11T08:00:00.000Z:Daniel",
+					},
+				},
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							success: { type: "boolean" },
+							message: { type: "string" },
+						},
+					},
+					400: { anyOf: [genericErrorSchema, validationErrorSchema] },
+					409: genericErrorSchema,
+					401: genericErrorSchema,
+				},
+			},
+		},
 		async (request, reply) => {
 			const userId = await getUserId(request, reply);
 
@@ -184,6 +322,16 @@ export async function doseRoutes(app: FastifyInstance) {
 				return { success: true, message: "Already marked" };
 			}
 
+			const [settings] = await db.select().from(userSettings).where(eq(userSettings.userId, userId));
+			const outOfStock = await isDoseOutOfStock({
+				userId,
+				doseId,
+				stockCalculationMode: (settings?.stockCalculationMode as "automatic" | "manual") ?? "automatic",
+			});
+			if (outOfStock) {
+				return reply.status(409).send({ error: "Medication is out of stock", code: "OUT_OF_STOCK" });
+			}
+
 			// Insert new record
 			await db.insert(doseTracking).values({
 				userId,
@@ -201,7 +349,24 @@ export async function doseRoutes(app: FastifyInstance) {
 	// ---------------------------------------------------------------------------
 	app.delete<{ Params: { doseId: string } }>(
 		"/doses/taken/:doseId",
-		{ preHandler: requireAuth },
+		{
+			preHandler: requireAuth,
+			schema: {
+				tags: ["doses"],
+				security: protectedEndpointSecurity,
+				params: {
+					type: "object",
+					required: ["doseId"],
+					properties: {
+						doseId: { type: "string", minLength: 1 },
+					},
+				},
+				response: {
+					200: { type: "object", properties: { success: { type: "boolean" } } },
+					401: genericErrorSchema,
+				},
+			},
+		},
 		async (request, reply) => {
 			const userId = await getUserId(request, reply);
 
@@ -230,7 +395,33 @@ export async function doseRoutes(app: FastifyInstance) {
 	// ---------------------------------------------------------------------------
 	app.post<{ Body: z.infer<typeof dismissDosesSchema> }>(
 		"/doses/dismiss",
-		{ preHandler: requireAuth },
+		{
+			preHandler: requireAuth,
+			schema: {
+				tags: ["doses"],
+				security: protectedEndpointSecurity,
+				body: {
+					type: "object",
+					properties: {
+						doseIds: { type: "array", items: { type: "string" } },
+					},
+					example: {
+						doseIds: ["1:2026-03-11T08:00:00.000Z:Daniel", "1:2026-03-11T20:00:00.000Z:Daniel"],
+					},
+				},
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							success: { type: "boolean" },
+							dismissedCount: { type: "integer" },
+						},
+					},
+					400: { anyOf: [genericErrorSchema, validationErrorSchema] },
+					401: genericErrorSchema,
+				},
+			},
+		},
 		async (request, reply) => {
 			const userId = await getUserId(request, reply);
 
@@ -267,6 +458,7 @@ export async function doseRoutes(app: FastifyInstance) {
 						userId,
 						doseId,
 						markedBy: null,
+						takenAt: new Date(0),
 						dismissed: true,
 					});
 					dismissedCount++;
@@ -280,61 +472,123 @@ export async function doseRoutes(app: FastifyInstance) {
 	// ---------------------------------------------------------------------------
 	// DELETE /doses/dismiss - PROTECTED: Clear all dismissed doses (un-dismiss)
 	// ---------------------------------------------------------------------------
-	app.delete("/doses/dismiss", { preHandler: requireAuth }, async (request, reply) => {
-		const userId = await getUserId(request, reply);
+	app.delete(
+		"/doses/dismiss",
+		{
+			preHandler: requireAuth,
+			schema: {
+				tags: ["doses"],
+				security: protectedEndpointSecurity,
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							success: { type: "boolean" },
+							clearedCount: { type: "integer" },
+						},
+					},
+					401: genericErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			const userId = await getUserId(request, reply);
 
-		// Delete all dismissed-only records (not taken ones)
-		// For taken+dismissed, just remove the dismissed flag
-		const dismissed = await db
-			.select()
-			.from(doseTracking)
-			.where(and(eq(doseTracking.userId, userId), eq(doseTracking.dismissed, true)));
+			// Delete all dismissed-only records (not taken ones)
+			// For taken+dismissed, just remove the dismissed flag
+			const dismissed = await db
+				.select()
+				.from(doseTracking)
+				.where(and(eq(doseTracking.userId, userId), eq(doseTracking.dismissed, true)));
 
-		for (const d of dismissed) {
-			if (d.markedBy !== null || d.takenAt) {
-				// This was also marked as taken - just remove dismissed flag
-				await db.update(doseTracking).set({ dismissed: false }).where(eq(doseTracking.id, d.id));
-			} else {
-				// This was only dismissed - delete it
-				await db.delete(doseTracking).where(eq(doseTracking.id, d.id));
+			for (const d of dismissed) {
+				const hasRealTakenTimestamp = d.takenAt instanceof Date ? d.takenAt.getTime() > 0 : Boolean(d.takenAt);
+
+				if (d.markedBy !== null || hasRealTakenTimestamp) {
+					// This was also marked as taken - just remove dismissed flag
+					await db.update(doseTracking).set({ dismissed: false }).where(eq(doseTracking.id, d.id));
+				} else {
+					// This was only dismissed - delete it
+					await db.delete(doseTracking).where(eq(doseTracking.id, d.id));
+				}
 			}
-		}
 
-		return { success: true, clearedCount: dismissed.length };
-	});
+			return { success: true, clearedCount: dismissed.length };
+		}
+	);
 
 	// ---------------------------------------------------------------------------
 	// GET /share/:token/doses - PUBLIC: Get taken doses for a share link
 	// Suppress request logs — polled every 5s by SharedSchedule
 	// ---------------------------------------------------------------------------
-	app.get<{ Params: { token: string } }>("/share/:token/doses", { logLevel: "warn" }, async (request, reply) => {
-		const { token } = request.params;
+	app.get<{ Params: { token: string } }>(
+		"/share/:token/doses",
+		{
+			schema: {
+				params: tokenParamsSchema,
+				response: {
+					200: doseReadResponseSchema,
+					404: genericErrorSchema,
+				},
+			},
+			logLevel: "warn",
+			config: {
+				rateLimit: {
+					max: 60,
+					timeWindow: "1 minute",
+					errorResponseBuilder: () => ({ error: "rate_limited" }),
+				},
+			},
+		},
+		async (request, reply) => {
+			const { token } = request.params;
 
-		const { share, reason } = await getActiveShareToken(token);
-		if (!share) {
-			request.log.warn(`[ShareDose] Rejected read for token ${maskToken(token)} (reason=${reason})`);
-			return reply.notFound("Share link not found");
+			const { share, reason } = await getActiveShareToken(token);
+			if (!share) {
+				request.log.warn(`[ShareDose] Rejected read for token ${maskToken(token)} (reason=${reason})`);
+				return reply.notFound("Share link not found");
+			}
+
+			// Get all taken doses for this user (no time limit)
+			const doses = await db.select().from(doseTracking).where(eq(doseTracking.userId, share.userId));
+
+			return {
+				doses: doses.map((d) => ({
+					doseId: d.doseId,
+					takenAt: d.takenAt?.getTime() ?? Date.now(),
+					markedBy: d.markedBy,
+					takenSource: d.takenSource ?? "manual",
+					dismissed: d.dismissed ?? false,
+				})),
+			};
 		}
-
-		// Get all taken doses for this user (no time limit)
-		const doses = await db.select().from(doseTracking).where(eq(doseTracking.userId, share.userId));
-
-		return {
-			doses: doses.map((d) => ({
-				doseId: d.doseId,
-				takenAt: d.takenAt?.getTime() ?? Date.now(),
-				markedBy: d.markedBy,
-				takenSource: d.takenSource ?? "manual",
-				dismissed: d.dismissed ?? false,
-			})),
-		};
-	});
+	);
 
 	// ---------------------------------------------------------------------------
 	// POST /share/:token/doses - PUBLIC: Mark a dose as taken via share link
 	// ---------------------------------------------------------------------------
 	app.post<{ Params: { token: string }; Body: z.infer<typeof shareDoseSchema> }>(
 		"/share/:token/doses",
+		{
+			schema: {
+				params: tokenParamsSchema,
+				body: {
+					type: "object",
+					properties: {
+						doseId: { type: "string" },
+					},
+					example: {
+						doseId: "1:2026-03-11T08:00:00.000Z:Daniel",
+					},
+				},
+				response: {
+					200: { type: "object", properties: { success: { type: "boolean" }, message: { type: "string" } } },
+					400: { anyOf: [genericErrorSchema, validationErrorSchema] },
+					409: genericErrorSchema,
+					404: genericErrorSchema,
+				},
+			},
+		},
 		async (request, reply) => {
 			const { token } = request.params;
 
@@ -372,11 +626,27 @@ export async function doseRoutes(app: FastifyInstance) {
 				return { success: true, message: "Already marked" };
 			}
 
-			// Insert new record - marked by the takenBy person
+			const [settings] = await db.select().from(userSettings).where(eq(userSettings.userId, share.userId));
+			const outOfStock = await isDoseOutOfStock({
+				userId: share.userId,
+				doseId,
+				stockCalculationMode: (settings?.stockCalculationMode as "automatic" | "manual") ?? "automatic",
+			});
+			if (outOfStock) {
+				request.log.info(
+					`[ShareDose] Rejected out-of-stock mark request (owner=${share.userId}, takenBy=${share.takenBy}, doseId=${doseId})`
+				);
+				return reply.status(409).send({ error: "Medication is out of stock", code: "OUT_OF_STOCK" });
+			}
+
+			// Insert new record - marked by the shared person, or the concrete intake person for an "all" link.
+			const parsedShareDose = parseDoseId(doseId);
+			const markedBy = share.takenBy === "all" ? (parsedShareDose?.personSuffix ?? share.takenBy) : share.takenBy;
+
 			await db.insert(doseTracking).values({
 				userId: share.userId,
 				doseId,
-				markedBy: share.takenBy, // e.g. "Daniel"
+				markedBy,
 				takenSource: "manual",
 			});
 
@@ -391,40 +661,62 @@ export async function doseRoutes(app: FastifyInstance) {
 	// ---------------------------------------------------------------------------
 	// DELETE /share/:token/doses/:doseId - PUBLIC: Unmark a dose via share link
 	// ---------------------------------------------------------------------------
-	app.delete<{ Params: { token: string; doseId: string } }>("/share/:token/doses/:doseId", async (request, reply) => {
-		const { token, doseId } = request.params;
+	app.delete<{ Params: { token: string; doseId: string } }>(
+		"/share/:token/doses/:doseId",
+		{
+			schema: {
+				params: {
+					type: "object",
+					required: ["token", "doseId"],
+					properties: {
+						token: tokenParamsSchema.properties.token,
+						doseId: { type: "string", minLength: 1 },
+					},
+				},
+				response: {
+					200: { type: "object", properties: { success: { type: "boolean" } } },
+					400: genericErrorSchema,
+					404: genericErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			const { token, doseId } = request.params;
 
-		const { share, reason } = await getActiveShareToken(token);
-		if (!share) {
-			request.log.warn(`[ShareDose] Rejected unmark for token ${maskToken(token)} (reason=${reason})`);
-			return reply.notFound("Share link not found");
+			const { share, reason } = await getActiveShareToken(token);
+			if (!share) {
+				request.log.warn(`[ShareDose] Rejected unmark for token ${maskToken(token)} (reason=${reason})`);
+				return reply.notFound("Share link not found");
+			}
+
+			const isValidShareDoseId = await validateShareDoseId(share, doseId);
+			if (!isValidShareDoseId) {
+				request.log.warn(
+					`[ShareDose] Rejected invalid doseId in unmark request (owner=${share.userId}, takenBy=${share.takenBy}, doseId=${doseId})`
+				);
+				return reply.status(400).send({ error: "Invalid or unauthorized doseId" });
+			}
+
+			// Check if this dose was dismissed
+			const [existing] = await db
+				.select()
+				.from(doseTracking)
+				.where(and(eq(doseTracking.userId, share.userId), eq(doseTracking.doseId, doseId)));
+
+			if (existing?.dismissed) {
+				// Already dismissed - keep the record as-is
+				request.log.debug(`[ShareDose] Unmark ignored for dismissed dose (owner=${share.userId}, doseId=${doseId})`);
+			} else {
+				// Not dismissed - delete the record entirely
+				await db
+					.delete(doseTracking)
+					.where(and(eq(doseTracking.userId, share.userId), eq(doseTracking.doseId, doseId)));
+				request.log.info(
+					`[ShareDose] Dose unmarked via share link (owner=${share.userId}, takenBy=${share.takenBy}, doseId=${doseId})`
+				);
+			}
+
+			return { success: true };
 		}
-
-		const isValidShareDoseId = await validateShareDoseId(share, doseId);
-		if (!isValidShareDoseId) {
-			request.log.warn(
-				`[ShareDose] Rejected invalid doseId in unmark request (owner=${share.userId}, takenBy=${share.takenBy}, doseId=${doseId})`
-			);
-			return reply.status(400).send({ error: "Invalid or unauthorized doseId" });
-		}
-
-		// Check if this dose was dismissed
-		const [existing] = await db
-			.select()
-			.from(doseTracking)
-			.where(and(eq(doseTracking.userId, share.userId), eq(doseTracking.doseId, doseId)));
-
-		if (existing?.dismissed) {
-			// Already dismissed - keep the record as-is
-			request.log.debug(`[ShareDose] Unmark ignored for dismissed dose (owner=${share.userId}, doseId=${doseId})`);
-		} else {
-			// Not dismissed - delete the record entirely
-			await db.delete(doseTracking).where(and(eq(doseTracking.userId, share.userId), eq(doseTracking.doseId, doseId)));
-			request.log.info(
-				`[ShareDose] Dose unmarked via share link (owner=${share.userId}, takenBy=${share.takenBy}, doseId=${doseId})`
-			);
-		}
-
-		return { success: true };
-	});
+	);
 }

backend/src/routes/export.ts

@@ -10,6 +10,12 @@ import { doseTracking, medications, refillHistory, shareTokens, userSettings } f
 import { getAnonymousUserId, requireAuth } from "../plugins/auth.js";
 import { env } from "../plugins/env.js";
 import type { AuthUser } from "../types/fastify.js";
+import {
+	applyOpenApiRouteStandards,
+	genericErrorSchema,
+	validationErrorSchema,
+} from "../utils/openapi-route-standards.js";
+import { normalizePackageType, PACKAGE_TYPES } from "../utils/package-profiles.js";
 import { parseIntakesJson, parseTakenByJson } from "../utils/scheduler-utils.js";
 
 const IMAGES_DIR = resolve(getDataDir(), "images");
@@ -39,7 +45,7 @@ const inventorySchema = z.object({
 	totalPills: z.number().int().nullable().optional(), // For bottle type: total capacity
 	looseTablets: z.number().int().min(0).default(0),
 	stockAdjustment: z.number().int().default(0), // Manual stock correction
-	packageType: z.enum(["blister", "bottle", "tube", "liquid_container"]).default("blister"),
+	packageType: z.enum(PACKAGE_TYPES).default("blister"),
 	packageAmountValue: z.number().int().min(0).default(0),
 	packageAmountUnit: z.enum(["ml", "g"]).default("ml"),
 });
@@ -130,6 +136,7 @@ const settingsExportSchema = z
 		language: z.string().default("en"),
 		stockCalculationMode: z.enum(["automatic", "manual"]).default("automatic"),
 		shareStockStatus: z.boolean().default(true),
+		shareMedicationOverview: z.boolean().default(false),
 	})
 	.optional();
 
@@ -144,6 +151,69 @@ const importDataSchema = z.object({
 	shareLinks: z.array(shareLinkSchema).default([]),
 });
 
+const exportQuerystringSchema = {
+	type: "object",
+	properties: {
+		includeSensitive: { type: "string", enum: ["true", "false"] },
+		includeImages: { type: "string", enum: ["true", "false"] },
+	},
+} as const;
+
+const exportResponseSchema = {
+	type: "object",
+	properties: {
+		version: { type: "string" },
+		exportedAt: { type: "string", format: "date-time" },
+		includeSensitiveData: { type: "boolean" },
+		medications: { type: "array", items: { type: "object", additionalProperties: true } },
+		doseHistory: { type: "array", items: { type: "object", additionalProperties: true } },
+		refillHistory: { type: "array", items: { type: "object", additionalProperties: true } },
+		settings: { type: "object", additionalProperties: true },
+		shareLinks: { type: "array", items: { type: "object", additionalProperties: true } },
+	},
+} as const;
+
+const importBodyOpenApiSchema = {
+	type: "object",
+	required: ["version", "exportedAt"],
+	properties: {
+		version: { type: "string" },
+		exportedAt: { type: "string", format: "date-time" },
+		includeSensitiveData: { type: "boolean" },
+		medications: { type: "array", items: { type: "object", additionalProperties: true } },
+		doseHistory: { type: "array", items: { type: "object", additionalProperties: true } },
+		refillHistory: { type: "array", items: { type: "object", additionalProperties: true } },
+		settings: { type: "object", additionalProperties: true },
+		shareLinks: { type: "array", items: { type: "object", additionalProperties: true } },
+	},
+	example: {
+		version: "1.8.0",
+		exportedAt: "2026-03-11T10:15:00.000Z",
+		includeSensitiveData: true,
+		medications: [
+			{
+				name: "Ibuprofen 400",
+				packageType: "box",
+				packCount: 1,
+				looseTablets: 8,
+				intakes: [
+					{
+						usage: 1,
+						every: 8,
+						start: "2026-03-11T08:00:00.000Z",
+						takenBy: "Daniel",
+						remind: true,
+					},
+				],
+			},
+		],
+		doseHistory: [{ doseId: "1:2026-03-11T08:00:00.000Z:Daniel", takenAt: 1773216000000 }],
+		refillHistory: [{ packsAdded: 1, loosePillsAdded: 4, refillDate: "2026-03-10T12:00:00.000Z" }],
+		settings: { language: "en", stockCalculationMode: "automatic" },
+		shareLinks: [{ takenBy: "Daniel", scheduleDays: 14 }],
+	},
+} as const;
+
 // =============================================================================
 // Helper Functions
 // =============================================================================
@@ -271,243 +341,257 @@ function buildDoseId(medicationId: number, blisterIndex: number, timestampMs: nu
 export async function exportRoutes(app: FastifyInstance) {
 	// All export routes require auth
 	app.addHook("preHandler", requireAuth);
+	applyOpenApiRouteStandards(app, { tag: "export", protectedByDefault: true });
 
 	// ---------------------------------------------------------------------------
 	// GET /export - Export all user data
 	// ---------------------------------------------------------------------------
-	app.get<{ Querystring: { includeSensitive?: string; includeImages?: string } }>("/export", async (request, reply) => {
-		const userId = await getUserId(request, reply);
-		const includeSensitive = request.query.includeSensitive === "true";
-		const includeImages = request.query.includeImages !== "false"; // Default to true
-
-		// 1. Load all medications
-		const meds = await db.select().from(medications).where(eq(medications.userId, userId)).orderBy(medications.id);
-
-		// Build medication ID to export ID mapping
-		const medIdToExportId = new Map<number, string>();
-		const exportMedications = meds.map((med, index) => {
-			const exportId = `med-${index + 1}`;
-			medIdToExportId.set(med.id, exportId);
-
-			// Safely convert lastStockCorrectionAt to ISO string
-			let lastStockCorrectionAtIso: string | null = null;
-			if (med.lastStockCorrectionAt) {
-				try {
-					if (med.lastStockCorrectionAt instanceof Date && !Number.isNaN(med.lastStockCorrectionAt.getTime())) {
-						lastStockCorrectionAtIso = med.lastStockCorrectionAt.toISOString();
-					} else if (typeof med.lastStockCorrectionAt === "number" || typeof med.lastStockCorrectionAt === "string") {
-						const d = new Date(med.lastStockCorrectionAt);
-						lastStockCorrectionAtIso = !Number.isNaN(d.getTime()) ? d.toISOString() : null;
-					}
-				} catch {
-					lastStockCorrectionAtIso = null;
-				}
-			}
-
-			return {
-				_exportId: exportId,
-				name: med.name,
-				genericName: med.genericName,
-				takenBy: parseTakenByJson(med.takenByJson),
-				medicationForm: med.medicationForm ?? "tablet",
-				pillForm: med.pillForm ?? null,
-				lifecycleCategory: med.lifecycleCategory ?? "refill_when_empty",
-				inventory: {
-					packCount: med.packCount ?? 1,
-					blistersPerPack: med.blistersPerPack ?? 1,
-					pillsPerBlister: med.pillsPerBlister ?? 1,
-					totalPills: med.totalPills ?? null,
-					looseTablets: med.looseTablets ?? 0,
-					stockAdjustment: med.stockAdjustment ?? 0,
-					packageType: med.packageType ?? "blister",
-					packageAmountValue: med.packageAmountValue ?? 0,
-					packageAmountUnit: (med.packageAmountUnit ?? "ml") as "ml" | "g",
+	app.get<{ Querystring: { includeSensitive?: string; includeImages?: string } }>(
+		"/export",
+		{
+			schema: {
+				querystring: exportQuerystringSchema,
+				response: {
+					200: exportResponseSchema,
+					401: genericErrorSchema,
 				},
-				pillWeightMg: med.pillWeightMg,
-				doseUnit: med.doseUnit ?? "mg",
-				schedules: parseIntakesForExport(med),
-				medicationStartDate: med.medicationStartDate || null,
-				medicationEndDate: med.medicationEndDate || null,
-				autoMarkObsoleteAfterEndDate: med.autoMarkObsoleteAfterEndDate ?? true,
-				expiryDate: med.expiryDate,
-				notes: med.notes,
-				intakeRemindersEnabled: med.intakeRemindersEnabled ?? false,
-				isObsolete: med.isObsolete ?? false,
-				obsoleteAt: med.obsoleteAt?.toISOString() ?? null,
-				prescriptionEnabled: med.prescriptionEnabled ?? false,
-				prescriptionAuthorizedRefills: med.prescriptionAuthorizedRefills ?? null,
-				prescriptionRemainingRefills: med.prescriptionRemainingRefills ?? null,
-				prescriptionLowRefillThreshold: med.prescriptionLowRefillThreshold ?? 1,
-				prescriptionExpiryDate: med.prescriptionExpiryDate ?? null,
-				dismissedUntil: med.dismissedUntil ?? null,
-				image: includeImages ? imageToBase64(med.imageUrl) : null,
-				lastStockCorrectionAt: lastStockCorrectionAtIso,
-			};
-		});
+			},
+		},
+		async (request, reply) => {
+			const userId = await getUserId(request, reply);
+			const includeSensitive = request.query.includeSensitive === "true";
+			const includeImages = request.query.includeImages !== "false"; // Default to true
 
-		// 2. Load all dose tracking entries
-		const doses = await db.select().from(doseTracking).where(eq(doseTracking.userId, userId));
+			// 1. Load all medications
+			const meds = await db.select().from(medications).where(eq(medications.userId, userId)).orderBy(medications.id);
 
-		const exportDoseHistory = doses
-			.map((dose) => {
-				const parsed = parseDoseId(dose.doseId);
-				if (!parsed) return null;
+			// Build medication ID to export ID mapping
+			const medIdToExportId = new Map<number, string>();
+			const exportMedications = meds.map((med, index) => {
+				const exportId = `med-${index + 1}`;
+				medIdToExportId.set(med.id, exportId);
 
-				const exportId = medIdToExportId.get(parsed.medicationId);
-				if (!exportId) return null; // Orphaned dose, skip
+				// Safely convert lastStockCorrectionAt to ISO string
+				let lastStockCorrectionAtIso: string | null = null;
+				if (med.lastStockCorrectionAt) {
+					try {
+						if (med.lastStockCorrectionAt instanceof Date && !Number.isNaN(med.lastStockCorrectionAt.getTime())) {
+							lastStockCorrectionAtIso = med.lastStockCorrectionAt.toISOString();
+						} else if (typeof med.lastStockCorrectionAt === "number" || typeof med.lastStockCorrectionAt === "string") {
+							const d = new Date(med.lastStockCorrectionAt);
+							lastStockCorrectionAtIso = !Number.isNaN(d.getTime()) ? d.toISOString() : null;
+						}
+					} catch {
+						lastStockCorrectionAtIso = null;
+					}
+				}
 
-				// Safely convert takenAt to ISO string
-				let takenAtIso: string;
-				try {
-					if (dose.takenAt instanceof Date && !Number.isNaN(dose.takenAt.getTime())) {
-						takenAtIso = dose.takenAt.toISOString();
-					} else if (typeof dose.takenAt === "number" || typeof dose.takenAt === "string") {
-						const d = new Date(dose.takenAt);
-						takenAtIso = !Number.isNaN(d.getTime()) ? d.toISOString() : new Date().toISOString();
-					} else {
+				return {
+					_exportId: exportId,
+					name: med.name,
+					genericName: med.genericName,
+					takenBy: parseTakenByJson(med.takenByJson),
+					medicationForm: med.medicationForm ?? "tablet",
+					pillForm: med.pillForm ?? null,
+					lifecycleCategory: med.lifecycleCategory ?? "refill_when_empty",
+					inventory: {
+						packCount: med.packCount ?? 1,
+						blistersPerPack: med.blistersPerPack ?? 1,
+						pillsPerBlister: med.pillsPerBlister ?? 1,
+						totalPills: med.totalPills ?? null,
+						looseTablets: med.looseTablets ?? 0,
+						stockAdjustment: med.stockAdjustment ?? 0,
+						packageType: normalizePackageType(med.packageType),
+						packageAmountValue: med.packageAmountValue ?? 0,
+						packageAmountUnit: (med.packageAmountUnit ?? "ml") as "ml" | "g",
+					},
+					pillWeightMg: med.pillWeightMg,
+					doseUnit: med.doseUnit ?? "mg",
+					schedules: parseIntakesForExport(med),
+					medicationStartDate: med.medicationStartDate || null,
+					medicationEndDate: med.medicationEndDate || null,
+					autoMarkObsoleteAfterEndDate: med.autoMarkObsoleteAfterEndDate ?? true,
+					expiryDate: med.expiryDate,
+					notes: med.notes,
+					intakeRemindersEnabled: med.intakeRemindersEnabled ?? false,
+					isObsolete: med.isObsolete ?? false,
+					obsoleteAt: med.obsoleteAt?.toISOString() ?? null,
+					prescriptionEnabled: med.prescriptionEnabled ?? false,
+					prescriptionAuthorizedRefills: med.prescriptionAuthorizedRefills ?? null,
+					prescriptionRemainingRefills: med.prescriptionRemainingRefills ?? null,
+					prescriptionLowRefillThreshold: med.prescriptionLowRefillThreshold ?? 1,
+					prescriptionExpiryDate: med.prescriptionExpiryDate ?? null,
+					dismissedUntil: med.dismissedUntil ?? null,
+					image: includeImages ? imageToBase64(med.imageUrl) : null,
+					lastStockCorrectionAt: lastStockCorrectionAtIso,
+				};
+			});
+
+			// 2. Load all dose tracking entries
+			const doses = await db.select().from(doseTracking).where(eq(doseTracking.userId, userId));
+
+			const exportDoseHistory = doses
+				.map((dose) => {
+					const parsed = parseDoseId(dose.doseId);
+					if (!parsed) return null;
+
+					const exportId = medIdToExportId.get(parsed.medicationId);
+					if (!exportId) return null; // Orphaned dose, skip
+
+					// Safely convert takenAt to ISO string
+					let takenAtIso: string;
+					try {
+						if (dose.takenAt instanceof Date && !Number.isNaN(dose.takenAt.getTime())) {
+							takenAtIso = dose.takenAt.toISOString();
+						} else if (typeof dose.takenAt === "number" || typeof dose.takenAt === "string") {
+							const d = new Date(dose.takenAt);
+							takenAtIso = !Number.isNaN(d.getTime()) ? d.toISOString() : new Date().toISOString();
+						} else {
+							takenAtIso = new Date().toISOString();
+						}
+					} catch {
 						takenAtIso = new Date().toISOString();
 					}
-				} catch {
-					takenAtIso = new Date().toISOString();
-				}
 
-				// Safely convert scheduled time
-				let scheduledTimeIso: string;
-				try {
-					const d = new Date(parsed.timestampMs);
-					scheduledTimeIso = !Number.isNaN(d.getTime()) ? d.toISOString() : new Date().toISOString();
-				} catch {
-					scheduledTimeIso = new Date().toISOString();
+					// Safely convert scheduled time
+					let scheduledTimeIso: string;
+					try {
+						const d = new Date(parsed.timestampMs);
+						scheduledTimeIso = !Number.isNaN(d.getTime()) ? d.toISOString() : new Date().toISOString();
+					} catch {
+						scheduledTimeIso = new Date().toISOString();
+					}
+
+					return {
+						medicationRef: exportId,
+						scheduleIndex: parsed.blisterIndex,
+						scheduledTime: scheduledTimeIso,
+						takenAt: takenAtIso,
+						markedBy: dose.markedBy,
+						takenSource: dose.takenSource === "automatic" ? "automatic" : "manual",
+						dismissed: dose.dismissed ?? false,
+						takenByPerson: parsed.person,
+					};
+				})
+				.filter((d): d is NonNullable<typeof d> => d !== null);
+
+			// 3. Load user settings
+			const [settings] = await db.select().from(userSettings).where(eq(userSettings.userId, userId));
+
+			const exportSettings = settings
+				? {
+						emailEnabled: settings.emailEnabled,
+						notificationEmail: settings.notificationEmail,
+						emailStockReminders: settings.emailStockReminders,
+						emailIntakeReminders: settings.emailIntakeReminders,
+						emailPrescriptionReminders: settings.emailPrescriptionReminders ?? true,
+						// Only include sensitive data if requested
+						shoutrrrEnabled: includeSensitive ? settings.shoutrrrEnabled : undefined,
+						shoutrrrUrl: includeSensitive ? settings.shoutrrrUrl : undefined,
+						shoutrrrStockReminders: settings.shoutrrrStockReminders,
+						shoutrrrIntakeReminders: settings.shoutrrrIntakeReminders,
+						shoutrrrPrescriptionReminders: settings.shoutrrrPrescriptionReminders ?? true,
+						reminderDaysBefore: settings.reminderDaysBefore,
+						repeatDailyReminders: settings.repeatDailyReminders,
+						skipRemindersForTakenDoses: settings.skipRemindersForTakenDoses,
+						repeatRemindersEnabled: settings.repeatRemindersEnabled,
+						reminderRepeatIntervalMinutes: settings.reminderRepeatIntervalMinutes,
+						maxNaggingReminders: settings.maxNaggingReminders,
+						lowStockDays: settings.lowStockDays,
+						normalStockDays: settings.normalStockDays,
+						highStockDays: settings.highStockDays,
+						expiryWarningDays: settings.expiryWarningDays,
+						language: settings.language,
+						stockCalculationMode: settings.stockCalculationMode,
+						shareStockStatus: settings.shareStockStatus,
+						shareMedicationOverview: settings.shareMedicationOverview ?? false,
+					}
+				: undefined;
+
+			// 4. Load share links
+			const shares = await db.select().from(shareTokens).where(eq(shareTokens.userId, userId));
+
+			const exportShareLinks = shares.map((share) => {
+				// Safely convert expiresAt to ISO string
+				let expiresAtIso: string | null = null;
+				if (share.expiresAt) {
+					try {
+						if (share.expiresAt instanceof Date && !Number.isNaN(share.expiresAt.getTime())) {
+							expiresAtIso = share.expiresAt.toISOString();
+						} else if (typeof share.expiresAt === "number" || typeof share.expiresAt === "string") {
+							const d = new Date(share.expiresAt);
+							expiresAtIso = !Number.isNaN(d.getTime()) ? d.toISOString() : null;
+						}
+					} catch {
+						expiresAtIso = null;
+					}
 				}
 
 				return {
-					medicationRef: exportId,
-					scheduleIndex: parsed.blisterIndex,
-					scheduledTime: scheduledTimeIso,
-					takenAt: takenAtIso,
-					markedBy: dose.markedBy,
-					takenSource: dose.takenSource === "automatic" ? "automatic" : "manual",
-					dismissed: dose.dismissed ?? false,
-					takenByPerson: parsed.person,
+					takenBy: share.takenBy,
+					scheduleDays: share.scheduleDays,
+					expiresAt: expiresAtIso,
+					regenerateToken: true, // Always regenerate tokens on import for security
 				};
-			})
-			.filter((d): d is NonNullable<typeof d> => d !== null);
+			});
 
-		// 3. Load user settings
-		const [settings] = await db.select().from(userSettings).where(eq(userSettings.userId, userId));
+			// 5. Load refill history
+			const refills = await db.select().from(refillHistory).where(eq(refillHistory.userId, userId));
 
-		const exportSettings = settings
-			? {
-					emailEnabled: settings.emailEnabled,
-					notificationEmail: settings.notificationEmail,
-					emailStockReminders: settings.emailStockReminders,
-					emailIntakeReminders: settings.emailIntakeReminders,
-					emailPrescriptionReminders: settings.emailPrescriptionReminders ?? true,
-					// Only include sensitive data if requested
-					shoutrrrEnabled: includeSensitive ? settings.shoutrrrEnabled : undefined,
-					shoutrrrUrl: includeSensitive ? settings.shoutrrrUrl : undefined,
-					shoutrrrStockReminders: settings.shoutrrrStockReminders,
-					shoutrrrIntakeReminders: settings.shoutrrrIntakeReminders,
-					shoutrrrPrescriptionReminders: settings.shoutrrrPrescriptionReminders ?? true,
-					reminderDaysBefore: settings.reminderDaysBefore,
-					repeatDailyReminders: settings.repeatDailyReminders,
-					skipRemindersForTakenDoses: settings.skipRemindersForTakenDoses,
-					repeatRemindersEnabled: settings.repeatRemindersEnabled,
-					reminderRepeatIntervalMinutes: settings.reminderRepeatIntervalMinutes,
-					maxNaggingReminders: settings.maxNaggingReminders,
-					lowStockDays: settings.lowStockDays,
-					normalStockDays: settings.normalStockDays,
-					highStockDays: settings.highStockDays,
-					expiryWarningDays: settings.expiryWarningDays,
-					language: settings.language,
-					stockCalculationMode: settings.stockCalculationMode,
-					shareStockStatus: settings.shareStockStatus,
-				}
-			: undefined;
+			const exportRefillHistory = refills
+				.map((refill) => {
+					const exportId = medIdToExportId.get(refill.medicationId);
+					if (!exportId) return null; // Orphaned refill, skip
 
-		// 4. Load share links
-		const shares = await db.select().from(shareTokens).where(eq(shareTokens.userId, userId));
-
-		const exportShareLinks = shares.map((share) => {
-			// Safely convert expiresAt to ISO string
-			let expiresAtIso: string | null = null;
-			if (share.expiresAt) {
-				try {
-					if (share.expiresAt instanceof Date && !Number.isNaN(share.expiresAt.getTime())) {
-						expiresAtIso = share.expiresAt.toISOString();
-					} else if (typeof share.expiresAt === "number" || typeof share.expiresAt === "string") {
-						const d = new Date(share.expiresAt);
-						expiresAtIso = !Number.isNaN(d.getTime()) ? d.toISOString() : null;
-					}
-				} catch {
-					expiresAtIso = null;
-				}
-			}
-
-			return {
-				takenBy: share.takenBy,
-				scheduleDays: share.scheduleDays,
-				expiresAt: expiresAtIso,
-				regenerateToken: true, // Always regenerate tokens on import for security
-			};
-		});
-
-		// 5. Load refill history
-		const refills = await db.select().from(refillHistory).where(eq(refillHistory.userId, userId));
-
-		const exportRefillHistory = refills
-			.map((refill) => {
-				const exportId = medIdToExportId.get(refill.medicationId);
-				if (!exportId) return null; // Orphaned refill, skip
-
-				// Safely convert refillDate to ISO string
-				let refillDateIso: string;
-				try {
-					if (refill.refillDate instanceof Date && !Number.isNaN(refill.refillDate.getTime())) {
-						refillDateIso = refill.refillDate.toISOString();
-					} else if (typeof refill.refillDate === "number" || typeof refill.refillDate === "string") {
-						const d = new Date(refill.refillDate);
-						refillDateIso = !Number.isNaN(d.getTime()) ? d.toISOString() : new Date().toISOString();
-					} else {
+					// Safely convert refillDate to ISO string
+					let refillDateIso: string;
+					try {
+						if (refill.refillDate instanceof Date && !Number.isNaN(refill.refillDate.getTime())) {
+							refillDateIso = refill.refillDate.toISOString();
+						} else if (typeof refill.refillDate === "number" || typeof refill.refillDate === "string") {
+							const d = new Date(refill.refillDate);
+							refillDateIso = !Number.isNaN(d.getTime()) ? d.toISOString() : new Date().toISOString();
+						} else {
+							refillDateIso = new Date().toISOString();
+						}
+					} catch {
 						refillDateIso = new Date().toISOString();
 					}
-				} catch {
-					refillDateIso = new Date().toISOString();
-				}
 
-				return {
-					medicationRef: exportId,
-					packsAdded: refill.packsAdded ?? 0,
-					loosePillsAdded: refill.loosePillsAdded ?? 0,
-					usedPrescription: refill.usedPrescription ?? false,
-					refillDate: refillDateIso,
-				};
-			})
-			.filter((r): r is NonNullable<typeof r> => r !== null);
+					return {
+						medicationRef: exportId,
+						packsAdded: refill.packsAdded ?? 0,
+						loosePillsAdded: refill.loosePillsAdded ?? 0,
+						usedPrescription: refill.usedPrescription ?? false,
+						refillDate: refillDateIso,
+					};
+				})
+				.filter((r): r is NonNullable<typeof r> => r !== null);
 
-		// Build export object
-		const exportData = {
-			version: EXPORT_VERSION,
-			exportedAt: new Date().toISOString(),
-			includeSensitiveData: includeSensitive,
-			medications: exportMedications,
-			doseHistory: exportDoseHistory,
-			refillHistory: exportRefillHistory,
-			settings: exportSettings,
-			shareLinks: exportShareLinks,
-		};
+			// Build export object
+			const exportData = {
+				version: EXPORT_VERSION,
+				exportedAt: new Date().toISOString(),
+				includeSensitiveData: includeSensitive,
+				medications: exportMedications,
+				doseHistory: exportDoseHistory,
+				refillHistory: exportRefillHistory,
+				settings: exportSettings,
+				shareLinks: exportShareLinks,
+			};
 
-		// Set download headers
-		const now = new Date();
-		const dateStr = now.toISOString().replace(/[-:]/g, "").replace(/T/, "-").slice(0, 13);
-		const authUser = env.AUTH_ENABLED ? (request.user as unknown as AuthUser | null) : null;
-		const userPart = authUser?.username ? `-${authUser.username}` : "";
-		const filename = `medassist-export${userPart}-${dateStr}.json`;
-		reply.header("Content-Type", "application/json");
-		reply.header("Content-Disposition", `attachment; filename="${filename}"`);
+			// Set download headers
+			const now = new Date();
+			const dateStr = now.toISOString().replace(/[-:]/g, "").replace(/T/, "-").slice(0, 13);
+			const authUser = env.AUTH_ENABLED ? (request.user as unknown as AuthUser | null) : null;
+			const userPart = authUser?.username ? `-${authUser.username}` : "";
+			const filename = `medassist-export${userPart}-${dateStr}.json`;
+			reply.header("Content-Type", "application/json");
+			reply.header("Content-Disposition", `attachment; filename="${filename}"`);
 
-		return exportData;
-	});
+			return exportData;
+		}
+	);
 
 	// ---------------------------------------------------------------------------
 	// POST /import - Import user data (replaces all existing data!)
@@ -520,6 +604,29 @@ export async function exportRoutes(app: FastifyInstance) {
 				rawBody: true,
 			},
 			bodyLimit: 50 * 1024 * 1024, // 50 MB
+			schema: {
+				body: importBodyOpenApiSchema,
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							success: { type: "boolean" },
+							imported: {
+								type: "object",
+								properties: {
+									medications: { type: "integer" },
+									doseHistory: { type: "integer" },
+									refillHistory: { type: "integer" },
+									settings: { type: "integer" },
+									shareLinks: { type: "integer" },
+								},
+							},
+						},
+					},
+					400: { anyOf: [genericErrorSchema, validationErrorSchema] },
+					401: genericErrorSchema,
+				},
+			},
 		},
 		async (request, reply) => {
 			const userId = await getUserId(request, reply);
@@ -595,7 +702,7 @@ export async function exportRoutes(app: FastifyInstance) {
 						medicationForm: med.medicationForm ?? "tablet",
 						pillForm: med.pillForm || null,
 						lifecycleCategory: med.lifecycleCategory ?? "refill_when_empty",
-						packageType: med.inventory.packageType ?? "blister",
+						packageType: normalizePackageType(med.inventory.packageType),
 						packageAmountValue: med.inventory.packageAmountValue ?? 0,
 						packageAmountUnit: med.inventory.packageAmountUnit ?? "ml",
 						packCount: med.inventory.packCount,
@@ -688,6 +795,7 @@ export async function exportRoutes(app: FastifyInstance) {
 					language: importData.settings.language ?? "en",
 					stockCalculationMode: importData.settings.stockCalculationMode ?? "automatic",
 					shareStockStatus: importData.settings.shareStockStatus ?? true,
+					shareMedicationOverview: importData.settings.shareMedicationOverview ?? false,
 				});
 			}
 

backend/src/routes/health.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { FastifyInstance } from "fastify";
+import { applyOpenApiRouteStandards } from "../utils/openapi-route-standards.js";
 
 // Read version from package.json at startup
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -10,10 +11,31 @@ const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
 const backendVersion = packageJson.version || "unknown";
 
 export async function healthRoutes(app: FastifyInstance) {
+	applyOpenApiRouteStandards(app, { tag: "health", protectedByDefault: false });
+
 	// Exempt from rate limit + suppress request logs (called every 30s by Docker healthcheck)
-	app.get("/health", { config: { rateLimit: false }, logLevel: "warn" }, async () => ({
-		status: "ok",
-		version: backendVersion,
-		smtpConfigured: Boolean(process.env.SMTP_HOST),
-	}));
+	app.get(
+		"/health",
+		{
+			config: { rateLimit: false },
+			logLevel: "warn",
+			schema: {
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							status: { type: "string", enum: ["ok"] },
+							version: { type: "string" },
+							smtpConfigured: { type: "boolean" },
+						},
+					},
+				},
+			},
+		},
+		async () => ({
+			status: "ok",
+			version: backendVersion,
+			smtpConfigured: Boolean(process.env.SMTP_HOST),
+		})
+	);
 }

backend/src/routes/oidc.ts

@@ -5,6 +5,7 @@ import * as client from "openid-client";
 import { db } from "../db/client.js";
 import { refreshTokens, users } from "../db/schema.js";
 import { env } from "../plugins/env.js";
+import { applyOpenApiRouteStandards, genericErrorSchema } from "../utils/openapi-route-standards.js";
 
 // =============================================================================
 // OIDC Configuration Cache
@@ -49,12 +50,14 @@ function getFrontendUrl(): string {
 // OIDC Routes
 // =============================================================================
 export async function oidcRoutes(app: FastifyInstance) {
+	applyOpenApiRouteStandards(app, { tag: "auth", protectedByDefault: false });
+
 	if (!env.OIDC_ENABLED) {
 		// Register a disabled route that returns an error
-		app.get("/auth/oidc/login", async (_request, reply) => {
+		app.get("/auth/oidc/login", { schema: { response: { 400: genericErrorSchema } } }, async (_request, reply) => {
 			return reply.status(400).send({ error: "OIDC authentication is not enabled" });
 		});
-		app.get("/auth/oidc/callback", async (_request, reply) => {
+		app.get("/auth/oidc/callback", { schema: { response: { 400: genericErrorSchema } } }, async (_request, reply) => {
 			return reply.status(400).send({ error: "OIDC authentication is not enabled" });
 		});
 		return;
@@ -63,58 +66,85 @@ export async function oidcRoutes(app: FastifyInstance) {
 	// ---------------------------------------------------------------------------
 	// GET /auth/oidc/login - Initiates OIDC flow
 	// ---------------------------------------------------------------------------
-	app.get("/auth/oidc/login", async (request, reply) => {
-		try {
-			const config = await getOIDCConfig();
+	app.get(
+		"/auth/oidc/login",
+		{
+			schema: {
+				response: {
+					302: { type: "null", description: "Redirect to OIDC provider" },
+					500: genericErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			try {
+				const config = await getOIDCConfig();
 
-			// Generate PKCE values
-			const codeVerifier = generateCodeVerifier();
-			const codeChallenge = generateCodeChallenge(codeVerifier);
-			const state = generateState();
+				// Generate PKCE values
+				const codeVerifier = generateCodeVerifier();
+				const codeChallenge = generateCodeChallenge(codeVerifier);
+				const state = generateState();
 
-			// Store PKCE verifier and state in signed cookies (short-lived)
-			reply.setCookie("oidc_code_verifier", codeVerifier, {
-				httpOnly: true,
-				secure: env.NODE_ENV === "production",
-				sameSite: "lax",
-				path: "/",
-				maxAge: 600, // 10 minutes
-				signed: true,
-			});
+				// Store PKCE verifier and state in signed cookies (short-lived)
+				reply.setCookie("oidc_code_verifier", codeVerifier, {
+					httpOnly: true,
+					secure: env.NODE_ENV === "production",
+					sameSite: "lax",
+					path: "/",
+					maxAge: 600, // 10 minutes
+					signed: true,
+				});
 
-			reply.setCookie("oidc_state", state, {
-				httpOnly: true,
-				secure: env.NODE_ENV === "production",
-				sameSite: "lax",
-				path: "/",
-				maxAge: 600,
-				signed: true,
-			});
+				reply.setCookie("oidc_state", state, {
+					httpOnly: true,
+					secure: env.NODE_ENV === "production",
+					sameSite: "lax",
+					path: "/",
+					maxAge: 600,
+					signed: true,
+				});
 
-			// Build authorization URL
-			const redirectUri = env.OIDC_REDIRECT_URI!;
-			const scope = env.OIDC_SCOPES;
+				// Build authorization URL
+				const redirectUri = env.OIDC_REDIRECT_URI!;
+				const scope = env.OIDC_SCOPES;
 
-			const authUrl = client.buildAuthorizationUrl(config, {
-				redirect_uri: redirectUri,
-				scope,
-				state,
-				code_challenge: codeChallenge,
-				code_challenge_method: "S256",
-			});
+				const authUrl = client.buildAuthorizationUrl(config, {
+					redirect_uri: redirectUri,
+					scope,
+					state,
+					code_challenge: codeChallenge,
+					code_challenge_method: "S256",
+				});
 
-			return reply.redirect(authUrl.href);
-		} catch (err: unknown) {
-			request.log.error({ err }, "[OIDC] Login initialization failed");
-			return reply.redirect(`${getFrontendUrl()}/?error=oidc_init_failed`);
+				return reply.redirect(authUrl.href);
+			} catch (err: unknown) {
+				request.log.error({ err }, "[OIDC] Login initialization failed");
+				return reply.redirect(`${getFrontendUrl()}/?error=oidc_init_failed`);
+			}
 		}
-	});
+	);
 
 	// ---------------------------------------------------------------------------
 	// GET /auth/oidc/callback - Handles callback from OIDC provider
 	// ---------------------------------------------------------------------------
 	app.get<{ Querystring: { code?: string; state?: string; error?: string; error_description?: string } }>(
 		"/auth/oidc/callback",
+		{
+			schema: {
+				querystring: {
+					type: "object",
+					properties: {
+						code: { type: "string" },
+						state: { type: "string" },
+						error: { type: "string" },
+						error_description: { type: "string" },
+					},
+				},
+				response: {
+					302: { type: "null", description: "Redirect back to frontend" },
+				},
+			},
+		},
 		async (request, reply) => {
 			const { code, state, error, error_description } = request.query;
 

backend/src/routes/refills.ts

@@ -6,6 +6,13 @@ import { medications, refillHistory } from "../db/schema.js";
 import { getAnonymousUserId, requireAuth } from "../plugins/auth.js";
 import { env } from "../plugins/env.js";
 import type { AuthUser } from "../types/fastify.js";
+import {
+	applyOpenApiRouteStandards,
+	genericErrorSchema,
+	idParamsSchema,
+	validationErrorSchema,
+} from "../utils/openapi-route-standards.js";
+import { isAmountBasedPackageType, normalizePackageType } from "../utils/package-profiles.js";
 
 const refillSchema = z
 	.object({
@@ -17,9 +24,72 @@ const refillSchema = z
 		message: "Must add at least one pack or some loose pills",
 	});
 
+const refillBodyOpenApiSchema = {
+	type: "object",
+	properties: {
+		packsAdded: { type: "integer", minimum: 0, default: 0 },
+		loosePillsAdded: { type: "integer", minimum: 0, default: 0 },
+		usePrescription: { type: "boolean", default: false },
+	},
+	description: "Provide at least one pack or some loose pills.",
+	example: {
+		packsAdded: 1,
+		loosePillsAdded: 4,
+		usePrescription: true,
+	},
+} as const;
+
+const refillResponseSchema = {
+	type: "object",
+	properties: {
+		success: { type: "boolean" },
+		refill: {
+			type: "object",
+			properties: {
+				id: { type: "number" },
+				packsAdded: { type: "integer" },
+				loosePillsAdded: { type: "integer" },
+				totalPillsAdded: { type: "number" },
+				refillDate: { type: "string", format: "date-time" },
+			},
+		},
+		newStock: {
+			type: "object",
+			properties: {
+				packCount: { type: "integer" },
+				looseTablets: { type: "integer" },
+				totalPills: { type: "number" },
+			},
+		},
+		prescription: {
+			type: "object",
+			properties: {
+				used: { type: "boolean" },
+				remainingRefills: { type: "integer" },
+				authorizedRefills: { type: "integer" },
+				lowRefillThreshold: { type: "integer" },
+				enabled: { type: "boolean" },
+			},
+		},
+	},
+} as const;
+
+const refillHistoryItemSchema = {
+	type: "object",
+	properties: {
+		id: { type: "number" },
+		packsAdded: { type: "integer" },
+		loosePillsAdded: { type: "integer" },
+		totalPillsAdded: { type: "number" },
+		usedPrescription: { type: "boolean" },
+		refillDate: { type: "string", format: "date-time" },
+	},
+} as const;
+
 export async function refillRoutes(app: FastifyInstance) {
 	// All refill routes require auth
 	app.addHook("preHandler", requireAuth);
+	applyOpenApiRouteStandards(app, { tag: "refills", protectedByDefault: true });
 
 	// Helper to get user ID from request
 	async function getUserId(request: FastifyRequest, reply: FastifyReply): Promise<number> {
@@ -35,142 +105,218 @@ export async function refillRoutes(app: FastifyInstance) {
 	}
 
 	// POST /medications/:id/refill - Add stock to medication
-	app.post<{ Params: { id: string } }>("/medications/:id/refill", async (req, reply) => {
-		const parsed = refillSchema.safeParse(req.body);
-		if (!parsed.success) return reply.status(400).send(parsed.error.format());
+	app.post<{ Params: { id: string } }>(
+		"/medications/:id/refill",
+		{
+			schema: {
+				params: idParamsSchema,
+				body: refillBodyOpenApiSchema,
+				response: {
+					200: refillResponseSchema,
+					400: { anyOf: [genericErrorSchema, validationErrorSchema] },
+					401: genericErrorSchema,
+					404: genericErrorSchema,
+					409: genericErrorSchema,
+				},
+			},
+		},
+		async (req, reply) => {
+			const parsed = refillSchema.safeParse(req.body);
+			if (!parsed.success) return reply.status(400).send(parsed.error.format());
 
-		const medId = Number(req.params.id);
-		if (Number.isNaN(medId)) return reply.badRequest("Invalid medication id");
+			const medId = Number(req.params.id);
+			if (Number.isNaN(medId)) return reply.badRequest("Invalid medication id");
 
-		const userId = await getUserId(req, reply);
+			const userId = await getUserId(req, reply);
 
-		// Verify ownership
-		const [med] = await db
-			.select()
-			.from(medications)
-			.where(and(eq(medications.id, medId), eq(medications.userId, userId)));
-		if (!med) return reply.notFound("Medication not found");
+			// Verify ownership
+			const [med] = await db
+				.select()
+				.from(medications)
+				.where(and(eq(medications.id, medId), eq(medications.userId, userId)));
+			if (!med) return reply.notFound("Medication not found");
 
-		const { packsAdded, loosePillsAdded, usePrescription } = parsed.data;
-		const isBottle = (med.packageType ?? "blister") === "bottle";
-		const effectivePacksAdded = isBottle ? 0 : packsAdded;
-		const effectiveLoosePillsAdded = loosePillsAdded;
-		const remainingPrescriptionRefills = med.prescriptionRemainingRefills ?? 0;
+			const { packsAdded, loosePillsAdded, usePrescription } = parsed.data;
+			const packageType = normalizePackageType(med.packageType);
+			const isBottle = packageType === "bottle";
+			const isAmountBased = isAmountBasedPackageType(packageType);
+			const isCountBasedAmountPackage = isAmountBased && !isBottle;
 
-		if (effectivePacksAdded < 1 && effectiveLoosePillsAdded < 1) {
-			return reply.status(400).send({ error: "Must add at least one pack or some loose pills" });
-		}
+			const configuredAmountPerPackage = Number(med.packageAmountValue ?? 0);
+			const fallbackAmountPerPackage = Math.max(
+				1,
+				Math.round((med.totalPills ?? med.looseTablets ?? 0) / Math.max(1, med.packCount || 1))
+			);
+			const amountPerPackage =
+				Number.isFinite(configuredAmountPerPackage) && configuredAmountPerPackage > 0
+					? configuredAmountPerPackage
+					: fallbackAmountPerPackage;
 
-		if (usePrescription) {
-			if (!(med.prescriptionEnabled ?? false)) {
-				return reply.status(400).send({ error: "Prescription refill is not enabled for this medication" });
+			const requestedPackAdds = Math.max(0, packsAdded);
+			const requestedAmountAdds = Math.max(0, loosePillsAdded);
+			const derivedCountFromAmount = Math.max(0, Math.round(requestedAmountAdds / amountPerPackage));
+
+			let effectivePacksAdded = requestedPackAdds;
+			if (isBottle) {
+				effectivePacksAdded = 0;
+			} else if (isCountBasedAmountPackage) {
+				effectivePacksAdded = Math.max(requestedPackAdds, derivedCountFromAmount);
 			}
-			if (remainingPrescriptionRefills <= 0) {
-				return reply.status(409).send({ error: "No remaining prescription refills" });
+			const effectiveLoosePillsAdded = isCountBasedAmountPackage
+				? effectivePacksAdded * amountPerPackage
+				: requestedAmountAdds;
+			const remainingPrescriptionRefills = med.prescriptionRemainingRefills ?? 0;
+
+			if (effectivePacksAdded < 1 && effectiveLoosePillsAdded < 1) {
+				return reply.status(400).send({ error: "Must add at least one pack or some loose pills" });
 			}
-			if (!isBottle && effectivePacksAdded > remainingPrescriptionRefills) {
-				return reply.status(409).send({ error: "Packs to add exceed remaining prescription refills" });
+
+			if (usePrescription) {
+				if (!(med.prescriptionEnabled ?? false)) {
+					return reply.status(400).send({ error: "Prescription refill is not enabled for this medication" });
+				}
+				if (remainingPrescriptionRefills <= 0) {
+					return reply.status(409).send({ error: "No remaining prescription refills" });
+				}
+				if (!isBottle && effectivePacksAdded > remainingPrescriptionRefills) {
+					return reply.status(409).send({ error: "Packs to add exceed remaining prescription refills" });
+				}
 			}
-		}
 
-		// Update medication stock
-		const newPackCount = med.packCount + effectivePacksAdded;
-		const newLooseTablets = med.looseTablets + effectiveLoosePillsAdded;
+			// Update medication stock
+			const newPackCount = med.packCount + effectivePacksAdded;
+			const newLooseTablets = med.looseTablets + effectiveLoosePillsAdded;
+			const previousAmountBase = med.totalPills ?? med.looseTablets;
+			const newTotalAmount = previousAmountBase + effectiveLoosePillsAdded;
 
-		let consumedRefills = 0;
-		if (usePrescription) {
-			consumedRefills = isBottle ? 1 : effectivePacksAdded;
-		}
-		const newRemainingRefills = usePrescription
-			? Math.max(0, remainingPrescriptionRefills - consumedRefills)
-			: (med.prescriptionRemainingRefills ?? null);
+			let consumedRefills = 0;
+			if (usePrescription) {
+				consumedRefills = isBottle ? 1 : effectivePacksAdded;
+			}
+			const newRemainingRefills = usePrescription
+				? Math.max(0, remainingPrescriptionRefills - consumedRefills)
+				: (med.prescriptionRemainingRefills ?? null);
 
-		await db
-			.update(medications)
-			.set({
+			const updatePayload: {
+				packCount: number;
+				looseTablets: number;
+				totalPills?: number;
+				packageAmountValue?: number;
+				prescriptionRemainingRefills: number | null;
+				updatedAt: Date;
+			} = {
 				packCount: newPackCount,
 				looseTablets: newLooseTablets,
 				prescriptionRemainingRefills: newRemainingRefills,
 				updatedAt: new Date(),
-			})
-			.where(and(eq(medications.id, medId), eq(medications.userId, userId)));
+			};
 
-		// Create refill history entry
-		const [refill] = await db
-			.insert(refillHistory)
-			.values({
-				medicationId: medId,
-				userId,
-				packsAdded: effectivePacksAdded,
-				loosePillsAdded: effectiveLoosePillsAdded,
-				usedPrescription: usePrescription,
-			})
-			.returning();
+			if (isCountBasedAmountPackage) {
+				updatePayload.totalPills = newTotalAmount;
+				updatePayload.packageAmountValue = amountPerPackage;
+			}
 
-		// Calculate pills added for response (packageType-aware)
-		const pillsPerPack = isBottle ? 0 : med.blistersPerPack * med.pillsPerBlister;
-		const totalPillsAdded = isBottle
-			? effectiveLoosePillsAdded
-			: effectivePacksAdded * pillsPerPack + effectiveLoosePillsAdded;
-		const newTotalPills = isBottle
-			? newLooseTablets + (med.stockAdjustment ?? 0)
-			: newPackCount * pillsPerPack + newLooseTablets + (med.stockAdjustment ?? 0);
+			await db
+				.update(medications)
+				.set(updatePayload)
+				.where(and(eq(medications.id, medId), eq(medications.userId, userId)));
 
-		return {
-			success: true,
-			refill: {
-				id: refill.id,
-				packsAdded: effectivePacksAdded,
-				loosePillsAdded: effectiveLoosePillsAdded,
-				totalPillsAdded,
-				refillDate: refill.refillDate,
-			},
-			newStock: {
-				packCount: newPackCount,
-				looseTablets: newLooseTablets,
-				totalPills: newTotalPills,
-			},
-			prescription: {
-				used: usePrescription,
-				remainingRefills: newRemainingRefills,
-				authorizedRefills: med.prescriptionAuthorizedRefills ?? null,
-				lowRefillThreshold: med.prescriptionLowRefillThreshold ?? 1,
-				enabled: med.prescriptionEnabled ?? false,
-			},
-		};
-	});
+			// Create refill history entry
+			const [refill] = await db
+				.insert(refillHistory)
+				.values({
+					medicationId: medId,
+					userId,
+					packsAdded: effectivePacksAdded,
+					loosePillsAdded: effectiveLoosePillsAdded,
+					usedPrescription: usePrescription,
+				})
+				.returning();
+
+			// Calculate pills added for response (packageType-aware)
+			const pillsPerPack = isBottle ? 0 : med.blistersPerPack * med.pillsPerBlister;
+			const totalPillsAdded = isAmountBased
+				? effectiveLoosePillsAdded
+				: effectivePacksAdded * pillsPerPack + effectiveLoosePillsAdded;
+			let newTotalPills = newPackCount * pillsPerPack + newLooseTablets + (med.stockAdjustment ?? 0);
+			if (isCountBasedAmountPackage) {
+				newTotalPills = (newTotalAmount ?? 0) + (med.stockAdjustment ?? 0);
+			} else if (isBottle) {
+				newTotalPills = newLooseTablets + (med.stockAdjustment ?? 0);
+			}
+
+			return {
+				success: true,
+				refill: {
+					id: refill.id,
+					packsAdded: effectivePacksAdded,
+					loosePillsAdded: effectiveLoosePillsAdded,
+					totalPillsAdded,
+					refillDate: refill.refillDate,
+				},
+				newStock: {
+					packCount: newPackCount,
+					looseTablets: newLooseTablets,
+					totalPills: newTotalPills,
+				},
+				prescription: {
+					used: usePrescription,
+					remainingRefills: newRemainingRefills,
+					authorizedRefills: med.prescriptionAuthorizedRefills ?? null,
+					lowRefillThreshold: med.prescriptionLowRefillThreshold ?? 1,
+					enabled: med.prescriptionEnabled ?? false,
+				},
+			};
+		}
+	);
 
 	// GET /medications/:id/refills - Get refill history for a medication
-	app.get<{ Params: { id: string } }>("/medications/:id/refills", async (req, reply) => {
-		const medId = Number(req.params.id);
-		if (Number.isNaN(medId)) return reply.badRequest("Invalid medication id");
+	app.get<{ Params: { id: string } }>(
+		"/medications/:id/refills",
+		{
+			schema: {
+				params: idParamsSchema,
+				response: {
+					200: { type: "array", items: refillHistoryItemSchema },
+					400: genericErrorSchema,
+					401: genericErrorSchema,
+					404: genericErrorSchema,
+				},
+			},
+		},
+		async (req, reply) => {
+			const medId = Number(req.params.id);
+			if (Number.isNaN(medId)) return reply.badRequest("Invalid medication id");
 
-		const userId = await getUserId(req, reply);
+			const userId = await getUserId(req, reply);
 
-		// Verify ownership
-		const [med] = await db
-			.select()
-			.from(medications)
-			.where(and(eq(medications.id, medId), eq(medications.userId, userId)));
-		if (!med) return reply.notFound("Medication not found");
+			// Verify ownership
+			const [med] = await db
+				.select()
+				.from(medications)
+				.where(and(eq(medications.id, medId), eq(medications.userId, userId)));
+			if (!med) return reply.notFound("Medication not found");
 
-		// Get refill history, newest first
-		const refills = await db
-			.select()
-			.from(refillHistory)
-			.where(eq(refillHistory.medicationId, medId))
-			.orderBy(desc(refillHistory.refillDate));
+			// Get refill history, newest first
+			const refills = await db
+				.select()
+				.from(refillHistory)
+				.where(and(eq(refillHistory.medicationId, medId), eq(refillHistory.userId, userId)))
+				.orderBy(desc(refillHistory.refillDate));
 
-		const isBottle = (med.packageType ?? "blister") === "bottle";
-		const pillsPerPack = isBottle ? 0 : med.blistersPerPack * med.pillsPerBlister;
+			const packageType = normalizePackageType(med.packageType);
+			const isBottle = packageType === "bottle";
+			const isAmountBased = isAmountBasedPackageType(packageType);
+			const pillsPerPack = isBottle ? 0 : med.blistersPerPack * med.pillsPerBlister;
 
-		return refills.map((r) => ({
-			id: r.id,
-			packsAdded: r.packsAdded,
-			loosePillsAdded: r.loosePillsAdded,
-			totalPillsAdded: isBottle ? r.loosePillsAdded : r.packsAdded * pillsPerPack + r.loosePillsAdded,
-			usedPrescription: r.usedPrescription ?? false,
-			refillDate: r.refillDate,
-		}));
-	});
+			return refills.map((r) => ({
+				id: r.id,
+				packsAdded: r.packsAdded,
+				loosePillsAdded: r.loosePillsAdded,
+				totalPillsAdded: isAmountBased ? r.loosePillsAdded : r.packsAdded * pillsPerPack + r.loosePillsAdded,
+				usedPrescription: r.usedPrescription ?? false,
+				refillDate: r.refillDate,
+			}));
+		}
+	);
 }

backend/src/routes/report.ts

@@ -1,4 +1,4 @@
-import { eq } from "drizzle-orm";
+import { and, eq } from "drizzle-orm";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 import { db } from "../db/client.js";
@@ -6,13 +6,61 @@ import { doseTracking, medications, refillHistory } from "../db/schema.js";
 import { getAnonymousUserId, requireAuth } from "../plugins/auth.js";
 import { env } from "../plugins/env.js";
 import type { AuthUser } from "../types/fastify.js";
+import {
+	applyOpenApiRouteStandards,
+	genericErrorSchema,
+	validationErrorSchema,
+} from "../utils/openapi-route-standards.js";
 
 const reportDataSchema = z.object({
 	medicationIds: z.array(z.number().int().positive()).min(1).max(100),
 });
 
+const reportDataBodyOpenApiSchema = {
+	type: "object",
+	required: ["medicationIds"],
+	properties: {
+		medicationIds: {
+			type: "array",
+			minItems: 1,
+			maxItems: 100,
+			items: { type: "integer", minimum: 1 },
+		},
+	},
+	example: {
+		medicationIds: [1, 3, 5],
+	},
+} as const;
+
+const reportDataResponseSchema = {
+	type: "object",
+	additionalProperties: {
+		type: "object",
+		properties: {
+			dosesTaken: { type: "integer" },
+			automaticDosesTaken: { type: "integer" },
+			dosesDismissed: { type: "integer" },
+			firstDoseAt: { type: "string" },
+			lastDoseAt: { type: "string" },
+			refills: {
+				type: "array",
+				items: {
+					type: "object",
+					properties: {
+						packsAdded: { type: "integer" },
+						loosePillsAdded: { type: "integer" },
+						usedPrescription: { type: "boolean" },
+						refillDate: { type: "string", format: "date-time" },
+					},
+				},
+			},
+		},
+	},
+} as const;
+
 export async function reportRoutes(app: FastifyInstance) {
 	app.addHook("preHandler", requireAuth);
+	applyOpenApiRouteStandards(app, { tag: "report", protectedByDefault: true });
 
 	async function getUserId(request: FastifyRequest, reply: FastifyReply): Promise<number> {
 		if (!env.AUTH_ENABLED) {
@@ -27,87 +75,104 @@ export async function reportRoutes(app: FastifyInstance) {
 	}
 
 	// POST /medications/report-data - Get aggregated dose/refill data for report generation
-	app.post("/medications/report-data", async (req, reply) => {
-		const parsed = reportDataSchema.safeParse(req.body);
-		if (!parsed.success) return reply.status(400).send(parsed.error.format());
+	app.post(
+		"/medications/report-data",
+		{
+			schema: {
+				body: reportDataBodyOpenApiSchema,
+				response: {
+					200: reportDataResponseSchema,
+					400: { anyOf: [genericErrorSchema, validationErrorSchema] },
+					401: genericErrorSchema,
+					403: genericErrorSchema,
+				},
+			},
+		},
+		async (req, reply) => {
+			const parsed = reportDataSchema.safeParse(req.body);
+			if (!parsed.success) return reply.status(400).send(parsed.error.format());
 
-		const userId = await getUserId(req, reply);
-		const { medicationIds } = parsed.data;
+			const userId = await getUserId(req, reply);
+			const { medicationIds } = parsed.data;
 
-		// Verify all medications belong to this user
-		const userMeds = await db.select({ id: medications.id }).from(medications).where(eq(medications.userId, userId));
-		const userMedIds = new Set(userMeds.map((m) => m.id));
+			// Verify all medications belong to this user
+			const userMeds = await db.select({ id: medications.id }).from(medications).where(eq(medications.userId, userId));
+			const userMedIds = new Set(userMeds.map((m) => m.id));
 
-		for (const id of medicationIds) {
-			if (!userMedIds.has(id)) {
-				return reply.status(403).send({ error: "Access denied to medication" });
+			for (const id of medicationIds) {
+				if (!userMedIds.has(id)) {
+					return reply.status(403).send({ error: "Access denied to medication" });
+				}
 			}
-		}
 
-		// Fetch dose tracking for all requested medications
-		// doseId format: "{medicationId}-{blisterIndex}-{dateMs}" or "{medicationId}-{blisterIndex}-{dateMs}-{takenBy}"
-		const allDoses = await db
-			.select({
-				doseId: doseTracking.doseId,
-				takenAt: doseTracking.takenAt,
-				dismissed: doseTracking.dismissed,
-				takenSource: doseTracking.takenSource,
-			})
-			.from(doseTracking)
-			.where(eq(doseTracking.userId, userId));
+			// Fetch dose tracking for all requested medications
+			// doseId format: "{medicationId}-{blisterIndex}-{dateMs}" or "{medicationId}-{blisterIndex}-{dateMs}-{takenBy}"
+			const allDoses = await db
+				.select({
+					doseId: doseTracking.doseId,
+					takenAt: doseTracking.takenAt,
+					dismissed: doseTracking.dismissed,
+					takenSource: doseTracking.takenSource,
+				})
+				.from(doseTracking)
+				.where(eq(doseTracking.userId, userId));
 
-		// Group doses by medication ID
-		const dosesByMed = new Map<number, { takenAt: Date; dismissed: boolean; takenSource: string }[]>();
-		for (const dose of allDoses) {
-			const medId = Number.parseInt(dose.doseId.split("-")[0], 10);
-			if (Number.isNaN(medId) || !medicationIds.includes(medId)) continue;
-			if (!dosesByMed.has(medId)) dosesByMed.set(medId, []);
-			dosesByMed.get(medId)!.push({
-				takenAt: dose.takenAt,
-				dismissed: dose.dismissed,
-				takenSource: dose.takenSource ?? "manual",
-			});
-		}
-
-		// Fetch refill history for requested medications
-		const result: Record<
-			number,
-			{
-				dosesTaken: number;
-				automaticDosesTaken: number;
-				dosesDismissed: number;
-				firstDoseAt: string | null;
-				lastDoseAt: string | null;
-				refills: { packsAdded: number; loosePillsAdded: number; usedPrescription: boolean; refillDate: string }[];
+			// Group doses by medication ID
+			const dosesByMed = new Map<number, { takenAt: Date; dismissed: boolean; takenSource: string }[]>();
+			for (const dose of allDoses) {
+				const medId = Number.parseInt(dose.doseId.split("-")[0], 10);
+				if (Number.isNaN(medId) || !medicationIds.includes(medId)) continue;
+				if (!dosesByMed.has(medId)) dosesByMed.set(medId, []);
+				dosesByMed.get(medId)!.push({
+					takenAt: dose.takenAt,
+					dismissed: dose.dismissed,
+					takenSource: dose.takenSource ?? "manual",
+				});
 			}
-		> = {};
 
-		for (const medId of medicationIds) {
-			const doses = dosesByMed.get(medId) ?? [];
-			const takenDoses = doses.filter((d) => !d.dismissed);
-			const automaticTakenDoses = takenDoses.filter((d) => d.takenSource === "automatic");
-			const dismissedDoses = doses.filter((d) => d.dismissed);
+			// Fetch refill history for requested medications
+			const result: Record<
+				number,
+				{
+					dosesTaken: number;
+					automaticDosesTaken: number;
+					dosesDismissed: number;
+					firstDoseAt: string | null;
+					lastDoseAt: string | null;
+					refills: { packsAdded: number; loosePillsAdded: number; usedPrescription: boolean; refillDate: string }[];
+				}
+			> = {};
 
-			const sortedTaken = takenDoses.map((d) => d.takenAt.getTime()).sort((a, b) => a - b);
+			for (const medId of medicationIds) {
+				const doses = dosesByMed.get(medId) ?? [];
+				const takenDoses = doses.filter((d) => !d.dismissed);
+				const automaticTakenDoses = takenDoses.filter((d) => d.takenSource === "automatic");
+				const dismissedDoses = doses.filter((d) => d.dismissed);
 
-			// Get refills for this medication
-			const refills = await db.select().from(refillHistory).where(eq(refillHistory.medicationId, medId));
+				const sortedTaken = takenDoses.map((d) => d.takenAt.getTime()).sort((a, b) => a - b);
 
-			result[medId] = {
-				dosesTaken: takenDoses.length,
-				automaticDosesTaken: automaticTakenDoses.length,
-				dosesDismissed: dismissedDoses.length,
-				firstDoseAt: sortedTaken.length > 0 ? new Date(sortedTaken[0]).toISOString() : null,
-				lastDoseAt: sortedTaken.length > 0 ? new Date(sortedTaken[sortedTaken.length - 1]).toISOString() : null,
-				refills: refills.map((r) => ({
-					packsAdded: r.packsAdded,
-					loosePillsAdded: r.loosePillsAdded,
-					usedPrescription: r.usedPrescription ?? false,
-					refillDate: r.refillDate instanceof Date ? r.refillDate.toISOString() : String(r.refillDate),
-				})),
-			};
+				// Get refills for this medication scoped to the authenticated user.
+				const refills = await db
+					.select()
+					.from(refillHistory)
+					.where(and(eq(refillHistory.medicationId, medId), eq(refillHistory.userId, userId)));
+
+				result[medId] = {
+					dosesTaken: takenDoses.length,
+					automaticDosesTaken: automaticTakenDoses.length,
+					dosesDismissed: dismissedDoses.length,
+					firstDoseAt: sortedTaken.length > 0 ? new Date(sortedTaken[0]).toISOString() : null,
+					lastDoseAt: sortedTaken.length > 0 ? new Date(sortedTaken[sortedTaken.length - 1]).toISOString() : null,
+					refills: refills.map((r) => ({
+						packsAdded: r.packsAdded,
+						loosePillsAdded: r.loosePillsAdded,
+						usedPrescription: r.usedPrescription ?? false,
+						refillDate: r.refillDate instanceof Date ? r.refillDate.toISOString() : String(r.refillDate),
+					})),
+				};
+			}
+
+			return result;
 		}
-
-		return result;
-	});
+	);
 }

backend/src/routes/settings.ts

@@ -33,6 +33,7 @@ export type UserSettings = {
 	language: Language;
 	stockCalculationMode: "automatic" | "manual";
 	shareStockStatus: boolean;
+	shareMedicationOverview: boolean;
 	upcomingTodayOnly: boolean;
 	shareScheduleTodayOnly: boolean;
 	swapDashboardMainSections: boolean;
@@ -72,6 +73,7 @@ type SettingsBody = {
 	language: string;
 	stockCalculationMode: "automatic" | "manual";
 	shareStockStatus: boolean;
+	shareMedicationOverview: boolean;
 	upcomingTodayOnly: boolean;
 	shareScheduleTodayOnly: boolean;
 	swapDashboardMainSections: boolean;
@@ -85,6 +87,18 @@ type TestShoutrrrBody = {
 	url: string;
 };
 
+const settingsEndpointSecurity: ReadonlyArray<Record<string, readonly string[]>> = [
+	{ bearerAuth: [] },
+	{ cookieAuth: [] },
+];
+const settingsErrorSchema = {
+	type: "object",
+	properties: {
+		error: { type: "string" },
+		code: { type: "string" },
+	},
+};
+
 function maskEmail(email: string): string {
 	const [localPart, domain] = email.split("@");
 	if (!domain) return "invalid-email";
@@ -122,6 +136,38 @@ function getDeliveryError(info: MailDeliveryInfo): string | null {
 	return "SMTP did not confirm accepted recipients.";
 }
 
+function classifyTestEmailFailure(error: unknown): { status: number; code: string; message: string } {
+	const errorMessage = error instanceof Error ? error.message : "Unknown error";
+	const normalizedMessage = errorMessage.toLowerCase();
+
+	if (
+		normalizedMessage.includes("smtp rejected all recipients") ||
+		normalizedMessage.includes("all recipients were rejected") ||
+		normalizedMessage.includes("recipient address rejected") ||
+		normalizedMessage.includes("nullmx")
+	) {
+		return {
+			status: 400,
+			code: "EMAIL_RECIPIENT_REJECTED",
+			message: `Failed to send email: ${errorMessage}`,
+		};
+	}
+
+	if (errorMessage.includes("SMTP did not confirm accepted recipients")) {
+		return {
+			status: 502,
+			code: "SMTP_DELIVERY_UNCONFIRMED",
+			message: `Failed to send email: ${errorMessage}`,
+		};
+	}
+
+	return {
+		status: 500,
+		code: "TEST_EMAIL_FAILED",
+		message: `Failed to send email: ${errorMessage}`,
+	};
+}
+
 function getNotificationProvider(url: string): string {
 	if (url.startsWith("discord://")) return "discord";
 	if (url.startsWith("telegram://")) return "telegram";
@@ -177,6 +223,7 @@ function getDefaultSettings() {
 		language: (process.env.DEFAULT_LANGUAGE as "en" | "de") || "en",
 		stockCalculationMode: (process.env.DEFAULT_STOCK_CALCULATION_MODE as "automatic" | "manual") || "automatic",
 		shareStockStatus: envBool("DEFAULT_SHARE_STOCK_STATUS", true),
+		shareMedicationOverview: envBool("DEFAULT_SHARE_MEDICATION_OVERVIEW", false),
 		upcomingTodayOnly: envBool("DEFAULT_UPCOMING_TODAY_ONLY", false),
 		shareScheduleTodayOnly: envBool("DEFAULT_SHARE_SCHEDULE_TODAY_ONLY", false),
 		swapDashboardMainSections: false,
@@ -239,6 +286,7 @@ export async function loadUserSettings(userId: number): Promise<UserSettings> {
 		language: settings.language as Language,
 		stockCalculationMode: (settings.stockCalculationMode as "automatic" | "manual") ?? "automatic",
 		shareStockStatus: settings.shareStockStatus ?? true,
+		shareMedicationOverview: settings.shareMedicationOverview ?? false,
 		upcomingTodayOnly: settings.upcomingTodayOnly ?? false,
 		shareScheduleTodayOnly: settings.shareScheduleTodayOnly ?? false,
 		swapDashboardMainSections: settings.swapDashboardMainSections ?? false,
@@ -283,6 +331,7 @@ export async function getAllUserSettings(): Promise<UserSettings[]> {
 		language: settings.language as Language,
 		stockCalculationMode: (settings.stockCalculationMode as "automatic" | "manual") ?? "automatic",
 		shareStockStatus: settings.shareStockStatus ?? true,
+		shareMedicationOverview: settings.shareMedicationOverview ?? false,
 		upcomingTodayOnly: settings.upcomingTodayOnly ?? false,
 		shareScheduleTodayOnly: settings.shareScheduleTodayOnly ?? false,
 		swapDashboardMainSections: settings.swapDashboardMainSections ?? false,
@@ -322,197 +371,350 @@ export async function settingsRoutes(app: FastifyInstance) {
 
 	// Get settings for current user
 	// Suppress request logs — polled every 30s for reminder status refresh
-	app.get("/settings", { logLevel: "warn" }, async (request, reply) => {
-		const userId = await getUserId(request, reply);
+	app.get(
+		"/settings",
+		{
+			logLevel: "warn",
+			schema: {
+				tags: ["settings"],
+				summary: "Get current user settings",
+				security: settingsEndpointSecurity,
+				response: {
+					200: { type: "object", additionalProperties: true },
+					401: settingsErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			const userId = await getUserId(request, reply);
 
-		const settings = await getOrCreateUserSettings(userId);
+			const settings = await getOrCreateUserSettings(userId);
+			const reminderHour = envInt("REMINDER_HOUR", 6);
+			const reminderMinutesBefore = envInt("REMINDER_MINUTES_BEFORE", 15);
 
-		return reply.send({
-			// User notification settings (from DB)
-			emailEnabled: settings.emailEnabled,
-			notificationEmail: settings.notificationEmail ?? "",
-			reminderDaysBefore: settings.reminderDaysBefore,
-			repeatDailyReminders: settings.repeatDailyReminders,
-			lowStockDays: settings.lowStockDays,
-			normalStockDays: settings.normalStockDays,
-			highStockDays: settings.highStockDays,
-			shoutrrrEnabled: settings.shoutrrrEnabled,
-			shoutrrrUrl: settings.shoutrrrUrl ?? "",
-			emailStockReminders: settings.emailStockReminders,
-			emailIntakeReminders: settings.emailIntakeReminders,
-			emailPrescriptionReminders: settings.emailPrescriptionReminders ?? true,
-			shoutrrrStockReminders: settings.shoutrrrStockReminders,
-			shoutrrrIntakeReminders: settings.shoutrrrIntakeReminders,
-			shoutrrrPrescriptionReminders: settings.shoutrrrPrescriptionReminders ?? true,
-			skipRemindersForTakenDoses: settings.skipRemindersForTakenDoses,
-			repeatRemindersEnabled: settings.repeatRemindersEnabled ?? false,
-			reminderRepeatIntervalMinutes: settings.reminderRepeatIntervalMinutes ?? 30,
-			maxNaggingReminders: settings.maxNaggingReminders ?? 5,
-			language: settings.language,
-			stockCalculationMode: settings.stockCalculationMode ?? "automatic",
-			shareStockStatus: settings.shareStockStatus ?? true,
-			upcomingTodayOnly: settings.upcomingTodayOnly ?? false,
-			shareScheduleTodayOnly: settings.shareScheduleTodayOnly ?? false,
-			swapDashboardMainSections: settings.swapDashboardMainSections ?? false,
-			// SMTP settings (from .env - shared/server-configured)
-			smtpHost: process.env.SMTP_HOST ?? "",
-			smtpPort: parseInt(process.env.SMTP_PORT ?? "587", 10),
-			smtpUser: process.env.SMTP_USER ?? "",
-			smtpFrom: process.env.SMTP_FROM ?? "",
-			smtpSecure: process.env.SMTP_SECURE === "true",
-			hasSmtpPassword: !!(process.env.SMTP_TOKEN || process.env.SMTP_PASS),
-			// Reminder state for this user
-			lastAutoEmailSent: settings.lastAutoEmailSent,
-			lastNotificationType: settings.lastNotificationType,
-			lastNotificationChannel: settings.lastNotificationChannel,
-			lastReminderMedName: settings.lastReminderMedName ?? null,
-			lastReminderTakenBy: settings.lastReminderTakenBy ?? null,
-			// Stock reminder tracking (separate from intake)
-			lastStockReminderSent: settings.lastStockReminderSent ?? null,
-			lastStockReminderChannel: settings.lastStockReminderChannel ?? null,
-			lastStockReminderMedNames: settings.lastStockReminderMedNames ?? null,
-			// Prescription reminder tracking (separate from stock/intake)
-			lastPrescriptionReminderSent: settings.lastPrescriptionReminderSent ?? null,
-			lastPrescriptionReminderChannel: settings.lastPrescriptionReminderChannel ?? null,
-			lastPrescriptionReminderMedNames: settings.lastPrescriptionReminderMedNames ?? null,
-			// Server settings (from .env, read-only)
-			expiryWarningDays: parseInt(process.env.EXPIRY_WARNING_DAYS ?? "30", 10),
-		});
-	});
+			return reply.send({
+				// User notification settings (from DB)
+				emailEnabled: settings.emailEnabled,
+				notificationEmail: settings.notificationEmail ?? "",
+				reminderDaysBefore: settings.reminderDaysBefore,
+				repeatDailyReminders: settings.repeatDailyReminders,
+				lowStockDays: settings.lowStockDays,
+				normalStockDays: settings.normalStockDays,
+				highStockDays: settings.highStockDays,
+				shoutrrrEnabled: settings.shoutrrrEnabled,
+				shoutrrrUrl: settings.shoutrrrUrl ?? "",
+				emailStockReminders: settings.emailStockReminders,
+				emailIntakeReminders: settings.emailIntakeReminders,
+				emailPrescriptionReminders: settings.emailPrescriptionReminders ?? true,
+				shoutrrrStockReminders: settings.shoutrrrStockReminders,
+				shoutrrrIntakeReminders: settings.shoutrrrIntakeReminders,
+				shoutrrrPrescriptionReminders: settings.shoutrrrPrescriptionReminders ?? true,
+				skipRemindersForTakenDoses: settings.skipRemindersForTakenDoses,
+				repeatRemindersEnabled: settings.repeatRemindersEnabled ?? false,
+				reminderRepeatIntervalMinutes: settings.reminderRepeatIntervalMinutes ?? 30,
+				maxNaggingReminders: settings.maxNaggingReminders ?? 5,
+				language: settings.language,
+				stockCalculationMode: settings.stockCalculationMode ?? "automatic",
+				shareStockStatus: settings.shareStockStatus ?? true,
+				shareMedicationOverview: settings.shareMedicationOverview ?? false,
+				upcomingTodayOnly: settings.upcomingTodayOnly ?? false,
+				shareScheduleTodayOnly: settings.shareScheduleTodayOnly ?? false,
+				swapDashboardMainSections: settings.swapDashboardMainSections ?? false,
+				// SMTP settings (from .env - shared/server-configured)
+				smtpHost: process.env.SMTP_HOST ?? "",
+				smtpPort: parseInt(process.env.SMTP_PORT ?? "587", 10),
+				smtpUser: process.env.SMTP_USER ?? "",
+				smtpFrom: process.env.SMTP_FROM ?? "",
+				smtpSecure: process.env.SMTP_SECURE === "true",
+				hasSmtpPassword: !!(process.env.SMTP_TOKEN || process.env.SMTP_PASS),
+				// Reminder state for this user
+				lastAutoEmailSent: settings.lastAutoEmailSent,
+				lastNotificationType: settings.lastNotificationType,
+				lastNotificationChannel: settings.lastNotificationChannel,
+				lastReminderMedName: settings.lastReminderMedName ?? null,
+				lastReminderTakenBy: settings.lastReminderTakenBy ?? null,
+				// Stock reminder tracking (separate from intake)
+				lastStockReminderSent: settings.lastStockReminderSent ?? null,
+				lastStockReminderChannel: settings.lastStockReminderChannel ?? null,
+				lastStockReminderMedNames: settings.lastStockReminderMedNames ?? null,
+				// Prescription reminder tracking (separate from stock/intake)
+				lastPrescriptionReminderSent: settings.lastPrescriptionReminderSent ?? null,
+				lastPrescriptionReminderChannel: settings.lastPrescriptionReminderChannel ?? null,
+				lastPrescriptionReminderMedNames: settings.lastPrescriptionReminderMedNames ?? null,
+				// Server settings (from .env, read-only)
+				reminderHour,
+				reminderMinutesBefore,
+				expiryWarningDays: parseInt(process.env.EXPIRY_WARNING_DAYS ?? "30", 10),
+			});
+		}
+	);
 
 	// Update settings for current user
-	app.put<{ Body: SettingsBody }>("/settings", async (request, reply) => {
-		const userId = await getUserId(request, reply);
+	app.put<{ Body: SettingsBody }>(
+		"/settings",
+		{
+			schema: {
+				tags: ["settings"],
+				summary: "Update current user settings",
+				security: settingsEndpointSecurity,
+				body: {
+					type: "object",
+					required: ["emailEnabled", "notificationEmail", "reminderDaysBefore", "language"],
+					properties: {
+						emailEnabled: { type: "boolean" },
+						notificationEmail: { type: "string" },
+						reminderDaysBefore: { type: "number" },
+						repeatDailyReminders: { type: "boolean" },
+						lowStockDays: { type: "number" },
+						normalStockDays: { type: "number" },
+						highStockDays: { type: "number" },
+						shoutrrrEnabled: { type: "boolean" },
+						shoutrrrUrl: { type: "string" },
+						emailStockReminders: { type: "boolean" },
+						emailIntakeReminders: { type: "boolean" },
+						emailPrescriptionReminders: { type: "boolean" },
+						shoutrrrStockReminders: { type: "boolean" },
+						shoutrrrIntakeReminders: { type: "boolean" },
+						shoutrrrPrescriptionReminders: { type: "boolean" },
+						skipRemindersForTakenDoses: { type: "boolean" },
+						repeatRemindersEnabled: { type: "boolean" },
+						reminderRepeatIntervalMinutes: { type: "number" },
+						maxNaggingReminders: { type: "number" },
+						language: { type: "string", enum: ["en", "de"] },
+						stockCalculationMode: { type: "string", enum: ["automatic", "manual"] },
+						shareStockStatus: { type: "boolean" },
+						shareMedicationOverview: { type: "boolean" },
+						upcomingTodayOnly: { type: "boolean" },
+						shareScheduleTodayOnly: { type: "boolean" },
+						swapDashboardMainSections: { type: "boolean" },
+					},
+					example: {
+						emailEnabled: true,
+						notificationEmail: "daniel@example.com",
+						reminderDaysBefore: 7,
+						repeatDailyReminders: true,
+						lowStockDays: 14,
+						normalStockDays: 30,
+						highStockDays: 90,
+						shoutrrrEnabled: false,
+						shoutrrrUrl: "",
+						emailStockReminders: true,
+						emailIntakeReminders: true,
+						emailPrescriptionReminders: true,
+						shoutrrrStockReminders: false,
+						shoutrrrIntakeReminders: false,
+						shoutrrrPrescriptionReminders: false,
+						skipRemindersForTakenDoses: true,
+						repeatRemindersEnabled: true,
+						reminderRepeatIntervalMinutes: 30,
+						maxNaggingReminders: 5,
+						language: "en",
+						stockCalculationMode: "automatic",
+						shareStockStatus: true,
+						shareMedicationOverview: false,
+						upcomingTodayOnly: false,
+						shareScheduleTodayOnly: false,
+						swapDashboardMainSections: false,
+					},
+				},
+				response: {
+					200: { type: "object", properties: { success: { type: "boolean" } } },
+					401: settingsErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			const userId = await getUserId(request, reply);
 
-		const body = request.body;
+			const body = request.body;
 
-		// Check if any stock reminders are configured
-		const hasEmailStock = body.emailEnabled && body.emailStockReminders && body.notificationEmail;
-		const hasShoutrrrStock = body.shoutrrrEnabled && body.shoutrrrStockReminders && body.shoutrrrUrl;
-		const hasAnyStockReminder = hasEmailStock || hasShoutrrrStock;
+			// Check if any stock reminders are configured
+			const hasEmailStock = body.emailEnabled && body.emailStockReminders && body.notificationEmail;
+			const hasShoutrrrStock = body.shoutrrrEnabled && body.shoutrrrStockReminders && body.shoutrrrUrl;
+			const hasAnyStockReminder = hasEmailStock || hasShoutrrrStock;
 
-		// Disable repeatDailyReminders if no stock reminders are configured
-		const repeatDailyReminders = hasAnyStockReminder ? (body.repeatDailyReminders ?? false) : false;
+			// Disable repeatDailyReminders if no stock reminders are configured
+			const repeatDailyReminders = hasAnyStockReminder ? (body.repeatDailyReminders ?? false) : false;
 
-		// Update or insert user settings
-		const existingSettings = await db.select().from(userSettings).where(eq(userSettings.userId, userId));
+			// Update or insert user settings
+			const existingSettings = await db.select().from(userSettings).where(eq(userSettings.userId, userId));
 
-		const settingsData = {
-			emailEnabled: body.emailEnabled,
-			notificationEmail: body.notificationEmail || null,
-			emailStockReminders: body.emailStockReminders ?? true,
-			emailIntakeReminders: body.emailIntakeReminders ?? true,
-			emailPrescriptionReminders: body.emailPrescriptionReminders ?? true,
-			shoutrrrEnabled: body.shoutrrrEnabled ?? false,
-			shoutrrrUrl: body.shoutrrrUrl || null,
-			shoutrrrStockReminders: body.shoutrrrStockReminders ?? true,
-			shoutrrrIntakeReminders: body.shoutrrrIntakeReminders ?? true,
-			shoutrrrPrescriptionReminders: body.shoutrrrPrescriptionReminders ?? true,
-			reminderDaysBefore: body.reminderDaysBefore,
-			repeatDailyReminders,
-			skipRemindersForTakenDoses: body.skipRemindersForTakenDoses ?? false,
-			repeatRemindersEnabled: body.repeatRemindersEnabled ?? false,
-			reminderRepeatIntervalMinutes: body.reminderRepeatIntervalMinutes ?? 30,
-			maxNaggingReminders: body.maxNaggingReminders ?? 5,
-			lowStockDays: body.lowStockDays ?? 30,
-			normalStockDays: body.normalStockDays ?? 90,
-			highStockDays: body.highStockDays ?? 180,
-			language: body.language ?? "en",
-			stockCalculationMode: body.stockCalculationMode ?? "automatic",
-			shareStockStatus: body.shareStockStatus ?? true,
-			upcomingTodayOnly: body.upcomingTodayOnly ?? false,
-			shareScheduleTodayOnly: body.shareScheduleTodayOnly ?? false,
-			swapDashboardMainSections: body.swapDashboardMainSections ?? false,
-			updatedAt: new Date(),
-		};
+			const settingsData = {
+				emailEnabled: body.emailEnabled,
+				notificationEmail: body.notificationEmail || null,
+				emailStockReminders: body.emailStockReminders ?? true,
+				emailIntakeReminders: body.emailIntakeReminders ?? true,
+				emailPrescriptionReminders: body.emailPrescriptionReminders ?? true,
+				shoutrrrEnabled: body.shoutrrrEnabled ?? false,
+				shoutrrrUrl: body.shoutrrrUrl || null,
+				shoutrrrStockReminders: body.shoutrrrStockReminders ?? true,
+				shoutrrrIntakeReminders: body.shoutrrrIntakeReminders ?? true,
+				shoutrrrPrescriptionReminders: body.shoutrrrPrescriptionReminders ?? true,
+				reminderDaysBefore: body.reminderDaysBefore,
+				repeatDailyReminders,
+				skipRemindersForTakenDoses: body.skipRemindersForTakenDoses ?? false,
+				repeatRemindersEnabled: body.repeatRemindersEnabled ?? false,
+				reminderRepeatIntervalMinutes: body.reminderRepeatIntervalMinutes ?? 30,
+				maxNaggingReminders: body.maxNaggingReminders ?? 5,
+				lowStockDays: body.lowStockDays ?? 30,
+				normalStockDays: body.normalStockDays ?? 90,
+				highStockDays: body.highStockDays ?? 180,
+				language: body.language ?? "en",
+				stockCalculationMode: body.stockCalculationMode ?? "automatic",
+				shareStockStatus: body.shareStockStatus ?? true,
+				shareMedicationOverview: body.shareMedicationOverview ?? false,
+				upcomingTodayOnly: body.upcomingTodayOnly ?? false,
+				shareScheduleTodayOnly: body.shareScheduleTodayOnly ?? false,
+				swapDashboardMainSections: body.swapDashboardMainSections ?? false,
+				updatedAt: new Date(),
+			};
 
-		if (existingSettings.length > 0) {
-			await db.update(userSettings).set(settingsData).where(eq(userSettings.userId, userId));
-		} else {
-			await db.insert(userSettings).values({
-				userId: userId,
-				...settingsData,
-			});
+			if (existingSettings.length > 0) {
+				await db.update(userSettings).set(settingsData).where(eq(userSettings.userId, userId));
+			} else {
+				await db.insert(userSettings).values({
+					userId: userId,
+					...settingsData,
+				});
+			}
+
+			return reply.send({ success: true });
 		}
-
-		return reply.send({ success: true });
-	});
+	);
 
 	// Update only the language setting (lightweight, called on dropdown change)
-	app.put<{ Body: { language: string } }>("/settings/language", async (request, reply) => {
-		const userId = await getUserId(request, reply);
-		const { language } = request.body;
+	app.put<{ Body: { language: string } }>(
+		"/settings/language",
+		{
+			schema: {
+				tags: ["settings"],
+				summary: "Update UI language",
+				security: settingsEndpointSecurity,
+				body: {
+					type: "object",
+					required: ["language"],
+					properties: {
+						language: { type: "string", enum: ["en", "de"] },
+					},
+					example: {
+						language: "de",
+					},
+				},
+				response: {
+					200: { type: "object", properties: { success: { type: "boolean" } } },
+					400: settingsErrorSchema,
+					401: settingsErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			const userId = await getUserId(request, reply);
+			const { language } = request.body;
 
-		if (!language || !["en", "de"].includes(language)) {
-			return reply.status(400).send({ error: "Invalid language" });
+			if (!language || !["en", "de"].includes(language)) {
+				return reply.status(400).send({ error: "Invalid language" });
+			}
+
+			const existingSettings = await db.select().from(userSettings).where(eq(userSettings.userId, userId));
+
+			if (existingSettings.length > 0) {
+				await db.update(userSettings).set({ language, updatedAt: new Date() }).where(eq(userSettings.userId, userId));
+			} else {
+				await db.insert(userSettings).values({
+					userId,
+					...getDefaultSettings(),
+					language,
+				});
+			}
+
+			return reply.send({ success: true });
 		}
-
-		const existingSettings = await db.select().from(userSettings).where(eq(userSettings.userId, userId));
-
-		if (existingSettings.length > 0) {
-			await db.update(userSettings).set({ language, updatedAt: new Date() }).where(eq(userSettings.userId, userId));
-		} else {
-			await db.insert(userSettings).values({
-				userId,
-				...getDefaultSettings(),
-				language,
-			});
-		}
-
-		return reply.send({ success: true });
-	});
+	);
 
 	// Test email - use SMTP settings from process.env
-	app.post<{ Body: TestEmailBody }>("/settings/test-email", async (request, reply) => {
-		const { email } = request.body;
-
-		const smtpHost = process.env.SMTP_HOST;
-		const smtpUser = process.env.SMTP_USER;
-		const smtpPass = process.env.SMTP_TOKEN || process.env.SMTP_PASS;
-		const smtpPort = parseInt(process.env.SMTP_PORT ?? "587", 10);
-		const smtpSecure = process.env.SMTP_SECURE === "true";
-		const smtpFrom = process.env.SMTP_FROM ?? smtpUser;
-
-		request.log.info(
-			{
-				to: maskEmail(email),
-				hasSmtpHost: Boolean(smtpHost),
-				hasSmtpUser: Boolean(smtpUser),
-				hasSmtpPass: Boolean(smtpPass),
-				hasSmtpFrom: Boolean(smtpFrom),
-				smtpPort,
-				smtpSecure,
-			},
-			"[Settings] Test email request received"
-		);
-
-		if (!smtpHost || !smtpUser) {
-			request.log.warn(
-				{ to: maskEmail(email), hasSmtpHost: Boolean(smtpHost), hasSmtpUser: Boolean(smtpUser) },
-				"[Settings] Test email skipped: SMTP not configured"
-			);
-			return reply.status(400).send({ error: "SMTP not configured" });
-		}
-
-		try {
-			const transporter = nodemailer.createTransport({
-				host: smtpHost,
-				port: smtpPort,
-				secure: smtpSecure,
-				auth: {
-					user: smtpUser,
-					pass: smtpPass ?? "",
+	app.post<{ Body: TestEmailBody }>(
+		"/settings/test-email",
+		{
+			schema: {
+				tags: ["settings"],
+				summary: "Send test email",
+				description: "Sends a test message using configured SMTP settings.",
+				security: settingsEndpointSecurity,
+				body: {
+					type: "object",
+					required: ["email"],
+					properties: {
+						email: { type: "string", format: "email" },
+					},
+					example: {
+						email: "daniel@example.com",
+					},
 				},
-			});
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							success: { type: "boolean" },
+							message: { type: "string" },
+						},
+					},
+					400: settingsErrorSchema,
+					401: settingsErrorSchema,
+					500: settingsErrorSchema,
+					502: settingsErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			const { email } = request.body;
 
-			request.log.info({ to: maskEmail(email) }, "[Settings] Sending test email");
+			const smtpHost = process.env.SMTP_HOST;
+			const smtpUser = process.env.SMTP_USER;
+			const smtpPass = process.env.SMTP_TOKEN || process.env.SMTP_PASS;
+			const smtpPort = parseInt(process.env.SMTP_PORT ?? "587", 10);
+			const smtpSecure = process.env.SMTP_SECURE === "true";
+			const smtpFrom = process.env.SMTP_FROM ?? smtpUser;
 
-			const mailResult = await transporter.sendMail({
-				from: smtpFrom,
-				to: email,
-				subject: "MedAssist-ng - Test Email",
-				text: "This is a test email from MedAssist-ng. If you received this, your email configuration is working correctly!",
-				html: `
+			request.log.info(
+				{
+					to: maskEmail(email),
+					hasSmtpHost: Boolean(smtpHost),
+					hasSmtpUser: Boolean(smtpUser),
+					hasSmtpPass: Boolean(smtpPass),
+					hasSmtpFrom: Boolean(smtpFrom),
+					smtpPort,
+					smtpSecure,
+				},
+				"[Settings] Test email request received"
+			);
+
+			if (!smtpHost || !smtpUser) {
+				request.log.warn(
+					{ to: maskEmail(email), hasSmtpHost: Boolean(smtpHost), hasSmtpUser: Boolean(smtpUser) },
+					"[Settings] Test email skipped: SMTP not configured"
+				);
+				return reply.status(400).send({ error: "SMTP not configured" });
+			}
+
+			try {
+				const transporter = nodemailer.createTransport({
+					host: smtpHost,
+					port: smtpPort,
+					secure: smtpSecure,
+					auth: {
+						user: smtpUser,
+						pass: smtpPass ?? "",
+					},
+				});
+
+				request.log.info({ to: maskEmail(email) }, "[Settings] Sending test email");
+
+				const mailResult = await transporter.sendMail({
+					from: smtpFrom,
+					to: email,
+					subject: "MedAssist-ng - Test Email",
+					text: "This is a test email from MedAssist-ng. If you received this, your email configuration is working correctly!",
+					html: `
           <div style="font-family: system-ui, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
             <h2 style="color: #2563eb;">MedAssist-ng - Test Email</h2>
             <p>This is a test email from MedAssist-ng.</p>
@@ -521,55 +723,89 @@ export async function settingsRoutes(app: FastifyInstance) {
             <p style="color: #6b7280; font-size: 14px;">Sent from MedAssist-ng Medication Planner</p>
           </div>
         `,
-			});
+				});
 
-			const deliveryError = getDeliveryError(mailResult);
-			if (deliveryError) {
-				throw new Error(deliveryError);
+				const deliveryError = getDeliveryError(mailResult);
+				if (deliveryError) {
+					throw new Error(deliveryError);
+				}
+
+				request.log.info({ to: maskEmail(email), messageId: mailResult.messageId }, "[Settings] Test email sent");
+
+				return reply.send({ success: true, message: "Test email sent successfully" });
+			} catch (error) {
+				request.log.error({ error, to: maskEmail(email) }, "[Settings] Test email failed");
+				const failure = classifyTestEmailFailure(error);
+				return reply.status(failure.status).send({ error: failure.message, code: failure.code });
 			}
-
-			request.log.info({ to: maskEmail(email), messageId: mailResult.messageId }, "[Settings] Test email sent");
-
-			return reply.send({ success: true, message: "Test email sent successfully" });
-		} catch (error) {
-			request.log.error({ error, to: maskEmail(email) }, "[Settings] Test email failed");
-			const errorMessage = error instanceof Error ? error.message : "Unknown error";
-			return reply.status(500).send({ error: `Failed to send email: ${errorMessage}` });
 		}
-	});
+	);
 
 	// Test Shoutrrr/ntfy notification
-	app.post<{ Body: TestShoutrrrBody }>("/settings/test-shoutrrr", async (request, reply) => {
-		const { url } = request.body;
+	app.post<{ Body: TestShoutrrrBody }>(
+		"/settings/test-shoutrrr",
+		{
+			schema: {
+				tags: ["settings"],
+				summary: "Send test push notification",
+				description: "Sends a test notification via a Shoutrrr-compatible URL.",
+				security: settingsEndpointSecurity,
+				body: {
+					type: "object",
+					required: ["url"],
+					properties: {
+						url: { type: "string" },
+					},
+					example: {
+						url: "ntfy://user:token@push.example.com/medassist",
+					},
+				},
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							success: { type: "boolean" },
+							message: { type: "string" },
+						},
+					},
+					400: settingsErrorSchema,
+					401: settingsErrorSchema,
+					500: settingsErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			const { url } = request.body;
 
-		if (!url) {
-			return reply.status(400).send({ error: "Notification URL is required" });
-		}
-
-		try {
-			const provider = getNotificationProvider(url);
-			const result = await sendShoutrrrNotification(
-				url,
-				"MedAssist-ng Test",
-				"This is a test notification from MedAssist-ng. If you received this, your notification configuration is working correctly!"
-			);
-
-			if (result.success) {
-				request.log.info({ provider }, "[Settings] Test push notification sent");
-				return reply.send({ success: true, message: "Test notification sent successfully" });
-			} else {
-				request.log.warn({ provider, error: result.error ?? "unknown" }, "[Settings] Test push notification failed");
-				return reply.status(500).send({ error: result.error });
+			if (!url) {
+				return reply.status(400).send({ error: "Notification URL is required" });
+			}
+
+			try {
+				const provider = getNotificationProvider(url);
+				const result = await sendShoutrrrNotification(
+					url,
+					"MedAssist-ng Test",
+					"This is a test notification from MedAssist-ng. If you received this, your notification configuration is working correctly!"
+				);
+
+				if (result.success) {
+					request.log.info({ provider }, "[Settings] Test push notification sent");
+					return reply.send({ success: true, message: "Test notification sent successfully" });
+				} else {
+					request.log.warn({ provider, error: result.error ?? "unknown" }, "[Settings] Test push notification failed");
+					return reply.status(500).send({ error: result.error });
+				}
+			} catch (error) {
+				request.log.error(
+					{ provider: getNotificationProvider(url), error },
+					"[Settings] Unexpected error while sending test push notification"
+				);
+				const errorMessage = error instanceof Error ? error.message : "Unknown error";
+				return reply.status(500).send({ error: `Failed to send notification: ${errorMessage}` });
 			}
-		} catch (error) {
-			request.log.error(
-				{ provider: getNotificationProvider(url), error },
-				"[Settings] Unexpected error while sending test push notification"
-			);
-			const errorMessage = error instanceof Error ? error.message : "Unknown error";
-			return reply.status(500).send({ error: `Failed to send notification: ${errorMessage}` });
 		}
-	});
+	);
 }
 
 // Validate and sanitize URL to prevent SSRF attacks

backend/src/routes/share.ts

@@ -3,10 +3,18 @@ import { and, eq } from "drizzle-orm";
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 import { z } from "zod";
 import { db } from "../db/client.js";
-import { medications, shareTokens, userSettings, users } from "../db/schema.js";
+import { doseTracking, medications, shareTokens, userSettings, users } from "../db/schema.js";
 import { getAnonymousUserId, requireAuth } from "../plugins/auth.js";
 import { env } from "../plugins/env.js";
+import { buildSharedMedicationOverview } from "../services/coverage.js";
 import type { AuthUser } from "../types/fastify.js";
+import {
+	applyOpenApiRouteStandards,
+	genericErrorSchema,
+	tokenParamsSchema,
+	validationErrorSchema,
+} from "../utils/openapi-route-standards.js";
+import { isAmountBasedPackageType, normalizePackageType } from "../utils/package-profiles.js";
 import {
 	getAllTakenByForMedication,
 	parseIntakesJson,
@@ -22,6 +30,73 @@ const createShareSchema = z.object({
 	scheduleDays: z.number().int().min(1).max(365).default(30),
 });
 
+const protectedEndpointSecurity: ReadonlyArray<Record<string, readonly string[]>> = [
+	{ bearerAuth: [] },
+	{ cookieAuth: [] },
+];
+
+const shareTokenPattern = /^[a-f0-9]{16}$/;
+
+const createShareBodyOpenApiSchema = {
+	type: "object",
+	properties: {
+		takenBy: { type: "string" },
+		scheduleDays: { type: "integer", minimum: 1, maximum: 365, default: 30 },
+	},
+	example: {
+		takenBy: "Daniel",
+		scheduleDays: 14,
+	},
+} as const;
+
+const shareReadResponseSchema = {
+	type: "object",
+	properties: {
+		takenBy: { type: "string" },
+		sharedBy: { type: "string" },
+		scheduleDays: { type: "integer" },
+		medications: { type: "array", items: { type: "object", additionalProperties: true } },
+		shareMedicationOverview: { type: "boolean" },
+		medicationOverview: {
+			anyOf: [{ type: "array", items: { type: "object", additionalProperties: true } }, { type: "null" }],
+		},
+		stockThresholds: { type: "object", additionalProperties: { type: "number" } },
+		stockCalculationMode: { type: "string", enum: ["automatic", "manual"] },
+		shareStockStatus: { type: "boolean" },
+		upcomingTodayOnly: { type: "boolean" },
+		shareScheduleTodayOnly: { type: "boolean" },
+	},
+} as const;
+
+const shareExpiredResponseSchema = {
+	type: "object",
+	properties: {
+		error: { type: "string" },
+		code: { type: "string" },
+		ownerUsername: { type: "string" },
+		takenBy: { type: "string" },
+		expiredAt: { type: "string", format: "date-time" },
+	},
+} as const;
+
+const shareOverviewExpiredResponseSchema = {
+	type: "object",
+	properties: {
+		error: { type: "string" },
+		expiredAt: { type: "string", format: "date-time" },
+	},
+} as const;
+
+const shareOverviewResponseSchema = {
+	type: "object",
+	properties: {
+		takenBy: { type: "string" },
+		sharedBy: { type: "string" },
+		generatedAt: { type: "string", format: "date-time" },
+		medications: { type: "array", items: { type: "object", additionalProperties: true } },
+	},
+} as const;
+
 function maskToken(token: string): string {
 	if (token.length <= 8) return token;
 	return `${token.slice(0, 4)}...${token.slice(-4)}`;
@@ -47,132 +122,266 @@ async function getUserId(request: FastifyRequest, reply: FastifyReply): Promise<
 // Share Routes
 // =============================================================================
 export async function shareRoutes(app: FastifyInstance) {
+	applyOpenApiRouteStandards(app, {
+		tag: "share",
+		protectedByDefault: false,
+		protectedPaths: [/^\/share$/, /^\/share\/people$/],
+	});
+
 	// ---------------------------------------------------------------------------
 	// GET /share/:token - PUBLIC: Get shared schedule by token
 	// ---------------------------------------------------------------------------
-	app.get<{ Params: { token: string } }>("/share/:token", async (request, reply) => {
-		const { token } = request.params;
+	app.get<{ Params: { token: string } }>(
+		"/share/:token",
+		{
+			schema: {
+				params: tokenParamsSchema,
+				response: {
+					200: shareReadResponseSchema,
+					404: genericErrorSchema,
+					410: shareExpiredResponseSchema,
+				},
+			},
+			config: {
+				rateLimit: {
+					max: 60,
+					timeWindow: "1 minute",
+					errorResponseBuilder: () => ({ error: "rate_limited" }),
+				},
+			},
+		},
+		async (request, reply) => {
+			const { token } = request.params;
 
-		// Find share token
-		const [share] = await db.select().from(shareTokens).where(eq(shareTokens.token, token));
-		if (!share) {
-			request.log.warn(`[Share] Invalid share token requested: ${maskToken(token)}`);
-			return reply.status(404).send({
-				error: "Share link not found",
-				code: "NOT_FOUND",
-			});
-		}
+			// Find share token
+			const [share] = await db.select().from(shareTokens).where(eq(shareTokens.token, token));
+			if (!share) {
+				request.log.warn(`[Share] Invalid share token requested: ${maskToken(token)}`);
+				return reply.status(404).send({
+					error: "Share link not found",
+					code: "NOT_FOUND",
+				});
+			}
 
-		// Check if token has expired
-		if (share.expiresAt && share.expiresAt.getTime() < Date.now()) {
-			request.log.warn(
-				`[Share] Expired token requested: ${maskToken(token)} (owner=${share.userId}, takenBy=${share.takenBy})`
-			);
-			// Get the username of the owner to show in the expired message
+			// Check if token has expired
+			if (share.expiresAt && share.expiresAt.getTime() < Date.now()) {
+				request.log.warn(
+					`[Share] Expired token requested: ${maskToken(token)} (owner=${share.userId}, takenBy=${share.takenBy})`
+				);
+				// Get the username of the owner to show in the expired message
+				const [owner] = await db.select({ username: users.username }).from(users).where(eq(users.id, share.userId));
+				return reply.status(410).send({
+					error: "Share link has expired",
+					code: "EXPIRED",
+					ownerUsername: owner?.username ?? "the owner",
+					takenBy: share.takenBy,
+					expiredAt: share.expiresAt.toISOString(),
+				});
+			}
+
+			// Get user settings for stock thresholds
+			const [settings] = await db.select().from(userSettings).where(eq(userSettings.userId, share.userId));
+
+			// Get the username of the owner who created this share link
 			const [owner] = await db.select({ username: users.username }).from(users).where(eq(users.id, share.userId));
-			return reply.status(410).send({
-				error: "Share link has expired",
-				code: "EXPIRED",
-				ownerUsername: owner?.username ?? "the owner",
-				takenBy: share.takenBy,
-				expiredAt: share.expiresAt.toISOString(),
+
+			// Get medications for this user filtered by takenBy (search in JSON array)
+			// Use SQLite JSON function to check if takenBy is in the array
+			const allMeds = await db.select().from(medications).where(eq(medications.userId, share.userId));
+
+			// Filter medications where takenBy matches either medication-level OR any intake-level takenBy
+			const meds = allMeds.filter((med) => {
+				const takenByArray = parseTakenByJson(med.takenByJson);
+				const intakes = parseIntakesJson(
+					med.intakesJson,
+					{ usageJson: med.usageJson, everyJson: med.everyJson, startJson: med.startJson },
+					med.intakeRemindersEnabled ?? false
+				);
+				return personTakesMedication(share.takenBy, takenByArray, intakes);
 			});
-		}
 
-		// Get user settings for stock thresholds
-		const [settings] = await db.select().from(userSettings).where(eq(userSettings.userId, share.userId));
+			// Parse blisters and build schedule data
+			const medicationsWithBlisters = meds.map((med) => {
+				// Parse intakes from new format, falling back to legacy
+				const intakes = parseIntakesJson(
+					med.intakesJson,
+					{ usageJson: med.usageJson, everyJson: med.everyJson, startJson: med.startJson },
+					med.intakeRemindersEnabled ?? false
+				);
 
-		// Get the username of the owner who created this share link
-		const [owner] = await db.select({ username: users.username }).from(users).where(eq(users.id, share.userId));
+				// Convert to legacy blisters format for backward compat
+				const blisters = intakes.map((i) => ({
+					usage: i.usage,
+					every: i.every,
+					start: i.start,
+				}));
 
-		// Get medications for this user filtered by takenBy (search in JSON array)
-		// Use SQLite JSON function to check if takenBy is in the array
-		const allMeds = await db.select().from(medications).where(eq(medications.userId, share.userId));
+				// Parse takenBy JSON array
+				const takenByArray = parseTakenByJson(med.takenByJson);
 
-		// Filter medications where takenBy matches either medication-level OR any intake-level takenBy
-		const meds = allMeds.filter((med) => {
-			const takenByArray = parseTakenByJson(med.takenByJson);
-			const intakes = parseIntakesJson(
-				med.intakesJson,
-				{ usageJson: med.usageJson, everyJson: med.everyJson, startJson: med.startJson },
-				med.intakeRemindersEnabled ?? false
-			);
-			return personTakesMedication(share.takenBy, takenByArray, intakes);
-		});
-
-		// Parse blisters and build schedule data
-		const medicationsWithBlisters = meds.map((med) => {
-			// Parse intakes from new format, falling back to legacy
-			const intakes = parseIntakesJson(
-				med.intakesJson,
-				{ usageJson: med.usageJson, everyJson: med.everyJson, startJson: med.startJson },
-				med.intakeRemindersEnabled ?? false
-			);
-
-			// Convert to legacy blisters format for backward compat
-			const blisters = intakes.map((i) => ({
-				usage: i.usage,
-				every: i.every,
-				start: i.start,
-			}));
-
-			// Parse takenBy JSON array
-			const takenByArray = parseTakenByJson(med.takenByJson);
-
-			const totalPills =
-				(med.packageType ?? "blister") === "bottle" ||
-				(med.packageType ?? "blister") === "tube" ||
-				(med.packageType ?? "blister") === "liquid_container"
+				const totalPills = isAmountBasedPackageType(med.packageType)
 					? med.looseTablets + (med.stockAdjustment ?? 0)
 					: med.packCount * med.blistersPerPack * med.pillsPerBlister + med.looseTablets + (med.stockAdjustment ?? 0);
-			return {
-				id: med.id,
-				name: med.name,
-				genericName: med.genericName,
-				pillWeightMg: med.pillWeightMg,
-				doseUnit: med.doseUnit ?? "mg",
-				imageUrl: med.imageUrl,
-				totalPills,
-				packageType: med.packageType ?? "blister",
-				packCount: med.packCount,
-				blistersPerPack: med.blistersPerPack,
-				looseTablets: med.looseTablets,
-				pillsPerBlister: med.pillsPerBlister,
-				takenBy: takenByArray,
-				intakes, // New unified format with per-intake takenBy
-				blisters, // Legacy format for backward compat
-				dismissedUntil: med.dismissedUntil,
-				updatedAt: med.updatedAt, // For filtering out doses from previous schedule configurations
-				lastStockCorrectionAt: med.lastStockCorrectionAt?.getTime() ?? null,
-				stockAdjustment: med.stockAdjustment ?? 0,
-			};
-		});
+				return {
+					id: med.id,
+					name: med.name,
+					genericName: med.genericName,
+					pillWeightMg: med.pillWeightMg,
+					doseUnit: med.doseUnit ?? "mg",
+					imageUrl: med.imageUrl,
+					totalPills,
+					packageType: normalizePackageType(med.packageType),
+					packCount: med.packCount,
+					blistersPerPack: med.blistersPerPack,
+					looseTablets: med.looseTablets,
+					pillsPerBlister: med.pillsPerBlister,
+					takenBy: takenByArray,
+					intakes, // New unified format with per-intake takenBy
+					blisters, // Legacy format for backward compat
+					dismissedUntil: med.dismissedUntil,
+					updatedAt: med.updatedAt, // For filtering out doses from previous schedule configurations
+					lastStockCorrectionAt: med.lastStockCorrectionAt?.getTime() ?? null,
+					stockAdjustment: med.stockAdjustment ?? 0,
+				};
+			});
 
-		return {
-			takenBy: share.takenBy,
-			sharedBy: owner?.username ?? null,
-			scheduleDays: share.scheduleDays,
-			medications: medicationsWithBlisters,
-			stockThresholds: {
-				lowStockDays: settings?.lowStockDays ?? 30,
-				normalStockDays: settings?.normalStockDays ?? 60,
-				highStockDays: settings?.highStockDays ?? 90,
-				reminderDaysBefore: settings?.reminderDaysBefore ?? 7,
-				expiryWarningDays: settings?.expiryWarningDays ?? 90,
+			const shareMedicationOverview = settings?.shareMedicationOverview ?? false;
+			const medicationOverview = shareMedicationOverview
+				? buildSharedMedicationOverview({
+						medications: meds,
+						doses: await db.select().from(doseTracking).where(eq(doseTracking.userId, share.userId)),
+						thresholdDays: settings?.lowStockDays ?? 30,
+						showStockStatus: settings?.shareStockStatus ?? true,
+					})
+				: null;
+
+			return {
+				takenBy: share.takenBy,
+				sharedBy: owner?.username ?? null,
+				scheduleDays: share.scheduleDays,
+				medications: medicationsWithBlisters,
+				shareMedicationOverview,
+				medicationOverview,
+				stockThresholds: {
+					lowStockDays: settings?.lowStockDays ?? 30,
+					normalStockDays: settings?.normalStockDays ?? 60,
+					highStockDays: settings?.highStockDays ?? 90,
+					reminderDaysBefore: settings?.reminderDaysBefore ?? 7,
+					expiryWarningDays: settings?.expiryWarningDays ?? 90,
+				},
+				stockCalculationMode: (settings?.stockCalculationMode as "automatic" | "manual") ?? "automatic",
+				shareStockStatus: settings?.shareStockStatus ?? true,
+				upcomingTodayOnly: settings?.upcomingTodayOnly ?? false,
+				shareScheduleTodayOnly: settings?.shareScheduleTodayOnly ?? false,
+			};
+		}
+	);
+
+	// ---------------------------------------------------------------------------
+	// GET /share/:token/overview - PUBLIC: Read-only medication overview by token
+	// ---------------------------------------------------------------------------
+	app.get<{ Params: { token: string } }>(
+		"/share/:token/overview",
+		{
+			schema: {
+				params: tokenParamsSchema,
+				response: {
+					200: shareOverviewResponseSchema,
+					404: genericErrorSchema,
+					410: shareOverviewExpiredResponseSchema,
+				},
 			},
-			stockCalculationMode: (settings?.stockCalculationMode as "automatic" | "manual") ?? "automatic",
-			shareStockStatus: settings?.shareStockStatus ?? true,
-			upcomingTodayOnly: settings?.upcomingTodayOnly ?? false,
-			shareScheduleTodayOnly: settings?.shareScheduleTodayOnly ?? false,
-		};
-	});
+			config: {
+				rateLimit: {
+					max: 60,
+					timeWindow: "1 minute",
+					errorResponseBuilder: () => ({ error: "rate_limited" }),
+				},
+			},
+		},
+		async (request, reply) => {
+			reply.header("Cache-Control", "no-store");
+
+			const { token } = request.params;
+			if (!shareTokenPattern.test(token)) {
+				request.log.warn(`[ShareOverview] Rejected invalid token format: ${maskToken(token)}`);
+				return reply.status(404).send({ error: "not_found" });
+			}
+
+			const [share] = await db.select().from(shareTokens).where(eq(shareTokens.token, token));
+			if (!share) {
+				request.log.warn(`[ShareOverview] Unknown token requested: ${maskToken(token)}`);
+				return reply.status(404).send({ error: "not_found" });
+			}
+
+			if (share.expiresAt && share.expiresAt.getTime() < Date.now()) {
+				request.log.warn(
+					`[ShareOverview] Expired token requested: ${maskToken(token)} (owner=${share.userId}, takenBy=${share.takenBy})`
+				);
+				return reply.status(410).send({
+					error: "expired",
+					expiredAt: share.expiresAt.toISOString(),
+				});
+			}
+
+			const [settings] = await db.select().from(userSettings).where(eq(userSettings.userId, share.userId));
+			const [owner] = await db.select({ username: users.username }).from(users).where(eq(users.id, share.userId));
+
+			const allMeds = await db.select().from(medications).where(eq(medications.userId, share.userId));
+			const meds = allMeds.filter((med) => {
+				const takenByArray = parseTakenByJson(med.takenByJson);
+				const intakes = parseIntakesJson(
+					med.intakesJson,
+					{ usageJson: med.usageJson, everyJson: med.everyJson, startJson: med.startJson },
+					med.intakeRemindersEnabled ?? false
+				);
+				return personTakesMedication(share.takenBy, takenByArray, intakes);
+			});
+
+			const doses = await db.select().from(doseTracking).where(eq(doseTracking.userId, share.userId));
+
+			const overview = buildSharedMedicationOverview({
+				medications: meds,
+				doses,
+				thresholdDays: settings?.lowStockDays ?? 30,
+				showStockStatus: settings?.shareStockStatus ?? true,
+			});
+
+			return {
+				takenBy: share.takenBy,
+				sharedBy: owner?.username ?? null,
+				generatedAt: new Date().toISOString(),
+				medications: overview,
+			};
+		}
+	);
 
 	// ---------------------------------------------------------------------------
 	// POST /share - PROTECTED: Create a new share link
 	// ---------------------------------------------------------------------------
 	app.post<{ Body: z.infer<typeof createShareSchema> }>(
 		"/share",
-		{ preHandler: requireAuth },
+		{
+			preHandler: requireAuth,
+			schema: {
+				tags: ["share"],
+				security: protectedEndpointSecurity,
+				body: createShareBodyOpenApiSchema,
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							reused: { type: "boolean" },
+							token: { type: "string" },
+							shareUrl: { type: "string" },
+							expiresAt: { type: ["string", "null"] },
+						},
+					},
+					400: { anyOf: [genericErrorSchema, validationErrorSchema] },
+					401: genericErrorSchema,
+				},
+			},
+		},
 		async (request, reply) => {
 			const userId = await getUserId(request, reply);
 
@@ -253,37 +462,56 @@ export async function shareRoutes(app: FastifyInstance) {
 	// ---------------------------------------------------------------------------
 	// GET /share/people - PROTECTED: Get list of unique takenBy values
 	// ---------------------------------------------------------------------------
-	app.get("/share/people", { preHandler: requireAuth }, async (request, reply) => {
-		const userId = await getUserId(request, reply);
+	app.get(
+		"/share/people",
+		{
+			preHandler: requireAuth,
+			schema: {
+				tags: ["share"],
+				security: protectedEndpointSecurity,
+				response: {
+					200: {
+						type: "object",
+						properties: {
+							people: { type: "array", items: { type: "string" } },
+						},
+					},
+					401: genericErrorSchema,
+				},
+			},
+		},
+		async (request, reply) => {
+			const userId = await getUserId(request, reply);
 
-		// Get all unique takenBy values for this user (from both medication-level and intake-level)
-		const meds = await db
-			.select({
-				takenByJson: medications.takenByJson,
-				intakesJson: medications.intakesJson,
-				usageJson: medications.usageJson,
-				everyJson: medications.everyJson,
-				startJson: medications.startJson,
-				intakeRemindersEnabled: medications.intakeRemindersEnabled,
-			})
-			.from(medications)
-			.where(eq(medications.userId, userId));
+			// Get all unique takenBy values for this user (from both medication-level and intake-level)
+			const meds = await db
+				.select({
+					takenByJson: medications.takenByJson,
+					intakesJson: medications.intakesJson,
+					usageJson: medications.usageJson,
+					everyJson: medications.everyJson,
+					startJson: medications.startJson,
+					intakeRemindersEnabled: medications.intakeRemindersEnabled,
+				})
+				.from(medications)
+				.where(eq(medications.userId, userId));
 
-		// Collect all unique person names from medication-level AND intake-level takenBy
-		const allPeople = new Set<string>();
-		for (const med of meds) {
-			const takenByArray = parseTakenByJson(med.takenByJson);
-			const intakes = parseIntakesJson(
-				med.intakesJson,
-				{ usageJson: med.usageJson, everyJson: med.everyJson, startJson: med.startJson },
-				med.intakeRemindersEnabled ?? false
-			);
-			const allForMed = getAllTakenByForMedication(takenByArray, intakes);
-			for (const person of allForMed) {
-				if (person) allPeople.add(person);
+			// Collect all unique person names from medication-level AND intake-level takenBy
+			const allPeople = new Set<string>();
+			for (const med of meds) {
+				const takenByArray = parseTakenByJson(med.takenByJson);
+				const intakes = parseIntakesJson(
+					med.intakesJson,
+					{ usageJson: med.usageJson, everyJson: med.everyJson, startJson: med.startJson },
+					med.intakeRemindersEnabled ?? false
+				);
+				const allForMed = getAllTakenByForMedication(takenByArray, intakes);
+				for (const person of allForMed) {
+					if (person) allPeople.add(person);
+				}
 			}
-		}
 
-		return { people: [...allPeople].sort() };
-	});
+			return { people: [...allPeople].sort() };
+		}
+	);
 }

backend/src/services/coverage.ts

@@ -0,0 +1,220 @@
+import type { doseTracking, medications } from "../db/schema.js";
+import { isAmountBasedPackageType } from "../utils/package-profiles.js";
+import {
+	getTodayInTimezone,
+	type Intake,
+	normalizeIntakeUsageForStock,
+	parseIntakesJson,
+	parseLocalDateTime,
+} from "../utils/scheduler-utils.js";
+
+const MS_PER_DAY = 86_400_000;
+const doseIdPattern = /^(\d+)-(\d+)-(\d+)(?:-(.+))?$/;
+
+type MedicationRow = typeof medications.$inferSelect;
+type DoseRow = typeof doseTracking.$inferSelect;
+
+export type SharedMedicationOverviewItem = {
+	name: string;
+	genericName: string | null;
+	imageUrl: string | null;
+	packageType: string;
+	packCount: number;
+	blistersPerPack: number;
+	pillsPerBlister: number;
+	totalPills: number | null;
+	looseTablets: number;
+	currentStock: number | null;
+	capacity: number | null;
+	daysLeft: number | null;
+	nextIntakeDate: string | null;
+	depletionDate: string | null;
+	priority: "normal" | "high" | "out-of-stock" | null;
+	expiryDate: string | null;
+	medicationStartDate: string | null;
+	prescriptionEnabled: boolean;
+	prescriptionRemainingRefills: number | null;
+};
+
+function toDateOnlyString(date: Date): string {
+	const year = date.getFullYear();
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${year}-${month}-${day}`;
+}
+
+function parseDateOnly(dateOnly: string): Date {
+	const [year, month, day] = dateOnly.split("-").map((value) => Number.parseInt(value, 10));
+	return new Date(year, month - 1, day, 0, 0, 0, 0);
+}
+
+function computeCapacity(medication: MedicationRow): number {
+	if (isAmountBasedPackageType(medication.packageType)) {
+		return medication.totalPills ?? medication.looseTablets;
+	}
+
+	return medication.packCount * medication.blistersPerPack * medication.pillsPerBlister;
+}
+
+function computeDailyDoseRate(intakes: Intake[], medication: MedicationRow): number {
+	return intakes.reduce((sum, intake) => {
+		if (intake.every <= 0) return sum;
+		const normalizedUsage = normalizeIntakeUsageForStock(intake, medication.medicationForm, medication.packageType);
+		return sum + normalizedUsage / intake.every;
+	}, 0);
+}
+
+function computeNextIntakeDate(intakes: Intake[], todayDateOnly: string): string | null {
+	const today = parseDateOnly(todayDateOnly);
+	let nextDate: Date | null = null;
+
+	for (const intake of intakes) {
+		if (intake.every <= 0) continue;
+
+		const startDate = parseLocalDateTime(intake.start);
+		const startDateOnly = new Date(startDate.getFullYear(), startDate.getMonth(), startDate.getDate(), 0, 0, 0, 0);
+
+		let candidate = startDateOnly;
+		if (candidate.getTime() < today.getTime()) {
+			const elapsedDays = Math.floor((today.getTime() - candidate.getTime()) / MS_PER_DAY);
+			const intervals = Math.ceil(elapsedDays / intake.every);
+			candidate = new Date(candidate.getTime() + intervals * intake.every * MS_PER_DAY);
+		}
+
+		if (!nextDate || candidate.getTime() < nextDate.getTime()) {
+			nextDate = candidate;
+		}
+	}
+
+	return nextDate ? toDateOnlyString(nextDate) : null;
+}
+
+function computeTakenAmount(
+	medication: MedicationRow,
+	intakes: Intake[],
+	dosesByMedication: Map<number, DoseRow[]>
+): number {
+	const doseRows = dosesByMedication.get(medication.id) ?? [];
+	if (doseRows.length === 0) return 0;
+
+	const correctionDateOnlyMs = medication.lastStockCorrectionAt
+		? new Date(
+				medication.lastStockCorrectionAt.getFullYear(),
+				medication.lastStockCorrectionAt.getMonth(),
+				medication.lastStockCorrectionAt.getDate(),
+				0,
+				0,
+				0,
+				0
+			).getTime()
+		: 0;
+
+	let takenAmount = 0;
+	for (const dose of doseRows) {
+		if (dose.dismissed) continue;
+
+		const match = doseIdPattern.exec(dose.doseId);
+		if (!match) continue;
+
+		const intakeIndex = Number.parseInt(match[2], 10);
+		const doseDateOnlyMs = Number.parseInt(match[3], 10);
+		if (Number.isNaN(intakeIndex) || Number.isNaN(doseDateOnlyMs)) continue;
+		if (doseDateOnlyMs < correctionDateOnlyMs) continue;
+
+		const intake = intakes[intakeIndex];
+		if (!intake) continue;
+
+		takenAmount += normalizeIntakeUsageForStock(intake, medication.medicationForm, medication.packageType);
+	}
+
+	return takenAmount;
+}
+
+function toNullableDate(value: string | null): string | null {
+	if (!value) return null;
+	return value.trim() ? value : null;
+}
+
+function computeOverviewPriority(
+	currentStock: number,
+	daysLeft: number | null,
+	thresholdDays: number
+): "normal" | "high" | "out-of-stock" {
+	if (currentStock <= 0 || daysLeft === 0) return "out-of-stock";
+	if (daysLeft !== null && daysLeft <= thresholdDays) return "high";
+	return "normal";
+}
+
+export function buildSharedMedicationOverview(options: {
+	medications: MedicationRow[];
+	doses: DoseRow[];
+	thresholdDays: number;
+	showStockStatus?: boolean;
+}): SharedMedicationOverviewItem[] {
+	const { medications: medicationRows, doses, thresholdDays, showStockStatus = true } = options;
+
+	const dosesByMedication = new Map<number, DoseRow[]>();
+	for (const dose of doses) {
+		const match = doseIdPattern.exec(dose.doseId);
+		if (!match) continue;
+
+		const medicationId = Number.parseInt(match[1], 10);
+		if (Number.isNaN(medicationId)) continue;
+
+		const existing = dosesByMedication.get(medicationId) ?? [];
+		existing.push(dose);
+		dosesByMedication.set(medicationId, existing);
+	}
+
+	const todayDateOnly = getTodayInTimezone();
+	const todayDate = parseDateOnly(todayDateOnly);
+
+	return medicationRows.map((medication) => {
+		const intakes = parseIntakesJson(
+			medication.intakesJson,
+			{
+				usageJson: medication.usageJson,
+				everyJson: medication.everyJson,
+				startJson: medication.startJson,
+			},
+			medication.intakeRemindersEnabled ?? false
+		);
+
+		const capacity = computeCapacity(medication);
+		const dailyDoseRate = computeDailyDoseRate(intakes, medication);
+		const takenAmount = computeTakenAmount(medication, intakes, dosesByMedication);
+		const rawCurrentStock = capacity + (medication.stockAdjustment ?? 0) - takenAmount;
+		const currentStock = Math.max(0, Math.floor(rawCurrentStock));
+		const daysLeft = dailyDoseRate > 0 ? Math.floor(currentStock / dailyDoseRate) : null;
+		const depletionDate =
+			daysLeft === null ? null : toDateOnlyString(new Date(todayDate.getTime() + daysLeft * MS_PER_DAY));
+		const priority = computeOverviewPriority(currentStock, daysLeft, thresholdDays);
+		const visibleCurrentStock = showStockStatus ? currentStock : null;
+		const visibleCapacity = showStockStatus ? capacity : null;
+		const visibleDaysLeft = showStockStatus ? daysLeft : null;
+		const visibleDepletionDate = showStockStatus ? depletionDate : null;
+		const visiblePriority = showStockStatus ? priority : null;
+
+		return {
+			name: medication.name,
+			genericName: medication.genericName,
+			imageUrl: medication.imageUrl,
+			packageType: medication.packageType,
+			packCount: medication.packCount,
+			blistersPerPack: medication.blistersPerPack,
+			pillsPerBlister: medication.pillsPerBlister,
+			totalPills: medication.totalPills,
+			looseTablets: medication.looseTablets,
+			currentStock: visibleCurrentStock,
+			capacity: visibleCapacity,
+			daysLeft: visibleDaysLeft,
+			nextIntakeDate: computeNextIntakeDate(intakes, todayDateOnly),
+			depletionDate: visibleDepletionDate,
+			priority: visiblePriority,
+			expiryDate: toNullableDate(medication.expiryDate),
+			medicationStartDate: toNullableDate(medication.medicationStartDate),
+			prescriptionEnabled: medication.prescriptionEnabled ?? false,
+			prescriptionRemainingRefills: medication.prescriptionRemainingRefills,
+		};
+	});
+}

backend/src/services/current-stock.ts

@@ -0,0 +1,151 @@
+import type { doseTracking, medications } from "../db/schema.js";
+import { isAmountBasedPackageType } from "../utils/package-profiles.js";
+import {
+	normalizeIntakeUsageForStock,
+	parseIntakesJson,
+	parseLocalDateTime,
+	parseTakenByJson,
+} from "../utils/scheduler-utils.js";
+
+type MedicationRow = typeof medications.$inferSelect;
+type DoseRow = typeof doseTracking.$inferSelect;
+
+const MS_PER_DAY = 86_400_000;
+const doseIdPattern = /^(\d+)-(\d+)-(\d+)(?:-(.+))?$/;
+
+function getDoseTakenAtMs(dose: DoseRow): number {
+	const rawTakenAt = Number(dose.takenAt);
+	if (Number.isFinite(rawTakenAt)) {
+		return rawTakenAt < 1_000_000_000_000 ? rawTakenAt * 1000 : rawTakenAt;
+	}
+
+	return new Date(dose.takenAt).getTime();
+}
+
+export function computeMedicationCurrentStock(options: {
+	medication: MedicationRow;
+	doses: DoseRow[];
+	stockCalculationMode: "automatic" | "manual";
+	nowMs?: number;
+}): number {
+	const { medication, doses, stockCalculationMode, nowMs = Date.now() } = options;
+
+	const intakes = parseIntakesJson(
+		medication.intakesJson,
+		{
+			usageJson: medication.usageJson,
+			everyJson: medication.everyJson,
+			startJson: medication.startJson,
+		},
+		medication.intakeRemindersEnabled ?? false
+	);
+
+	const baseStock = isAmountBasedPackageType(medication.packageType)
+		? medication.looseTablets + (medication.stockAdjustment ?? 0)
+		: medication.packCount * medication.blistersPerPack * medication.pillsPerBlister +
+			medication.looseTablets +
+			(medication.stockAdjustment ?? 0);
+
+	const relevantDoses = doses.filter((dose) => !dose.dismissed);
+	const stockCorrectionCutoff = medication.lastStockCorrectionAt
+		? new Date(medication.lastStockCorrectionAt).getTime()
+		: 0;
+	let consumed = 0;
+
+	if (stockCalculationMode === "automatic") {
+		const medicationTakenBy = parseTakenByJson(medication.takenByJson);
+
+		intakes.forEach((intake, intakeIndex) => {
+			const usage = normalizeIntakeUsageForStock(intake, medication.medicationForm, medication.packageType);
+			const intakeStart = parseLocalDateTime(intake.start).getTime();
+			if (Number.isNaN(intakeStart)) return;
+
+			const period = Math.max(1, intake.every) * MS_PER_DAY;
+			let effectiveStart: number;
+			if (stockCorrectionCutoff > 0 && stockCorrectionCutoff >= intakeStart) {
+				const elapsedSinceStart = stockCorrectionCutoff - intakeStart;
+				const periodsElapsed = Math.floor(elapsedSinceStart / period);
+				effectiveStart = intakeStart + (periodsElapsed + 1) * period;
+			} else {
+				effectiveStart = intakeStart;
+			}
+
+			let peopleForThisIntake: Array<string | null>;
+			if (intake.takenBy) {
+				peopleForThisIntake = [intake.takenBy];
+			} else if (medicationTakenBy.length > 0) {
+				peopleForThisIntake = medicationTakenBy;
+			} else {
+				peopleForThisIntake = [null];
+			}
+
+			let lastAutoConsumedDateMs = 0;
+			if (effectiveStart <= nowMs) {
+				const occurrences = Math.floor((nowMs - effectiveStart) / period) + 1;
+				consumed += occurrences * usage * peopleForThisIntake.length;
+
+				const lastDoseTime = new Date(effectiveStart + (occurrences - 1) * period);
+				lastAutoConsumedDateMs = new Date(
+					lastDoseTime.getFullYear(),
+					lastDoseTime.getMonth(),
+					lastDoseTime.getDate()
+				).getTime();
+			}
+
+			const stockCorrectionDateOnly =
+				stockCorrectionCutoff > 0
+					? new Date(
+							new Date(stockCorrectionCutoff).getFullYear(),
+							new Date(stockCorrectionCutoff).getMonth(),
+							new Date(stockCorrectionCutoff).getDate()
+						).getTime()
+					: 0;
+			const earlyCutoff = Math.max(lastAutoConsumedDateMs, stockCorrectionDateOnly);
+
+			for (const dose of relevantDoses) {
+				const match = doseIdPattern.exec(dose.doseId);
+				if (!match) continue;
+
+				const parsedIntakeIndex = Number.parseInt(match[2], 10);
+				const doseDateOnlyMs = Number.parseInt(match[3], 10);
+				if (Number.isNaN(parsedIntakeIndex) || Number.isNaN(doseDateOnlyMs) || parsedIntakeIndex !== intakeIndex) {
+					continue;
+				}
+
+				if (doseDateOnlyMs > earlyCutoff) {
+					consumed += usage;
+				}
+			}
+		});
+	} else {
+		intakes.forEach((intake, intakeIndex) => {
+			const usage = normalizeIntakeUsageForStock(intake, medication.medicationForm, medication.packageType);
+			const intakeStart = parseLocalDateTime(intake.start);
+			const intakeStartDateOnly = new Date(
+				intakeStart.getFullYear(),
+				intakeStart.getMonth(),
+				intakeStart.getDate()
+			).getTime();
+			if (Number.isNaN(intakeStartDateOnly)) return;
+
+			for (const dose of relevantDoses) {
+				const match = doseIdPattern.exec(dose.doseId);
+				if (!match) continue;
+
+				const parsedIntakeIndex = Number.parseInt(match[2], 10);
+				const doseDateOnlyMs = Number.parseInt(match[3], 10);
+				if (Number.isNaN(parsedIntakeIndex) || Number.isNaN(doseDateOnlyMs) || parsedIntakeIndex !== intakeIndex) {
+					continue;
+				}
+
+				const takenAtMs = getDoseTakenAtMs(dose);
+				const afterCorrectionOrNoCorrection = stockCorrectionCutoff === 0 || takenAtMs > stockCorrectionCutoff;
+				if (doseDateOnlyMs >= intakeStartDateOnly && afterCorrectionOrNoCorrection) {
+					consumed += usage;
+				}
+			}
+		});
+	}
+
+	return Math.max(0, Math.floor(baseStock - consumed));
+}

backend/src/services/intake-reminder-scheduler.ts

@@ -4,7 +4,7 @@ import { and, eq, gte, lte } from "drizzle-orm";
 import nodemailer from "nodemailer";
 import { db } from "../db/client.js";
 import { getDataDir } from "../db/db-utils.js";
-import { doseTracking, medications } from "../db/schema.js";
+import { doseTracking, medications, users } from "../db/schema.js";
 import {
 	getDateLocale,
 	getFooterHtml,
@@ -23,11 +23,13 @@ import {
 	getTodaysIntakes,
 	getUpcomingIntakes,
 	type IntakeReminderState,
+	normalizeIntakeUsageForStock,
 	parseIntakeReminderState,
 	parseIntakesJson,
 	parseTakenByJson,
 	type UpcomingIntake,
 } from "../utils/scheduler-utils.js";
+import { computeMedicationCurrentStock } from "./current-stock.js";
 import { updateReminderSentTime, updateUserReminderSentTime } from "./reminder-scheduler.js";
 
 const REMINDER_MINUTES_BEFORE = parseInt(process.env.REMINDER_MINUTES_BEFORE ?? "15", 10);
@@ -50,6 +52,36 @@ function saveIntakeReminderState(state: IntakeReminderState): void {
 	writeFileSync(intakeReminderStateFile, JSON.stringify(state, null, 2));
 }
 
+type MailDeliveryInfo = {
+	accepted?: unknown;
+	rejected?: unknown;
+	response?: unknown;
+};
+
+function normalizeRecipients(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	return value
+		.map((entry) => (typeof entry === "string" ? entry : String(entry ?? "")))
+		.map((entry) => entry.trim())
+		.filter(Boolean);
+}
+
+function getDeliveryError(info: MailDeliveryInfo): string | null {
+	const accepted = normalizeRecipients(info.accepted);
+	const rejected = normalizeRecipients(info.rejected);
+
+	if (accepted.length > 0) return null;
+	if (rejected.length > 0) {
+		return `SMTP rejected all recipients: ${rejected.join(", ")}`;
+	}
+
+	if (typeof info.response === "string" && info.response.trim()) {
+		return `SMTP did not confirm accepted recipients. Response: ${info.response}`;
+	}
+
+	return "SMTP did not confirm accepted recipients.";
+}
+
 function buildDoseIdForIntake(intake: UpcomingIntake & { medicationId: number; blisterIndex: number }): string {
 	const intakeDate = intake.intakeTime;
 	const dateOnlyMs = new Date(intakeDate.getFullYear(), intakeDate.getMonth(), intakeDate.getDate()).getTime();
@@ -59,6 +91,21 @@ function buildDoseIdForIntake(intake: UpcomingIntake & { medicationId: number; b
 	return `${intake.medicationId}-${intake.blisterIndex}-${dateOnlyMs}`;
 }
 
+async function resolveSchedulerUserDisplayName(userId: number): Promise<string> {
+	const [userRow] = await db.select({ username: users.username }).from(users).where(eq(users.id, userId)).limit(1);
+	return userRow?.username?.trim() || `unknown-user-${userId}`;
+}
+
+function formatIntakeDescriptor(
+	definitionIndex: number,
+	medicationName: string,
+	medicationId: number,
+	intake: { every: number; usage: number; start: string; intakeRemindersEnabled: boolean; takenBy: string | null }
+): string {
+	const takenByPart = intake.takenBy ? `, takenBy=${intake.takenBy}` : "";
+	return `Intake #${definitionIndex + 1} (index=${definitionIndex}, medication=${medicationName}, medicationId=${medicationId}, start=${intake.start}, every=${intake.every}d, usage=${intake.usage}, reminderEnabled=${intake.intakeRemindersEnabled}${takenByPart})`;
+}
+
 async function autoMarkDueIntakesAsTaken(
 	settings: UserSettings & { userId: number },
 	rows: (typeof medications.$inferSelect)[],
@@ -88,6 +135,10 @@ async function autoMarkDueIntakesAsTaken(
 			)
 		);
 	const existingDoseIds = new Set(existingToday.map((d) => d.doseId));
+	const trackedDoses = await db
+		.select()
+		.from(doseTracking)
+		.where(and(eq(doseTracking.userId, settings.userId), eq(doseTracking.dismissed, false)));
 
 	let inserted = 0;
 
@@ -107,6 +158,15 @@ async function autoMarkDueIntakesAsTaken(
 
 		const medicationTakenBy = parseTakenByJson(med.takenByJson);
 		const medDisplayName = med.name || med.genericName || "";
+		let remainingStock = computeMedicationCurrentStock({
+			medication: med,
+			doses: trackedDoses,
+			stockCalculationMode: settings.stockCalculationMode,
+			nowMs: now.getTime(),
+		});
+		if (remainingStock <= 0) {
+			continue;
+		}
 		const todaysIntakes = getTodaysIntakes(
 			medDisplayName,
 			intakes,
@@ -137,6 +197,14 @@ async function autoMarkDueIntakesAsTaken(
 				continue;
 			}
 
+			const intakeDefinition = intakes[intake.blisterIndex];
+			const usage = intakeDefinition
+				? normalizeIntakeUsageForStock(intakeDefinition, med.medicationForm, med.packageType)
+				: 0;
+			if (remainingStock <= 0) {
+				break;
+			}
+
 			await db.insert(doseTracking).values({
 				userId: settings.userId,
 				doseId,
@@ -147,12 +215,22 @@ async function autoMarkDueIntakesAsTaken(
 			});
 
 			existingDoseIds.add(doseId);
+			trackedDoses.push({
+				id: 0,
+				userId: settings.userId,
+				doseId,
+				takenAt: intake.intakeTime,
+				markedBy: null,
+				takenSource: "automatic",
+				dismissed: false,
+			});
+			remainingStock = Math.max(0, remainingStock - usage);
 			inserted++;
 		}
 	}
 
 	if (inserted > 0) {
-		logger.info(`[IntakeReminder] User ${settings.userId}: Auto-marked ${inserted} due intake dose(s) as taken`);
+		logger.info(`[IntakeReminder] Auto-marked ${inserted} due intake dose(s) as taken`);
 	}
 
 	return inserted;
@@ -166,7 +244,7 @@ async function sendIntakeReminderEmail(
 	repeatIntervalMinutes?: number,
 	currentCount?: number,
 	maxCount?: number
-): Promise<{ success: boolean; error?: string }> {
+): Promise<{ success: boolean; error?: string; messageId?: string; smtpResponse?: string }> {
 	const smtpHost = process.env.SMTP_HOST;
 	const smtpUser = process.env.SMTP_USER;
 	const smtpPass = process.env.SMTP_TOKEN || process.env.SMTP_PASS; // Token takes precedence
@@ -310,7 +388,7 @@ ${getFooterPlain(language)}`;
 			},
 		});
 
-		await transporter.sendMail({
+		const mailResult = await transporter.sendMail({
 			from: smtpFrom,
 			to: email,
 			subject: `💊 ${subject}`,
@@ -318,7 +396,16 @@ ${getFooterPlain(language)}`;
 			html,
 		});
 
-		return { success: true };
+		const deliveryError = getDeliveryError(mailResult);
+		if (deliveryError) {
+			return { success: false, error: deliveryError };
+		}
+
+		return {
+			success: true,
+			messageId: mailResult.messageId,
+			smtpResponse: typeof mailResult.response === "string" ? mailResult.response : undefined,
+		};
 	} catch (error) {
 		const errorMessage = error instanceof Error ? error.message : "Unknown error";
 		return { success: false, error: errorMessage };
@@ -336,23 +423,22 @@ async function checkAndSendIntakeReminders(logger: ServiceLogger): Promise<void>
 		return; // No users with settings
 	}
 
-	logger.debug(`[IntakeReminder] Found ${allUserSettings.length} users to check`);
+	logger.debug(`[IntakeReminder] Evaluating ${allUserSettings.length} intake profile(s) for auto-marking`);
 
 	for (const userSettings of allUserSettings) {
 		await checkAndSendIntakeRemindersForUser(userSettings, logger);
 	}
 }
 
-async function checkAndSendIntakeRemindersForUser(
+export async function checkAndSendIntakeRemindersForUser(
 	settings: UserSettings & { userId: number },
 	logger: ServiceLogger
 ): Promise<void> {
 	const language = settings.language;
 	const tr = getTranslations(language);
+	const schedulerUserName = await resolveSchedulerUserDisplayName(settings.userId);
 
-	logger.debug(
-		`[IntakeReminder] Checking user ${settings.userId} - repeat:${settings.repeatRemindersEnabled} skip:${settings.skipRemindersForTakenDoses}`
-	);
+	logger.debug(`[IntakeReminder] Evaluating intake reminder profile for user '${schedulerUserName}'`);
 
 	const rows = await db
 		.select()
@@ -370,73 +456,76 @@ async function checkAndSendIntakeRemindersForUser(
 	const shoutrrrEnabled = settings.shoutrrrEnabled && settings.shoutrrrUrl && settings.shoutrrrIntakeReminders;
 
 	if (!emailEnabled && !shoutrrrEnabled) {
-		logger.debug(
-			`[IntakeReminder] User ${settings.userId}: No intake notifications enabled (email:${emailEnabled}, shoutrrr:${shoutrrrEnabled})`
-		);
 		return; // No intake reminder notifications enabled for this user
 	}
 
 	logger.debug(
-		`[IntakeReminder] User ${settings.userId}: Notifications enabled (email:${emailEnabled}, shoutrrr:${shoutrrrEnabled})`
+		`[IntakeReminder] Notifications enabled for current scheduler context (email:${emailEnabled}, shoutrrr:${shoutrrrEnabled})`
 	);
 
-	// Get all medications with intake reminders enabled for this user
-	const medsWithReminders = rows.filter((row) => row.intakeRemindersEnabled);
+	// Build medication entries that have at least one reminder-enabled intake.
+	// Intake-level reminders are the single source of truth.
+	const reminderEntries = rows
+		.map((med) => {
+			const intakes = parseIntakesJson(
+				med.intakesJson,
+				{ usageJson: med.usageJson, everyJson: med.everyJson, startJson: med.startJson },
+				false
+			);
+			const intakesWithReminders = intakes.filter((intake) => intake.intakeRemindersEnabled === true);
+			return { med, intakes, intakesWithReminders };
+		})
+		.filter((entry) => entry.intakesWithReminders.length > 0);
 
-	if (medsWithReminders.length === 0) {
-		logger.debug(`[IntakeReminder] User ${settings.userId}: No medications have reminders enabled`);
+	if (reminderEntries.length === 0) {
+		logger.debug("[IntakeReminder] No medications have reminders enabled for current scheduler context");
 		return; // No medications have reminders enabled for this user
 	}
 
-	logger.debug(
-		`[IntakeReminder] User ${settings.userId}: Found ${medsWithReminders.length} medications with reminders`
-	);
+	logger.debug(`[IntakeReminder] Found ${reminderEntries.length} medications with reminders`);
 
 	const state = loadIntakeReminderState();
 	const allUpcoming: (UpcomingIntake & { medicationId: number; blisterIndex: number })[] = [];
+	let scheduledIntakesTodayCount = 0;
 	// Get start and end of today in user's timezone (for filtering today's doses only)
 	const now = new Date();
+	const checkMinuteStart = new Date(Math.floor(now.getTime() / 60000) * 60000);
+	const checkMinuteEnd = new Date(checkMinuteStart.getTime() + 60000);
 	const todayStart = new Date(now.toLocaleString("en-US", { timeZone: tz }));
 	todayStart.setHours(0, 0, 0, 0);
 
 	const todayEnd = new Date(now.toLocaleString("en-US", { timeZone: tz }));
 	todayEnd.setHours(23, 59, 59, 999);
 
-	logger.debug(
-		`[IntakeReminder] User ${settings.userId}: Today range: ${todayStart.toISOString()} to ${todayEnd.toISOString()}`
-	);
+	logger.debug(`[IntakeReminder] Today range: ${todayStart.toISOString()} to ${todayEnd.toISOString()}`);
 
 	// Find intakes: upcoming ones in reminder window + past ones for repeat reminders
-	for (const med of medsWithReminders) {
-		// Parse intakes using new format (with per-intake takenBy), falling back to legacy
-		const intakes = parseIntakesJson(
-			med.intakesJson,
-			{ usageJson: med.usageJson, everyJson: med.everyJson, startJson: med.startJson },
-			med.intakeRemindersEnabled ?? false
-		);
+	for (const { med, intakes, intakesWithReminders } of reminderEntries) {
 		// Medication-level takenBy (for fallback/display purposes)
 		const medicationTakenBy = parseTakenByJson(med.takenByJson);
 		const medDisplayName = med.name || med.genericName || "";
 
 		logger.debug(
-			`[IntakeReminder] User ${settings.userId}: Processing medication "${medDisplayName}" with ${intakes.length} intakes`
+			`[IntakeReminder] Processing medication '${medDisplayName}' (id=${med.id}) with ${intakes.length} intake definition(s)`
 		);
 
-		// Filter intakes that have reminders enabled (per-intake setting or medication-level)
-		const intakesWithReminders = intakes.filter((intake, idx) => {
-			const hasReminder = intake.intakeRemindersEnabled || med.intakeRemindersEnabled;
-			if (!hasReminder) {
-				logger.debug(`[IntakeReminder] User ${settings.userId}: Intake ${idx} has reminders disabled, skipping`);
-			}
-			return hasReminder;
-		});
-
 		// Process each intake separately to track blisterIndex
 		intakesWithReminders.forEach((intake, _blisterIndex) => {
 			const actualIndex = intakes.indexOf(intake); // Get the actual index in original array
-			logger.debug(
-				`[IntakeReminder] User ${settings.userId}: Intake ${actualIndex} - start: ${intake.start}, every: ${intake.every} days, usage: ${intake.usage}, takenBy: ${intake.takenBy || "(none)"}`
+			const intakeDescriptor = formatIntakeDescriptor(actualIndex, medDisplayName, med.id, intake);
+			logger.debug(`[IntakeReminder] ${intakeDescriptor}`);
+
+			const todaysIntakesForThisDefinition = getTodaysIntakes(
+				medDisplayName,
+				[intake],
+				medicationTakenBy,
+				med.pillWeightMg,
+				locale,
+				tz,
+				med.id,
+				med.doseUnit ?? "mg"
 			);
+			scheduledIntakesTodayCount += todaysIntakesForThisDefinition.length;
 
 			// Always get upcoming intakes (15 min before) for first reminders
 			const upcomingIntakes = getUpcomingIntakes(
@@ -452,7 +541,10 @@ async function checkAndSendIntakeRemindersForUser(
 				med.doseUnit ?? "mg"
 			);
 			logger.debug(
-				`[IntakeReminder] User ${settings.userId}: Intake ${actualIndex} found ${upcomingIntakes.length} upcoming intakes (reminder window)`
+				`[IntakeReminder] ${intakeDescriptor} -> ${upcomingIntakes.length} intake(s) currently due for advance reminder (default ${REMINDER_MINUTES_BEFORE} min before intake, with catch-up while intake is still in the future)`
+			);
+			logger.debug(
+				`[IntakeReminder] ${intakeDescriptor} -> ${todaysIntakesForThisDefinition.length} scheduled intake(s) today (independent of reminder window)`
 			);
 
 			// Add upcoming intakes for first reminders
@@ -466,24 +558,14 @@ async function checkAndSendIntakeRemindersForUser(
 
 			// If repeat reminders enabled, also check for missed intakes (past the intake time)
 			if (settings.repeatRemindersEnabled) {
-				const allTodaysIntakes = getTodaysIntakes(
-					medDisplayName,
-					[intake],
-					medicationTakenBy,
-					med.pillWeightMg,
-					locale,
-					tz,
-					med.id,
-					med.doseUnit ?? "mg"
-				);
 				logger.debug(
-					`[IntakeReminder] User ${settings.userId}: Intake ${actualIndex} - all today's intakes: ${allTodaysIntakes.length}, times: ${allTodaysIntakes.map((i) => i.intakeTime.toISOString()).join(", ")}`
+					`[IntakeReminder] ${intakeDescriptor} -> ${todaysIntakesForThisDefinition.length} candidate intake(s) for repeat reminders`
 				);
-				const missedIntakes = allTodaysIntakes.filter(
+				const missedIntakes = todaysIntakesForThisDefinition.filter(
 					(todayIntake) => todayIntake.intakeTime.getTime() < now.getTime()
 				);
 				logger.debug(
-					`[IntakeReminder] User ${settings.userId}: Intake ${actualIndex} found ${missedIntakes.length} missed intakes (past intake time)`
+					`[IntakeReminder] ${intakeDescriptor} -> ${missedIntakes.length} missed intake(s) (past intake time)`
 				);
 
 				// Add missed intakes for repeat reminders (only if not already in upcoming list)
@@ -501,10 +583,13 @@ async function checkAndSendIntakeRemindersForUser(
 		});
 	}
 
-	logger.debug(`[IntakeReminder] User ${settings.userId}: Total ${allUpcoming.length} intakes for today`);
+	logger.debug(`[IntakeReminder] Total scheduled intakes for today: ${scheduledIntakesTodayCount}`);
+	logger.debug(`[IntakeReminder] Total reminder candidates in current check: ${allUpcoming.length}`);
 
 	if (allUpcoming.length === 0) {
-		logger.debug(`[IntakeReminder] User ${settings.userId}: No intakes for today`);
+		logger.debug(
+			`[IntakeReminder] No reminder due in this check window (minute=${checkMinuteStart.toISOString()}..${checkMinuteEnd.toISOString()}, advanceLead=${REMINDER_MINUTES_BEFORE}m, plus catch-up while intake is still future)`
+		);
 		return; // No upcoming intakes for today
 	}
 
@@ -536,7 +621,7 @@ async function checkAndSendIntakeRemindersForUser(
 					// Send a catch-up reminder (counts as first nagging reminder).
 					remindersToSend.push({ ...intake, currentSendCount: 1, maxReminders, isAdvanceReminder: false });
 					logger.info(
-						`[IntakeReminder] User ${settings.userId}: Catch-up reminder for recently missed "${intake.medName}" at ${intake.intakeTimeStr} (${Math.round(minutesSinceIntake)} min ago)`
+						`[IntakeReminder] Catch-up reminder for recently missed intake (${Math.round(minutesSinceIntake)} min ago)`
 					);
 				} else {
 					// Long ago — seed state without notification (user likely already noticed)
@@ -547,15 +632,13 @@ async function checkAndSendIntakeRemindersForUser(
 						advanceSent: false,
 					};
 					logger.debug(
-						`[IntakeReminder] User ${settings.userId}: Seeding state for old past "${intake.medName}" at ${intake.intakeTimeStr} (no notification — ${Math.round(minutesSinceIntake)} min ago)`
+						`[IntakeReminder] Seeding state for old past intake (no notification — ${Math.round(minutesSinceIntake)} min ago)`
 					);
 				}
 			} else {
 				// Upcoming - this is advance reminder (no counter)
 				remindersToSend.push({ ...intake, currentSendCount: 0, maxReminders, isAdvanceReminder: true });
-				logger.debug(
-					`[IntakeReminder] User ${settings.userId}: Advance reminder for "${intake.medName}" at ${intake.intakeTimeStr}`
-				);
+				logger.debug("[IntakeReminder] Advance reminder candidate added");
 			}
 		} else if (settings.repeatRemindersEnabled && isIntakePast) {
 			// Intake time passed - check if we need to send nagging reminder
@@ -568,15 +651,11 @@ async function checkAndSendIntakeRemindersForUser(
 
 			if (currentNaggingCount >= maxReminders) {
 				// Max nagging reminders reached - stop
-				logger.debug(
-					`[IntakeReminder] User ${settings.userId}: Max nagging (${maxReminders}) reached for "${intake.medName}" at ${intake.intakeTimeStr}`
-				);
+				logger.debug(`[IntakeReminder] Max nagging (${maxReminders}) reached for intake reminder key`);
 			} else if (timeSinceLastReminder >= intervalMs) {
 				const nextSendCount = currentNaggingCount + 1;
 				remindersToSend.push({ ...intake, currentSendCount: nextSendCount, maxReminders, isAdvanceReminder: false });
-				logger.debug(
-					`[IntakeReminder] User ${settings.userId}: Nagging reminder for "${intake.medName}" at ${intake.intakeTimeStr} (${nextSendCount}/${maxReminders})`
-				);
+				logger.debug(`[IntakeReminder] Nagging reminder candidate added (${nextSendCount}/${maxReminders})`);
 			}
 		}
 		// Else: Already sent and either repeats disabled or intake not yet past - skip
@@ -614,9 +693,7 @@ async function checkAndSendIntakeRemindersForUser(
 				const doseId = `${intake.medicationId}-${intake.blisterIndex}-${dateOnlyMs}-${intake.takenBy}`;
 				const isTaken = takenDoseIds.has(doseId);
 				if (isTaken) {
-					logger.debug(
-						`[IntakeReminder] User ${settings.userId}: Skipping "${intake.medName}" - dose ${doseId} already taken`
-					);
+					logger.debug("[IntakeReminder] Skipping reminder candidate - dose already taken");
 				}
 				return !isTaken;
 			} else {
@@ -624,21 +701,19 @@ async function checkAndSendIntakeRemindersForUser(
 				const doseId = `${intake.medicationId}-${intake.blisterIndex}-${dateOnlyMs}`;
 				const isTaken = takenDoseIds.has(doseId);
 				if (isTaken) {
-					logger.debug(
-						`[IntakeReminder] User ${settings.userId}: Skipping "${intake.medName}" - dose ${doseId} already taken`
-					);
+					logger.debug("[IntakeReminder] Skipping reminder candidate - dose already taken");
 				}
 				return !isTaken;
 			}
 		});
 
 		if (remindersToSend.length === 0) {
-			logger.debug(`[IntakeReminder] User ${settings.userId}: All doses taken, skipping reminders`);
+			logger.debug("[IntakeReminder] All doses taken, skipping reminders");
 			return;
 		}
 	}
 
-	logger.info(`[IntakeReminder] User ${settings.userId}: Sending reminder for ${remindersToSend.length} intakes...`);
+	logger.info(`[IntakeReminder] Sending reminder for ${remindersToSend.length} intakes...`);
 
 	// Determine if this is a repeat reminder:
 	// - Any intake already has a state entry AND is past (repeat after first reminder)
@@ -670,9 +745,9 @@ async function checkAndSendIntakeRemindersForUser(
 		);
 		emailSuccess = result.success;
 		if (result.success) {
-			logger.info(`[IntakeReminder] User ${settings.userId}: Email sent successfully`);
+			logger.info("[IntakeReminder] Email sent successfully");
 		} else {
-			logger.error(`[IntakeReminder] User ${settings.userId}: Failed to send email: ${result.error}`);
+			logger.error(`[IntakeReminder] Failed to send email: ${result.error}`);
 		}
 	}
 
@@ -736,9 +811,9 @@ async function checkAndSendIntakeRemindersForUser(
 		const result = await sendShoutrrrNotification(settings.shoutrrrUrl!, title, message);
 		shoutrrrSuccess = result.success;
 		if (result.success) {
-			logger.info(`[IntakeReminder] User ${settings.userId}: Push notification sent successfully`);
+			logger.info("[IntakeReminder] Push notification sent successfully");
 		} else {
-			logger.error(`[IntakeReminder] User ${settings.userId}: Failed to send push: ${result.error}`);
+			logger.error(`[IntakeReminder] Failed to send push: ${result.error}`);
 		}
 	}
 

backend/src/services/reminder-scheduler.ts

@@ -8,6 +8,12 @@ import { doseTracking, medications, userSettings } from "../db/schema.js";
 import { getFooterHtml, getFooterPlain, getTranslations, type Language, t } from "../i18n/translations.js";
 import { getAllUserSettings, sendShoutrrrNotification, type UserSettings } from "../routes/settings.js";
 import type { ServiceLogger } from "../utils/logger.js";
+import {
+	isAmountBasedPackageType,
+	isLiquidContainerPackageType,
+	isTubePackageType,
+	normalizePackageType,
+} from "../utils/package-profiles.js";
 // Import shared utilities
 import {
 	type Blister,
@@ -268,9 +274,10 @@ async function getMedicationsNeedingReminder(
 	const msPerDay = 86_400_000;
 
 	for (const row of rows) {
+		const packageType = normalizePackageType(row.packageType);
 		// Tube stock reminders are intentionally disabled:
 		// topical usage in grams cannot be mapped reliably to schedule events.
-		if ((row.packageType ?? "blister") === "tube") continue;
+		if (isTubePackageType(packageType)) continue;
 
 		const intakes = parseIntakesJson(
 			row.intakesJson,
@@ -283,10 +290,9 @@ async function getMedicationsNeedingReminder(
 			start: i.start,
 		}));
 
-		const originalTotalPills =
-			(row.packageType ?? "blister") === "bottle"
-				? row.looseTablets + (row.stockAdjustment ?? 0)
-				: row.packCount * row.blistersPerPack * row.pillsPerBlister + row.looseTablets + (row.stockAdjustment ?? 0);
+		const originalTotalPills = isAmountBasedPackageType(packageType)
+			? row.looseTablets + (row.stockAdjustment ?? 0)
+			: row.packCount * row.blistersPerPack * row.pillsPerBlister + row.looseTablets + (row.stockAdjustment ?? 0);
 
 		const stockCorrectionCutoff = row.lastStockCorrectionAt ? new Date(row.lastStockCorrectionAt).getTime() : 0;
 		const takenDoseIds = takenDoseIdsByMed.get(row.id) ?? new Set<string>();
@@ -393,7 +399,7 @@ async function getMedicationsNeedingReminder(
 
 		if (daysLeft === null) continue;
 
-		const isLiquid = (row.packageType ?? "blister") === "liquid_container";
+		const isLiquid = isLiquidContainerPackageType(packageType);
 		const { lowDays, criticalDays } = isLiquid
 			? getLiquidReminderThresholds(reminderDaysBefore)
 			: { lowDays: lowStockDays, criticalDays: reminderDaysBefore };
@@ -681,12 +687,10 @@ async function checkAndSendReminderForUser(
 		if (!state.notifiedMedications.includes(userStockNotifiedKey) || settings.repeatDailyReminders) {
 			const stockSendLock = acquireReminderSendLock(userStockNotifiedKey);
 			if (!stockSendLock) {
-				logger.debug(`[Reminder] User ${settings.userId}: stock reminder lock already held, skipping duplicate send`);
+				logger.debug("[Reminder] Stock reminder lock already held, skipping duplicate send");
 			} else {
 				try {
-					logger.info(
-						`[Reminder] User ${settings.userId}: Sending stock reminder for ${allLowStock.length} medications...`
-					);
+					logger.info(`[Reminder] Sending stock reminder for ${allLowStock.length} medications...`);
 
 					let emailSuccess = false;
 					let shoutrrrSuccess = false;
@@ -700,7 +704,7 @@ async function checkAndSendReminderForUser(
 						);
 						emailSuccess = result.success;
 						if (!result.success) {
-							logger.error(`[Reminder] User ${settings.userId}: Failed to send stock email: ${result.error}`);
+							logger.error(`[Reminder] Failed to send stock email: ${result.error}`);
 						}
 					}
 
@@ -742,7 +746,7 @@ async function checkAndSendReminderForUser(
 						const result = await sendShoutrrrNotification(settings.shoutrrrUrl!, title, message);
 						shoutrrrSuccess = result.success;
 						if (!result.success) {
-							logger.error(`[Reminder] User ${settings.userId}: Failed to send stock push: ${result.error}`);
+							logger.error(`[Reminder] Failed to send stock push: ${result.error}`);
 						}
 					}
 
@@ -774,9 +778,7 @@ async function checkAndSendReminderForUser(
 		if (!state.notifiedMedications.includes(userPrescriptionNotifiedKey) || settings.repeatDailyReminders) {
 			const prescriptionSendLock = acquireReminderSendLock(userPrescriptionNotifiedKey);
 			if (!prescriptionSendLock) {
-				logger.debug(
-					`[Reminder] User ${settings.userId}: prescription reminder lock already held, skipping duplicate send`
-				);
+				logger.debug("[Reminder] Prescription reminder lock already held, skipping duplicate send");
 			} else {
 				try {
 					// Re-check using fresh state after acquiring lock and pre-mark today as notified.
@@ -785,9 +787,7 @@ async function checkAndSendReminderForUser(
 					const alreadyNotified = lockedState.notifiedMedications.includes(userPrescriptionNotifiedKey);
 					const shouldSend = !alreadyNotified || settings.repeatDailyReminders;
 					if (!shouldSend) {
-						logger.debug(
-							`[Reminder] User ${settings.userId}: prescription reminder already marked as sent today, skipping`
-						);
+						logger.debug("[Reminder] Prescription reminder already marked as sent today, skipping");
 					}
 
 					const preMarkedNotified =
@@ -807,9 +807,7 @@ async function checkAndSendReminderForUser(
 					}
 
 					if (shouldSend) {
-						logger.info(
-							`[Reminder] User ${settings.userId}: Sending prescription reminder for ${allPrescriptionLow.length} medications...`
-						);
+						logger.info(`[Reminder] Sending prescription reminder for ${allPrescriptionLow.length} medications...`);
 
 						const emptyRx = allPrescriptionLow.filter((m) => m.remainingRefills <= 0);
 						const lowRx = allPrescriptionLow.filter((m) => m.remainingRefills > 0);
@@ -941,9 +939,7 @@ async function checkAndSendReminderForUser(
 									emailSuccess = true;
 								} catch (error) {
 									const errorMessage = error instanceof Error ? error.message : "Unknown error";
-									logger.error(
-										`[Reminder] User ${settings.userId}: Failed to send prescription email: ${errorMessage}`
-									);
+									logger.error(`[Reminder] Failed to send prescription email: ${errorMessage}`);
 								}
 							}
 						}
@@ -980,7 +976,7 @@ async function checkAndSendReminderForUser(
 							const result = await sendShoutrrrNotification(settings.shoutrrrUrl!, title, message);
 							shoutrrrSuccess = result.success;
 							if (!result.success) {
-								logger.error(`[Reminder] User ${settings.userId}: Failed to send prescription push: ${result.error}`);
+								logger.error(`[Reminder] Failed to send prescription push: ${result.error}`);
 							}
 						}
 

backend/src/test/auth.test.ts

@@ -8,6 +8,7 @@ import sensible from "@fastify/sensible";
 import type { Client } from "@libsql/client";
 import Fastify, { type FastifyInstance } from "fastify";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
 
 // Use vi.hoisted to create the db BEFORE mocks are set up
 const { testClient, testDb } = vi.hoisted(() => {
@@ -97,7 +98,7 @@ describe("Auth Routes (AUTH_ENABLED=true)", () => {
 	beforeAll(async () => {
 		await createSchema(testClient);
 
-		app = Fastify({ logger: false });
+		app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 
 		await app.register(sensible);
 		await app.register(cookie, { secret: "test-cookie-secret-12345" });
@@ -228,7 +229,7 @@ describe("Auth Routes (AUTH_ENABLED=true)", () => {
 			});
 
 			expect(response.statusCode).toBe(400);
-			expect(response.json().code).toBe("VALIDATION_ERROR");
+			expect(response.json().code).toBe("FST_ERR_VALIDATION");
 		});
 
 		it("should reject short username", async () => {
@@ -242,7 +243,7 @@ describe("Auth Routes (AUTH_ENABLED=true)", () => {
 			});
 
 			expect(response.statusCode).toBe(400);
-			expect(response.json().code).toBe("VALIDATION_ERROR");
+			expect(response.json().code).toBe("FST_ERR_VALIDATION");
 		});
 
 		it("should register with trimmed username when input has whitespace", async () => {

backend/src/test/business-authz-real.test.ts

@@ -0,0 +1,486 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import cookie from "@fastify/cookie";
+import jwt from "@fastify/jwt";
+import sensible from "@fastify/sensible";
+import { migrate } from "drizzle-orm/libsql/migrator";
+import Fastify, { type FastifyInstance } from "fastify";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { runAlterMigrations } from "../db/db-utils.js";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
+
+const { testClient, testDb, mockedEnv } = vi.hoisted(() => {
+	const { createClient } = require("@libsql/client");
+	const { drizzle } = require("drizzle-orm/libsql");
+	const client = createClient({ url: ":memory:" });
+	const db = drizzle(client);
+
+	return {
+		testClient: client,
+		testDb: db,
+		mockedEnv: {
+			AUTH_ENABLED: true,
+			REGISTRATION_ENABLED: true,
+			FORM_LOGIN_ENABLED: true,
+			OIDC_ENABLED: false,
+			OIDC_PROVIDER_NAME: "SSO",
+			NODE_ENV: "test",
+			LOG_LEVEL: "silent",
+			PORT: 3000,
+			CORS_ORIGINS: "*",
+			JWT_SECRET: "test-jwt-secret",
+			REFRESH_SECRET: "test-refresh-secret",
+			COOKIE_SECRET: "test-cookie-secret",
+			ACCESS_TOKEN_TTL_MINUTES: 15,
+			REFRESH_TOKEN_TTL_DAYS: 7,
+			OPENAPI_DOCS_ENABLED: false,
+		},
+	};
+});
+
+vi.mock("../db/client.js", () => ({
+	db: testDb,
+	migrationsReady: Promise.resolve(),
+}));
+
+vi.mock("../plugins/env.js", () => ({ env: mockedEnv }));
+
+const { medicationRoutes } = await import("../routes/medications.js");
+const { doseRoutes } = await import("../routes/doses.js");
+const { refillRoutes } = await import("../routes/refills.js");
+const { shareRoutes } = await import("../routes/share.js");
+const { reportRoutes } = await import("../routes/report.js");
+const { exportRoutes } = await import("../routes/export.js");
+const { hashApiKeyToken } = await import("../plugins/auth.js");
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const migrationsFolder = resolve(__dirname, "../../drizzle");
+
+async function clearTables() {
+	await testClient.execute("DELETE FROM refill_history");
+	await testClient.execute("DELETE FROM dose_tracking");
+	await testClient.execute("DELETE FROM share_tokens");
+	await testClient.execute("DELETE FROM user_settings");
+	await testClient.execute("DELETE FROM medications");
+	await testClient.execute("DELETE FROM api_keys");
+	await testClient.execute("DELETE FROM refresh_tokens");
+	await testClient.execute("DELETE FROM users");
+}
+
+async function createUser(username: string) {
+	const result = await testClient.execute({
+		sql: "INSERT INTO users (username, auth_provider, is_active) VALUES (?, 'local', 1) RETURNING id",
+		args: [username],
+	});
+
+	return Number(result.rows[0].id);
+}
+
+function buildSessionCookie(app: FastifyInstance, userId: number, username: string) {
+	const token = app.jwt.sign({ sub: userId, username });
+	return `access_token=${token}`;
+}
+
+async function insertApiKey(options: {
+	userId: number;
+	token: string;
+	scope?: "read" | "write";
+	isActive?: boolean;
+	expiresAt?: Date | null;
+}) {
+	const expiresAtValue = options.expiresAt ? Math.floor(options.expiresAt.getTime() / 1000) : null;
+
+	await testClient.execute({
+		sql: `INSERT INTO api_keys (user_id, name, key_hash, token_prefix, scope, is_active, expires_at)
+		      VALUES (?, ?, ?, ?, ?, ?, ?)`,
+		args: [
+			options.userId,
+			"Seeded Key",
+			hashApiKeyToken(options.token),
+			`${options.token.slice(0, 12)}...`,
+			options.scope ?? "write",
+			options.isActive === false ? 0 : 1,
+			expiresAtValue,
+		],
+	});
+}
+
+async function seedMedication(options: {
+	userId: number;
+	name: string;
+	takenBy?: string[];
+	packCount?: number;
+	looseTablets?: number;
+	start?: string;
+}) {
+	const start = options.start ?? "2026-01-01T08:00:00.000Z";
+	const takenBy = options.takenBy ?? ["Daniel"];
+	const result = await testClient.execute({
+		sql: `INSERT INTO medications (
+		  user_id, name, generic_name, taken_by_json, medication_form, package_type,
+		  pack_count, blisters_per_pack, pills_per_blister, loose_tablets,
+		  usage_json, every_json, start_json, intakes_json,
+		  stock_adjustment, intake_reminders_enabled
+		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING id`,
+		args: [
+			options.userId,
+			options.name,
+			`${options.name} Generic`,
+			JSON.stringify(takenBy),
+			"tablet",
+			"blister",
+			options.packCount ?? 1,
+			1,
+			10,
+			options.looseTablets ?? 0,
+			JSON.stringify([1]),
+			JSON.stringify([1]),
+			JSON.stringify([start]),
+			JSON.stringify([
+				{
+					usage: 1,
+					every: 1,
+					start,
+					takenBy: takenBy[0] ?? null,
+					intakeRemindersEnabled: true,
+				},
+			]),
+			0,
+			1,
+		],
+	});
+
+	return Number(result.rows[0].id);
+}
+
+async function seedDose(options: { userId: number; doseId: string; dismissed?: boolean }) {
+	await testClient.execute({
+		sql: "INSERT INTO dose_tracking (user_id, dose_id, dismissed) VALUES (?, ?, ?)",
+		args: [options.userId, options.doseId, options.dismissed ? 1 : 0],
+	});
+}
+
+async function seedRefill(options: {
+	userId: number;
+	medicationId: number;
+	packsAdded?: number;
+	loosePillsAdded?: number;
+}) {
+	await testClient.execute({
+		sql: `INSERT INTO refill_history (medication_id, user_id, packs_added, loose_pills_added, used_prescription)
+		      VALUES (?, ?, ?, ?, 0)`,
+		args: [options.medicationId, options.userId, options.packsAdded ?? 1, options.loosePillsAdded ?? 0],
+	});
+}
+
+function buildMedicationPayload(name: string) {
+	return {
+		name,
+		genericName: `${name} Generic`,
+		takenBy: ["Daniel"],
+		packCount: 1,
+		blistersPerPack: 1,
+		pillsPerBlister: 10,
+		looseTablets: 0,
+		blisters: [{ usage: 1, every: 1, start: "2026-01-01T08:00:00.000Z" }],
+	};
+}
+
+function buildImportPayload() {
+	return {
+		version: "1.3",
+		exportedAt: new Date().toISOString(),
+		includeSensitiveData: false,
+		medications: [],
+		doseHistory: [],
+		refillHistory: [],
+		settings: {
+			emailEnabled: false,
+			emailStockReminders: true,
+			emailIntakeReminders: true,
+			emailPrescriptionReminders: true,
+			shoutrrrStockReminders: true,
+			shoutrrrIntakeReminders: true,
+			shoutrrrPrescriptionReminders: true,
+			reminderDaysBefore: 7,
+			repeatDailyReminders: false,
+			skipRemindersForTakenDoses: false,
+			repeatRemindersEnabled: false,
+			reminderRepeatIntervalMinutes: 30,
+			maxNaggingReminders: 5,
+			lowStockDays: 30,
+			normalStockDays: 90,
+			highStockDays: 180,
+			language: "en",
+			stockCalculationMode: "automatic",
+			shareStockStatus: true,
+		},
+		shareLinks: [],
+	};
+}
+
+describe("Real business route authz contracts", () => {
+	let app: FastifyInstance;
+
+	beforeAll(async () => {
+		await migrate(testDb, { migrationsFolder });
+		await runAlterMigrations(testClient);
+
+		app = Fastify({ logger: false, ajv: documentationSchemaAjv });
+		await app.register(sensible);
+		await app.register(cookie, { secret: "test-cookie-secret" });
+		await app.register(jwt, {
+			secret: "test-jwt-secret",
+			cookie: { cookieName: "access_token", signed: false },
+		});
+		await app.register(medicationRoutes);
+		await app.register(doseRoutes);
+		await app.register(refillRoutes);
+		await app.register(shareRoutes);
+		await app.register(reportRoutes);
+		await app.register(exportRoutes);
+		await app.ready();
+	});
+
+	afterAll(async () => {
+		await app.close();
+		testClient.close();
+	});
+
+	beforeEach(async () => {
+		vi.clearAllMocks();
+		await clearTables();
+	});
+
+	it("rejects protected business endpoints without authentication", async () => {
+		const endpoints: Array<{
+			method: "GET" | "POST";
+			url: string;
+			payload?: Record<string, unknown>;
+		}> = [
+			{ method: "GET", url: "/medications" },
+			{ method: "GET", url: "/doses/taken" },
+			{ method: "POST", url: "/share", payload: { takenBy: "Daniel", scheduleDays: 7 } },
+			{ method: "GET", url: "/export" },
+			{ method: "POST", url: "/medications/report-data", payload: { medicationIds: [1] } },
+			{ method: "POST", url: "/medications/1/refill", payload: { packsAdded: 1, loosePillsAdded: 0 } },
+		];
+
+		for (const endpoint of endpoints) {
+			const response = await app.inject({ method: endpoint.method, url: endpoint.url, payload: endpoint.payload });
+			expect(response.statusCode, `${endpoint.method} ${endpoint.url}`).toBe(401);
+			expect(response.json()).toMatchObject({ code: "AUTH_REQUIRED" });
+		}
+	});
+
+	it("scopes medication listing and export output to the authenticated user", async () => {
+		const ownerId = await createUser("owner-medications");
+		const otherId = await createUser("other-medications");
+		const ownerCookie = buildSessionCookie(app, ownerId, "owner-medications");
+
+		await seedMedication({ userId: ownerId, name: "Owner Only Med" });
+		await seedMedication({ userId: otherId, name: "Other User Med" });
+
+		const listResponse = await app.inject({
+			method: "GET",
+			url: "/medications",
+			headers: { cookie: ownerCookie },
+		});
+
+		expect(listResponse.statusCode).toBe(200);
+		expect(listResponse.body).toContain("Owner Only Med");
+		expect(listResponse.body).not.toContain("Other User Med");
+
+		const exportResponse = await app.inject({
+			method: "GET",
+			url: "/export",
+			headers: { cookie: ownerCookie },
+		});
+
+		expect(exportResponse.statusCode).toBe(200);
+		expect(exportResponse.body).toContain("Owner Only Med");
+		expect(exportResponse.body).not.toContain("Other User Med");
+	});
+
+	it("returns 404 when a user updates or deletes another user's medication", async () => {
+		const ownerId = await createUser("owner-update");
+		const otherId = await createUser("other-update");
+		const otherCookie = buildSessionCookie(app, otherId, "other-update");
+		const medicationId = await seedMedication({ userId: ownerId, name: "Protected Medication" });
+
+		const updateResponse = await app.inject({
+			method: "PUT",
+			url: `/medications/${medicationId}`,
+			headers: { cookie: otherCookie },
+			payload: buildMedicationPayload("Updated By Stranger"),
+		});
+
+		expect(updateResponse.statusCode).toBe(404);
+
+		const deleteResponse = await app.inject({
+			method: "DELETE",
+			url: `/medications/${medicationId}`,
+			headers: { cookie: otherCookie },
+		});
+
+		expect(deleteResponse.statusCode).toBe(404);
+
+		const dbState = await testClient.execute({
+			sql: "SELECT name FROM medications WHERE id = ?",
+			args: [medicationId],
+		});
+		expect(dbState.rows).toEqual([expect.objectContaining({ name: "Protected Medication" })]);
+	});
+
+	it("scopes dose reads and writes to the authenticated user", async () => {
+		const ownerId = await createUser("owner-dose");
+		const otherId = await createUser("other-dose");
+		const ownerCookie = buildSessionCookie(app, ownerId, "owner-dose");
+		const otherCookie = buildSessionCookie(app, otherId, "other-dose");
+
+		await seedDose({ userId: ownerId, doseId: "101-0-1760000000000" });
+		await seedDose({ userId: otherId, doseId: "202-0-1760000000000" });
+
+		const listResponse = await app.inject({
+			method: "GET",
+			url: "/doses/taken",
+			headers: { cookie: ownerCookie },
+		});
+
+		expect(listResponse.statusCode).toBe(200);
+		expect(listResponse.body).toContain("101-0-1760000000000");
+		expect(listResponse.body).not.toContain("202-0-1760000000000");
+
+		const deleteResponse = await app.inject({
+			method: "DELETE",
+			url: "/doses/taken/101-0-1760000000000",
+			headers: { cookie: otherCookie },
+		});
+
+		expect(deleteResponse.statusCode).toBe(200);
+
+		const ownerDose = await testClient.execute({
+			sql: "SELECT COUNT(*) AS count FROM dose_tracking WHERE user_id = ? AND dose_id = ?",
+			args: [ownerId, "101-0-1760000000000"],
+		});
+		expect(Number(ownerDose.rows[0].count)).toBe(1);
+	});
+
+	it("enforces medication ownership on refill history and report generation", async () => {
+		const ownerId = await createUser("owner-refill");
+		const otherId = await createUser("other-refill");
+		const otherCookie = buildSessionCookie(app, otherId, "other-refill");
+		const medicationId = await seedMedication({ userId: ownerId, name: "Owner Refill Med", packCount: 2 });
+		await seedRefill({ userId: ownerId, medicationId });
+
+		const refillListResponse = await app.inject({
+			method: "GET",
+			url: `/medications/${medicationId}/refills`,
+			headers: { cookie: otherCookie },
+		});
+
+		expect(refillListResponse.statusCode).toBe(404);
+
+		const refillMutationResponse = await app.inject({
+			method: "POST",
+			url: `/medications/${medicationId}/refill`,
+			headers: { cookie: otherCookie },
+			payload: { packsAdded: 1, loosePillsAdded: 0 },
+		});
+
+		expect(refillMutationResponse.statusCode).toBe(404);
+
+		const reportResponse = await app.inject({
+			method: "POST",
+			url: "/medications/report-data",
+			headers: { cookie: otherCookie },
+			payload: { medicationIds: [medicationId] },
+		});
+
+		expect(reportResponse.statusCode).toBe(403);
+		expect(reportResponse.json()).toMatchObject({ error: "Access denied to medication" });
+	});
+
+	it("scopes share people to the authenticated user's medications", async () => {
+		const ownerId = await createUser("owner-share");
+		const otherId = await createUser("other-share");
+		const ownerCookie = buildSessionCookie(app, ownerId, "owner-share");
+
+		await seedMedication({ userId: ownerId, name: "Daniel Med", takenBy: ["Daniel"] });
+		await seedMedication({ userId: otherId, name: "Anna Med", takenBy: ["Anna"] });
+
+		const response = await app.inject({
+			method: "GET",
+			url: "/share/people",
+			headers: { cookie: ownerCookie },
+		});
+
+		expect(response.statusCode).toBe(200);
+		expect(response.json()).toEqual({ people: ["Daniel"] });
+	});
+
+	it("rejects mutation routes for read-only API keys across business endpoints", async () => {
+		const userId = await createUser("readonly-business-key");
+		const medicationId = await seedMedication({ userId, name: "Readonly Med" });
+		const apiToken = "ma_readonly_business_routes_123456789";
+		await insertApiKey({ userId, token: apiToken, scope: "read" });
+
+		const responses = await Promise.all([
+			app.inject({
+				method: "POST",
+				url: "/medications",
+				headers: { authorization: `Bearer ${apiToken}` },
+				payload: buildMedicationPayload("Blocked Create"),
+			}),
+			app.inject({
+				method: "POST",
+				url: "/doses/taken",
+				headers: { authorization: `Bearer ${apiToken}` },
+				payload: { doseId: "1-0-1760000000000" },
+			}),
+			app.inject({
+				method: "POST",
+				url: `/medications/${medicationId}/refill`,
+				headers: { authorization: `Bearer ${apiToken}` },
+				payload: { packsAdded: 1, loosePillsAdded: 0 },
+			}),
+			app.inject({
+				method: "POST",
+				url: "/share",
+				headers: { authorization: `Bearer ${apiToken}` },
+				payload: { takenBy: "Daniel", scheduleDays: 7 },
+			}),
+			app.inject({
+				method: "POST",
+				url: "/import",
+				headers: { authorization: `Bearer ${apiToken}` },
+				payload: buildImportPayload(),
+			}),
+		]);
+
+		for (const response of responses) {
+			expect(response.statusCode).toBe(403);
+			expect(response.json()).toMatchObject({ code: "API_KEY_SCOPE_FORBIDDEN" });
+		}
+	});
+
+	it("allows read-only API keys to use read endpoints while keeping data scoped to the key owner", async () => {
+		const userId = await createUser("readonly-export-user");
+		const otherId = await createUser("readonly-export-other");
+		await seedMedication({ userId, name: "Readable Owner Med" });
+		await seedMedication({ userId: otherId, name: "Unreadable Other Med" });
+		const apiToken = "ma_readonly_export_access_123456789";
+		await insertApiKey({ userId, token: apiToken, scope: "read" });
+
+		const response = await app.inject({
+			method: "GET",
+			url: "/export",
+			headers: { authorization: `Bearer ${apiToken}` },
+		});
+
+		expect(response.statusCode).toBe(200);
+		expect(response.body).toContain("Readable Owner Med");
+		expect(response.body).not.toContain("Unreadable Other Med");
+	});
+});

backend/src/test/doses.test.ts

@@ -1,487 +1,412 @@
-/**
- * Tests for /doses/taken API endpoints.
- * Tests marking doses as taken, listing taken doses, and unmarking.
- */
-import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
-import { buildTestApp, clearTestData, closeTestApp, createTestUser, type TestContext } from "./setup.js";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import cookie from "@fastify/cookie";
+import jwt from "@fastify/jwt";
+import { migrate } from "drizzle-orm/libsql/migrator";
+import Fastify, { type FastifyInstance } from "fastify";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { runAlterMigrations } from "../db/db-utils.js";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
 
-// =============================================================================
-// Route Registration
-// Since we can't easily import routes that depend on the global db,
-// we'll create simplified route handlers for testing the core logic.
-// =============================================================================
+const { testClient, testDb, mockedEnv } = vi.hoisted(() => {
+	const { createClient } = require("@libsql/client");
+	const { drizzle } = require("drizzle-orm/libsql");
+	const client = createClient({ url: ":memory:" });
+	const db = drizzle(client);
 
-async function registerDoseRoutes(ctx: TestContext) {
-	const { app, client } = ctx;
+	return {
+		testClient: client,
+		testDb: db,
+		mockedEnv: {
+			AUTH_ENABLED: true,
+			REGISTRATION_ENABLED: true,
+			FORM_LOGIN_ENABLED: true,
+			OIDC_ENABLED: false,
+			OIDC_PROVIDER_NAME: "SSO",
+			NODE_ENV: "test",
+			LOG_LEVEL: "silent",
+			PORT: 3000,
+			CORS_ORIGINS: "*",
+			JWT_SECRET: "test-jwt-secret",
+			REFRESH_SECRET: "test-refresh-secret",
+			COOKIE_SECRET: "test-cookie-secret",
+			ACCESS_TOKEN_TTL_MINUTES: 15,
+			REFRESH_TOKEN_TTL_DAYS: 7,
+			OPENAPI_DOCS_ENABLED: false,
+		},
+	};
+});
 
-	// GET /doses/taken - List all taken doses
-	app.get("/doses/taken", async (_request, _reply) => {
-		// In test mode, use user ID 1 (will be created in tests)
-		const userId = 1;
+vi.mock("../db/client.js", () => ({
+	db: testDb,
+	migrationsReady: Promise.resolve(),
+}));
 
-		const result = await client.execute({
-			sql: `SELECT dose_id, taken_at, marked_by FROM dose_tracking WHERE user_id = ?`,
-			args: [userId],
-		});
+vi.mock("../plugins/env.js", () => ({ env: mockedEnv }));
 
-		return {
-			doses: result.rows.map((d) => ({
-				doseId: d.dose_id,
-				takenAt: (d.taken_at as number) * 1000, // Convert to ms
-				markedBy: d.marked_by,
-			})),
-		};
+const { doseRoutes } = await import("../routes/doses.js");
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const migrationsFolder = resolve(__dirname, "../../drizzle");
+
+async function clearTables() {
+	await testClient.execute("DELETE FROM dose_tracking");
+	await testClient.execute("DELETE FROM share_tokens");
+	await testClient.execute("DELETE FROM api_keys");
+	await testClient.execute("DELETE FROM refresh_tokens");
+	await testClient.execute("DELETE FROM medications");
+	await testClient.execute("DELETE FROM user_settings");
+	await testClient.execute("DELETE FROM users");
+}
+
+async function createUser(username: string) {
+	const result = await testClient.execute({
+		sql: "INSERT INTO users (username, auth_provider, is_active) VALUES (?, 'local', 1) RETURNING id",
+		args: [username],
 	});
 
-	// POST /doses/taken - Mark a dose as taken
-	app.post<{ Body: { doseId: string } }>("/doses/taken", async (request, reply) => {
-		const userId = 1;
-		const { doseId } = request.body || {};
+	return Number(result.rows[0].id);
+}
 
-		if (!doseId || typeof doseId !== "string" || doseId.length === 0) {
-			return reply.status(400).send({ error: "doseId is required" });
-		}
-
-		// Check if already marked
-		const existing = await client.execute({
-			sql: `SELECT id FROM dose_tracking WHERE user_id = ? AND dose_id = ?`,
-			args: [userId, doseId],
-		});
-
-		if (existing.rows.length > 0) {
-			return { success: true, message: "Already marked" };
-		}
-
-		// Insert new record
-		await client.execute({
-			sql: `INSERT INTO dose_tracking (user_id, dose_id, marked_by) VALUES (?, ?, NULL)`,
-			args: [userId, doseId],
-		});
-
-		return { success: true };
-	});
-
-	// DELETE /doses/taken/:doseId - Unmark a dose
-	app.delete<{ Params: { doseId: string } }>("/doses/taken/:doseId", async (request, _reply) => {
-		const userId = 1;
-		const { doseId } = request.params;
-
-		// Check if this dose was also dismissed
-		const existing = await client.execute({
-			sql: `SELECT id, dismissed FROM dose_tracking WHERE user_id = ? AND dose_id = ?`,
-			args: [userId, doseId],
-		});
-
-		if (existing.rows.length > 0 && existing.rows[0].dismissed) {
-			// Already dismissed - keep the record as-is (don't delete)
-			// The dose stays dismissed, we just ignore the undo request
-		} else {
-			// Not dismissed - delete the record entirely
-			await client.execute({
-				sql: `DELETE FROM dose_tracking WHERE user_id = ? AND dose_id = ?`,
-				args: [userId, doseId],
-			});
-		}
-
-		return { success: true };
-	});
-
-	// POST /doses/dismiss - Dismiss missed doses without deducting stock
-	app.post<{ Body: { doseIds: string[] } }>("/doses/dismiss", async (request, reply) => {
-		const userId = 1;
-		const { doseIds } = request.body || {};
-
-		if (!doseIds || !Array.isArray(doseIds) || doseIds.length === 0) {
-			return reply.status(400).send({ error: "doseIds array is required" });
-		}
-
-		let dismissedCount = 0;
-		for (const doseId of doseIds) {
-			// Check if already exists
-			const existing = await client.execute({
-				sql: `SELECT id, dismissed FROM dose_tracking WHERE user_id = ? AND dose_id = ?`,
-				args: [userId, doseId],
-			});
-
-			if (existing.rows.length > 0) {
-				// Update to dismissed if not already
-				if (!existing.rows[0].dismissed) {
-					await client.execute({
-						sql: `UPDATE dose_tracking SET dismissed = 1 WHERE id = ?`,
-						args: [existing.rows[0].id],
-					});
-					dismissedCount++;
-				}
-			} else {
-				// Insert new dismissed record
-				await client.execute({
-					sql: `INSERT INTO dose_tracking (user_id, dose_id, dismissed) VALUES (?, ?, 1)`,
-					args: [userId, doseId],
-				});
-				dismissedCount++;
-			}
-		}
-
-		return { success: true, dismissedCount };
+async function insertMedication(options: {
+	id: number;
+	userId: number;
+	takenBy?: string[];
+	packCount?: number;
+	looseTablets?: number;
+	start?: string;
+}) {
+	const intakeStart = options.start ?? "2025-01-01T08:00:00.000Z";
+	await testClient.execute({
+		sql: `INSERT INTO medications (
+			id, user_id, name, taken_by_json, medication_form, package_type,
+			pack_count, blisters_per_pack, pills_per_blister, loose_tablets, stock_adjustment,
+			usage_json, every_json, start_json, intakes_json, intake_reminders_enabled
+		) VALUES (?, ?, 'Test Medication', ?, 'tablet', 'blister', ?, 1, 10, ?, 0, '[1]', '[1]', ?, '[]', 0)`,
+		args: [
+			options.id,
+			options.userId,
+			JSON.stringify(options.takenBy ?? []),
+			options.packCount ?? 1,
+			options.looseTablets ?? 0,
+			intakeStart,
+			"[]",
+		],
 	});
 }
 
-// =============================================================================
-// Tests
-// =============================================================================
+async function insertUserSettings(userId: number, stockCalculationMode: "automatic" | "manual" = "automatic") {
+	await testClient.execute({
+		sql: "INSERT INTO user_settings (user_id, stock_calculation_mode) VALUES (?, ?)",
+		args: [userId, stockCalculationMode],
+	});
+}
+
+async function _insertShareToken(userId: number, token: string, takenBy: string) {
+	await testClient.execute({
+		sql: "INSERT INTO share_tokens (user_id, token, taken_by, schedule_days) VALUES (?, ?, ?, 30)",
+		args: [userId, token, takenBy],
+	});
+}
+
+function buildSessionCookie(app: FastifyInstance, userId: number, username: string) {
+	const token = app.jwt.sign({ sub: userId, username });
+	return `access_token=${token}`;
+}
+
+async function insertDose(options: {
+	userId: number;
+	doseId: string;
+	markedBy?: string | null;
+	dismissed?: boolean;
+	takenAt?: number | null;
+	takenSource?: "manual" | "automatic";
+}) {
+	await testClient.execute({
+		sql: `INSERT INTO dose_tracking (user_id, dose_id, marked_by, dismissed, taken_at, taken_source)
+		      VALUES (?, ?, ?, ?, ?, ?)`,
+		args: [
+			options.userId,
+			options.doseId,
+			options.markedBy ?? null,
+			options.dismissed ? 1 : 0,
+			options.takenAt === undefined ? Math.floor(Date.now() / 1000) : (options.takenAt ?? 0),
+			options.takenSource ?? "manual",
+		],
+	});
+}
 
 describe("Dose Tracking API", () => {
-	let ctx: TestContext;
+	let app: FastifyInstance;
 	let userId: number;
+	let cookieHeader: string;
 
 	beforeAll(async () => {
-		ctx = await buildTestApp();
-		await registerDoseRoutes(ctx);
-		await ctx.app.ready();
+		await migrate(testDb, { migrationsFolder });
+		await runAlterMigrations(testClient);
+
+		app = Fastify({ logger: false, ajv: documentationSchemaAjv });
+		await app.register(cookie, { secret: "test-cookie-secret" });
+		await app.register(jwt, {
+			secret: "test-jwt-secret",
+			cookie: { cookieName: "access_token", signed: false },
+		});
+		await app.register(doseRoutes);
+		await app.ready();
 	});
 
 	afterAll(async () => {
-		await closeTestApp(ctx);
+		await app.close();
+		testClient.close();
 	});
 
 	beforeEach(async () => {
-		await clearTestData(ctx.client);
-		// Create test user - will get ID 1 since table is cleared
-		userId = await createTestUser(ctx.client, { username: "testuser" });
-		// Reset SQLite autoincrement so user gets ID 1
-		await ctx.client.execute("DELETE FROM sqlite_sequence WHERE name='users'");
-		await clearTestData(ctx.client);
-		userId = await createTestUser(ctx.client, { username: "testuser" });
+		await clearTables();
+		userId = await createUser("dose-test-user");
+		cookieHeader = buildSessionCookie(app, userId, "dose-test-user");
 	});
 
-	// ---------------------------------------------------------------------------
-	// POST /doses/taken
-	// ---------------------------------------------------------------------------
-
 	describe("POST /doses/taken", () => {
-		it("should mark a dose as taken", async () => {
+		it("marks a dose as taken", async () => {
 			const doseId = "1-0-1735344000000";
 
-			const response = await ctx.app.inject({
+			const response = await app.inject({
 				method: "POST",
 				url: "/doses/taken",
+				headers: { cookie: cookieHeader },
 				payload: { doseId },
 			});
 
 			expect(response.statusCode).toBe(200);
 			expect(response.json()).toEqual({ success: true });
 
-			// Verify in database
-			const result = await ctx.client.execute({
-				sql: `SELECT dose_id, marked_by FROM dose_tracking WHERE user_id = ? AND dose_id = ?`,
+			const result = await testClient.execute({
+				sql: "SELECT dose_id, marked_by, taken_source FROM dose_tracking WHERE user_id = ? AND dose_id = ?",
 				args: [userId, doseId],
 			});
-			expect(result.rows.length).toBe(1);
-			expect(result.rows[0].dose_id).toBe(doseId);
-			expect(result.rows[0].marked_by).toBeNull();
+			expect(result.rows).toEqual([
+				expect.objectContaining({ dose_id: doseId, marked_by: null, taken_source: "manual" }),
+			]);
 		});
 
-		it("should return idempotent response when dose already marked", async () => {
+		it("returns an idempotent response when the dose is already marked", async () => {
 			const doseId = "1-0-1735344000000";
+			await insertDose({ userId, doseId });
 
-			// Mark once
-			await ctx.app.inject({
-				method: "POST",
-				url: "/doses/taken",
-				payload: { doseId },
-			});
-
-			// Mark again
-			const response = await ctx.app.inject({
+			const response = await app.inject({
 				method: "POST",
 				url: "/doses/taken",
+				headers: { cookie: cookieHeader },
 				payload: { doseId },
 			});
 
 			expect(response.statusCode).toBe(200);
 			expect(response.json()).toEqual({ success: true, message: "Already marked" });
 
-			// Should still only have one record
-			const result = await ctx.client.execute({
-				sql: `SELECT COUNT(*) as count FROM dose_tracking WHERE user_id = ? AND dose_id = ?`,
+			const countResult = await testClient.execute({
+				sql: "SELECT COUNT(*) AS count FROM dose_tracking WHERE user_id = ? AND dose_id = ?",
 				args: [userId, doseId],
 			});
-			expect(result.rows[0].count).toBe(1);
+			expect(Number(countResult.rows[0].count)).toBe(1);
 		});
 
-		it("should reject request without doseId", async () => {
-			const response = await ctx.app.inject({
+		it("rejects requests without a doseId", async () => {
+			const response = await app.inject({
 				method: "POST",
 				url: "/doses/taken",
+				headers: { cookie: cookieHeader },
 				payload: {},
 			});
 
 			expect(response.statusCode).toBe(400);
-			expect(response.json()).toEqual({ error: "doseId is required" });
+			expect(response.json()).toEqual({ error: "Required" });
 		});
 
-		it("should reject request with empty doseId", async () => {
-			const response = await ctx.app.inject({
+		it("accepts dose IDs with a person suffix and special characters", async () => {
+			const doseId = "5-0-1735344000000-Max Müller";
+
+			const response = await app.inject({
 				method: "POST",
 				url: "/doses/taken",
-				payload: { doseId: "" },
+				headers: { cookie: cookieHeader },
+				payload: { doseId },
 			});
 
-			expect(response.statusCode).toBe(400);
-			expect(response.json()).toEqual({ error: "doseId is required" });
+			expect(response.statusCode).toBe(200);
+
+			const getResponse = await app.inject({
+				method: "GET",
+				url: "/doses/taken",
+				headers: { cookie: cookieHeader },
+			});
+
+			expect(getResponse.statusCode).toBe(200);
+			expect(getResponse.json().doses[0].doseId).toBe(doseId);
+		});
+
+		it("rejects taking a dose when the medication is out of stock", async () => {
+			await insertMedication({ id: 5, userId, packCount: 0, looseTablets: 0 });
+			await insertUserSettings(userId, "automatic");
+
+			const response = await app.inject({
+				method: "POST",
+				url: "/doses/taken",
+				headers: { cookie: cookieHeader },
+				payload: { doseId: "5-0-1735344000000" },
+			});
+
+			expect(response.statusCode).toBe(409);
+			expect(response.json()).toEqual({ error: "Medication is out of stock", code: "OUT_OF_STOCK" });
+		});
+
+		it("allows taking a historical dose when stock existed at that occurrence", async () => {
+			await insertMedication({
+				id: 6,
+				userId,
+				packCount: 1,
+				looseTablets: 0,
+				start: "2025-01-01T08:00:00.000Z",
+			});
+			await insertUserSettings(userId, "automatic");
+
+			const historicalDoseId = "6-0-1736064000000";
+			const response = await app.inject({
+				method: "POST",
+				url: "/doses/taken",
+				headers: { cookie: cookieHeader },
+				payload: { doseId: historicalDoseId },
+			});
+
+			expect(response.statusCode).toBe(200);
+			expect(response.json()).toEqual({ success: true });
 		});
 	});
 
-	// ---------------------------------------------------------------------------
-	// GET /doses/taken
-	// ---------------------------------------------------------------------------
-
 	describe("GET /doses/taken", () => {
-		it("should return empty array when no doses taken", async () => {
-			const response = await ctx.app.inject({
+		it("returns an empty array when no doses were taken", async () => {
+			const response = await app.inject({
 				method: "GET",
 				url: "/doses/taken",
+				headers: { cookie: cookieHeader },
 			});
 
 			expect(response.statusCode).toBe(200);
 			expect(response.json()).toEqual({ doses: [] });
 		});
 
-		it("should return list of taken doses", async () => {
-			const doseId1 = "1-0-1735344000000";
-			const doseId2 = "1-0-1735430400000";
-
-			// Mark two doses
-			await ctx.app.inject({
-				method: "POST",
-				url: "/doses/taken",
-				payload: { doseId: doseId1 },
-			});
-			await ctx.app.inject({
-				method: "POST",
-				url: "/doses/taken",
-				payload: { doseId: doseId2 },
+		it("returns only the authenticated user's taken doses with metadata", async () => {
+			const otherUserId = await createUser("dose-other-user");
+			await insertDose({
+				userId,
+				doseId: "1-0-1735344000000",
+				markedBy: "Daniel",
+				takenSource: "automatic",
 			});
+			await insertDose({ userId, doseId: "1-0-1735430400000" });
+			await insertDose({ userId: otherUserId, doseId: "9-0-1735516800000" });
 
-			const response = await ctx.app.inject({
+			const response = await app.inject({
 				method: "GET",
 				url: "/doses/taken",
+				headers: { cookie: cookieHeader },
 			});
 
 			expect(response.statusCode).toBe(200);
 			const data = response.json();
 			expect(data.doses).toHaveLength(2);
-			expect(data.doses.map((d: { doseId: string }) => d.doseId).sort()).toEqual([doseId1, doseId2].sort());
-			// Each dose should have a takenAt timestamp
-			for (const dose of data.doses) {
-				expect(dose.takenAt).toBeTypeOf("number");
-				expect(dose.takenAt).toBeGreaterThan(0);
-				expect(dose.markedBy).toBeNull();
-			}
-		});
-
-		it("should include markedBy when present", async () => {
-			const doseId = "1-0-1735344000000";
-
-			// Insert directly with markedBy
-			await ctx.client.execute({
-				sql: `INSERT INTO dose_tracking (user_id, dose_id, marked_by) VALUES (?, ?, ?)`,
-				args: [userId, doseId, "Daniel"],
-			});
-
-			const response = await ctx.app.inject({
-				method: "GET",
-				url: "/doses/taken",
-			});
-
-			expect(response.statusCode).toBe(200);
-			const data = response.json();
-			expect(data.doses).toHaveLength(1);
-			expect(data.doses[0].markedBy).toBe("Daniel");
+			expect(data.doses.map((dose: { doseId: string }) => dose.doseId).sort()).toEqual([
+				"1-0-1735344000000",
+				"1-0-1735430400000",
+			]);
+			expect(data.doses).toEqual(
+				expect.arrayContaining([
+					expect.objectContaining({ markedBy: "Daniel", takenSource: "automatic" }),
+					expect.objectContaining({ markedBy: null, takenSource: "manual" }),
+				])
+			);
 		});
 	});
 
-	// ---------------------------------------------------------------------------
-	// DELETE /doses/taken/:doseId
-	// ---------------------------------------------------------------------------
-
 	describe("DELETE /doses/taken/:doseId", () => {
-		it("should unmark a dose", async () => {
+		it("unmarks an existing dose", async () => {
 			const doseId = "1-0-1735344000000";
+			await insertDose({ userId, doseId });
 
-			// Mark first
-			await ctx.app.inject({
-				method: "POST",
-				url: "/doses/taken",
-				payload: { doseId },
-			});
-
-			// Verify marked
-			let result = await ctx.client.execute({
-				sql: `SELECT COUNT(*) as count FROM dose_tracking WHERE dose_id = ?`,
-				args: [doseId],
-			});
-			expect(result.rows[0].count).toBe(1);
-
-			// Unmark
-			const response = await ctx.app.inject({
+			const response = await app.inject({
 				method: "DELETE",
 				url: `/doses/taken/${encodeURIComponent(doseId)}`,
+				headers: { cookie: cookieHeader },
 			});
 
 			expect(response.statusCode).toBe(200);
 			expect(response.json()).toEqual({ success: true });
 
-			// Verify unmarked
-			result = await ctx.client.execute({
-				sql: `SELECT COUNT(*) as count FROM dose_tracking WHERE dose_id = ?`,
-				args: [doseId],
+			const countResult = await testClient.execute({
+				sql: "SELECT COUNT(*) AS count FROM dose_tracking WHERE user_id = ? AND dose_id = ?",
+				args: [userId, doseId],
 			});
-			expect(result.rows[0].count).toBe(0);
+			expect(Number(countResult.rows[0].count)).toBe(0);
 		});
 
-		it("should succeed even if dose was not marked", async () => {
-			const doseId = "nonexistent-dose-id";
+		it("keeps the record when the dose is dismissed", async () => {
+			const doseId = "1-0-1735344000000";
+			await insertDose({ userId, doseId, dismissed: true });
 
-			const response = await ctx.app.inject({
+			const response = await app.inject({
 				method: "DELETE",
 				url: `/doses/taken/${encodeURIComponent(doseId)}`,
+				headers: { cookie: cookieHeader },
 			});
 
 			expect(response.statusCode).toBe(200);
-			expect(response.json()).toEqual({ success: true });
+
+			const result = await testClient.execute({
+				sql: "SELECT dose_id, dismissed FROM dose_tracking WHERE user_id = ? AND dose_id = ?",
+				args: [userId, doseId],
+			});
+			expect(result.rows).toEqual([expect.objectContaining({ dose_id: doseId, dismissed: 1 })]);
 		});
 
-		it("should preserve dismissed status when unmarking a dose", async () => {
-			const doseId = "1-0-1735344000000";
-
-			// First dismiss the dose
-			await ctx.app.inject({
-				method: "POST",
-				url: "/doses/dismiss",
-				payload: { doseIds: [doseId] },
-			});
-
-			// Verify it's dismissed
-			let result = await ctx.client.execute({
-				sql: `SELECT dismissed, taken_at FROM dose_tracking WHERE dose_id = ?`,
-				args: [doseId],
-			});
-			expect(result.rows[0].dismissed).toBe(1);
-			const originalTakenAt = result.rows[0].taken_at;
-
-			// Now try to unmark it (undo) - should keep the dismissed record
-			const response = await ctx.app.inject({
+		it("still succeeds when the dose does not exist", async () => {
+			const response = await app.inject({
 				method: "DELETE",
-				url: `/doses/taken/${encodeURIComponent(doseId)}`,
+				url: "/doses/taken/nonexistent-dose-id",
+				headers: { cookie: cookieHeader },
 			});
 
 			expect(response.statusCode).toBe(200);
 			expect(response.json()).toEqual({ success: true });
-
-			// Verify the record still exists and is still dismissed
-			result = await ctx.client.execute({
-				sql: `SELECT dose_id, dismissed, taken_at FROM dose_tracking WHERE dose_id = ?`,
-				args: [doseId],
-			});
-			expect(result.rows.length).toBe(1);
-			expect(result.rows[0].dismissed).toBe(1);
-			expect(result.rows[0].taken_at).toBe(originalTakenAt); // unchanged
 		});
 	});
 
-	// ---------------------------------------------------------------------------
-	// Dose ID Format Tests
-	// ---------------------------------------------------------------------------
-
-	describe("Dose ID Format", () => {
-		it("should handle standard dose ID format: {medId}-{blisterIdx}-{timestamp}", async () => {
-			const doseId = "5-0-1735344000000";
-
-			const response = await ctx.app.inject({
-				method: "POST",
-				url: "/doses/taken",
-				payload: { doseId },
-			});
-
-			expect(response.statusCode).toBe(200);
-			expect(response.json()).toEqual({ success: true });
-		});
-
-		it("should handle dose ID with person: {medId}-{blisterIdx}-{timestamp}-{person}", async () => {
-			const doseId = "5-0-1735344000000-Daniel";
-
-			const response = await ctx.app.inject({
-				method: "POST",
-				url: "/doses/taken",
-				payload: { doseId },
-			});
-
-			expect(response.statusCode).toBe(200);
-			expect(response.json()).toEqual({ success: true });
-		});
-
-		it("should handle special characters in dose ID", async () => {
-			// Dose ID with URL-unsafe characters (edge case)
-			const doseId = "5-0-1735344000000-Max Müller";
-
-			const response = await ctx.app.inject({
-				method: "POST",
-				url: "/doses/taken",
-				payload: { doseId },
-			});
-
-			expect(response.statusCode).toBe(200);
-
-			// Can retrieve it
-			const getResponse = await ctx.app.inject({
-				method: "GET",
-				url: "/doses/taken",
-			});
-
-			expect(getResponse.json().doses[0].doseId).toBe(doseId);
-		});
-	});
-
-	// ---------------------------------------------------------------------------
-	// Dismiss Doses Tests (POST /doses/dismiss)
-	// ---------------------------------------------------------------------------
-
 	describe("POST /doses/dismiss", () => {
-		it("should dismiss multiple doses", async () => {
-			const doseIds = ["1-0-1735344000000", "1-0-1735430400000"];
-
-			const response = await ctx.app.inject({
+		it("dismisses multiple doses", async () => {
+			const response = await app.inject({
 				method: "POST",
 				url: "/doses/dismiss",
-				payload: { doseIds },
+				headers: { cookie: cookieHeader },
+				payload: { doseIds: ["1-0-1735344000000", "1-0-1735430400000"] },
 			});
 
 			expect(response.statusCode).toBe(200);
 			expect(response.json()).toEqual({ success: true, dismissedCount: 2 });
 
-			// Verify in database
-			const result = await ctx.client.execute({
-				sql: `SELECT dose_id, dismissed FROM dose_tracking WHERE user_id = ? AND dismissed = 1`,
+			const result = await testClient.execute({
+				sql: "SELECT COUNT(*) AS count FROM dose_tracking WHERE user_id = ? AND dismissed = 1",
 				args: [userId],
 			});
-			expect(result.rows.length).toBe(2);
+			expect(Number(result.rows[0].count)).toBe(2);
 		});
 
-		it("should not double-count already dismissed doses", async () => {
+		it("does not double-count already dismissed doses", async () => {
 			const doseId = "1-0-1735344000000";
+			await insertDose({ userId, doseId, dismissed: true });
 
-			// Dismiss once
-			await ctx.app.inject({
-				method: "POST",
-				url: "/doses/dismiss",
-				payload: { doseIds: [doseId] },
-			});
-
-			// Dismiss again
-			const response = await ctx.app.inject({
+			const response = await app.inject({
 				method: "POST",
 				url: "/doses/dismiss",
+				headers: { cookie: cookieHeader },
 				payload: { doseIds: [doseId] },
 			});
 
@@ -489,54 +414,71 @@ describe("Dose Tracking API", () => {
 			expect(response.json()).toEqual({ success: true, dismissedCount: 0 });
 		});
 
-		it("should reject empty doseIds array", async () => {
-			const response = await ctx.app.inject({
-				method: "POST",
-				url: "/doses/dismiss",
-				payload: { doseIds: [] },
-			});
-
-			expect(response.statusCode).toBe(400);
-			expect(response.json()).toEqual({ error: "doseIds array is required" });
-		});
-
-		it("should reject missing doseIds", async () => {
-			const response = await ctx.app.inject({
-				method: "POST",
-				url: "/doses/dismiss",
-				payload: {},
-			});
-
-			expect(response.statusCode).toBe(400);
-			expect(response.json()).toEqual({ error: "doseIds array is required" });
-		});
-
-		it("should dismiss a dose that was already taken (convert to dismissed)", async () => {
+		it("converts a taken dose into a dismissed one", async () => {
 			const doseId = "1-0-1735344000000";
+			await insertDose({ userId, doseId, dismissed: false });
 
-			// First mark as taken
-			await ctx.app.inject({
-				method: "POST",
-				url: "/doses/taken",
-				payload: { doseId },
-			});
-
-			// Then dismiss it
-			const response = await ctx.app.inject({
+			const response = await app.inject({
 				method: "POST",
 				url: "/doses/dismiss",
+				headers: { cookie: cookieHeader },
 				payload: { doseIds: [doseId] },
 			});
 
 			expect(response.statusCode).toBe(200);
 			expect(response.json()).toEqual({ success: true, dismissedCount: 1 });
 
-			// Verify it's now dismissed
-			const result = await ctx.client.execute({
-				sql: `SELECT dismissed FROM dose_tracking WHERE user_id = ? AND dose_id = ?`,
+			const result = await testClient.execute({
+				sql: "SELECT dismissed FROM dose_tracking WHERE user_id = ? AND dose_id = ?",
 				args: [userId, doseId],
 			});
-			expect(result.rows[0].dismissed).toBe(1);
+			expect(result.rows).toEqual([expect.objectContaining({ dismissed: 1 })]);
+		});
+
+		it("rejects missing or empty doseIds", async () => {
+			const emptyResponse = await app.inject({
+				method: "POST",
+				url: "/doses/dismiss",
+				headers: { cookie: cookieHeader },
+				payload: { doseIds: [] },
+			});
+
+			expect(emptyResponse.statusCode).toBe(400);
+			expect(emptyResponse.json()).toEqual({ error: "At least one doseId is required" });
+
+			const missingResponse = await app.inject({
+				method: "POST",
+				url: "/doses/dismiss",
+				headers: { cookie: cookieHeader },
+				payload: {},
+			});
+
+			expect(missingResponse.statusCode).toBe(400);
+			expect(missingResponse.json()).toEqual({ error: "Required" });
+		});
+	});
+
+	describe("DELETE /doses/dismiss", () => {
+		it("clears dismissed-only records and removes the dismissed flag from taken doses", async () => {
+			await insertDose({ userId, doseId: "1-0-1735344000000", dismissed: true, takenAt: null });
+			await insertDose({ userId, doseId: "1-0-1735430400000", dismissed: true, markedBy: "Daniel" });
+
+			const response = await app.inject({
+				method: "DELETE",
+				url: "/doses/dismiss",
+				headers: { cookie: cookieHeader },
+			});
+
+			expect(response.statusCode).toBe(200);
+			expect(response.json()).toEqual({ success: true, clearedCount: 2 });
+
+			const rows = await testClient.execute({
+				sql: "SELECT dose_id, dismissed, marked_by FROM dose_tracking WHERE user_id = ? ORDER BY dose_id ASC",
+				args: [userId],
+			});
+			expect(rows.rows).toEqual([
+				expect.objectContaining({ dose_id: "1-0-1735430400000", dismissed: 0, marked_by: "Daniel" }),
+			]);
 		});
 	});
 });

backend/src/test/e2e-routes.test.ts

@@ -10,6 +10,7 @@ import sensible from "@fastify/sensible";
 import type { Client } from "@libsql/client";
 import Fastify, { type FastifyInstance } from "fastify";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
 
 // Use vi.hoisted to create the db BEFORE mocks are set up
 const { testClient, testDb } = vi.hoisted(() => {
@@ -145,6 +146,7 @@ async function createSchema(client: Client) {
       language text NOT NULL DEFAULT 'en',
       stock_calculation_mode text NOT NULL DEFAULT 'automatic',
       share_stock_status integer NOT NULL DEFAULT 1,
+	share_medication_overview integer NOT NULL DEFAULT 0,
 	upcoming_today_only integer NOT NULL DEFAULT 0,
 	share_schedule_today_only integer NOT NULL DEFAULT 0,
 	swap_dashboard_main_sections integer NOT NULL DEFAULT 0,
@@ -247,7 +249,7 @@ describe("E2E Tests with Real Routes", () => {
 		await createSchema(testClient);
 
 		// Build app with real routes
-		app = Fastify({ logger: false });
+		app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 
 		await app.register(sensible);
 		await app.register(cookie, { secret: "test-cookie-secret" });
@@ -345,6 +347,37 @@ describe("E2E Tests with Real Routes", () => {
 				usedPrescription: true,
 			});
 		});
+
+		it("should not include refill history entries from another user for the same medication", async () => {
+			const medId = await createMedication(testClient, userId, "Report Isolation Med", ["Daniel"]);
+			const otherUserId = await _createUser(testClient, "report-isolation-other-user");
+
+			await testClient.execute({
+				sql: `INSERT INTO refill_history (medication_id, user_id, packs_added, loose_pills_added, used_prescription, refill_date)
+				      VALUES (?, ?, ?, ?, ?, ?)`,
+				args: [medId, userId, 1, 0, 0, 1735603200],
+			});
+			await testClient.execute({
+				sql: `INSERT INTO refill_history (medication_id, user_id, packs_added, loose_pills_added, used_prescription, refill_date)
+				      VALUES (?, ?, ?, ?, ?, ?)`,
+				args: [medId, otherUserId, 9, 99, 1, 1735689600],
+			});
+
+			const response = await app.inject({
+				method: "POST",
+				url: "/medications/report-data",
+				payload: { medicationIds: [medId] },
+			});
+
+			expect(response.statusCode).toBe(200);
+			const data = response.json();
+			expect(data[medId].refills).toHaveLength(1);
+			expect(data[medId].refills[0]).toMatchObject({
+				packsAdded: 1,
+				loosePillsAdded: 0,
+				usedPrescription: false,
+			});
+		});
 	});
 
 	afterAll(async () => {
@@ -503,6 +536,80 @@ describe("E2E Tests with Real Routes", () => {
 
 			expect(response.statusCode).toBe(404);
 		});
+
+		it("should return shared medication overview for a valid token", async () => {
+			await createMedication(testClient, userId, "Aspirin", ["Daniel"]);
+			const token = "abcdef0123456789";
+			await createShareToken(testClient, userId, "Daniel", token);
+
+			const response = await app.inject({
+				method: "GET",
+				url: `/share/${token}/overview`,
+			});
+
+			expect(response.statusCode).toBe(200);
+			expect(response.headers["cache-control"]).toBe("no-store");
+
+			const data = response.json();
+			expect(data.takenBy).toBe("Daniel");
+			expect(data.sharedBy).toBe("__anonymous__");
+			expect(Array.isArray(data.medications)).toBe(true);
+			expect(data.medications).toHaveLength(1);
+			expect(data.medications[0].name).toBe("Aspirin");
+			expect(data.medications[0].currentStock).toBeTypeOf("number");
+		});
+
+		it("should return 404 for unknown overview token", async () => {
+			const response = await app.inject({
+				method: "GET",
+				url: "/share/abcdef0123456789/overview",
+			});
+
+			expect(response.statusCode).toBe(404);
+			expect(response.json()).toEqual({ error: "not_found" });
+		});
+
+		it("should return 410 for expired overview token", async () => {
+			const token = "fedcba9876543210";
+			await testClient.execute({
+				sql: "INSERT INTO share_tokens (user_id, token, taken_by, schedule_days, expires_at) VALUES (?, ?, ?, 30, ?)",
+				args: [userId, token, "Daniel", Math.floor(Date.now() / 1000) - 60],
+			});
+
+			const response = await app.inject({
+				method: "GET",
+				url: `/share/${token}/overview`,
+			});
+
+			expect(response.statusCode).toBe(410);
+			const data = response.json();
+			expect(data.error).toBe("expired");
+			expect(data.expiredAt).toBeTypeOf("string");
+		});
+
+		it("should hide stock fields in overview when share_stock_status is disabled", async () => {
+			await createMedication(testClient, userId, "Ibuprofen", ["Daniel"]);
+			const token = "0123456789abcdef";
+			await createShareToken(testClient, userId, "Daniel", token);
+
+			await testClient.execute({
+				sql: "INSERT INTO user_settings (user_id, share_stock_status, low_stock_days) VALUES (?, 0, 30)",
+				args: [userId],
+			});
+
+			const response = await app.inject({
+				method: "GET",
+				url: `/share/${token}/overview`,
+			});
+
+			expect(response.statusCode).toBe(200);
+			const [medication] = response.json().medications;
+			expect(medication.currentStock).toBeNull();
+			expect(medication.capacity).toBeNull();
+			expect(medication.daysLeft).toBeNull();
+			expect(medication.depletionDate).toBeNull();
+			expect(medication.priority).toBeNull();
+		});
 	});
 
 	// ---------------------------------------------------------------------------
@@ -834,7 +941,7 @@ describe("E2E Tests with Real Routes", () => {
 			});
 
 			expect(response.statusCode).toBe(400);
-			expect(response.json().error).toBe("Invalid language");
+			expect(response.json().error).toMatch(/Invalid language|Bad Request/);
 		});
 
 		it("should create and update language via lightweight language endpoint", async () => {
@@ -1929,6 +2036,47 @@ describe("E2E Tests with Real Routes", () => {
 			expect(hasLooseRefill).toBe(true);
 		});
 
+		it("should not return refill history entries from another user for the same medication", async () => {
+			const createResponse = await app.inject({
+				method: "POST",
+				url: "/medications",
+				payload: {
+					name: "Refill Isolation Med",
+					packCount: 1,
+					blistersPerPack: 2,
+					pillsPerBlister: 10,
+					blisters: [{ usage: 1, every: 1, start: "2025-01-01T08:00:00.000Z" }],
+				},
+			});
+			const medId = createResponse.json().id;
+			const otherUserId = await _createUser(testClient, "refill-isolation-other-user");
+
+			await testClient.execute({
+				sql: `INSERT INTO refill_history (medication_id, user_id, packs_added, loose_pills_added, used_prescription, refill_date)
+				      VALUES (?, ?, ?, ?, ?, ?)`,
+				args: [medId, userId, 2, 3, 0, 1735603200],
+			});
+			await testClient.execute({
+				sql: `INSERT INTO refill_history (medication_id, user_id, packs_added, loose_pills_added, used_prescription, refill_date)
+				      VALUES (?, ?, ?, ?, ?, ?)`,
+				args: [medId, otherUserId, 8, 88, 1, 1735689600],
+			});
+
+			const response = await app.inject({
+				method: "GET",
+				url: `/medications/${medId}/refills`,
+			});
+
+			expect(response.statusCode).toBe(200);
+			const refills = response.json();
+			expect(refills).toHaveLength(1);
+			expect(refills[0]).toMatchObject({
+				packsAdded: 2,
+				loosePillsAdded: 3,
+				usedPrescription: false,
+			});
+		});
+
 		it("should return 404 for non-existent medication", async () => {
 			const response = await app.inject({
 				method: "GET",
@@ -2302,6 +2450,29 @@ describe("E2E Tests with Real Routes", () => {
 				payload: {
 					emailEnabled: true,
 					notificationEmail: "test@example.com",
+					reminderDaysBefore: 7,
+					repeatDailyReminders: false,
+					lowStockDays: 30,
+					normalStockDays: 90,
+					highStockDays: 180,
+					shoutrrrEnabled: false,
+					shoutrrrUrl: "",
+					emailStockReminders: true,
+					emailIntakeReminders: true,
+					emailPrescriptionReminders: true,
+					shoutrrrStockReminders: true,
+					shoutrrrIntakeReminders: true,
+					shoutrrrPrescriptionReminders: true,
+					skipRemindersForTakenDoses: false,
+					repeatRemindersEnabled: false,
+					reminderRepeatIntervalMinutes: 30,
+					maxNaggingReminders: 5,
+					language: "en",
+					stockCalculationMode: "automatic",
+					shareStockStatus: true,
+					upcomingTodayOnly: false,
+					shareScheduleTodayOnly: false,
+					swapDashboardMainSections: false,
 				},
 			});
 
@@ -2506,10 +2677,10 @@ describe("E2E Tests with Real Routes", () => {
 	});
 
 	// ---------------------------------------------------------------------------
-	// Package Type (blister, bottle, liquid_container) Tests
+	// Package Type (blister, bottle, tube, liquid_container) Tests
 	// ---------------------------------------------------------------------------
 
-	describe("Package type handling (blister, bottle, liquid_container)", () => {
+	describe("Package type handling (blister, bottle, tube, liquid_container)", () => {
 		const bottleMedication = {
 			name: "Vitamin D Drops",
 			packageType: "bottle",
@@ -2542,6 +2713,21 @@ describe("E2E Tests with Real Routes", () => {
 			blisters: [{ usage: 5, every: 1, start: "2025-01-01T08:00:00.000Z" }],
 		};
 
+		const tubeMedication = {
+			name: "Topical Cream",
+			medicationForm: "topical",
+			packageType: "tube",
+			doseUnit: "units",
+			packCount: 2,
+			packageAmountValue: 40,
+			packageAmountUnit: "g",
+			blistersPerPack: 1,
+			pillsPerBlister: 1,
+			totalPills: 80,
+			looseTablets: 80,
+			blisters: [{ usage: 2, every: 1, start: "2025-01-01T08:00:00.000Z" }],
+		};
+
 		it("should create and return bottle type medication", async () => {
 			const response = await app.inject({
 				method: "POST",
@@ -2698,6 +2884,72 @@ describe("E2E Tests with Real Routes", () => {
 			expect(data.refill.totalPillsAdded).toBe(35); // 1*30 + 5
 		});
 
+		it("should keep liquid_container refill additive and preserve amount baseline", async () => {
+			const createResponse = await app.inject({
+				method: "POST",
+				url: "/medications",
+				payload: {
+					...liquidContainerMedication,
+					packCount: 1,
+					packageAmountValue: 180,
+					totalPills: 180,
+					looseTablets: 180,
+				},
+			});
+			expect(createResponse.statusCode).toBe(200);
+			const medId = createResponse.json().id;
+
+			const refillResponse = await app.inject({
+				method: "POST",
+				url: `/medications/${medId}/refill`,
+				payload: { packsAdded: 1, loosePillsAdded: 0 },
+			});
+
+			expect(refillResponse.statusCode).toBe(200);
+			const refillData = refillResponse.json();
+			expect(refillData.refill.packsAdded).toBe(1);
+			expect(refillData.refill.loosePillsAdded).toBe(180);
+			expect(refillData.refill.totalPillsAdded).toBe(180);
+			expect(refillData.newStock.totalPills).toBe(360);
+
+			const medsResponse = await app.inject({ method: "GET", url: "/medications" });
+			expect(medsResponse.statusCode).toBe(200);
+			const med = medsResponse.json().find((m: Record<string, unknown>) => m.id === medId);
+			expect(med).toBeTruthy();
+			expect(med.totalPills).toBe(360);
+			expect(med.looseTablets).toBe(360);
+		});
+
+		it("should keep tube refill additive and preserve amount baseline", async () => {
+			const createResponse = await app.inject({
+				method: "POST",
+				url: "/medications",
+				payload: tubeMedication,
+			});
+			expect(createResponse.statusCode).toBe(200);
+			const medId = createResponse.json().id;
+
+			const refillResponse = await app.inject({
+				method: "POST",
+				url: `/medications/${medId}/refill`,
+				payload: { packsAdded: 1, loosePillsAdded: 0 },
+			});
+
+			expect(refillResponse.statusCode).toBe(200);
+			const refillData = refillResponse.json();
+			expect(refillData.refill.packsAdded).toBe(1);
+			expect(refillData.refill.loosePillsAdded).toBe(40);
+			expect(refillData.refill.totalPillsAdded).toBe(40);
+			expect(refillData.newStock.totalPills).toBe(120);
+
+			const medsResponse = await app.inject({ method: "GET", url: "/medications" });
+			expect(medsResponse.statusCode).toBe(200);
+			const med = medsResponse.json().find((m: Record<string, unknown>) => m.id === medId);
+			expect(med).toBeTruthy();
+			expect(med.totalPills).toBe(120);
+			expect(med.looseTablets).toBe(120);
+		});
+
 		it("should return correct totalPillsAdded in refill history for bottle type", async () => {
 			const createResponse = await app.inject({
 				method: "POST",

backend/src/test/intake-reminder-scheduler.test.ts

@@ -0,0 +1,258 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { db } from "../db/client.js";
+import { checkAndSendIntakeRemindersForUser } from "../services/intake-reminder-scheduler.js";
+
+vi.mock("../db/client.js", () => ({
+	db: {
+		select: vi.fn(),
+		insert: vi.fn(),
+	},
+}));
+
+function createLogger() {
+	return {
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+	};
+}
+
+describe("checkAndSendIntakeRemindersForUser", () => {
+	const mockedDb = vi.mocked(db);
+	let originalTz: string | undefined;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(new Date(2026, 0, 5, 10, 30, 0));
+		originalTz = process.env.TZ;
+		process.env.TZ = Intl.DateTimeFormat().resolvedOptions().timeZone;
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+		vi.restoreAllMocks();
+		if (originalTz === undefined) {
+			delete process.env.TZ;
+		} else {
+			process.env.TZ = originalTz;
+		}
+	});
+
+	it("auto-marks due intakes in automatic mode even when all intake reminder channels are disabled", async () => {
+		const insertedRows: Array<Record<string, unknown>> = [];
+		const selectMock = vi.mocked(mockedDb.select);
+		const insertMock = vi.mocked(mockedDb.insert);
+
+		selectMock
+			.mockImplementationOnce(
+				() =>
+					({
+						from: () => ({
+							where: () => ({
+								limit: async () => [{ username: "auto-user" }],
+							}),
+						}),
+					}) as never
+			)
+			.mockImplementationOnce(
+				() =>
+					({
+						from: () => ({
+							where: () => ({
+								orderBy: async () => [
+									{
+										id: 7,
+										userId: 11,
+										name: "Vitamin D",
+										genericName: null,
+										takenByJson: null,
+										packageType: "blister",
+										medicationForm: "tablet",
+										packCount: 1,
+										blistersPerPack: 1,
+										pillsPerBlister: 10,
+										looseTablets: 0,
+										stockAdjustment: 0,
+										pillWeightMg: null,
+										doseUnit: "mg",
+										isObsolete: false,
+										intakeRemindersEnabled: false,
+										intakesJson: JSON.stringify([
+											{
+												usage: 1,
+												every: 1,
+												start: "2026-01-05T08:00:00.000Z",
+												takenBy: null,
+												intakeRemindersEnabled: false,
+											},
+										]),
+										usageJson: "[]",
+										everyJson: "[]",
+										startJson: "[]",
+									},
+								],
+							}),
+						}),
+					}) as never
+			)
+			.mockImplementationOnce(
+				() =>
+					({
+						from: () => ({
+							where: async () => [],
+						}),
+					}) as never
+			)
+			.mockImplementationOnce(
+				() =>
+					({
+						from: () => ({
+							where: async () => [],
+						}),
+					}) as never
+			);
+
+		insertMock.mockImplementation(
+			() =>
+				({
+					values: async (row: Record<string, unknown>) => {
+						insertedRows.push(row);
+					},
+				}) as never
+		);
+
+		const logger = createLogger();
+
+		await checkAndSendIntakeRemindersForUser(
+			{
+				userId: 11,
+				language: "en",
+				stockCalculationMode: "automatic",
+				emailEnabled: false,
+				notificationEmail: null,
+				emailIntakeReminders: false,
+				shoutrrrEnabled: false,
+				shoutrrrUrl: null,
+				shoutrrrIntakeReminders: false,
+				repeatRemindersEnabled: false,
+			} as never,
+			logger as never
+		);
+
+		expect(insertedRows).toHaveLength(1);
+		expect(insertedRows[0]).toMatchObject({
+			userId: 11,
+			doseId: `7-0-${new Date(2026, 0, 5).getTime()}`,
+			markedBy: null,
+			takenSource: "automatic",
+			dismissed: false,
+		});
+		expect(logger.info).toHaveBeenCalledWith("[IntakeReminder] Auto-marked 1 due intake dose(s) as taken");
+	});
+
+	it("does not auto-mark due intakes when current stock is empty", async () => {
+		const insertedRows: Array<Record<string, unknown>> = [];
+		const selectMock = vi.mocked(mockedDb.select);
+		const insertMock = vi.mocked(mockedDb.insert);
+
+		selectMock
+			.mockImplementationOnce(
+				() =>
+					({
+						from: () => ({
+							where: () => ({
+								limit: async () => [{ username: "auto-user" }],
+							}),
+						}),
+					}) as never
+			)
+			.mockImplementationOnce(
+				() =>
+					({
+						from: () => ({
+							where: () => ({
+								orderBy: async () => [
+									{
+										id: 7,
+										userId: 11,
+										name: "Vitamin D",
+										genericName: null,
+										takenByJson: null,
+										packageType: "blister",
+										medicationForm: "tablet",
+										packCount: 0,
+										blistersPerPack: 1,
+										pillsPerBlister: 10,
+										looseTablets: 0,
+										stockAdjustment: 0,
+										pillWeightMg: null,
+										doseUnit: "mg",
+										isObsolete: false,
+										intakeRemindersEnabled: false,
+										intakesJson: JSON.stringify([
+											{
+												usage: 1,
+												every: 1,
+												start: "2026-01-05T08:00:00.000Z",
+												takenBy: null,
+												intakeRemindersEnabled: false,
+											},
+										]),
+										usageJson: "[]",
+										everyJson: "[]",
+										startJson: "[]",
+									},
+								],
+							}),
+						}),
+					}) as never
+			)
+			.mockImplementationOnce(
+				() =>
+					({
+						from: () => ({
+							where: async () => [],
+						}),
+					}) as never
+			)
+			.mockImplementationOnce(
+				() =>
+					({
+						from: () => ({
+							where: async () => [],
+						}),
+					}) as never
+			);
+
+		insertMock.mockImplementation(
+			() =>
+				({
+					values: async (row: Record<string, unknown>) => {
+						insertedRows.push(row);
+					},
+				}) as never
+		);
+
+		const logger = createLogger();
+
+		await checkAndSendIntakeRemindersForUser(
+			{
+				userId: 11,
+				language: "en",
+				stockCalculationMode: "automatic",
+				emailEnabled: false,
+				notificationEmail: null,
+				emailIntakeReminders: false,
+				shoutrrrEnabled: false,
+				shoutrrrUrl: null,
+				shoutrrrIntakeReminders: false,
+				repeatRemindersEnabled: false,
+			} as never,
+			logger as never
+		);
+
+		expect(insertedRows).toHaveLength(0);
+		expect(logger.info).not.toHaveBeenCalledWith("[IntakeReminder] Auto-marked 1 due intake dose(s) as taken");
+	});
+});

backend/src/test/integration.test.ts

@@ -10,6 +10,7 @@ import sensible from "@fastify/sensible";
 import type { Client } from "@libsql/client";
 import Fastify, { type FastifyInstance } from "fastify";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
 
 // Use vi.hoisted to create the db BEFORE mocks are set up
 const { testClient, testDb } = vi.hoisted(() => {
@@ -139,6 +140,7 @@ async function createSchema(client: Client) {
       language text NOT NULL DEFAULT 'en',
       stock_calculation_mode text NOT NULL DEFAULT 'automatic',
       share_stock_status integer NOT NULL DEFAULT 1,
+	share_medication_overview integer NOT NULL DEFAULT 0,
 	upcoming_today_only integer NOT NULL DEFAULT 0,
 	share_schedule_today_only integer NOT NULL DEFAULT 0,
 	swap_dashboard_main_sections integer NOT NULL DEFAULT 0,
@@ -203,7 +205,7 @@ describe("Integration Tests", () => {
 	beforeAll(async () => {
 		await createSchema(testClient);
 
-		app = Fastify({ logger: false });
+		app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 		await app.register(sensible);
 		await app.register(cookie, { secret: "test-cookie-secret" });
 		await app.register(jwt, {
@@ -253,6 +255,9 @@ describe("Integration Tests", () => {
 				url: "/medications",
 				payload: {
 					name: "Test Med",
+					packCount: 1,
+					blistersPerPack: 1,
+					pillsPerBlister: 10,
 					blisters: [{ usage: 1, every: 1, start: "2025-01-01T08:00:00.000Z" }],
 				},
 			});
@@ -306,6 +311,9 @@ describe("Integration Tests", () => {
 				url: "/medications",
 				payload: {
 					name: "Test Med",
+					packCount: 1,
+					blistersPerPack: 1,
+					pillsPerBlister: 10,
 					blisters: [{ usage: 1, every: 1, start: "2025-01-10T08:00:00.000Z" }],
 				},
 			});
@@ -344,6 +352,9 @@ describe("Integration Tests", () => {
 				url: "/medications",
 				payload: {
 					name: "Test Med",
+					packCount: 1,
+					blistersPerPack: 1,
+					pillsPerBlister: 10,
 					blisters: [
 						{ usage: 1, every: 1, start: "2025-01-01T08:00:00.000Z" },
 						{ usage: 0.5, every: 1, start: "2025-01-05T20:00:00.000Z" },
@@ -405,6 +416,9 @@ describe("Integration Tests", () => {
 				url: "/medications",
 				payload: {
 					name: "Weekly Med",
+					packCount: 1,
+					blistersPerPack: 1,
+					pillsPerBlister: 10,
 					blisters: [{ usage: 1, every: 7, start: "2025-10-17T08:00:00" }],
 				},
 			});
@@ -542,6 +556,9 @@ describe("Integration Tests", () => {
 				url: "/medications",
 				payload: {
 					name: "Interval Med",
+					packCount: 1,
+					blistersPerPack: 1,
+					pillsPerBlister: 10,
 					blisters: [{ usage: 1, every: 1, start: "2025-10-17T08:00:00" }],
 				},
 			});
@@ -596,6 +613,9 @@ describe("Integration Tests", () => {
 				payload: {
 					name: "Aspirin",
 					takenBy: ["Daniel"],
+					packCount: 1,
+					blistersPerPack: 1,
+					pillsPerBlister: 10,
 					blisters: [{ usage: 1, every: 1, start: "2025-01-01T08:00:00.000Z" }],
 				},
 			});

backend/src/test/oidc.test.ts

@@ -1,6 +1,7 @@
 import cookie from "@fastify/cookie";
 import Fastify from "fastify";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
 
 type OidcMocks = {
 	discovery: ReturnType<typeof vi.fn>;
@@ -54,7 +55,7 @@ async function buildOidcApp(envOverrides: Record<string, unknown>) {
 
 	const { oidcRoutes } = await import("../routes/oidc.js");
 
-	const app = Fastify({ logger: false });
+	const app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 	await app.register(cookie, { secret: "test-cookie-secret" });
 	app.decorate("config", {
 		accessSecret: "test-jwt-secret-12345",

backend/src/test/planner.test.ts

@@ -1,6 +1,7 @@
 import type { Client } from "@libsql/client";
 import Fastify, { type FastifyInstance } from "fastify";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
 
 // Create test database and mocks before anything else (hoisted)
 const {
@@ -156,6 +157,7 @@ async function createSchema(client: Client) {
       language text NOT NULL DEFAULT 'en',
       stock_calculation_mode text NOT NULL DEFAULT 'automatic',
       share_stock_status integer NOT NULL DEFAULT 1,
+	share_medication_overview integer NOT NULL DEFAULT 0,
 	upcoming_today_only integer NOT NULL DEFAULT 0,
 	share_schedule_today_only integer NOT NULL DEFAULT 0,
 	swap_dashboard_main_sections integer NOT NULL DEFAULT 0,
@@ -214,7 +216,7 @@ describe("Planner Routes", () => {
 			args: [],
 		});
 
-		app = Fastify({ logger: false });
+		app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 		await app.register(plannerRoutes);
 		await app.ready();
 

backend/src/test/routes-real.test.ts

@@ -4,6 +4,7 @@ import { migrate } from "drizzle-orm/libsql/migrator";
 import Fastify, { type FastifyInstance } from "fastify";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { runAlterMigrations } from "../db/db-utils.js";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
 
 const { testClient, testDb, mockedEnv, nodemailerSendMail, fetchMock } = vi.hoisted(() => {
 	const { createClient } = require("@libsql/client");
@@ -45,7 +46,9 @@ vi.mock("nodemailer", () => ({
 	},
 }));
 
-const { settingsRoutes, sendShoutrrrNotification } = await import("../routes/settings.js");
+const { settingsRoutes, sendShoutrrrNotification, loadUserSettings, getAllUserSettings } = await import(
+	"../routes/settings.js"
+);
 const { exportRoutes } = await import("../routes/export.js");
 const { reportRoutes } = await import("../routes/report.js");
 
@@ -106,7 +109,7 @@ describe("Real route coverage: settings/export/report", () => {
 	beforeAll(async () => {
 		await migrate(testDb, { migrationsFolder });
 		await runAlterMigrations(testClient);
-		app = Fastify({ logger: false });
+		app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 		await app.register(settingsRoutes);
 		await app.register(exportRoutes);
 		await app.register(reportRoutes);
@@ -142,6 +145,73 @@ describe("Real route coverage: settings/export/report", () => {
 		expect(body.shareScheduleTodayOnly).toBe(false);
 	});
 
+	it("GET /settings returns a non-empty serialized payload with SMTP fields", async () => {
+		process.env.SMTP_HOST = "smtp.example.com";
+		process.env.SMTP_PORT = "2525";
+		process.env.SMTP_USER = "mailer@example.com";
+		process.env.SMTP_FROM = "MedAssist <mailer@example.com>";
+		process.env.SMTP_PASS = "secret";
+
+		await app.inject({
+			method: "PUT",
+			url: "/settings",
+			payload: {
+				emailEnabled: true,
+				notificationEmail: "person@example.com",
+				reminderDaysBefore: 5,
+				repeatDailyReminders: true,
+				lowStockDays: 14,
+				normalStockDays: 45,
+				highStockDays: 90,
+				shoutrrrEnabled: false,
+				shoutrrrUrl: "",
+				emailStockReminders: true,
+				emailIntakeReminders: true,
+				emailPrescriptionReminders: true,
+				shoutrrrStockReminders: true,
+				shoutrrrIntakeReminders: true,
+				shoutrrrPrescriptionReminders: true,
+				skipRemindersForTakenDoses: false,
+				repeatRemindersEnabled: true,
+				reminderRepeatIntervalMinutes: 20,
+				maxNaggingReminders: 4,
+				language: "en",
+				stockCalculationMode: "manual",
+				shareStockStatus: true,
+				upcomingTodayOnly: true,
+				shareScheduleTodayOnly: true,
+				swapDashboardMainSections: true,
+			},
+		});
+
+		const response = await app.inject({ method: "GET", url: "/settings" });
+
+		expect(response.statusCode).toBe(200);
+		expect(response.body).not.toBe("{}");
+
+		const body = response.json();
+		expect(body).toEqual(
+			expect.objectContaining({
+				emailEnabled: true,
+				notificationEmail: "person@example.com",
+				reminderDaysBefore: 5,
+				repeatDailyReminders: true,
+				repeatRemindersEnabled: true,
+				reminderRepeatIntervalMinutes: 20,
+				maxNaggingReminders: 4,
+				stockCalculationMode: "manual",
+				upcomingTodayOnly: true,
+				shareScheduleTodayOnly: true,
+				swapDashboardMainSections: true,
+				smtpHost: "smtp.example.com",
+				smtpPort: 2525,
+				smtpUser: "mailer@example.com",
+				smtpFrom: "MedAssist <mailer@example.com>",
+				hasSmtpPassword: true,
+			})
+		);
+	});
+
 	it("PUT /settings disables repeatDailyReminders when no stock reminder channel exists", async () => {
 		const response = await app.inject({
 			method: "PUT",
@@ -190,7 +260,30 @@ describe("Real route coverage: settings/export/report", () => {
 			payload: { language: "fr" },
 		});
 		expect(response.statusCode).toBe(400);
-		expect(response.json().error).toBe("Invalid language");
+		expect(response.json().error).toMatch(/Invalid language|Bad Request/);
+	});
+
+	it("PUT /settings/language creates and updates the stored language", async () => {
+		let response = await app.inject({
+			method: "PUT",
+			url: "/settings/language",
+			payload: { language: "de" },
+		});
+
+		expect(response.statusCode).toBe(200);
+
+		response = await app.inject({
+			method: "PUT",
+			url: "/settings/language",
+			payload: { language: "en" },
+		});
+
+		expect(response.statusCode).toBe(200);
+
+		const stored = await testClient.execute({
+			sql: "SELECT language FROM user_settings WHERE user_id = 1",
+		});
+		expect(stored.rows[0].language).toBe("en");
 	});
 
 	it("POST /settings/test-email fails when SMTP is not configured", async () => {
@@ -224,6 +317,22 @@ describe("Real route coverage: settings/export/report", () => {
 		expect(nodemailerSendMail).toHaveBeenCalledTimes(1);
 	});
 
+	it("POST /settings/test-email maps generic transport failures to HTTP 500", async () => {
+		process.env.SMTP_HOST = "smtp.example.com";
+		process.env.SMTP_USER = "mailer@example.com";
+		process.env.SMTP_PASS = "secret";
+		nodemailerSendMail.mockRejectedValue(new Error("socket hang up"));
+
+		const response = await app.inject({
+			method: "POST",
+			url: "/settings/test-email",
+			payload: { email: "person@example.com" },
+		});
+
+		expect(response.statusCode).toBe(500);
+		expect(response.json()).toMatchObject({ code: "TEST_EMAIL_FAILED" });
+	});
+
 	it("POST /settings/test-shoutrrr validates URL presence", async () => {
 		const response = await app.inject({
 			method: "POST",
@@ -233,6 +342,30 @@ describe("Real route coverage: settings/export/report", () => {
 		expect(response.statusCode).toBe(400);
 	});
 
+	it("POST /settings/test-shoutrrr returns 500 when notification delivery fails", async () => {
+		const response = await app.inject({
+			method: "POST",
+			url: "/settings/test-shoutrrr",
+			payload: { url: "ftp://invalid.example.com/topic" },
+		});
+
+		expect(response.statusCode).toBe(500);
+		expect(response.json().error).toMatch(/Only HTTP\/HTTPS protocols are allowed|Unsupported URL format/);
+	});
+
+	it("POST /settings/test-shoutrrr returns 200 for a valid ntfy target", async () => {
+		fetchMock.mockResolvedValue({ ok: true });
+
+		const response = await app.inject({
+			method: "POST",
+			url: "/settings/test-shoutrrr",
+			payload: { url: "ntfy://ntfy.sh/medassist" },
+		});
+
+		expect(response.statusCode).toBe(200);
+		expect(response.json()).toEqual({ success: true, message: "Test notification sent successfully" });
+	});
+
 	it("sendShoutrrrNotification blocks localhost/private targets", async () => {
 		const result = await sendShoutrrrNotification("http://127.0.0.1/hook", "test", "message");
 		expect(result.success).toBe(false);
@@ -266,6 +399,169 @@ describe("Real route coverage: settings/export/report", () => {
 		expect(JSON.parse(call[1].body)).toMatchObject({ title: "Title", message: "Body" });
 	});
 
+	it("sendShoutrrrNotification returns HTTP response errors for ntfy-style endpoints", async () => {
+		fetchMock.mockResolvedValue({ ok: false, status: 429, text: () => Promise.resolve("rate limited") });
+
+		const result = await sendShoutrrrNotification("https://ntfy.sh/medassist", "Title", "Body");
+
+		expect(result).toEqual({ success: false, error: "HTTP 429: rate limited" });
+	});
+
+	it("sendShoutrrrNotification rejects invalid Discord webhook identifiers", async () => {
+		const result = await sendShoutrrrNotification("discord://bad-token@not-a-number", "Title", "Body");
+
+		expect(result).toEqual({ success: false, error: "Invalid Discord webhook ID" });
+	});
+
+	it("sendShoutrrrNotification validates Pushover URL credentials", async () => {
+		const result = await sendShoutrrrNotification("pushover://missing-token", "Title", "Body");
+
+		expect(result).toEqual({ success: false, error: "Invalid Pushover URL format" });
+	});
+
+	it("sendShoutrrrNotification requires Telegram chats and validates tokens", async () => {
+		let result = await sendShoutrrrNotification("telegram://123:abc@telegram", "Title", "Body");
+		expect(result).toEqual({ success: false, error: "Telegram URL requires chats parameter" });
+
+		result = await sendShoutrrrNotification("telegram://invalid@telegram?chats=123", "Title", "Body");
+		expect(result).toEqual({ success: false, error: "Invalid Telegram token format" });
+	});
+
+	it("sendShoutrrrNotification converts Gotify URLs and supports disabletls", async () => {
+		fetchMock.mockResolvedValue({ ok: true });
+
+		const result = await sendShoutrrrNotification(
+			"gotify://push.example.com/basepath/token123?disabletls=yes&priority=8",
+			"Title",
+			"Body"
+		);
+
+		expect(result).toEqual({ success: true });
+		const [targetUrl, requestInit] = fetchMock.mock.calls[0];
+		expect(targetUrl).toBe("http://push.example.com/basepath/message?token=token123");
+		expect(requestInit.body).toBe("Body\n\n(priority=8)");
+		expect(requestInit.headers).toMatchObject({ Tags: "pill" });
+	});
+
+	it("loadUserSettings creates defaults for users without settings", async () => {
+		const settings = await loadUserSettings(1);
+
+		expect(settings).toEqual(
+			expect.objectContaining({
+				userId: 1,
+				emailEnabled: false,
+				emailPrescriptionReminders: true,
+				shoutrrrPrescriptionReminders: true,
+				stockCalculationMode: "automatic",
+				shareStockStatus: true,
+			})
+		);
+	});
+
+	it("loadUserSettings maps persisted settings", async () => {
+		await testClient.execute({
+			sql: `INSERT INTO user_settings (
+				user_id, email_enabled, notification_email, email_stock_reminders, email_intake_reminders,
+				email_prescription_reminders, shoutrrr_enabled, shoutrrr_url, shoutrrr_stock_reminders,
+				shoutrrr_intake_reminders, shoutrrr_prescription_reminders, reminder_days_before,
+				repeat_daily_reminders, low_stock_days, normal_stock_days, high_stock_days, language,
+				stock_calculation_mode, share_stock_status, skip_reminders_for_taken_doses,
+				repeat_reminders_enabled, reminder_repeat_interval_minutes, max_nagging_reminders,
+				upcoming_today_only, share_schedule_today_only, swap_dashboard_main_sections
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			args: [
+				1,
+				1,
+				"person@example.com",
+				1,
+				1,
+				1,
+				0,
+				null,
+				1,
+				1,
+				1,
+				4,
+				0,
+				12,
+				30,
+				90,
+				"de",
+				"manual",
+				1,
+				0,
+				0,
+				30,
+				5,
+				0,
+				0,
+				0,
+			],
+		});
+
+		const settings = await loadUserSettings(1);
+
+		expect(settings).toEqual(
+			expect.objectContaining({
+				notificationEmail: "person@example.com",
+				skipRemindersForTakenDoses: false,
+				repeatRemindersEnabled: false,
+				reminderRepeatIntervalMinutes: 30,
+				maxNaggingReminders: 5,
+				stockCalculationMode: "manual",
+				shareStockStatus: true,
+				upcomingTodayOnly: false,
+				shareScheduleTodayOnly: false,
+				swapDashboardMainSections: false,
+			})
+		);
+	});
+
+	it("getAllUserSettings returns mapped entries for each persisted user", async () => {
+		await testClient.execute({
+			sql: "INSERT INTO users (id, username, auth_provider, is_active) VALUES (?, ?, ?, 1)",
+			args: [2, "second-user", "local"],
+		});
+		await testClient.execute({
+			sql: `INSERT INTO user_settings (
+				user_id, email_enabled, notification_email, email_stock_reminders, email_intake_reminders,
+				email_prescription_reminders, shoutrrr_enabled, shoutrrr_url, shoutrrr_stock_reminders,
+				shoutrrr_intake_reminders, shoutrrr_prescription_reminders, reminder_days_before,
+				repeat_daily_reminders, low_stock_days, normal_stock_days, high_stock_days, language,
+				stock_calculation_mode, share_stock_status, upcoming_today_only, share_schedule_today_only,
+				swap_dashboard_main_sections
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			args: [1, 0, null, 1, 1, 1, 1, "ntfy://ntfy.sh/topic", 1, 1, 1, 7, 1, 30, 60, 120, "en", "manual", 1, 1, 0, 1],
+		});
+		await testClient.execute({
+			sql: `INSERT INTO user_settings (
+				user_id, email_enabled, notification_email, email_stock_reminders, email_intake_reminders,
+				email_prescription_reminders, shoutrrr_enabled, shoutrrr_url, shoutrrr_stock_reminders,
+				shoutrrr_intake_reminders, shoutrrr_prescription_reminders, reminder_days_before,
+				repeat_daily_reminders, low_stock_days, normal_stock_days, high_stock_days, language,
+				stock_calculation_mode, share_stock_status, upcoming_today_only, share_schedule_today_only,
+				swap_dashboard_main_sections
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			args: [2, 1, "second@example.com", 0, 1, 1, 0, null, 1, 1, 1, 10, 0, 20, 50, 100, "de", "automatic", 1, 0, 0, 0],
+		});
+
+		const allSettings = await getAllUserSettings();
+
+		expect(allSettings).toHaveLength(2);
+		expect(allSettings).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({ userId: 1, stockCalculationMode: "manual", upcomingTodayOnly: true }),
+				expect.objectContaining({
+					userId: 2,
+					emailPrescriptionReminders: true,
+					shoutrrrPrescriptionReminders: true,
+					stockCalculationMode: "automatic",
+					shareStockStatus: true,
+				}),
+			])
+		);
+	});
+
 	it("POST /medications/report-data returns 403 for meds not owned by user", async () => {
 		await seedMedication("Owned Med");
 		const response = await app.inject({

backend/src/test/server.test.ts

@@ -6,6 +6,7 @@ import cors from "@fastify/cors";
 import sensible from "@fastify/sensible";
 import Fastify, { type FastifyInstance } from "fastify";
 import { afterEach, describe, expect, it } from "vitest";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
 
 // Import from utils to avoid index.ts import side effects (server start)
 import {
@@ -197,6 +198,7 @@ describe("Server Bootstrap", () => {
 				logger: {
 					level: "silent", // Disable logging for tests
 				},
+				ajv: documentationSchemaAjv,
 			});
 
 			expect(app).toBeDefined();
@@ -206,7 +208,7 @@ describe("Server Bootstrap", () => {
 		});
 
 		it("should register sensible plugin", async () => {
-			const app = Fastify({ logger: false });
+			const app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 			await app.register(sensible);
 
 			// Sensible adds error helpers
@@ -219,7 +221,7 @@ describe("Server Bootstrap", () => {
 		it("should register cors plugin with multiple origins", async () => {
 			const origins = ["http://localhost:5173", "http://localhost:4173"];
 
-			const app = Fastify({ logger: false });
+			const app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 			await app.register(cors, { origin: origins, credentials: true });
 
 			// Add a test route
@@ -243,7 +245,7 @@ describe("Server Bootstrap", () => {
 		});
 
 		it("should register cookie plugin", async () => {
-			const app = Fastify({ logger: false });
+			const app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 			await app.register(cookie, { secret: "test-cookie-secret" });
 
 			// Add a test route that sets a cookie
@@ -267,7 +269,7 @@ describe("Server Bootstrap", () => {
 
 	describe("Config Decorator", () => {
 		it("should create config with auth settings", async () => {
-			const app = Fastify({ logger: false });
+			const app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 
 			const accessTtlMinutes = 15;
 			const refreshTtlDays = 7;
@@ -369,7 +371,7 @@ describe("Server Bootstrap", () => {
 
 	describe("Route Registration", () => {
 		it("should register multiple route plugins", async () => {
-			const app = Fastify({ logger: false });
+			const app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 
 			// Mock route plugins
 			const healthRoutes = async (app: FastifyInstance) => {
@@ -402,7 +404,7 @@ describe("Server Bootstrap", () => {
 
 	describe("Server Startup", () => {
 		it("should listen on specified port", async () => {
-			const app = Fastify({ logger: false });
+			const app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 
 			app.get("/test", async () => ({ ok: true }));
 
@@ -415,7 +417,7 @@ describe("Server Bootstrap", () => {
 		});
 
 		it("should handle listen errors gracefully", async () => {
-			const app = Fastify({ logger: false });
+			const app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 
 			// Try to listen on an invalid port
 			await expect(app.listen({ port: -1, host: "127.0.0.1" })).rejects.toThrow();

backend/src/test/services.test.ts

@@ -21,6 +21,7 @@ import {
 	parseIntakeReminderState,
 	parseReminderState,
 	parseTakenByJson,
+	personTakesMedication,
 } from "../utils/scheduler-utils.js";
 
 // Helper to convert Blister to Intake for tests
@@ -151,6 +152,16 @@ describe("Scheduler Utils - Timezone Functions", () => {
 	});
 });
 
+describe("Scheduler Utils - Sharing", () => {
+	it("treats the all-share sentinel as matching intake-specific assignees", () => {
+		const intakes = [blisterToIntake({ usage: 1, every: 1, start: "2025-01-01T08:00:00.000Z" }, "Max")];
+
+		expect(personTakesMedication("all", [], intakes)).toBe(true);
+		expect(personTakesMedication("Max", [], intakes)).toBe(true);
+		expect(personTakesMedication("Anna", [], intakes)).toBe(false);
+	});
+});
+
 describe("Scheduler Utils - Blister Parsing", () => {
 	describe("parseBlisters", () => {
 		it("should parse valid blister JSON arrays", () => {

backend/src/test/settings-auth-security.test.ts

@@ -0,0 +1,396 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import cookie from "@fastify/cookie";
+import jwt from "@fastify/jwt";
+import sensible from "@fastify/sensible";
+import { migrate } from "drizzle-orm/libsql/migrator";
+import Fastify, { type FastifyInstance } from "fastify";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { runAlterMigrations } from "../db/db-utils.js";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
+
+const { testClient, testDb, mockedEnv, nodemailerSendMail } = vi.hoisted(() => {
+	const { createClient } = require("@libsql/client");
+	const { drizzle } = require("drizzle-orm/libsql");
+	const client = createClient({ url: ":memory:" });
+	const db = drizzle(client);
+
+	return {
+		testClient: client,
+		testDb: db,
+		mockedEnv: {
+			AUTH_ENABLED: true,
+			REGISTRATION_ENABLED: true,
+			FORM_LOGIN_ENABLED: true,
+			OIDC_ENABLED: false,
+			OIDC_PROVIDER_NAME: "SSO",
+			NODE_ENV: "test",
+			LOG_LEVEL: "silent",
+			PORT: 3000,
+			CORS_ORIGINS: "*",
+			JWT_SECRET: "test-jwt-secret",
+			REFRESH_SECRET: "test-refresh-secret",
+			COOKIE_SECRET: "test-cookie-secret",
+			ACCESS_TOKEN_TTL_MINUTES: 15,
+			REFRESH_TOKEN_TTL_DAYS: 7,
+			OPENAPI_DOCS_ENABLED: false,
+		},
+		nodemailerSendMail: vi.fn(),
+	};
+});
+
+vi.mock("../db/client.js", () => ({
+	db: testDb,
+	migrationsReady: Promise.resolve(),
+}));
+
+vi.mock("../plugins/env.js", () => ({ env: mockedEnv }));
+
+vi.mock("nodemailer", () => ({
+	default: {
+		createTransport: () => ({
+			sendMail: nodemailerSendMail,
+		}),
+	},
+}));
+
+const { settingsRoutes } = await import("../routes/settings.js");
+const { apiKeyRoutes } = await import("../routes/api-keys.js");
+const { hashApiKeyToken } = await import("../plugins/auth.js");
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const migrationsFolder = resolve(__dirname, "../../drizzle");
+
+async function clearTables() {
+	await testClient.execute("DELETE FROM api_keys");
+	await testClient.execute("DELETE FROM refresh_tokens");
+	await testClient.execute("DELETE FROM user_settings");
+	await testClient.execute("DELETE FROM users");
+}
+
+async function createUser(username: string) {
+	const result = await testClient.execute({
+		sql: "INSERT INTO users (username, auth_provider, is_active) VALUES (?, 'local', 1) RETURNING id",
+		args: [username],
+	});
+
+	return Number(result.rows[0].id);
+}
+
+function buildSessionCookie(app: FastifyInstance, userId: number, username: string) {
+	const token = app.jwt.sign({ sub: userId, username });
+	return `access_token=${token}`;
+}
+
+async function insertApiKey(options: {
+	userId: number;
+	token: string;
+	scope?: "read" | "write";
+	isActive?: boolean;
+	expiresAt?: Date | null;
+}) {
+	const expiresAtValue = options.expiresAt ? Math.floor(options.expiresAt.getTime() / 1000) : null;
+
+	const result = await testClient.execute({
+		sql: `INSERT INTO api_keys (user_id, name, key_hash, token_prefix, scope, is_active, expires_at)
+		      VALUES (?, ?, ?, ?, ?, ?, ?) RETURNING id`,
+		args: [
+			options.userId,
+			"Seeded Key",
+			hashApiKeyToken(options.token),
+			`${options.token.slice(0, 12)}...`,
+			options.scope ?? "write",
+			options.isActive === false ? 0 : 1,
+			expiresAtValue,
+		],
+	});
+
+	return Number(result.rows[0].id);
+}
+
+describe("Settings and API key security contracts", () => {
+	let app: FastifyInstance;
+
+	beforeAll(async () => {
+		await migrate(testDb, { migrationsFolder });
+		await runAlterMigrations(testClient);
+
+		app = Fastify({ logger: false, ajv: documentationSchemaAjv });
+		await app.register(sensible);
+		await app.register(cookie, { secret: "test-cookie-secret" });
+		await app.register(jwt, {
+			secret: "test-jwt-secret",
+			cookie: { cookieName: "access_token", signed: false },
+		});
+		await app.register(settingsRoutes);
+		await app.register(apiKeyRoutes);
+		await app.ready();
+	});
+
+	afterAll(async () => {
+		await app.close();
+		testClient.close();
+	});
+
+	beforeEach(async () => {
+		vi.clearAllMocks();
+		await clearTables();
+		delete process.env.SMTP_HOST;
+		delete process.env.SMTP_USER;
+		delete process.env.SMTP_TOKEN;
+		delete process.env.SMTP_PASS;
+		delete process.env.SMTP_FROM;
+		delete process.env.SMTP_PORT;
+		delete process.env.SMTP_SECURE;
+	});
+
+	it("rejects GET /settings without authentication when auth is enabled", async () => {
+		const response = await app.inject({ method: "GET", url: "/settings" });
+
+		expect(response.statusCode).toBe(401);
+		expect(response.json()).toMatchObject({ code: "AUTH_REQUIRED" });
+	});
+
+	it("returns settings defaults for an authenticated session cookie", async () => {
+		const userId = await createUser("settings-session-user");
+		const response = await app.inject({
+			method: "GET",
+			url: "/settings",
+			headers: { cookie: buildSessionCookie(app, userId, "settings-session-user") },
+		});
+
+		expect(response.statusCode).toBe(200);
+		expect(response.json()).toEqual(
+			expect.objectContaining({
+				emailEnabled: false,
+				language: "en",
+				stockCalculationMode: "automatic",
+			})
+		);
+	});
+
+	it("allows GET /settings with a read-only API key", async () => {
+		const userId = await createUser("settings-read-user");
+		process.env.SMTP_HOST = "smtp.example.com";
+		process.env.SMTP_PORT = "2525";
+
+		const apiToken = "ma_read_only_valid_token_123456789";
+		await insertApiKey({ userId, token: apiToken, scope: "read" });
+
+		const response = await app.inject({
+			method: "GET",
+			url: "/settings",
+			headers: { authorization: `Bearer ${apiToken}` },
+		});
+
+		expect(response.statusCode).toBe(200);
+		expect(response.json()).toEqual(
+			expect.objectContaining({
+				smtpHost: "smtp.example.com",
+				smtpPort: 2525,
+			})
+		);
+	});
+
+	it("rejects PUT /settings with a read-only API key", async () => {
+		const userId = await createUser("settings-read-mutation-user");
+		const apiToken = "ma_read_only_mutation_token_123456789";
+		await insertApiKey({ userId, token: apiToken, scope: "read" });
+
+		const response = await app.inject({
+			method: "PUT",
+			url: "/settings",
+			headers: { authorization: `Bearer ${apiToken}` },
+			payload: {
+				emailEnabled: false,
+				notificationEmail: "",
+				reminderDaysBefore: 7,
+				repeatDailyReminders: false,
+				lowStockDays: 30,
+				normalStockDays: 90,
+				highStockDays: 180,
+				shoutrrrEnabled: false,
+				shoutrrrUrl: "",
+				emailStockReminders: true,
+				emailIntakeReminders: true,
+				emailPrescriptionReminders: true,
+				shoutrrrStockReminders: true,
+				shoutrrrIntakeReminders: true,
+				shoutrrrPrescriptionReminders: true,
+				skipRemindersForTakenDoses: false,
+				repeatRemindersEnabled: false,
+				reminderRepeatIntervalMinutes: 30,
+				maxNaggingReminders: 5,
+				language: "en",
+				stockCalculationMode: "automatic",
+				shareStockStatus: true,
+				upcomingTodayOnly: false,
+				shareScheduleTodayOnly: false,
+				swapDashboardMainSections: false,
+			},
+		});
+
+		expect(response.statusCode).toBe(403);
+		expect(response.json()).toMatchObject({ code: "API_KEY_SCOPE_FORBIDDEN" });
+	});
+
+	it("rejects invalid API key bearer tokens for GET /settings", async () => {
+		const response = await app.inject({
+			method: "GET",
+			url: "/settings",
+			headers: { authorization: "Bearer definitely-not-a-medassist-key" },
+		});
+
+		expect(response.statusCode).toBe(401);
+		expect(response.json()).toMatchObject({ code: "INVALID_API_KEY" });
+	});
+
+	it("rejects expired API keys for GET /settings", async () => {
+		const userId = await createUser("settings-expired-key-user");
+		const apiToken = "ma_expired_token_for_settings_123456789";
+		await insertApiKey({
+			userId,
+			token: apiToken,
+			scope: "read",
+			expiresAt: new Date(Date.now() - 60_000),
+		});
+
+		const response = await app.inject({
+			method: "GET",
+			url: "/settings",
+			headers: { authorization: `Bearer ${apiToken}` },
+		});
+
+		expect(response.statusCode).toBe(401);
+		expect(response.json()).toMatchObject({ code: "API_KEY_EXPIRED" });
+	});
+
+	it("rotates API keys and does not leak raw tokens from the list endpoint", async () => {
+		const userId = await createUser("api-key-session-user");
+		const cookieHeader = buildSessionCookie(app, userId, "api-key-session-user");
+
+		const firstCreate = await app.inject({
+			method: "POST",
+			url: "/auth/api-keys",
+			headers: { cookie: cookieHeader },
+			payload: { name: "Primary key", scope: "write", expiresInDays: 30 },
+		});
+
+		expect(firstCreate.statusCode).toBe(201);
+		const firstBody = firstCreate.json();
+		expect(firstBody.token).toMatch(/^ma_/);
+
+		const secondCreate = await app.inject({
+			method: "POST",
+			url: "/auth/api-keys",
+			headers: { cookie: cookieHeader },
+			payload: { name: "Rotated key", scope: "write", expiresInDays: 30 },
+		});
+
+		expect(secondCreate.statusCode).toBe(201);
+		const secondBody = secondCreate.json();
+
+		const listResponse = await app.inject({
+			method: "GET",
+			url: "/auth/api-keys",
+			headers: { cookie: cookieHeader },
+		});
+
+		expect(listResponse.statusCode).toBe(200);
+		expect(listResponse.body).not.toContain(firstBody.token);
+		expect(listResponse.body).not.toContain(secondBody.token);
+		expect(listResponse.body).not.toContain("keyHash");
+		expect(listResponse.json().keys).toHaveLength(2);
+
+		const dbState = await testClient.execute({
+			sql: "SELECT name, is_active FROM api_keys WHERE user_id = ? ORDER BY id ASC",
+			args: [userId],
+		});
+		expect(dbState.rows).toEqual([
+			expect.objectContaining({ name: "Primary key", is_active: 0 }),
+			expect.objectContaining({ name: "Rotated key", is_active: 1 }),
+		]);
+	});
+
+	it("rejects API key rotation when authenticated with a read-only API key", async () => {
+		const userId = await createUser("api-key-readonly-rotate-user");
+		const readOnlyToken = "ma_readonly_rotation_denied_123456789";
+		await insertApiKey({ userId, token: readOnlyToken, scope: "read" });
+
+		const response = await app.inject({
+			method: "POST",
+			url: "/auth/api-keys",
+			headers: { authorization: `Bearer ${readOnlyToken}` },
+			payload: { name: "Blocked rotation", scope: "write", expiresInDays: 30 },
+		});
+
+		expect(response.statusCode).toBe(403);
+		expect(response.json()).toMatchObject({ code: "API_KEY_SCOPE_FORBIDDEN" });
+	});
+
+	it("returns 404 when deleting an API key owned by a different user", async () => {
+		const ownerUserId = await createUser("api-key-owner");
+		const otherUserId = await createUser("api-key-other-user");
+		const otherCookieHeader = buildSessionCookie(app, otherUserId, "api-key-other-user");
+
+		const keyId = await insertApiKey({
+			userId: ownerUserId,
+			token: "ma_write_owner_token_123456789",
+			scope: "write",
+		});
+
+		const response = await app.inject({
+			method: "DELETE",
+			url: `/auth/api-keys/${keyId}`,
+			headers: { cookie: otherCookieHeader },
+		});
+
+		expect(response.statusCode).toBe(404);
+		expect(response.json()).toMatchObject({ code: "API_KEY_NOT_FOUND" });
+	});
+
+	it("maps SMTP recipient rejection to HTTP 400 instead of a generic 500", async () => {
+		const userId = await createUser("settings-email-recipient-user");
+		process.env.SMTP_HOST = "smtp.example.com";
+		process.env.SMTP_USER = "mailer@example.com";
+		process.env.SMTP_PASS = "secret";
+		nodemailerSendMail.mockResolvedValue({
+			accepted: [],
+			rejected: ["missing@example.com"],
+			response: "550 5.1.1 recipient address rejected",
+		});
+
+		const response = await app.inject({
+			method: "POST",
+			url: "/settings/test-email",
+			headers: { cookie: buildSessionCookie(app, userId, "settings-email-recipient-user") },
+			payload: { email: "missing@example.com" },
+		});
+
+		expect(response.statusCode).toBe(400);
+		expect(response.json()).toMatchObject({ code: "EMAIL_RECIPIENT_REJECTED" });
+	});
+
+	it("maps missing SMTP acceptance to HTTP 502 for test email", async () => {
+		const userId = await createUser("settings-email-unconfirmed-user");
+		process.env.SMTP_HOST = "smtp.example.com";
+		process.env.SMTP_USER = "mailer@example.com";
+		process.env.SMTP_PASS = "secret";
+		nodemailerSendMail.mockResolvedValue({
+			accepted: [],
+			rejected: [],
+			response: "250 queued without explicit acceptance",
+		});
+
+		const response = await app.inject({
+			method: "POST",
+			url: "/settings/test-email",
+			headers: { cookie: buildSessionCookie(app, userId, "settings-email-unconfirmed-user") },
+			payload: { email: "person@example.com" },
+		});
+
+		expect(response.statusCode).toBe(502);
+		expect(response.json()).toMatchObject({ code: "SMTP_DELIVERY_UNCONFIRMED" });
+	});
+});

backend/src/test/setup.ts

@@ -13,6 +13,7 @@ import { type Client, createClient } from "@libsql/client";
 import { drizzle } from "drizzle-orm/libsql";
 import { migrate } from "drizzle-orm/libsql/migrator";
 import Fastify, { type FastifyInstance } from "fastify";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
 
 // Get migrations folder path
 const __filename = fileURLToPath(import.meta.url);
@@ -44,7 +45,7 @@ export async function buildTestApp(): Promise<TestContext> {
 	await runTestMigrations(client);
 
 	// Create Fastify app with minimal plugins
-	const app = Fastify({ logger: false });
+	const app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 
 	await app.register(sensible);
 	await app.register(cookie, { secret: "test-cookie-secret" });
@@ -217,13 +218,20 @@ export interface UpdateUserSettingsOptions {
 	stockCalculationMode?: "automatic" | "manual";
 	lowStockDays?: number;
 	shareStockStatus?: boolean;
+	shareMedicationOverview?: boolean;
 }
 
 /**
  * Create or update user settings
  */
 export async function setUserSettings(client: Client, options: UpdateUserSettingsOptions): Promise<void> {
-	const { userId, stockCalculationMode = "automatic", lowStockDays = 30, shareStockStatus } = options;
+	const {
+		userId,
+		stockCalculationMode = "automatic",
+		lowStockDays = 30,
+		shareStockStatus,
+		shareMedicationOverview,
+	} = options;
 
 	// Check if settings exist
 	const existing = await client.execute({
@@ -232,20 +240,46 @@ export async function setUserSettings(client: Client, options: UpdateUserSetting
 	});
 
 	if (existing.rows.length > 0) {
+		const updateArgs = [stockCalculationMode, lowStockDays] as Array<string | number>;
+		let updateSql = "UPDATE user_settings SET stock_calculation_mode = ?, low_stock_days = ?";
+
+		if (shareStockStatus !== undefined) {
+			updateSql += ", share_stock_status = ?";
+			updateArgs.push(shareStockStatus ? 1 : 0);
+		}
+
+		if (shareMedicationOverview !== undefined) {
+			updateSql += ", share_medication_overview = ?";
+			updateArgs.push(shareMedicationOverview ? 1 : 0);
+		}
+
+		updateSql += " WHERE user_id = ?";
+		updateArgs.push(userId);
+
 		await client.execute({
-			sql: `UPDATE user_settings SET stock_calculation_mode = ?, low_stock_days = ?${shareStockStatus !== undefined ? ", share_stock_status = ?" : ""} WHERE user_id = ?`,
-			args:
-				shareStockStatus !== undefined
-					? [stockCalculationMode, lowStockDays, shareStockStatus ? 1 : 0, userId]
-					: [stockCalculationMode, lowStockDays, userId],
+			sql: updateSql,
+			args: updateArgs,
 		});
 	} else {
+		const insertColumns = ["user_id", "stock_calculation_mode", "low_stock_days"];
+		const insertPlaceholders = ["?", "?", "?"];
+		const insertArgs = [userId, stockCalculationMode, lowStockDays] as Array<string | number>;
+
+		if (shareStockStatus !== undefined) {
+			insertColumns.push("share_stock_status");
+			insertPlaceholders.push("?");
+			insertArgs.push(shareStockStatus ? 1 : 0);
+		}
+
+		if (shareMedicationOverview !== undefined) {
+			insertColumns.push("share_medication_overview");
+			insertPlaceholders.push("?");
+			insertArgs.push(shareMedicationOverview ? 1 : 0);
+		}
+
 		await client.execute({
-			sql: `INSERT INTO user_settings (user_id, stock_calculation_mode, low_stock_days${shareStockStatus !== undefined ? ", share_stock_status" : ""}) VALUES (?, ?, ?${shareStockStatus !== undefined ? ", ?" : ""})`,
-			args:
-				shareStockStatus !== undefined
-					? [userId, stockCalculationMode, lowStockDays, shareStockStatus ? 1 : 0]
-					: [userId, stockCalculationMode, lowStockDays],
+			sql: `INSERT INTO user_settings (${insertColumns.join(", ")}) VALUES (${insertPlaceholders.join(", ")})`,
+			args: insertArgs,
 		});
 	}
 }

backend/src/test/stock-semantics-parity.test.ts

@@ -4,6 +4,7 @@ import { migrate } from "drizzle-orm/libsql/migrator";
 import Fastify, { type FastifyInstance } from "fastify";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { runAlterMigrations } from "../db/db-utils.js";
+import { documentationSchemaAjv } from "../utils/documentation-schema-keywords.js";
 
 const { testClient, testDb, mockedEnv } = vi.hoisted(() => {
 	const { createClient } = require("@libsql/client");
@@ -173,7 +174,7 @@ describe("Stock semantics parity (planner usage vs scheduler)", () => {
 	beforeAll(async () => {
 		await migrate(testDb, { migrationsFolder });
 		await runAlterMigrations(testClient);
-		app = Fastify({ logger: false });
+		app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 		await app.register(medicationRoutes);
 		await app.ready();
 	});

backend/src/types/fastify.d.ts

@@ -5,7 +5,12 @@ import "@fastify/jwt";
 export interface AuthUser {
 	id: number;
 	username: string;
-	role: string;
+}
+
+export interface AuthContext {
+	method: "session" | "api_key";
+	scope: "read" | "write";
+	apiKeyId?: number;
 }
 
 declare module "fastify" {
@@ -22,6 +27,7 @@ declare module "fastify" {
 
 	interface FastifyRequest {
 		user?: AuthUser | null;
+		authContext?: AuthContext;
 		correlationId?: string;
 	}
 }

backend/src/utils/documentation-schema-keywords.ts

@@ -0,0 +1,10 @@
+import type { Plugin } from "ajv";
+
+export const registerDocumentationSchemaKeywords: Plugin<unknown> = (ajv) => {
+	ajv.addKeyword({ keyword: "example", valid: true });
+	return ajv;
+};
+
+export const documentationSchemaAjv = {
+	plugins: [registerDocumentationSchemaKeywords],
+};

backend/src/utils/openapi-route-standards.ts

@@ -0,0 +1,114 @@
+import type { FastifyInstance, RouteOptions } from "fastify";
+
+type SecurityEntry = Readonly<Record<string, readonly string[]>>;
+
+const defaultProtectedSecurity: readonly SecurityEntry[] = [{ bearerAuth: [] }, { cookieAuth: [] }];
+
+export const genericErrorSchema = {
+	type: "object",
+	properties: {
+		error: { type: "string" },
+		code: { type: "string" },
+	},
+} as const;
+
+export const validationErrorSchema = {
+	type: "object",
+	additionalProperties: true,
+} as const;
+
+export const idParamsSchema = {
+	type: "object",
+	required: ["id"],
+	properties: {
+		id: { type: "string", pattern: "^\\d+$" },
+	},
+} as const;
+
+export const tokenParamsSchema = {
+	type: "object",
+	required: ["token"],
+	properties: {
+		token: { type: "string", minLength: 1 },
+	},
+} as const;
+
+export const successResponseSchema = {
+	type: "object",
+	properties: {
+		success: { type: "boolean" },
+	},
+} as const;
+
+export const messageResponseSchema = {
+	type: "object",
+	properties: {
+		success: { type: "boolean" },
+		message: { type: "string" },
+	},
+} as const;
+
+export type OpenApiRouteStandardsOptions = {
+	tag: string;
+	protectedByDefault: boolean;
+	protectedPaths?: RegExp[];
+	publicPaths?: RegExp[];
+};
+
+function asMethods(method: RouteOptions["method"]): string[] {
+	if (Array.isArray(method)) return method.map((m) => String(m).toUpperCase());
+	return [String(method).toUpperCase()];
+}
+
+function pathMatches(path: string, patterns: RegExp[] | undefined): boolean {
+	if (!patterns || patterns.length === 0) return false;
+	return patterns.some((pattern) => pattern.test(path));
+}
+
+function buildDefaultSummary(methods: string[], path: string): string {
+	const methodText = methods.join("/");
+	return `${methodText} ${path}`;
+}
+
+function buildDefaultDescription(requiresAuth: boolean): string {
+	return requiresAuth
+		? "Protected endpoint. Requires Bearer token (API key or JWT) or session cookie."
+		: "Public endpoint.";
+}
+
+export function applyOpenApiRouteStandards(app: FastifyInstance, options: OpenApiRouteStandardsOptions): void {
+	app.addHook("onRoute", (routeOptions) => {
+		const methods = asMethods(routeOptions.method);
+		const path = routeOptions.url;
+
+		const isExplicitlyPublic = pathMatches(path, options.publicPaths);
+		const isExplicitlyProtected = pathMatches(path, options.protectedPaths);
+		let requiresAuth = options.protectedByDefault;
+		if (isExplicitlyPublic) {
+			requiresAuth = false;
+		} else if (isExplicitlyProtected) {
+			requiresAuth = true;
+		}
+
+		routeOptions.schema = routeOptions.schema ?? {};
+		routeOptions.schema.tags = routeOptions.schema.tags ?? [options.tag];
+		routeOptions.schema.summary = routeOptions.schema.summary ?? buildDefaultSummary(methods, path);
+		routeOptions.schema.description = routeOptions.schema.description ?? buildDefaultDescription(requiresAuth);
+
+		if (requiresAuth) {
+			routeOptions.schema.security = routeOptions.schema.security ?? defaultProtectedSecurity;
+			routeOptions.schema.response = {
+				...(routeOptions.schema.response ?? {}),
+				401: (routeOptions.schema.response as Record<number | string, unknown> | undefined)?.[401] ?? {
+					type: "object",
+					properties: {
+						error: { type: "string" },
+						code: { type: "string" },
+					},
+				},
+			};
+		} else if (routeOptions.schema.security === undefined) {
+			routeOptions.schema.security = [];
+		}
+	});
+}

backend/src/utils/package-profiles.ts

@@ -0,0 +1,32 @@
+export const PACKAGE_TYPES = ["blister", "bottle", "tube", "liquid_container"] as const;
+
+export type PackageType = (typeof PACKAGE_TYPES)[number];
+
+const PACKAGE_TYPE_SET = new Set<string>(PACKAGE_TYPES);
+
+export function normalizePackageType(packageType?: string | null): PackageType {
+	if (packageType && PACKAGE_TYPE_SET.has(packageType)) {
+		return packageType as PackageType;
+	}
+	return "blister";
+}
+
+export function isTubePackageType(packageType?: string | null): boolean {
+	return normalizePackageType(packageType) === "tube";
+}
+
+export function isLiquidContainerPackageType(packageType?: string | null): boolean {
+	return normalizePackageType(packageType) === "liquid_container";
+}
+
+export function isAmountBasedPackageType(packageType?: string | null): boolean {
+	const normalized = normalizePackageType(packageType);
+	return normalized === "bottle" || normalized === "tube" || normalized === "liquid_container";
+}
+
+export function getPlannerUnitKind(packageType?: string | null): "pills" | "ml" | "units" {
+	const normalized = normalizePackageType(packageType);
+	if (normalized === "tube") return "units";
+	if (normalized === "liquid_container") return "ml";
+	return "pills";
+}

backend/src/utils/scheduler-utils.ts

@@ -4,6 +4,7 @@
  */
 
 import { getDateLocale, type Language } from "../i18n/translations.js";
+import { isLiquidContainerPackageType, isTubePackageType } from "./package-profiles.js";
 
 // Legacy type - individual blister schedule (DEPRECATED: use Intake instead)
 export type Blister = { usage: number; every: number; start: string };
@@ -36,9 +37,9 @@ export function normalizeIntakeUsageForStock(
 ): number {
 	const usage = Number(intake.usage);
 	if (!Number.isFinite(usage) || usage <= 0) return 0;
-	if (packageType === "tube") return 0;
+	if (isTubePackageType(packageType)) return 0;
 
-	const isLiquidStock = packageType === "liquid_container" || medicationForm === "liquid";
+	const isLiquidStock = isLiquidContainerPackageType(packageType) || medicationForm === "liquid";
 	if (!isLiquidStock) return usage;
 
 	if (intake.intakeUnit === "tsp") return usage * 5;
@@ -291,6 +292,7 @@ export function getAllTakenByForMedication(medicationTakenBy: string[], intakes:
  * Check if a person takes this medication (either via medication-level or intake-level takenBy).
  */
 export function personTakesMedication(person: string, medicationTakenBy: string[], intakes: Intake[]): boolean {
+	if (person === "all") return medicationTakenBy.length > 0 || intakes.some((intake) => intake.takenBy !== null);
 	if (medicationTakenBy.includes(person)) return true;
 	return intakes.some((intake) => intake.takenBy === person);
 }

docker-compose.dev.yml

@@ -1,3 +1,5 @@
+name: medassist-dev
+
 services:
   backend-dev:
     image: node:22-slim
@@ -10,6 +12,7 @@ services:
     env_file:
       - .env
     environment:
+      - NODE_ENV=development
       - DATA_DIR=/app/data
       - RATE_LIMIT_MAX=1000
     ports:
@@ -33,6 +36,7 @@ services:
     env_file:
       - .env
     environment:
+      - NODE_ENV=development
       - BACKEND_URL=http://backend-dev:3000
     ports:
       - "5173:5173"

docker-compose.yml

@@ -1,3 +1,5 @@
+name: medassist-ng
+
 services:
   backend:
     image: ghcr.io/danielvolz/medassist-ng-backend:latest

docs/DEFAULT_USER_SETTINGS.md

@@ -0,0 +1,52 @@
+# Default User Settings
+
+This document lists all environment variables used as defaults for new users.
+
+Scope and behavior:
+
+- These values are applied only when a user's settings are created for the first time.
+- After that, values stored in the database are used and take precedence.
+- Source of truth in code: [backend/src/routes/settings.ts](backend/src/routes/settings.ts).
+
+## Email Defaults
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEFAULT_EMAIL_ENABLED` | `false` | Enable email notifications by default. |
+| `DEFAULT_NOTIFICATION_EMAIL` | empty | Default notification email address. |
+| `DEFAULT_EMAIL_STOCK_REMINDERS` | `true` | Send stock reminders via email. |
+| `DEFAULT_EMAIL_INTAKE_REMINDERS` | `true` | Send intake reminders via email. |
+| `DEFAULT_EMAIL_PRESCRIPTION_REMINDERS` | `true` | Send prescription reminders via email. |
+
+## Push Defaults (Shoutrrr)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEFAULT_SHOUTRRR_ENABLED` | `false` | Enable push notifications by default. |
+| `DEFAULT_SHOUTRRR_URL` | empty | Default Shoutrrr URL. |
+| `DEFAULT_SHOUTRRR_STOCK_REMINDERS` | `true` | Send stock reminders via push. |
+| `DEFAULT_SHOUTRRR_INTAKE_REMINDERS` | `true` | Send intake reminders via push. |
+| `DEFAULT_SHOUTRRR_PRESCRIPTION_REMINDERS` | `true` | Send prescription reminders via push. |
+
+## Reminder and Stock Defaults
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEFAULT_REPEAT_DAILY_REMINDERS` | `false` | Repeat stock reminders daily. |
+| `DEFAULT_SKIP_REMINDERS_FOR_TAKEN_DOSES` | `false` | Skip reminders for doses already marked as taken. |
+| `DEFAULT_REPEAT_REMINDERS_ENABLED` | `false` | Enable repeat reminders (nagging) for missed doses. |
+| `DEFAULT_REMINDER_REPEAT_INTERVAL_MINUTES` | `30` | Repeat interval for nagging reminders. |
+| `DEFAULT_MAX_NAGGING_REMINDERS` | `5` | Maximum number of repeat reminders per dose. |
+| `DEFAULT_LOW_STOCK_DAYS` | `30` | Low stock threshold in days. |
+| `DEFAULT_NORMAL_STOCK_DAYS` | `90` | Normal stock threshold in days. |
+| `DEFAULT_HIGH_STOCK_DAYS` | `180` | High stock threshold in days. |
+
+## UI Defaults
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DEFAULT_LANGUAGE` | `en` | Default language (`en` or `de`). |
+| `DEFAULT_STOCK_CALCULATION_MODE` | `automatic` | Default stock mode (`automatic` or `manual`). |
+| `DEFAULT_SHARE_STOCK_STATUS` | `true` | Show stock status on shared schedule links. |
+| `DEFAULT_UPCOMING_TODAY_ONLY` | `false` | Show only today's upcoming doses by default. |
+| `DEFAULT_SHARE_SCHEDULE_TODAY_ONLY` | `false` | Show only today's schedule in shared view by default. |

frontend/e2e/dashboard-data.spec.ts

@@ -117,6 +117,9 @@ test.describe("Dashboard with medications", () => {
 
 	test("should show day summary with dose progress", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
+		await expect(overviewTable).toBeVisible({ timeout: 10000 });
+		await expect(overviewTable.getByText(MED_1)).toBeVisible({ timeout: 10000 });
 
 		const todayBlock = page.locator(".day-block.today");
 		await expect(todayBlock).toBeVisible({ timeout: 10000 });

frontend/e2e/fixtures/index.ts

@@ -259,12 +259,14 @@ export async function createMedicationViaAPI(data: {
 	takenBy?: string[];
 	notes?: string;
 	expiryDate?: string;
-	packageType?: "blister" | "bottle";
+	packageType?: "blister" | "bottle" | "tube" | "liquid_container";
+	medicationForm?: "capsule" | "tablet" | "liquid" | "topical";
 	packCount?: number;
 	blistersPerPack?: number;
 	pillsPerBlister?: number;
 	looseTablets?: number;
 	totalPills?: number;
+	packageAmountValue?: number;
 	intakeRemindersEnabled?: boolean;
 	intakes?: {
 		usage: number;
@@ -275,15 +277,29 @@ export async function createMedicationViaAPI(data: {
 	}[];
 }): Promise<TestMedication> {
 	let token = getAuthCookie();
-	const isBottle = data.packageType === "bottle";
+	const packageType = data.packageType ?? "blister";
+	const isAmountBased = packageType === "bottle" || packageType === "tube" || packageType === "liquid_container";
+	let defaultMedicationForm: "capsule" | "tablet" | "liquid" | "topical" = "tablet";
+	if (packageType === "tube") {
+		defaultMedicationForm = "topical";
+	} else if (packageType === "liquid_container") {
+		defaultMedicationForm = "liquid";
+	}
+	const medicationForm = data.medicationForm ?? defaultMedicationForm;
+	const packageAmountValue =
+		data.packageAmountValue ??
+		(packageType === "tube" || packageType === "liquid_container" ? Math.max(1, data.totalPills ?? 30) : 0);
 	const body = {
-		packageType: isBottle ? "bottle" : "blister",
-		packCount: isBottle ? 1 : (data.packCount ?? 1),
-		blistersPerPack: isBottle ? 1 : (data.blistersPerPack ?? 1),
-		pillsPerBlister: isBottle ? 1 : (data.pillsPerBlister ?? 10),
-		// For bottles: looseTablets IS the current stock. Default to totalPills if not specified.
-		looseTablets: isBottle ? (data.looseTablets ?? data.totalPills ?? 0) : (data.looseTablets ?? 0),
-		totalPills: isBottle ? (data.totalPills ?? null) : null,
+		packageType,
+		medicationForm,
+		packCount: packageType === "tube" ? 1 : (data.packCount ?? 1),
+		blistersPerPack: isAmountBased ? 1 : (data.blistersPerPack ?? 1),
+		pillsPerBlister: isAmountBased ? 1 : (data.pillsPerBlister ?? 10),
+		// Amount-based packages use looseTablets as current stock.
+		looseTablets: isAmountBased ? (data.looseTablets ?? data.totalPills ?? 0) : (data.looseTablets ?? 0),
+		totalPills: isAmountBased ? (data.totalPills ?? null) : null,
+		packageAmountValue,
+		packageAmountUnit: packageType === "tube" ? "g" : "ml",
 		intakes: [
 			{
 				usage: 1,
@@ -411,6 +427,15 @@ export async function createShareTokenViaAPI(takenBy: string, scheduleDays = 30)
 			await new Promise((r) => setTimeout(r, 3000 * (attempt + 1)));
 			continue;
 		}
+		if (res.status === 400) {
+			const text = await res.text();
+			if (text.includes('"code":"NO_MEDICATIONS"') && attempt < 4) {
+				// Freshly seeded E2E medication data can lag briefly behind the share lookup.
+				await new Promise((r) => setTimeout(r, 1000 * (attempt + 1)));
+				continue;
+			}
+			throw new Error(`Failed to create share token: ${res.status} ${text}`);
+		}
 		if (!res.ok) {
 			const text = await res.text();
 			throw new Error(`Failed to create share token: ${res.status} ${text}`);

frontend/e2e/medication-crud.spec.ts

@@ -26,7 +26,7 @@ async function fillAndSaveMedication(
 	opts: {
 		name: string;
 		genericName?: string;
-		packageType?: "blister" | "bottle";
+		packageType?: "blister" | "bottle" | "tube" | "liquid_container";
 		packs?: string;
 		blistersPerPack?: string;
 		pillsPerBlister?: string;
@@ -56,6 +56,18 @@ async function fillAndSaveMedication(
 		if (opts.totalCapacity)
 			await form.getByLabel(/(Total Capacity|form\.totalCapacity|Total \(pills\))/i).fill(opts.totalCapacity);
 		if (opts.currentPills) await form.getByLabel(/(Current Pills|form\.currentPills)/i).fill(opts.currentPills);
+	} else if (opts.packageType === "tube") {
+		await packageTypeSelect.selectOption("tube");
+		await page.getByRole("tab", { name: /Package/i }).click();
+		if (opts.totalCapacity) {
+			await form.getByLabel(/(Amount per tube|form\.packageAmountPerTube)/i).fill(opts.totalCapacity);
+		}
+	} else if (opts.packageType === "liquid_container") {
+		await packageTypeSelect.selectOption("liquid_container");
+		await page.getByRole("tab", { name: /Package/i }).click();
+		if (opts.totalCapacity) {
+			await form.getByLabel(/(Package amount|form\.packageAmount)/i).fill(opts.totalCapacity);
+		}
 	} else {
 		await packageTypeSelect.selectOption("blister");
 		await page.getByRole("tab", { name: /Package/i }).click();
@@ -83,7 +95,11 @@ async function fillAndSaveMedication(
 			await form.getByRole("button", { name: /(Intake|form\.blisters\.addIntake)/i }).click();
 		}
 		const row = form.locator(".blister-row").nth(i);
-		await row.getByLabel(/(Usage \((pills|tablets)\)|form\.blisters\.usage)/i).fill(intakes[i].usage);
+		await row
+			.getByLabel(
+				/(Usage \((pills|tablets|capsules|ml|applications)\)|form\.blisters\.(usage|usageTablets|usageCapsules|usageMl|usageApplication))/i
+			)
+			.fill(intakes[i].usage);
 		await row.getByLabel(/(Every \(days\)|form\.blisters\.everyDays)/i).fill(intakes[i].every);
 	}
 
@@ -194,6 +210,26 @@ test.describe("Medication CRUD", () => {
 			});
 		});
 
+		test("should create a tube medication via the form", async ({ page }) => {
+			await navigateTo(page, "/medications");
+
+			await fillAndSaveMedication(page, {
+				name: "Test Tube Cream",
+				packageType: "tube",
+				totalCapacity: "50",
+			});
+		});
+
+		test("should create a liquid-container medication via the form", async ({ page }) => {
+			await navigateTo(page, "/medications");
+
+			await fillAndSaveMedication(page, {
+				name: "Test Liquid Syrup",
+				packageType: "liquid_container",
+				totalCapacity: "120",
+			});
+		});
+
 		test("should create medication with notes and expiry date", async ({ page }) => {
 			await navigateTo(page, "/medications");
 

frontend/e2e/medication-edit.spec.ts

@@ -329,7 +329,7 @@ test.describe("Medication Editing", () => {
 		}
 	});
 
-	test("should change package type between blister and bottle", async ({ page }) => {
+	test("should change package type across all supported profiles", async ({ page }) => {
 		createdMeds.push(
 			await createMedicationViaAPI({
 				name: "PackType Change Med",
@@ -357,15 +357,24 @@ test.describe("Medication Editing", () => {
 		await packageSelect.selectOption("bottle");
 		await page.getByRole("tab", { name: /Package/i }).click();
 		await expect(form.getByLabel(/(Total Capacity|form\.totalCapacity|Total \(pills\))/i)).toBeVisible();
+		await page.getByRole("tab", { name: /General/i }).click();
 
-		// Fill bottle-specific fields
-		await form.getByLabel(/(Total Capacity|form\.totalCapacity|Total \(pills\))/i).fill("120");
+		// Switch to tube
+		await packageSelect.selectOption("tube");
+		await page.getByRole("tab", { name: /Package/i }).click();
+		await expect(form.getByLabel(/(Amount per tube|form\.packageAmountPerTube)/i)).toBeVisible();
+		await page.getByRole("tab", { name: /General/i }).click();
+
+		// Switch to liquid container and persist this final state
+		await packageSelect.selectOption("liquid_container");
+		await page.getByRole("tab", { name: /Package/i }).click();
+		await expect(form.getByLabel(/(Package amount|form\.packageAmount)/i)).toBeVisible();
 
 		await saveEditAndVerify(page, "PackType Change Med");
 
-		// Verify it's still a bottle after reload
+		// Verify final package type persisted
 		await clickEditMed(page, "PackType Change Med");
-		await expect(page.locator("select.package-type-select")).toHaveValue("bottle");
+		await expect(page.locator("select.package-type-select")).toHaveValue("liquid_container");
 	});
 
 	test("should edit multiple fields at once (name, notes, generic, taken-by)", async ({ page }) => {

frontend/e2e/medications.spec.ts

@@ -87,25 +87,17 @@ test.describe("Medications Page", () => {
 		expect(hasPacks || hasTotal).toBeTruthy();
 	});
 
-	test("should toggle package type between blister and bottle", async ({ page }) => {
+	test("should expose all supported package type options", async ({ page }) => {
 		await openMedicationForm(page);
 		const form = visibleMedForm(page);
-		await page.getByRole("tab", { name: /Package/i }).click();
+		const packageSelect = form.locator("select.package-type-select");
+		await expect(packageSelect).toBeVisible();
 
-		// Find the package type radio buttons or selector
-		const blisterOption = form.getByText(/(Blister Pack|form\.packageType\.blister)/i);
-		const bottleOption = form.getByText(/(Pill Bottle|form\.packageType\.bottle)/i);
+		const optionValues = await packageSelect
+			.locator("option")
+			.evaluateAll((options) => options.map((option) => (option as HTMLOptionElement).value));
 
-		if (await blisterOption.isVisible().catch(() => false)) {
-			// Switch to bottle
-			await bottleOption.click();
-			// Bottle-specific fields should appear
-			await expect(form.getByLabel(/(Total Capacity|form\.totalCapacity)/i)).toBeVisible();
-
-			// Switch back to blister
-			await blisterOption.click();
-			await expect(form.getByLabel(/(Blisters per pack|form\.blistersPerPack)/i)).toBeVisible();
-		}
+		expect(optionValues).toEqual(expect.arrayContaining(["blister", "bottle", "tube", "liquid_container"]));
 	});
 
 	test("should have intake schedule with add button", async ({ page }) => {

frontend/e2e/schedule-data.spec.ts

@@ -195,8 +195,13 @@ test.describe("Schedule with medications", () => {
 		const takeBtn = todayBlock.locator("button.dose-btn.take:not([disabled])").first();
 		test.skip(!(await takeBtn.isVisible().catch(() => false)), "No actionable take-dose button is visible for today");
 
-		await takeBtn.click();
-		await page.waitForLoadState("networkidle");
+		await Promise.all([
+			page.waitForResponse(
+				(response) => response.url().includes("/api/doses/taken") && response.request().method() === "POST",
+				{ timeout: 10000 }
+			),
+			takeBtn.click(),
+		]);
 		await expect(todayBlock.locator("button.dose-btn.undo").first()).toBeVisible({ timeout: 10000 });
 	});
 
@@ -224,15 +229,4 @@ test.describe("Schedule with medications", () => {
 			expect(await takeButtons.count()).toBeGreaterThanOrEqual(1);
 		}
 	});
-
-	test("should show medication names in timeline rows", async ({ page }) => {
-		await navigateTo(page, "/dashboard");
-		await page.waitForLoadState("networkidle");
-
-		const todayBlock = page.locator(".day-block.today");
-		await expect(todayBlock).toBeVisible({ timeout: 15000 });
-
-		const medNames = todayBlock.locator(".med-name");
-		expect(await medNames.count()).toBeGreaterThanOrEqual(1);
-	});
 });

frontend/e2e/schedule.spec.ts

@@ -157,9 +157,13 @@ test.describe("Schedule Timeline", () => {
 
 	test("should display share button in schedules section", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
-		await expect(page.locator(".taken-by-badge").first()).toBeVisible();
-
 		const shareBtn = page.locator("button.share-btn");
+		const shareVisible = await shareBtn
+			.waitFor({ state: "visible", timeout: 10000 })
+			.then(() => true)
+			.catch(() => false);
+		test.skip(!shareVisible, "Share button is unavailable in this environment");
+
 		await expect(shareBtn).toBeVisible();
 	});
 });

frontend/e2e/settings.spec.ts

@@ -1,6 +1,9 @@
 import { expect } from "@playwright/test";
 import { authFile, navigateTo, test } from "./fixtures";
 
+const emailHeadingPattern = /Email|E-Mail/i;
+const smtpUnavailablePattern = /stay unavailable until SMTP is configured|bleiben deaktiviert, bis SMTP/i;
+
 /**
  * Settings Page E2E Tests
  *
@@ -53,6 +56,58 @@ test.describe("Settings Page", () => {
 		expect(await toggles.count()).toBeGreaterThanOrEqual(2);
 	});
 
+	test("should keep email controls disabled when settings request is forbidden", async ({ page }) => {
+		await page.route("**/api/settings", async (route) => {
+			if (route.request().method() !== "GET") {
+				await route.continue();
+				return;
+			}
+
+			await route.fulfill({
+				status: 403,
+				contentType: "application/json",
+				body: JSON.stringify({ error: "Forbidden", code: "FORBIDDEN" }),
+			});
+		});
+
+		await navigateTo(page, "/settings");
+
+		const emailSection = page
+			.locator(".setting-section")
+			.filter({ has: page.locator(".section-header h3").filter({ hasText: emailHeadingPattern }) })
+			.first();
+		const emailToggle = emailSection.locator('input[type="checkbox"]').first();
+
+		await expect(emailToggle).toBeDisabled();
+		await expect(emailSection.getByText(smtpUnavailablePattern)).toHaveCount(0);
+	});
+
+	test("should keep the email toggle enabled when the settings API returns smtp configuration", async ({ page }) => {
+		await navigateTo(page, "/settings");
+
+		const settingsResponse = await page.evaluate(async () => {
+			const response = await fetch("/api/settings", { credentials: "include" });
+			const body = await response.json().catch(() => null);
+			return {
+				ok: response.ok,
+				status: response.status,
+				body,
+			};
+		});
+
+		test.skip(!settingsResponse.ok, `Settings request failed with status ${settingsResponse.status}`);
+		test.skip(!settingsResponse.body?.smtpHost, "SMTP is not configured in this environment");
+
+		const emailSection = page
+			.locator(".setting-section")
+			.filter({ has: page.locator(".section-header h3").filter({ hasText: emailHeadingPattern }) })
+			.first();
+		const emailToggle = emailSection.locator('input[type="checkbox"]').first();
+
+		await expect(emailToggle).toBeEnabled();
+		await expect(emailSection.getByText(smtpUnavailablePattern)).toHaveCount(0);
+	});
+
 	test("should show stock settings section with threshold inputs", async ({ page }) => {
 		await navigateTo(page, "/settings");
 
@@ -104,6 +159,28 @@ test.describe("Settings Page", () => {
 		await expect(exportButton).toBeVisible();
 	});
 
+	test("should generate a new API key from the settings page", async ({ page }) => {
+		await navigateTo(page, "/settings");
+
+		const generateButton = page.getByRole("button", { name: /Generate key|Key erzeugen/i });
+		test.skip(
+			!(await generateButton.isVisible().catch(() => false)),
+			"API key action is unavailable in this environment"
+		);
+
+		await generateButton.click();
+
+		const tokenInput = page.locator(".api-key-token-input");
+		const tokenVisible = await tokenInput
+			.waitFor({ state: "visible", timeout: 5000 })
+			.then(() => true)
+			.catch(() => false);
+		test.skip(!tokenVisible, "API key token UI is unavailable in this environment");
+
+		await expect(tokenInput).toBeVisible();
+		await expect(tokenInput).toHaveValue(/^ma_/);
+	});
+
 	test("should show export/import section", async ({ page }) => {
 		await navigateTo(page, "/settings");
 

frontend/e2e/share-schedule.spec.ts

@@ -96,6 +96,10 @@ test.describe("Share Schedule", () => {
 
 	test("should open share dialog with person list", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
+		await expect(overviewTable).toBeVisible({ timeout: 10000 });
+		await expect(overviewTable.getByText(MED_ALICE)).toBeVisible({ timeout: 10000 });
+		await expect(overviewTable.getByText(MED_BOB)).toBeVisible({ timeout: 10000 });
 
 		// Click the share button
 		const shareBtn = page.locator("button.share-btn");
@@ -136,7 +140,7 @@ test.describe("Share Schedule", () => {
 		await generateBtn.click();
 
 		// Wait for link to be generated
-		const shareLinkInput = modal.locator("input.share-link-input");
+		const shareLinkInput = modal.locator("input.share-link-input").first();
 		await expect(shareLinkInput).toBeVisible({ timeout: 10000 });
 
 		// The share link should contain /share/
@@ -144,7 +148,7 @@ test.describe("Share Schedule", () => {
 		expect(linkValue).toContain("/share/");
 
 		// Copy button should be visible
-		await expect(modal.locator("button.btn-copy")).toBeVisible();
+		await expect(modal.locator("button.btn-copy").first()).toBeVisible();
 
 		// Close
 		await page.locator("button.modal-close").click();
@@ -178,18 +182,19 @@ test.describe("Share Schedule", () => {
 
 		await page.goto(`/share/${shareToken.token}`);
 		await page.waitForLoadState("networkidle");
-
-		// Wait for page content to load
-		await page.waitForTimeout(2000);
+		await expect(page.locator(".shared-schedule-loading-skeleton")).toBeHidden({ timeout: 10000 });
+		const sharedSchedule = page.locator(".shared-schedule-container");
+		await expect(sharedSchedule).toBeVisible({ timeout: 10000 });
 
 		// The page should show Alice's medication name
-		const content = page.getByText(MED_ALICE);
+		const content = sharedSchedule.getByText(MED_ALICE);
 		try {
 			await expect(content).toBeVisible({ timeout: 10000 });
 		} catch {
 			// Reload and retry — sometimes the initial load misses
 			await page.reload();
 			await page.waitForLoadState("networkidle");
+			await expect(page.locator(".shared-schedule-loading-skeleton")).toBeHidden({ timeout: 10000 });
 			await expect(content).toBeVisible({ timeout: 10000 });
 		}
 	});
@@ -226,27 +231,32 @@ test.describe("Share Schedule", () => {
 		// Visit Alice's share — should show Alice's med
 		await page.goto(`/share/${aliceToken.token}`);
 		await page.waitForLoadState("networkidle");
-		await page.waitForTimeout(2000);
+		await expect(page.locator(".shared-schedule-loading-skeleton")).toBeHidden({ timeout: 10000 });
+		const sharedSchedule = page.locator(".shared-schedule-container");
+		await expect(sharedSchedule).toBeVisible({ timeout: 10000 });
 
 		try {
-			await expect(page.getByText(MED_ALICE)).toBeVisible({ timeout: 10000 });
+			await expect(sharedSchedule.getByText(MED_ALICE)).toBeVisible({ timeout: 10000 });
 		} catch {
 			await page.reload();
 			await page.waitForLoadState("networkidle");
-			await expect(page.getByText(MED_ALICE)).toBeVisible({ timeout: 10000 });
+			await expect(page.locator(".shared-schedule-loading-skeleton")).toBeHidden({ timeout: 10000 });
+			await expect(sharedSchedule.getByText(MED_ALICE)).toBeVisible({ timeout: 10000 });
 		}
 
 		// Visit Bob's share — should show Bob's med
 		await page.goto(`/share/${bobToken.token}`);
 		await page.waitForLoadState("networkidle");
-		await page.waitForTimeout(2000);
+		await expect(page.locator(".shared-schedule-loading-skeleton")).toBeHidden({ timeout: 10000 });
+		await expect(sharedSchedule).toBeVisible({ timeout: 10000 });
 
 		try {
-			await expect(page.getByText(MED_BOB)).toBeVisible({ timeout: 10000 });
+			await expect(sharedSchedule.getByText(MED_BOB)).toBeVisible({ timeout: 10000 });
 		} catch {
 			await page.reload();
 			await page.waitForLoadState("networkidle");
-			await expect(page.getByText(MED_BOB)).toBeVisible({ timeout: 10000 });
+			await expect(page.locator(".shared-schedule-loading-skeleton")).toBeHidden({ timeout: 10000 });
+			await expect(sharedSchedule.getByText(MED_BOB)).toBeVisible({ timeout: 10000 });
 		}
 	});
 

frontend/e2e/stock-status.spec.ts

@@ -141,6 +141,7 @@ test.describe("Stock Status Levels", () => {
 
 		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
+		await expect(overviewTable.getByText(MED_HIGH)).toBeVisible({ timeout: 10000 });
 
 		// High stock med row should have a .status-chip.high
 		const highRow = overviewTable.locator(".table-row").filter({ hasText: MED_HIGH });
@@ -192,6 +193,37 @@ test.describe("Stock Status Levels", () => {
 		await expect(depletedRow.locator(".status-chip.danger")).toBeVisible();
 	});
 
+	test("should keep the depleted take button visually dangerous while disabled", async ({ page }) => {
+		await navigateTo(page, "/dashboard");
+
+		const todayBlock = page.locator(".day-block.today");
+		await expect(todayBlock).toBeVisible({ timeout: 10000 });
+
+		const depletedRow = todayBlock.locator(".time-row").filter({ hasText: MED_DEPLETED });
+		await expect(depletedRow).toBeVisible();
+
+		const takeButton = depletedRow.locator("button.dose-btn.take.out-of-stock");
+		await expect(takeButton).toBeDisabled();
+
+		const expectedDangerStyles = await page.evaluate(() => {
+			const probe = document.createElement("button");
+			probe.style.backgroundColor = "var(--danger)";
+			probe.style.borderColor = "var(--danger)";
+			document.body.appendChild(probe);
+			const styles = getComputedStyle(probe);
+			const result = {
+				backgroundColor: styles.backgroundColor,
+				borderTopColor: styles.borderTopColor,
+			};
+			probe.remove();
+			return result;
+		});
+
+		await expect(takeButton).toHaveCSS("opacity", "1");
+		await expect(takeButton).toHaveCSS("background-color", expectedDangerStyles.backgroundColor);
+		await expect(takeButton).toHaveCSS("border-top-color", expectedDangerStyles.borderTopColor);
+	});
+
 	test("should show days-left and runs-out date in overview", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
@@ -199,15 +231,17 @@ test.describe("Stock Status Levels", () => {
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		// High stock should show many days (around 299)
+		await expect(overviewTable.getByText(MED_HIGH)).toBeVisible({ timeout: 10000 });
 		const highRow = overviewTable.locator(".table-row").filter({ hasText: MED_HIGH });
-		const highRowText = await highRow.textContent();
+		const highRowText = (await highRow.textContent()) ?? "";
 		// Should contain a 3-digit number for days
 		expect(highRowText).toMatch(/\d{2,3}/);
 
-		// Depleted should show 0 or very low number
+		// Depleted rows can now show either explicit zero days left or an em dash placeholder.
+		await expect(overviewTable.getByText(MED_DEPLETED)).toBeVisible({ timeout: 10000 });
 		const depletedRow = overviewTable.locator(".table-row").filter({ hasText: MED_DEPLETED });
-		const depletedText = await depletedRow.textContent();
-		expect(depletedText).toContain("0");
+		const depletedText = (await depletedRow.textContent()) ?? "";
+		expect(depletedText.includes("0") || depletedText.includes("—")).toBeTruthy();
 	});
 
 	test("should show reorder reminder card with low-stock medications", async ({ page }) => {

frontend/nginx.conf

@@ -23,6 +23,49 @@ server {
     # Allow larger file uploads (for medication images and data import/export)
     client_max_body_size 50M;
 
+    # -------------------------------------------------------------------------
+    # Swagger/OpenAPI docs (optional)
+    # When backend docs are enabled, expose them through the frontend ingress so
+    # no separate backend port is required for /docs access.
+    #
+    # Important: do not inherit the app-shell CSP here. Swagger UI ships its own
+    # CSP headers from Fastify and would otherwise be blocked by the stricter
+    # frontend policy.
+    # -------------------------------------------------------------------------
+    location = /docs {
+        resolver 127.0.0.11 valid=10s ipv6=off;
+        set $backend_upstream ${BACKEND_URL};
+
+        proxy_pass http://$backend_upstream;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_pass_header Set-Cookie;
+        proxy_cookie_path / /;
+
+        # Defining a location-level header prevents inheritance of the stricter
+        # frontend app-shell headers while leaving backend Swagger headers intact.
+        add_header X-Docs-Proxy "1" always;
+    }
+
+    location ^~ /docs/ {
+        resolver 127.0.0.11 valid=10s ipv6=off;
+        set $backend_upstream ${BACKEND_URL};
+
+        proxy_pass http://$backend_upstream;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_pass_header Set-Cookie;
+        proxy_cookie_path / /;
+
+        # Defining a location-level header prevents inheritance of the stricter
+        # frontend app-shell headers while leaving backend Swagger headers intact.
+        add_header X-Docs-Proxy "1" always;
+    }
+
     location / {
         try_files $uri /index.html;
     }

frontend/package-lock.json

@@ -1,29 +1,29 @@
 {
   "name": "medassist-ng-frontend",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "medassist-ng-frontend",
-      "version": "1.18.1",
+      "version": "1.19.0",
       "dependencies": {
-        "i18next": "^25.8.13",
+        "i18next": "^25.8.14",
         "i18next-browser-languagedetector": "^8.2.1",
-        "lucide-react": "^0.575.0",
+        "lucide-react": "^0.577.0",
         "react": "^19.2.4",
         "react-dom": "^19.2.4",
-        "react-i18next": "^15.4.1",
+        "react-i18next": "^16.5.6",
         "react-router-dom": "^7.13.1",
         "zod": "^4.3.6"
       },
       "devDependencies": {
-        "@biomejs/biome": "^2.4.4",
+        "@biomejs/biome": "^2.4.6",
         "@playwright/test": "^1.58.2",
         "@testing-library/jest-dom": "^6.9.1",
         "@testing-library/react": "^16.3.2",
         "@testing-library/user-event": "^14.6.1",
-        "@types/node": "^25.3.3",
+        "@types/node": "^25.3.5",
         "@types/react": "^19.2.14",
         "@types/react-dom": "^19.2.3",
         "@types/react-router-dom": "^5.3.3",
@@ -406,9 +406,9 @@
       }
     },
     "node_modules/@biomejs/biome": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.4.4.tgz",
-      "integrity": "sha512-tigwWS5KfJf0cABVd52NVaXyAVv4qpUXOWJ1rxFL8xF1RVoeS2q/LK+FHgYoKMclJCuRoCWAPy1IXaN9/mS61Q==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.4.6.tgz",
+      "integrity": "sha512-QnHe81PMslpy3mnpL8DnO2M4S4ZnYPkjlGCLWBZT/3R9M6b5daArWMMtEfP52/n174RKnwRIf3oT8+wc9ihSfQ==",
       "dev": true,
       "license": "MIT OR Apache-2.0",
       "bin": {
@@ -422,20 +422,20 @@
         "url": "https://opencollective.com/biome"
       },
       "optionalDependencies": {
-        "@biomejs/cli-darwin-arm64": "2.4.4",
-        "@biomejs/cli-darwin-x64": "2.4.4",
-        "@biomejs/cli-linux-arm64": "2.4.4",
-        "@biomejs/cli-linux-arm64-musl": "2.4.4",
-        "@biomejs/cli-linux-x64": "2.4.4",
-        "@biomejs/cli-linux-x64-musl": "2.4.4",
-        "@biomejs/cli-win32-arm64": "2.4.4",
-        "@biomejs/cli-win32-x64": "2.4.4"
+        "@biomejs/cli-darwin-arm64": "2.4.6",
+        "@biomejs/cli-darwin-x64": "2.4.6",
+        "@biomejs/cli-linux-arm64": "2.4.6",
+        "@biomejs/cli-linux-arm64-musl": "2.4.6",
+        "@biomejs/cli-linux-x64": "2.4.6",
+        "@biomejs/cli-linux-x64-musl": "2.4.6",
+        "@biomejs/cli-win32-arm64": "2.4.6",
+        "@biomejs/cli-win32-x64": "2.4.6"
       }
     },
     "node_modules/@biomejs/cli-darwin-arm64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.4.tgz",
-      "integrity": "sha512-jZ+Xc6qvD6tTH5jM6eKX44dcbyNqJHssfl2nnwT6vma6B1sj7ZLTGIk6N5QwVBs5xGN52r3trk5fgd3sQ9We9A==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.4.6.tgz",
+      "integrity": "sha512-NW18GSyxr+8sJIqgoGwVp5Zqm4SALH4b4gftIA0n62PTuBs6G2tHlwNAOj0Vq0KKSs7Sf88VjjmHh0O36EnzrQ==",
       "cpu": [
         "arm64"
       ],
@@ -450,9 +450,9 @@
       }
     },
     "node_modules/@biomejs/cli-darwin-x64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.4.4.tgz",
-      "integrity": "sha512-Dh1a/+W+SUCXhEdL7TiX3ArPTFCQKJTI1mGncZNWfO+6suk+gYA4lNyJcBB+pwvF49uw0pEbUS49BgYOY4hzUg==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.4.6.tgz",
+      "integrity": "sha512-4uiE/9tuI7cnjtY9b07RgS7gGyYOAfIAGeVJWEfeCnAarOAS7qVmuRyX6d7JTKw28/mt+rUzMasYeZ+0R/U1Mw==",
       "cpu": [
         "x64"
       ],
@@ -467,9 +467,9 @@
       }
     },
     "node_modules/@biomejs/cli-linux-arm64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.4.4.tgz",
-      "integrity": "sha512-V/NFfbWhsUU6w+m5WYbBenlEAz8eYnSqRMDMAW3K+3v0tYVkNyZn8VU0XPxk/lOqNXLSCCrV7FmV/u3SjCBShg==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.4.6.tgz",
+      "integrity": "sha512-kMLaI7OF5GN1Q8Doymjro1P8rVEoy7BKQALNz6fiR8IC1WKduoNyteBtJlHT7ASIL0Cx2jR6VUOBIbcB1B8pew==",
       "cpu": [
         "arm64"
       ],
@@ -484,9 +484,9 @@
       }
     },
     "node_modules/@biomejs/cli-linux-arm64-musl": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.4.4.tgz",
-      "integrity": "sha512-+sPAXq3bxmFwhVFJnSwkSF5Rw2ZAJMH3MF6C9IveAEOdSpgajPhoQhbbAK12SehN9j2QrHpk4J/cHsa/HqWaYQ==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.4.6.tgz",
+      "integrity": "sha512-F/JdB7eN22txiTqHM5KhIVt0jVkzZwVYrdTR1O3Y4auBOQcXxHK4dxULf4z43QyZI5tsnQJrRBHZy7wwtL+B3A==",
       "cpu": [
         "arm64"
       ],
@@ -501,9 +501,9 @@
       }
     },
     "node_modules/@biomejs/cli-linux-x64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.4.4.tgz",
-      "integrity": "sha512-R4+ZCDtG9kHArasyBO+UBD6jr/FcFCTH8QkNTOCu0pRJzCWyWC4EtZa2AmUZB5h3e0jD7bRV2KvrENcf8rndBg==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.4.6.tgz",
+      "integrity": "sha512-oHXmUFEoH8Lql1xfc3QkFLiC1hGR7qedv5eKNlC185or+o4/4HiaU7vYODAH3peRCfsuLr1g6v2fK9dFFOYdyw==",
       "cpu": [
         "x64"
       ],
@@ -518,9 +518,9 @@
       }
     },
     "node_modules/@biomejs/cli-linux-x64-musl": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.4.4.tgz",
-      "integrity": "sha512-gGvFTGpOIQDb5CQ2VC0n9Z2UEqlP46c4aNgHmAMytYieTGEcfqhfCFnhs6xjt0S3igE6q5GLuIXtdQt3Izok+g==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.4.6.tgz",
+      "integrity": "sha512-C9s98IPDu7DYarjlZNuzJKTjVHN03RUnmHV5htvqsx6vEUXCDSJ59DNwjKVD5XYoSS4N+BYhq3RTBAL8X6svEg==",
       "cpu": [
         "x64"
       ],
@@ -535,9 +535,9 @@
       }
     },
     "node_modules/@biomejs/cli-win32-arm64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.4.4.tgz",
-      "integrity": "sha512-trzCqM7x+Gn832zZHgr28JoYagQNX4CZkUZhMUac2YxvvyDRLJDrb5m9IA7CaZLlX6lTQmADVfLEKP1et1Ma4Q==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.4.6.tgz",
+      "integrity": "sha512-xzThn87Pf3YrOGTEODFGONmqXpTwUNxovQb72iaUOdcw8sBSY3+3WD8Hm9IhMYLnPi0n32s3L3NWU6+eSjfqFg==",
       "cpu": [
         "arm64"
       ],
@@ -552,9 +552,9 @@
       }
     },
     "node_modules/@biomejs/cli-win32-x64": {
-      "version": "2.4.4",
-      "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.4.tgz",
-      "integrity": "sha512-gnOHKVPFAAPrpoPt2t+Q6FZ7RPry/FDV3GcpU53P3PtLNnQjBmKyN2Vh/JtqXet+H4pme8CC76rScwdjDcT1/A==",
+      "version": "2.4.6",
+      "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.4.6.tgz",
+      "integrity": "sha512-7++XhnsPlr1HDbor5amovPjOH6vsrFOCdp93iKXhFn6bcMUI6soodj3WWKfgEO6JosKU1W5n3uky3WW9RlRjTg==",
       "cpu": [
         "x64"
       ],
@@ -1779,9 +1779,9 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "25.3.3",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.3.3.tgz",
-      "integrity": "sha512-DpzbrH7wIcBaJibpKo9nnSQL0MTRdnWttGyE5haGwK86xgMOkFLp7vEyfQPGLOJh5wNYiJ3V9PmUMDhV9u8kkQ==",
+      "version": "25.3.5",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.3.5.tgz",
+      "integrity": "sha512-oX8xrhvpiyRCQkG1MFchB09f+cXftgIXb3a7UUa4Y3wpmZPw5tyZGTLWhlESOLq1Rq6oDlc8npVU2/9xiCuXMA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -2494,9 +2494,9 @@
       }
     },
     "node_modules/i18next": {
-      "version": "25.8.13",
-      "resolved": "https://registry.npmjs.org/i18next/-/i18next-25.8.13.tgz",
-      "integrity": "sha512-E0vzjBY1yM+nsFrtgkjLhST2NBkirkvOVoQa0MSldhsuZ3jUge7ZNpuwG0Cfc74zwo5ZwRzg3uOgT+McBn32iA==",
+      "version": "25.8.14",
+      "resolved": "https://registry.npmjs.org/i18next/-/i18next-25.8.14.tgz",
+      "integrity": "sha512-paMUYkfWJMsWPeE/Hejcw+XLhHrQPehem+4wMo+uELnvIwvCG019L9sAIljwjCmEMtFQQO3YeitJY8Kctei3iA==",
       "funding": [
         {
           "type": "individual",
@@ -2685,9 +2685,9 @@
       }
     },
     "node_modules/lucide-react": {
-      "version": "0.575.0",
-      "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-0.575.0.tgz",
-      "integrity": "sha512-VuXgKZrk0uiDlWjGGXmKV6MSk9Yy4l10qgVvzGn2AWBx1Ylt0iBexKOAoA6I7JO3m+M9oeovJd3yYENfkUbOeg==",
+      "version": "0.577.0",
+      "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-0.577.0.tgz",
+      "integrity": "sha512-4LjoFv2eEPwYDPg/CUdBJQSDfPyzXCRrVW1X7jrx/trgxnxkHFjnVZINbzvzxjN70dxychOfg+FTYwBiS3pQ5A==",
       "license": "ISC",
       "peerDependencies": {
         "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
@@ -2980,16 +2980,17 @@
       }
     },
     "node_modules/react-i18next": {
-      "version": "15.7.4",
-      "resolved": "https://registry.npmjs.org/react-i18next/-/react-i18next-15.7.4.tgz",
-      "integrity": "sha512-nyU8iKNrI5uDJch0z9+Y5XEr34b0wkyYj3Rp+tfbahxtlswxSCjcUL9H0nqXo9IR3/t5Y5PKIA3fx3MfUyR9Xw==",
+      "version": "16.5.6",
+      "resolved": "https://registry.npmjs.org/react-i18next/-/react-i18next-16.5.6.tgz",
+      "integrity": "sha512-Ua7V2/efA88ido7KyK51fb8Ki8M/sRfW8LR/rZ/9ZKr2luhuTI7kwYZN5agT1rWG7aYm5G0RYE/6JR8KJoCMDw==",
       "license": "MIT",
       "dependencies": {
-        "@babel/runtime": "^7.27.6",
-        "html-parse-stringify": "^3.0.1"
+        "@babel/runtime": "^7.28.4",
+        "html-parse-stringify": "^3.0.1",
+        "use-sync-external-store": "^1.6.0"
       },
       "peerDependencies": {
-        "i18next": ">= 23.4.0",
+        "i18next": ">= 25.6.2",
         "react": ">= 16.8.0",
         "typescript": "^5"
       },
@@ -3337,9 +3338,9 @@
       }
     },
     "node_modules/undici": {
-      "version": "7.21.0",
-      "resolved": "https://registry.npmjs.org/undici/-/undici-7.21.0.tgz",
-      "integrity": "sha512-Hn2tCQpoDt1wv23a68Ctc8Cr/BHpUSfaPYrkajTXOS9IKpxVRx/X5m1K2YkbK2ipgZgxXSgsUinl3x+2YdSSfg==",
+      "version": "7.24.1",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-7.24.1.tgz",
+      "integrity": "sha512-5xoBibbmnjlcR3jdqtY2Lnx7WbrD/tHlT01TmvqZUFVc9Q1w4+j5hbnapTqbcXITMH1ovjq/W7BkqBilHiVAaA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -3384,6 +3385,15 @@
         "browserslist": ">= 4.21.0"
       }
     },
+    "node_modules/use-sync-external-store": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz",
+      "integrity": "sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/vite": {
       "version": "7.3.1",
       "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.1.tgz",

frontend/package.json

@@ -1,7 +1,7 @@
 {
   "name": "medassist-ng-frontend",
   "private": true,
-  "version": "1.18.2",
+  "version": "1.20.0",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -27,22 +27,22 @@
     "test:e2e:report": "playwright show-report"
   },
   "dependencies": {
-    "i18next": "^25.8.13",
+    "i18next": "^25.8.14",
     "i18next-browser-languagedetector": "^8.2.1",
-    "lucide-react": "^0.575.0",
+    "lucide-react": "^0.577.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
-    "react-i18next": "^15.4.1",
+    "react-i18next": "^16.5.6",
     "react-router-dom": "^7.13.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
+    "@biomejs/biome": "^2.4.6",
     "@playwright/test": "^1.58.2",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^25.3.3",
+    "@types/node": "^25.3.5",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@types/react-router-dom": "^5.3.3",

frontend/src/App.tsx

@@ -13,7 +13,7 @@ import { AppHeader } from "./components/AppHeader";
 import { AuthPage, AuthProvider, useAuth } from "./components/Auth";
 import { AppProvider, UnsavedChangesProvider, useAppContext } from "./context";
 import { useScrollLock } from "./hooks/useScrollLock";
-import { DashboardPage, MedicationsPage, PlannerPage, SchedulePage, SettingsPage } from "./pages";
+import { DashboardPage, MedicationsPage, PlannerPage, SchedulePage, SettingsPage, SharedOverviewPage } from "./pages";
 
 // Vite injects this at build time from package.json
 declare const __APP_VERSION__: string;
@@ -29,6 +29,7 @@ export default function App() {
 		<AuthProvider>
 			<Routes>
 				{/* Public share route - accessible without auth */}
+				<Route path="/share/:token/overview" element={<SharedOverviewPage />} />
 				<Route path="/share/:token" element={<SharedSchedule />} />
 				{/* All other routes go through AppRouter */}
 				<Route path="*" element={<AppRouter />} />

frontend/src/components/MedDetailModal.tsx

@@ -15,7 +15,15 @@ import { useTranslation } from "react-i18next";
 import { Lightbox, MedicationAvatar } from "../components";
 import { useEscapeKey } from "../hooks";
 import type { Coverage, Medication, RefillEntry, StockThresholds } from "../types";
-import { getMedDisplayName, getMedTotal, getPackageSize } from "../types";
+import {
+	allowsPillFormSelection,
+	getMedDisplayName,
+	getMedTotal,
+	getPackageSize,
+	isAmountBasedPackageType,
+	isLiquidContainerPackageType,
+	isTubePackageType,
+} from "../types";
 import { formatNumber, generateICS, getExpiryClass, getSystemLocale } from "../utils";
 import { getStockStatus } from "../utils/schedule";
 import { splitCurrentBlisterStock } from "../utils/stock";
@@ -170,7 +178,7 @@ export function MedDetailModal({
 	}, [showEditStockModal]);
 
 	const remainingPrescriptionRefills = Math.max(0, Number(selectedMed?.prescriptionRemainingRefills) || 0);
-	const prescriptionPackCapEnabled = selectedMed?.packageType === "blister" && usePrescriptionRefill;
+	const prescriptionPackCapEnabled = !isAmountBasedPackageType(selectedMed?.packageType) && usePrescriptionRefill;
 	const cappedRefillPacks = prescriptionPackCapEnabled
 		? Math.min(refillPacks, remainingPrescriptionRefills)
 		: refillPacks;
@@ -179,7 +187,7 @@ export function MedDetailModal({
 	useEffect(() => {
 		if (!selectedMed) return;
 		if (!showRefillModal) return;
-		if (selectedMed.packageType !== "blister" || !usePrescriptionRefill) return;
+		if (isAmountBasedPackageType(selectedMed.packageType) || !usePrescriptionRefill) return;
 		if (refillPacks <= remainingPrescriptionRefills) return;
 		onRefillPacksChange(remainingPrescriptionRefills);
 	}, [
@@ -192,9 +200,10 @@ export function MedDetailModal({
 	]);
 
 	if (!selectedMed) return null;
-	const isAmountPackage = selectedMed.packageType === "tube" || selectedMed.packageType === "liquid_container";
+	const isAmountPackage =
+		isTubePackageType(selectedMed.packageType) || isLiquidContainerPackageType(selectedMed.packageType);
 	const amountUnitLabel =
-		selectedMed.packageType === "liquid_container" || selectedMed.medicationForm === "liquid"
+		isLiquidContainerPackageType(selectedMed.packageType) || selectedMed.medicationForm === "liquid"
 			? t("form.packageAmountUnitMl")
 			: t("form.packageAmountUnitG");
 	const stockUnitLabel = isAmountPackage ? amountUnitLabel : null;
@@ -202,12 +211,9 @@ export function MedDetailModal({
 	const medCoverage = coverage.all.find((c) => c.name === getMedDisplayName(selectedMed));
 	const packageSize = getPackageSize(selectedMed);
 	// Structural max = sealed package capacity only (excludes pre-existing looseTablets).
-	const structuralMax =
-		selectedMed.packageType === "bottle" ||
-		selectedMed.packageType === "tube" ||
-		selectedMed.packageType === "liquid_container"
-			? (selectedMed.totalPills ?? packageSize)
-			: selectedMed.packCount * selectedMed.blistersPerPack * selectedMed.pillsPerBlister;
+	const structuralMax = isAmountBasedPackageType(selectedMed.packageType)
+		? (selectedMed.totalPills ?? packageSize)
+		: selectedMed.packCount * selectedMed.blistersPerPack * selectedMed.pillsPerBlister;
 	const currentStock = medCoverage ? Math.round(medCoverage.medsLeft) : getMedTotal(selectedMed);
 	const status = medCoverage ? getStockStatus(medCoverage.daysLeft, medCoverage.medsLeft, settings) : null;
 	const fallbackTextClass = status?.className === "warning" ? "warning-text" : "success-text";
@@ -216,12 +222,9 @@ export function MedDetailModal({
 	const currentFullBlisters = Math.max(0, stock.fullBlisters);
 	const currentPartialPills = Math.max(0, stock.openBlisterPills);
 	const currentLoosePills = Math.max(0, stock.loosePills);
-	const stockDisplayTotal =
-		selectedMed.packageType === "bottle" ||
-		selectedMed.packageType === "tube" ||
-		selectedMed.packageType === "liquid_container"
-			? (selectedMed.totalPills ?? packageSize)
-			: Math.max(0, structuralMax);
+	const stockDisplayTotal = isAmountBasedPackageType(selectedMed.packageType)
+		? (selectedMed.totalPills ?? packageSize)
+		: Math.max(0, structuralMax);
 	const packageCount = Math.max(1, Number(selectedMed.packCount) || 1);
 	const amountPerPackage = (() => {
 		const configured = Number(selectedMed.packageAmountValue ?? 0);
@@ -243,8 +246,16 @@ export function MedDetailModal({
 	const closeLabel = t("common.close");
 	const decrementLabel = t("editStock.decreaseValue");
 	const incrementLabel = t("editStock.increaseValue");
+	const showPillWeightDetails = allowsPillFormSelection(selectedMed.packageType) && !!selectedMed.pillWeightMg;
+	const pillWeightMg = showPillWeightDetails ? (selectedMed.pillWeightMg ?? 0) : 0;
+	const isTubeRefillPackage = isTubePackageType(selectedMed.packageType);
+	const isLiquidRefillPackage =
+		isLiquidContainerPackageType(selectedMed.packageType) || selectedMed.medicationForm === "liquid";
+	const isCountBasedAmountRefillPackage = isLiquidRefillPackage || isTubeRefillPackage;
+	const liquidRefillAmountPerBottle = Math.max(1, Math.round(Number.isFinite(amountPerPackage) ? amountPerPackage : 1));
+	const amountRefillPackageCount = Math.max(0, Math.round(refillLoose / liquidRefillAmountPerBottle));
 	const getScheduleUsageLabel = (usage: number, intakeUnit?: "ml" | "tsp" | "tbsp" | null) => {
-		if (selectedMed.packageType === "liquid_container") {
+		if (isLiquidContainerPackageType(selectedMed.packageType)) {
 			if (intakeUnit === "tsp") {
 				return `${usage} ${t("form.blisters.teaspoons", { count: Math.abs(usage) })}`;
 			}
@@ -253,7 +264,7 @@ export function MedDetailModal({
 			}
 			return `${usage} ${t("form.packageAmountUnitMl")}`;
 		}
-		if (selectedMed.packageType === "tube") {
+		if (isTubePackageType(selectedMed.packageType)) {
 			return `${usage} ${t("form.blisters.applications", { count: Math.abs(usage) })}`;
 		}
 		return `${usage} ${usage !== 1 ? t("common.pills") : t("common.pill")}`;
@@ -266,12 +277,10 @@ export function MedDetailModal({
 					every: blister.every,
 					start: blister.start,
 					takenBy: null,
-					intakeRemindersEnabled: selectedMed.intakeRemindersEnabled ?? false,
+					intakeRemindersEnabled: false,
 					intakeUnit: null,
 				}));
-	const hasAnyIntakeReminder = scheduleIntakes.some(
-		(intake) => (intake.intakeRemindersEnabled ?? selectedMed.intakeRemindersEnabled ?? false) === true
-	);
+	const hasAnyIntakeReminder = scheduleIntakes.some((intake) => intake.intakeRemindersEnabled === true);
 	const normalizeBlisterStock = (nextFull: number, nextPartial: number, nextLoose: number) => {
 		let normalizedFull = Math.max(0, nextFull);
 		let normalizedPartial = Math.max(0, nextPartial);
@@ -400,7 +409,7 @@ export function MedDetailModal({
 
 	const renderEditStockModal = () => {
 		if (!showEditStockModal) return null;
-		const isLiquidPackage = selectedMed.packageType === "liquid_container";
+		const isLiquidPackage = isLiquidContainerPackageType(selectedMed.packageType);
 		const liquidBottleCount = Math.max(1, editStockFullBlisters);
 		const liquidAmountPerBottle = Math.max(1, Number.isFinite(amountPerPackage) ? amountPerPackage : 1);
 		const liquidCapacity = Math.max(1, Math.round(liquidBottleCount * liquidAmountPerBottle));
@@ -439,7 +448,7 @@ export function MedDetailModal({
 					<h2>{t("editStock.title")}</h2>
 					<p className="edit-stock-med-name">{getMedDisplayName(selectedMed)}</p>
 					<p className="edit-stock-hint">{t("editStock.hint")}</p>
-					{selectedMed.packageType === "blister" && (
+					{!isAmountBasedPackageType(selectedMed.packageType) && (
 						<p className="edit-stock-cap-info edit-stock-live-breakdown">
 							{t("editStock.currentComposition", {
 								fullBlisters: currentFullBlisters,
@@ -449,10 +458,10 @@ export function MedDetailModal({
 							})}
 						</p>
 					)}
-					{selectedMed.packageType === "bottle" && (
+					{isAmountBasedPackageType(selectedMed.packageType) && !isTubePackageType(selectedMed.packageType) && (
 						<p className="edit-stock-cap-info">{t("editStock.packageSize", { count: structuralMax })}</p>
 					)}
-					{(selectedMed.packageType === "tube" || selectedMed.packageType === "liquid_container") && (
+					{(isTubePackageType(selectedMed.packageType) || isLiquidContainerPackageType(selectedMed.packageType)) && (
 						<p className="edit-stock-cap-info">
 							{t("form.totalAmount")}: {formatNumber(isLiquidPackage ? liquidCapacity : structuralMax)}{" "}
 							{amountUnitLabel}
@@ -465,10 +474,7 @@ export function MedDetailModal({
 					{(() => {
 						const dbTotal = getMedTotal(selectedMed);
 						const currentTotal = medCoverage ? Math.round(medCoverage.medsLeft) : dbTotal;
-						const isBottle =
-							selectedMed.packageType === "bottle" ||
-							selectedMed.packageType === "tube" ||
-							selectedMed.packageType === "liquid_container";
+						const isBottle = isAmountBasedPackageType(selectedMed.packageType);
 						const enteredTotal = isLiquidPackage
 							? Math.min(liquidCapacity, editStockPartialBlisterPills)
 							: isBottle
@@ -813,7 +819,7 @@ export function MedDetailModal({
 					<div className="med-detail-section">
 						<h3>{t("modal.stockInfo")}</h3>
 						<div className="med-detail-grid">
-							{selectedMed.packageType === "blister" && (
+							{!isAmountBasedPackageType(selectedMed.packageType) && (
 								<>
 									<div className="med-detail-item">
 										<span className="med-detail-label">{t("table.fullBlisters")}</span>
@@ -832,7 +838,7 @@ export function MedDetailModal({
 									</div>
 								</>
 							)}
-							<div className={`med-detail-item ${selectedMed.packageType === "bottle" ? "full-width" : "full-width"}`}>
+							<div className="med-detail-item full-width">
 								<span className="med-detail-label">
 									{isAmountPackage ? t("form.currentAmount") : t("modal.currentStock")}
 								</span>
@@ -858,27 +864,27 @@ export function MedDetailModal({
 					<div className="med-detail-section">
 						<h3>
 							{t("modal.packageDetails")} (
-							{selectedMed.packageType === "bottle"
-								? t("form.packageTypeBottle")
-								: selectedMed.packageType === "tube"
-									? t("form.packageTypeTube")
-									: selectedMed.packageType === "liquid_container"
-										? t("form.packageTypeLiquidContainer")
+							{isTubePackageType(selectedMed.packageType)
+								? t("form.packageTypeTube")
+								: isLiquidContainerPackageType(selectedMed.packageType)
+									? t("form.packageTypeLiquidContainer")
+									: isAmountBasedPackageType(selectedMed.packageType)
+										? t("form.packageTypeBottle")
 										: t("form.packageTypeBlister")}
 							)
-							{selectedMed.packageType === "tube" && (
+							{isTubePackageType(selectedMed.packageType) && (
 								<span className="info-tooltip small" data-tooltip={t("modal.packageTypeTubeHint")}>
 									ℹ️
 								</span>
 							)}
-							{selectedMed.packageType === "liquid_container" && (
+							{isLiquidContainerPackageType(selectedMed.packageType) && (
 								<span className="info-tooltip small" data-tooltip={t("modal.packageTypeLiquidHint")}>
 									ℹ️
 								</span>
 							)}
 						</h3>
 						<div className="med-detail-grid">
-							{selectedMed.packageType === "blister" ? (
+							{!isAmountBasedPackageType(selectedMed.packageType) ? (
 								<>
 									<div className="med-detail-item">
 										<span className="med-detail-label">{t("modal.packs")}</span>
@@ -893,7 +899,7 @@ export function MedDetailModal({
 										<span className="med-detail-value">{selectedMed.pillsPerBlister}</span>
 									</div>
 								</>
-							) : selectedMed.packageType === "liquid_container" ? (
+							) : isLiquidContainerPackageType(selectedMed.packageType) ? (
 								<>
 									<div className="med-detail-item">
 										<span className="med-detail-label">{t("form.bottles")}</span>
@@ -912,7 +918,7 @@ export function MedDetailModal({
 										</span>
 									</div>
 								</>
-							) : selectedMed.packageType === "tube" ? (
+							) : isTubePackageType(selectedMed.packageType) ? (
 								<>
 									<div className="med-detail-item">
 										<span className="med-detail-label">{t("form.tubes")}</span>
@@ -937,7 +943,7 @@ export function MedDetailModal({
 									<span className="med-detail-value">{(selectedMed.totalPills ?? packageSize) || "—"}</span>
 								</div>
 							)}
-							{selectedMed.pillWeightMg && (
+							{showPillWeightDetails && (
 								<div className="med-detail-item">
 									<span className="med-detail-label">{t("modal.pillWeight")}</span>
 									<span className="med-detail-value">
@@ -967,7 +973,7 @@ export function MedDetailModal({
 						<div className="med-detail-section">
 							<h3>
 								{t("modal.intakeSchedule")}{" "}
-								{(selectedMed.intakeRemindersEnabled || hasAnyIntakeReminder) && (
+								{hasAnyIntakeReminder && (
 									<span className="reminder-icon info-tooltip" data-tooltip={t("tooltips.intakeReminders")}>
 										<Bell size={14} aria-hidden="true" />
 									</span>
@@ -978,7 +984,7 @@ export function MedDetailModal({
 									const hasPerIntakeTakenBy = !!intake.takenBy;
 									const personCount = Math.max(1, selectedMed.takenBy?.length ?? 0);
 									const totalUsage = hasPerIntakeTakenBy ? intake.usage : intake.usage * personCount;
-									const showIntakeBell = intake.intakeRemindersEnabled ?? selectedMed.intakeRemindersEnabled ?? false;
+									const showIntakeBell = intake.intakeRemindersEnabled === true;
 
 									return (
 										<div
@@ -987,8 +993,7 @@ export function MedDetailModal({
 										>
 											<span className="med-schedule-usage">
 												{getScheduleUsageLabel(totalUsage, intake.intakeUnit)}
-												{selectedMed.pillWeightMg &&
-													` (${totalUsage * selectedMed.pillWeightMg} ${selectedMed.doseUnit ?? "mg"})`}
+												{showPillWeightDetails && ` (${totalUsage * pillWeightMg} ${selectedMed.doseUnit ?? "mg"})`}
 											</span>
 											<span className="med-schedule-freq">
 												{intake.every === 1 ? t("common.daily") : t("common.everyNDays", { count: intake.every })}
@@ -1115,13 +1120,10 @@ export function MedDetailModal({
 											</span>
 											<span className="refill-amount">
 												{(() => {
-													const total =
-														selectedMed.packageType === "bottle" ||
-														selectedMed.packageType === "tube" ||
-														selectedMed.packageType === "liquid_container"
-															? entry.loosePillsAdded
-															: entry.packsAdded * selectedMed.blistersPerPack * selectedMed.pillsPerBlister +
-																entry.loosePillsAdded;
+													const total = isAmountBasedPackageType(selectedMed.packageType)
+														? entry.loosePillsAdded
+														: entry.packsAdded * selectedMed.blistersPerPack * selectedMed.pillsPerBlister +
+															entry.loosePillsAdded;
 													return `+${total}${isAmountPackage ? ` ${stockUnitLabel}` : ` ${total === 1 ? t("common.pill") : t("common.pills")}`}`;
 												})()}
 												{entry.usedPrescription && (
@@ -1221,7 +1223,7 @@ export function MedDetailModal({
 						<p className="refill-med-name">{getMedDisplayName(selectedMed)}</p>
 
 						<div className="refill-form">
-							{selectedMed.packageType === "blister" ? (
+							{!isAmountBasedPackageType(selectedMed.packageType) ? (
 								<>
 									<label>
 										{t("refill.packs")}
@@ -1242,6 +1244,23 @@ export function MedDetailModal({
 										})}
 									</label>
 								</>
+							) : isCountBasedAmountRefillPackage ? (
+								<label>
+									{isTubeRefillPackage ? t("form.tubes") : t("form.bottles")}
+									{renderRefillStepperInput({
+										value: amountRefillPackageCount,
+										min: 0,
+										max: Number.MAX_SAFE_INTEGER,
+										onChange: (nextPackages) => {
+											onRefillPacksChange(nextPackages);
+											onRefillLooseChange(nextPackages * liquidRefillAmountPerBottle);
+										},
+									})}
+									<p className="edit-stock-cap-info" style={{ marginTop: "0.35rem" }}>
+										{isTubeRefillPackage ? t("form.packageAmountPerTube") : t("form.packageAmountPerBottle")}:{" "}
+										{formatNumber(liquidRefillAmountPerBottle)} {amountUnitLabel}
+									</p>
+								</label>
 							) : (
 								<label>
 									{t("refill.pillsToAdd")}
@@ -1265,7 +1284,7 @@ export function MedDetailModal({
 												onUsePrescriptionRefillChange(checked);
 												if (
 													checked &&
-													selectedMed.packageType === "blister" &&
+													!isAmountBasedPackageType(selectedMed.packageType) &&
 													refillPacks > remainingPrescriptionRefills
 												) {
 													onRefillPacksChange(remainingPrescriptionRefills);
@@ -1291,10 +1310,10 @@ export function MedDetailModal({
 									className="success"
 									onClick={() => onSubmitRefill(selectedMed.id, usePrescriptionRefill)}
 									disabled={
-										(selectedMed.packageType === "bottle" ||
-										selectedMed.packageType === "tube" ||
-										selectedMed.packageType === "liquid_container"
-											? refillLoose < 1
+										(isAmountBasedPackageType(selectedMed.packageType)
+											? isCountBasedAmountRefillPackage
+												? amountRefillPackageCount < 1
+												: refillLoose < 1
 											: cappedRefillPacks < 1 && refillLoose < 1) ||
 										exceedsPrescriptionPackLimit ||
 										refillSaving
@@ -1303,9 +1322,10 @@ export function MedDetailModal({
 									{refillSaving ? t("common.saving") : t("refill.button")}
 								</button>
 								{(() => {
-									const totalRefill =
-										selectedMed.packageType === "blister"
-											? cappedRefillPacks * selectedMed.blistersPerPack * selectedMed.pillsPerBlister + refillLoose
+									const totalRefill = !isAmountBasedPackageType(selectedMed.packageType)
+										? cappedRefillPacks * selectedMed.blistersPerPack * selectedMed.pillsPerBlister + refillLoose
+										: isCountBasedAmountRefillPackage
+											? amountRefillPackageCount * liquidRefillAmountPerBottle
 											: refillLoose;
 									return totalRefill > 0 ? (
 										<span className="refill-preview">

frontend/src/components/MobileEditModal.tsx

@@ -10,7 +10,14 @@ import { useTranslation } from "react-i18next";
 import { useEscapeKey } from "../hooks/useEscapeKey";
 import { useScrollLock } from "../hooks/useScrollLock";
 import type { DoseUnit, FieldErrors, FormBlister, FormIntake, FormState, Medication } from "../types";
-import { DOSE_UNITS } from "../types";
+import {
+	allowsPillFormSelection,
+	DOSE_UNITS,
+	isAmountBasedPackageType,
+	isLiquidContainerPackageType,
+	isTubePackageType,
+	PACKAGE_PROFILES,
+} from "../types";
 import { deriveTotal } from "../utils";
 import { DateInput } from "./DateInput";
 import { FormNumberStepper } from "./FormNumberStepper";
@@ -68,7 +75,7 @@ export interface MobileEditModalProps {
 
 /** Calculate total pills from form state */
 function deriveTotalFromForm(form: FormState) {
-	if (form.packageType === "bottle" || form.packageType === "tube" || form.packageType === "liquid_container") {
+	if (isAmountBasedPackageType(form.packageType)) {
 		// For bottle type, looseTablets is the current stock
 		return Number(form.looseTablets) || 0;
 	}
@@ -126,19 +133,19 @@ export function MobileEditModal({
 	const activeTabIndexRef = useRef(0);
 
 	const allowFractionalIntake = useMemo(() => {
-		if (form.packageType === "liquid_container") return true;
-		if (form.packageType === "tube") return form.medicationForm === "liquid";
+		if (isLiquidContainerPackageType(form.packageType)) return true;
+		if (isTubePackageType(form.packageType)) return form.medicationForm === "liquid";
 		return form.pillForm === "tablet";
 	}, [form.packageType, form.medicationForm, form.pillForm]);
 
 	const getUsageLabel = useCallback(
 		(intake: (typeof form.intakes)[number]) => {
-			if (form.packageType === "liquid_container") {
+			if (isLiquidContainerPackageType(form.packageType)) {
 				if (intake.intakeUnit === "tsp") return t("form.blisters.usageTsp");
 				if (intake.intakeUnit === "tbsp") return t("form.blisters.usageTbsp");
 				return t("form.blisters.usageMl");
 			}
-			if (form.packageType === "tube") {
+			if (isTubePackageType(form.packageType)) {
 				return form.medicationForm === "liquid" ? t("form.blisters.usageMl") : t("form.blisters.usageApplication");
 			}
 			if (form.pillForm === "capsule") return t("form.blisters.usageCapsules");
@@ -147,7 +154,7 @@ export function MobileEditModal({
 		[form.packageType, form.medicationForm, form.pillForm, t]
 	);
 
-	const usesAmountLabels = form.packageType === "tube" || form.packageType === "liquid_container";
+	const usesAmountLabels = isTubePackageType(form.packageType) || isLiquidContainerPackageType(form.packageType);
 	const totalCapacityLabel = usesAmountLabels ? t("form.totalAmount") : t("form.totalCapacity");
 	const currentStockLabel = usesAmountLabels ? t("form.currentAmount") : t("form.currentPills");
 	const totalLabel = usesAmountLabels ? t("form.totalAmountLabel") : t("form.total");
@@ -414,42 +421,46 @@ export function MobileEditModal({
 												<span className="field-error">{fieldErrors.genericName}</span>
 											)}
 										</label>
-										<label className="full">
-											{t("form.medicationStartDate")}
-											<DateInput
-												value={form.medicationStartDate}
-												onChange={(e) => onHandleValueChange("medicationStartDate", e.target.value)}
-												placeholder={t("common.optional")}
-											/>
-											{!readOnlyMode && dateConsistencyError && (
-												<span className="field-error">{dateConsistencyError}</span>
-											)}
-										</label>
+										<div className="full date-pair-group">
+											<label className="date-pair-field">
+												{t("form.medicationStartDate")}
+												<DateInput
+													value={form.medicationStartDate}
+													onChange={(e) => onHandleValueChange("medicationStartDate", e.target.value)}
+													placeholder={t("common.optional")}
+												/>
+												{!readOnlyMode && dateConsistencyError && (
+													<span className="field-error">{dateConsistencyError}</span>
+												)}
+											</label>
+											<label className="date-pair-field">
+												{t("form.medicationEndDate")}
+												<DateInput
+													value={form.medicationEndDate}
+													onChange={(e) => onHandleValueChange("medicationEndDate", e.target.value)}
+													placeholder={t("common.optional")}
+												/>
+											</label>
+										</div>
 										<label className="full">
 											{t("form.packageType")}
 											<select
-												className="package-type-select"
+												className="select-field package-type-select"
 												value={form.packageType}
 												onChange={(e) => onHandleValueChange("packageType", e.target.value as FormState["packageType"])}
 											>
-												<option value="blister">{t("form.packageTypeBlister")}</option>
-												<option value="bottle">{t("form.packageTypeBottle")}</option>
-												<option value="tube">{t("form.packageTypeTube")}</option>
-												<option value="liquid_container">{t("form.packageTypeLiquidContainer")}</option>
+												{PACKAGE_PROFILES.map((profile) => (
+													<option key={profile.value} value={profile.value}>
+														{t(profile.labelKey)}
+													</option>
+												))}
 											</select>
 										</label>
-										<label className="full">
-											{t("form.medicationEndDate")}
-											<DateInput
-												value={form.medicationEndDate}
-												onChange={(e) => onHandleValueChange("medicationEndDate", e.target.value)}
-												placeholder={t("common.optional")}
-											/>
-										</label>
-										{form.packageType !== "tube" && form.packageType !== "liquid_container" && (
+										{allowsPillFormSelection(form.packageType) && (
 											<label className="full">
 												{t("form.pillForm")}
 												<select
+													className="select-field"
 													value={form.pillForm}
 													onChange={(e) => onHandleValueChange("pillForm", e.target.value as FormState["pillForm"])}
 												>
@@ -458,18 +469,26 @@ export function MobileEditModal({
 												</select>
 											</label>
 										)}
-										{form.packageType === "tube" && (
+										{isTubePackageType(form.packageType) && (
 											<label className="full">
 												{t("form.medicationForm")}
-												<select value={"topical"} onChange={() => onHandleValueChange("medicationForm", "topical")}>
+												<select
+													className="select-field"
+													value={"topical"}
+													onChange={() => onHandleValueChange("medicationForm", "topical")}
+												>
 													<option value="topical">{t("form.medicationFormTopical")}</option>
 												</select>
 											</label>
 										)}
-										{form.packageType === "liquid_container" && (
+										{isLiquidContainerPackageType(form.packageType) && (
 											<label className="full">
 												{t("form.medicationForm")}
-												<select value={"liquid"} onChange={() => onHandleValueChange("medicationForm", "liquid")}>
+												<select
+													className="select-field"
+													value={"liquid"}
+													onChange={() => onHandleValueChange("medicationForm", "liquid")}
+												>
 													<option value="liquid">{t("form.medicationFormLiquid")}</option>
 												</select>
 											</label>
@@ -560,7 +579,7 @@ export function MobileEditModal({
 									<div className="full form-category">
 										<h4 className="form-category-title">{t("form.sections.stock")}</h4>
 										{(() => {
-											if (form.packageType === "blister") {
+											if (!isAmountBasedPackageType(form.packageType)) {
 												return (
 													<>
 														<label>
@@ -601,7 +620,7 @@ export function MobileEditModal({
 												);
 											}
 
-											if (form.packageType === "tube") {
+											if (isTubePackageType(form.packageType)) {
 												return (
 													<>
 														<label>
@@ -622,7 +641,7 @@ export function MobileEditModal({
 																<select
 																	value="g"
 																	disabled
-																	className="dose-unit-select"
+																	className="select-field dose-unit-select"
 																	aria-label={t("form.packageAmountUnitG")}
 																>
 																	<option value="g">{t("form.packageAmountUnitG")}</option>
@@ -640,7 +659,7 @@ export function MobileEditModal({
 												);
 											}
 
-											if (form.packageType === "liquid_container") {
+											if (isLiquidContainerPackageType(form.packageType)) {
 												return (
 													<>
 														<label>
@@ -667,7 +686,7 @@ export function MobileEditModal({
 																<select
 																	value="ml"
 																	disabled
-																	className="dose-unit-select"
+																	className="select-field dose-unit-select"
 																	aria-label={t("form.packageAmountUnitMl")}
 																>
 																	<option value="ml">{t("form.packageAmountUnitMl")}</option>
@@ -710,7 +729,7 @@ export function MobileEditModal({
 												</>
 											);
 										})()}
-										{form.packageType === "bottle" && (
+										{isAmountBasedPackageType(form.packageType) && !isTubePackageType(form.packageType) && (
 											<div className="full stock-total-row">
 												<div className="stock-total-field">
 													<p className="sub">
@@ -720,7 +739,7 @@ export function MobileEditModal({
 												</div>
 											</div>
 										)}
-										{form.packageType !== "tube" && form.packageType !== "liquid_container" && (
+										{allowsPillFormSelection(form.packageType) && (
 											<label className="full">
 												{t("form.pillWeight")} ({form.doseUnit})
 												<div className="dose-input-group">
@@ -735,7 +754,7 @@ export function MobileEditModal({
 													<select
 														value={form.doseUnit}
 														onChange={(e) => onFormChange({ ...form, doseUnit: e.target.value as DoseUnit })}
-														className="dose-unit-select"
+														className="select-field dose-unit-select"
 													>
 														{DOSE_UNITS.map((unit) => (
 															<option key={unit.value} value={unit.value}>
@@ -837,10 +856,11 @@ export function MobileEditModal({
 														onChange={(e) => onSetIntakeValue(idx, "startTime", e.target.value)}
 													/>
 												</label>
-												{form.packageType === "liquid_container" && (
+												{isLiquidContainerPackageType(form.packageType) && (
 													<label className="compact full-row">
 														<span>{t("form.blisters.intakeUnit")}</span>
 														<select
+															className="select-field"
 															value={intake.intakeUnit}
 															onChange={(e) =>
 																onSetIntakeValue(idx, "intakeUnit", e.target.value as "ml" | "tsp" | "tbsp")
@@ -856,6 +876,7 @@ export function MobileEditModal({
 													<label className="compact full-row taken-by-field">
 														<span>{t("form.blisters.takenByIntake")}</span>
 														<select
+															className="select-field"
 															value={intake.takenBy}
 															onChange={(e) => onSetIntakeValue(idx, "takenBy", e.target.value)}
 														>

frontend/src/components/ReportModal.tsx

@@ -3,7 +3,13 @@ import { useTranslation } from "react-i18next";
 import { useEscapeKey } from "../hooks/useEscapeKey";
 import { useScrollLock } from "../hooks/useScrollLock";
 import type { Medication } from "../types";
-import { getMedDisplayName, getPackageSize } from "../types";
+import {
+	getMedDisplayName,
+	getPackageSize,
+	isAmountBasedPackageType,
+	isLiquidContainerPackageType,
+	isTubePackageType,
+} from "../types";
 import { MedicationAvatar } from "./MedicationAvatar";
 
 type ReportFormat = "txt" | "md" | "pdf";
@@ -299,35 +305,35 @@ function fmtDateTime(iso: string | null | undefined): string {
 }
 
 function getTubeUnitKey(med: Medication): "form.ml" | "blisters.applications" {
-	if (med.packageType === "liquid_container") return "form.ml";
+	if (isLiquidContainerPackageType(med.packageType)) return "form.ml";
 	return med.medicationForm === "liquid" ? "form.ml" : "blisters.applications";
 }
 
 function getUsageText(med: Medication, usage: number, t: TFn): string {
-	if (med.packageType === "tube" || med.packageType === "liquid_container") {
+	if (isTubePackageType(med.packageType) || isLiquidContainerPackageType(med.packageType)) {
 		return `${usage} ${t(getTubeUnitKey(med))}`;
 	}
 	return `${usage} ${usage === 1 ? t("common.pill") : t("common.pills")}`;
 }
 
 function getTotalCapacityLabel(med: Medication, t: TFn): string {
-	if (med.packageType === "tube" || med.packageType === "liquid_container") {
+	if (isTubePackageType(med.packageType) || isLiquidContainerPackageType(med.packageType)) {
 		return t("form.totalAmountLabel", { unit: t(getTubeUnitKey(med)) });
 	}
 	return t("report.docTotalCapacity");
 }
 
 function getCurrentStockText(med: Medication, t: TFn): string {
-	if (med.packageType === "tube" || med.packageType === "liquid_container") {
+	if (isTubePackageType(med.packageType) || isLiquidContainerPackageType(med.packageType)) {
 		return `${getPackageSize(med)} ${t(getTubeUnitKey(med))}`;
 	}
 	return `${getPackageSize(med)} ${t("common.pills")}`;
 }
 
 function getReportPackageTypeLabel(med: Medication, t: TFn): string {
-	if (med.packageType === "bottle") return t("report.docBottle");
-	if (med.packageType === "tube") return t("report.docTube");
-	if (med.packageType === "liquid_container") return t("form.packageTypeLiquidContainer");
+	if (isTubePackageType(med.packageType)) return t("report.docTube");
+	if (isLiquidContainerPackageType(med.packageType)) return t("form.packageTypeLiquidContainer");
+	if (isAmountBasedPackageType(med.packageType)) return t("report.docBottle");
 	return t("report.docBlister");
 }
 
@@ -374,7 +380,7 @@ function generateTextReport(
 		// Package / Stock
 		lines.push(h3(t("report.docPackage")));
 		lines.push(item(t("report.docPackageType"), getReportPackageTypeLabel(med, t)));
-		if (med.packageType === "blister") {
+		if (!isAmountBasedPackageType(med.packageType)) {
 			lines.push(item(t("report.docPacks"), String(med.packCount)));
 			lines.push(item(t("report.docBlistersPerPack"), String(med.blistersPerPack)));
 			lines.push(item(t("report.docPillsPerBlister"), String(med.pillsPerBlister)));
@@ -383,7 +389,7 @@ function generateTextReport(
 			lines.push(item(getTotalCapacityLabel(med, t), String(med.totalPills ?? med.looseTablets)));
 		}
 		lines.push(item(t("report.docCurrentStock"), getCurrentStockText(med, t)));
-		if (med.packageType !== "tube" && med.packageType !== "liquid_container" && med.pillWeightMg)
+		if (!isTubePackageType(med.packageType) && !isLiquidContainerPackageType(med.packageType) && med.pillWeightMg)
 			lines.push(item(t("report.docDosePerPill"), `${med.pillWeightMg} ${med.doseUnit ?? "mg"}`));
 		if (med.expiryDate) lines.push(item(t("report.docExpiryDate"), fmtDate(med.expiryDate)));
 		if (med.notes) lines.push(item(t("report.docNotes"), med.notes));
@@ -439,7 +445,7 @@ function generateTextReport(
 			if (data.refills.length > 0) {
 				lines.push(h3(t("report.docRefillHistory")));
 				for (const r of data.refills) {
-					let entry = `${fmtDate(r.refillDate)}: +${r.packsAdded} ${t("report.docPacks")}, +${r.loosePillsAdded} ${med.packageType === "tube" || med.packageType === "liquid_container" ? t(getTubeUnitKey(med)) : t("common.pills")}`;
+					let entry = `${fmtDate(r.refillDate)}: +${r.packsAdded} ${t("report.docPacks")}, +${r.loosePillsAdded} ${isTubePackageType(med.packageType) || isLiquidContainerPackageType(med.packageType) ? t(getTubeUnitKey(med)) : t("common.pills")}`;
 					if (r.usedPrescription) entry += ` ${t("report.docRefillPrescription")}`;
 					lines.push(fmt === "md" ? `- ${entry}` : `  • ${entry}`);
 				}
@@ -572,7 +578,7 @@ function buildPrintHtml(
 		s += `<h3>${escHtml(t("report.docPackage"))}</h3>`;
 		s += `<table><tbody>`;
 		s += `<tr><td class="label">${escHtml(t("report.docPackageType"))}</td><td>${escHtml(getReportPackageTypeLabel(med, t))}</td></tr>`;
-		if (med.packageType === "blister") {
+		if (!isAmountBasedPackageType(med.packageType)) {
 			s += `<tr><td class="label">${escHtml(t("report.docPacks"))}</td><td>${med.packCount}</td></tr>`;
 			s += `<tr><td class="label">${escHtml(t("report.docBlistersPerPack"))}</td><td>${med.blistersPerPack}</td></tr>`;
 			s += `<tr><td class="label">${escHtml(t("report.docPillsPerBlister"))}</td><td>${med.pillsPerBlister}</td></tr>`;
@@ -582,7 +588,7 @@ function buildPrintHtml(
 			s += `<tr><td class="label">${escHtml(getTotalCapacityLabel(med, t))}</td><td>${med.totalPills ?? med.looseTablets}</td></tr>`;
 		}
 		s += `<tr><td class="label">${escHtml(t("report.docCurrentStock"))}</td><td>${escHtml(getCurrentStockText(med, t))}</td></tr>`;
-		if (med.packageType !== "tube" && med.packageType !== "liquid_container" && med.pillWeightMg)
+		if (!isTubePackageType(med.packageType) && !isLiquidContainerPackageType(med.packageType) && med.pillWeightMg)
 			s += `<tr><td class="label">${escHtml(t("report.docDosePerPill"))}</td><td>${med.pillWeightMg} ${escHtml(med.doseUnit ?? "mg")}</td></tr>`;
 		if (med.expiryDate)
 			s += `<tr><td class="label">${escHtml(t("report.docExpiryDate"))}</td><td>${fmtDate(med.expiryDate)}</td></tr>`;
@@ -646,7 +652,7 @@ function buildPrintHtml(
 				s += `<h3>${escHtml(t("report.docRefillHistory"))}</h3>`;
 				s += `<ul>`;
 				for (const r of data.refills) {
-					let entry = `${fmtDate(r.refillDate)}: +${r.packsAdded} ${escHtml(t("report.docPacks"))}, +${r.loosePillsAdded} ${escHtml(med.packageType === "tube" || med.packageType === "liquid_container" ? t(getTubeUnitKey(med)) : t("common.pills"))}`;
+					let entry = `${fmtDate(r.refillDate)}: +${r.packsAdded} ${escHtml(t("report.docPacks"))}, +${r.loosePillsAdded} ${escHtml(isTubePackageType(med.packageType) || isLiquidContainerPackageType(med.packageType) ? t(getTubeUnitKey(med)) : t("common.pills"))}`;
 					if (r.usedPrescription) entry += ` <em>${escHtml(t("report.docRefillPrescription"))}</em>`;
 					s += `<li>${entry}</li>`;
 				}

frontend/src/components/ShareDialog.tsx

@@ -42,6 +42,7 @@ export function ShareDialog({
 	const { t } = useTranslation();
 	const closeLabel = t("common.close");
 	const copyLabel = shareCopied ? t("share.copied") : t("share.copyLink");
+	const getPersonLabel = (person: string) => (person === "all" ? t("share.allPeople") : person);
 
 	// ESC is handled by the global handler in App.tsx to avoid double history.back()
 
@@ -91,6 +92,7 @@ export function ShareDialog({
 						return (
 							<div className="share-dialog-result">
 								<p className="share-success">{t("share.linkGenerated")}</p>
+								<p className="share-link-label">{t("share.scheduleLink")}</p>
 								<div className="share-link-box">
 									<input
 										type="text"
@@ -131,12 +133,13 @@ export function ShareDialog({
 								<label htmlFor="share-person-select">{t("share.selectPerson")}</label>
 								<select
 									id="share-person-select"
+									className="select-field"
 									value={shareSelectedPerson}
 									onChange={(e) => onShareSelectedPersonChange(e.target.value)}
 								>
 									{sharePeople.map((person) => (
 										<option key={person} value={person}>
-											{person}
+											{getPersonLabel(person)}
 										</option>
 									))}
 								</select>
@@ -146,6 +149,7 @@ export function ShareDialog({
 								<label htmlFor="share-period-select">{t("share.selectPeriod")}</label>
 								<select
 									id="share-period-select"
+									className="select-field"
 									value={shareSelectedDays}
 									onChange={(e) => onShareSelectedDaysChange(Number(e.target.value))}
 								>

frontend/src/components/SharedMedicationOverviewSection.tsx

@@ -0,0 +1,194 @@
+import { useTranslation } from "react-i18next";
+import type { SharedMedicationOverviewItem } from "../types";
+import { formatDate } from "../utils/formatters";
+import { MedicationAvatar } from "./MedicationAvatar";
+
+function formatPackageInfo(medication: SharedMedicationOverviewItem): string {
+	if (medication.packageType === "blister") {
+		return `${medication.packCount} x ${medication.blistersPerPack} x ${medication.pillsPerBlister}`;
+	}
+
+	if (medication.totalPills !== null) {
+		return `${medication.packCount} x ${medication.totalPills}`;
+	}
+
+	return `${medication.packCount}`;
+}
+
+function getOverviewStatus(
+	priority: SharedMedicationOverviewItem["priority"]
+): { className: string; labelKey: string } | null {
+	if (priority === null) return null;
+	if (priority === "out-of-stock") {
+		return { className: "danger", labelKey: "status.outOfStock" };
+	}
+	if (priority === "high") {
+		return { className: "warning", labelKey: "status.lowStock" };
+	}
+	return { className: "normal", labelKey: "status.normal" };
+}
+
+export interface SharedMedicationOverviewSectionProps {
+	takenBy: string;
+	sharedBy: string | null;
+	medications: SharedMedicationOverviewItem[];
+	showTitle?: boolean;
+	onMedicationImageClick?: (imageUrl: string, name: string) => void;
+}
+
+export function SharedMedicationOverviewSection({
+	takenBy,
+	medications,
+	showTitle = true,
+	onMedicationImageClick,
+}: SharedMedicationOverviewSectionProps) {
+	const { t } = useTranslation();
+	const renderMedicationAvatar = (name: string, imageUrl: string | null) => {
+		const isClickable = Boolean(imageUrl && onMedicationImageClick);
+
+		return (
+			<div
+				className={isClickable ? "med-avatar clickable" : undefined}
+				onClick={() => {
+					if (imageUrl && onMedicationImageClick) onMedicationImageClick(imageUrl, name);
+				}}
+				onKeyDown={(e) => {
+					if ((e.key === "Enter" || e.key === " ") && imageUrl && onMedicationImageClick) {
+						onMedicationImageClick(imageUrl, name);
+					}
+				}}
+			>
+				<MedicationAvatar name={name} imageUrl={imageUrl} size="sm" />
+			</div>
+		);
+	};
+
+	return (
+		<section className="shared-overview-inline-section" aria-label={t("sharedOverview.title", { person: takenBy })}>
+			{showTitle ? (
+				<div className="shared-overview-section-header">
+					<h2>{t("sharedOverview.title", { person: takenBy })}</h2>
+				</div>
+			) : null}
+			{medications.length === 0 ? (
+				<p className="shared-schedule-empty">{t("sharedOverview.noMedications")}</p>
+			) : (
+				<>
+					<div className="shared-overview-table-wrap">
+						<table className="shared-overview-table">
+							<thead>
+								<tr>
+									<th>{t("sharedOverview.columns.name")}</th>
+									<th>{t("sharedOverview.columns.package")}</th>
+									<th>{t("sharedOverview.columns.stock")}</th>
+									<th>{t("sharedOverview.columns.daysLeft")}</th>
+									<th>{t("sharedOverview.columns.depletion")}</th>
+									<th>{t("sharedOverview.columns.priority")}</th>
+								</tr>
+							</thead>
+							<tbody>
+								{medications.map((medication) => {
+									const overviewStatus = getOverviewStatus(medication.priority);
+
+									return (
+										<tr key={`${medication.name}-${medication.medicationStartDate ?? "no-start"}`}>
+											<td>
+												<div className="shared-overview-medication-cell">
+													{renderMedicationAvatar(medication.name, medication.imageUrl)}
+													<div className="shared-overview-medication-text">
+														<div className="shared-overview-med-name">
+															<strong>{medication.name}</strong>
+															{medication.genericName ? (
+																<span className="shared-overview-med-generic">{medication.genericName}</span>
+															) : null}
+														</div>
+													</div>
+												</div>
+											</td>
+											<td>{formatPackageInfo(medication)}</td>
+											<td>
+												<span className="shared-overview-stock-value">
+													{medication.currentStock === null || medication.capacity === null
+														? "-"
+														: t("sharedOverview.stock.of", {
+																current: medication.currentStock,
+																capacity: medication.capacity,
+															})}
+												</span>
+											</td>
+											<td>{medication.daysLeft === null ? "-" : medication.daysLeft}</td>
+											<td>
+												<span className="shared-overview-date-value">{formatDate(medication.depletionDate)}</span>
+											</td>
+											<td>
+												{overviewStatus === null ? (
+													"-"
+												) : (
+													<span className={`shared-overview-priority ${overviewStatus.className}`}>
+														{t(overviewStatus.labelKey)}
+													</span>
+												)}
+											</td>
+										</tr>
+									);
+								})}
+							</tbody>
+						</table>
+					</div>
+
+					<div className="shared-overview-cards">
+						{medications.map((medication) => {
+							const overviewStatus = getOverviewStatus(medication.priority);
+
+							return (
+								<article
+									className="shared-overview-card"
+									key={`${medication.name}-${medication.medicationStartDate ?? "no-start"}`}
+								>
+									<div className="shared-overview-card-title">
+										{renderMedicationAvatar(medication.name, medication.imageUrl)}
+										<div className="shared-overview-medication-text">
+											<div className="shared-overview-med-name">
+												<strong>{medication.name}</strong>
+												{medication.genericName ? (
+													<span className="shared-overview-med-generic">{medication.genericName}</span>
+												) : null}
+											</div>
+										</div>
+									</div>
+									<div className="shared-overview-card-grid">
+										<span>{t("sharedOverview.columns.package")}</span>
+										<strong>{formatPackageInfo(medication)}</strong>
+										<span>{t("sharedOverview.columns.stock")}</span>
+										<strong>
+											<span className="shared-overview-stock-value">
+												{medication.currentStock === null || medication.capacity === null
+													? "-"
+													: t("sharedOverview.stock.of", {
+															current: medication.currentStock,
+															capacity: medication.capacity,
+														})}
+											</span>
+										</strong>
+										<span>{t("sharedOverview.columns.daysLeft")}</span>
+										<strong>{medication.daysLeft === null ? "-" : medication.daysLeft}</strong>
+
+										<span>{t("sharedOverview.columns.depletion")}</span>
+										<strong>
+											<span className="shared-overview-date-value">{formatDate(medication.depletionDate)}</span>
+										</strong>
+									</div>
+									{overviewStatus ? (
+										<span className={`shared-overview-priority ${overviewStatus.className}`}>
+											{t(overviewStatus.labelKey)}
+										</span>
+									) : null}
+								</article>
+							);
+						})}
+					</div>
+				</>
+			)}
+		</section>
+	);
+}

frontend/src/components/UserFilterModal.tsx

@@ -7,6 +7,7 @@ import { MedicationAvatar } from "../components";
 import { useEscapeKey } from "../hooks/useEscapeKey";
 import type { Coverage, Medication, StockThresholds } from "../types";
 import { getMedDisplayName, getMedTotal, getPackageSize } from "../types";
+import { allowsPillFormSelection, isLiquidContainerPackageType, isTubePackageType } from "../types/package-profiles";
 import { formatNumber } from "../utils";
 import { getSystemLocale } from "../utils/formatters";
 import { getStockStatus } from "../utils/schedule";
@@ -32,6 +33,43 @@ export function UserFilterModal({
 }: UserFilterModalProps) {
 	const { t, i18n } = useTranslation();
 
+	const isLiquidMedication = (med: Medication): boolean => {
+		const rawPackageType = med.packageType as unknown as string | null | undefined;
+		return (
+			isLiquidContainerPackageType(med.packageType) || rawPackageType === "liquid" || med.medicationForm === "liquid"
+		);
+	};
+
+	const getLiquidCountUnitLabel = (unit: "ml" | "tsp" | "tbsp" | null | undefined, usage: number): string => {
+		if (unit === "tsp") return t("form.blisters.teaspoons", { count: Math.abs(usage) });
+		if (unit === "tbsp") return t("form.blisters.tablespoons", { count: Math.abs(usage) });
+		return t("form.packageAmountUnitMl");
+	};
+
+	const formatIntakeUsageLabel = (
+		med: Medication,
+		usage: number,
+		intakeUnit?: "ml" | "tsp" | "tbsp" | null
+	): string => {
+		if (isLiquidMedication(med)) {
+			return `${formatNumber(usage)} ${getLiquidCountUnitLabel(intakeUnit, usage)}`;
+		}
+		if (isTubePackageType(med.packageType)) {
+			return `${formatNumber(usage)} ${t("form.blisters.applications", { count: usage })}`;
+		}
+		return `${formatNumber(usage)} ${usage !== 1 ? t("common.pills") : t("common.pill")}`;
+	};
+
+	const formatStockSummaryLabel = (med: Medication, currentStock: number, packageSize: number): string => {
+		if (isLiquidMedication(med)) {
+			return `${formatNumber(currentStock)}/${formatNumber(packageSize)} ${t("form.packageAmountUnitMl")}`;
+		}
+		if (isTubePackageType(med.packageType)) {
+			return `${formatNumber(currentStock)}/${formatNumber(packageSize)} ${t("form.packageAmountUnitG")}`;
+		}
+		return `${formatNumber(currentStock)}/${formatNumber(packageSize)} ${packageSize === 1 ? t("common.pill") : t("common.pills")}`;
+	};
+
 	useEscapeKey(!!selectedUser, onClose);
 
 	if (!selectedUser) return null;
@@ -70,7 +108,7 @@ export function UserFilterModal({
 							? getStockStatus(medCoverage.daysLeft, medCoverage.medsLeft, settings, med.packageType)
 							: getStockStatus(null, getMedTotal(med), settings, med.packageType);
 						const packageSize = getPackageSize(med);
-						const currentStock = medCoverage ? formatNumber(medCoverage.medsLeft) : formatNumber(getMedTotal(med));
+						const currentStock = medCoverage ? medCoverage.medsLeft : getMedTotal(med);
 
 						// Get intakes relevant to this person
 						const personIntakes = (
@@ -109,10 +147,12 @@ export function UserFilterModal({
 													minute: "2-digit",
 												});
 												const intakeKey = `${intake.start}-${intake.usage}-${intake.every}-${intake.takenBy ?? ""}`;
+												const intakeUnit = "intakeUnit" in intake ? intake.intakeUnit : undefined;
 												return (
 													<span key={intakeKey} className="user-med-intake-item">
-														{intake.usage} {intake.usage !== 1 ? t("common.pills") : t("common.pill")}
-														{med.pillWeightMg != null &&
+														{formatIntakeUsageLabel(med, intake.usage, intakeUnit)}
+														{allowsPillFormSelection(med.packageType) &&
+															med.pillWeightMg != null &&
 															` (${intake.usage * med.pillWeightMg} ${med.doseUnit ?? "mg"})`}{" "}
 														{intake.every === 1 ? t("common.daily") : t("common.everyNDays", { count: intake.every })}{" "}
 														{t("modal.at")} {timeStr}
@@ -123,10 +163,7 @@ export function UserFilterModal({
 									)}
 								</div>
 								<div className="user-med-stats">
-									<span className="user-med-pills">
-										{currentStock}/{formatNumber(packageSize)}{" "}
-										{packageSize === 1 ? t("common.pill") : t("common.pills")}
-									</span>
+									<span className="user-med-pills">{formatStockSummaryLabel(med, currentStock, packageSize)}</span>
 									{status && <span className={`status-chip ${status.className}`}>{t(status.label)}</span>}
 								</div>
 							</div>

frontend/src/components/index.ts

@@ -21,6 +21,7 @@ export { default as ProfileModal } from "./ProfileModal";
 export { default as ReportModal } from "./ReportModal";
 export type { ShareDialogProps } from "./ShareDialog";
 export { ShareDialog } from "./ShareDialog";
+export { SharedMedicationOverviewSection } from "./SharedMedicationOverviewSection";
 export { SharedSchedule } from "./SharedSchedule";
 export type { TagInputProps } from "./TagInput";
 export { TagInput } from "./TagInput";

frontend/src/context/AppContext.tsx

@@ -3,7 +3,14 @@ import { createContext, useCallback, useContext, useEffect, useMemo, useRef, use
 import { useTranslation } from "react-i18next";
 import { useAuth } from "../components/Auth";
 import { useCollapsedDays, useDoses, useMedications, useRefill, useSettings, useShare } from "../hooks";
-import type { Coverage, FormState, Medication, ScheduleEvent, StockThresholds } from "../types";
+import {
+	type Coverage,
+	type FormState,
+	getMedDisplayName,
+	type Medication,
+	type ScheduleEvent,
+	type StockThresholds,
+} from "../types";
 import { getSystemLocale } from "../utils/formatters";
 import { log } from "../utils/logger";
 import { buildSchedulePreview, calculateCoverage, computeMissedPastDoseIds, getStockStatus } from "../utils/schedule";
@@ -54,6 +61,7 @@ export interface AppContextValue {
 	setSettings: ReturnType<typeof useSettings>["setSettings"];
 	savedSettings: ReturnType<typeof useSettings>["savedSettings"];
 	settingsLoading: boolean;
+	settingsLoadError: ReturnType<typeof useSettings>["settingsLoadError"];
 	settingsSaving: boolean;
 	settingsSaved: boolean;
 	testingEmail: boolean;
@@ -69,15 +77,11 @@ export interface AppContextValue {
 	takenDoses: Set<string>;
 	setTakenDoses: React.Dispatch<React.SetStateAction<Set<string>>>;
 	dismissedDoses: Set<string>;
-	clearingMissed: boolean;
-	showClearMissedConfirm: boolean;
-	setShowClearMissedConfirm: (show: boolean) => void;
 	getDoseId: (baseDoseId: string, person: string | null) => string;
 	isDoseTakenAutomatically: (doseId: string) => boolean;
 	countTakenDoses: (doses: Array<{ id: string; takenBy: string[] }>) => { total: number; taken: number };
 	markDoseTaken: (doseId: string) => Promise<void>;
 	undoDoseTaken: (doseId: string) => Promise<void>;
-	dismissMissedDoses: (doseIds: string[]) => Promise<void>;
 
 	// From useCollapsedDays
 	manuallyCollapsedDays: Set<string>;
@@ -299,14 +303,49 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
 		if (typeof window !== "undefined" && user?.id) {
 			const storedDays = localStorage.getItem(userStorageKey(user.id, "scheduleDays"));
 			setScheduleDays(storedDays ? Number(storedDays) : 30);
+		} else {
+			setScheduleDays(30);
 		}
 	}, [user?.id]);
 
-	// Load medications and settings when user changes
+	// Security boundary: clear user-scoped UI state immediately on user/session switches,
+	// then load fresh data for the active identity.
 	useEffect(() => {
+		if (!user?.id) {
+			setScheduleDays(30);
+		}
+
+		medications.clearMedicationsState();
+		settingsHook.resetSettingsState();
+		doses.clearDosesState();
+		refill.clearRefillState();
+		share.resetShareDialogState();
+
+		setSelectedMed(null);
+		setShowImageLightbox(false);
+		setScheduleLightboxImage(null);
+		setSelectedUser(null);
+		setShowPastDays(false);
+		setShowFutureDays(false);
+		setShowExportModal(false);
+		setShowImportConfirm(false);
+		setPendingImportData(null);
+		setImportResult(null);
+
 		medications.loadMeds();
 		settingsHook.loadSettings();
-	}, [medications.loadMeds, settingsHook.loadSettings]);
+		doses.loadTakenDoses();
+	}, [
+		user?.id,
+		medications.clearMedicationsState,
+		medications.loadMeds,
+		settingsHook.resetSettingsState,
+		settingsHook.loadSettings,
+		doses.clearDosesState,
+		doses.loadTakenDoses,
+		refill.clearRefillState,
+		share.resetShareDialogState,
+	]);
 
 	// Update selectedMed when meds change (e.g., after refill)
 	useEffect(() => {
@@ -357,6 +396,25 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
 
 	const coverageByMed = useMemo(() => Object.fromEntries(coverage.all.map((c) => [c.name, c])), [coverage.all]);
 
+	const outOfStockMedicationIds = useMemo(
+		() =>
+			new Set(
+				activeMeds.filter((med) => (coverageByMed[getMedDisplayName(med)]?.medsLeft ?? 1) <= 0).map((med) => med.id)
+			),
+		[activeMeds, coverageByMed]
+	);
+
+	const effectiveTakenDoses = useMemo(
+		() =>
+			new Set(
+				Array.from(doses.takenDoses).filter((doseId) => {
+					const medId = Number.parseInt(doseId.split("-")[0] ?? "", 10);
+					return Number.isNaN(medId) || !outOfStockMedicationIds.has(medId);
+				})
+			),
+		[doses.takenDoses, outOfStockMedicationIds]
+	);
+
 	// Centralized stock thresholds for consistent status display across all components
 	const stockThresholds: StockThresholds = useMemo(
 		() => ({
@@ -480,8 +538,8 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
 	}, [groupedSchedule, scheduleDays]);
 
 	const missedPastDoseIds = useMemo(
-		() => computeMissedPastDoseIds(pastDays, activeMeds, doses.takenDoses, doses.dismissedDoses),
-		[pastDays, activeMeds, doses.takenDoses, doses.dismissedDoses]
+		() => computeMissedPastDoseIds(pastDays, activeMeds, effectiveTakenDoses, doses.dismissedDoses),
+		[pastDays, activeMeds, effectiveTakenDoses, doses.dismissedDoses]
 	);
 
 	// Modal helpers with browser history support
@@ -735,61 +793,13 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
 			settings.maxNaggingReminders !== savedSettings.maxNaggingReminders ||
 			settings.stockCalculationMode !== savedSettings.stockCalculationMode ||
 			settings.shareStockStatus !== savedSettings.shareStockStatus ||
+			settings.shareMedicationOverview !== savedSettings.shareMedicationOverview ||
 			settings.upcomingTodayOnly !== savedSettings.upcomingTodayOnly ||
 			settings.shareScheduleTodayOnly !== savedSettings.shareScheduleTodayOnly ||
 			settings.expiryWarningDays !== savedSettings.expiryWarningDays
 		);
 	}, [settingsHook.settings, settingsHook.savedSettings]);
 
-	// New dismissMissedDoses that uses medication-level dismissedUntil dates
-	// This is robust against timestamp changes from schedule updates or timezone fixes
-	const [clearingMissedState, setClearingMissedState] = useState(false);
-
-	const dismissMissedDoses = useCallback(
-		async (doseIds: string[]) => {
-			if (doseIds.length === 0) return;
-
-			// Extract unique medication IDs from dose IDs (format: medId-blisterIdx-timestamp[-person])
-			const medIds = new Set<number>();
-			for (const doseId of doseIds) {
-				const parts = doseId.split("-");
-				if (parts.length >= 1) {
-					const medId = parseInt(parts[0], 10);
-					if (!Number.isNaN(medId)) {
-						medIds.add(medId);
-					}
-				}
-			}
-
-			if (medIds.size === 0) return;
-
-			// Get today's date in YYYY-MM-DD format
-			const today = new Date();
-			const until = `${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, "0")}-${String(today.getDate()).padStart(2, "0")}`;
-
-			setClearingMissedState(true);
-			try {
-				const res = await fetch("/api/medications/dismiss-until", {
-					method: "POST",
-					headers: { "Content-Type": "application/json" },
-					credentials: "include",
-					body: JSON.stringify({ medicationIds: Array.from(medIds), until }),
-				});
-
-				if (res.ok) {
-					// Reload medications to get updated dismissedUntil values
-					await medications.loadMeds();
-					doses.setShowClearMissedConfirm(false);
-				}
-			} catch {
-				// Error - dialog stays open
-			} finally {
-				setClearingMissedState(false);
-			}
-		},
-		[medications, doses]
-	);
-
 	// Build context value
 	const value: AppContextValue = useMemo(
 		() => ({
@@ -801,6 +811,7 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
 			setSettings: settingsHook.setSettings,
 			savedSettings: settingsHook.savedSettings,
 			settingsLoading: settingsHook.settingsLoading,
+			settingsLoadError: settingsHook.settingsLoadError,
 			settingsSaving: settingsHook.settingsSaving,
 			settingsSaved: settingsHook.settingsSaved,
 			testingEmail: settingsHook.testingEmail,
@@ -816,15 +827,11 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
 			takenDoses: doses.takenDoses,
 			setTakenDoses: doses.setTakenDoses,
 			dismissedDoses: doses.dismissedDoses,
-			clearingMissed: clearingMissedState,
-			showClearMissedConfirm: doses.showClearMissedConfirm,
-			setShowClearMissedConfirm: doses.setShowClearMissedConfirm,
 			getDoseId: doses.getDoseId,
 			isDoseTakenAutomatically: doses.isDoseTakenAutomatically,
 			countTakenDoses: doses.countTakenDoses,
 			markDoseTaken: doses.markDoseTaken,
 			undoDoseTaken: doses.undoDoseTaken,
-			dismissMissedDoses,
 
 			// From useCollapsedDays
 			manuallyCollapsedDays: collapsed.manuallyCollapsedDays,
@@ -983,8 +990,6 @@ export function AppProvider({ children }: { children: React.ReactNode }) {
 			handleImportFileSelect,
 			handleImportConfirm,
 			settingsChanged,
-			clearingMissedState,
-			dismissMissedDoses,
 		]
 	);
 

frontend/src/hooks/useCollapsedDays.ts

@@ -24,6 +24,9 @@ export function useCollapsedDays(userId: number | undefined): UseCollapsedDaysRe
 			);
 			setManuallyCollapsedDays(collapsed);
 			setManuallyExpandedDays(expanded);
+		} else {
+			setManuallyCollapsedDays(new Set());
+			setManuallyExpandedDays(new Set());
 		}
 	}, [userId]);
 

frontend/src/hooks/useDoses.ts

@@ -3,6 +3,7 @@
 // =============================================================================
 
 import { useCallback, useEffect, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
 
 export interface UseDosesReturn {
 	takenDoses: Set<string>;
@@ -10,8 +11,7 @@ export interface UseDosesReturn {
 	takenDoseTimestamps: Map<string, number>;
 	takenDoseSources: Map<string, "manual" | "automatic">;
 	dismissedDoses: Set<string>;
-	showClearMissedConfirm: boolean;
-	setShowClearMissedConfirm: (show: boolean) => void;
+	clearDosesState: () => void;
 	getDoseId: (baseDoseId: string, person: string | null) => string;
 	isDoseTakenAutomatically: (doseId: string) => boolean;
 	countTakenDoses: (doses: Array<{ id: string; takenBy: string[] }>) => { total: number; taken: number };
@@ -21,15 +21,23 @@ export interface UseDosesReturn {
 }
 
 export function useDoses(): UseDosesReturn {
+	const { t } = useTranslation();
 	const [takenDoses, setTakenDoses] = useState<Set<string>>(new Set());
 	const [takenDoseTimestamps, setTakenDoseTimestamps] = useState<Map<string, number>>(new Map());
 	const [takenDoseSources, setTakenDoseSources] = useState<Map<string, "manual" | "automatic">>(new Map());
 	const [dismissedDoses, setDismissedDoses] = useState<Set<string>>(new Set());
-	const [showClearMissedConfirm, setShowClearMissedConfirm] = useState(false);
 
 	// Track in-flight mutations to prevent polling from overwriting optimistic updates
 	const mutationInFlightRef = useRef(0);
 
+	const clearDosesState = useCallback(() => {
+		setTakenDoses(new Set());
+		setTakenDoseTimestamps(new Map());
+		setTakenDoseSources(new Map());
+		setDismissedDoses(new Set());
+		mutationInFlightRef.current = 0;
+	}, []);
+
 	// Load taken doses from server
 	const loadTakenDoses = useCallback(async () => {
 		// Skip polling while mutations are in-flight to prevent race conditions
@@ -60,12 +68,15 @@ export function useDoses(): UseDosesReturn {
 				setTakenDoseTimestamps(timestamps);
 				setTakenDoseSources(sources);
 				setDismissedDoses(dismissed);
+			} else if (res.status === 401 || res.status === 403) {
+				// Prevent showing previous user's dose state after auth/session changes.
+				clearDosesState();
 			}
 			// Don't reset on error - keep current state
 		} catch {
 			// Don't reset on error - keep current state
 		}
-	}, []);
+	}, [clearDosesState]);
 
 	// Poll for taken doses from server (works with or without auth)
 	useEffect(() => {
@@ -105,6 +116,15 @@ export function useDoses(): UseDosesReturn {
 		[takenDoses, getDoseId]
 	);
 
+	const getErrorCode = useCallback(async (response: Response): Promise<string | null> => {
+		try {
+			const data = (await response.json()) as { code?: string };
+			return typeof data.code === "string" ? data.code : null;
+		} catch {
+			return null;
+		}
+	}, []);
+
 	const markDoseTaken = useCallback(
 		async (doseId: string) => {
 			// Optimistic update
@@ -127,12 +147,18 @@ export function useDoses(): UseDosesReturn {
 
 			// Send to server
 			try {
-				await fetch("/api/doses/taken", {
+				const response = await fetch("/api/doses/taken", {
 					method: "POST",
 					headers: { "Content-Type": "application/json" },
 					credentials: "include",
 					body: JSON.stringify({ doseId }),
 				});
+				if (!response.ok) {
+					if ((await getErrorCode(response)) === "OUT_OF_STOCK") {
+						alert(t("common.outOfStockTakeBlocked"));
+					}
+					throw new Error("Failed to mark dose as taken");
+				}
 			} catch {
 				// Revert on error
 				setTakenDoses((prev) => {
@@ -156,7 +182,7 @@ export function useDoses(): UseDosesReturn {
 				loadTakenDoses();
 			}
 		},
-		[loadTakenDoses]
+		[getErrorCode, loadTakenDoses, t]
 	);
 
 	const undoDoseTaken = useCallback(
@@ -207,8 +233,7 @@ export function useDoses(): UseDosesReturn {
 		takenDoseTimestamps,
 		takenDoseSources,
 		dismissedDoses,
-		showClearMissedConfirm,
-		setShowClearMissedConfirm,
+		clearDosesState,
 		getDoseId,
 		isDoseTakenAutomatically,
 		countTakenDoses,

frontend/src/hooks/useMedicationForm.ts

@@ -1,7 +1,13 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 import type { FieldErrors, FormBlister, FormIntake, FormState, Medication } from "../types";
-import { FIELD_LIMITS } from "../types";
+import {
+	FIELD_LIMITS,
+	isAmountBasedPackageType,
+	isLiquidContainerPackageType,
+	isTubePackageType,
+	normalizePackageType,
+} from "../types";
 import { toDateValue, toTimeValue } from "../utils/formatters";
 
 export const defaultBlister = (): FormBlister => {
@@ -230,18 +236,19 @@ export function useMedicationForm(): UseMedicationFormReturn {
 		const authorizedRefills = Math.max(0, med.prescriptionAuthorizedRefills ?? 0);
 		const remainingRefills = Math.min(Math.max(0, med.prescriptionRemainingRefills ?? 0), authorizedRefills);
 		const lowRefillThreshold = Math.min(Math.max(0, med.prescriptionLowRefillThreshold ?? 1), authorizedRefills);
-		const isTubeOrLiquidPackage = med.packageType === "tube" || med.packageType === "liquid_container";
+		const packageType = normalizePackageType(med.packageType);
+		const isTubeOrLiquidPackage = isTubePackageType(packageType) || isLiquidContainerPackageType(packageType);
 		let normalizedPackCount = String(med.packCount);
 		let normalizedPackageAmountValue = String(med.packageAmountValue ?? 0);
 
 		if (isTubeOrLiquidPackage) {
-			const safePackCount = med.packageType === "tube" ? 1 : Math.max(1, med.packCount || 1);
+			const safePackCount = isTubePackageType(packageType) ? 1 : Math.max(1, med.packCount || 1);
 			normalizedPackCount = String(safePackCount);
 
 			const rawPackageAmount = Number(med.packageAmountValue ?? 0);
 			const legacyKnownAmount = Math.max(0, Number(med.totalPills ?? 0), Number(med.looseTablets ?? 0));
 
-			if (med.packageType === "tube") {
+			if (isTubePackageType(packageType)) {
 				normalizedPackageAmountValue = String(
 					legacyKnownAmount > 0 ? legacyKnownAmount : Math.max(1, rawPackageAmount)
 				);
@@ -256,16 +263,12 @@ export function useMedicationForm(): UseMedicationFormReturn {
 			? Math.max(0, (Number(normalizedPackCount) || 0) * (Number(normalizedPackageAmountValue) || 0))
 			: null;
 
-		const bottleTotalPills =
-			(med.packageType === "bottle" || med.packageType === "tube" || med.packageType === "liquid_container") &&
-			med.looseTablets
-				? String(med.looseTablets)
-				: "";
+		const bottleTotalPills = isAmountBasedPackageType(packageType) && med.looseTablets ? String(med.looseTablets) : "";
 		let resolvedForm = med.medicationForm;
 		if (!resolvedForm) {
-			if (med.packageType === "tube") {
+			if (isTubePackageType(packageType)) {
 				resolvedForm = "topical";
-			} else if (med.packageType === "liquid_container") {
+			} else if (isLiquidContainerPackageType(packageType)) {
 				resolvedForm = "liquid";
 			} else {
 				resolvedForm = med.pillForm ?? "tablet";
@@ -273,9 +276,9 @@ export function useMedicationForm(): UseMedicationFormReturn {
 		}
 		const resolvedPillForm = med.pillForm ?? (resolvedForm === "capsule" ? "capsule" : "tablet");
 		let normalizedPackageAmountUnit = med.packageAmountUnit ?? "ml";
-		if (med.packageType === "tube") {
+		if (isTubePackageType(packageType)) {
 			normalizedPackageAmountUnit = "g";
-		} else if (med.packageType === "liquid_container") {
+		} else if (isLiquidContainerPackageType(packageType)) {
 			normalizedPackageAmountUnit = "ml";
 		}
 		let resolvedTotalPills = bottleTotalPills;
@@ -291,7 +294,7 @@ export function useMedicationForm(): UseMedicationFormReturn {
 			medicationForm: resolvedForm,
 			pillForm: resolvedPillForm,
 			lifecycleCategory: med.lifecycleCategory ?? "refill_when_empty",
-			packageType: med.packageType ?? "blister",
+			packageType,
 			packCount: normalizedPackCount,
 			blistersPerPack: String(med.blistersPerPack),
 			pillsPerBlister: String(med.pillsPerBlister),
@@ -347,14 +350,15 @@ export function useMedicationForm(): UseMedicationFormReturn {
 				const next = { ...prev, [key]: value } as FormState;
 
 				if (key === "packageType") {
-					if (value === "tube") {
+					const nextPackageType = value as FormState["packageType"];
+					if (isTubePackageType(nextPackageType)) {
 						next.packCount = "1";
 						next.packageAmountValue = String(Math.max(1, Number(next.packageAmountValue) || 0));
 						next.medicationForm = "topical";
 						next.lifecycleCategory = "treatment_period";
 						next.doseUnit = "units";
 						next.packageAmountUnit = "g";
-					} else if (value === "liquid_container") {
+					} else if (isLiquidContainerPackageType(nextPackageType)) {
 						next.packCount = String(Math.max(1, Number(next.packCount) || 1));
 						next.packageAmountValue = String(Math.max(1, Number(next.packageAmountValue) || 0));
 						next.medicationForm = "liquid";
@@ -369,12 +373,12 @@ export function useMedicationForm(): UseMedicationFormReturn {
 				}
 
 				if (key === "medicationForm") {
-					if (next.packageType === "tube") {
+					if (isTubePackageType(next.packageType)) {
 						next.medicationForm = "topical";
 						next.lifecycleCategory = "treatment_period";
 						next.doseUnit = "units";
 						next.packageAmountUnit = "g";
-					} else if (next.packageType === "liquid_container") {
+					} else if (isLiquidContainerPackageType(next.packageType)) {
 						next.medicationForm = "liquid";
 						next.lifecycleCategory = "refill_when_empty";
 						next.doseUnit = "ml";
@@ -383,10 +387,10 @@ export function useMedicationForm(): UseMedicationFormReturn {
 					}
 				}
 
-				if (next.packageType === "tube") {
+				if (isTubePackageType(next.packageType)) {
 					next.packCount = "1";
 					next.packageAmountUnit = "g";
-				} else if (next.packageType === "liquid_container") {
+				} else if (isLiquidContainerPackageType(next.packageType)) {
 					next.packageAmountUnit = "ml";
 				}
 

frontend/src/hooks/useMedications.ts

@@ -8,6 +8,7 @@ export interface UseMedicationsReturn {
 	saving: boolean;
 	setSaving: React.Dispatch<React.SetStateAction<boolean>>;
 	uploadingImage: boolean;
+	clearMedicationsState: () => void;
 	loadMeds: () => void;
 	deleteMed: (id: number, editingId: number | null, resetForm: () => void) => Promise<void>;
 	uploadMedImage: (medId: number, file: File) => Promise<void>;
@@ -20,6 +21,13 @@ export function useMedications(): UseMedicationsReturn {
 	const [saving, setSaving] = useState(false);
 	const [uploadingImage, setUploadingImage] = useState(false);
 
+	const clearMedicationsState = useCallback(() => {
+		setMeds([]);
+		setLoading(false);
+		setSaving(false);
+		setUploadingImage(false);
+	}, []);
+
 	const loadMeds = useCallback(() => {
 		setLoading(true);
 		fetch("/api/medications?includeObsolete=true", { credentials: "include" })
@@ -96,6 +104,7 @@ export function useMedications(): UseMedicationsReturn {
 		saving,
 		setSaving,
 		uploadingImage,
+		clearMedicationsState,
 		loadMeds,
 		deleteMed,
 		uploadMedImage,

frontend/src/hooks/useRefill.ts

@@ -1,6 +1,12 @@
 import { useCallback, useEffect, useState } from "react";
 import type { Coverage, FormState, Medication, RefillEntry } from "../types";
-import { getMedTotal, getPackageSize } from "../types";
+import {
+	getMedTotal,
+	getPackageSize,
+	isAmountBasedPackageType,
+	isLiquidContainerPackageType,
+	isTubePackageType,
+} from "../types";
 
 export interface UseRefillReturn {
 	// Refill state
@@ -30,6 +36,7 @@ export interface UseRefillReturn {
 	editStockMedication: Medication | null;
 
 	// Actions
+	clearRefillState: () => void;
 	loadRefillHistory: (medId: number) => Promise<void>;
 	submitRefill: (
 		medId: number,
@@ -63,6 +70,22 @@ export function useRefill(): UseRefillReturn {
 	const [editStockSaving, setEditStockSaving] = useState(false);
 	const [editStockMedication, setEditStockMedication] = useState<Medication | null>(null);
 
+	const clearRefillState = useCallback(() => {
+		setShowRefillModal(false);
+		setRefillPacks(1);
+		setRefillLoose(0);
+		setUsePrescriptionRefill(false);
+		setRefillSaving(false);
+		setRefillHistory([]);
+		setRefillHistoryExpanded(false);
+		setShowEditStockModal(false);
+		setEditStockFullBlisters(0);
+		setEditStockPartialBlisterPills(0);
+		setEditStockLoosePills(0);
+		setEditStockSaving(false);
+		setEditStockMedication(null);
+	}, []);
+
 	// Load refill history for a medication
 	const loadRefillHistory = useCallback(async (medId: number) => {
 		try {
@@ -137,10 +160,9 @@ export function useRefill(): UseRefillReturn {
 			if (!selectedMed) return;
 			setEditStockSaving(true);
 			try {
-				const isTubePackage = selectedMed.packageType === "tube";
-				const isBottlePackage = selectedMed.packageType === "bottle";
-				const isLiquidPackage = selectedMed.packageType === "liquid_container";
-				const isAmountPackage = isBottlePackage || isTubePackage || isLiquidPackage;
+				const isTubePackage = isTubePackageType(selectedMed.packageType);
+				const isLiquidPackage = isLiquidContainerPackageType(selectedMed.packageType);
+				const isAmountPackage = isAmountBasedPackageType(selectedMed.packageType);
 				const liquidAmountPerBottle = Math.max(
 					1,
 					Number.isFinite(Number(selectedMed.packageAmountValue)) && Number(selectedMed.packageAmountValue) > 0
@@ -268,10 +290,7 @@ export function useRefill(): UseRefillReturn {
 	const openEditStockModal = useCallback((selectedMed: Medication, coverage: { all: Coverage[] }) => {
 		if (!selectedMed) return;
 		setEditStockMedication(selectedMed);
-		const isAmountPackage =
-			selectedMed.packageType === "bottle" ||
-			selectedMed.packageType === "tube" ||
-			selectedMed.packageType === "liquid_container";
+		const isAmountPackage = isAmountBasedPackageType(selectedMed.packageType);
 		// Get current stock from coverage (after consumption)
 		const medCoverage = coverage.all.find((c) => c.name === selectedMed.name);
 		const dbTotal = getMedTotal(selectedMed);
@@ -282,7 +301,7 @@ export function useRefill(): UseRefillReturn {
 		const knownLoose = Math.min(currentStock, Math.max(0, selectedMed.looseTablets));
 		const sealedPills = Math.max(0, currentStock - knownLoose);
 		let fullBlisters: number;
-		if (selectedMed.packageType === "liquid_container") {
+		if (isLiquidContainerPackageType(selectedMed.packageType)) {
 			fullBlisters = Math.max(1, selectedMed.packCount);
 		} else if (isAmountPackage) {
 			fullBlisters = 0;
@@ -325,6 +344,7 @@ export function useRefill(): UseRefillReturn {
 	}, [showEditStockModal]);
 
 	return {
+		clearRefillState,
 		showRefillModal,
 		setShowRefillModal,
 		refillPacks,

frontend/src/hooks/useSettings.ts

@@ -4,6 +4,7 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
+import { log } from "../utils/logger";
 
 export interface Settings {
 	emailEnabled: boolean;
@@ -46,12 +47,17 @@ export interface Settings {
 	shoutrrrPrescriptionReminders: boolean;
 	stockCalculationMode: "automatic" | "manual";
 	shareStockStatus: boolean;
+	shareMedicationOverview: boolean;
 	upcomingTodayOnly: boolean;
 	shareScheduleTodayOnly: boolean;
 	swapDashboardMainSections: boolean;
+	reminderHour: number;
+	reminderMinutesBefore: number;
 	expiryWarningDays: number;
 }
 
+export type SettingsLoadError = "auth" | "forbidden" | "request" | null;
+
 const defaultSettings: Settings = {
 	emailEnabled: false,
 	notificationEmail: "",
@@ -93,9 +99,12 @@ const defaultSettings: Settings = {
 	shoutrrrPrescriptionReminders: true,
 	stockCalculationMode: "automatic",
 	shareStockStatus: true,
+	shareMedicationOverview: false,
 	upcomingTodayOnly: false,
 	shareScheduleTodayOnly: false,
 	swapDashboardMainSections: false,
+	reminderHour: 6,
+	reminderMinutesBefore: 15,
 	expiryWarningDays: 30,
 };
 
@@ -104,6 +113,7 @@ export interface UseSettingsReturn {
 	setSettings: React.Dispatch<React.SetStateAction<Settings>>;
 	savedSettings: Settings;
 	settingsLoading: boolean;
+	settingsLoadError: SettingsLoadError;
 	settingsSaving: boolean;
 	settingsSaved: boolean;
 	testingEmail: boolean;
@@ -117,6 +127,7 @@ export interface UseSettingsReturn {
 	testEmail: () => Promise<void>;
 	testShoutrrr: () => Promise<void>;
 	hasUnsavedChanges: boolean;
+	resetSettingsState: () => void;
 }
 
 export function useSettings(): UseSettingsReturn {
@@ -124,6 +135,7 @@ export function useSettings(): UseSettingsReturn {
 	const [settings, setSettings] = useState<Settings>(defaultSettings);
 	const [savedSettings, setSavedSettings] = useState<Settings>(defaultSettings);
 	const [settingsLoading, setSettingsLoading] = useState(false);
+	const [settingsLoadError, setSettingsLoadError] = useState<SettingsLoadError>(null);
 	const [settingsSaving, setSettingsSaving] = useState(false);
 	const [settingsSaved, setSettingsSaved] = useState(false);
 	const [testingEmail, setTestingEmail] = useState(false);
@@ -131,88 +143,105 @@ export function useSettings(): UseSettingsReturn {
 	const [testingShoutrrr, setTestingShoutrrr] = useState(false);
 	const [testShoutrrrResult, setTestShoutrrrResult] = useState<{ success: boolean; message: string } | null>(null);
 
-	// Load settings function - exposed for manual refresh (e.g., after auth)
-	const loadSettings = useCallback(() => {
-		setSettingsLoading(true);
-		fetch("/api/settings", { credentials: "include" })
-			.then((res) => (res.ok ? res.json() : Promise.reject()))
-			.then((data) => {
-				const newSettings = { ...defaultSettings, ...data, smtpPass: "" };
-				setSettings(newSettings);
-				setSavedSettings(newSettings);
-				setSettingsSaved(false);
-			})
-			.catch(() => {})
-			.finally(() => setSettingsLoading(false));
+	// Generation counter: incremented on every resetSettingsState call.
+	// loadSettings captures the current generation; if it changes before
+	// the fetch completes, the stale response is silently discarded.
+	const loadGenerationRef = useRef(0);
+	const latestSettingsRef = useRef(settings);
+	const latestSavedSettingsRef = useRef(savedSettings);
+
+	useEffect(() => {
+		latestSettingsRef.current = settings;
+	}, [settings]);
+
+	useEffect(() => {
+		latestSavedSettingsRef.current = savedSettings;
+	}, [savedSettings]);
+
+	const resetSettingsState = useCallback(() => {
+		loadGenerationRef.current += 1; // Invalidate any in-flight loadSettings
+		setSettings(defaultSettings);
+		setSavedSettings(defaultSettings);
+		setSettingsLoading(false);
+		setSettingsLoadError(null);
+		setSettingsSaving(false);
+		setSettingsSaved(false);
+		setTestingEmail(false);
+		setTestEmailResult(null);
+		setTestingShoutrrr(false);
+		setTestShoutrrrResult(null);
 	}, []);
 
-	// Load settings on mount
-	useEffect(() => {
-		loadSettings();
-	}, [loadSettings]);
+	const clearReminderMetadata = useCallback(() => {
+		setSettings((prev) => ({
+			...prev,
+			lastAutoEmailSent: null,
+			lastNotificationType: null,
+			lastNotificationChannel: null,
+			lastReminderMedName: null,
+			lastReminderTakenBy: null,
+			lastStockReminderSent: null,
+			lastStockReminderChannel: null,
+			lastStockReminderMedNames: null,
+			lastPrescriptionReminderSent: null,
+			lastPrescriptionReminderChannel: null,
+			lastPrescriptionReminderMedNames: null,
+		}));
+		setSavedSettings((prev) => ({
+			...prev,
+			lastAutoEmailSent: null,
+			lastNotificationType: null,
+			lastNotificationChannel: null,
+			lastReminderMedName: null,
+			lastReminderTakenBy: null,
+			lastStockReminderSent: null,
+			lastStockReminderChannel: null,
+			lastStockReminderMedNames: null,
+			lastPrescriptionReminderSent: null,
+			lastPrescriptionReminderChannel: null,
+			lastPrescriptionReminderMedNames: null,
+		}));
+	}, []);
 
-	// Auto-refresh reminder status (last sent timestamp) every 30 seconds
-	useEffect(() => {
-		const refreshReminderStatus = () => {
-			fetch("/api/settings", { credentials: "include" })
-				.then((res) => (res.ok ? res.json() : Promise.reject()))
-				.then((data) => {
-					// Only update the reminder-related fields without triggering unsaved changes
-					setSettings((prev) => ({
-						...prev,
-						lastAutoEmailSent: data.lastAutoEmailSent ?? prev.lastAutoEmailSent,
-						lastNotificationType: data.lastNotificationType ?? prev.lastNotificationType,
-						lastNotificationChannel: data.lastNotificationChannel ?? prev.lastNotificationChannel,
-						lastReminderMedName: data.lastReminderMedName ?? prev.lastReminderMedName,
-						lastReminderTakenBy: data.lastReminderTakenBy ?? prev.lastReminderTakenBy,
-						lastStockReminderSent: data.lastStockReminderSent ?? prev.lastStockReminderSent,
-						lastStockReminderChannel: data.lastStockReminderChannel ?? prev.lastStockReminderChannel,
-						lastStockReminderMedNames: data.lastStockReminderMedNames ?? prev.lastStockReminderMedNames,
-						lastPrescriptionReminderSent: data.lastPrescriptionReminderSent ?? prev.lastPrescriptionReminderSent,
-						lastPrescriptionReminderChannel:
-							data.lastPrescriptionReminderChannel ?? prev.lastPrescriptionReminderChannel,
-						lastPrescriptionReminderMedNames:
-							data.lastPrescriptionReminderMedNames ?? prev.lastPrescriptionReminderMedNames,
-					}));
-					setSavedSettings((prev) => ({
-						...prev,
-						lastAutoEmailSent: data.lastAutoEmailSent ?? prev.lastAutoEmailSent,
-						lastNotificationType: data.lastNotificationType ?? prev.lastNotificationType,
-						lastNotificationChannel: data.lastNotificationChannel ?? prev.lastNotificationChannel,
-						lastReminderMedName: data.lastReminderMedName ?? prev.lastReminderMedName,
-						lastReminderTakenBy: data.lastReminderTakenBy ?? prev.lastReminderTakenBy,
-						lastStockReminderSent: data.lastStockReminderSent ?? prev.lastStockReminderSent,
-						lastStockReminderChannel: data.lastStockReminderChannel ?? prev.lastStockReminderChannel,
-						lastStockReminderMedNames: data.lastStockReminderMedNames ?? prev.lastStockReminderMedNames,
-						lastPrescriptionReminderSent: data.lastPrescriptionReminderSent ?? prev.lastPrescriptionReminderSent,
-						lastPrescriptionReminderChannel:
-							data.lastPrescriptionReminderChannel ?? prev.lastPrescriptionReminderChannel,
-						lastPrescriptionReminderMedNames:
-							data.lastPrescriptionReminderMedNames ?? prev.lastPrescriptionReminderMedNames,
-					}));
-				})
-				.catch(() => {});
+	const fetchWithRefresh = useCallback(async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+		const requestInit: RequestInit = {
+			credentials: "include",
+			...init,
 		};
 
-		const interval = setInterval(refreshReminderStatus, 30000);
-		return () => clearInterval(interval);
+		let response = await fetch(input, requestInit);
+		if (response.status !== 401) {
+			return response;
+		}
+
+		const refreshResponse = await fetch("/api/auth/refresh", {
+			method: "POST",
+			credentials: "include",
+		});
+		if (!refreshResponse.ok) {
+			return response;
+		}
+
+		response = await fetch(input, requestInit);
+		return response;
 	}, []);
 
-	// Internal save function (no event needed)
-	const performSave = useCallback(
-		async (settingsToSave: Settings) => {
-			// Auto-disable email if no recipient is set
+	const buildSettingsPayload = useCallback(
+		(settingsToSave: Settings) => {
 			const effectiveEmailEnabled = settingsToSave.emailEnabled && !!settingsToSave.notificationEmail?.trim();
-			// Auto-disable push if no URL is set
 			const effectiveShoutrrrEnabled = settingsToSave.shoutrrrEnabled && !!settingsToSave.shoutrrrUrl?.trim();
+			const hasEmailStock =
+				effectiveEmailEnabled && settingsToSave.emailStockReminders && !!settingsToSave.notificationEmail?.trim();
+			const hasShoutrrrStock =
+				effectiveShoutrrrEnabled && settingsToSave.shoutrrrStockReminders && !!settingsToSave.shoutrrrUrl?.trim();
+			const hasAnyStockReminder = hasEmailStock || hasShoutrrrStock;
+			const repeatDailyReminders = hasAnyStockReminder ? settingsToSave.repeatDailyReminders : false;
 
-			setSettingsSaving(true);
-
-			const payload = {
+			return {
 				emailEnabled: effectiveEmailEnabled,
 				notificationEmail: settingsToSave.notificationEmail,
 				reminderDaysBefore: settingsToSave.reminderDaysBefore,
-				repeatDailyReminders: settingsToSave.repeatDailyReminders,
+				repeatDailyReminders,
 				skipRemindersForTakenDoses: settingsToSave.skipRemindersForTakenDoses,
 				repeatRemindersEnabled: settingsToSave.repeatRemindersEnabled,
 				reminderRepeatIntervalMinutes: settingsToSave.reminderRepeatIntervalMinutes,
@@ -230,6 +259,7 @@ export function useSettings(): UseSettingsReturn {
 				shoutrrrPrescriptionReminders: settingsToSave.shoutrrrPrescriptionReminders,
 				stockCalculationMode: settingsToSave.stockCalculationMode,
 				shareStockStatus: settingsToSave.shareStockStatus,
+				shareMedicationOverview: settingsToSave.shareMedicationOverview,
 				upcomingTodayOnly: settingsToSave.upcomingTodayOnly,
 				shareScheduleTodayOnly: settingsToSave.shareScheduleTodayOnly,
 				swapDashboardMainSections: settingsToSave.swapDashboardMainSections,
@@ -241,21 +271,182 @@ export function useSettings(): UseSettingsReturn {
 				smtpFrom: settingsToSave.smtpFrom,
 				smtpSecure: settingsToSave.smtpSecure,
 			};
+		},
+		[i18n.language]
+	);
 
-			await fetch("/api/settings", {
+	const flushSettingsWithKeepalive = useCallback(
+		(settingsToSave: Settings) => {
+			const payload = buildSettingsPayload(settingsToSave);
+			void fetch("/api/settings", {
 				method: "PUT",
 				headers: { "Content-Type": "application/json" },
 				credentials: "include",
+				keepalive: true,
 				body: JSON.stringify(payload),
-			}).catch(() => null);
-
-			const updatedSettings = { ...settingsToSave };
-			setSettings(updatedSettings);
-			setSettingsSaving(false);
-			setSavedSettings(updatedSettings);
-			setSettingsSaved(true);
+			}).catch(() => {});
 		},
-		[i18n.language]
+		[buildSettingsPayload]
+	);
+
+	// Load settings function - exposed for manual refresh (e.g., after auth)
+	const loadSettings = useCallback(() => {
+		setSettingsLoading(true);
+		const generation = loadGenerationRef.current;
+		fetchWithRefresh("/api/settings")
+			.then((res) => {
+				// Discard result if a newer loadSettings call (or resetSettingsState) has fired
+				if (loadGenerationRef.current !== generation) return Promise.reject("stale");
+				if (!res.ok) {
+					log.warn("[useSettings] loadSettings failed", { status: res.status });
+					if (res.status === 401 || res.status === 403) {
+						resetSettingsState();
+					}
+					return Promise.reject({ status: res.status });
+				}
+				return res.json();
+			})
+			.then((data) => {
+				if (!data || loadGenerationRef.current !== generation) return;
+				log.debug("[useSettings] settings loaded", { smtpConfigured: !!data.smtpHost });
+				const newSettings = { ...defaultSettings, ...data, smtpPass: "" };
+				setSettings(newSettings);
+				setSavedSettings(newSettings);
+				setSettingsLoadError(null);
+				setSettingsSaved(false);
+			})
+			.catch((error: unknown) => {
+				if (error === "stale") return;
+				const status =
+					typeof error === "object" && error !== null && "status" in error ? (error.status as number) : undefined;
+				if (status === 401) {
+					setSettingsLoadError("auth");
+					return;
+				}
+				if (status === 403) {
+					setSettingsLoadError("forbidden");
+					return;
+				}
+				setSettingsLoadError("request");
+			})
+			.finally(() => {
+				if (loadGenerationRef.current === generation) setSettingsLoading(false);
+			});
+	}, [fetchWithRefresh, resetSettingsState]);
+
+	// Load settings on mount
+	useEffect(() => {
+		loadSettings();
+	}, [loadSettings]);
+
+	// Auto-refresh reminder status (last sent timestamp) every 30 seconds
+	useEffect(() => {
+		const refreshReminderStatus = () => {
+			fetchWithRefresh("/api/settings")
+				.then((res) => {
+					if (!res.ok) {
+						if (res.status === 401 || res.status === 403) {
+							clearReminderMetadata();
+						}
+						return Promise.reject();
+					}
+					return res.json();
+				})
+				.then((data) => {
+					const pick = <T>(key: string, fallback: T): T => (Object.hasOwn(data, key) ? (data[key] as T) : fallback);
+
+					// Only update the reminder-related fields without triggering unsaved changes
+					setSettings((prev) => ({
+						...prev,
+						lastAutoEmailSent: pick("lastAutoEmailSent", prev.lastAutoEmailSent),
+						lastNotificationType: pick("lastNotificationType", prev.lastNotificationType),
+						lastNotificationChannel: pick("lastNotificationChannel", prev.lastNotificationChannel),
+						lastReminderMedName: pick("lastReminderMedName", prev.lastReminderMedName),
+						lastReminderTakenBy: pick("lastReminderTakenBy", prev.lastReminderTakenBy),
+						lastStockReminderSent: pick("lastStockReminderSent", prev.lastStockReminderSent),
+						lastStockReminderChannel: pick("lastStockReminderChannel", prev.lastStockReminderChannel),
+						lastStockReminderMedNames: pick("lastStockReminderMedNames", prev.lastStockReminderMedNames),
+						lastPrescriptionReminderSent: pick("lastPrescriptionReminderSent", prev.lastPrescriptionReminderSent),
+						lastPrescriptionReminderChannel: pick(
+							"lastPrescriptionReminderChannel",
+							prev.lastPrescriptionReminderChannel
+						),
+						lastPrescriptionReminderMedNames: pick(
+							"lastPrescriptionReminderMedNames",
+							prev.lastPrescriptionReminderMedNames
+						),
+					}));
+					setSavedSettings((prev) => ({
+						...prev,
+						lastAutoEmailSent: pick("lastAutoEmailSent", prev.lastAutoEmailSent),
+						lastNotificationType: pick("lastNotificationType", prev.lastNotificationType),
+						lastNotificationChannel: pick("lastNotificationChannel", prev.lastNotificationChannel),
+						lastReminderMedName: pick("lastReminderMedName", prev.lastReminderMedName),
+						lastReminderTakenBy: pick("lastReminderTakenBy", prev.lastReminderTakenBy),
+						lastStockReminderSent: pick("lastStockReminderSent", prev.lastStockReminderSent),
+						lastStockReminderChannel: pick("lastStockReminderChannel", prev.lastStockReminderChannel),
+						lastStockReminderMedNames: pick("lastStockReminderMedNames", prev.lastStockReminderMedNames),
+						lastPrescriptionReminderSent: pick("lastPrescriptionReminderSent", prev.lastPrescriptionReminderSent),
+						lastPrescriptionReminderChannel: pick(
+							"lastPrescriptionReminderChannel",
+							prev.lastPrescriptionReminderChannel
+						),
+						lastPrescriptionReminderMedNames: pick(
+							"lastPrescriptionReminderMedNames",
+							prev.lastPrescriptionReminderMedNames
+						),
+					}));
+				})
+				.catch(() => {});
+		};
+
+		const interval = setInterval(refreshReminderStatus, 30000);
+		return () => clearInterval(interval);
+	}, [clearReminderMetadata, fetchWithRefresh]);
+
+	// Internal save function (no event needed)
+	const performSave = useCallback(
+		async (settingsToSave: Settings, options?: { syncState?: boolean }) => {
+			const syncState = options?.syncState ?? true;
+			const payload = buildSettingsPayload(settingsToSave);
+
+			if (syncState) {
+				setSettingsSaving(true);
+			}
+
+			try {
+				const response = await fetchWithRefresh("/api/settings", {
+					method: "PUT",
+					headers: { "Content-Type": "application/json" },
+					keepalive: true,
+					body: JSON.stringify(payload),
+				});
+
+				if (!response.ok) {
+					throw new Error(`SETTINGS_SAVE_FAILED_${response.status}`);
+				}
+
+				if (syncState) {
+					const updatedSettings = { ...settingsToSave };
+					setSettings(updatedSettings);
+					setSavedSettings(updatedSettings);
+					setSettingsSaved(true);
+				} else {
+					latestSavedSettingsRef.current = { ...settingsToSave };
+				}
+			} catch {
+				if (syncState) {
+					setSettingsSaved(false);
+					// Keep UI aligned with backend truth if save failed (auth/session/network/server error).
+					loadSettings();
+				}
+			} finally {
+				if (syncState) {
+					setSettingsSaving(false);
+				}
+			}
+		},
+		[buildSettingsPayload, fetchWithRefresh, loadSettings]
 	);
 
 	// Debounced auto-save: fires whenever settings change
@@ -283,8 +474,8 @@ export function useSettings(): UseSettingsReturn {
 		}
 
 		debounceRef.current = setTimeout(() => {
-			performSave(settings);
-		}, 600);
+			void performSave(settings);
+		}, 50);
 
 		return () => {
 			if (debounceRef.current) {
@@ -293,6 +484,32 @@ export function useSettings(): UseSettingsReturn {
 		};
 	}, [settings, savedSettings, performSave]);
 
+	useEffect(() => {
+		const flushPendingSettings = () => {
+			if (JSON.stringify(latestSettingsRef.current) === JSON.stringify(latestSavedSettingsRef.current)) {
+				return;
+			}
+
+			flushSettingsWithKeepalive(latestSettingsRef.current);
+		};
+
+		window.addEventListener("pagehide", flushPendingSettings);
+
+		return () => {
+			window.removeEventListener("pagehide", flushPendingSettings);
+
+			if (debounceRef.current) {
+				clearTimeout(debounceRef.current);
+			}
+
+			if (JSON.stringify(latestSettingsRef.current) === JSON.stringify(latestSavedSettingsRef.current)) {
+				return;
+			}
+
+			flushSettingsWithKeepalive(latestSettingsRef.current);
+		};
+	}, [flushSettingsWithKeepalive]);
+
 	// Mark initial load as done after first settings load completes
 	useEffect(() => {
 		if (!settingsLoading && !initialLoadDone.current) {
@@ -317,10 +534,9 @@ export function useSettings(): UseSettingsReturn {
 		setTestingEmail(true);
 		setTestEmailResult(null);
 		try {
-			const res = await fetch("/api/settings/test-email", {
+			const res = await fetchWithRefresh("/api/settings/test-email", {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
-				credentials: "include",
 				body: JSON.stringify({ email: settings.notificationEmail }),
 			});
 			const data = await res.json();
@@ -333,16 +549,15 @@ export function useSettings(): UseSettingsReturn {
 		} finally {
 			setTestingEmail(false);
 		}
-	}, [settings.notificationEmail]);
+	}, [fetchWithRefresh, settings.notificationEmail]);
 
 	const testShoutrrr = useCallback(async () => {
 		setTestingShoutrrr(true);
 		setTestShoutrrrResult(null);
 		try {
-			const res = await fetch("/api/settings/test-shoutrrr", {
+			const res = await fetchWithRefresh("/api/settings/test-shoutrrr", {
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
-				credentials: "include",
 				body: JSON.stringify({ url: settings.shoutrrrUrl }),
 			});
 			const data = await res.json();
@@ -355,7 +570,7 @@ export function useSettings(): UseSettingsReturn {
 		} finally {
 			setTestingShoutrrr(false);
 		}
-	}, [settings.shoutrrrUrl]);
+	}, [fetchWithRefresh, settings.shoutrrrUrl]);
 
 	// Check for unsaved changes
 	const hasUnsavedChanges = JSON.stringify(settings) !== JSON.stringify(savedSettings);
@@ -365,6 +580,7 @@ export function useSettings(): UseSettingsReturn {
 		setSettings,
 		savedSettings,
 		settingsLoading,
+		settingsLoadError,
 		settingsSaving,
 		settingsSaved,
 		testingEmail,
@@ -378,5 +594,6 @@ export function useSettings(): UseSettingsReturn {
 		testEmail,
 		testShoutrrr,
 		hasUnsavedChanges,
+		resetSettingsState,
 	};
 }

frontend/src/hooks/useShare.ts

@@ -7,6 +7,8 @@ import type { Medication } from "../types";
 import { withCorrelation } from "../utils/correlation";
 import { log } from "../utils/logger";
 
+const SHARE_ALL_VALUE = "all";
+
 export interface UseShareReturn {
 	showShareDialog: boolean;
 	sharePeople: string[];
@@ -43,10 +45,20 @@ export function useShare(): UseShareReturn {
 		setShareSelectedPerson("");
 		setShareSelectedDays(30);
 
-		// Get unique takenBy people from all medications (flatten arrays)
-		const allPeople = meds.flatMap((m) => m.takenBy || []);
-		const uniquePeople = [...new Set(allPeople)].filter(Boolean).sort();
-		setSharePeople(uniquePeople);
+		// Include both per-intake assignments and legacy medication-level assignments.
+		const uniquePeople = [
+			...new Set(
+				meds.flatMap((medication) => [
+					...(medication.intakes
+						?.map((intake) => intake.takenBy)
+						.filter((person): person is string => Boolean(person)) ?? []),
+					...(medication.takenBy || []),
+				])
+			),
+		]
+			.filter(Boolean)
+			.sort();
+		setSharePeople(uniquePeople.length > 0 ? [SHARE_ALL_VALUE, ...uniquePeople] : []);
 		log.info("[ShareDialog] Opened", { medicationCount: meds.length, personCount: uniquePeople.length });
 		if (uniquePeople.length > 0) {
 			setShareSelectedPerson(uniquePeople[0]);

frontend/src/i18n/de.json

@@ -292,6 +292,18 @@
       "title": "Sprache",
       "select": "Sprache auswählen"
     },
+    "apiKey": {
+      "title": "API-Zugriff",
+      "generateTitle": "API-Key erzeugen",
+      "generateDesc": "Erstellt einen neuen API-Key mit Schreibrechten. Der vorherige Key wird automatisch ungültig.",
+      "generateButton": "Key erzeugen",
+      "generating": "Wird erzeugt...",
+      "currentToken": "Neuer API-Key",
+      "copyButton": "Kopieren",
+      "copied": "Kopiert",
+      "copyHint": "Diesen Key jetzt kopieren. Er wird nur einmal angezeigt und kann später nicht erneut abgerufen werden.",
+      "generateError": "API-Key konnte nicht erzeugt werden"
+    },
     "notifications": {
       "title": "Benachrichtigungen",
       "channels": "Kanäle",
@@ -312,7 +324,11 @@
     },
     "email": {
       "recipient": "Empfänger",
-      "notConfigured": "Nicht konfiguriert"
+        "notConfigured": "Nicht konfiguriert",
+        "serverNotConfigured": "E-Mail-Benachrichtigungen bleiben deaktiviert, bis SMTP im Backend konfiguriert ist.",
+        "loadErrorAuth": "Die E-Mail-Einstellungen konnten nicht geladen werden, weil deine Sitzung nicht mehr gültig ist. Bitte melde dich erneut an.",
+        "loadErrorForbidden": "Die E-Mail-Einstellungen konnten nicht geladen werden, weil diese Sitzung sie nicht lesen darf.",
+        "loadErrorGeneric": "Die Verfügbarkeit von E-Mail konnte nicht geprüft werden, weil das Laden der Einstellungen fehlgeschlagen ist."
     },
     "push": {
       "url": "URL",
@@ -323,9 +339,9 @@
     "schedule": {
       "title": "Erinnerungsplan",
       "stockCheck": "Bestands- & Rezeptprüfung",
-      "dailyAt6": "Täglich um 6:00 Uhr",
+      "dailyAtHour": "Täglich um {{hour}}:00 Uhr",
       "intakeCheck": "Einnahmeprüfung",
-      "15minBefore": "15 Min. vor geplanter Zeit",
+      "minutesBefore": "{{minutes}} Min. vor geplanter Zeit",
       "nextCheck": "Nächste Bestandsprüfung",
       "lastSent": "Letzte Benachrichtigung",
       "lastStockSent": "Letzte Bestands-Erinnerung",
@@ -348,8 +364,6 @@
       "highStockDays": "Hoch (Tage)",
       "highStockTooltip": "Bestand über diesem Wert bedeutet, dass du gut versorgt bist",
       "thresholdValidation": "Werte müssen wie folgt sein: Kritisch < Niedrig < Hoch",
-      "shareStockStatus": "Bestand auf geteilten Links anzeigen",
-      "shareStockStatusDesc": "Bestandsstatus (Normal/Niedrig/Kritisch) und farbige Rahmen auf geteilten Zeitplan-Links für Einnahme-Nutzer anzeigen",
       "packageTypesNote": "Hinweis: Tubenmedikamente sind von Bestands-Erinnerungen ausgeschlossen. Flüssigbehälter-Medikamente verwenden einen einzelnen Reminder-Basiswert (Niedrig und Kritisch werden automatisch von diesem Wert abgeleitet)."
     },
     "timeline": {
@@ -361,6 +375,8 @@
       "swapDashboardSections": "Bevorstehenden Zeitplan vor Medikamentenübersicht anzeigen",
       "swapDashboardSectionsDesc": "Wenn aktiviert, wird der Bereich mit bevorstehenden Einnahmen über der Medikamentenübersicht angezeigt.",
       "sharedSection": "Geteilter Zeitplan",
+      "shareMedicationOverview": "Medikamentenübersicht auf geteilten Links anzeigen",
+      "shareMedicationOverviewDesc": "Die Medikamentenübersicht im normalen geteilten Zeitplan für Einnahme-Nutzer einbetten.",
       "shareScheduleTodayOnly": "Geteilte Links zeigen nur heute",
       "shareScheduleTodayOnlyDesc": "Vergangene und zukünftige Tage in geteilten Zeitplänen ausblenden und nur heutige Einträge zeigen."
     },
@@ -481,6 +497,7 @@
     "saveFailed": "Speichern fehlgeschlagen",
     "networkError": "Netzwerkfehler",
     "saving": "Wird gespeichert...",
+    "outOfStockTakeBlocked": "Dieses Medikament ist leer. Die Einnahme kann nicht als eingenommen markiert werden.",
     "unsavedChanges": {
       "title": "Ungespeicherte Änderungen",
       "message": "Du hast ungespeicherte Änderungen. Möchtest du die Seite wirklich verlassen?",
@@ -535,13 +552,17 @@
     "button": "Teilen",
     "title": "Zeitplan teilen",
     "description": "Generiere einen geheimen Link, um den Medikamentenplan für eine bestimmte Person zu teilen. Jeder mit diesem Link kann den Zeitplan sehen. Wenn die Person eine Dosis als eingenommen markiert, wird sie auch in deiner App als eingenommen angezeigt.",
+    "allPeople": "Alle",
     "selectPerson": "Person auswählen",
     "selectPeriod": "Zeitraum auswählen",
     "generateLink": "Link generieren",
     "generating": "Wird generiert...",
     "generateAnother": "Weiteren Link generieren",
     "linkGenerated": "Teilen-Link erstellt!",
+    "scheduleLink": "Zeitplan-Link",
+    "overviewLink": "Übersichts-Link",
     "copyLink": "Link kopieren",
+    "copyOverviewLink": "Übersichts-Link kopieren",
     "copied": "In Zwischenablage kopiert!",
     "noPeople": "Keine Medikamente mit 'Eingenommen von' zugewiesen. Füge zuerst eine Person zu einem Medikament hinzu.",
     "scheduleFor": "Zeitplan für",
@@ -557,6 +578,34 @@
       "expiredOn": "Abgelaufen am: {{date}}"
     }
   },
+  "sharedOverview": {
+    "title": "Medikamente für {{person}}",
+    "sharedBy": "Geteilt von {{user}}",
+    "expiredOn": "Abgelaufen am: {{date}}",
+    "noMedications": "Für diesen Teilen-Link sind keine Medikamente verfügbar.",
+    "columns": {
+      "name": "Name",
+      "package": "Packung",
+      "stock": "Bestand",
+      "daysLeft": "Geschätzte Resttage",
+      "nextIntake": "Nächste Einnahme",
+      "depletion": "Aufgebraucht",
+      "priority": "Bestandswarnung"
+    },
+    "priority": {
+      "normal": "Bestand ok",
+      "high": "Niedriger Bestand"
+    },
+    "stock": {
+      "of": "{{current}} von {{capacity}}"
+    },
+    "error": {
+      "notFound": "Teilen-Link nicht gefunden",
+      "expired": "Dieser geteilte Übersichts-Link ist abgelaufen",
+      "rateLimit": "Zu viele Anfragen. Bitte versuche es in einem Moment erneut.",
+      "generic": "Die Medikamentenübersicht konnte nicht geladen werden"
+    }
+  },
   "exportImport": {
     "title": "Datenexport / -import",
     "description": "Sichere deine Daten oder übertrage sie auf ein anderes Gerät.",