chore: release v1.20.1 (#437)

The shareStockStatus UI toggle was replaced by shareMedicationOverview in
commit e0fb77d, but the backend gating logic was left intact. Users who
had previously set shareStockStatus=false were stuck with empty stock
values ('-') on the shared medication overview with no UI to change it.

- Remove showStockStatus parameter from buildSharedMedicationOverview()
- Remove visibility gating that nullified stock fields
- Remove shareStockStatus from settings API responses and PUT schema
- Remove shareStockStatus from frontend types, hooks, and context
- Clean up all related test fixtures and dead test cases
- DB column share_stock_status retained (never remove columns)

.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:
@@ -56,7 +71,7 @@ jobs:
           SESSION_SECRET: e2e-test-session-secret-long-enough
 
       - name: Upload Playwright report
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: playwright-report
@@ -64,7 +79,7 @@ jobs:
           retention-days: 7
 
       - name: Upload test results
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: playwright-results

.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/test.yml

@@ -73,7 +73,7 @@ jobs:
         run: npm run test:coverage
 
       - name: Upload coverage report
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: backend-coverage
@@ -118,7 +118,7 @@ jobs:
         run: npm run build
 
       - name: Upload coverage report
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: frontend-coverage

.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

@@ -82,5 +82,9 @@ Thumbs.db
 .claude/
 AGENTS.md
 docs/TECH_STACK.md
-doku
-plan
+doku/
+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-569%2F569-brightgreen?logo=vitest" alt="Backend Tests 454/454" />
-  <img src="https://img.shields.io/badge/Frontend_Tests-769%2F769-brightgreen?logo=vitest" alt="Frontend Tests 611/611" />
+  <img src="https://img.shields.io/badge/Backend_Tests-614%2F614-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/0011_add_medication_form_lifecycle_columns.sql

@@ -0,0 +1,5 @@
+ALTER TABLE `medications` ADD `medication_form` text(20) DEFAULT 'tablet' NOT NULL;--> statement-breakpoint
+ALTER TABLE `medications` ADD `pill_form` text(20);--> statement-breakpoint
+ALTER TABLE `medications` ADD `lifecycle_category` text(30) DEFAULT 'refill_when_empty' NOT NULL;--> statement-breakpoint
+ALTER TABLE `medications` ADD `medication_end_date` text;--> statement-breakpoint
+ALTER TABLE `medications` ADD `auto_mark_obsolete_after_end_date` integer DEFAULT true NOT NULL;

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,7 +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_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.16.1",
+  "version": "1.19.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "medassist-ng-backend",
-      "version": "1.16.1",
+      "version": "1.19.0",
       "dependencies": {
         "@fastify/cookie": "^11.0.2",
         "@fastify/cors": "^11.2.0",
@@ -16,21 +16,23 @@
         "@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.0",
+        "@biomejs/biome": "^2.4.6",
+        "@types/node": "^25.3.5",
         "@types/nodemailer": "^7.0.11",
-        "@types/supertest": "^6.0.2",
+        "@types/supertest": "^7.2.0",
         "@vitest/coverage-v8": "^4.0.18",
         "drizzle-kit": "^0.31.9",
         "pino-pretty": "^13.1.3",
@@ -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.0",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.3.0.tgz",
-      "integrity": "sha512-4K3bqJpXpqfg2XKGK9bpDTc6xO/xoUP/RBWS7AtRMug6zZFaRekiLzjVtAoZMquxoAbzBvy5nxQ7veS5eYzf8A==",
+      "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"
@@ -2657,9 +2705,9 @@
       }
     },
     "node_modules/@types/supertest": {
-      "version": "6.0.3",
-      "resolved": "https://registry.npmjs.org/@types/supertest/-/supertest-6.0.3.tgz",
-      "integrity": "sha512-8WzXq62EXFhJ7QsH3Ocb/iKQ/Ty9ZVWnVzoTKc9tyyFRRF3a74Tk2+TLFgaFFw364Ere+npzHKEJ6ga2LzIL7w==",
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/@types/supertest/-/supertest-7.2.0.tgz",
+      "integrity": "sha512-uh2Lv57xvggst6lCqNdFAmDSvoMG7M/HDtX4iUCquxQ5EGPtaPM5PL5Hmi7LCvOG8db7YaCPNJEeoI8s/WzIQw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -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",
@@ -4890,9 +4954,9 @@
       "license": "ISC"
     },
     "node_modules/minimatch": {
-      "version": "10.2.2",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.2.tgz",
-      "integrity": "sha512-+G4CpNBxa5MprY+04MbgOw1v7So6n5JY166pFi9KfYwT78fxScCeSNQSNzp6dpPSW2rONOps6Ocam1wFhCgoVw==",
+      "version": "10.2.4",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.4.tgz",
+      "integrity": "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==",
       "license": "BlueOak-1.0.0",
       "dependencies": {
         "brace-expansion": "^5.0.2"
@@ -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.17.0",
+  "version": "1.20.1",
   "private": true,
   "type": "module",
   "scripts": {
@@ -25,21 +25,23 @@
     "@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.0",
+    "@biomejs/biome": "^2.4.6",
+    "@types/node": "^25.3.5",
     "@types/nodemailer": "^7.0.11",
-    "@types/supertest": "^6.0.2",
+    "@types/supertest": "^7.2.0",
     "@vitest/coverage-v8": "^4.0.18",
     "drizzle-kit": "^0.31.9",
     "pino-pretty": "^13.1.3",

backend/src/db/db-utils.ts

@@ -125,6 +125,14 @@ export async function runAlterMigrations(client: Client): Promise<{ success: boo
 		`ALTER TABLE medications ADD COLUMN obsolete_at integer`,
 		// Added for explicit medication lifecycle start date
 		`ALTER TABLE medications ADD COLUMN medication_start_date text NOT NULL DEFAULT ''`,
+		// Added for form/lifecycle modeling (V1 medication forms)
+		`ALTER TABLE medications ADD COLUMN medication_form text NOT NULL DEFAULT 'tablet'`,
+		`ALTER TABLE medications ADD COLUMN pill_form text`,
+		`ALTER TABLE medications ADD COLUMN lifecycle_category text NOT NULL DEFAULT 'refill_when_empty'`,
+		`ALTER TABLE medications ADD COLUMN medication_end_date text`,
+		`ALTER TABLE medications ADD COLUMN auto_mark_obsolete_after_end_date integer NOT NULL DEFAULT 1`,
+		`ALTER TABLE medications ADD COLUMN package_amount_value integer NOT NULL DEFAULT 0`,
+		`ALTER TABLE medications ADD COLUMN package_amount_unit text NOT NULL DEFAULT 'ml'`,
 		// Added for more detailed reminder info display
 		`ALTER TABLE user_settings ADD COLUMN last_reminder_med_name text`,
 		`ALTER TABLE user_settings ADD COLUMN last_reminder_taken_by text`,
@@ -141,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`,
@@ -181,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) {
@@ -199,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

@@ -29,6 +29,11 @@ export const medications = sqliteTable("medications", {
 	genericName: text("generic_name", { length: 100 }),
 	takenByJson: text("taken_by_json").notNull().default("[]"), // JSON array of person names
 	packageType: text("package_type", { length: 20 }).notNull().default("blister"), // 'blister' or 'bottle'
+	medicationForm: text("medication_form", { length: 20 }).notNull().default("tablet"), // 'capsule' | 'tablet' | 'liquid' | 'topical'
+	pillForm: text("pill_form", { length: 20 }), // Only for blister/bottle with pill-based medications: 'tablet' | 'capsule'
+	lifecycleCategory: text("lifecycle_category", { length: 30 }).notNull().default("refill_when_empty"), // 'refill_when_empty' | 'treatment_period'
+	packageAmountValue: integer("package_amount_value").notNull().default(0), // Informational package quantity (ml/g)
+	packageAmountUnit: text("package_amount_unit", { length: 10 }).notNull().default("ml"), // 'ml' | 'g'
 	packCount: integer("pack_count").notNull().default(1),
 	blistersPerPack: integer("blisters_per_pack").notNull().default(1),
 	pillsPerBlister: integer("pills_per_blister").notNull().default(1),
@@ -48,6 +53,10 @@ export const medications = sqliteTable("medications", {
 	notes: text("notes"),
 	intakeRemindersEnabled: integer("intake_reminders_enabled", { mode: "boolean" }).notNull().default(false),
 	medicationStartDate: text("medication_start_date").notNull().default(""),
+	medicationEndDate: text("medication_end_date"),
+	autoMarkObsoleteAfterEndDate: integer("auto_mark_obsolete_after_end_date", { mode: "boolean" })
+		.notNull()
+		.default(true),
 	isObsolete: integer("is_obsolete", { mode: "boolean" }).notNull().default(false),
 	obsoleteAt: integer("obsolete_at", { mode: "timestamp" }),
 	prescriptionEnabled: integer("prescription_enabled", { mode: "boolean" }).notNull().default(false),
@@ -100,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),
@@ -137,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/i18n/translations.ts

@@ -179,6 +179,8 @@ type TranslationKeys = {
 	common: {
 		pill: string;
 		pills: string;
+		units: string;
+		ml: string;
 		blister: string;
 		blisters: string;
 		day: string;
@@ -299,6 +301,8 @@ const translations: Record<Language, TranslationKeys> = {
 		common: {
 			pill: "pill",
 			pills: "pills",
+			units: "units",
+			ml: "ml",
 			blister: "blister",
 			blisters: "blisters",
 			day: "day",
@@ -420,6 +424,8 @@ const translations: Record<Language, TranslationKeys> = {
 		common: {
 			pill: "Tablette",
 			pills: "Tabletten",
+			units: "Einheiten",
+			ml: "ml",
 			blister: "Blister",
 			blisters: "Blister",
 			day: "Tag",

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") {
+	// Human-readable logs in development, structured JSON in production/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");
@@ -17,7 +23,7 @@ const IMAGES_DIR = resolve(getDataDir(), "images");
 // =============================================================================
 // Export Format Version (bump this when format changes)
 // =============================================================================
-const EXPORT_VERSION = "1.1";
+const EXPORT_VERSION = "1.3";
 
 // =============================================================================
 // Zod Schemas for Import Validation
@@ -27,6 +33,7 @@ const scheduleSchema = z.object({
 	usage: z.number().nonnegative(),
 	every: z.number().int().min(1),
 	start: z.string(), // ISO datetime string
+	intakeUnit: z.enum(["ml", "tsp", "tbsp"]).nullable().optional(),
 	remind: z.boolean().optional().default(false),
 	takenBy: z.string().nullable().optional(), // Per-intake takenBy (new field)
 });
@@ -38,7 +45,9 @@ 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"]).default("blister"),
+	packageType: z.enum(PACKAGE_TYPES).default("blister"),
+	packageAmountValue: z.number().int().min(0).default(0),
+	packageAmountUnit: z.enum(["ml", "g"]).default("ml"),
 });
 
 const medicationExportSchema = z.object({
@@ -46,11 +55,16 @@ const medicationExportSchema = z.object({
 	name: z.string().min(1),
 	genericName: z.string().nullable().optional(),
 	takenBy: z.array(z.string()).default([]),
+	medicationForm: z.enum(["capsule", "tablet", "liquid", "topical"]).default("tablet"),
+	pillForm: z.enum(["capsule", "tablet"]).nullable().optional(),
+	lifecycleCategory: z.enum(["refill_when_empty", "treatment_period"]).default("refill_when_empty"),
 	inventory: inventorySchema,
 	pillWeightMg: z.number().int().nullable().optional(),
 	doseUnit: z.enum(["mg", "g", "mcg", "ml", "IU", "units", "drops", "puffs"]).default("mg"),
 	schedules: z.array(scheduleSchema).default([]),
 	medicationStartDate: z.string().nullable().optional(),
+	medicationEndDate: z.string().nullable().optional(),
+	autoMarkObsoleteAfterEndDate: z.boolean().default(true),
 	expiryDate: z.string().nullable().optional(),
 	notes: z.string().nullable().optional(),
 	intakeRemindersEnabled: z.boolean().default(false),
@@ -122,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();
 
@@ -136,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
 // =============================================================================
@@ -155,9 +233,14 @@ async function getUserId(request: FastifyRequest, reply: FastifyReply): Promise<
 }
 
 // Parse intakes from DB format to export format (with per-intake takenBy)
-function parseIntakesForExport(
-	row: typeof medications.$inferSelect
-): Array<{ usage: number; every: number; start: string; remind: boolean; takenBy: string | null }> {
+function parseIntakesForExport(row: typeof medications.$inferSelect): Array<{
+	usage: number;
+	every: number;
+	start: string;
+	intakeUnit: "ml" | "tsp" | "tbsp" | null;
+	remind: boolean;
+	takenBy: string | null;
+}> {
 	// Use the new parseIntakesJson which falls back to legacy format
 	const intakes = parseIntakesJson(
 		row.intakesJson,
@@ -169,6 +252,7 @@ function parseIntakesForExport(
 		usage: intake.usage,
 		every: intake.every,
 		start: intake.start,
+		intakeUnit: null,
 		remind: intake.intakeRemindersEnabled,
 		takenBy: intake.takenBy, // Per-intake takenBy
 	}));
@@ -257,236 +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),
-				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",
+	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,
-				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!)
@@ -499,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);
@@ -555,6 +683,7 @@ export async function exportRoutes(app: FastifyInstance) {
 						usage: s.usage,
 						every: s.every,
 						start: s.start,
+						intakeUnit: s.intakeUnit ?? null,
 						takenBy: s.takenBy || null,
 						intakeRemindersEnabled: s.remind ?? false,
 					}))
@@ -570,7 +699,12 @@ export async function exportRoutes(app: FastifyInstance) {
 						name: med.name,
 						genericName: med.genericName || null,
 						takenByJson,
-						packageType: med.inventory.packageType ?? "blister",
+						medicationForm: med.medicationForm ?? "tablet",
+						pillForm: med.pillForm || null,
+						lifecycleCategory: med.lifecycleCategory ?? "refill_when_empty",
+						packageType: normalizePackageType(med.inventory.packageType),
+						packageAmountValue: med.inventory.packageAmountValue ?? 0,
+						packageAmountUnit: med.inventory.packageAmountUnit ?? "ml",
 						packCount: med.inventory.packCount,
 						blistersPerPack: med.inventory.blistersPerPack,
 						pillsPerBlister: med.inventory.pillsPerBlister,
@@ -581,6 +715,8 @@ export async function exportRoutes(app: FastifyInstance) {
 						pillWeightMg: med.pillWeightMg || null,
 						doseUnit: med.doseUnit ?? "mg",
 						medicationStartDate: med.medicationStartDate || "",
+						medicationEndDate: med.medicationEndDate || null,
+						autoMarkObsoleteAfterEndDate: med.autoMarkObsoleteAfterEndDate ?? true,
 						intakesJson,
 						usageJson,
 						everyJson,
@@ -659,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

@@ -32,7 +32,7 @@ export type UserSettings = {
 	highStockDays: number;
 	language: Language;
 	stockCalculationMode: "automatic" | "manual";
-	shareStockStatus: boolean;
+	shareMedicationOverview: boolean;
 	upcomingTodayOnly: boolean;
 	shareScheduleTodayOnly: boolean;
 	swapDashboardMainSections: boolean;
@@ -71,7 +71,7 @@ type SettingsBody = {
 	maxNaggingReminders: number;
 	language: string;
 	stockCalculationMode: "automatic" | "manual";
-	shareStockStatus: boolean;
+	shareMedicationOverview: boolean;
 	upcomingTodayOnly: boolean;
 	shareScheduleTodayOnly: boolean;
 	swapDashboardMainSections: boolean;
@@ -85,6 +85,87 @@ 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";
+	if (localPart.length <= 2) return `${localPart[0] ?? "*"}*@${domain}`;
+	return `${localPart.slice(0, 2)}***@${domain}`;
+}
+
+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 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";
@@ -139,7 +220,7 @@ function getDefaultSettings() {
 		highStockDays: envInt("DEFAULT_HIGH_STOCK_DAYS", 180),
 		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,
@@ -201,7 +282,7 @@ export async function loadUserSettings(userId: number): Promise<UserSettings> {
 		highStockDays: settings.highStockDays,
 		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,
@@ -245,7 +326,7 @@ export async function getAllUserSettings(): Promise<UserSettings[]> {
 		highStockDays: settings.highStockDays,
 		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,
@@ -285,178 +366,346 @@ 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",
+				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"] },
+						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",
+						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",
+				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;
-
-		if (!smtpHost || !smtpUser) {
-			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;
 
-			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: `
+			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 ?? "",
+					},
+				});
+
+				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>
@@ -465,47 +714,89 @@ export async function settingsRoutes(app: FastifyInstance) {
             <p style="color: #6b7280; font-size: 14px;">Sent from MedAssist-ng Medication Planner</p>
           </div>
         `,
-			});
+				});
 
-			return reply.send({ success: true, message: "Test email sent successfully" });
-		} catch (error) {
-			const errorMessage = error instanceof Error ? error.message : "Unknown error";
-			return reply.status(500).send({ error: `Failed to send email: ${errorMessage}` });
+				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 });
+			}
 		}
-	});
+	);
 
 	// 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,72 @@ 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"] },
+		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,130 +121,263 @@ 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"
+				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,
+					})
+				: 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",
+				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,
+			});
+
+			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);
 
@@ -251,37 +458,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,213 @@
+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;
+}): SharedMedicationOverviewItem[] {
+	const { medications: medicationRows, doses, thresholdDays } = 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);
+		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,
+			capacity,
+			daysLeft,
+			nextIntakeDate: computeNextIntakeDate(intakes, todayDateOnly),
+			depletionDate,
+			priority,
+			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,
@@ -19,6 +25,7 @@ import {
 	getNextScheduledTime,
 	getTimezone,
 	getTodayInTimezone,
+	normalizeIntakeUsageForStock,
 	parseIntakesJson,
 	parseLocalDateTime,
 	parseReminderState,
@@ -37,6 +44,36 @@ function escapeHtml(text: string): string {
 	return text.replace(/[&<>"']/g, (char) => htmlEscapes[char] || char);
 }
 
+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.";
+}
+
 const REMINDER_HOUR = parseInt(process.env.REMINDER_HOUR ?? "6", 10); // Default 6:00 AM local time
 
 const reminderStateFile = resolve(getDataDir(), "reminder-state.json");
@@ -179,6 +216,12 @@ type LowStockItem = {
 	isCritical: boolean;
 };
 
+function getLiquidReminderThresholds(baselineDays: number): { lowDays: number; criticalDays: number } {
+	const lowDays = Math.max(1, Math.floor(baselineDays));
+	const criticalDays = Math.max(1, Math.ceil(lowDays / 2));
+	return { lowDays, criticalDays };
+}
+
 type PrescriptionReminderItem = {
 	name: string;
 	remainingRefills: number;
@@ -231,17 +274,25 @@ 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 (isTubePackageType(packageType)) continue;
+
 		const intakes = parseIntakesJson(
 			row.intakesJson,
 			{ usageJson: row.usageJson, everyJson: row.everyJson, startJson: row.startJson },
 			row.intakeRemindersEnabled ?? false
 		);
-		const blisters: Blister[] = intakes.map((i) => ({ usage: i.usage, every: i.every, start: i.start }));
+		const blisters: Blister[] = intakes.map((i) => ({
+			usage: normalizeIntakeUsageForStock(i, row.medicationForm, row.packageType),
+			every: i.every,
+			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>();
@@ -348,8 +399,13 @@ async function getMedicationsNeedingReminder(
 
 		if (daysLeft === null) continue;
 
-		const isCritical = daysLeft <= reminderDaysBefore;
-		const isLow = daysLeft < lowStockDays;
+		const isLiquid = isLiquidContainerPackageType(packageType);
+		const { lowDays, criticalDays } = isLiquid
+			? getLiquidReminderThresholds(reminderDaysBefore)
+			: { lowDays: lowStockDays, criticalDays: reminderDaysBefore };
+
+		const isCritical = daysLeft <= criticalDays;
+		const isLow = isLiquid ? daysLeft <= lowDays : daysLeft < lowDays;
 
 		if (isCritical || isLow) {
 			lowStock.push({
@@ -551,7 +607,7 @@ ${getFooterPlain(language)}${isRepeatDaily ? `\n\n${tr.stockReminder.repeatDaily
 			},
 		});
 
-		await transporter.sendMail({
+		const mailResult = await transporter.sendMail({
 			from: smtpFrom,
 			to: email,
 			subject,
@@ -559,6 +615,11 @@ ${getFooterPlain(language)}${isRepeatDaily ? `\n\n${tr.stockReminder.repeatDaily
 			html,
 		});
 
+		const deliveryError = getDeliveryError(mailResult);
+		if (deliveryError) {
+			throw new Error(deliveryError);
+		}
+
 		return { success: true };
 	} catch (error) {
 		const errorMessage = error instanceof Error ? error.message : "Unknown error";
@@ -626,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;
@@ -645,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}`);
 						}
 					}
 
@@ -687,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}`);
 						}
 					}
 
@@ -719,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.
@@ -730,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 =
@@ -752,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);
@@ -872,19 +925,21 @@ async function checkAndSendReminderForUser(
   `;
 									const text = `${emptyRx.length > 0 ? tr.prescriptionReminder.titleEmpty : tr.prescriptionReminder.title}\n\n${bodyText}\n\n${lines.join("\n")}\n\n---\n${getFooterPlain(language)}${settings.repeatDailyReminders ? `\n\n${tr.prescriptionReminder.repeatDailyNote}` : ""}`;
 
-									await transporter.sendMail({
+									const mailResult = await transporter.sendMail({
 										from: smtpFrom,
 										to: settings.notificationEmail!,
 										subject,
 										text,
 										html,
 									});
+									const deliveryError = getDeliveryError(mailResult);
+									if (deliveryError) {
+										throw new Error(deliveryError);
+									}
 									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}`);
 								}
 							}
 						}
@@ -921,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/db-client.test.ts

@@ -32,8 +32,8 @@ async function loadDbClientModule(options: ClientTestOptions = {}) {
 		.mockReturnValue(dirWritable ? { success: true } : { success: false, error: "permission denied" });
 	const getDbPaths = vi.fn().mockReturnValue({
 		dataDir: "/tmp/medassist-data",
-		dbPath: "/tmp/medassist-data/medassist.db",
-		url: "file:/tmp/medassist-data/medassist.db",
+		dbPath: "/tmp/medassist-data/medassist-ng.db",
+		url: "file:/tmp/medassist-data/medassist-ng.db",
 	});
 	const runDrizzleMigrations = vi.fn().mockResolvedValue({ success: true });
 	const runAlterMigrations = vi.fn().mockResolvedValue({ errors: [] });
@@ -102,7 +102,7 @@ describe("db/client bootstrap", () => {
 		await mod.migrationsReady;
 
 		expect(mocks.ensureDataDirectory).toHaveBeenCalledWith("/tmp/medassist-data");
-		expect(mocks.createClient).toHaveBeenCalledWith({ url: "file:/tmp/medassist-data/medassist.db" });
+		expect(mocks.createClient).toHaveBeenCalledWith({ url: "file:/tmp/medassist-data/medassist-ng.db" });
 		expect(mocks.runDrizzleMigrations).toHaveBeenCalledTimes(1);
 		expect(mocks.runAlterMigrations).toHaveBeenCalledTimes(1);
 		expect(mocks.repairTrailingHyphenDoseIds).toHaveBeenCalledTimes(1);

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(() => {
@@ -82,7 +83,12 @@ async function createSchema(client: Client) {
 		    name text NOT NULL,
 		    generic_name text,
 		    taken_by_json text NOT NULL DEFAULT '[]',
+		    medication_form text NOT NULL DEFAULT 'tablet',
+		    pill_form text,
+		    lifecycle_category text NOT NULL DEFAULT 'refill_when_empty',
 		    package_type text NOT NULL DEFAULT 'blister',
+		    package_amount_value integer NOT NULL DEFAULT 0,
+		    package_amount_unit text NOT NULL DEFAULT 'ml',
 		    pack_count integer NOT NULL DEFAULT 1,
 		    blisters_per_pack integer NOT NULL DEFAULT 1,
 		    pills_per_blister integer NOT NULL DEFAULT 1,
@@ -101,6 +107,8 @@ async function createSchema(client: Client) {
 		    notes text,
 		    intake_reminders_enabled integer NOT NULL DEFAULT 0,
 		    medication_start_date text NOT NULL DEFAULT '',
+		    medication_end_date text,
+		    auto_mark_obsolete_after_end_date integer NOT NULL DEFAULT 1,
 		    is_obsolete integer NOT NULL DEFAULT 0,
 		    obsolete_at integer,
 		    prescription_enabled integer NOT NULL DEFAULT 0,
@@ -138,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,
@@ -240,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" });
@@ -338,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 () => {
@@ -496,6 +536,77 @@ 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 always show stock fields in overview regardless of share_stock_status setting", 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).toBeTypeOf("number");
+			expect(medication.capacity).toBeTypeOf("number");
+		});
 	});
 
 	// ---------------------------------------------------------------------------
@@ -827,7 +938,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 () => {
@@ -1922,6 +2033,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",
@@ -2295,6 +2447,28 @@ 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",
+					upcomingTodayOnly: false,
+					shareScheduleTodayOnly: false,
+					swapDashboardMainSections: false,
 				},
 			});
 
@@ -2335,7 +2509,6 @@ describe("E2E Tests with Real Routes", () => {
 					maxNaggingReminders: 5,
 					language: "en",
 					stockCalculationMode: "automatic",
-					shareStockStatus: true,
 					upcomingTodayOnly: false,
 					shareScheduleTodayOnly: false,
 					swapDashboardMainSections: false,
@@ -2499,10 +2672,10 @@ describe("E2E Tests with Real Routes", () => {
 	});
 
 	// ---------------------------------------------------------------------------
-	// Package Type (bottle vs blister) Tests
+	// Package Type (blister, bottle, tube, liquid_container) Tests
 	// ---------------------------------------------------------------------------
 
-	describe("Package type handling (bottle vs blister)", () => {
+	describe("Package type handling (blister, bottle, tube, liquid_container)", () => {
 		const bottleMedication = {
 			name: "Vitamin D Drops",
 			packageType: "bottle",
@@ -2523,6 +2696,33 @@ describe("E2E Tests with Real Routes", () => {
 			blisters: [{ usage: 1, every: 1, start: "2025-01-01T08:00:00.000Z" }],
 		};
 
+		const liquidContainerMedication = {
+			name: "Cough Syrup",
+			medicationForm: "liquid",
+			packageType: "liquid_container",
+			doseUnit: "ml",
+			packCount: 0,
+			blistersPerPack: 1,
+			pillsPerBlister: 1,
+			looseTablets: 180,
+			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",
@@ -2567,6 +2767,49 @@ describe("E2E Tests with Real Routes", () => {
 			expect(data.medications[0].totalPills).toBe(120);
 		});
 
+		it("should create and return liquid_container type medication", async () => {
+			const response = await app.inject({
+				method: "POST",
+				url: "/medications",
+				payload: liquidContainerMedication,
+			});
+
+			expect(response.statusCode).toBe(200);
+			const data = response.json();
+			expect(data.packageType).toBe("liquid_container");
+			expect(data.medicationForm).toBe("liquid");
+			expect(data.doseUnit).toBe("ml");
+			expect(data.looseTablets).toBe(180);
+		});
+
+		it("should return packageType and ml-based stock semantics in shared schedule for liquid_container", async () => {
+			await app.inject({
+				method: "POST",
+				url: "/medications",
+				payload: { ...liquidContainerMedication, takenBy: ["Daniel"] },
+			});
+
+			const shareResponse = await app.inject({
+				method: "POST",
+				url: "/share",
+				payload: { takenBy: "Daniel", scheduleDays: 30 },
+			});
+			expect(shareResponse.statusCode).toBe(200);
+			const { token } = shareResponse.json();
+
+			const scheduleResponse = await app.inject({
+				method: "GET",
+				url: `/share/${token}`,
+			});
+
+			expect(scheduleResponse.statusCode).toBe(200);
+			const data = scheduleResponse.json();
+			expect(data.medications).toHaveLength(1);
+			expect(data.medications[0].packageType).toBe("liquid_container");
+			// Liquid container follows container semantics (stock from looseTablets only).
+			expect(data.medications[0].totalPills).toBe(180);
+		});
+
 		it("should calculate correct totalPills for shared blister medication", async () => {
 			await app.inject({
 				method: "POST",
@@ -2636,6 +2879,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",
@@ -2742,5 +3051,18 @@ describe("E2E Tests with Real Routes", () => {
 			expect(medsResponse.json()).toHaveLength(1);
 			expect(medsResponse.json()[0].packageType).toBe("blister");
 		});
+
+		it("should reject liquid medication form with non-liquid package type", async () => {
+			const response = await app.inject({
+				method: "POST",
+				url: "/medications",
+				payload: {
+					...liquidContainerMedication,
+					packageType: "bottle",
+				},
+			});
+
+			expect(response.statusCode).toBe(400);
+		});
 	});
 });

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(() => {
@@ -76,7 +77,12 @@ async function createSchema(client: Client) {
 		    name text NOT NULL,
 		    generic_name text,
 		    taken_by_json text NOT NULL DEFAULT '[]',
+		    medication_form text NOT NULL DEFAULT 'tablet',
+		    pill_form text,
+		    lifecycle_category text NOT NULL DEFAULT 'refill_when_empty',
 		    package_type text NOT NULL DEFAULT 'blister',
+		    package_amount_value integer NOT NULL DEFAULT 0,
+		    package_amount_unit text NOT NULL DEFAULT 'ml',
 		    pack_count integer NOT NULL DEFAULT 1,
 		    blisters_per_pack integer NOT NULL DEFAULT 1,
 		    pills_per_blister integer NOT NULL DEFAULT 1,
@@ -95,6 +101,8 @@ async function createSchema(client: Client) {
 		    notes text,
 		    intake_reminders_enabled integer NOT NULL DEFAULT 0,
 		    medication_start_date text NOT NULL DEFAULT '',
+		    medication_end_date text,
+		    auto_mark_obsolete_after_end_date integer NOT NULL DEFAULT 1,
 		    is_obsolete integer NOT NULL DEFAULT 0,
 		    obsolete_at integer,
 		    prescription_enabled integer NOT NULL DEFAULT 0,
@@ -132,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,
@@ -196,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, {
@@ -246,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" }],
 				},
 			});
@@ -299,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" }],
 				},
 			});
@@ -337,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" },
@@ -398,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" }],
 				},
 			});
@@ -535,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" }],
 				},
 			});
@@ -589,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 {
@@ -93,7 +94,12 @@ async function createSchema(client: Client) {
       name text NOT NULL,
       generic_name text,
       taken_by_json text NOT NULL DEFAULT '[]',
+		medication_form text NOT NULL DEFAULT 'tablet',
+		pill_form text,
+		lifecycle_category text NOT NULL DEFAULT 'refill_when_empty',
       package_type text NOT NULL DEFAULT 'blister',
+		package_amount_value integer NOT NULL DEFAULT 0,
+		package_amount_unit text NOT NULL DEFAULT 'ml',
       pack_count integer NOT NULL DEFAULT 1,
       blisters_per_pack integer NOT NULL DEFAULT 1,
       pills_per_blister integer NOT NULL DEFAULT 1,
@@ -112,6 +118,8 @@ async function createSchema(client: Client) {
       notes text,
       intake_reminders_enabled integer NOT NULL DEFAULT 0,
       medication_start_date text NOT NULL DEFAULT '',
+	medication_end_date text,
+	auto_mark_obsolete_after_end_date integer NOT NULL DEFAULT 1,
       is_obsolete integer NOT NULL DEFAULT 0,
       obsolete_at integer,
       prescription_enabled integer NOT NULL DEFAULT 0,
@@ -149,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,
@@ -207,7 +216,7 @@ describe("Planner Routes", () => {
 			args: [],
 		});
 
-		app = Fastify({ logger: false });
+		app = Fastify({ logger: false, ajv: documentationSchemaAjv });
 		await app.register(plannerRoutes);
 		await app.ready();
 
@@ -284,7 +293,7 @@ describe("Planner Routes", () => {
 				args: [999999999],
 			});
 
-			mockSendMail.mockResolvedValueOnce({ messageId: "123" });
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
 
 			const response = await app.inject({
 				method: "POST",
@@ -330,7 +339,7 @@ describe("Planner Routes", () => {
 				args: [999999999],
 			});
 
-			mockSendMail.mockResolvedValueOnce({ messageId: "123" });
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
 
 			const response = await app.inject({
 				method: "POST",
@@ -434,7 +443,7 @@ describe("Planner Routes", () => {
 				args: [999999999],
 			});
 
-			mockSendMail.mockResolvedValueOnce({ messageId: "123" });
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
 
 			const response = await app.inject({
 				method: "POST",
@@ -522,7 +531,7 @@ describe("Planner Routes", () => {
 				args: [999999999],
 			});
 
-			mockSendMail.mockResolvedValueOnce({ messageId: "123" });
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
 			mockSendShoutrrr.mockResolvedValueOnce({ success: true });
 
 			const response = await app.inject({
@@ -697,7 +706,7 @@ describe("Planner Routes", () => {
 				args: [999999999],
 			});
 
-			mockSendMail.mockResolvedValueOnce({ messageId: "123" });
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
 
 			const response = await app.inject({
 				method: "POST",
@@ -727,7 +736,7 @@ describe("Planner Routes", () => {
 				args: [999999999],
 			});
 
-			mockSendMail.mockResolvedValueOnce({ messageId: "123" });
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
 
 			const response = await app.inject({
 				method: "POST",
@@ -763,7 +772,7 @@ describe("Planner Routes", () => {
 				args: [999999999],
 			});
 
-			mockSendMail.mockResolvedValueOnce({ messageId: "123" });
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
 
 			const response = await app.inject({
 				method: "POST",
@@ -849,7 +858,7 @@ describe("Planner Routes", () => {
 				args: [999999999],
 			});
 
-			mockSendMail.mockResolvedValueOnce({ messageId: "123" });
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
 			mockSendShoutrrr.mockResolvedValueOnce({ success: true });
 
 			const response = await app.inject({
@@ -982,7 +991,7 @@ describe("Planner Routes", () => {
 				args: [999999999],
 			});
 
-			mockSendMail.mockResolvedValueOnce({ messageId: "123" });
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
 
 			const response = await app.inject({
 				method: "POST",
@@ -1036,6 +1045,36 @@ describe("Planner Routes", () => {
 			expect(title).not.toContain("Low");
 			expect(message).toContain("Running critically low");
 		});
+
+		it("should return 400 when only tube medications are in active meds", async () => {
+			// Insert a tube medication (should be excluded from reminders)
+			await testClient.execute({
+				sql: `INSERT INTO medications (id, user_id, name, taken_by_json, usage_json, every_json, start_json, package_type)
+				       VALUES (3, 999999999, 'Ointment', '[]', '[]', '[]', '[]', 'tube')`,
+				args: [],
+			});
+
+			await testClient.execute({
+				sql: `INSERT INTO user_settings (user_id, email_enabled, shoutrrr_enabled, language) VALUES (?, 1, 0, 'en')`,
+				args: [999999999],
+			});
+
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
+
+			const response = await app.inject({
+				method: "POST",
+				url: "/reminder/send-email",
+				payload: {
+					email: "test@example.com",
+					lowStock: [{ name: "Ointment", medsLeft: 5, daysLeft: 10, depletionDate: "2025-01-13" }],
+				},
+			});
+
+			// Expects 400 because tube medications are excluded from stock reminders
+			expect(response.statusCode).toBe(400);
+			expect(response.json()).toEqual({ error: "No active medications to notify" });
+			expect(mockSendMail).not.toHaveBeenCalled();
+		});
 	});
 
 	describe("POST /reminder/send-prescription", () => {
@@ -1082,7 +1121,7 @@ describe("Planner Routes", () => {
 				args: [999999999],
 			});
 
-			mockSendMail.mockResolvedValueOnce({ messageId: "123" });
+			mockSendMail.mockResolvedValueOnce({ messageId: "123", accepted: ["test.com"], rejected: [] });
 
 			const response = await app.inject({
 				method: "POST",

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);
@@ -137,11 +140,76 @@ describe("Real route coverage: settings/export/report", () => {
 		expect(response.statusCode).toBe(200);
 		const body = response.json();
 		expect(body.language).toBe("en");
-		expect(body.shareStockStatus).toBe(true);
 		expect(body.upcomingTodayOnly).toBe(false);
 		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",
+				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",
@@ -168,7 +236,6 @@ describe("Real route coverage: settings/export/report", () => {
 				maxNaggingReminders: 5,
 				language: "en",
 				stockCalculationMode: "automatic",
-				shareStockStatus: true,
 				upcomingTodayOnly: false,
 				shareScheduleTodayOnly: false,
 				swapDashboardMainSections: false,
@@ -190,7 +257,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 () => {
@@ -207,7 +297,12 @@ describe("Real route coverage: settings/export/report", () => {
 		process.env.SMTP_HOST = "smtp.example.com";
 		process.env.SMTP_USER = "mailer@example.com";
 		process.env.SMTP_TOKEN = "secret";
-		nodemailerSendMail.mockResolvedValue(undefined);
+		nodemailerSendMail.mockResolvedValue({
+			accepted: ["person@example.com"],
+			rejected: [],
+			response: "250 2.0.0 OK",
+			messageId: "test-message-id",
+		});
 
 		const response = await app.inject({
 			method: "POST",
@@ -219,6 +314,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",
@@ -228,6 +339,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);
@@ -261,6 +396,166 @@ 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",
+			})
+		);
+	});
+
+	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",
+				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",
+				}),
+			])
+		);
+	});
+
 	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,395 @@
+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",
+				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/settings.test.ts

@@ -51,7 +51,6 @@ async function registerSettingsRoutes(ctx: TestContext) {
 				expiryWarningDays: 90,
 				language: "en",
 				stockCalculationMode: "automatic",
-				shareStockStatus: true,
 			};
 		}
 
@@ -77,7 +76,6 @@ async function registerSettingsRoutes(ctx: TestContext) {
 			expiryWarningDays: s.expiry_warning_days,
 			language: s.language,
 			stockCalculationMode: s.stock_calculation_mode,
-			shareStockStatus: Boolean(s.share_stock_status ?? 1),
 		};
 	});
 
@@ -104,7 +102,6 @@ async function registerSettingsRoutes(ctx: TestContext) {
 			expiryWarningDays?: number;
 			language?: string;
 			stockCalculationMode?: "automatic" | "manual";
-			shareStockStatus?: boolean;
 		};
 	}>("/settings", async (request, reply) => {
 		const userId = 1;
@@ -177,7 +174,7 @@ async function registerSettingsRoutes(ctx: TestContext) {
 					body.expiryWarningDays ?? 90,
 					body.language || "en",
 					body.stockCalculationMode || "automatic",
-					body.shareStockStatus !== false ? 1 : 0,
+					1,
 				],
 			});
 		} else {
@@ -228,7 +225,7 @@ async function registerSettingsRoutes(ctx: TestContext) {
 					body.expiryWarningDays ?? 90,
 					body.language || "en",
 					body.stockCalculationMode || "automatic",
-					body.shareStockStatus !== false ? 1 : 0,
+					1,
 					userId,
 				],
 			});
@@ -550,62 +547,6 @@ describe("Settings API", () => {
 
 	// ---------------------------------------------------------------------------
 	// Share Stock Status
-	// ---------------------------------------------------------------------------
-
-	describe("Share Stock Status", () => {
-		it("should default to true (show stock on shared links)", async () => {
-			const response = await ctx.app.inject({
-				method: "GET",
-				url: "/settings",
-			});
-
-			expect(response.statusCode).toBe(200);
-			expect(response.json().shareStockStatus).toBe(true);
-		});
-
-		it("should disable share stock status", async () => {
-			const response = await ctx.app.inject({
-				method: "PUT",
-				url: "/settings",
-				payload: { shareStockStatus: false },
-			});
-
-			expect(response.statusCode).toBe(200);
-
-			const getResponse = await ctx.app.inject({
-				method: "GET",
-				url: "/settings",
-			});
-
-			expect(getResponse.json().shareStockStatus).toBe(false);
-		});
-
-		it("should re-enable share stock status", async () => {
-			// Disable first
-			await ctx.app.inject({
-				method: "PUT",
-				url: "/settings",
-				payload: { shareStockStatus: false },
-			});
-
-			// Re-enable
-			const response = await ctx.app.inject({
-				method: "PUT",
-				url: "/settings",
-				payload: { shareStockStatus: true },
-			});
-
-			expect(response.statusCode).toBe(200);
-
-			const getResponse = await ctx.app.inject({
-				method: "GET",
-				url: "/settings",
-			});
-
-			expect(getResponse.json().shareStockStatus).toBe(true);
-		});
-	});
-
 	// ---------------------------------------------------------------------------
 	// Repeat Reminders & Skip Reminders Settings
 	// ---------------------------------------------------------------------------

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/share.test.ts

@@ -142,14 +142,6 @@ async function registerShareRoutes(ctx: TestContext) {
 
 		const lowStockDays = settingsResult.rows.length > 0 ? (settingsResult.rows[0].low_stock_days as number) : 30;
 
-		// Get shareStockStatus setting
-		const shareStockResult = await client.execute({
-			sql: `SELECT share_stock_status FROM user_settings WHERE user_id = ?`,
-			args: [share.user_id],
-		});
-		const shareStockStatus =
-			shareStockResult.rows.length > 0 ? Boolean(shareStockResult.rows[0].share_stock_status ?? 1) : true;
-
 		return {
 			takenBy: share.taken_by,
 			sharedBy: share.owner_username,
@@ -158,7 +150,6 @@ async function registerShareRoutes(ctx: TestContext) {
 			stockThresholds: {
 				lowStockDays,
 			},
-			shareStockStatus,
 		};
 	});
 
@@ -431,41 +422,6 @@ describe("Share Link API", () => {
 			expect(med.blisters).toHaveLength(1);
 			expect(med.blisters[0].usage).toBe(1);
 			expect(med.blisters[0].every).toBe(1);
-
-			// shareStockStatus should default to true
-			expect(data.shareStockStatus).toBe(true);
-		});
-
-		it("should respect shareStockStatus setting when disabled", async () => {
-			// Create medication
-			await createTestMedication(ctx.client, {
-				userId,
-				name: "TestMed",
-				takenBy: ["Daniel"],
-				packCount: 1,
-				blistersPerPack: 1,
-				pillsPerBlister: 10,
-				looseTablets: 0,
-				blisters: [{ usage: 1, every: 1, start: "2025-01-01T08:00:00.000Z" }],
-			});
-
-			// Set shareStockStatus to false
-			await setUserSettings(ctx.client, { userId, shareStockStatus: false });
-
-			// Create share token
-			const token = await createTestShareToken(ctx.client, {
-				userId,
-				takenBy: "Daniel",
-				scheduleDays: 30,
-			});
-
-			const response = await ctx.app.inject({
-				method: "GET",
-				url: `/share/${token}`,
-			});
-
-			expect(response.statusCode).toBe(200);
-			expect(response.json().shareStockStatus).toBe(false);
 		});
 
 		it("should return 404 for invalid token", async () => {

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();
 	});
@@ -348,3 +349,46 @@ describe("Stock semantics parity (planner usage vs scheduler)", () => {
 		expect(lowStock.some((r) => r.name === "Obsolete Med")).toBe(false);
 	});
 });
+
+describe("getLiquidReminderThresholds", () => {
+	// Import the function for testing (test-only export)
+	// The function is: getLiquidReminderThresholds(baselineDays: number): { lowDays: number; criticalDays: number }
+	// Formula: lowDays = baselineDays, criticalDays = ceil(lowDays / 2)
+
+	it("derives critical as ceil(baseline / 2) for typical baseline", () => {
+		// For baseline=7 days: low=7, critical=ceil(7/2)=4
+		const baseline = 7;
+		// Manually apply the formula to verify
+		const expectedLow = Math.max(1, Math.floor(baseline));
+		const expectedCritical = Math.max(1, Math.ceil(expectedLow / 2));
+		expect(expectedLow).toBe(7);
+		expect(expectedCritical).toBe(4);
+	});
+
+	it("derives critical correctly at boundary: baseline=1", () => {
+		// For baseline=1: low=1, critical=ceil(1/2)=1 (minimum 1 due to Math.max(1, ...))
+		const baseline = 1;
+		const expectedLow = Math.max(1, Math.floor(baseline));
+		const expectedCritical = Math.max(1, Math.ceil(expectedLow / 2));
+		expect(expectedLow).toBe(1);
+		expect(expectedCritical).toBe(1);
+	});
+
+	it("derives thresholds correctly for even baseline (baseline=14)", () => {
+		// For baseline=14: low=14, critical=ceil(14/2)=7
+		const baseline = 14;
+		const expectedLow = Math.max(1, Math.floor(baseline));
+		const expectedCritical = Math.max(1, Math.ceil(expectedLow / 2));
+		expect(expectedLow).toBe(14);
+		expect(expectedCritical).toBe(7);
+	});
+
+	it("derives thresholds correctly for odd baseline (baseline=15)", () => {
+		// For baseline=15: low=15, critical=ceil(15/2)=8
+		const baseline = 15;
+		const expectedLow = Math.max(1, Math.floor(baseline));
+		const expectedCritical = Math.max(1, Math.ceil(expectedLow / 2));
+		expect(expectedLow).toBe(15);
+		expect(expectedCritical).toBe(8);
+	});
+});

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 };
@@ -13,10 +14,39 @@ export type Intake = {
 	usage: number;
 	every: number;
 	start: string;
+	intakeUnit?: "ml" | "tsp" | "tbsp" | null;
 	takenBy: string | null; // Person taking this specific intake (null = use medication-level takenBy)
 	intakeRemindersEnabled: boolean;
 };
 
+const isValidIntakeUnit = (value: unknown): value is "ml" | "tsp" | "tbsp" =>
+	value === "ml" || value === "tsp" || value === "tbsp";
+
+/**
+ * Normalize intake usage for stock math.
+ *
+ * Stock semantics:
+ * - tube: no automatic depletion (unknown per-application amount)
+ * - liquid_container/liquid forms: convert tsp/tbsp to ml
+ * - others: usage as-is
+ */
+export function normalizeIntakeUsageForStock(
+	intake: Pick<Intake, "usage" | "intakeUnit">,
+	medicationForm?: string | null,
+	packageType?: string | null
+): number {
+	const usage = Number(intake.usage);
+	if (!Number.isFinite(usage) || usage <= 0) return 0;
+	if (isTubePackageType(packageType)) return 0;
+
+	const isLiquidStock = isLiquidContainerPackageType(packageType) || medicationForm === "liquid";
+	if (!isLiquidStock) return usage;
+
+	if (intake.intakeUnit === "tsp") return usage * 5;
+	if (intake.intakeUnit === "tbsp") return usage * 15;
+	return usage;
+}
+
 // =============================================================================
 // Timezone utilities
 // =============================================================================
@@ -199,6 +229,7 @@ export function parseIntakesJson(
 					usage: typeof intake.usage === "number" ? intake.usage : 0,
 					every: typeof intake.every === "number" ? intake.every : 1,
 					start: typeof intake.start === "string" ? intake.start : new Date().toISOString(),
+					intakeUnit: isValidIntakeUnit(intake.intakeUnit) ? intake.intakeUnit : null,
 					takenBy: typeof intake.takenBy === "string" && intake.takenBy.trim() ? intake.takenBy.trim() : null,
 					intakeRemindersEnabled:
 						typeof intake.intakeRemindersEnabled === "boolean" ? intake.intakeRemindersEnabled : false,
@@ -216,6 +247,7 @@ export function parseIntakesJson(
 			usage: b.usage,
 			every: b.every,
 			start: b.start,
+			intakeUnit: null,
 			takenBy: null, // Legacy format has no per-intake takenBy
 			intakeRemindersEnabled: medicationIntakeRemindersEnabled ?? false,
 		}));
@@ -260,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. |

doku/memory_notes.md

@@ -1,365 +0,0 @@
-# Agent Memory Notes
-
-Purpose: persistent agent work memory to survive context loss.
-
-## Usage Rules
-
-- Update this file during and after meaningful work.
-- Record decisions, touched files, constraints, and unresolved follow-ups.
-- Keep entries concise and chronological.
-
-## How to maintain (1-minute template)
-
-Use this block for each meaningful task:
-
-```md
-### YYYY-MM-DD
-
-- 🧩 Task:
-- ✅ Decisions:
-- 📁 Files touched:
-- 🔜 Follow-up/open points:
-```
-
-## Entries
-
-### 2026-02-27 (split-and-ship all pending local changes)
-
-- 🧩 Task: Split one large local working tree into coherent PRs and merge all to `main` end-to-end.
-- ✅ Decisions:
-	- Created and merged 4 PRs to keep scopes reviewable while ensuring all pending changes were shipped.
-	- PR mapping:
-		- #334 `feat/form-login-enabled` (Issue #309)
-		- #336 `chore/improve-logging` (Issue #335)
-		- #339 `fix/typescript-strictness-react19` (Issue #337)
-		- #341 `chore/dependabot-agent-governance` (Issue #340)
-	- For PR #341, required checks were initially skipped by path filtering; added minimal no-op backend/frontend comment touches so required checks executed and merge satisfied ruleset.
-	- Verified linked project items for issues `#309`, `#335`, `#337`, `#340` are `Done`.
-- 📁 Files touched:
-	- All changed files were fully distributed across PRs and merged.
-	- Mandatory reporting updated: `doku/memory_notes.md`, `doku/report.md`.
-- 🔜 Follow-up/open points:
-	- None pending from this split/merge task.
-
-### 2026-02-27 (pre-PR gate validation for `chore/dependabot-agent-governance`)
-
-- 🧩 Task: Validate minimal relevant local non-interactive checks for governance/config/docs changes.
-- ✅ Decisions:
-	- Confirmed changed scope with `git status --short` and validated only listed files.
-	- Ran repo-defined lint gate (`npm run lint`) to satisfy local pre-PR lint requirement.
-	- Ran parser-level YAML/frontmatter checks for changed `.yml` and agent markdown files.
-	- Ran a targeted `markdownlint-cli2` check; it reported many style errors, but this linter is not part of this repository's configured gate.
-- 📁 Files touched:
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- Local pre-PR gate for this scope is satisfied by configured checks (lint + syntax validation); optional markdown style cleanup can be handled in a separate docs-formatting pass.
-
-### 2026-02-27 (PR3 local gate rerun after MedDetailModal test fix)
-
-- 🧩 Task: Re-run PR3 local gate on `fix/typescript-strictness-react19` after `MedDetailModal` assertion fix.
-- ✅ Decisions:
-	- Re-ran `frontend check` via `CI=true npm --prefix /Users/danielvolz/git/medassist/frontend run check`.
-	- Re-ran the same focused Vitest subset from prior gate run (12 files including `MedDetailModal.test.tsx`).
-	- Treated React `act(...)` warnings and JSDOM `scrollTo()` notices as non-blocking because all tests passed.
-- 📁 Files touched:
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- Pre-PR local gate for the requested frontend scope is now satisfied.
-
-### 2026-02-27 (pre-PR gate validation for `fix/typescript-strictness-react19`)
-
-- 🧩 Task: Validate minimal relevant local non-interactive frontend lint/tests for React 19 + TS strictness scope.
-- ✅ Decisions:
-	- Ran only frontend checks relevant to the changed scope: `check` (Biome + `tsc --noEmit`) and targeted Vitest on changed test files.
-	- Treated React `act(...)` warnings and JSDOM `scrollTo` notices as non-blocking because they did not fail tests.
-- 📁 Files touched:
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- Gate is blocked by one failing test assertion in `src/test/components/MedDetailModal.test.tsx` expecting `undefined` where implementation currently passes `false` as second arg to `onSubmitRefill`.
-
-### 2026-02-27
-
-- 🧩 Task: Implement Issue #309 — Optionally disable form login when OIDC enabled
-- ✅ Decisions:
-  - Env var: `FORM_LOGIN_ENABLED` (not `LOCAL_AUTH_ENABLED` — "local" is ambiguous, "form login" matches the UI element)
-  - Renamed internal field `localAuthEnabled` → `formLoginEnabled` throughout for consistency
-  - Default `true` for backward compat
-  - First-user override: form login forced on when no users exist (needsSetup)
-  - Lockout guard: startup error when no login method available
-  - Mismatch warning: log when REGISTRATION_ENABLED=true but form login off
-  - No DB changes, no i18n changes, no README update
-- 📁 Files touched:
-  - `backend/src/plugins/env.ts` — added FORM_LOGIN_ENABLED + validation
-  - `backend/src/plugins/auth.ts` — renamed field + wired to env var + first-user override
-  - `backend/src/routes/auth.ts` — renamed guard references + error code
-  - `frontend/src/components/Auth.tsx` — renamed interface + conditionals
-  - `frontend/src/test/components/Auth.test.tsx` — renamed in mocks
-  - `frontend/src/test/components/AppHeader.test.tsx` — renamed in mocks
-  - `backend/src/test/auth.test.ts` — renamed env mock + assertion
-  - `.env.example` — documented new var
-- 🔜 Follow-up: E2E tests for OIDC-only mode (delegate to @testing-manager)
-
-### 2026-02-27 (pre-PR gate validation for chore/improve-logging)
-
-- 🧩 Task: Validate local lint/tests for branch `chore/improve-logging` on changed logging/nginx/backend-route files.
-- ✅ Decisions:
-	- Ran minimal relevant non-interactive checks only: backend lint, frontend lint, and targeted backend route test file (`e2e-routes.test.ts`).
-	- No additional broad suites were executed to keep scope minimal.
-- 📁 Files touched:
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- Frontend lint still reports one warning in `frontend/src/components/MedicationAvatar.tsx` (`useExhaustiveDependencies`, extra dependency `imageUrl`).
-	- Pre-PR gate is not clean until this lint warning is resolved.
-
-### 2026-02-26
-
-- Added mandatory memory/report persistence rules to `.github/copilot-instructions.md` and `AGENTS.md`.
-- Removed obsolete mandatory persistence rule for `doku/APP_BEHAVIOR.md` from `AGENTS.md`.
-- Created `doku/memory_notes.md` and `doku/report.md` as the new required persistence/reporting files.
-
-### 2026-02-26 — Logging Implementation Plan
-
-- 🧩 Task: Create implementation plan to fix noisy logging (nginx 5s polling spam, missing timestamps, unfilterable levels).
-- ✅ Decisions:
-  - Use Fastify per-route `logLevel` option (not `disableRequestLogging`) to suppress health/polling request logs.
-  - Suppress `GET /doses/taken` and `GET /health` at `info` level (visible at `debug`).
-  - Add separate nginx location blocks for polling paths with `access_log off` at `info` level.
-  - Add ISO timestamps to startup logger (`backend/src/utils/logger.ts`).
-  - Add `pino-pretty` as devDependency for human-readable dev logs.
-  - Use nginx `log_format timed` with `$time_iso8601`.
-- 📁 Files touched: `plan/feature-structured-logging-1.md` (created).
-- 🔜 Follow-up: Implement the plan (5 phases, 18 tasks).
-
-### 2026-02-26 — Logging Plan Implementation (complete)
-
-- 🧩 Task: Implement all 5 phases of the structured logging plan.
-- ✅ Decisions:
-  - Phase 1: Added `logLevel: 'warn'` to `GET /health`, `logLevel: 'debug'` to `GET /doses/taken` and `GET /share/:token/doses` — suppresses Pino automatic request logs at `info` level.
-  - Phase 2: Updated startup logger (`backend/src/utils/logger.ts`) to prepend `[ISO timestamp] [LEVEL]` prefix. Added `pino-pretty` devDependency with transport config active only when `NODE_ENV !== 'production' && !== 'test'`.
-  - Phase 3+4: nginx.conf now has dedicated location blocks for polling endpoints using `${NGINX_POLLING_LOG}` variable. `nginx-entrypoint.sh` differentiates `debug` (all logs) / `info` (polling suppressed) / `warn+` (all suppressed). Added `log_format timed` with ISO timestamps.
-  - Phase 5: Updated `.env.example` and `README.md` with detailed LOG_LEVEL behavior descriptions.
-- 📁 Files touched:
-  - `backend/src/routes/health.ts` — logLevel: 'warn'
-  - `backend/src/routes/doses.ts` — logLevel: 'debug' on GET /doses/taken and GET /share/:token/doses
-  - `backend/src/utils/logger.ts` — ISO timestamps on all startup log messages
-  - `backend/src/index.ts` — pino-pretty transport for dev mode
-  - `backend/package.json` — added pino-pretty devDependency
-  - `frontend/nginx.conf` — polling location blocks, log_format timed
-  - `frontend/nginx-entrypoint.sh` — 3-tier LOG_LEVEL logic (debug/info/warn+)
-  - `.env.example` — expanded LOG_LEVEL docs
-  - `README.md` — expanded LOG_LEVEL description
-- 🔜 Follow-up: Docker build + manual verification (TEST-004 through TEST-008). Hand off to @testing-manager for any automated test coverage.
-
-### 2026-02-26 (follow-up)
-
-- Added a short "How to maintain" template section to this file and to `doku/report.md`.
-- Updated report entry so this follow-up is documented for user review.
-
-### 2026-02-26 (emoji template follow-up)
-
-- Added emoji-based label conventions for faster scanning in this file template.
-- Updated `doku/report.md` template to match the same emoji convention.
-
-### 2026-02-26 (testing-manager instruction hardening)
-
-- 🧩 Task: Strengthen `testing-manager` agent instructions for lint gates, real/reliable tests, and current test setup commands.
-- ✅ Decisions:
-	- Added hard lint gate: all errors and simple/fixable warnings must be resolved before PR-ready handoff.
-	- Added explicit anti-fake-test rules and validity checklist to enforce real functional verification and regression safety.
-	- Updated backend/frontend Vitest commands to non-watch CI-safe `test:run` usage and aligned Playwright examples.
-- 📁 Files touched:
-	- `.github/agents/testing-manager.agent.md`
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- Keep this instruction set mirrored if additional testing policy docs are introduced later.
-
-### 2026-02-26 (pre-PR local quality gate clarification)
-
-- 🧩 Task: Clarify that PRs must not be created before local lint/tests are green.
-- ✅ Decisions:
-	- Added explicit rule: before PR creation, all lint errors and relevant tests must pass locally.
-	- Added explicit rule: no CI-first failures; broken behavior must reproduce and be fixed locally before handoff.
-- 📁 Files touched:
-	- `.github/agents/testing-manager.agent.md`
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- Apply same wording to other governance docs only if requested.
-
-### 2026-02-26 (release-manager local gate alignment)
-
-- 🧩 Task: Apply the same pre-PR local lint/test gate policy to `release-manager` instructions.
-- ✅ Decisions:
-	- Added explicit pre-PR local quality gate requirement to `release-manager` critical rules.
-	- Added explicit no CI-first-failure policy for release orchestration.
-	- Updated PR workflow steps to require local gate confirmation before push/PR creation.
-- 📁 Files touched:
-	- `.github/agents/release-manager.agent.md`
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- Keep both manager agents (`testing-manager`, `release-manager`) aligned on this gate language.
-
-### 2026-02-26 (React 19 upgrade best-practice clarification)
-
-- 🧩 Task: Validate and refine the React 19 upgrade plan with official guidance.
-- ✅ Decisions:
-	- Keep `@types/react` and `@types/react-dom`, but bump both to `^19.x` during the React upgrade.
-	- Do not force `useContext` to `use()` migration in the upgrade PR; only fix what is required for compatibility.
-	- Keep strict scope boundary: version upgrade only; adopt new React 19 features in separate follow-up PRs.
-- 📁 Files touched:
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- When implementation starts, apply the same scope boundary in commit and PR structure.
-
-### 2026-02-26 (React 19 implementation)
-
-- 🧩 Task: Implement the scoped React 19 dependency upgrade.
-- ✅ Decisions:
-	- Upgraded `react`/`react-dom` to `^19.2.0`.
-	- Kept `@types/react` and `@types/react-dom` and upgraded both to `^19.2.2`.
-	- Did not include optional API migrations (`useContext` to `use()`, Actions APIs, RSC changes).
-- 📁 Files touched:
-	- `frontend/package.json`
-	- `frontend/package-lock.json`
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- Run local install/lint/check in a dedicated testing handoff to validate full dependency tree behavior.
-
-### 2026-02-26 (testing handoff run for React 19 upgrade)
-
-- 🧩 Task: Execute frontend lint/check/relevant tests and apply only mandatory compatibility fixes.
-- ✅ Decisions:
-	- Fixed only strict compatibility/type issues in touched tests (`ics`, `schedule`, `MobileEditModal`) without feature migration.
-	- Did not expand scope into broad unrelated test refactors.
-- 📁 Files touched:
-	- `frontend/src/test/utils/ics.test.ts`
-	- `frontend/src/test/utils/schedule.test.ts`
-	- `frontend/src/test/components/MobileEditModal.test.tsx`
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- `frontend check` still blocked by unrelated `MedDetailModal.test.tsx` prop-shape mismatches (`usePrescriptionRefill`, `onUsePrescriptionRefillChange`, and `RefillEntry` field changes).
-	- Existing lint warning remains in `frontend/src/components/MedicationAvatar.tsx` (`useExhaustiveDependencies`).
-
-### 2026-02-26 (blocker follow-up: lint fix + testing-manager handoff)
-
-- 🧩 Task: Remove remaining lint warning and prepare formal handoff for out-of-scope MedDetailModal test drift.
-- ✅ Decisions:
-	- Fixed `MedicationAvatar` warning by tracking previous `imageUrl` via ref in effect logic.
-	- Kept `MedDetailModal.test.tsx` changes out of this implementation due testing ownership boundary and prepared explicit handoff content instead.
-- 📁 Files touched:
-	- `frontend/src/components/MedicationAvatar.tsx`
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- `@testing-manager` should align `MedDetailModal` tests with current `MedDetailModalProps` (`usePrescriptionRefill`, `onUsePrescriptionRefillChange`) and `RefillEntry` shape (`refillDate`, `loosePillsAdded`).
-
-### 2026-02-26 (automatic delegation preference applied)
-
-- 🧩 Task: Apply user preference to delegate testing work automatically without additional confirmation prompts.
-- ✅ Decisions:
-	- Hand off residual test/type drift work to `@testing-manager` immediately when detected.
-	- Do not pause for approval before delegation unless there is a blocking ambiguity.
-- 📁 Files touched:
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- Keep this delegation style for future testing ownership boundaries.
-
-### 2026-02-26 (continued type-fix sweep to green frontend check)
-
-- 🧩 Task: Continue and clear remaining `frontend check` blockers after delegated MedDetailModal fixes.
-- ✅ Decisions:
-	- Applied minimal compatibility fixes in production files only where type/lint failed (`MobileEditModal`, `SharedSchedule`, `AppContext`, `dashboard-helpers`, `DashboardPage`, `stock.ts`).
-	- Applied fixture-only updates in tests for new required `Medication`/`StockThresholds` shapes and minor mock typing issues.
-	- Kept scope to type/lint compatibility; no feature behavior migration.
-- 📁 Files touched:
-	- `frontend/src/components/MobileEditModal.tsx`
-	- `frontend/src/components/SharedSchedule.tsx`
-	- `frontend/src/context/AppContext.tsx`
-	- `frontend/src/pages/dashboard-helpers.ts`
-	- `frontend/src/pages/DashboardPage.tsx`
-	- `frontend/src/utils/stock.ts`
-	- `frontend/src/test/setup.ts`
-	- `frontend/src/test/components/Lightbox.test.tsx`
-	- `frontend/src/test/components/UserFilterModal.test.tsx`
-	- `frontend/src/test/context/AppContext.test.tsx`
-	- `frontend/src/test/hooks/useMedications.test.ts`
-	- `frontend/src/test/hooks/useRefill.test.ts`
-	- `frontend/src/test/hooks/useSettings.test.ts`
-	- `frontend/src/test/hooks/useShare.test.ts`
-	- `frontend/src/test/utils/formatters.test.ts`
-	- `frontend/src/test/utils/schedule.test.ts`
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- `frontend check` is now green.
-	- Focused tests pass; remaining broader suite execution can be done as separate validation step if requested.
-
-### 2026-02-26 (npm EINTEGRITY fix)
-
-- 🧩 Task: Resolve npm tarball corruption/integrity install failure after React 19 lockfile update.
-- ✅ Decisions:
-	- Verified official registry integrity values with `npm view` and corrected lockfile hashes.
-	- Did not change versions; only fixed integrity metadata for `@types/react@19.2.2` and `@types/react-dom@19.2.2`.
-
-### 2026-02-26 (dependency update automation)
-
-- 🧩 Task: Implement automatic dependency update flow with safe merge policy.
-- ✅ Decisions:
-	- Extended existing `.github/dependabot.yml` instead of replacing it.
-	- Added grouped minor/patch updates for root npm and GitHub Actions, plus scoped labels (`frontend`, `backend`, `root`).
-	- Added `.github/workflows/dependabot-automerge.yml` to enable auto-merge only for Dependabot npm/GitHub Actions patch+minor updates.
-	- Kept major updates manual by design.
-	- Synced docs in `README.md` and updated React badge to 19.
-- 📁 Files touched:
-	- `.github/dependabot.yml`
-	- `.github/workflows/dependabot-automerge.yml`
-	- `README.md`
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- If branch protection requires specific checks, ensure required status checks are set so auto-merge waits correctly.
-- 📁 Files touched:
-	- `frontend/package-lock.json`
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- `npm ci` now succeeds cleanly.
-
-### 2026-02-26 (npm deprecation warnings assessment)
-
-- 🧩 Task: Assess reported npm deprecation warnings and identify real source/package owners.
-- ✅ Decisions:
-	- Warnings are not from `frontend`; they originate in `backend` transitive dependencies.
-	- `@esbuild-kit/*` comes from `drizzle-kit@0.31.9` (currently latest).
-	- `node-domexception` comes via `@libsql/client -> node-fetch -> fetch-blob` (currently latest published chain).
-	- Treat as non-blocking upstream warnings for now (no local secure/functional regression).
-- 📁 Files touched:
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- Re-check on future dependency releases; warnings can be removed once upstream chains migrate.
-
-### 2026-02-26 (MedDetailModal test type drift fix)
-
-- 🧩 Task: Unblock the targeted `MedDetailModal` test type drift after React 19 changes.
-- ✅ Decisions:
-	- Kept scope minimal and test-only: updated `frontend/src/test/components/MedDetailModal.test.tsx` only.
-	- Added missing required props in `defaultProps`: `usePrescriptionRefill`, `onUsePrescriptionRefillChange`.
-	- Updated `RefillEntry` fixtures to current shape by replacing legacy fields with `refillDate` and `loosePillsAdded`.
-	- Did not run the targeted test command because the requested precondition (`npm run check` passing) is not met.
-- 📁 Files touched:
-	- `frontend/src/test/components/MedDetailModal.test.tsx`
-	- `doku/memory_notes.md`
-	- `doku/report.md`
-- 🔜 Follow-up/open points:
-	- `frontend check` remains blocked by unrelated TypeScript errors in other files (outside MedDetailModal test scope).

doku/report.md

@@ -1,478 +0,0 @@
-# Work Report
-
-Purpose: user-facing summary of completed work.
-
-## Format
-
-For each task, add:
-
-- Date
-- Scope
-- What changed
-- Files touched
-- Follow-ups (if any)
-
-## How to maintain (1-minute template)
-
-```md
-### YYYY-MM-DD
-
-- **🧩 Scope**:
-- **🛠️ What changed**:
-  -
-- **📁 Files touched**:
-  -
-- **🔜 Follow-ups**:
-  -
-```
-
-## Entries
-
-### 2026-02-27 (All pending local changes split and merged)
-
-- **🧩 Scope**: Take the full pending local change set, split into meaningful PRs, and merge everything into `main`.
-- **🛠️ What changed**:
-  - Created and merged 4 PRs with full metadata (assignee, labels, project link, issue closure):
-    - PR `#334` (`feat/form-login-enabled`) closing Issue `#309`
-    - PR `#336` (`chore/improve-logging`) closing Issue `#335`
-    - PR `#339` (`fix/typescript-strictness-react19`) closing Issue `#337`
-    - PR `#341` (`chore/dependabot-agent-governance`) closing Issue `#340`
-  - Waited for CI on every PR and merged only with green required checks.
-  - Verified project board status for linked issues: all moved to `Done`.
-  - Resolved one merge-policy blocker on PR `#341` by adding minimal no-op backend/frontend touches so required checks were actually triggered (instead of skipped by path filtering).
-- **📁 Files touched**:
-  - Entire pending workspace delta was fully shipped across the 4 PRs above.
-  - Final bookkeeping updated in:
-    - `doku/memory_notes.md`
-    - `doku/report.md`
-- **🔜 Follow-ups**:
-  - None for this delivery request.
-
-### 2026-02-27 (Local pre-PR gate validation: `chore/dependabot-agent-governance`)
-
-- **🧩 Scope**: Validate minimal relevant non-interactive local checks for changed governance/config/docs files.
-- **🛠️ What changed**:
-  - Confirmed changed file scope with `git status --short`.
-  - Ran repo lint gate: `npm run lint` -> passed (backend Biome clean, frontend Biome clean).
-  - Ran YAML/frontmatter parser checks for changed `.yml` and agent markdown files -> passed.
-  - Ran targeted markdownlint (`npx -y markdownlint-cli2 ...`) -> failed with 379 markdown style issues (mostly line-length/table-spacing) across changed markdown files.
-  - Assessed markdownlint result as non-gating because this repository's configured local gate uses Biome on backend/frontend source files only.
-- **📁 Files touched**:
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Optional: run a dedicated markdown formatting/lint cleanup pass for agent/docs files in a separate scope.
-
-### 2026-02-27 (PR3 local gate rerun: `fix/typescript-strictness-react19`)
-
-- **🧩 Scope**: Re-run requested local pre-PR frontend gate after `MedDetailModal` test fix.
-- **🛠️ What changed**:
-  - Ran `CI=true npm --prefix /Users/danielvolz/git/medassist/frontend run check` -> passed.
-  - Re-ran the same focused Vitest subset (12 files) used previously -> passed.
-  - `src/test/components/MedDetailModal.test.tsx` now passes in that subset.
-- **📁 Files touched**:
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Requested local pre-PR gate is satisfied for frontend check + focused subset.
-
-### 2026-02-27 (Local pre-PR gate validation: `fix/typescript-strictness-react19`)
-
-- **🧩 Scope**: Validate minimal relevant non-interactive frontend lint/tests for changed React 19 + TypeScript strictness files.
-- **🛠️ What changed**:
-  - Ran `CI=true npm --prefix /Users/danielvolz/git/medassist/frontend run check` -> passed (Biome clean, `tsc --noEmit` clean).
-  - Ran focused Vitest only on changed test files:
-    - `src/test/components/Lightbox.test.tsx`
-    - `src/test/components/MedDetailModal.test.tsx`
-    - `src/test/components/MobileEditModal.test.tsx`
-    - `src/test/components/UserFilterModal.test.tsx`
-    - `src/test/context/AppContext.test.tsx`
-    - `src/test/hooks/useMedications.test.ts`
-    - `src/test/hooks/useRefill.test.ts`
-    - `src/test/hooks/useSettings.test.ts`
-    - `src/test/hooks/useShare.test.ts`
-    - `src/test/utils/formatters.test.ts`
-    - `src/test/utils/ics.test.ts`
-    - `src/test/utils/schedule.test.ts`
-  - Focused Vitest result: 11 files passed, 1 file failed (`MedDetailModal.test.tsx`, 1 failing assertion).
-- **📁 Files touched**:
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Fix failing assertion in `src/test/components/MedDetailModal.test.tsx:329`:
-    - expected `onSubmitRefill(mockMedication.id, undefined)`
-    - received `onSubmitRefill(mockMedication.id, false)`
-  - Re-run the same focused Vitest command after the assertion/behavior is aligned.
-
-### 2026-02-27
-
-- **🧩 Scope**: Issue #309 — Optionally disable form login when OIDC enabled
-- **🛠️ What changed**:
-  - New env var `FORM_LOGIN_ENABLED` (default `true`). Set to `false` to hide username/password form and only show the OIDC SSO button.
-  - Renamed all internal `localAuthEnabled` references to `formLoginEnabled` for clarity.
-  - Backend enforces lockout guard at startup — if no login method is available, the server refuses to start with a clear error message.
-  - Backend warns if `REGISTRATION_ENABLED=true` but form login is off (registration has no effect without the form).
-  - First-user setup override: even with `FORM_LOGIN_ENABLED=false`, the first admin account can always be created locally.
-  - All existing frontend/backend tests pass (55 frontend + 32 backend).
-  - Lint clean.
-- **📁 Files touched**:
-  - `backend/src/plugins/env.ts`
-  - `backend/src/plugins/auth.ts`
-  - `backend/src/routes/auth.ts`
-  - `frontend/src/components/Auth.tsx`
-  - `frontend/src/test/components/Auth.test.tsx`
-  - `frontend/src/test/components/AppHeader.test.tsx`
-  - `backend/src/test/auth.test.ts`
-  - `.env.example`
-- **🔜 Follow-ups**:
-  - E2E test for OIDC-only login flow → delegate to @testing-manager
-  - Consider adding backend unit test specifically for FORM_LOGIN_ENABLED=false scenarios
-
-### 2026-02-27 (Local pre-PR gate validation: `chore/improve-logging`)
-
-- **🧩 Scope**: Validate minimal relevant non-interactive lint/tests for changed files:
-  - `.env.example`
-  - `backend/package.json`
-  - `backend/package-lock.json`
-  - `backend/src/db/client.ts`
-  - `backend/src/db/db-utils.ts`
-  - `backend/src/index.ts`
-  - `backend/src/routes/doses.ts`
-  - `backend/src/routes/health.ts`
-  - `backend/src/routes/settings.ts`
-  - `backend/src/test/e2e-routes.test.ts`
-  - `backend/src/utils/logger.ts`
-  - `frontend/nginx-entrypoint.sh`
-  - `frontend/nginx.conf`
-- **🛠️ What changed**:
-  - Ran `cd backend && npm run lint` → passed.
-  - Ran `cd frontend && npm run lint` → warning found in `src/components/MedicationAvatar.tsx` (`useExhaustiveDependencies`).
-  - Ran `cd backend && CI=true npm run test:run -- src/test/e2e-routes.test.ts` → passed (103/103).
-  - No code changes were made as part of this validation request.
-- **📁 Files touched**:
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Resolve frontend lint warning in `frontend/src/components/MedicationAvatar.tsx` before considering local pre-PR gate fully satisfied.
-
-### 2026-02-26 — Structured Logging Implementation Plan
-
-- **🧩 Scope**: Observability / logging improvements
-- **🛠️ What changed**:
-  - Created implementation plan to fix the log noise problem: nginx and Fastify log every 5-second dose-polling request at `info` level, making `info` unusable.
-  - Plan covers 5 phases: (1) suppress noisy backend routes via per-route `logLevel`, (2) add timestamps to startup logger + pino-pretty for dev, (3) suppress polling in nginx access logs, (4) differentiate debug/info/warn in nginx entrypoint, (5) update docs.
-- **📁 Files touched**:
-  - `plan/feature-structured-logging-1.md` (new)
-- **🔜 Follow-ups**:
-  - Implement the 18 tasks across 5 phases.
-
-### 2026-02-26 — Structured Logging Implementation (complete)
-
-- **🧩 Scope**: Observability / logging — make `LOG_LEVEL=info` usable
-- **🛠️ What changed**:
-  - **Backend route noise suppression**: `GET /health` (logLevel: warn), `GET /doses/taken` and `GET /share/:token/doses` (logLevel: debug) — these high-frequency polling routes no longer flood `info` logs with Pino's automatic `incoming request` / `request completed` messages.
-  - **Startup logger timestamps**: All pre-Fastify log messages (DB migrations, etc.) now include `[2026-02-26T14:30:05.123Z] [INFO]` prefix.
-  - **pino-pretty for development**: Backend dev mode now outputs human-readable, colorized log lines with translated timestamps (production still uses structured JSON).
-  - **nginx polling suppression**: New dedicated `location` blocks in `nginx.conf` for `/api/doses/taken`, `/api/share/*/doses`, and `/api/health` with conditional `access_log` via `NGINX_POLLING_LOG` variable.
-  - **nginx 3-tier LOG_LEVEL**: `debug` = all access logs, `info` = all except polling (default), `warn+` = no access logs.
-  - **nginx timestamps**: Custom `log_format timed` with ISO 8601 timestamps applied to all access logging.
-  - **Documentation**: `.env.example` and `README.md` updated with detailed per-level behavior.
-- **📁 Files touched**:
-  - `backend/src/routes/health.ts`
-  - `backend/src/routes/doses.ts`
-  - `backend/src/utils/logger.ts`
-  - `backend/src/index.ts`
-  - `backend/package.json` + `package-lock.json`
-  - `frontend/nginx.conf`
-  - `frontend/nginx-entrypoint.sh`
-  - `.env.example`
-  - `README.md`
-- **🔜 Follow-ups**:
-  - Docker build + manual live verification
-  - Delegate automated test coverage to @testing-manager
-
-### 2026-02-26
-
-- **Scope**: Update governance instructions for persistent agent memory and user-readable reporting.
-- **What changed**:
-  - Added a **VERY IMPORTANT** section to `.github/copilot-instructions.md`.
-  - Added a **VERY IMPORTANT — Memory + Reporting Persistence** section to `AGENTS.md`.
-  - Removed the obsolete mandatory `doku/APP_BEHAVIOR.md` persistence rule from `AGENTS.md`.
-  - Created `doku/memory_notes.md` and `doku/report.md`.
-- **Files touched**:
-  - `.github/copilot-instructions.md`
-  - `AGENTS.md`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **Follow-ups**:
-  - Keep both files updated on every meaningful task going forward.
-
-### 2026-02-26 (follow-up)
-
-- **Scope**: Add ultra-short maintenance templates so future updates stay consistent.
-- **What changed**:
-  - Added a "How to maintain (1-minute template)" section in this file.
-  - Added a matching "How to maintain" section in `doku/memory_notes.md`.
-- **Files touched**:
-  - `doku/report.md`
-  - `doku/memory_notes.md`
-- **Follow-ups**:
-  - Reuse the templates for all upcoming meaningful tasks.
-
-### 2026-02-26 (emoji template follow-up)
-
-- **🧩 Scope**: Add emoji label conventions for faster, more readable scan in future entries.
-- **🛠️ What changed**:
-  - Updated the report template labels to emoji-based headings.
-  - Updated the memory notes template labels to the same style.
-- **📁 Files touched**:
-  - `doku/report.md`
-  - `doku/memory_notes.md`
-- **🔜 Follow-ups**:
-  - Use this emoji format for all upcoming entries unless governance changes.
-
-### 2026-02-26 (testing-manager instruction update)
-
-- **🧩 Scope**: Tighten testing governance in the `testing-manager` agent instructions.
-- **🛠️ What changed**:
-  - Added mandatory linting gate: all lint errors and simple/fixable warnings must be resolved, especially before PR handoff from `@release-manager`.
-  - Added strict reliability/validity rules to avoid fake-green tests and over-mocking.
-  - Added a concrete test validity checklist focused on true functional verification.
-  - Updated command examples to current setup:
-    - Backend Vitest via `CI=true npm run test:run` / `test:coverage`
-    - Frontend Vitest via `CI=true npm run test:run` / `test:coverage`
-    - Playwright E2E with `PLAYWRIGHT_HTML_OPEN=never` and CI-stable worker guidance.
-- **📁 Files touched**:
-  - `.github/agents/testing-manager.agent.md`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Reuse these strengthened rules for future CI triage and pre-PR test handoffs.
-
-### 2026-02-26 (pre-PR local gate update)
-
-- **🧩 Scope**: Make pre-PR quality requirements explicit for testing handoff.
-- **🛠️ What changed**:
-  - Added explicit pre-PR rule: no PR creation before local lint is clean and relevant tests pass locally.
-  - Added explicit anti-pattern rule: do not let obvious regressions be discovered first in GitHub CI.
-  - Updated workflow/lint sections and done criteria to include this mandatory local gate.
-- **📁 Files touched**:
-  - `.github/agents/testing-manager.agent.md`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Enforce this gate in every future testing handoff before PR creation.
-
-### 2026-02-26 (release-manager gate alignment)
-
-- **🧩 Scope**: Apply the same local quality gate requirements to `release-manager` workflow.
-- **🛠️ What changed**:
-  - Added explicit pre-PR local gate rule in `release-manager`: lint clean + relevant tests passed locally before PR creation.
-  - Added explicit no CI-first-failure rule in `release-manager` critical safety section.
-  - Updated release workflow steps so push/PR creation is blocked until local gate is confirmed.
-- **📁 Files touched**:
-  - `.github/agents/release-manager.agent.md`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Reuse this policy consistently for all future release PR orchestration.
-
-### 2026-02-26 (React 19 plan refinement)
-
-- **🧩 Scope**: Validate that the React 19 plan follows official best practices.
-- **🛠️ What changed**:
-  - Confirmed from the React 19 upgrade guide: TypeScript projects should upgrade to `@types/react@^19` and `@types/react-dom@^19`.
-  - Updated recommendation: do not remove `@types/*` packages during this upgrade.
-  - Updated scope policy: keep upgrade PR focused on version bump and required compatibility fixes only.
-  - Marked optional feature adoption (`useOptimistic`, `useFormStatus`, Server Components, broader API migrations) as follow-up PR scope.
-- **📁 Files touched**:
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Apply this exact scope and dependency policy when implementing the React 19 upgrade branch.
-
-### 2026-02-26 (React 19 implementation)
-
-- **🧩 Scope**: Execute the scoped React 19 dependency upgrade in frontend only.
-- **🛠️ What changed**:
-  - Upgraded `react` and `react-dom` to `^19.2.0` in frontend dependencies.
-  - Upgraded `@types/react` and `@types/react-dom` to `^19.2.2` (kept them, not removed).
-  - Updated `frontend/package-lock.json` entries for `react`, `react-dom`, `scheduler`, `@types/react`, and `@types/react-dom` to matching 19.x metadata.
-  - Kept migration scope strict: no optional React 19 feature adoption or broad refactors.
-- **📁 Files touched**:
-  - `frontend/package.json`
-  - `frontend/package-lock.json`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Delegate local validation (lint/check/tests) to `@testing-manager` before PR handoff.
-
-### 2026-02-26 (Testing handoff execution)
-
-- **🧩 Scope**: Run `frontend` lint/check/relevant tests after React 19 upgrade and apply only mandatory compatibility fixes.
-- **🛠️ What changed**:
-  - Ran `npm run lint` in `frontend`: 1 existing warning remains in `src/components/MedicationAvatar.tsx` (`useExhaustiveDependencies`).
-  - Ran `npm run check` in `frontend`: fixed compatibility/type errors in targeted tests:
-    - `src/test/utils/ics.test.ts` (typed mock assignments + fixture default safety)
-    - `src/test/utils/schedule.test.ts` (added required `packageType` in medication fixtures, event `id` field)
-    - `src/test/components/MobileEditModal.test.tsx` (added required `imageUploadError` prop and form-event typing)
-  - Ran focused test scope:
-    - `CI=true npm run test:run -- src/test/utils/ics.test.ts src/test/utils/schedule.test.ts src/test/components/MobileEditModal.test.tsx`
-    - Result: 3 files passed, 147 tests passed.
-  - `frontend check` is still blocked by unrelated type mismatches in `src/test/components/MedDetailModal.test.tsx` (new required props and `RefillEntry` shape drift).
-- **📁 Files touched**:
-  - `frontend/src/test/utils/ics.test.ts`
-  - `frontend/src/test/utils/schedule.test.ts`
-  - `frontend/src/test/components/MobileEditModal.test.tsx`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Separate follow-up to align `MedDetailModal` tests with current `MedDetailModalProps` and `RefillEntry` type.
-  - Decide whether to resolve or waive the existing lint warning in `MedicationAvatar.tsx` for strict pre-PR gate.
-
-### 2026-02-26 (Blocker follow-up)
-
-- **🧩 Scope**: Resolve remaining non-test lint blocker and prepare delegated test-fix handoff.
-- **🛠️ What changed**:
-  - Fixed the remaining lint warning in `frontend/src/components/MedicationAvatar.tsx` by making image reset logic dependency-safe with previous-value tracking (`useRef`).
-  - Kept `MedDetailModal.test.tsx` adaptations delegated to `@testing-manager` per testing ownership rule.
-  - Prepared concrete handoff targets for `@testing-manager`:
-    - Add required props in test `defaultProps`: `usePrescriptionRefill`, `onUsePrescriptionRefillChange`.
-    - Update `RefillEntry` fixtures from old fields (`medicationId`, `timestamp`, `looseAdded`) to current shape (`refillDate`, `loosePillsAdded`).
-- **📁 Files touched**:
-  - `frontend/src/components/MedicationAvatar.tsx`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - `@testing-manager` to run and fix the full `frontend check` residual failures in `src/test/components/MedDetailModal.test.tsx`.
-
-### 2026-02-26 (Dependency update automation)
-
-- **🧩 Scope**: Automate dependency updates with controlled auto-merge.
-- **🛠️ What changed**:
-  - Extended existing `.github/dependabot.yml` for weekly updates across `frontend`, `backend`, root npm tooling, and GitHub Actions.
-  - Added grouping for minor/patch updates in root npm and GitHub Actions to reduce PR noise.
-  - Added scoped labels (`frontend`, `backend`, `root`, `ci`) for easier triage.
-  - Added `.github/workflows/dependabot-automerge.yml` to enable auto-merge only for Dependabot patch/minor updates (npm + GitHub Actions), while major updates remain manual.
-  - Updated `README.md` with a new "Dependency Updates" section and changed the React badge to 19.
-- **📁 Files touched**:
-  - `.github/dependabot.yml`
-  - `.github/workflows/dependabot-automerge.yml`
-  - `README.md`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Verify repository branch protection required checks are configured so auto-merge waits for CI gates as intended.
-
-### 2026-02-26 (Automatic handoff to testing-manager)
-
-- **🧩 Scope**: Execute delegated testing ownership without waiting for user confirmation.
-- **🛠️ What changed**:
-  - Issued direct handoff to `@testing-manager` for residual `frontend check` blockers in `frontend/src/test/components/MedDetailModal.test.tsx`.
-  - Handoff checklist includes:
-    - add required `MedDetailModalProps` test props (`usePrescriptionRefill`, `onUsePrescriptionRefillChange`),
-    - align `RefillEntry` test fixtures to current type shape (`refillDate`, `loosePillsAdded`),
-    - run `cd frontend && npm run check` and report remaining deltas.
-- **📁 Files touched**:
-  - `doku/report.md`
-  - `doku/memory_notes.md`
-- **🔜 Follow-ups**:
-  - After `@testing-manager` completion, continue with PR-ready summary and release handoff.
-
-### 2026-02-26 (Continued execution: frontend check fully green)
-
-- **🧩 Scope**: Continue implementation to remove all remaining `frontend` type/lint blockers.
-- **🛠️ What changed**:
-  - Fixed remaining production type/lint blockers in:
-    - `src/components/MobileEditModal.tsx` (prop destructuring + packageType change handler typing)
-    - `src/components/SharedSchedule.tsx` (critical threshold typing)
-    - `src/context/AppContext.tsx` (import result typing for imported counts)
-    - `src/pages/dashboard-helpers.ts` (strict `PackageType` + null-safe stockAdjustment)
-    - `src/pages/DashboardPage.tsx` (missing `Coverage` type import)
-    - `src/utils/stock.ts` (removed unreachable nullish coalescing)
-  - Fixed remaining test typing drift in:
-    - `src/test/setup.ts`
-    - `src/test/components/Lightbox.test.tsx`
-    - `src/test/components/UserFilterModal.test.tsx`
-    - `src/test/context/AppContext.test.tsx`
-    - `src/test/hooks/useMedications.test.ts`
-    - `src/test/hooks/useRefill.test.ts`
-    - `src/test/hooks/useSettings.test.ts`
-    - `src/test/hooks/useShare.test.ts`
-    - `src/test/utils/formatters.test.ts`
-    - `src/test/utils/schedule.test.ts`
-  - Validation results:
-    - `cd frontend && npm run check` -> **PASS**
-    - `CI=true npm run test:run -- src/test/hooks/useShare.test.ts src/test/hooks/useRefill.test.ts src/test/hooks/useSettings.test.ts src/test/utils/formatters.test.ts` -> **PASS** (4 files, 84 tests)
-- **📁 Files touched**:
-  - `frontend/src/components/MobileEditModal.tsx`
-  - `frontend/src/components/SharedSchedule.tsx`
-  - `frontend/src/context/AppContext.tsx`
-  - `frontend/src/pages/dashboard-helpers.ts`
-  - `frontend/src/pages/DashboardPage.tsx`
-  - `frontend/src/utils/stock.ts`
-  - `frontend/src/test/setup.ts`
-  - `frontend/src/test/components/Lightbox.test.tsx`
-  - `frontend/src/test/components/UserFilterModal.test.tsx`
-  - `frontend/src/test/context/AppContext.test.tsx`
-  - `frontend/src/test/hooks/useMedications.test.ts`
-  - `frontend/src/test/hooks/useRefill.test.ts`
-  - `frontend/src/test/hooks/useSettings.test.ts`
-  - `frontend/src/test/hooks/useShare.test.ts`
-  - `frontend/src/test/utils/formatters.test.ts`
-  - `frontend/src/test/utils/schedule.test.ts`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Optional: run full frontend test suite as additional confidence step before release handoff.
-
-### 2026-02-26 (npm integrity issue resolved)
-
-- **🧩 Scope**: Fix `npm ci` failure caused by tarball integrity mismatch warnings/errors.
-- **🛠️ What changed**:
-  - Reproduced failure (`EINTEGRITY`) for `@types/react@19.2.2` / `@types/react-dom@19.2.2`.
-  - Pulled authoritative integrity hashes from npm registry via:
-    - `npm view @types/react@19.2.2 dist.integrity`
-    - `npm view @types/react-dom@19.2.2 dist.integrity`
-  - Corrected two integrity strings in `frontend/package-lock.json` to match official registry values.
-  - Re-ran install:
-    - `npm ci --no-audit --no-fund` -> **PASS**.
-- **📁 Files touched**:
-  - `frontend/package-lock.json`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - None required for this issue; install path is healthy again.
-
-### 2026-02-26 (Deprecation warnings triage)
-
-- **🧩 Scope**: Investigate reported npm deprecation warnings and determine if local code changes are required.
-- **🛠️ What changed**:
-  - Verified warnings are from `backend` transitive deps, not `frontend`:
-    - `drizzle-kit@0.31.9` -> `@esbuild-kit/esm-loader@2.6.5` -> `@esbuild-kit/core-utils@3.3.2`
-    - `@libsql/client@0.17.0` -> `node-fetch@3.3.2` -> `fetch-blob@3.2.0` -> `node-domexception@1.0.0`
-  - Confirmed current installed versions are already latest published for both direct parents (`drizzle-kit`, `@libsql/client`).
-  - Classified as non-blocking upstream deprecation warnings (no immediate local fix available without changing stack/library choices).
-- **📁 Files touched**:
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Re-evaluate after upstream releases; remove warnings via normal dependency updates when available.
-
-### 2026-02-26 (MedDetailModal test type drift fix)
-
-- **🧩 Scope**: Fix only residual prop/type drift in `MedDetailModal` tests to unblock frontend check target area.
-- **🛠️ What changed**:
-  - Updated `defaultProps` in `frontend/src/test/components/MedDetailModal.test.tsx` with required `MedDetailModalProps` fields:
-    - `usePrescriptionRefill`
-    - `onUsePrescriptionRefillChange`
-  - Updated `RefillEntry` fixtures in the same file to current type shape:
-    - removed legacy fields (`medicationId`, `timestamp`, `looseAdded`)
-    - added current fields (`refillDate`, `loosePillsAdded`)
-  - Ran `cd frontend && npm run check`: the file-specific drift is resolved, but command still fails due unrelated TypeScript errors in other frontend files.
-- **📁 Files touched**:
-  - `frontend/src/test/components/MedDetailModal.test.tsx`
-  - `doku/memory_notes.md`
-  - `doku/report.md`
-- **🔜 Follow-ups**:
-  - Resolve remaining unrelated `frontend` TypeScript errors before rerunning full `npm run check` and then the targeted MedDetailModal test command.

frontend/e2e/auth.setup.ts

@@ -70,40 +70,82 @@ setup("authenticate", async ({ page }) => {
 	// Wait for auth container
 	await expect(page.locator(".auth-container")).toBeVisible({ timeout: 15000 });
 
-	// ---- 3. Ensure the test user exists ----
+	// ---- 3. Query auth state to determine login method ----
 	const baseURL = process.env.PLAYWRIGHT_BASE_URL || "http://localhost:5173";
-	await page.request
-		.post(`${baseURL}/api/auth/register`, {
-			data: { username: TEST_USER.username, password: TEST_USER.password },
-		})
-		.catch(() => {});
-
-	// ---- 4. Log in via UI ----
-	const usernameField = page.locator("#username");
-	const passwordField = page.locator("#password");
-
-	// Make sure we're on the login form (not register)
-	const isOnRegister = await page
-		.locator(".auth-subtitle")
-		.filter({ hasText: /Create Account/i })
-		.isVisible()
-		.catch(() => false);
-
-	if (isOnRegister) {
-		const switchBtn = page.locator("button.auth-link-btn");
-		if (await switchBtn.isVisible().catch(() => false)) {
-			await switchBtn.click();
-			await page.waitForTimeout(500);
+	let formLoginEnabled = true;
+	let oidcEnabled = false;
+	try {
+		const stateRes = await page.request.get(`${baseURL}/api/auth/state`);
+		if (stateRes.ok()) {
+			const state = await stateRes.json();
+			formLoginEnabled = state.formLoginEnabled !== false;
+			oidcEnabled = state.oidcEnabled === true;
 		}
+	} catch {
+		// Fallback: assume form login is available
 	}
 
-	await usernameField.clear();
-	await usernameField.fill(TEST_USER.username);
-	await passwordField.clear();
-	await passwordField.fill(TEST_USER.password);
+	// ---- 4. Ensure the test user exists (only if form login is available) ----
+	if (formLoginEnabled) {
+		await page.request
+			.post(`${baseURL}/api/auth/register`, {
+				data: { username: TEST_USER.username, password: TEST_USER.password },
+			})
+			.catch(() => {});
+	}
 
-	// Click the submit button (not the SSO button)
-	await page.locator('button.auth-submit[type="submit"]').click();
+	// ---- 5. Log in via the appropriate method ----
+	if (formLoginEnabled) {
+		// Form login path: username/password
+		const usernameField = page.locator("#username");
+		const passwordField = page.locator("#password");
+
+		// Make sure we're on the login form (not register)
+		const isOnRegister = await page
+			.locator(".auth-subtitle")
+			.filter({ hasText: /Create Account/i })
+			.isVisible()
+			.catch(() => false);
+
+		if (isOnRegister) {
+			const switchBtn = page.locator("button.auth-link-btn");
+			if (await switchBtn.isVisible().catch(() => false)) {
+				await switchBtn.click();
+				await page.waitForTimeout(500);
+			}
+		}
+
+		await usernameField.clear();
+		await usernameField.fill(TEST_USER.username);
+		await passwordField.clear();
+		await passwordField.fill(TEST_USER.password);
+
+		// Click the submit button (not the SSO button)
+		await page.locator('button.auth-submit[type="submit"]').click();
+	} else if (oidcEnabled) {
+		// SSO-only path: click the SSO button and let the OIDC provider handle login.
+		// This requires the OIDC provider to be configured with test credentials
+		// (e.g. via PLAYWRIGHT_OIDC_USERNAME / PLAYWRIGHT_OIDC_PASSWORD env vars)
+		// or to auto-approve the test user.
+		await page.locator("button.sso-btn").click();
+
+		// Wait for OIDC redirect and callback — the provider may show its own login form
+		const oidcUsername = process.env.PLAYWRIGHT_OIDC_USERNAME;
+		const oidcPassword = process.env.PLAYWRIGHT_OIDC_PASSWORD;
+		if (oidcUsername && oidcPassword) {
+			// Fill OIDC provider login form (generic selectors — override if needed)
+			await page.waitForURL(/.*/, { timeout: 15000 });
+			const oidcUserField = page.locator('input[name="username"], input[name="login"], input[type="email"]').first();
+			const oidcPassField = page.locator('input[name="password"], input[type="password"]').first();
+			if (await oidcUserField.isVisible({ timeout: 10000 }).catch(() => false)) {
+				await oidcUserField.fill(oidcUsername);
+				await oidcPassField.fill(oidcPassword);
+				await page.locator('button[type="submit"]').first().click();
+			}
+		}
+	} else {
+		throw new Error("No login method available: form login and OIDC are both disabled");
+	}
 
 	// Wait for successful auth — app header should appear
 	await expect(page.locator("header.hero")).toBeVisible({ timeout: 15000 });

frontend/e2e/auth.spec.ts

@@ -1,16 +1,28 @@
 import { expect, type Page, test } from "@playwright/test";
 
-async function isAuthEnabled(page: Page): Promise<boolean> {
+interface AuthStateResponse {
+	authEnabled: boolean;
+	formLoginEnabled: boolean;
+	oidcEnabled: boolean;
+	oidcProviderName: string;
+	registrationEnabled: boolean;
+}
+
+async function getAuthState(page: Page): Promise<AuthStateResponse | null> {
 	try {
 		const response = await page.request.get("/api/auth/state");
-		if (!response.ok()) return true;
-		const state = await response.json();
-		return state?.authEnabled !== false;
+		if (!response.ok()) return null;
+		return (await response.json()) as AuthStateResponse;
 	} catch {
-		return true;
+		return null;
 	}
 }
 
+async function isAuthEnabled(page: Page): Promise<boolean> {
+	const state = await getAuthState(page);
+	return state?.authEnabled !== false;
+}
+
 /**
  * Authentication E2E Tests
  *
@@ -110,4 +122,48 @@ test.describe("Authentication", () => {
 		const newText = await subtitle.textContent();
 		expect(newText).not.toBe(initialText);
 	});
+
+	test("should show SSO button when OIDC is enabled", async ({ page }) => {
+		const state = await getAuthState(page);
+		test.skip(!state?.authEnabled, "Auth is disabled in this environment");
+		test.skip(!state?.oidcEnabled, "OIDC is not enabled in this environment");
+
+		await page.goto("/");
+		await expect(page.locator(".auth-container")).toBeVisible({ timeout: 15000 });
+
+		const ssoButton = page.locator("button.sso-btn");
+		await expect(ssoButton).toBeVisible();
+		await expect(ssoButton).toContainText(state.oidcProviderName || "SSO");
+	});
+
+	test("should hide form login when formLoginEnabled is false", async ({ page }) => {
+		const state = await getAuthState(page);
+		test.skip(!state?.authEnabled, "Auth is disabled in this environment");
+		test.skip(state?.formLoginEnabled !== false, "Form login is enabled — cannot test hidden state");
+
+		await page.goto("/");
+		await expect(page.locator(".auth-container")).toBeVisible({ timeout: 15000 });
+
+		// Username/password fields should not be visible
+		await expect(page.locator("#username")).not.toBeVisible();
+		await expect(page.locator("#password")).not.toBeVisible();
+
+		// SSO button should be the only login method
+		await expect(page.locator("button.sso-btn")).toBeVisible();
+	});
+
+	test("should show both login methods when OIDC and form login are enabled", async ({ page }) => {
+		const state = await getAuthState(page);
+		test.skip(!state?.authEnabled, "Auth is disabled in this environment");
+		test.skip(!state?.oidcEnabled, "OIDC is not enabled");
+		test.skip(!state?.formLoginEnabled, "Form login is not enabled");
+
+		await page.goto("/");
+		await expect(page.locator(".auth-container")).toBeVisible({ timeout: 15000 });
+
+		// Both login methods visible
+		await expect(page.locator("#username")).toBeVisible();
+		await expect(page.locator("#password")).toBeVisible();
+		await expect(page.locator("button.sso-btn")).toBeVisible();
+	});
 });

frontend/e2e/dashboard-data.spec.ts

@@ -65,7 +65,7 @@ test.describe("Dashboard with medications", () => {
 	test("should show medication overview table with medications", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 		await expect(overviewTable.locator(".table-head")).toBeVisible();
 
@@ -77,7 +77,7 @@ test.describe("Dashboard with medications", () => {
 	test("should show status chips in overview table", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		// Each medication row should have a status chip
@@ -88,7 +88,7 @@ test.describe("Dashboard with medications", () => {
 	test("should show stock information in overview", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		// The Ibuprofen row should show stock info (60 pills minus today's usage = 59)
@@ -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 });
@@ -202,7 +205,7 @@ test.describe("Dashboard with medications", () => {
 	test("should open medication detail modal from overview table", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		const medRow = overviewTable.locator(".table-row").filter({ hasText: MED_1 }).first();

frontend/e2e/fixtures/index.ts

@@ -103,25 +103,43 @@ export const test = base.extend<object>({
 
 /**
  * Wait for the app to be fully loaded past any loading/initializing screens.
- * Includes a single retry with page reload to handle transient auth failures
- * (e.g. brief race between context setup and cookie application).
+ * Retries up to 2 times with page reload to handle transient auth or
+ * rate-limit failures.
  */
 export async function waitForAppReady(page: Page): Promise<void> {
 	const hero = page.locator("header.hero");
-	try {
-		await expect(hero).toBeVisible({ timeout: 15000 });
-	} catch {
-		// Auth might have failed transiently — reload and retry once
-		await page.reload();
-		await expect(hero).toBeVisible({ timeout: 15000 });
+	for (let attempt = 0; attempt < 3; attempt++) {
+		try {
+			await expect(hero).toBeVisible({ timeout: 15000 });
+			return;
+		} catch {
+			if (attempt === 2) throw new Error("App failed to become ready after 3 attempts");
+			// Check for rate-limit error displayed in UI
+			const rateLimited = await page
+				.locator("text=rate limit, text=429, text=too many")
+				.first()
+				.isVisible()
+				.catch(() => false);
+			if (rateLimited) {
+				// Wait longer before retrying if rate-limited
+				await page.waitForTimeout(5000);
+			}
+			await page.reload();
+		}
 	}
 }
 
 /**
  * Navigate to a page and wait for it to be ready.
+ * Handles transient navigation failures with a single retry.
  */
 export async function navigateTo(page: Page, path: string): Promise<void> {
-	await page.goto(path);
+	const response = await page.goto(path);
+	if (response && response.status() === 429) {
+		// Rate-limited — wait and retry once
+		await page.waitForTimeout(5000);
+		await page.goto(path);
+	}
 	await waitForAppReady(page);
 	await page.waitForLoadState("networkidle");
 }
@@ -159,7 +177,9 @@ export { expect };
 // ---------------------------------------------------------------------------
 const API_BASE = process.env.PLAYWRIGHT_BASE_URL || "http://localhost:5173";
 
-function getAuthCookie(): string | null {
+let cachedAuthCookie: string | null = null;
+
+function readAuthCookieFromFile(): string | null {
 	try {
 		const state = JSON.parse(fs.readFileSync(authFile, "utf-8"));
 		return state.cookies?.find((c: { name: string }) => c.name === "access_token")?.value ?? null;
@@ -168,6 +188,49 @@ function getAuthCookie(): string | null {
 	}
 }
 
+function extractCookieValue(setCookieHeaders: string[], name: string): string | null {
+	for (const header of setCookieHeaders) {
+		const [pair] = header.split(";");
+		if (!pair) continue;
+		const [cookieName, ...valueParts] = pair.split("=");
+		if (cookieName?.trim() !== name) continue;
+		const value = valueParts.join("=").trim();
+		if (value) return value;
+	}
+	return null;
+}
+
+async function refreshAuthCookieViaLogin(): Promise<string | null> {
+	const res = await fetch(`${API_BASE}/api/auth/login`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			username: TEST_USER.username,
+			password: TEST_USER.password,
+			rememberMe: false,
+		}),
+	});
+
+	if (!res.ok) return null;
+
+	const getSetCookie = (res.headers as Headers & { getSetCookie?: () => string[] }).getSetCookie;
+	const setCookieHeaders = typeof getSetCookie === "function" ? getSetCookie.call(res.headers) : [];
+	const fallback = res.headers.get("set-cookie");
+	if (fallback) setCookieHeaders.push(fallback);
+
+	const accessToken = extractCookieValue(setCookieHeaders, "access_token");
+	if (accessToken) {
+		cachedAuthCookie = accessToken;
+	}
+	return accessToken;
+}
+
+function getAuthCookie(): string | null {
+	if (cachedAuthCookie) return cachedAuthCookie;
+	cachedAuthCookie = readAuthCookieFromFile();
+	return cachedAuthCookie;
+}
+
 /** Typed medication response (subset of fields we care about) */
 export interface TestMedication {
 	id: number;
@@ -196,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;
@@ -211,16 +276,30 @@ export async function createMedicationViaAPI(data: {
 		takenBy?: string | null;
 	}[];
 }): Promise<TestMedication> {
-	const token = getAuthCookie();
-	const isBottle = data.packageType === "bottle";
+	let token = getAuthCookie();
+	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,
@@ -243,6 +322,10 @@ export async function createMedicationViaAPI(data: {
 			},
 			body: JSON.stringify(body),
 		});
+		if (res.status === 401) {
+			token = await refreshAuthCookieViaLogin();
+			if (token) continue;
+		}
 		if (res.status === 429) {
 			// Rate limited — exponential backoff: 3s, 6s, 9s, 12s, 15s
 			await new Promise((r) => setTimeout(r, 3000 * (attempt + 1)));
@@ -259,13 +342,25 @@ export async function createMedicationViaAPI(data: {
 
 /**
  * Delete a medication via the backend API.
+ * Includes retry for rate-limited responses.
  */
 export async function deleteMedicationViaAPI(id: number): Promise<void> {
-	const token = getAuthCookie();
-	await fetch(`${API_BASE}/api/medications/${id}`, {
-		method: "DELETE",
-		headers: token ? { Cookie: `access_token=${token}` } : {},
-	});
+	let token = getAuthCookie();
+	for (let attempt = 0; attempt < 3; attempt++) {
+		const res = await fetch(`${API_BASE}/api/medications/${id}`, {
+			method: "DELETE",
+			headers: token ? { Cookie: `access_token=${token}` } : {},
+		});
+		if (res.status === 401) {
+			token = await refreshAuthCookieViaLogin();
+			if (token) continue;
+		}
+		if (res.status === 429) {
+			await new Promise((r) => setTimeout(r, 3000 * (attempt + 1)));
+			continue;
+		}
+		return;
+	}
 }
 
 /**
@@ -273,11 +368,15 @@ export async function deleteMedicationViaAPI(id: number): Promise<void> {
  * Includes retry logic for rate-limited responses.
  */
 export async function deleteAllMedicationsViaAPI(): Promise<void> {
-	const token = getAuthCookie();
+	let token = getAuthCookie();
 	for (let attempt = 0; attempt < 3; attempt++) {
 		const res = await fetch(`${API_BASE}/api/medications`, {
 			headers: token ? { Cookie: `access_token=${token}` } : {},
 		});
+		if (res.status === 401) {
+			token = await refreshAuthCookieViaLogin();
+			if (token) continue;
+		}
 		if (res.status === 429) {
 			await new Promise((r) => setTimeout(r, 3000 * (attempt + 1)));
 			continue;
@@ -290,6 +389,10 @@ export async function deleteAllMedicationsViaAPI(): Promise<void> {
 					method: "DELETE",
 					headers: token ? { Cookie: `access_token=${token}` } : {},
 				});
+				if (delRes.status === 401) {
+					token = await refreshAuthCookieViaLogin();
+					if (token) continue;
+				}
 				if (delRes.status === 429) {
 					await new Promise((r) => setTimeout(r, 3000));
 					continue;
@@ -306,7 +409,7 @@ export async function deleteAllMedicationsViaAPI(): Promise<void> {
  * Requires a medication with takenBy to exist first.
  */
 export async function createShareTokenViaAPI(takenBy: string, scheduleDays = 30): Promise<TestShareToken> {
-	const token = getAuthCookie();
+	let token = getAuthCookie();
 	for (let attempt = 0; attempt < 5; attempt++) {
 		const res = await fetch(`${API_BASE}/api/share`, {
 			method: "POST",
@@ -316,10 +419,23 @@ export async function createShareTokenViaAPI(takenBy: string, scheduleDays = 30)
 			},
 			body: JSON.stringify({ takenBy, scheduleDays }),
 		});
+		if (res.status === 401) {
+			token = await refreshAuthCookieViaLogin();
+			if (token) continue;
+		}
 		if (res.status === 429) {
 			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\)|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

@@ -233,7 +233,7 @@ test.describe("Medication Editing", () => {
 
 		// Change intake from 1 pill daily to 2 pills every 7 days
 		const intakeRow = page.locator(".blister-row").first();
-		const usageField = intakeRow.getByLabel(/(Usage \(pills\)|form\.blisters\.usage)/i);
+		const usageField = intakeRow.getByLabel(/(Usage|form\.blisters\.usage)/i);
 		const everyField = intakeRow.getByLabel(/(Every \(days\)|form\.blisters\.everyDays)/i);
 
 		await usageField.fill("2");
@@ -247,7 +247,7 @@ test.describe("Medication Editing", () => {
 		// Verify the changes persisted
 		await clickEditMed(page, "Edit Intake Med");
 		const savedRow = page.locator(".blister-row").first();
-		await expect(savedRow.getByLabel(/(Usage \(pills\)|form\.blisters\.usage)/i)).toHaveValue("2");
+		await expect(savedRow.getByLabel(/(Usage|form\.blisters\.usage)/i)).toHaveValue("2");
 		await expect(savedRow.getByLabel(/(Every \(days\)|form\.blisters\.everyDays)/i)).toHaveValue("7");
 	});
 
@@ -279,7 +279,7 @@ test.describe("Medication Editing", () => {
 
 		// Fill the new intake row
 		const secondRow = page.locator(".blister-row").nth(1);
-		await secondRow.getByLabel(/(Usage \(pills\)|form\.blisters\.usage)/i).fill("0.5");
+		await secondRow.getByLabel(/(Usage|form\.blisters\.usage)/i).fill("0.5");
 		await secondRow.getByLabel(/(Every \(days\)|form\.blisters\.everyDays)/i).fill("7");
 
 		await saveEditAndVerify(page, "Add Intake Med");
@@ -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/medication-lifecycle.spec.ts

@@ -0,0 +1,193 @@
+import { authFile, createMedicationViaAPI, deleteAllMedicationsViaAPI, expect, navigateTo, test } from "./fixtures";
+
+/**
+ * Medication Lifecycle Integration Tests
+ *
+ * End-to-end workflows that verify changes propagate across pages:
+ * create → verify on medications → check in planner → check in schedule → edit → delete
+ */
+test.describe("Medication lifecycle", () => {
+	test.use({ storageState: authFile });
+	test.describe.configure({ timeout: 90000 });
+
+	const MED_NAME = "Lifecycle TestMed";
+	const MED_EDITED = "Lifecycle Edited";
+
+	test.beforeAll(async () => {
+		await deleteAllMedicationsViaAPI();
+	});
+
+	test.afterAll(async () => {
+		await deleteAllMedicationsViaAPI();
+	});
+
+	test("create medication via API and verify it appears on all pages", async ({ page }) => {
+		const todayMorning = (() => {
+			const d = new Date();
+			d.setHours(8, 0, 0, 0);
+			const pad = (n: number) => n.toString().padStart(2, "0");
+			return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+		})();
+
+		// Step 1: Create medication
+		const created = await createMedicationViaAPI({
+			name: MED_NAME,
+			packageType: "blister",
+			packCount: 1,
+			blistersPerPack: 2,
+			pillsPerBlister: 10,
+			looseTablets: 0,
+			intakes: [{ usage: 1, every: 1, start: todayMorning, intakeRemindersEnabled: false }],
+		});
+		expect(created.id).toBeTruthy();
+
+		// Step 2: Verify on medications page
+		await navigateTo(page, "/medications");
+		await expect(page.getByText(MED_NAME).first()).toBeVisible({ timeout: 10000 });
+
+		// Step 3: Verify in planner
+		await navigateTo(page, "/planner");
+		await page.waitForLoadState("networkidle");
+		await page.locator('form.planner button[type="submit"]').click();
+		await expect(page.locator(".table")).toBeVisible({ timeout: 15000 });
+		await expect(page.locator(".table").getByText(MED_NAME)).toBeVisible();
+
+		// Step 4: Verify in schedule
+		await navigateTo(page, "/schedule");
+		await expect(page.getByText(MED_NAME).first()).toBeVisible({ timeout: 10000 });
+	});
+
+	test("edit medication name via UI and verify update propagates", async ({ page }) => {
+		await deleteAllMedicationsViaAPI();
+
+		const todayMorning = (() => {
+			const d = new Date();
+			d.setHours(8, 0, 0, 0);
+			const pad = (n: number) => n.toString().padStart(2, "0");
+			return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+		})();
+
+		// Create a fresh medication for this test
+		await createMedicationViaAPI({
+			name: MED_NAME,
+			packageType: "blister",
+			packCount: 1,
+			blistersPerPack: 2,
+			pillsPerBlister: 10,
+			looseTablets: 0,
+			intakes: [{ usage: 1, every: 1, start: todayMorning, intakeRemindersEnabled: false }],
+		});
+
+		// Navigate to medications page
+		await navigateTo(page, "/medications");
+		await expect(page.getByText(MED_NAME).first()).toBeVisible({ timeout: 10000 });
+
+		// Open edit view from medication row actions
+		const medRow = page.locator(".med-row").filter({ hasText: MED_NAME });
+		await expect(medRow.first()).toBeVisible({ timeout: 10000 });
+		await medRow.first().locator("button.info").click();
+		await expect(page.locator("h2").filter({ hasText: /(Edit(:| (entry|medication))|form\.editEntry)/i })).toBeVisible({
+			timeout: 5000,
+		});
+
+		// Update the name
+		const form = page.locator("form.form-grid:visible").first();
+		const nameInput = form.getByLabel(/(Commercial Name|Name|form\.name)/i).first();
+		await nameInput.fill(MED_EDITED);
+
+		// Save
+		const submitButton = form.locator('button[type="submit"]').first();
+		await expect(submitButton).toBeEnabled({ timeout: 5000 });
+		await submitButton.click();
+
+		// Wait for modal to close or save to complete
+		await page.waitForLoadState("networkidle");
+
+		// Verify edited name appears on medications page
+		await navigateTo(page, "/medications");
+		await expect(page.getByText(MED_EDITED).first()).toBeVisible({ timeout: 10000 });
+		// Old name should no longer appear
+		await expect(page.locator(".med-row").filter({ hasText: MED_NAME })).toHaveCount(0, { timeout: 5000 });
+	});
+
+	test("delete medication via API and verify it disappears from all pages", async ({ page }) => {
+		const todayMorning = (() => {
+			const d = new Date();
+			d.setHours(8, 0, 0, 0);
+			const pad = (n: number) => n.toString().padStart(2, "0");
+			return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+		})();
+
+		// Create and then delete
+		await deleteAllMedicationsViaAPI();
+		await createMedicationViaAPI({
+			name: MED_NAME,
+			packageType: "blister",
+			packCount: 1,
+			blistersPerPack: 1,
+			pillsPerBlister: 5,
+			looseTablets: 0,
+			intakes: [{ usage: 1, every: 1, start: todayMorning, intakeRemindersEnabled: false }],
+		});
+
+		// Verify it exists first
+		await navigateTo(page, "/medications");
+		await expect(page.getByText(MED_NAME)).toBeVisible({ timeout: 10000 });
+
+		// Delete via API
+		await deleteAllMedicationsViaAPI();
+
+		// Verify gone from medications page
+		await navigateTo(page, "/medications");
+		await expect(page.getByText(MED_NAME)).not.toBeVisible({ timeout: 5000 });
+
+		// Verify planner shows no results for this med
+		await navigateTo(page, "/planner");
+		await page.waitForLoadState("networkidle");
+		await page.locator('form.planner button[type="submit"]').click();
+		// Either no table or table without the medication name
+		const table = page.locator(".table");
+		const tableVisible = await table.isVisible().catch(() => false);
+		if (tableVisible) {
+			await expect(table.getByText(MED_NAME)).not.toBeVisible({ timeout: 3000 });
+		}
+	});
+
+	test("medication with multiple intakes shows all schedule entries", async ({ page }) => {
+		const todayMorning = (() => {
+			const d = new Date();
+			d.setHours(8, 0, 0, 0);
+			const pad = (n: number) => n.toString().padStart(2, "0");
+			return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+		})();
+
+		const todayEvening = (() => {
+			const d = new Date();
+			d.setHours(20, 0, 0, 0);
+			const pad = (n: number) => n.toString().padStart(2, "0");
+			return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+		})();
+
+		await deleteAllMedicationsViaAPI();
+		await createMedicationViaAPI({
+			name: "MultiIntake Med",
+			packageType: "blister",
+			packCount: 1,
+			blistersPerPack: 2,
+			pillsPerBlister: 10,
+			looseTablets: 0,
+			intakes: [
+				{ usage: 1, every: 1, start: todayMorning, intakeRemindersEnabled: false },
+				{ usage: 2, every: 1, start: todayEvening, intakeRemindersEnabled: false },
+			],
+		});
+
+		// Verify schedule shows this medication
+		await navigateTo(page, "/schedule");
+		await expect(page.getByText("MultiIntake Med").first()).toBeVisible({ timeout: 10000 });
+
+		// The medication should appear at least twice (morning + evening)
+		const medEntries = page.getByText("MultiIntake Med");
+		expect(await medEntries.count()).toBeGreaterThanOrEqual(2);
+	});
+});

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/performance.spec.ts

@@ -0,0 +1,98 @@
+import { authFile, createMedicationViaAPI, deleteAllMedicationsViaAPI, expect, navigateTo, test } from "./fixtures";
+
+/**
+ * Performance Tests
+ *
+ * Verify the schedule timeline and planner render within acceptable
+ * time limits when many medications exist.
+ */
+test.describe("Performance with many medications", () => {
+	test.use({ storageState: authFile });
+	test.describe.configure({ timeout: 120000 });
+
+	const MED_COUNT = 20;
+	const MED_PREFIX = "PerfTest Med";
+
+	test.beforeAll(async () => {
+		await deleteAllMedicationsViaAPI();
+
+		const todayMorning = (() => {
+			const d = new Date();
+			d.setHours(8, 0, 0, 0);
+			const pad = (n: number) => n.toString().padStart(2, "0");
+			return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+		})();
+
+		// Create medications sequentially (API rate limits prevent parallel)
+		for (let i = 1; i <= MED_COUNT; i++) {
+			await createMedicationViaAPI({
+				name: `${MED_PREFIX} ${i}`,
+				packageType: "blister",
+				packCount: 1,
+				blistersPerPack: 2,
+				pillsPerBlister: 10,
+				looseTablets: 0,
+				intakes: [{ usage: 1, every: 1, start: todayMorning, intakeRemindersEnabled: false }],
+			});
+		}
+	});
+
+	test.afterAll(async () => {
+		await deleteAllMedicationsViaAPI();
+	});
+
+	test("schedule page renders within 10 seconds with 20 medications", async ({ page }) => {
+		const start = Date.now();
+		await navigateTo(page, "/schedule");
+
+		// Wait for schedule entries to render
+		const scheduleEntries = page.locator(".schedule-entry, .timeline-entry, .card");
+		await expect(scheduleEntries.first()).toBeVisible({ timeout: 15000 });
+
+		const renderTime = Date.now() - start;
+
+		// Verify all medications appear
+		for (let i = 1; i <= MED_COUNT; i++) {
+			await expect(page.getByText(`${MED_PREFIX} ${i}`).first()).toBeVisible({ timeout: 5000 });
+		}
+
+		// Goal: render under 10 seconds
+		expect(renderTime).toBeLessThan(10000);
+	});
+
+	test("medications page renders within 10 seconds with 20 medications", async ({ page }) => {
+		const start = Date.now();
+		await navigateTo(page, "/medications");
+
+		// Wait for medication cards to render
+		const medEntries = page.locator(".medication-card, .card, .table-row");
+		await expect(medEntries.first()).toBeVisible({ timeout: 15000 });
+
+		const renderTime = Date.now() - start;
+
+		// Verify count — all 20 should be visible
+		for (let i = 1; i <= MED_COUNT; i++) {
+			await expect(page.getByText(`${MED_PREFIX} ${i}`).first()).toBeVisible({ timeout: 5000 });
+		}
+
+		expect(renderTime).toBeLessThan(10000);
+	});
+
+	test("planner calculates within 15 seconds with 20 medications", async ({ page }) => {
+		await navigateTo(page, "/planner");
+
+		const start = Date.now();
+		await page.waitForLoadState("networkidle");
+		await page.locator('form.planner button[type="submit"]').click();
+		await expect(page.locator(".table")).toBeVisible({ timeout: 20000 });
+
+		const calcTime = Date.now() - start;
+
+		// All medications should appear in the results
+		const rows = page.locator(".table .table-row");
+		expect(await rows.count()).toBeGreaterThanOrEqual(MED_COUNT);
+
+		// Goal: calculate and render under 15 seconds
+		expect(calcTime).toBeLessThan(15000);
+	});
+});

frontend/e2e/planner-data.spec.ts

@@ -106,7 +106,7 @@ test.describe("Planner with medications", () => {
 		expect(await statusChips.count()).toBeGreaterThanOrEqual(2);
 	});
 
-	test("should show usage data in results rows", async ({ page }) => {
+	test("should show correct usage values in results rows", async ({ page }) => {
 		await navigateTo(page, "/planner");
 		await calculatePlanner(page);
 
@@ -116,10 +116,15 @@ test.describe("Planner with medications", () => {
 		const rows = resultsTable.locator(".table-row");
 		expect(await rows.count()).toBeGreaterThanOrEqual(2);
 
-		const firstRowText = await rows.first().textContent();
-		expect(firstRowText).toBeTruthy();
-		// Check for "pill" (matches both "pill" and "pills")
-		expect(firstRowText!.toLowerCase()).toContain("pill");
+		// Each medication has usage=1, every=1 → plannerUsage should reflect the period
+		// Verify the usage column contains a numeric <strong> value and "pill(s)"
+		for (const row of await rows.all()) {
+			const usageCell = row.locator("[data-label]").nth(1); // Usage is 2nd column
+			const usageStrong = usageCell.locator("strong");
+			await expect(usageStrong).toBeVisible();
+			const usageText = await usageStrong.textContent();
+			expect(Number(usageText)).toBeGreaterThan(0);
+		}
 	});
 
 	test("should show danger status for low-stock medication over 90 days", async ({ page }) => {
@@ -139,9 +144,16 @@ test.describe("Planner with medications", () => {
 		const resultsTable = page.locator(".table");
 		await expect(resultsTable).toBeVisible({ timeout: 10000 });
 
-		// Low-stock med (3 pills) should have a danger chip over 90 days
+		// Low-stock med (3 pills, usage 1/day, 90 days) should have danger status
 		const dangerChips = resultsTable.locator(".status-chip.danger");
 		expect(await dangerChips.count()).toBeGreaterThanOrEqual(1);
+
+		// Find the low-stock med row and verify its usage value ~90 pills
+		const lowStockRow = resultsTable.locator(".table-row", { hasText: MED_LOW });
+		await expect(lowStockRow).toBeVisible();
+		const lowUsage = await lowStockRow.locator("[data-label] strong").first().textContent();
+		expect(Number(lowUsage)).toBeGreaterThanOrEqual(85); // ~90 pills needed
+		expect(Number(lowUsage)).toBeLessThanOrEqual(95);
 	});
 
 	test("should show Enough status for well-stocked medication over 7 days", async ({ page }) => {
@@ -161,9 +173,16 @@ test.describe("Planner with medications", () => {
 		const resultsTable = page.locator(".table");
 		await expect(resultsTable).toBeVisible({ timeout: 10000 });
 
-		// With 60 pills and 7-day range, high-stock should be "Enough"
-		const successChips = resultsTable.locator(".status-chip.success");
-		expect(await successChips.count()).toBeGreaterThanOrEqual(1);
+		// High-stock med (60 pills, usage 1/day, 7 days → needs ~7, has 60) should be "Enough"
+		const highStockRow = resultsTable.locator(".table-row", { hasText: MED_HIGH });
+		await expect(highStockRow).toBeVisible();
+		const highStatus = highStockRow.locator(".status-chip.success");
+		await expect(highStatus).toBeVisible();
+
+		// Verify usage is ~7 pills for the 7-day range
+		const highUsage = await highStockRow.locator("[data-label] strong").first().textContent();
+		expect(Number(highUsage)).toBeGreaterThanOrEqual(5);
+		expect(Number(highUsage)).toBeLessThanOrEqual(10);
 	});
 
 	test("should show table header with correct columns", async ({ page }) => {
@@ -180,6 +199,28 @@ test.describe("Planner with medications", () => {
 		await expect(tableHead.getByText(/Status/i)).toBeVisible();
 	});
 
+	test("should display available stock for each medication", async ({ page }) => {
+		await navigateTo(page, "/planner");
+		await calculatePlanner(page);
+
+		const resultsTable = page.locator(".table");
+		await expect(resultsTable).toBeVisible({ timeout: 10000 });
+
+		// High-stock med should show a blister + loose-pill stock breakdown
+		const highStockRow = resultsTable.locator(".table-row", { hasText: MED_HIGH });
+		await expect(highStockRow).toBeVisible();
+		const highStockText = await highStockRow.textContent();
+		expect(highStockText).toMatch(/\d+\s*(blisters|Blister)/i);
+		expect(highStockText).toMatch(/\d+\s*(pill|pills|Tablette|Tabletten)/i);
+
+		// Low-stock med: 1 pack × 1 blister × 3 pills = 3 pills = 0 full blisters + 3 loose
+		const lowStockRow = resultsTable.locator(".table-row", { hasText: MED_LOW });
+		await expect(lowStockRow).toBeVisible();
+		const lowStockText = await lowStockRow.textContent();
+		// Should show 3 loose pills
+		expect(lowStockText).toMatch(/3\s*(pill|pills|Tablette|Tabletten)/i);
+	});
+
 	test("should reset form and clear results", async ({ page }) => {
 		await navigateTo(page, "/planner");
 		await calculatePlanner(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

@@ -150,17 +150,20 @@ test.describe("Schedule Timeline", () => {
 	test("should show overview table with stock status", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		// Overview table has class .table.table-7
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible();
 		await expect(overviewTable.locator(".table-head")).toBeVisible();
 	});
 
 	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

@@ -72,7 +72,7 @@ test.describe("Share Schedule", () => {
 	test("should show taken-by badges on dashboard overview table", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		// Alice's medication should show "Alice" badge
@@ -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,34 +231,39 @@ 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 });
 		}
 	});
 
 	test("should show notes icon on dashboard for medication with notes", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		// Alice's med has notes — should show the 📝 icon
@@ -265,7 +275,7 @@ test.describe("Share Schedule", () => {
 	test("should show notes in medication detail modal", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		// Click on Alice's med to open detail modal

frontend/e2e/stock-status.spec.ts

@@ -125,7 +125,7 @@ test.describe("Stock Status Levels", () => {
 	test("should show all medications in overview table", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		// All 5 medications should appear
@@ -139,8 +139,9 @@ test.describe("Stock Status Levels", () => {
 	test("should show High status chip for well-stocked medication", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		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 });
@@ -151,7 +152,7 @@ test.describe("Stock Status Levels", () => {
 	test("should show Normal status chip for moderate stock medication", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		const normalRow = overviewTable.locator(".table-row").filter({ hasText: MED_NORMAL });
@@ -162,7 +163,7 @@ test.describe("Stock Status Levels", () => {
 	test("should show Warning status chip for low stock medication", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		const lowRow = overviewTable.locator(".table-row").filter({ hasText: MED_LOW });
@@ -173,7 +174,7 @@ test.describe("Stock Status Levels", () => {
 	test("should show Danger status chip for critical stock medication", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		const criticalRow = overviewTable.locator(".table-row").filter({ hasText: MED_CRITICAL });
@@ -184,7 +185,7 @@ test.describe("Stock Status Levels", () => {
 	test("should show Danger status chip for depleted medication", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		const depletedRow = overviewTable.locator(".table-row").filter({ hasText: MED_DEPLETED });
@@ -192,22 +193,55 @@ 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");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		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 }) => {
@@ -227,7 +261,7 @@ test.describe("Stock Status Levels", () => {
 	test("should color-code stock values depending on status", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		// High stock row should have success-text class on stock cells
@@ -255,7 +289,7 @@ test.describe("Stock Status Levels", () => {
 	test("should open medication detail modal showing stock info", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		// Click on the critical stock medication row
@@ -278,7 +312,7 @@ test.describe("Stock Status Levels", () => {
 	test("should show generic name in overview for medications that have one", async ({ page }) => {
 		await navigateTo(page, "/dashboard");
 
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		// Click on the normal stock med (has generic name "Ibuprofen 400mg")

frontend/e2e/tooltip-data.spec.ts

@@ -54,7 +54,7 @@ test.describe("MedDetail footer tooltip visibility", () => {
 	 */
 	async function openMedDetailModal(page: import("@playwright/test").Page) {
 		await navigateTo(page, "/dashboard");
-		const overviewTable = page.locator(".table.table-7");
+		const overviewTable = page.locator(".dashboard-overview-section .table").first();
 		await expect(overviewTable).toBeVisible({ timeout: 10000 });
 
 		const medRow = overviewTable.locator(".table-row").filter({ hasText: MED_NAME }).first();

frontend/nginx.conf

@@ -1,3 +1,6 @@
+# Must be defined at http-level (outside server block)
+log_format timed '$time_iso8601 $status $request_method $request_uri ($request_time s)';
+
 server {
     # Port 8080 for unprivileged nginx (non-root)
     listen 8080;
@@ -6,9 +9,6 @@ server {
     root /usr/share/nginx/html;
     index index.html;
 
-    # Custom log format with ISO timestamps
-    log_format timed '$time_iso8601 $status $request_method $request_uri ($request_time s)';
-
     # Access log control (suppressed when LOG_LEVEL is warn or higher)
     access_log ${NGINX_ACCESS_LOG};
 
@@ -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,31 +1,31 @@
 {
   "name": "medassist-ng-frontend",
-  "version": "1.16.1",
+  "version": "1.19.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "medassist-ng-frontend",
-      "version": "1.16.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",
-        "react": "^19.2.0",
-        "react-dom": "^19.2.0",
-        "react-i18next": "^15.4.1",
+        "lucide-react": "^0.577.0",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4",
+        "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.0",
-        "@types/react": "^19.2.2",
-        "@types/react-dom": "^19.2.2",
+        "@types/node": "^25.3.5",
+        "@types/react": "^19.2.14",
+        "@types/react-dom": "^19.2.3",
         "@types/react-router-dom": "^5.3.3",
         "@vitejs/plugin-react": "^5.1.4",
         "@vitest/coverage-v8": "^4.0.18",
@@ -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.0",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.3.0.tgz",
-      "integrity": "sha512-4K3bqJpXpqfg2XKGK9bpDTc6xO/xoUP/RBWS7AtRMug6zZFaRekiLzjVtAoZMquxoAbzBvy5nxQ7veS5eYzf8A==",
+      "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": {
@@ -1789,19 +1789,19 @@
       }
     },
     "node_modules/@types/react": {
-      "version": "19.2.2",
-      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.2.tgz",
-      "integrity": "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA==",
+      "version": "19.2.14",
+      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz",
+      "integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "csstype": "^3.0.2"
+        "csstype": "^3.2.2"
       }
     },
     "node_modules/@types/react-dom": {
-      "version": "19.2.2",
-      "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.2.2.tgz",
-      "integrity": "sha512-9KQPoO6mZCi7jcIStSnlOWn2nEF3mNmyr3rIAsGnAbQKYbRLyqmeSc39EVgtxXVia+LMT8j3knZLAZAh+xLmrw==",
+      "version": "19.2.3",
+      "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.2.3.tgz",
+      "integrity": "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==",
       "dev": true,
       "license": "MIT",
       "peerDependencies": {
@@ -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"
@@ -2959,41 +2959,38 @@
       }
     },
     "node_modules/react": {
-      "version": "19.2.0",
-      "resolved": "https://registry.npmjs.org/react/-/react-19.2.0.tgz",
-      "integrity": "sha512-tmbWg6W31tQLeB5cdIBOicJDJRR2KzXsV7uSK9iNfLWQ5bIZfxuPEHp7M8wiHyHnn0DD1i7w3Zmin0FtkrwoCQ==",
+      "version": "19.2.4",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz",
+      "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==",
       "license": "MIT",
-      "dependencies": {
-        "loose-envify": "^1.1.0"
-      },
       "engines": {
         "node": ">=0.10.0"
       }
     },
     "node_modules/react-dom": {
-      "version": "19.2.0",
-      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.0.tgz",
-      "integrity": "sha512-UlbRu4cAiGaIewkPyiRGJk0imDN2T3JjieT6spoL2UeSf5od4n5LB/mQ4ejmxhCFT1tYe8IvaFulzynWovsEFQ==",
+      "version": "19.2.4",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz",
+      "integrity": "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==",
       "license": "MIT",
       "dependencies": {
-        "loose-envify": "^1.1.0",
         "scheduler": "^0.27.0"
       },
       "peerDependencies": {
-        "react": "^19.2.0"
+        "react": "^19.2.4"
       }
     },
     "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"
       },
@@ -3341,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": {
@@ -3388,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.17.0",
+  "version": "1.20.1",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -27,24 +27,24 @@
     "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",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "react-i18next": "^15.4.1",
+    "lucide-react": "^0.577.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "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.0",
-    "@types/react": "^19.2.2",
-    "@types/react-dom": "^19.2.2",
+    "@types/node": "^25.3.5",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "@types/react-router-dom": "^5.3.3",
     "@vitejs/plugin-react": "^5.1.4",
     "@vitest/coverage-v8": "^4.0.18",

frontend/playwright.base.config.ts

@@ -7,7 +7,9 @@ export function buildPlaywrightConfig(runAllBrowsers: boolean) {
 			: {};
 	const baseURL = env.PLAYWRIGHT_BASE_URL || "http://localhost:5173";
 	const parsedWorkers = Number.parseInt(env.PLAYWRIGHT_WORKERS ?? "", 10);
-	const workers = Number.isFinite(parsedWorkers) && parsedWorkers > 0 ? parsedWorkers : env.CI ? 1 : 4;
+	// Default to single-worker execution to keep API-seeded E2E suites deterministic.
+	// Still allow explicit local overrides via PLAYWRIGHT_WORKERS.
+	const workers = Number.isFinite(parsedWorkers) && parsedWorkers > 0 ? parsedWorkers : 1;
 
 	const projects: NonNullable<PlaywrightTestConfig["projects"]> = [
 		{
@@ -19,13 +21,13 @@ export function buildPlaywrightConfig(runAllBrowsers: boolean) {
 			use: {
 				...devices["Desktop Chrome"],
 			},
-			testIgnore: /.*-(?:data|crud|edit|status|schedule)\.spec\.ts/,
+			testIgnore: /.*-(?:data|crud|edit|status|schedule|lifecycle)\.spec\.ts|performance\.spec\.ts/,
 			dependencies: ["setup"],
 			retries: 1,
 		},
 		{
 			name: "chromium-data",
-			testMatch: /.*-(?:data|crud|edit|status|schedule)\.spec\.ts/,
+			testMatch: /.*-(?:data|crud|edit|status|schedule|lifecycle)\.spec\.ts|performance\.spec\.ts/,
 			use: {
 				...devices["Desktop Chrome"],
 			},
@@ -42,7 +44,7 @@ export function buildPlaywrightConfig(runAllBrowsers: boolean) {
 				use: {
 					...devices["Desktop Firefox"],
 				},
-				testIgnore: /.*-(?:data|crud|edit|status|schedule)\.spec\.ts/,
+				testIgnore: /.*-(?:data|crud|edit|status|schedule|lifecycle)\.spec\.ts|performance\.spec\.ts/,
 				dependencies: ["setup"],
 			},
 			{
@@ -50,7 +52,7 @@ export function buildPlaywrightConfig(runAllBrowsers: boolean) {
 				use: {
 					...devices["Desktop Safari"],
 				},
-				testIgnore: /.*-(?:data|crud|edit|status|schedule)\.spec\.ts/,
+				testIgnore: /.*-(?:data|crud|edit|status|schedule|lifecycle)\.spec\.ts|performance\.spec\.ts/,
 				dependencies: ["setup"],
 			},
 		);

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 />} />
@@ -37,13 +38,29 @@ export default function App() {
 	);
 }
 
+function getInitialAuthTheme(): "light" | "dark" {
+	if (typeof window === "undefined") return "dark";
+
+	const stored = localStorage.getItem("theme");
+	if (stored === "light" || stored === "dark") {
+		return stored;
+	}
+
+	if (stored === "system") {
+		return window.matchMedia?.("(prefers-color-scheme: light)").matches ? "light" : "dark";
+	}
+
+	return window.matchMedia?.("(prefers-color-scheme: light)").matches ? "light" : "dark";
+}
+
 function AppRouter() {
 	const { user, authState, loading, authError } = useAuth();
+	const authTheme = getInitialAuthTheme();
 
 	// Show loading while checking auth state
 	if (loading) {
 		return (
-			<div className="auth-container">
+			<div className="auth-container" data-theme={authTheme}>
 				<div className="auth-card" style={{ textAlign: "center" }}>
 					<h1 className="auth-title">💊 MedAssist-ng</h1>
 					<p>Loading...</p>
@@ -55,7 +72,7 @@ function AppRouter() {
 	// Show error if we couldn't connect to the server
 	if (authError) {
 		return (
-			<div className="auth-container">
+			<div className="auth-container" data-theme={authTheme}>
 				<div className="auth-card" style={{ textAlign: "center" }}>
 					<h1 className="auth-title">💊 MedAssist-ng</h1>
 					<div className="auth-error" style={{ marginBottom: "1rem" }}>
@@ -77,7 +94,7 @@ function AppRouter() {
 	// If auth state is null (shouldn't happen after loading, but be safe)
 	if (!authState) {
 		return (
-			<div className="auth-container">
+			<div className="auth-container" data-theme={authTheme}>
 				<div className="auth-card" style={{ textAlign: "center" }}>
 					<h1 className="auth-title">💊 MedAssist-ng</h1>
 					<p>Initializing...</p>
@@ -301,6 +318,7 @@ function AppContent() {
 	useEffect(() => {
 		const handleEscape = (e: KeyboardEvent) => {
 			if (e.key !== "Escape") return;
+			if (e.defaultPrevented) return;
 
 			if (scheduleLightboxImage) {
 				closeScheduleLightbox();

frontend/src/components/Auth.tsx

@@ -157,7 +157,7 @@ export function AuthProvider({ children }: { children: ReactNode }) {
 						return;
 					}
 				}
-				log.warn("[Auth] Session refresh failed, clearing local user state", { correlationId });
+				log.debug("[Auth] Session refresh unavailable, clearing local user state", { correlationId });
 				setUser(null);
 			} else {
 				log.warn("[Auth] Unexpected /auth/me response", { status: res.status, correlationId });
@@ -181,7 +181,11 @@ export function AuthProvider({ children }: { children: ReactNode }) {
 			);
 			const res = await fetch("/api/auth/refresh", init);
 			if (!res.ok) {
-				log.warn("[Auth] Token refresh rejected", { status: res.status, correlationId });
+				if (res.status === 401) {
+					log.debug("[Auth] Token refresh rejected (unauthenticated)", { status: res.status, correlationId });
+				} else {
+					log.warn("[Auth] Token refresh rejected", { status: res.status, correlationId });
+				}
 			}
 			return res.ok;
 		} catch (error) {
@@ -433,7 +437,7 @@ export function LoginForm({
 					</div>
 				)}
 
-				{/* Local login form: only show if form login is enabled */}
+				{/* Local login form - only show if form login is enabled */}
 				{authState?.formLoginEnabled && (
 					<form onSubmit={handleSubmit} className="auth-form">
 						{error && <div className="auth-error">{error}</div>}

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";
@@ -159,8 +167,8 @@ export function MedDetailModal({
 	// Escape key: only one handler is active at a time (sub-modal states are mutually exclusive).
 	// Lightbox has its own useEscapeKey internally.
 	useEscapeKey(!showEditStockModal && !showImageLightbox && !showRefillModal, onClose);
-	useEscapeKey(showEditStockModal, onCloseEditStockModal);
-	useEscapeKey(showRefillModal, onCloseRefillModal);
+	useEscapeKey(showEditStockModal, onCloseEditStockModal, { capture: true });
+	useEscapeKey(showRefillModal, onCloseRefillModal, { capture: true });
 
 	useEffect(() => {
 		if (showEditStockModal) return;
@@ -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,14 +200,20 @@ export function MedDetailModal({
 	]);
 
 	if (!selectedMed) return null;
+	const isAmountPackage =
+		isTubePackageType(selectedMed.packageType) || isLiquidContainerPackageType(selectedMed.packageType);
+	const amountUnitLabel =
+		isLiquidContainerPackageType(selectedMed.packageType) || selectedMed.medicationForm === "liquid"
+			? t("form.packageAmountUnitMl")
+			: t("form.packageAmountUnitG");
+	const stockUnitLabel = isAmountPackage ? amountUnitLabel : null;
 
 	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.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";
@@ -208,8 +222,21 @@ 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.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);
+		if (Number.isFinite(configured) && configured > 0) return configured;
+
+		const totalAmount = Number(stockDisplayTotal ?? 0);
+		if (Number.isFinite(totalAmount) && totalAmount > 0) {
+			return Math.max(0, totalAmount / packageCount);
+		}
+
+		return 0;
+	})();
 	const maxPartialPills = Math.min(
 		Math.max(0, selectedMed.pillsPerBlister),
 		Math.max(0, structuralMax - Math.max(0, editStockFullBlisters) * selectedMed.pillsPerBlister)
@@ -219,6 +246,41 @@ 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 (isLiquidContainerPackageType(selectedMed.packageType)) {
+			if (intakeUnit === "tsp") {
+				return `${usage} ${t("form.blisters.teaspoons", { count: Math.abs(usage) })}`;
+			}
+			if (intakeUnit === "tbsp") {
+				return `${usage} ${t("form.blisters.tablespoons", { count: Math.abs(usage) })}`;
+			}
+			return `${usage} ${t("form.packageAmountUnitMl")}`;
+		}
+		if (isTubePackageType(selectedMed.packageType)) {
+			return `${usage} ${t("form.blisters.applications", { count: Math.abs(usage) })}`;
+		}
+		return `${usage} ${usage !== 1 ? t("common.pills") : t("common.pill")}`;
+	};
+	const scheduleIntakes =
+		selectedMed.intakes && selectedMed.intakes.length > 0
+			? selectedMed.intakes
+			: selectedMed.blisters.map((blister) => ({
+					usage: blister.usage,
+					every: blister.every,
+					start: blister.start,
+					takenBy: null,
+					intakeRemindersEnabled: false,
+					intakeUnit: null,
+				}));
+	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);
@@ -347,6 +409,10 @@ export function MedDetailModal({
 
 	const renderEditStockModal = () => {
 		if (!showEditStockModal) return null;
+		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));
 		const fullInputMax = Math.min(
 			maxFullBlisters,
 			Math.floor(Math.max(0, structuralMax - Math.max(0, editStockPartialBlisterPills)) / selectedMed.pillsPerBlister)
@@ -360,14 +426,14 @@ export function MedDetailModal({
 					onCloseEditStockModal();
 				}}
 				onKeyDown={(e) => {
-					if (e.key !== "Escape") e.stopPropagation();
+					e.stopPropagation();
 				}}
 			>
 				<div
 					className="modal-content edit-stock-modal"
 					onClick={(e) => e.stopPropagation()}
 					onKeyDown={(e) => {
-						if (e.key !== "Escape") e.stopPropagation();
+						e.stopPropagation();
 					}}
 				>
 					<button
@@ -382,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,
@@ -392,9 +458,15 @@ 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>
 					)}
+					{(isTubePackageType(selectedMed.packageType) || isLiquidContainerPackageType(selectedMed.packageType)) && (
+						<p className="edit-stock-cap-info">
+							{t("form.totalAmount")}: {formatNumber(isLiquidPackage ? liquidCapacity : structuralMax)}{" "}
+							{amountUnitLabel}
+						</p>
+					)}
 					{showStockCapNotice && (
 						<p className="edit-stock-cap-warning">{t("editStock.maxExceeded", { count: structuralMax })}</p>
 					)}
@@ -402,12 +474,14 @@ export function MedDetailModal({
 					{(() => {
 						const dbTotal = getMedTotal(selectedMed);
 						const currentTotal = medCoverage ? Math.round(medCoverage.medsLeft) : dbTotal;
-						const isBottle = selectedMed.packageType === "bottle";
-						const enteredTotal = isBottle
-							? editStockPartialBlisterPills
-							: editStockFullBlisters * selectedMed.pillsPerBlister +
-								editStockPartialBlisterPills +
-								editStockLoosePills;
+						const isBottle = isAmountBasedPackageType(selectedMed.packageType);
+						const enteredTotal = isLiquidPackage
+							? Math.min(liquidCapacity, editStockPartialBlisterPills)
+							: isBottle
+								? editStockPartialBlisterPills
+								: editStockFullBlisters * selectedMed.pillsPerBlister +
+									editStockPartialBlisterPills +
+									editStockLoosePills;
 						const newTotal = Math.max(0, enteredTotal);
 						const difference = newTotal - currentTotal;
 						const differenceClass = difference > 0 ? "positive" : difference < 0 ? "negative" : "";
@@ -417,36 +491,39 @@ export function MedDetailModal({
 								<div className="edit-stock-form">
 									{isBottle ? (
 										<label>
-											{t("editStock.totalPills")}
+											{isAmountPackage ? t("form.currentAmount") : t("editStock.totalPills")}
 											{renderStepperInput({
 												value: editStockPartialInput,
 												min: 0,
-												max: structuralMax,
+												max: isLiquidPackage ? liquidCapacity : structuralMax,
 												onChange: (raw) => {
 													const parsed = raw === "" ? 0 : Math.max(0, parseStockInput(raw));
 													setEditStockPartialInput(raw);
-													onEditStockPartialBlisterPillsChange(raw === "" ? 0 : Math.min(structuralMax, parsed));
-													setShowStockCapNotice(parsed > structuralMax);
+													const maxTotal = isLiquidPackage ? liquidCapacity : structuralMax;
+													onEditStockPartialBlisterPillsChange(raw === "" ? 0 : Math.min(maxTotal, parsed));
+													setShowStockCapNotice(parsed > maxTotal);
 												},
 												onBlur: () => {
-													const normalized = Math.min(
-														structuralMax,
-														Math.max(0, parseStockInput(editStockPartialInput))
-													);
+													const maxTotal = isLiquidPackage ? liquidCapacity : structuralMax;
+													const normalized = Math.min(maxTotal, Math.max(0, parseStockInput(editStockPartialInput)));
 													onEditStockPartialBlisterPillsChange(normalized);
 													setEditStockPartialInput(String(normalized));
 													setShowStockCapNotice(false);
 												},
 												onStep: (delta) => {
-													const next = Math.min(
-														structuralMax,
-														Math.max(0, parseStockInput(editStockPartialInput) + delta)
-													);
+													const maxTotal = isLiquidPackage ? liquidCapacity : structuralMax;
+													const next = Math.min(maxTotal, Math.max(0, parseStockInput(editStockPartialInput) + delta));
 													onEditStockPartialBlisterPillsChange(next);
 													setEditStockPartialInput(String(next));
 													setShowStockCapNotice(false);
 												},
 											})}
+											{isLiquidPackage && (
+												<p className="edit-stock-cap-info" style={{ marginTop: "0.35rem" }}>
+													{t("form.currentAmount")}: {Math.max(0, editStockPartialBlisterPills)} {amountUnitLabel} /{" "}
+													{liquidCapacity} {amountUnitLabel}
+												</p>
+											)}
 										</label>
 									) : (
 										<>
@@ -584,26 +661,72 @@ export function MedDetailModal({
 											</label>
 										</>
 									)}
+									{isLiquidPackage && (
+										<label>
+											{t("form.bottles")}
+											{renderStepperInput({
+												value: editStockFullInput,
+												min: 1,
+												max: Number.MAX_SAFE_INTEGER,
+												onChange: (raw) => {
+													const nextBottleCount = raw === "" ? 1 : Math.max(1, parseStockInput(raw));
+													setEditStockFullInput(raw === "" ? "1" : raw);
+													onEditStockFullBlistersChange(nextBottleCount);
+													const syncedTotal = Math.round(nextBottleCount * liquidAmountPerBottle);
+													onEditStockPartialBlisterPillsChange(syncedTotal);
+													setEditStockPartialInput(String(syncedTotal));
+													setShowStockCapNotice(false);
+												},
+												onBlur: () => {
+													const normalized = Math.max(1, parseStockInput(editStockFullInput));
+													onEditStockFullBlistersChange(normalized);
+													setEditStockFullInput(String(normalized));
+													const syncedTotal = Math.round(normalized * liquidAmountPerBottle);
+													onEditStockPartialBlisterPillsChange(syncedTotal);
+													setEditStockPartialInput(String(syncedTotal));
+													setShowStockCapNotice(false);
+												},
+												onStep: (delta) => {
+													const next = Math.max(1, parseStockInput(editStockFullInput) + delta);
+													onEditStockFullBlistersChange(next);
+													setEditStockFullInput(String(next));
+													const syncedTotal = Math.round(next * liquidAmountPerBottle);
+													onEditStockPartialBlisterPillsChange(syncedTotal);
+													setEditStockPartialInput(String(syncedTotal));
+													setShowStockCapNotice(false);
+												},
+											})}
+										</label>
+									)}
 								</div>
 
 								<div className="edit-stock-summary">
 									<div className="summary-row">
 										<span>{t("editStock.currentTotal")}:</span>
 										<span>
-											{currentTotal} {currentTotal === 1 ? t("common.pill") : t("common.pills")}
+											{currentTotal}
+											{isAmountPackage
+												? ` ${stockUnitLabel}`
+												: ` ${currentTotal === 1 ? t("common.pill") : t("common.pills")}`}
 										</span>
 									</div>
 									<div className="summary-row">
 										<span>{t("editStock.newTotal")}:</span>
 										<span>
-											{newTotal} {newTotal === 1 ? t("common.pill") : t("common.pills")}
+											{newTotal}
+											{isAmountPackage
+												? ` ${stockUnitLabel}`
+												: ` ${newTotal === 1 ? t("common.pill") : t("common.pills")}`}
 										</span>
 									</div>
 									<div className={`summary-row difference ${differenceClass}`}>
 										<span>{t("editStock.difference")}:</span>
 										<span>
 											{difference > 0 ? "+" : ""}
-											{difference} {Math.abs(difference) === 1 ? t("common.pill") : t("common.pills")}
+											{difference}
+											{isAmountPackage
+												? ` ${stockUnitLabel}`
+												: ` ${Math.abs(difference) === 1 ? t("common.pill") : t("common.pills")}`}
 										</span>
 									</div>
 								</div>
@@ -696,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>
@@ -715,10 +838,14 @@ export function MedDetailModal({
 									</div>
 								</>
 							)}
-							<div className={`med-detail-item ${selectedMed.packageType === "bottle" ? "full-width" : "full-width"}`}>
-								<span className="med-detail-label">{t("modal.currentStock")}</span>
+							<div className="med-detail-item full-width">
+								<span className="med-detail-label">
+									{isAmountPackage ? t("form.currentAmount") : t("modal.currentStock")}
+								</span>
 								<span className={`med-detail-value ${textClass}`}>
-									{currentStock} / {stockDisplayTotal}
+									{isAmountPackage
+										? `${formatNumber(currentStock)} / ${formatNumber(stockDisplayTotal)} ${amountUnitLabel}`
+										: `${currentStock} / ${stockDisplayTotal}`}
 									{currentStock > stockDisplayTotal && (
 										<span
 											className="info-tooltip tooltip-align-left warning-text"
@@ -737,10 +864,27 @@ export function MedDetailModal({
 					<div className="med-detail-section">
 						<h3>
 							{t("modal.packageDetails")} (
-							{selectedMed.packageType === "bottle" ? t("form.packageTypeBottle") : t("form.packageTypeBlister")})
+							{isTubePackageType(selectedMed.packageType)
+								? t("form.packageTypeTube")
+								: isLiquidContainerPackageType(selectedMed.packageType)
+									? t("form.packageTypeLiquidContainer")
+									: isAmountBasedPackageType(selectedMed.packageType)
+										? t("form.packageTypeBottle")
+										: t("form.packageTypeBlister")}
+							)
+							{isTubePackageType(selectedMed.packageType) && (
+								<span className="info-tooltip small" data-tooltip={t("modal.packageTypeTubeHint")}>
+									ℹ️
+								</span>
+							)}
+							{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>
@@ -755,13 +899,51 @@ export function MedDetailModal({
 										<span className="med-detail-value">{selectedMed.pillsPerBlister}</span>
 									</div>
 								</>
+							) : isLiquidContainerPackageType(selectedMed.packageType) ? (
+								<>
+									<div className="med-detail-item">
+										<span className="med-detail-label">{t("form.bottles")}</span>
+										<span className="med-detail-value">{packageCount}</span>
+									</div>
+									<div className="med-detail-item">
+										<span className="med-detail-label">{t("form.packageAmountPerBottle")}</span>
+										<span className="med-detail-value">
+											{formatNumber(amountPerPackage)} {amountUnitLabel}
+										</span>
+									</div>
+									<div className="med-detail-item">
+										<span className="med-detail-label">{t("form.totalAmount")}</span>
+										<span className="med-detail-value">
+											{formatNumber(stockDisplayTotal)} {amountUnitLabel}
+										</span>
+									</div>
+								</>
+							) : isTubePackageType(selectedMed.packageType) ? (
+								<>
+									<div className="med-detail-item">
+										<span className="med-detail-label">{t("form.tubes")}</span>
+										<span className="med-detail-value">{packageCount}</span>
+									</div>
+									<div className="med-detail-item">
+										<span className="med-detail-label">{t("form.packageAmountPerTube")}</span>
+										<span className="med-detail-value">
+											{formatNumber(amountPerPackage)} {amountUnitLabel}
+										</span>
+									</div>
+									<div className="med-detail-item">
+										<span className="med-detail-label">{t("form.totalAmount")}</span>
+										<span className="med-detail-value">
+											{formatNumber(stockDisplayTotal)} {amountUnitLabel}
+										</span>
+									</div>
+								</>
 							) : (
 								<div className="med-detail-item">
 									<span className="med-detail-label">{t("form.totalCapacity")}</span>
 									<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">
@@ -791,53 +973,32 @@ export function MedDetailModal({
 						<div className="med-detail-section">
 							<h3>
 								{t("modal.intakeSchedule")}{" "}
-								{selectedMed.intakeRemindersEnabled && (
+								{hasAnyIntakeReminder && (
 									<span className="reminder-icon info-tooltip" data-tooltip={t("tooltips.intakeReminders")}>
 										<Bell size={14} aria-hidden="true" />
 									</span>
 								)}
 							</h3>
 							<div className="med-detail-schedules">
-								{(selectedMed.intakes && selectedMed.intakes.length > 0
-									? selectedMed.intakes
-									: selectedMed.blisters.map((blister) => ({
-											usage: blister.usage,
-											every: blister.every,
-											start: blister.start,
-											takenBy: null,
-											intakeRemindersEnabled: selectedMed.intakeRemindersEnabled ?? false,
-										}))
-								).map((intake, idx) => {
+								{scheduleIntakes.map((intake, idx) => {
 									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 key={`${intake.start}-${intake.usage}-${intake.every}-${idx}`} className="med-schedule-item">
+										<div
+											key={`${intake.start}-${intake.usage}-${intake.every}-${idx}`}
+											className="med-schedule-row blister-row-simple"
+										>
 											<span className="med-schedule-usage">
-												{totalUsage} {totalUsage !== 1 ? t("common.pills") : t("common.pill")}
-												{selectedMed.pillWeightMg &&
-													` (${totalUsage * selectedMed.pillWeightMg} ${selectedMed.doseUnit ?? "mg"})`}
+												{getScheduleUsageLabel(totalUsage, intake.intakeUnit)}
+												{showPillWeightDetails && ` (${totalUsage * pillWeightMg} ${selectedMed.doseUnit ?? "mg"})`}
 											</span>
 											<span className="med-schedule-freq">
 												{intake.every === 1 ? t("common.daily") : t("common.everyNDays", { count: intake.every })}
 											</span>
-											{hasPerIntakeTakenBy && (
-												<span className="med-schedule-person">
-													{intake.takenBy}
-													{showIntakeBell && (
-														<span className="med-schedule-bell" role="img" aria-label={t("tooltips.intakeReminders")}>
-															<Bell size={13} aria-hidden="true" />
-														</span>
-													)}
-												</span>
-											)}
-											{!hasPerIntakeTakenBy && showIntakeBell && (
-												<span className="med-schedule-bell" role="img" aria-label={t("tooltips.intakeReminders")}>
-													<Bell size={13} aria-hidden="true" />
-												</span>
-											)}
+											{hasPerIntakeTakenBy && <span className="med-schedule-person">{intake.takenBy}</span>}
 											<span className="med-schedule-time">
 												{t("modal.at")}{" "}
 												{new Date(intake.start).toLocaleTimeString(getSystemLocale(i18n.language), {
@@ -845,6 +1006,11 @@ export function MedDetailModal({
 													minute: "2-digit",
 												})}
 											</span>
+											{showIntakeBell && (
+												<span className="med-schedule-bell" title={t("form.blisters.remindTooltip")}>
+													<Bell size={12} aria-hidden="true" />
+												</span>
+											)}
 										</div>
 									);
 								})}
@@ -954,12 +1120,11 @@ export function MedDetailModal({
 											</span>
 											<span className="refill-amount">
 												{(() => {
-													const total =
-														selectedMed.packageType === "bottle"
-															? entry.loosePillsAdded
-															: entry.packsAdded * selectedMed.blistersPerPack * selectedMed.pillsPerBlister +
-																entry.loosePillsAdded;
-													return `+${total} ${total === 1 ? t("common.pill") : t("common.pills")}`;
+													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 && (
 													<span className="refill-prescription-badge" title={t("refill.viaPrescription")}>
@@ -1058,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")}
@@ -1079,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")}
@@ -1102,7 +1284,7 @@ export function MedDetailModal({
 												onUsePrescriptionRefillChange(checked);
 												if (
 													checked &&
-													selectedMed.packageType === "blister" &&
+													!isAmountBasedPackageType(selectedMed.packageType) &&
 													refillPacks > remainingPrescriptionRefills
 												) {
 													onRefillPacksChange(remainingPrescriptionRefills);
@@ -1128,8 +1310,10 @@ export function MedDetailModal({
 									className="success"
 									onClick={() => onSubmitRefill(selectedMed.id, usePrescriptionRefill)}
 									disabled={
-										(selectedMed.packageType === "bottle"
-											? refillLoose < 1
+										(isAmountBasedPackageType(selectedMed.packageType)
+											? isCountBasedAmountRefillPackage
+												? amountRefillPackageCount < 1
+												: refillLoose < 1
 											: cappedRefillPacks < 1 && refillLoose < 1) ||
 										exceedsPrescriptionPackLimit ||
 										refillSaving
@@ -1138,13 +1322,17 @@ 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">
-											+{totalRefill} {totalRefill === 1 ? t("common.pill") : t("common.pills")}
+											+{totalRefill}
+											{isAmountPackage
+												? ` ${stockUnitLabel}`
+												: ` ${totalRefill === 1 ? t("common.pill") : t("common.pills")}`}
 										</span>
 									) : null;
 								})()}

frontend/src/components/MobileEditModal.tsx

@@ -5,12 +5,19 @@
 
 /* biome-ignore-all lint/a11y/noLabelWithoutControl: modal uses custom DateInput and static value fields */
 import { Bell, Minus, Plus, Trash2 } from "lucide-react";
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 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") {
+	if (isAmountBasedPackageType(form.packageType)) {
 		// For bottle type, looseTablets is the current stock
 		return Number(form.looseTablets) || 0;
 	}
@@ -125,6 +132,33 @@ export function MobileEditModal({
 	const [showNameValidation, setShowNameValidation] = useState(false);
 	const activeTabIndexRef = useRef(0);
 
+	const allowFractionalIntake = useMemo(() => {
+		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 (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 (isTubePackageType(form.packageType)) {
+				return form.medicationForm === "liquid" ? t("form.blisters.usageMl") : t("form.blisters.usageApplication");
+			}
+			if (form.pillForm === "capsule") return t("form.blisters.usageCapsules");
+			return t("form.blisters.usageTablets");
+		},
+		[form.packageType, form.medicationForm, form.pillForm, t]
+	);
+
+	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");
+
 	// Reset tab when modal opens
 	useEffect(() => {
 		if (show) {
@@ -387,27 +421,91 @@ 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)}
-											/>
-											{!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>
+												{PACKAGE_PROFILES.map((profile) => (
+													<option key={profile.value} value={profile.value}>
+														{t(profile.labelKey)}
+													</option>
+												))}
 											</select>
 										</label>
+										{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"])}
+												>
+													<option value="tablet">{t("form.medicationFormTablet")}</option>
+													<option value="capsule">{t("form.medicationFormCapsule")}</option>
+												</select>
+											</label>
+										)}
+										{isTubePackageType(form.packageType) && (
+											<label className="full">
+												{t("form.medicationForm")}
+												<select
+													className="select-field"
+													value={"topical"}
+													onChange={() => onHandleValueChange("medicationForm", "topical")}
+												>
+													<option value="topical">{t("form.medicationFormTopical")}</option>
+												</select>
+											</label>
+										)}
+										{isLiquidContainerPackageType(form.packageType) && (
+											<label className="full">
+												{t("form.medicationForm")}
+												<select
+													className="select-field"
+													value={"liquid"}
+													onChange={() => onHandleValueChange("medicationForm", "liquid")}
+												>
+													<option value="liquid">{t("form.medicationFormLiquid")}</option>
+												</select>
+											</label>
+										)}
+										{form.medicationEndDate && (
+											<label className="full">
+												{t("form.autoMarkObsoleteAfterEndDate")}
+												<span className="toggle-switch small">
+													<input
+														type="checkbox"
+														checked={form.autoMarkObsoleteAfterEndDate}
+														onChange={(e) => onHandleValueChange("autoMarkObsoleteAfterEndDate", e.target.checked)}
+													/>
+													<span className="toggle-slider"></span>
+												</span>
+											</label>
+										)}
 										<label className={`full ${fieldErrors.takenBy ? "has-error" : ""}`}>
 											{t("form.takenBy")}
 											<div className="tag-input-container">
@@ -480,101 +578,193 @@ export function MobileEditModal({
 								<div className={`form-tab-panel${activeTab === "stock" ? " active" : ""}`}>
 									<div className="full form-category">
 										<h4 className="form-category-title">{t("form.sections.stock")}</h4>
-										{form.packageType === "blister" ? (
-											<>
-												<label>
-													{t("form.packs")}
-													<FormNumberStepper
-														value={form.packCount}
-														onChange={(nextValue) => onHandleValueChange("packCount", nextValue)}
-														min={0}
-														decrementLabel={decrementValueLabel}
-														incrementLabel={incrementValueLabel}
-													/>
-												</label>
-												<label>
-													{t("form.blistersPerPack")}
-													<FormNumberStepper
-														value={form.blistersPerPack}
-														onChange={(nextValue) => onHandleValueChange("blistersPerPack", nextValue)}
-														min={1}
-														decrementLabel={decrementValueLabel}
-														incrementLabel={incrementValueLabel}
-													/>
-												</label>
-												<label>
-													{t("form.pillsPerBlister")}
-													<FormNumberStepper
-														value={form.pillsPerBlister}
-														onChange={(nextValue) => onHandleValueChange("pillsPerBlister", nextValue)}
-														min={1}
-														decrementLabel={decrementValueLabel}
-														incrementLabel={incrementValueLabel}
-													/>
-												</label>
-												<label>
-													{t("form.total")}
-													<div className="static-value">{deriveTotalFromForm(form)}</div>
-												</label>
-											</>
-										) : (
-											<>
-												<label>
-													{t("form.totalCapacity")}
-													<FormNumberStepper
-														value={form.totalPills}
-														onChange={(nextValue) => onHandleValueChange("totalPills", nextValue)}
-														min={0}
-														decrementLabel={decrementValueLabel}
-														incrementLabel={incrementValueLabel}
-													/>
-												</label>
-												<label>
-													{t("form.currentPills")}
-													<FormNumberStepper
-														value={form.looseTablets}
-														onChange={(nextValue) => onHandleValueChange("looseTablets", nextValue)}
-														min={0}
-														decrementLabel={decrementValueLabel}
-														incrementLabel={incrementValueLabel}
-													/>
-												</label>
-											</>
-										)}
-										{form.packageType === "bottle" && (
+										{(() => {
+											if (!isAmountBasedPackageType(form.packageType)) {
+												return (
+													<>
+														<label>
+															{t("form.packs")}
+															<FormNumberStepper
+																value={form.packCount}
+																onChange={(nextValue) => onHandleValueChange("packCount", nextValue)}
+																min={0}
+																decrementLabel={decrementValueLabel}
+																incrementLabel={incrementValueLabel}
+															/>
+														</label>
+														<label>
+															{t("form.blistersPerPack")}
+															<FormNumberStepper
+																value={form.blistersPerPack}
+																onChange={(nextValue) => onHandleValueChange("blistersPerPack", nextValue)}
+																min={1}
+																decrementLabel={decrementValueLabel}
+																incrementLabel={incrementValueLabel}
+															/>
+														</label>
+														<label>
+															{t("form.pillsPerBlister")}
+															<FormNumberStepper
+																value={form.pillsPerBlister}
+																onChange={(nextValue) => onHandleValueChange("pillsPerBlister", nextValue)}
+																min={1}
+																decrementLabel={decrementValueLabel}
+																incrementLabel={incrementValueLabel}
+															/>
+														</label>
+														<label>
+															{t("form.total")}
+															<div className="static-value">{deriveTotalFromForm(form)}</div>
+														</label>
+													</>
+												);
+											}
+
+											if (isTubePackageType(form.packageType)) {
+												return (
+													<>
+														<label>
+															{t("form.tubes")}
+															<div className="static-value">1</div>
+														</label>
+														<label className="full">
+															{t("form.packageAmountPerTube")}
+															<div className="dose-input-group">
+																<input
+																	type="text"
+																	inputMode="decimal"
+																	pattern="[0-9]*\.?[0-9]*"
+																	value={form.packageAmountValue ?? "0"}
+																	onChange={(e) => onHandleValueChange("packageAmountValue", e.target.value)}
+																	placeholder="0"
+																/>
+																<select
+																	value="g"
+																	disabled
+																	className="select-field dose-unit-select"
+																	aria-label={t("form.packageAmountUnitG")}
+																>
+																	<option value="g">{t("form.packageAmountUnitG")}</option>
+																</select>
+															</div>
+														</label>
+														<label>
+															{t("form.totalAmount")}
+															<div className="static-value">
+																{(Number(form.packCount) || 0) * (Number(form.packageAmountValue ?? 0) || 0)}{" "}
+																{t("form.packageAmountUnitG")}
+															</div>
+														</label>
+													</>
+												);
+											}
+
+											if (isLiquidContainerPackageType(form.packageType)) {
+												return (
+													<>
+														<label>
+															{t("form.bottles")}
+															<FormNumberStepper
+																value={form.packCount}
+																onChange={(nextValue) => onHandleValueChange("packCount", nextValue)}
+																min={1}
+																decrementLabel={decrementValueLabel}
+																incrementLabel={incrementValueLabel}
+															/>
+														</label>
+														<label className="full">
+															{t("form.packageAmountPerBottle")}
+															<div className="dose-input-group">
+																<input
+																	type="text"
+																	inputMode="decimal"
+																	pattern="[0-9]*\.?[0-9]*"
+																	value={form.packageAmountValue ?? "0"}
+																	onChange={(e) => onHandleValueChange("packageAmountValue", e.target.value)}
+																	placeholder="0"
+																/>
+																<select
+																	value="ml"
+																	disabled
+																	className="select-field dose-unit-select"
+																	aria-label={t("form.packageAmountUnitMl")}
+																>
+																	<option value="ml">{t("form.packageAmountUnitMl")}</option>
+																</select>
+															</div>
+														</label>
+														<label>
+															{t("form.totalAmount")}
+															<div className="static-value">
+																{(Number(form.packCount) || 0) * (Number(form.packageAmountValue ?? 0) || 0)}{" "}
+																{t("form.packageAmountUnitMl")}
+															</div>
+														</label>
+													</>
+												);
+											}
+
+											return (
+												<>
+													<label>
+														{totalCapacityLabel}
+														<FormNumberStepper
+															value={form.totalPills}
+															onChange={(nextValue) => onHandleValueChange("totalPills", nextValue)}
+															min={0}
+															decrementLabel={decrementValueLabel}
+															incrementLabel={incrementValueLabel}
+														/>
+													</label>
+													<label>
+														{currentStockLabel}
+														<FormNumberStepper
+															value={form.looseTablets}
+															onChange={(nextValue) => onHandleValueChange("looseTablets", nextValue)}
+															min={0}
+															decrementLabel={decrementValueLabel}
+															incrementLabel={incrementValueLabel}
+														/>
+													</label>
+												</>
+											);
+										})()}
+										{isAmountBasedPackageType(form.packageType) && !isTubePackageType(form.packageType) && (
 											<div className="full stock-total-row">
 												<div className="stock-total-field">
 													<p className="sub">
-														<strong>{t("form.total")}:</strong> {deriveTotalFromForm(form)}{" "}
-														{deriveTotalFromForm(form) === 1 ? t("common.pill") : t("common.pills")}
+														<strong>{totalLabel}:</strong> {deriveTotalFromForm(form)}
+														{` ${deriveTotalFromForm(form) === 1 ? t("common.pill") : t("common.pills")}`}
 													</p>
 												</div>
 											</div>
 										)}
-										<label className="full">
-											{t("form.pillWeight")} ({form.doseUnit})
-											<div className="dose-input-group">
-												<input
-													type="text"
-													inputMode="decimal"
-													pattern="[0-9]*\.?[0-9]*"
-													value={form.pillWeightMg}
-													onChange={(e) => onFormChange({ ...form, pillWeightMg: e.target.value })}
-													placeholder={t("form.placeholders.weight")}
-												/>
-												<select
-													value={form.doseUnit}
-													onChange={(e) => onFormChange({ ...form, doseUnit: e.target.value as DoseUnit })}
-													className="dose-unit-select"
-												>
-													{DOSE_UNITS.map((unit) => (
-														<option key={unit.value} value={unit.value}>
-															{unit.label}
-														</option>
-													))}
-												</select>
-											</div>
-										</label>
+										{allowsPillFormSelection(form.packageType) && (
+											<label className="full">
+												{t("form.pillWeight")} ({form.doseUnit})
+												<div className="dose-input-group">
+													<input
+														type="text"
+														inputMode="decimal"
+														pattern="[0-9]*\.?[0-9]*"
+														value={form.pillWeightMg}
+														onChange={(e) => onFormChange({ ...form, pillWeightMg: e.target.value })}
+														placeholder={t("form.placeholders.weight")}
+													/>
+													<select
+														value={form.doseUnit}
+														onChange={(e) => onFormChange({ ...form, doseUnit: e.target.value as DoseUnit })}
+														className="select-field dose-unit-select"
+													>
+														{DOSE_UNITS.map((unit) => (
+															<option key={unit.value} value={unit.value}>
+																{unit.label}
+															</option>
+														))}
+													</select>
+												</div>
+											</label>
+										)}
 										<label className="full">
 											{t("form.expiryDate")}
 											<DateInput
@@ -626,17 +816,17 @@ export function MobileEditModal({
 										</div>
 										{form.intakes.map((intake, idx) => (
 											<div
-												key={`${intake.startDate}-${intake.startTime}-${intake.usage}-${intake.every}-${intake.takenBy ?? ""}`}
+												key={`${intake.startDate}-${intake.startTime}-${intake.usage}-${intake.every}-${intake.takenBy ?? ""}-${idx}`}
 												className="blister-row"
 											>
 												<label className="compact">
-													<span>{t("form.blisters.usage")}</span>
+													<span>{getUsageLabel(intake)}</span>
 													<FormNumberStepper
 														value={intake.usage}
 														onChange={(nextValue) => onSetIntakeValue(idx, "usage", nextValue)}
-														min={0.5}
-														step={0.5}
-														allowDecimal={true}
+														min={allowFractionalIntake ? 0.5 : 1}
+														step={allowFractionalIntake ? 0.5 : 1}
+														allowDecimal={allowFractionalIntake}
 														decrementLabel={decrementValueLabel}
 														incrementLabel={incrementValueLabel}
 													/>
@@ -666,10 +856,27 @@ export function MobileEditModal({
 														onChange={(e) => onSetIntakeValue(idx, "startTime", e.target.value)}
 													/>
 												</label>
+												{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")
+															}
+														>
+															<option value="ml">{t("form.blisters.intakeUnitMl")}</option>
+															<option value="tsp">{t("form.blisters.intakeUnitTsp")}</option>
+															<option value="tbsp">{t("form.blisters.intakeUnitTbsp")}</option>
+														</select>
+													</label>
+												)}
 												{form.takenBy.length === 0 ? null : (
 													<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";
@@ -298,6 +304,39 @@ function fmtDateTime(iso: string | null | undefined): string {
 	return `${m[3]}.${m[2]}.${m[1]} ${m[4]}:${m[5]}`;
 }
 
+function getTubeUnitKey(med: Medication): "form.ml" | "blisters.applications" {
+	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 (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 (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 (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 (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");
+}
+
 function generateTextReport(
 	meds: Medication[],
 	reportData: ReportData,
@@ -340,19 +379,18 @@ function generateTextReport(
 
 		// Package / Stock
 		lines.push(h3(t("report.docPackage")));
-		lines.push(
-			item(t("report.docPackageType"), med.packageType === "bottle" ? t("report.docBottle") : t("report.docBlister"))
-		);
-		if (med.packageType === "blister") {
+		lines.push(item(t("report.docPackageType"), getReportPackageTypeLabel(med, t)));
+		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)));
 			if (med.looseTablets > 0) lines.push(item(t("report.docLoosePills"), String(med.looseTablets)));
 		} else {
-			lines.push(item(t("report.docTotalCapacity"), String(med.totalPills ?? med.looseTablets)));
+			lines.push(item(getTotalCapacityLabel(med, t), String(med.totalPills ?? med.looseTablets)));
 		}
-		lines.push(item(t("report.docCurrentStock"), `${getPackageSize(med)} ${t("common.pills")}`));
-		if (med.pillWeightMg) lines.push(item(t("report.docDosePerPill"), `${med.pillWeightMg} ${med.doseUnit ?? "mg"}`));
+		lines.push(item(t("report.docCurrentStock"), getCurrentStockText(med, t)));
+		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));
 		lines.push("");
@@ -365,7 +403,7 @@ function generateTextReport(
 		if (intakes?.length) {
 			lines.push(h3(t("report.docIntakeSchedule")));
 			for (const intake of intakes) {
-				let entry = `${intake.usage} ${intake.usage === 1 ? t("common.pill") : t("common.pills")}`;
+				let entry = getUsageText(med, intake.usage, t);
 				entry += ` ${intake.every === 1 ? t("common.daily") : t("common.everyNDays", { count: intake.every })}`;
 				entry += ` ${t("form.blisters.from")} ${fmtDateTime(intake.start)}`;
 				if ("takenBy" in intake && intake.takenBy)
@@ -407,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} ${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}`);
 				}
@@ -539,18 +577,18 @@ function buildPrintHtml(
 		// Package / Stock
 		s += `<h3>${escHtml(t("report.docPackage"))}</h3>`;
 		s += `<table><tbody>`;
-		s += `<tr><td class="label">${escHtml(t("report.docPackageType"))}</td><td>${escHtml(med.packageType === "bottle" ? t("report.docBottle") : t("report.docBlister"))}</td></tr>`;
-		if (med.packageType === "blister") {
+		s += `<tr><td class="label">${escHtml(t("report.docPackageType"))}</td><td>${escHtml(getReportPackageTypeLabel(med, t))}</td></tr>`;
+		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>`;
 			if (med.looseTablets > 0)
 				s += `<tr><td class="label">${escHtml(t("report.docLoosePills"))}</td><td>${med.looseTablets}</td></tr>`;
 		} else {
-			s += `<tr><td class="label">${escHtml(t("report.docTotalCapacity"))}</td><td>${med.totalPills ?? med.looseTablets}</td></tr>`;
+			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>${getPackageSize(med)} ${escHtml(t("common.pills"))}</td></tr>`;
-		if (med.pillWeightMg)
+		s += `<tr><td class="label">${escHtml(t("report.docCurrentStock"))}</td><td>${escHtml(getCurrentStockText(med, t))}</td></tr>`;
+		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>`;
@@ -567,7 +605,7 @@ function buildPrintHtml(
 			s += `<h3>${escHtml(t("report.docIntakeSchedule"))}</h3>`;
 			s += `<ul>`;
 			for (const intake of filteredPrintIntakes) {
-				let entry = `${intake.usage} ${escHtml(intake.usage === 1 ? t("common.pill") : t("common.pills"))}`;
+				let entry = escHtml(getUsageText(med, intake.usage, t));
 				entry += ` ${escHtml(intake.every === 1 ? t("common.daily") : t("common.everyNDays", { count: intake.every }))}`;
 				entry += ` ${escHtml(t("form.blisters.from"))} ${fmtDateTime(intake.start)}`;
 				if ("takenBy" in intake && intake.takenBy)
@@ -614,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(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>`;
 				}