feat: update default persistence to MongoDB and enhance configuration options

- Implement lazy MongoDB client initialization in backend/db/mongo_client.py.
- Create Gunicorn configuration to ensure MongoDB client is initialized per worker.
- Refactor database access layer to support MongoDB with a new MongoLockedTable adapter.
- Add migration script to transfer existing TinyDB data to MongoDB, preserving idempotency.
- Update tracking event handling to ensure deterministic ordering with a monotonic sequence.
- Modify tests to use mongomock for MongoDB integration and ensure existing tests pass.
- Add integration test script to run tests against a local MongoDB Docker container.
- Document environment variables and migration process in specs/feat-database-migration.md.

.gitea/workflows/promote-master.yaml

@@ -394,7 +394,7 @@ jobs:
             fi
 
             frontend_ok=false
-            if curl -kfsS "https://localhost:${frontend_host_port}/" >/dev/null 2>&1; then
+            if curl -fsS "http://localhost:${frontend_host_port}/" >/dev/null 2>&1; then
               frontend_ok=true
             fi
 

.gitignore

@@ -10,3 +10,5 @@ backend/test-results/
 **/.DS_Store
 frontend/cert.pem
 frontend/key.pem
+tmp/
+backend/.env*

.opencode/agents/architect.md

@@ -0,0 +1,98 @@
+---
+name: architect
+description: "Defines system requirements, data contracts, and architectural blueprints."
+mode: subagent
+model: "deepseek/deepseek-v4-pro"
+thinking: "enabled"
+permission:
+  edit: allow
+  bash: deny
+---
+
+You are the Lead Systems Architect. You are responsible for ensuring all subagents work from a shared technical specification. Understand the codebase deeply, identify and ask about underspecified details, design elegant architectures
+
+## Core Responsibilities
+
+- **Specification:** Create and maintain `specs/` markdown files for new features.
+- **Clarity:** Understand before acting — Read and comprehend existing code patterns first.
+- **Contracts:** Define API payload shapes (JSON schemas), Python type hints, and Vue prop interfaces before any code is written.
+- **Decision Log:** Maintain a `decisions.md` file to track _why_ certain architectural choices were made (e.g., why you chose a specific Vue state management pattern).
+
+## Working discipline
+
+These bias toward caution over speed — use judgment on trivial tasks.
+
+- **Think before acting** — state assumptions; if the request has more than one reading, surface them instead of silently choosing; if a simpler path exists, say so.
+- **Simplicity first** — the minimum that solves the problem; no speculative features, abstractions, configurability, or handling of impossible cases.
+- **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it.
+- **Goal-driven** — turn the task into a concrete success check and iterate until it passes.
+
+## Phase 1: Discovery
+
+Goal: Understand what needs to be built.
+
+1. Create a todo list covering all seven phases.
+2. If the feature is unclear, ask the user:
+   - What problem are they solving?
+   - What should the feature do?
+   - Any constraints or requirements?
+3. Summarize your understanding and confirm with the user before proceeding.
+
+## Phase 2: Codebase exploration
+
+Goal: Understand relevant existing code at both high and low levels.
+
+1. Dispatch 2–3 `code-explorer` sub-tasks in parallel. Each should:
+   - Trace through the code comprehensively, focusing on abstractions, architecture, and control flow.
+   - Target a different aspect (similar features, high-level architecture, UX, extension points).
+   - Return a list of 5–10 key files to read.
+2. After they return, read every file they identified to build deep understanding.
+3. Present a comprehensive summary of findings and patterns to the user.
+
+## Phase 3: Clarifying questions
+
+Goal: Fill gaps and resolve ambiguities before designing.
+
+**This is one of the most important phases. Do not skip.**
+
+1. Review the codebase findings and the original feature request.
+2. Identify underspecified aspects: edge cases, error handling, integration points, scope boundaries, design preferences, backward compatibility, performance.
+3. Present all questions to the user as a clear, organized list.
+4. **Wait for answers** before moving to architecture.
+
+If the user says "whatever you think is best", make your recommendation explicit and get confirmation.
+
+## Phase 4: Architecture design
+
+Goal: Design multiple implementation approaches with different trade-offs.
+
+1. Dispatch 2–3 `code-architect` sub-tasks in parallel, each with a different focus:
+   - **Minimal changes** — smallest diff, maximum reuse of existing code.
+   - **Clean architecture** — maintainability, elegant abstractions.
+   - **Pragmatic balance** — speed plus quality.
+2. Review all approaches and form an opinion on which fits best for this task. Consider scope (small fix vs. large feature), urgency, complexity, and team context.
+3. Present to the user: a brief summary of each approach, a trade-offs comparison, your recommendation with reasoning, and concrete differences in implementation.
+4. **Ask the user which approach they prefer.**
+
+## Phase 5: Create Spec
+
+Goal: Build the spec.
+**Do not start without explicit user approval.**
+
+1. Wait for approval.
+2. Re-read all relevant files identified earlier.
+3. Spec following the chosen architecture. We are not writing code, just the specification.
+4. Strictly follow codebase conventions (naming, style, error-handling patterns).
+5. Update todos as you progress.
+
+## Phase 6: Summary
+
+Goal: Document what was accomplished.
+
+1. Mark all todos complete.
+2. Save spec to specs/[feature-name].md
+3. Summarize:
+   - What was built
+   - Key decisions made
+   - Files modified
+   - Suggest running the @feature-pipeline skill to begin implementation

.opencode/agents/developer.md

@@ -0,0 +1,28 @@
+---
+name: Developer
+description: Implements core application features across Python backends and Vue frontends.
+mode: subagent
+model: moonshotai/kimi-k2.7-code
+temperature: 0.2
+maxSteps: 50
+permission:
+  edit: allow
+  bash: allow
+options:
+  reasoningEffort: high
+  thinking:
+    type: enabled
+---
+
+You are an expert full-stack developer focused on building clean, modular features.
+
+### Technical Stack Focus
+
+- **Backend:** Python. Prioritize clean architecture, explicit type hinting, and robust error/exception handling.
+- **Frontend:** Vue 3. Utilize the Composition API, structured reactive state management, and semantic components.
+
+### Core Instructions
+
+1. Maintain a strong separation of concerns between business logic and the transport layer.
+2. Match the established formatting, design tokens, and architectural conventions of the existing codebase.
+3. Avoid pulling in heavy external dependencies when clean native implementations are straightforward.

.opencode/agents/reviewer.md

@@ -0,0 +1,29 @@
+---
+name: reviewer
+description: "Performs read-only code reviews, security audits, and architectural soundness checks on Python/Vue code."
+mode: "subagent"
+model: deepseek/deepseek-v4-pro
+temperature: 0.2
+maxSteps: 50
+permission:
+  edit: deny
+  bash: allow
+options:
+  reasoningEffort: max
+  thinking:
+    type: enabled
+---
+
+You are a specialized code reviewer subagent.
+
+### Strict Constraints
+
+- **Read-Only Context:** Your role is to analyze, critique, and guide. Do not use `write`, `edit`, or patch tools to modify the workspace files directly.
+
+### Audit Focus Areas
+
+- Ensure asynchronous tasks in your Vue components balance resource utilization correctly.
+- Catch containerization bottlenecks or environment sync gaps in Docker configurations.
+- Verify strict typing boundaries between backend Python data models and frontend components.
+
+Provide feedback by explicitly noting the file, logical block, and detected issue.

.opencode/agents/tester.md

@@ -0,0 +1,32 @@
+---
+name: tester
+description: "Holistic QA: Manages unit, integration, and writes and auto-repairs E2E test suites."
+mode: "subagent"
+model: "moonshotai/kimi-k2.7-code"
+permission:
+  edit: allow
+  bash:
+    "pytest *": "allow"
+    "npx playwright *": "allow"
+    "playwright-cli *": "allow"
+    "npm *": "ask"
+---
+
+You are a comprehensive QA Engineer. You own the quality of the entire repository.
+
+## Operational Directives
+
+- **Unit Testing:** Audit the Developer's unit tests. If you identify missing coverage for edge cases, write the additional unit tests yourself.
+- **Front End Testing:** Audit the Developers frontend tests. If you identify missing coverage for edge cases, write the additional unit tests yourself.
+- **E2E Ownership:** Author and maintain all Playwright E2E suites using the playwright-cli skills. Prioritize user-facing locators (`getByRole`, `getByLabel`).
+- **Gatekeeping:** Before any task is considered "Done," run the full suite (unit + E2E). If a test fails, you own the investigation.
+- **Verification:** When a failure occurs, do not just notify. Trace the stack trace, identify the breaking commit or configuration change, and suggest a fix.
+
+## Autonomous Repair Protocol
+
+When executing tests (especially `playwright`):
+
+1. **Analyze Failure:** If a test fails, do not just report. Parse the stack trace, identifying if the error is a `locator` issue, a `timeout` issue, or a `logic` error.
+2. **The "Application Bug" Check:** If the failure indicates that the _application code_ is incorrect (rather than the test locator), **STOP**. Ask the user if you should fix the application logic or if the test is wrong.
+3. **Looping:** You have permission to fix the test (e.g., update a locator) and re-run.
+4. **Safety Limit:** Do not run more than 3 repair attempts per test file. If it fails 3 times, stop, output the logs, and ask for help.

.opencode/agents/writer.md

@@ -0,0 +1,24 @@
+---
+description: "Drafts and updates technical documentation, architecture guides, and API specs."
+mode: "subagent"
+model: "deepseek/deepseek/deepseek-v4-flash"
+permission:
+  edit: allow
+  bash: deny
+options:
+  thinking:
+    type: disabled
+---
+
+You are a technical writer who communicates complex software architectures with pinpoint precision.
+
+### Deliverables
+
+- Clear, architectural READMEs, system setup guides, and internal team runbooks.
+- Clean API documentation maps outlining payload shapes, status codes, and endpoint routing.
+
+### Style Guide
+
+1. Keep prose technical, precise, and highly scannable.
+2. Avoid generic corporate or marketing phrases. Lead with the technical details immediately.
+3. Maximize the use of Markdown tables, bulleted structural lists, and code blocks for readability.

.opencode/commands/code-architect.md

@@ -0,0 +1,58 @@
+---
+description: Design a feature architecture by analyzing existing codebase patterns and conventions, then provide a comprehensive implementation blueprint with specific files to create or modify, component designs, data flows, and a build sequence. Use this skill when the user asks for an architecture design, an implementation plan for a non-trivial feature, or when dispatched as a sub-task during feature-dev architecture phase.
+---
+
+# Code Architect
+
+You are a senior software architect who delivers comprehensive, actionable architecture blueprints by deeply understanding codebases and making confident architectural decisions.
+
+## Working discipline
+
+These bias toward caution over speed — use judgment on trivial tasks.
+
+- **Think before acting** — state assumptions; if the request has more than one reading, surface them instead of silently choosing; if a simpler path exists, say so.
+- **Simplicity first** — the minimum that solves the problem; no speculative features, abstractions, configurability, or handling of impossible cases.
+- **Surgical changes** — touch only what the task needs; do not refactor or restyle adjacent code; match existing style; clean up only the orphans your change created, and mention unrelated dead code rather than deleting it.
+- **Goal-driven** — turn the task into a concrete success check and iterate until it passes.
+
+## Core process
+
+### 1. Codebase pattern analysis
+
+Extract existing patterns, conventions, and architectural decisions. Identify:
+
+- The technology stack
+- Module boundaries and abstraction layers
+- Project guidelines (`CLAUDE.md` / `AGENTS.md`)
+- Similar features already implemented — how were they structured?
+- Key abstractions the codebase already provides
+
+### 2. Architecture design
+
+Based on patterns found, design the complete feature architecture:
+
+- Make decisive choices. Pick one approach and commit to it.
+- Ensure seamless integration with existing code.
+- Design for testability, performance, and maintainability.
+
+### 3. Complete implementation blueprint
+
+Specify every file to create or modify, component responsibilities, integration points, and data flow. Break the implementation into clear phases.
+
+## Output
+
+Deliver a decisive, complete architecture blueprint. Include:
+
+- **Patterns & conventions found** — list existing patterns with `file:line` references, similar features, and key abstractions to leverage.
+- **Architecture decision** — your chosen approach with rationale and trade-offs.
+- **Component design** — each component with its file path, responsibilities, dependencies, and interfaces.
+- **Implementation map** — specific files to create or modify, with detailed change descriptions.
+- **Data flow** — complete flow from entry points through transformations to outputs.
+- **Build sequence** — phased implementation steps as a checklist.
+- **Critical details** — error handling, state management, testing approach, performance, security.
+
+Make confident architectural choices. Be specific and actionable: provide file paths, function names, and concrete steps. Avoid presenting multiple equally-weighted options unless the user specifically asked for trade-off analysis.
+
+---
+
+**User arguments:** $ARGUMENTS

.opencode/commands/code-explorer.md

@@ -0,0 +1,58 @@
+---
+description: Deeply analyze an existing codebase feature by tracing execution paths, mapping architecture layers, understanding patterns and abstractions, and documenting dependencies. Use this skill when you need to understand how a feature works before modifying or extending it, when dispatched as a sub-task during feature-dev exploration, or when the user asks "how does X work in this codebase".
+---
+
+# Code Explorer
+
+You are an expert code analyst specializing in tracing and understanding feature implementations across codebases.
+
+## Core mission
+
+Provide a complete understanding of how a specific feature works by tracing its implementation from entry points to data storage, through all abstraction layers.
+
+## Analysis approach
+
+### 1. Feature discovery
+
+- Find entry points: APIs, UI components, CLI commands.
+- Locate core implementation files.
+- Map feature boundaries and configuration surface.
+
+### 2. Code-flow tracing
+
+- Follow call chains from entry to output.
+- Trace data transformations at each step.
+- Identify all dependencies and integrations.
+- Document state changes and side effects.
+
+### 3. Architecture analysis
+
+- Map abstraction layers: presentation → business logic → data.
+- Identify design patterns and architectural decisions.
+- Document interfaces between components.
+- Note cross-cutting concerns: auth, logging, caching, observability.
+
+### 4. Implementation details
+
+- Key algorithms and data structures.
+- Error handling and edge cases.
+- Performance considerations.
+- Technical debt or improvement areas.
+
+## Output
+
+Deliver a comprehensive analysis that helps developers understand the feature deeply enough to modify or extend it. Always include:
+
+- **Entry points** with `file:line` references
+- **Step-by-step execution flow** with data transformations
+- **Key components** and their responsibilities
+- **Architecture insights** — patterns, layers, design decisions
+- **Dependencies** — internal and external
+- **Observations** about strengths, issues, or opportunities
+- **Essential files list** — the files a developer absolutely must read to understand this topic
+
+Structure the response for maximum clarity and usefulness. Always cite specific file paths and line numbers.
+
+---
+
+**User arguments:** $ARGUMENTS

.opencode/skills/bugfix/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: bugfix
+description: "Executes a bugfix pipeline on one or more gitea issues: Developer -> Tester -> Reviewer"
+---
+
+## What I do
+
+I orchestrate a sequential bugfix and verification pipeline - I will retrieve issues(s) from Gitea (title, body, images, comments, etc...). I will then forward information from the issues to the respective subagents.
+
+Use gitea-mcp-server to interact with Gitea. Verify that the server is running and accessible.
+
+If an issue is not provided, ask the user for the issue number(s).
+
+1. **Developer**: Provides a code fix for each issue.
+2. **Reviewer**: Audits the code and architectural soundness.
+3. **Tester**: Runs tests related to the bugfix and determines if new unit tests, integration tests, or end-to-end tests are needed. If so, implement. Verify by running the test suite.
+
+## Execution Rules
+
+- Stop and ask the user for clarification if a step fails or is ambiguous.
+- Use the `@` mention to trigger the respective subagents sequentially.
+- Pass the context from the previous stage to the next stage to ensure consistency.
+- Use multiple subagents to handle different aspects of the bugfix process if it will help.
+
+## When to use me
+
+Invoke me when you are ready to fix a Gitea issue or multiple issues.

.opencode/skills/e2e-repair/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: e2e-repair
+description: "Runs playwright tests, captures errors, and triggers auto-repair."
+---
+
+## Logic
+
+1. Execute: `npx playwright test [test_file]`
+2. If Success:
+   - Report success.
+   - Exit.
+3. If Failure:
+   - Capture output.
+   - Pass logs to @tester agent.
+   - @tester analyzes error and edits file.
+   - Repeat until success or max_retries reached.
+
+## Safety Guardrails
+
+- Make use of playwright-cli skills for test execution and repair.
+- Max Retries: 3 per file.
+- If the error persists after 3 retries, report: "Repair exhausted: Please review logs."

.opencode/skills/feature-pipeline/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: feature-pipeline
+description: "Executes the full dev-to-docs pipeline: Developer -> Tester -> Reviewer -> Writer."
+---
+
+## What I do
+
+I orchestrate a sequential feature implementation and verification pipeline:
+
+1. **Developer**: Implements the feature based on the spec.
+2. **Reviewer**: Audits the code and architectural soundness.
+3. **Tester**: Runs full unit/E2E test suites; repairs failures if found.
+4. **Writer**: Updates README and API docs based on verified code.
+
+## Execution Rules
+
+- Stop and ask the user for clarification if a step fails or is ambiguous.
+- Use the `@` mention to trigger the respective subagents sequentially.
+- Pass the context from the previous stage to the next stage to ensure consistency.
+
+## When to use me
+
+Invoke me when you are ready to begin a new feature or when the Architect has finished a specification.

.opencode/skills/playwright-cli/SKILL.md

@@ -0,0 +1,420 @@
+---
+name: playwright-cli
+description: Automate browser interactions, test web pages and work with Playwright tests.
+allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)
+---
+
+# Browser Automation with playwright-cli
+
+## Quick start
+
+```bash
+# open new browser
+playwright-cli open
+# navigate to a page
+playwright-cli goto https://playwright.dev
+# interact with the page using refs from the snapshot
+playwright-cli click e15
+playwright-cli type "page.click"
+playwright-cli press Enter
+# take a screenshot (rarely used, as snapshot is more common)
+playwright-cli screenshot
+# close the browser
+playwright-cli close
+```
+
+## Commands
+
+### Core
+
+```bash
+playwright-cli open
+# open and navigate right away
+playwright-cli open https://example.com/
+playwright-cli goto https://playwright.dev
+playwright-cli type "search query"
+playwright-cli click e3
+playwright-cli dblclick e7
+# --submit presses Enter after filling the element
+playwright-cli fill e5 "user@example.com"  --submit
+playwright-cli drag e2 e8
+# drop files or data onto an element (from outside the page)
+playwright-cli drop e4 --path=./image.png
+playwright-cli drop e4 --data="text/plain=hello world"
+playwright-cli hover e4
+playwright-cli select e9 "option-value"
+playwright-cli upload ./document.pdf
+playwright-cli check e12
+playwright-cli uncheck e12
+playwright-cli snapshot
+# search the snapshot for text or a regexp, returns matching nodes with surrounding context
+playwright-cli find "Sign in"
+playwright-cli find --regex "Sign (in|up)"
+# wrap the regexp in slashes to add flags, e.g. /i for case-insensitive
+playwright-cli find --regex "/sign (in|up)/i"
+playwright-cli eval "document.title"
+playwright-cli eval "el => el.textContent" e5
+# get element id, class, or any attribute not visible in the snapshot
+playwright-cli eval "el => el.id" e5
+playwright-cli eval "el => el.getAttribute('data-testid')" e5
+playwright-cli dialog-accept
+playwright-cli dialog-accept "confirmation text"
+playwright-cli dialog-dismiss
+playwright-cli resize 1920 1080
+playwright-cli close
+```
+
+### Navigation
+
+```bash
+playwright-cli go-back
+playwright-cli go-forward
+playwright-cli reload
+```
+
+### Keyboard
+
+```bash
+playwright-cli press Enter
+playwright-cli press ArrowDown
+playwright-cli keydown Shift
+playwright-cli keyup Shift
+```
+
+### Mouse
+
+```bash
+playwright-cli mousemove 150 300
+playwright-cli mousedown
+playwright-cli mousedown right
+playwright-cli mouseup
+playwright-cli mouseup right
+playwright-cli mousewheel 0 100
+```
+
+### Save as
+
+```bash
+playwright-cli screenshot
+playwright-cli screenshot e5
+playwright-cli screenshot --filename=page.png
+playwright-cli screenshot --hires
+playwright-cli pdf --filename=page.pdf
+```
+
+### Tabs
+
+```bash
+playwright-cli tab-list
+playwright-cli tab-new
+playwright-cli tab-new https://example.com/page
+playwright-cli tab-close
+playwright-cli tab-close 2
+playwright-cli tab-select 0
+```
+
+### Storage
+
+```bash
+playwright-cli state-save
+playwright-cli state-save auth.json
+playwright-cli state-load auth.json
+
+# Cookies
+playwright-cli cookie-list
+playwright-cli cookie-list --domain=example.com
+playwright-cli cookie-get session_id
+playwright-cli cookie-set session_id abc123
+playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+playwright-cli cookie-delete session_id
+playwright-cli cookie-clear
+
+# LocalStorage
+playwright-cli localstorage-list
+playwright-cli localstorage-get theme
+playwright-cli localstorage-set theme dark
+playwright-cli localstorage-delete theme
+playwright-cli localstorage-clear
+
+# SessionStorage
+playwright-cli sessionstorage-list
+playwright-cli sessionstorage-get step
+playwright-cli sessionstorage-set step 3
+playwright-cli sessionstorage-delete step
+playwright-cli sessionstorage-clear
+```
+
+### Network
+
+```bash
+playwright-cli route "**/*.jpg" --status=404
+playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
+playwright-cli route-list
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+### DevTools
+
+```bash
+playwright-cli console
+playwright-cli console warning
+playwright-cli requests
+playwright-cli request 5
+playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
+playwright-cli run-code --filename=script.js
+playwright-cli tracing-start
+playwright-cli tracing-stop
+playwright-cli video-start video.webm
+playwright-cli video-chapter "Chapter Title" --description="Details" --duration=2000
+playwright-cli video-stop
+
+# annotate each subsequent action (click, type, ...) with a callout naming the action and highlighting the target
+playwright-cli video-show-actions --duration=600 --position=top-right
+playwright-cli video-hide-actions
+
+# launch the dashboard for UI review / design feedback — user annotates the page, you receive the annotated screenshot, snapshot, and notes
+playwright-cli show --annotate
+
+# generate a Playwright locator for an element from its ref or selector
+playwright-cli generate-locator e5 --raw
+
+# show a persistent highlight overlay for an element, optionally with a custom style
+playwright-cli highlight e5
+playwright-cli highlight e5 --style="outline: 3px dashed red"
+# hide a single element highlight, or all page highlights when no target is given
+playwright-cli highlight e5 --hide
+playwright-cli highlight --hide
+```
+
+## Raw output
+
+The global `--raw` option strips page status, generated code, and snapshot sections from the output, returning only the result value. Use it to pipe command output into other tools. Commands that don't produce output return nothing.
+
+```bash
+playwright-cli --raw eval "JSON.stringify(performance.timing)" | jq '.loadEventEnd - .navigationStart'
+playwright-cli --raw eval "JSON.stringify([...document.querySelectorAll('a')].map(a => a.href))" > links.json
+playwright-cli --raw snapshot > before.yml
+playwright-cli click e5
+playwright-cli --raw snapshot > after.yml
+diff before.yml after.yml
+TOKEN=$(playwright-cli --raw cookie-get session_id)
+playwright-cli --raw localstorage-get theme
+```
+
+For structured output wrapping every reply as JSON, pass --json
+```bash
+playwright-cli list --json
+```
+
+## Open parameters
+```bash
+# Use specific browser when creating session
+playwright-cli open --browser=chrome
+playwright-cli open --browser=firefox
+playwright-cli open --browser=webkit
+playwright-cli open --browser=msedge
+
+# Emulate a generic mobile device (Pixel 10 for Chromium, iPhone 17 for WebKit).
+# Prefer this when a mobile layout is acceptable: mobile pages are usually
+# lighter, so snapshots are smaller and cheaper.
+playwright-cli open --mobile
+playwright-cli open --device="iPhone 15"
+
+# Use persistent profile (by default profile is in-memory)
+playwright-cli open --persistent
+# Use persistent profile with custom directory
+playwright-cli open --profile=/path/to/profile
+
+# Connect to browser via Playwright Extension
+playwright-cli attach --extension=chrome
+
+# Connect to a running Chrome or Edge by channel name
+playwright-cli attach --cdp=chrome
+playwright-cli attach --cdp=msedge
+
+# Connect to a running browser via CDP endpoint
+playwright-cli attach --cdp=http://localhost:9222
+
+# Start with config file
+playwright-cli open --config=my-config.json
+
+# Close the browser
+playwright-cli close
+# Detach from an attached browser (leaves the external browser running)
+playwright-cli -s=msedge detach
+# Delete user data for the default session
+playwright-cli delete-data
+```
+
+## URLs with `&` on Windows
+
+On Windows, `cmd.exe` and PowerShell treat `&` as a command separator, so URLs with multiple query parameters get truncated before `playwright-cli` runs. Escape `&` with `^&` in `cmd.exe`, or use `--%` in PowerShell:
+
+```batch
+playwright-cli goto "https://example.com/?a=1^&b=2"
+```
+
+```powershell
+playwright-cli --% goto "https://example.com/?a=1&b=2"
+```
+
+## Snapshots
+
+After each command, playwright-cli provides a snapshot of the current browser state.
+
+```bash
+> playwright-cli goto https://example.com
+### Page
+- Page URL: https://example.com/
+- Page Title: Example Domain
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+You can also take a snapshot on demand using `playwright-cli snapshot` command. All the options below can be combined as needed.
+
+```bash
+# default - save to a file with timestamp-based name
+playwright-cli snapshot
+
+# save to file, use when snapshot is a part of the workflow result
+playwright-cli snapshot --filename=after-click.yaml
+
+# snapshot an element instead of the whole page
+playwright-cli snapshot "#main"
+
+# limit snapshot depth for efficiency, take a partial snapshot afterwards
+playwright-cli snapshot --depth=4
+playwright-cli snapshot e34
+
+# include each element's bounding box as [box=x,y,width,height]
+playwright-cli snapshot --boxes
+
+# search a large snapshot instead of capturing it all — returns matching nodes
+# with 3 lines of context around each match (like grep -C)
+playwright-cli find "Add to cart"
+playwright-cli find --regex "\\$[0-9]+\\.[0-9]{2}"
+```
+
+## Targeting elements
+
+By default, use refs from the snapshot to interact with page elements.
+
+```bash
+# get snapshot with refs
+playwright-cli snapshot
+
+# interact using a ref
+playwright-cli click e15
+```
+
+You can also use css selectors or Playwright locators.
+
+```bash
+# css selector
+playwright-cli click "#main > button.submit"
+
+# role locator
+playwright-cli click "getByRole('button', { name: 'Submit' })"
+
+# test id
+playwright-cli click "getByTestId('submit-button')"
+```
+
+## Browser Sessions
+
+```bash
+# create new browser session named "mysession" with persistent profile
+playwright-cli -s=mysession open example.com --persistent
+# same with manually specified profile directory (use when requested explicitly)
+playwright-cli -s=mysession open example.com --profile=/path/to/profile
+playwright-cli -s=mysession click e6
+playwright-cli -s=mysession close  # stop a named browser
+playwright-cli -s=mysession delete-data  # delete user data for persistent session
+
+playwright-cli list
+# Close all browsers
+playwright-cli close-all
+# Forcefully kill all browser processes
+playwright-cli kill-all
+```
+
+## Installation
+
+If global `playwright-cli` command is not available, try a local version via `npx playwright cli`:
+
+```bash
+npx --no-install playwright --version
+```
+
+When local version is available, use `npx playwright cli` in all commands. Otherwise, install `playwright-cli` as a global command:
+
+```bash
+npm install -g @playwright/cli@latest
+```
+
+## Example: Form submission
+
+```bash
+playwright-cli open https://example.com/form
+playwright-cli snapshot
+
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Multi-tab workflow
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tab-new https://example.com/other
+playwright-cli tab-list
+playwright-cli tab-select 0
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Debugging with DevTools
+
+```bash
+playwright-cli open https://example.com
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli console
+playwright-cli requests
+playwright-cli close
+```
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tracing-start
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli tracing-stop
+playwright-cli close
+```
+
+## Example: Interactive session
+
+Ask the user for UI review or design feedback. The user draws boxes on the live page and types comments; you receive the annotated screenshot, the snapshot of the marked region, and the user's notes. Use this whenever the user asks for "UI review", "design feedback", or to "ask the user what they think / want / mean":
+
+```bash
+playwright-cli open https://example.com
+playwright-cli show --annotate
+```
+
+## Specific tasks
+
+* **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
+* **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+* **Running Playwright code** [references/running-code.md](references/running-code.md)
+* **Browser session management** [references/session-management.md](references/session-management.md)
+* **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+* **Test generation (plan / generate / heal)** [references/test-generation.md](references/test-generation.md)
+* **Tracing** [references/tracing.md](references/tracing.md)
+* **Video recording** [references/video-recording.md](references/video-recording.md)
+* **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)

.opencode/skills/playwright-cli/references/element-attributes.md

@@ -0,0 +1,23 @@
+# Inspecting Element Attributes
+
+When the snapshot doesn't show an element's `id`, `class`, `data-*` attributes, or other DOM properties, use `eval` to inspect them.
+
+## Examples
+
+```bash
+playwright-cli snapshot
+# snapshot shows a button as e7 but doesn't reveal its id or data attributes
+
+# get the element's id
+playwright-cli eval "el => el.id" e7
+
+# get all CSS classes
+playwright-cli eval "el => el.className" e7
+
+# get a specific attribute
+playwright-cli eval "el => el.getAttribute('data-testid')" e7
+playwright-cli eval "el => el.getAttribute('aria-label')" e7
+
+# get a computed style property
+playwright-cli eval "el => getComputedStyle(el).display" e7
+```

.opencode/skills/playwright-cli/references/playwright-tests.md

@@ -0,0 +1,39 @@
+# Running Playwright Tests
+
+To run Playwright tests, use the `npx playwright test` command, or a package manager script. To avoid opening the interactive html report, use `PLAYWRIGHT_HTML_OPEN=never` environment variable.
+
+```bash
+# Run all tests
+PLAYWRIGHT_HTML_OPEN=never npx playwright test
+
+# Run all tests through a custom npm script
+PLAYWRIGHT_HTML_OPEN=never npm run special-test-command
+```
+
+# Debugging Playwright Tests
+
+To debug a failing Playwright test, run it with `--debug=cli` option. This command will pause the test at the start and print the debugging instructions.
+
+**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed. Make sure to stop the command after you have finished.
+
+Once instructions containing a session name are printed, use `playwright-cli` to attach the session and explore the page.
+
+```bash
+# Run the test
+PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
+# ...
+# ... debugging instructions for "tw-abcdef" session ...
+# ...
+
+# Attach to the test
+playwright-cli attach tw-abcdef
+```
+
+Keep the test running in the background while you explore and look for a fix.
+The test is paused at the start, so you should step over or pause at a particular location
+where the problem is most likely to be.
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into the test. Most of the time, a specific locator or an expectation should be updated, but it could also be a bug in the app. Use your judgement.
+
+After fixing the test, stop the background test run. Rerun to check that test passes.

.opencode/skills/playwright-cli/references/request-mocking.md

@@ -0,0 +1,87 @@
+# Request Mocking
+
+Intercept, mock, modify, and block network requests.
+
+## CLI Route Commands
+
+```bash
+# Mock with custom status
+playwright-cli route "**/*.jpg" --status=404
+
+# Mock with JSON body
+playwright-cli route "**/api/users" --body='[{"id":1,"name":"Alice"}]' --content-type=application/json
+
+# Mock with custom headers
+playwright-cli route "**/api/data" --body='{"ok":true}' --header="X-Custom: value"
+
+# Remove headers from requests
+playwright-cli route "**/*" --remove-header=cookie,authorization
+
+# List active routes
+playwright-cli route-list
+
+# Remove a route or all routes
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+## URL Patterns
+
+```
+**/api/users           - Exact path match
+**/api/*/details       - Wildcard in path
+**/*.{png,jpg,jpeg}    - Match file extensions
+**/search?q=*          - Match query parameters
+```
+
+## Advanced Mocking with run-code
+
+For conditional responses, request body inspection, response modification, or delays:
+
+### Conditional Response Based on Request
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/login', route => {
+    const body = route.request().postDataJSON();
+    if (body.username === 'admin') {
+      route.fulfill({ body: JSON.stringify({ token: 'mock-token' }) });
+    } else {
+      route.fulfill({ status: 401, body: JSON.stringify({ error: 'Invalid' }) });
+    }
+  });
+}"
+```
+
+### Modify Real Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/user', async route => {
+    const response = await route.fetch();
+    const json = await response.json();
+    json.isPremium = true;
+    await route.fulfill({ response, json });
+  });
+}"
+```
+
+### Simulate Network Failures
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/offline', route => route.abort('internetdisconnected'));
+}"
+# Options: connectionrefused, timedout, connectionreset, internetdisconnected
+```
+
+### Delayed Response
+
+```bash
+playwright-cli run-code "async page => {
+  await page.route('**/api/slow', async route => {
+    await new Promise(r => setTimeout(r, 3000));
+    route.fulfill({ body: JSON.stringify({ data: 'loaded' }) });
+  });
+}"
+```

.opencode/skills/playwright-cli/references/running-code.md

@@ -0,0 +1,241 @@
+# Running Custom Playwright Code
+
+Use `run-code` to execute arbitrary Playwright code for advanced scenarios not covered by CLI commands.
+
+## Syntax
+
+```bash
+playwright-cli run-code "async page => {
+  // Your Playwright code here
+  // Access page.context() for browser context operations
+}"
+```
+
+You can also load the function from a file:
+
+```bash
+playwright-cli run-code --filename=./my-script.js
+```
+
+
+The code must be a single function expression, it is wrapped in `(...)` and evaluated.
+import/export/require syntax is not supported.
+
+## Geolocation
+
+```bash
+# Grant geolocation permission and set location
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
+}"
+
+# Set location to London
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['geolocation']);
+  await page.context().setGeolocation({ latitude: 51.5074, longitude: -0.1278 });
+}"
+
+# Clear geolocation override
+playwright-cli run-code "async page => {
+  await page.context().clearPermissions();
+}"
+```
+
+## Permissions
+
+```bash
+# Grant multiple permissions
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions([
+    'geolocation',
+    'notifications',
+    'camera',
+    'microphone'
+  ]);
+}"
+
+# Grant permissions for specific origin
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read'], {
+    origin: 'https://example.com'
+  });
+}"
+```
+
+## Media Emulation
+
+```bash
+# Emulate dark color scheme
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'dark' });
+}"
+
+# Emulate light color scheme
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ colorScheme: 'light' });
+}"
+
+# Emulate reduced motion
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+}"
+
+# Emulate print media
+playwright-cli run-code "async page => {
+  await page.emulateMedia({ media: 'print' });
+}"
+```
+
+## Wait Strategies
+
+```bash
+# Wait for network idle
+playwright-cli run-code "async page => {
+  await page.waitForLoadState('networkidle');
+}"
+
+# Wait for specific element
+playwright-cli run-code "async page => {
+  await page.locator('.loading').waitFor({ state: 'hidden' });
+}"
+
+# Wait for function to return true
+playwright-cli run-code "async page => {
+  await page.waitForFunction(() => window.appReady === true);
+}"
+
+# Wait with timeout
+playwright-cli run-code "async page => {
+  await page.locator('.result').waitFor({ timeout: 10000 });
+}"
+```
+
+## Frames and Iframes
+
+```bash
+# Work with iframe
+playwright-cli run-code "async page => {
+  const frame = page.locator('iframe#my-iframe').contentFrame();
+  await frame.locator('button').click();
+}"
+
+# Get all frames
+playwright-cli run-code "async page => {
+  const frames = page.frames();
+  return frames.map(f => f.url());
+}"
+```
+
+## File Downloads
+
+```bash
+# Handle file download
+playwright-cli run-code "async page => {
+  const downloadPromise = page.waitForEvent('download');
+  await page.getByRole('link', { name: 'Download' }).click();
+  const download = await downloadPromise;
+  await download.saveAs('./downloaded-file.pdf');
+  return download.suggestedFilename();
+}"
+```
+
+## Clipboard
+
+```bash
+# Read clipboard (requires permission)
+playwright-cli run-code "async page => {
+  await page.context().grantPermissions(['clipboard-read']);
+  return await page.evaluate(() => navigator.clipboard.readText());
+}"
+
+# Write to clipboard
+playwright-cli run-code "async page => {
+  await page.evaluate(text => navigator.clipboard.writeText(text), 'Hello clipboard!');
+}"
+```
+
+## Page Information
+
+```bash
+# Get page title
+playwright-cli run-code "async page => {
+  return await page.title();
+}"
+
+# Get current URL
+playwright-cli run-code "async page => {
+  return page.url();
+}"
+
+# Get page content
+playwright-cli run-code "async page => {
+  return await page.content();
+}"
+
+# Get viewport size
+playwright-cli run-code "async page => {
+  return page.viewportSize();
+}"
+```
+
+## JavaScript Execution
+
+```bash
+# Execute JavaScript and return result
+playwright-cli run-code "async page => {
+  return await page.evaluate(() => {
+    return {
+      userAgent: navigator.userAgent,
+      language: navigator.language,
+      cookiesEnabled: navigator.cookieEnabled
+    };
+  });
+}"
+
+# Pass arguments to evaluate
+playwright-cli run-code "async page => {
+  const multiplier = 5;
+  return await page.evaluate(m => document.querySelectorAll('li').length * m, multiplier);
+}"
+```
+
+## Error Handling
+
+```bash
+# Try-catch in run-code
+playwright-cli run-code "async page => {
+  try {
+    await page.getByRole('button', { name: 'Submit' }).click({ timeout: 1000 });
+    return 'clicked';
+  } catch (e) {
+    return 'element not found';
+  }
+}"
+```
+
+## Complex Workflows
+
+```bash
+# Login and save state
+playwright-cli run-code "async page => {
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('secret');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await page.waitForURL('**/dashboard');
+  await page.context().storageState({ path: 'auth.json' });
+  return 'Login successful';
+}"
+
+# Scrape data from multiple pages
+playwright-cli run-code "async page => {
+  const results = [];
+  for (let i = 1; i <= 3; i++) {
+    await page.goto(\`https://example.com/page/\${i}\`);
+    const items = await page.locator('.item').allTextContents();
+    results.push(...items);
+  }
+  return results;
+}"
+```

.opencode/skills/playwright-cli/references/session-management.md

@@ -0,0 +1,225 @@
+# Browser Session Management
+
+Run multiple isolated browser sessions concurrently with state persistence.
+
+## Named Browser Sessions
+
+Use `-s` flag to isolate browser contexts:
+
+```bash
+# Browser 1: Authentication flow
+playwright-cli -s=auth open https://app.example.com/login
+
+# Browser 2: Public browsing (separate cookies, storage)
+playwright-cli -s=public open https://example.com
+
+# Commands are isolated by browser session
+playwright-cli -s=auth fill e1 "user@example.com"
+playwright-cli -s=public snapshot
+```
+
+## Browser Session Isolation Properties
+
+Each browser session has independent:
+- Cookies
+- LocalStorage / SessionStorage
+- IndexedDB
+- Cache
+- Browsing history
+- Open tabs
+
+## Browser Session Commands
+
+```bash
+# List all browser sessions
+playwright-cli list
+
+# Stop a browser session (close the browser)
+playwright-cli close                # stop the default browser
+playwright-cli -s=mysession close   # stop a named browser
+
+# Stop all browser sessions
+playwright-cli close-all
+
+# Forcefully kill all daemon processes (for stale/zombie processes)
+playwright-cli kill-all
+
+# Delete browser session user data (profile directory)
+playwright-cli delete-data                # delete default browser data
+playwright-cli -s=mysession delete-data   # delete named browser data
+```
+
+## Environment Variable
+
+Set a default browser session name via environment variable:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION="mysession"
+playwright-cli open example.com  # Uses "mysession" automatically
+```
+
+## Common Patterns
+
+### Concurrent Scraping
+
+```bash
+#!/bin/bash
+# Scrape multiple sites concurrently
+
+# Start all browsers
+playwright-cli -s=site1 open https://site1.com &
+playwright-cli -s=site2 open https://site2.com &
+playwright-cli -s=site3 open https://site3.com &
+wait
+
+# Take snapshots from each
+playwright-cli -s=site1 snapshot
+playwright-cli -s=site2 snapshot
+playwright-cli -s=site3 snapshot
+
+# Cleanup
+playwright-cli close-all
+```
+
+### A/B Testing Sessions
+
+```bash
+# Test different user experiences
+playwright-cli -s=variant-a open "https://app.com?variant=a"
+playwright-cli -s=variant-b open "https://app.com?variant=b"
+
+# Compare
+playwright-cli -s=variant-a screenshot
+playwright-cli -s=variant-b screenshot
+```
+
+### Persistent Profile
+
+By default, browser profile is kept in memory only. Use `--persistent` flag on `open` to persist the browser profile to disk:
+
+```bash
+# Use persistent profile (auto-generated location)
+playwright-cli open https://example.com --persistent
+
+# Use persistent profile with custom directory
+playwright-cli open https://example.com --profile=/path/to/profile
+```
+
+## Attaching to a Running Browser
+
+Use `attach` to connect to a browser that is already running, instead of launching a new one.
+
+### Attach by channel name
+
+Connect to a running Chrome or Edge instance by its channel name. The browser must have remote debugging enabled — navigate to `chrome://inspect/#remote-debugging` in the target browser and check "Allow remote debugging for this browser instance".
+
+```bash
+# Attach to Chrome
+playwright-cli attach --cdp=chrome
+
+# Attach to Chrome Canary
+playwright-cli attach --cdp=chrome-canary
+
+# Attach to Microsoft Edge
+playwright-cli attach --cdp=msedge
+
+# Attach to Edge Dev
+playwright-cli attach --cdp=msedge-dev
+```
+
+Supported channels: `chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`, `msedge-beta`, `msedge-dev`, `msedge-canary`.
+
+When `--session` is not provided, the session is named after the channel (e.g. `--cdp=msedge` creates a session called `msedge`), so parallel attaches to Chrome and Edge don't collide on `default`. Pass `--session=<name>` to override.
+
+### Attach via CDP endpoint
+
+Connect to a browser that exposes a Chrome DevTools Protocol endpoint:
+
+```bash
+playwright-cli attach --cdp=http://localhost:9222
+```
+
+### Attach via browser extension
+
+Connect to a browser with the Playwright extension installed:
+
+```bash
+playwright-cli attach --extension
+```
+
+### Detach
+
+Tear down an attached session without affecting the external browser:
+
+```bash
+# Detach the default attached session
+playwright-cli detach
+
+# Detach a specific attached session
+playwright-cli -s=msedge detach
+```
+
+`detach` only works on sessions created via `attach`. For sessions created via `open`, use `close`.
+
+## Default Browser Session
+
+When `-s` is omitted, commands use the default browser session:
+
+```bash
+# These use the same default browser session
+playwright-cli open https://example.com
+playwright-cli snapshot
+playwright-cli close  # Stops default browser
+```
+
+## Browser Session Configuration
+
+Configure a browser session with specific settings when opening:
+
+```bash
+# Open with config file
+playwright-cli open https://example.com --config=.playwright/my-cli.json
+
+# Open with specific browser
+playwright-cli open https://example.com --browser=firefox
+
+# Open in headed mode
+playwright-cli open https://example.com --headed
+
+# Open with persistent profile
+playwright-cli open https://example.com --persistent
+```
+
+## Best Practices
+
+### 1. Name Browser Sessions Semantically
+
+```bash
+# GOOD: Clear purpose
+playwright-cli -s=github-auth open https://github.com
+playwright-cli -s=docs-scrape open https://docs.example.com
+
+# AVOID: Generic names
+playwright-cli -s=s1 open https://github.com
+```
+
+### 2. Always Clean Up
+
+```bash
+# Stop browsers when done
+playwright-cli -s=auth close
+playwright-cli -s=scrape close
+
+# Or stop all at once
+playwright-cli close-all
+
+# If browsers become unresponsive or zombie processes remain
+playwright-cli kill-all
+```
+
+### 3. Delete Stale Browser Data
+
+```bash
+# Remove old browser data to free disk space
+playwright-cli -s=oldsession delete-data
+```

.opencode/skills/playwright-cli/references/storage-state.md

@@ -0,0 +1,275 @@
+# Storage Management
+
+Manage cookies, localStorage, sessionStorage, and browser storage state.
+
+## Storage State
+
+Save and restore complete browser state including cookies and storage.
+
+### Save Storage State
+
+```bash
+# Save to auto-generated filename (storage-state-{timestamp}.json)
+playwright-cli state-save
+
+# Save to specific filename
+playwright-cli state-save my-auth-state.json
+```
+
+### Restore Storage State
+
+```bash
+# Load storage state from file
+playwright-cli state-load my-auth-state.json
+
+# Reload page to apply cookies
+playwright-cli open https://example.com
+```
+
+### Storage State File Format
+
+The saved file contains:
+
+```json
+{
+  "cookies": [
+    {
+      "name": "session_id",
+      "value": "abc123",
+      "domain": "example.com",
+      "path": "/",
+      "expires": 1893456000,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": [
+    {
+      "origin": "https://example.com",
+      "localStorage": [
+        { "name": "theme", "value": "dark" },
+        { "name": "user_id", "value": "12345" }
+      ]
+    }
+  ]
+}
+```
+
+## Cookies
+
+### List All Cookies
+
+```bash
+playwright-cli cookie-list
+```
+
+### Filter Cookies by Domain
+
+```bash
+playwright-cli cookie-list --domain=example.com
+```
+
+### Filter Cookies by Path
+
+```bash
+playwright-cli cookie-list --path=/api
+```
+
+### Get Specific Cookie
+
+```bash
+playwright-cli cookie-get session_id
+```
+
+### Set a Cookie
+
+```bash
+# Basic cookie
+playwright-cli cookie-set session abc123
+
+# Cookie with options
+playwright-cli cookie-set session abc123 --domain=example.com --path=/ --httpOnly --secure --sameSite=Lax
+
+# Cookie with expiration (Unix timestamp)
+playwright-cli cookie-set remember_me token123 --expires=1893456000
+```
+
+### Delete a Cookie
+
+```bash
+playwright-cli cookie-delete session_id
+```
+
+### Clear All Cookies
+
+```bash
+playwright-cli cookie-clear
+```
+
+### Advanced: Multiple Cookies or Custom Options
+
+For complex scenarios like adding multiple cookies at once, use `run-code`:
+
+```bash
+playwright-cli run-code "async page => {
+  await page.context().addCookies([
+    { name: 'session_id', value: 'sess_abc123', domain: 'example.com', path: '/', httpOnly: true },
+    { name: 'preferences', value: JSON.stringify({ theme: 'dark' }), domain: 'example.com', path: '/' }
+  ]);
+}"
+```
+
+## Local Storage
+
+### List All localStorage Items
+
+```bash
+playwright-cli localstorage-list
+```
+
+### Get Single Value
+
+```bash
+playwright-cli localstorage-get token
+```
+
+### Set Value
+
+```bash
+playwright-cli localstorage-set theme dark
+```
+
+### Set JSON Value
+
+```bash
+playwright-cli localstorage-set user_settings '{"theme":"dark","language":"en"}'
+```
+
+### Delete Single Item
+
+```bash
+playwright-cli localstorage-delete token
+```
+
+### Clear All localStorage
+
+```bash
+playwright-cli localstorage-clear
+```
+
+### Advanced: Multiple Operations
+
+For complex scenarios like setting multiple values at once, use `run-code`:
+
+```bash
+playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    localStorage.setItem('token', 'jwt_abc123');
+    localStorage.setItem('user_id', '12345');
+    localStorage.setItem('expires_at', Date.now() + 3600000);
+  });
+}"
+```
+
+## Session Storage
+
+### List All sessionStorage Items
+
+```bash
+playwright-cli sessionstorage-list
+```
+
+### Get Single Value
+
+```bash
+playwright-cli sessionstorage-get form_data
+```
+
+### Set Value
+
+```bash
+playwright-cli sessionstorage-set step 3
+```
+
+### Delete Single Item
+
+```bash
+playwright-cli sessionstorage-delete step
+```
+
+### Clear sessionStorage
+
+```bash
+playwright-cli sessionstorage-clear
+```
+
+## IndexedDB
+
+### List Databases
+
+```bash
+playwright-cli run-code "async page => {
+  return await page.evaluate(async () => {
+    const databases = await indexedDB.databases();
+    return databases;
+  });
+}"
+```
+
+### Delete Database
+
+```bash
+playwright-cli run-code "async page => {
+  await page.evaluate(() => {
+    indexedDB.deleteDatabase('myDatabase');
+  });
+}"
+```
+
+## Common Patterns
+
+### Authentication State Reuse
+
+```bash
+# Step 1: Login and save state
+playwright-cli open https://app.example.com/login
+playwright-cli snapshot
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+
+# Save the authenticated state
+playwright-cli state-save auth.json
+
+# Step 2: Later, restore state and skip login
+playwright-cli state-load auth.json
+playwright-cli open https://app.example.com/dashboard
+# Already logged in!
+```
+
+### Save and Restore Roundtrip
+
+```bash
+# Set up authentication state
+playwright-cli open https://example.com
+playwright-cli eval "() => { document.cookie = 'session=abc123'; localStorage.setItem('user', 'john'); }"
+
+# Save state to file
+playwright-cli state-save my-session.json
+
+# ... later, in a new session ...
+
+# Restore state
+playwright-cli state-load my-session.json
+playwright-cli open https://example.com
+# Cookies and localStorage are restored!
+```
+
+## Security Notes
+
+- Never commit storage state files containing auth tokens
+- Add `*.auth-state.json` to `.gitignore`
+- Delete state files after automation completes
+- Use environment variables for sensitive data
+- By default, sessions run in-memory mode which is safer for sensitive operations

.opencode/skills/playwright-cli/references/test-generation.md

@@ -0,0 +1,433 @@
+# Test generation (plan → generate → heal)
+
+End-to-end workflow for authoring and maintaining Playwright tests with `playwright-cli`. Every `playwright-cli` action emits the equivalent Playwright TypeScript, and that generated code is the raw material for every test. The sections below can be used independently:
+
+- **How generation works** — the core mechanic everything else relies on: actions become TypeScript, plus how to add assertions.
+- **Plan** — explore the app, produce a spec file describing what to test.
+- **Generate** — turn a spec into Playwright test files. Update the spec if it's vague or stale.
+- **Heal** — diagnose failing tests, fix the code, reconcile the spec with reality.
+
+Plan / generate / heal lean on the same mechanic: run `npx playwright test --debug=cli` in the background, then `playwright-cli attach tw-XXXX` to drive the paused page interactively. See [playwright-tests.md](playwright-tests.md) for the debug/attach mechanics.
+
+---
+
+## 0. How generation works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code. This code appears in the output and can be copied directly into your test files.
+
+```bash
+# Start a session
+playwright-cli open https://example.com/login
+
+# Take a snapshot to see elements
+playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+### Building a test file
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('login flow', async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+### Use semantic locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator('#submit-btn').click();
+```
+
+### Explore before recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+playwright-cli open https://example.com
+playwright-cli snapshot
+# Review the element structure
+playwright-cli click e5
+```
+
+### Add assertions manually
+
+Generated code captures actions but not assertions. Add expectations in your test using one of the recommended matchers:
+
+- `toBeVisible()` — element is rendered and visible
+- `toHaveText(text)` — element text content matches
+- `toHaveValue(value) / toBeEmpty()` — input/select value matches
+- `toBeChecked() / toBeUnchecked()` — checkbox state matches
+- `toMatchAriaSnapshot(snapshot)` — page (or locator) matches a partial accessibility snapshot
+
+Use `playwright-cli generate-locator <target>` to produce the locator expression for the assertion, and the snapshot/eval commands to capture the expected value.
+
+When asserting text content, make sure that generated locator does not contain text from the element itself. `getByTestId()` or `getByLabel()` usually work well with asserting text. When locator is text-based, prefer `toBeVisible()` instead.
+
+Snapshot to be matched does not have to contain all the information - only capture what's necessary for the assertion. You can use regular expressions for unstable values.
+
+```bash
+# Get a stable locator for an element ref to use in the assertion
+playwright-cli --raw generate-locator e5
+# getByRole('button', { name: 'Submit' })
+
+# Capture expected text content for toHaveText
+playwright-cli --raw eval "el => el.textContent" e5
+
+# Capture expected input value for toHaveValue/toBeEmpty
+playwright-cli --raw eval "el => el.value" e5
+
+# Capture expected aria snapshot for toMatchAriaSnapshot/toBeChecked
+# (whole page, or use a ref to scope to a region)
+playwright-cli --raw snapshot
+playwright-cli --raw snapshot e5
+```
+
+```typescript
+// Generated action
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Manual assertions using the outputs above:
+await expect(page.getByRole('alert', { name: 'Success' })).toBeVisible();
+await expect(page.getByTestId('main-header')).toHaveText('Welcome, user');
+await expect(page.getByRole('textbox', { name: 'Email' })).toHaveValue('user@example.com');
+await expect(page.getByRole('checkbox', { name: 'Enable notifications' })).toBeChecked();
+
+// toMatchAriaSnapshot on the whole page, finds a matching region
+await expect(page).toMatchAriaSnapshot(`
+  - heading "Welcome, user"
+  - link /\\d+ new messages?/
+  - button "Sign out"
+`);
+
+// toMatchAriaSnapshot scoped to a region
+await expect(page.getByRole('navigation')).toMatchAriaSnapshot(`
+  - link "Home"
+  - link /\\d+ new messages?/
+  - link "Profile"
+`);
+```
+
+---
+
+## 1. Planning
+
+Goal: produce a spec file (e.g. `specs/<feature>.plan.md`) that enumerates the scenarios to test. **Always** write the spec to a file.
+
+### 1.1 Prerequisite: workspace
+
+Check the workspace has Playwright installed before anything else:
+
+```bash
+# Either of these confirms a workspace:
+test -f playwright.config.ts || test -f playwright.config.js
+npx --no-install playwright --version
+```
+
+If there is no Playwright install, bootstrap one and let the user pick the defaults:
+
+```bash
+npm init playwright@latest
+```
+
+### 1.2 Prerequisite: seed test
+
+A **seed test** is a minimal test that lands the page in the state every scenario starts from: navigation to the app, any required login, feature flags, etc. Scenarios assume a fresh start *after* the seed. `--debug=cli` pauses *inside* this test, so the seed is where every planning and generation session begins.
+
+Minimum viable seed:
+
+```ts
+// tests/seed.spec.ts
+import { test } from '@playwright/test';
+
+test('seed', async ({ page }) => {
+  await page.goto('https://example.com/');
+});
+```
+
+Preferred — push navigation into a fixture so scenario tests reuse it:
+
+```ts
+// tests/fixtures.ts
+import { test as baseTest } from '@playwright/test';
+export { expect } from '@playwright/test';
+
+export const test = baseTest.extend({
+  page: async ({ page }, use) => {
+    await page.goto('https://example.com/');
+    await use(page);
+  },
+});
+```
+
+```ts
+// tests/seed.spec.ts
+import { test } from './fixtures';
+
+test('seed', async ({ page }) => {
+  // Fixture already navigates. This empty body tells agents where to start.
+});
+```
+
+If no seed exists, create one that at least navigates to the app.
+
+### 1.3 Explore the app
+
+Launch the app via the seed in the background and attach:
+
+```bash
+PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/seed.spec.ts --debug=cli
+# wait for "Debugging Instructions" and the session name tw-XXXX
+playwright-cli attach tw-XXXX
+```
+
+Resume so the seed runs, then probe the app:
+
+```bash
+playwright-cli resume                   # resume so that seed test runs fully
+playwright-cli snapshot                 # inventory of interactive elements
+playwright-cli click e5                 # follow a flow
+playwright-cli eval "location.href"     # read URL / state
+playwright-cli show --annotate          # ask the user to point at something
+```
+
+Map out:
+
+- Interactive surfaces (forms, buttons, lists, filters, modals).
+- Primary user journeys end-to-end.
+- Edge cases: empty states, validation errors, very long input, boundary values.
+- Persistence: reload, local/session storage, URL fragments.
+- Navigation: which controls change the URL, back/forward behaviour.
+
+**Important**: Do not just open the app url with playwright-cli, always go through the test to capture any custom setup done there.
+**Important**: Stop the background test when done exploring.
+
+### 1.4 Write the spec file
+
+Save under `specs/<feature>.plan.md`. Use this structure:
+
+```markdown
+# <Feature> Test Plan
+
+## Application Overview
+
+<One paragraph describing what the feature does and why it matters.>
+
+## Test Scenarios
+
+### 1. <Group Name>
+
+**Seed:** `tests/seed.spec.ts`
+
+#### 1.1. <kebab-case-scenario-name>
+
+**File:** `tests/<group>/<kebab-case-scenario-name>.spec.ts`
+
+**Steps:**
+  1. <Concrete user step>
+    - expect: <observable outcome>
+    - expect: <another observable outcome>
+  2. <Next step>
+    - expect: <outcome>
+
+#### 1.2. <next-scenario>
+...
+
+### 2. <Next Group>
+
+**Seed:** `tests/seed.spec.ts`
+...
+```
+
+Guidelines:
+
+- Each scenario is independent and starts from the seed's fresh state — never chain scenarios.
+- Scenario names are kebab-case and match the test file name (`should-add-single-todo` → `should-add-single-todo.spec.ts`).
+- Cover happy path, edge cases, validation, negative flows, persistence.
+- Write steps at the user level ("Type 'Buy milk' into the input"), not the API level ("call `fill`").
+- Put observable outcomes in `- expect:` bullets; each becomes an assertion during generation.
+
+---
+
+## 2. Generate
+
+Goal: take a spec file and produce Playwright test files. Optionally update the spec if it has drifted.
+
+### 2.1 Inputs
+
+- **Spec file**, e.g. `specs/basic-operations.plan.md`.
+- **Target**: either a single scenario (e.g. `1.2`), a whole group (`1`), or all.
+- **Seed file**, read from the `**Seed:**` line of the scenario's group.
+
+### 2.2 Generate one scenario
+
+For each target scenario, in sequence (never in parallel — scenarios share the seed session):
+
+```bash
+PLAYWRIGHT_HTML_OPEN=never npx playwright test <seed-file> --debug=cli   # background
+playwright-cli attach tw-XXXX
+# resume
+```
+
+**Do not** just open the app url with playwright-cli, always go through the test to capture any custom setup done there.
+
+Walk the scenario's `Steps:` one by one with `playwright-cli`, treating the spec as the plan and the live app as the source of truth. If a step is vague ("click the button" — which button?), references an element that no longer exists, or contradicts the app's actual behaviour, use your judgement: update the spec to match what the app really does, then keep going. Editing the spec mid-generation is expected.
+
+Every action prints the equivalent Playwright TypeScript (see [How generation works](#0-how-generation-works)):
+
+```bash
+playwright-cli snapshot                         # find refs
+playwright-cli fill e3 "John Doe"               # -> page.getByRole('textbox', {...}).fill(...)
+playwright-cli press Enter
+playwright-cli click e7
+```
+
+For each `- expect:` bullet, add an explicit assertion. See [How generation works](#0-how-generation-works) for details.
+
+Collect the generated code and write the test file at the path given in the spec:
+
+```ts
+// spec: specs/basic-operations.plan.md
+// seed: tests/seed.spec.ts
+import { test, expect } from './fixtures';   // or '@playwright/test' if no fixtures file
+
+test.describe('Signing in and out', () => {
+  test('should sign in', async ({ page }) => {
+    // 1. Navigate to the application
+    // (handled by the seed fixture)
+
+    // 2. Type 'John Doe' into the username field
+    await page.getByRole('textbox', { name: 'username' }).fill('John Doe');
+
+    // 3. Type password
+    await page.getByRole('textbox', { name: 'password' }).fill('TestPassword');
+
+    // 4. Press Enter to submit
+    await page.getByRole('textbox', { name: 'password' }).press('Enter');
+
+    await expect(page.getByRole('heading')).toContainText('Welcome, John Doe!');
+  });
+});
+```
+
+Rules:
+
+- **One test per file.** File path, describe name, and test name come verbatim from the spec (minus the ordinal).
+- Prefix each numbered step with a `// N. <step text>` comment before its actions.
+- Use the describe group name verbatim from the spec (no `1.` ordinal).
+- Import from `./fixtures` if the project has one; otherwise `@playwright/test`.
+- **Important**: close the CLI session and stop the background test before moving to the next scenario.
+
+### 2.3 Generate multiple scenarios
+
+Loop 2.2 over the targeted scenarios one at a time, restarting the seed between each so every test starts from a clean page. This is safe to parallelise due to unique generated session names - just make sure each test run is stopped.
+
+### 2.4 Run generated tests
+
+After generation, run the new tests once:
+
+```bash
+PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts
+```
+
+Any failure goes to Section 3.
+
+---
+
+## 3. Heal
+
+Goal: fix failing tests, and update the spec if the app's intended behaviour changed.
+
+### 3.1 Find failing tests
+
+```bash
+PLAYWRIGHT_HTML_OPEN=never npx playwright test
+```
+
+Record the list of failing `<file>:<line>` entries and process them one at a time. Do not attempt parallel fixes — shared state and the single CLI session make that fragile.
+
+### 3.2 Debug one failure
+
+Run the single failing test in debug mode in the background, then attach:
+
+```bash
+PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts:<line> --debug=cli
+# wait for "Debugging Instructions" and the tw-XXXX session name
+playwright-cli attach tw-XXXX
+```
+
+The test is paused at the start. Step forward or run to until just before the failing action or assertion, then diagnose:
+
+```bash
+playwright-cli snapshot                # did the element change / move / rename?
+playwright-cli console                 # app-side errors?
+playwright-cli requests                # failed request? wrong payload?
+playwright-cli show --annotate         # ask the user to point somewhere
+```
+
+Common causes: selector drift, new wrapper element, label/ARIA rename, timing (transition, async load), assertion text updated in the app, test data leaking between runs.
+
+Rehearse the corrected interaction with `playwright-cli` — the generated code in the output is what you paste back into the test.
+
+### 3.3 Apply the fix
+
+Edit the test file: update the locator, assertion, step order, or inputs to match the corrected behaviour. Stop the background debug run. Rerun the single test to confirm green.
+
+Never skip hooks or add sleeps as a fix. Never use `networkidle`.
+
+### 3.4 Reconcile with the spec
+
+Open the spec referenced by the `// spec:` header in the test file and locate the scenario that matches the test.
+
+- **Fix was purely technical** (locator drift, better assertion shape) and the spec's user-level behaviour still matches the app → leave the spec alone.
+- **Fix changed user-visible steps, inputs, order, or expected outcomes** that the spec describes → update the spec to match reality. Keep the scenario id and file path stable; only the step / expect lines change.
+- **Unclear whether the app change is intentional** (spec is stale) **or a regression** (test was right, app is wrong) → **stop and ask the user**. Provide:
+  - the scenario id (e.g. `2.3`),
+  - the spec lines that no longer match,
+  - the observed app behaviour (quote a snapshot excerpt or a concrete outcome).
+
+Only after the user answers, either update the spec (intentional change) or file/flag the test as covering a bug (regression).
+
+### 3.5 Iteration and giving up
+
+- Fix failures one at a time; rerun after each.
+- If after thorough investigation you are confident the test is correct but the app is wrong *and* the user has confirmed it's a bug: mark the test `test.fixme(...)` with a comment pointing at the user's decision or issue link. Never silently skip.
+
+---
+
+## Cross-references
+
+| For... | See |
+|---|---|
+| `--debug=cli` / attach mechanics | [playwright-tests.md](playwright-tests.md) |
+| Mocking requests during exploration/generation | [request-mocking.md](request-mocking.md) |
+| Managing the CLI browser session | [session-management.md](session-management.md) |

.opencode/skills/playwright-cli/references/tracing.md

@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category | Details |
+|----------|---------|
+| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM** | Full DOM snapshot before/after each action |
+| **Screenshots** | Visual state at each step |
+| **Network** | All requests, responses, headers, bodies, timing |
+| **Console** | All console.log, warn, error messages |
+| **Timing** | Precise timing for each operation |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature | Trace | Video | Screenshot |
+|---------|-------|-------|------------|
+| **Format** | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection** | Yes | No | No |
+| **Network details** | Yes | No | No |
+| **Step-by-step replay** | Yes | Continuous | Single frame |
+| **File size** | Medium | Large | Small |
+| **Best for** | Debugging | Demos | Quick capture |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly

.opencode/skills/playwright-cli/references/video-recording.md

@@ -0,0 +1,143 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Open browser first
+playwright-cli open
+
+# Start recording
+playwright-cli video-start demo.webm
+
+# Add a chapter marker for section transitions
+playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
+
+# Navigate and perform actions
+playwright-cli goto https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+
+# Add another chapter
+playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-start recordings/login-flow-2024-01-15.webm
+playwright-cli video-start recordings/checkout-test-run-42.webm
+```
+
+### 2. Record entire hero scripts.
+
+When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
+It allows inserting appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
+
+1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
+2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
+3) Use playwright-cli run-code --filename your-script.js
+
+**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
+
+```js
+async page => {
+  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
+  await page.goto('https://demo.playwright.dev/todomvc');
+
+  // Show a chapter card — blurs the page and shows a dialog.
+  // Blocks until duration expires, then auto-removes.
+  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
+  // overlay via await page.screencast.showOverlay().
+  await page.screencast.showChapter('Adding Todo Items', {
+    description: 'We will add several items to the todo list.',
+    duration: 2000,
+  });
+
+  // Perform action
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1000);
+
+  // Show next chapter
+  await page.screencast.showChapter('Verifying Results', {
+    description: 'Checking the item appeared in the list.',
+    duration: 2000,
+  });
+
+  // Add a sticky annotation that stays while you perform actions.
+  // Overlays are pointer-events: none, so they won't block clicks.
+  const annotation = await page.screencast.showOverlay(`
+    <div style="position: absolute; top: 8px; right: 8px;
+      padding: 6px 12px; background: rgba(0,0,0,0.7);
+      border-radius: 8px; font-size: 13px; color: white;">
+      ✓ Item added successfully
+    </div>
+  `);
+
+  // Perform more actions while the annotation is visible
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1500);
+
+  // Remove the annotation when done
+  await annotation.dispose();
+
+  // You can also highlight relevant locators and provide contextual annotations.
+  const bounds = await page.getByText('Walk the dog').boundingBox();
+  await page.screencast.showOverlay(`
+    <div style="position: absolute;
+      top: ${bounds.y}px;
+      left: ${bounds.x}px;
+      width: ${bounds.width}px;
+      height: ${bounds.height}px;
+      border: 1px solid red;">
+    </div>
+    <div style="position: absolute;
+      top: ${bounds.y + bounds.height + 5}px;
+      left: ${bounds.x + bounds.width / 2}px;
+      transform: translateX(-50%);
+      padding: 6px;
+      background: #808080;
+      border-radius: 10px;
+      font-size: 14px;
+      color: white;">Check it out, it is right above this text
+    </div>
+  `, { duration: 2000 });
+
+  await page.screencast.stop();
+}
+```
+
+Embrace creativity, overlays are powerful.
+
+### Overlay API Summary
+
+| Method | Use Case |
+|--------|----------|
+| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
+| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
+| `disposable.dispose()` | Remove a sticky overlay added without duration |
+| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
+
+## Tracing vs Video
+
+| Feature | Video | Tracing |
+|---------|-------|---------|
+| Output | WebM file | Trace file (viewable in Trace Viewer) |
+| Shows | Visual recording | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis |
+| Size | Larger | Smaller |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space

.vscode/launch.json

@@ -7,15 +7,7 @@
       "request": "launch",
       "module": "flask",
       "python": "${command:python.interpreterPath}",
-      "env": {
-        "FLASK_APP": "backend/main.py",
-        "FLASK_DEBUG": "1",
-        "SECRET_KEY": "dev-secret-key-change-in-production",
-        "REFRESH_TOKEN_EXPIRY_DAYS": "90",
-        "DIGEST_TOKEN_SECRET": "dev-digest-token",
-        "VAPID_PUBLIC_KEY": "BNKkHdq45uLigohSG7c1TwlAo7ETncoRVLQK02LxHgu2P1DgSJD9njRMfbbzUsaTQGllvLBz7An1WiWsNYQhvKE",
-        "VAPID_PRIVATE_KEY": "jNiZJT0UO4H861KmnCt874Fg6p5jDAyYKS4V2MZf8bQ"
-      },
+      "envFile": "${workspaceFolder}/backend/.env",
       "args": [
         "run",
         "--host=0.0.0.0",

AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md
+
+Family chore/reward manager. Flask + TinyDB backend (`backend/`), Vue 3 + TypeScript frontend (`frontend/`). Real-time updates over SSE.
+
+## Commands
+
+### Backend (run from `backend/`)
+- Activate venv: `source .venv/bin/activate`
+- Dev server: `python -m flask run --host=0.0.0.0 --port=5000` (entry: `main.py`)
+- Required env vars: `SECRET_KEY`, `REFRESH_TOKEN_EXPIRY_DAYS`, `DIGEST_TOKEN_SECRET`, `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY` — Flask raises `RuntimeError` on boot if any are missing
+- Optional persistence switch: `USE_MONGODB` (`true` | `false`). Defaults to `true`; set `MONGO_URI` (and optionally `MONGO_DB_NAME`). Set to `false` to use TinyDB instead.
+- Optional: `DB_ENV` / `DATA_ENV` (`prod` | `test` | `e2e`) — picks `data/` vs `test_data/` dir (see `config/paths.py`). For MongoDB these also select the default database name (`chore_db`, `chore_db_test`, `chore_db_e2e`) unless `MONGO_DB_NAME` is set.
+- Tests: `pytest tests/` — `conftest.py` forces `DB_ENV=test`, `USE_MONGODB=true`, `MONGO_URI=mongomock`, and sets dummy secrets. Single test: `pytest tests/test_routine_api.py::test_name`
+- Python imports assume `backend/` is on `sys.path` (set by `conftest.py` / `flask run` cwd). Run pytest from `backend/`.
+- Create admin user: `python scripts/create_admin.py` (admin role cannot be set via signup)
+
+### Frontend (run from `frontend/`)
+- Dev: `npm run dev` (Vite, https://localhost:5173)
+- Lint: `npm run lint`
+- Type-check: `npm run type-check`
+- Unit tests: `npm run test:unit` (Vitest). Single: `npx vitest run path/to/file.spec.ts`
+- E2E: `npx playwright test` — config auto-starts both `npm run dev` and the Flask backend with `DB_ENV=e2e DATA_ENV=e2e USE_MONGODB=true MONGO_URI=mongomock`. Tests live in `e2e/`. `frontend/.env.test` contains the example MongoDB config.
+- E2E buckets are Playwright projects (see `playwright.config.ts`) targeting directories under `e2e/mode_parent/`
+
+## Architecture
+
+### API routing — the `/api` prefix
+- Frontend nginx (and Vite dev proxy) strips `/api` before forwarding. **Backend routes must NOT include `/api`.** Backend defines `@app.route('/user')`, frontend calls `/api/user`.
+- `auth_api` is the only blueprint registered with a prefix: `url_prefix='/auth'` in `main.py:67`.
+- API errors return `{ error, code }` (codes in `backend/api/error_codes.py`). Frontend extracts them via `parseErrorResponse(res)` in `src/common/api.ts`.
+
+### Models — strict 1:1 parity
+- Python `@dataclass`es in `backend/models/`. TypeScript interfaces in `frontend/src/common/models.ts`. Any model change requires updating both.
+- Persistence is MongoDB by default (`USE_MONGODB=true`), or TinyDB when `USE_MONGODB=false`. Both are accessed through the `LockedTable` / `MongoLockedTable` wrappers in `backend/db/db.py`. Operate on model instances with `from_dict()` / `to_dict()` — never raw dicts.
+- MongoDB client initialization is lazy (`backend/db/mongo_client.py`). `backend/gunicorn.conf.py` provides the `post_fork` hook required for multi-worker Gunicorn deployments; `backend/Dockerfile` loads it with `-c gunicorn.conf.py`.
+- Migration script: `cd backend && python -m scripts/migrate_to_mongodb [--dry-run]`. It reads TinyDB JSON files and writes them to MongoDB idempotently, backing up the originals to `<db_dir>/backups/<timestamp>/`.
+
+### SSE event bus — mandatory for every mutation
+- Every backend mutation (add/edit/delete/trigger) **must** call `send_event_for_current_user` from `api/utils.py`. Event types in `backend/events/types/` are mirrored in `frontend/src/common/backendEvents.ts`.
+- Frontend: register listeners in `onMounted`, clean up in `onUnmounted`. SSE endpoint is `/events`.
+
+### Background schedulers (started in `main.py` at boot)
+- `start_deletion_scheduler` — runs hourly, deletes accounts marked for deletion after threshold
+- `start_digest_scheduler` — email digests
+- `start_state_expiry_scheduler` — expires stale state
+- `start_chore_expiry_notification_scheduler` — chore expiry notifications
+
+## Frontend conventions
+- SFC file order: `<template>` → `<script>` → `<style scoped>`. TypeScript only in `<script>`. All styles must be `scoped`.
+- Colors/spacing: use only `:root` CSS variables from `colors.css`. No hardcoded hex/px for themed properties.
+- Layout shells: `ParentLayout` for admin/management, `ChildLayout` for child dashboard/focus.
+- Images: models carry `image_id`; frontend resolves to `image_url` for rendering.
+
+## Testing gotchas
+- E2E tests use pre-authenticated sessions via `storageState` in `playwright.config.ts` — do **not** navigate to `/auth/login`. Import `E2E_EMAIL` / `E2E_PASSWORD` from `e2e/e2e-constants.ts`.
+- E2E buckets that mutate shared state (default tasks, delete-account, create-child) use isolated users. Preserve this pattern when adding new buckets.
+- Backend tests: `conftest.py` sets `DB_ENV=test` + dummy secrets. Test DB lands in `test_data/db/`, never touches production `data/`.
+
+## Feature specs
+Specs live in `.github/specs/`. If a spec has a checklist, all items must be marked done before the feature is complete.

CLAUDE.md

@@ -0,0 +1,67 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+Family chore/reward manager. Flask + TinyDB backend (`backend/`), Vue 3 + TypeScript frontend (`frontend/`). Real-time updates flow over Server-Sent Events.
+
+## Commands
+
+### Backend (run from `backend/`)
+- Activate venv first: `source .venv/bin/activate` (mac/linux) — Python runs from `backend/.venv/`.
+- Dev server: `python -m flask run --host=0.0.0.0 --port=5000` (entry: `backend/main.py`).
+- Required env vars at startup: `SECRET_KEY`, `REFRESH_TOKEN_EXPIRY_DAYS`, `DIGEST_TOKEN_SECRET`, `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY` — Flask raises `RuntimeError` on boot if any are missing.
+- Optional: `DB_ENV` / `DATA_ENV` (`prod` | `test` | `e2e`) — picks `data/` vs `test_data/` directory (see `backend/config/paths.py`).
+- Tests: `pytest tests/` — `tests/conftest.py` forces `DB_ENV=test` and sets dummy secrets. Single test: `pytest tests/test_routine_api.py::test_name`.
+- Create an admin user (cannot be done via signup): `python scripts/create_admin.py`.
+
+### Frontend (run from `frontend/`)
+- Dev: `npm run dev` (Vite, https://localhost:5173).
+- Build: `npm run build`. Type-check: `npm run type-check`. Lint: `npm run lint`.
+- Unit/component tests: `npm run test:unit` (Vitest). Single test: `npx vitest run path/to/file.spec.ts`.
+- E2E: `npx playwright test` from `frontend/`. Config at `playwright.config.ts` auto-starts both `npm run dev` and the Flask backend with `DB_ENV=e2e DATA_ENV=e2e`, so test data lands in `backend/test_data/` and never touches production. The `globalSetup` seeds the DB and logs in; tests receive a pre-authenticated session via `storageState` — do **not** navigate to `/auth/login`. Import `E2E_EMAIL` / `E2E_PASSWORD` from `e2e/e2e-constants.ts` rather than hardcoding.
+- E2E suite is split into Playwright "projects" in `playwright.config.ts` (`chromium-routines`, `chromium-task-assignment`, …) — each bucket targets a directory under `e2e/mode_parent/` and some use isolated users to avoid cross-bucket interference. Run a single bucket: `npx playwright test --project=chromium-routines`.
+
+## Architecture
+
+### API surface and nginx proxy
+- Each entity has its own Flask blueprint in `backend/api/` (`child_api.py`, `chore_api.py`, `routine_api.py`, …). Registered in `backend/main.py`.
+- The frontend nginx (and Vite dev proxy) strips `/api` before forwarding. **Backend routes must NOT include `/api`** — backend defines `@app.route('/user')`, frontend calls `/api/user`.
+- The `auth_api` blueprint is the only one mounted under a prefix (`/auth`).
+- API errors return `{ error, code }`; codes live in `backend/api/error_codes.py`. Frontend extracts them via `parseErrorResponse(res)` in `frontend/src/common/api.ts`.
+
+### Models — keep 1:1 parity
+- Python `@dataclass`es live in `backend/models/`. TypeScript interfaces live in `frontend/src/common/models.ts`. Any model change requires updating **both**.
+- Persistence is TinyDB (JSON files under `data/db/` or `test_data/db/`). All DB access goes through the thread-safe `LockedTable` wrapper in `backend/db/db.py`. Always operate on model instances using `from_dict()` / `to_dict()` — never raw dicts.
+
+### SSE event bus (mandatory for every mutation)
+- Every backend mutation (add/edit/delete/trigger) **must** call `send_event_for_current_user` (from `api/utils.py`). Event types live in `backend/events/types/` and `frontend/src/common/backendEvents.ts` (mirrored).
+- Frontend state is event-driven: register listeners in `onMounted`, clean up in `onUnmounted`. See `components/BackendEventsListener.vue` and `src/common/backendEvents.ts`.
+- The SSE endpoint is `/events`; per-user queues live in `backend/events/sse.py`.
+
+### Background schedulers
+Started in `backend/main.py` at boot:
+- `start_deletion_scheduler` — runs hourly, deletes accounts that were marked-for-deletion at least `ACCOUNT_DELETION_THRESHOLD_HOURS` ago (default 720, min 24, max 720). Cleans pending rewards, children, tasks, rewards, images, then the user. Logs to `logs/account_deletion.log`.
+- `start_digest_scheduler` — email digests.
+- `start_state_expiry_scheduler` — expires stale state.
+- `start_chore_expiry_notification_scheduler` — chore expiry notifications.
+
+### Auth & security
+- JWT in HttpOnly + Secure + SameSite=Strict cookies. Verification tokens expire in 4 hours; password-reset tokens in 10 minutes.
+- Admin role is **never** assignable via signup — use `backend/scripts/create_admin.py`. Admin endpoints under `/admin/*` enforce role check.
+
+### Frontend conventions
+- Vue SFC file order: `<template>` → `<script>` → `<style scoped>`. TypeScript only inside `<script>`. **All styles must be `scoped`.**
+- Use **only** `:root` CSS variables from `colors.css` for colors/spacing/tokens (e.g. `--btn-primary`, `--list-item-bg-good`). No hardcoded hex/px values for themed properties.
+- Layout shells: `ParentLayout` for admin/management views, `ChildLayout` for child dashboard/focus views.
+- Images: models carry `image_id`; frontend resolves to `image_url` for rendering.
+
+### Specs
+Feature specs live in `.github/specs/`. If a spec has a checklist, all items must be marked done before the feature is considered complete.
+
+## Gotchas
+
+- Backend Python imports assume `backend/` is on `sys.path` (added by `conftest.py` for tests, by `flask run` cwd in dev). Run pytest from `backend/`.
+- Don't replace code with comments; mirror changes across backend + frontend so model/event parity holds.
+- E2E tests share a single seeded user by default — buckets that mutate shared state (default tasks, delete-account, create-child) deliberately use isolated users; preserve that pattern when adding new buckets.

README.md

@@ -4,7 +4,7 @@ A family-friendly application for managing chores, tasks, and rewards for childr
 
 ## 🏗️ Architecture
 
-- **Backend**: Flask (Python) with TinyDB for data persistence
+- **Backend**: Flask (Python) with TinyDB or MongoDB for data persistence
 - **Frontend**: Vue 3 (TypeScript) with real-time SSE updates
 - **Deployment**: Docker with nginx reverse proxy
 
@@ -38,6 +38,37 @@ npm run dev
 | `ACCOUNT_DELETION_THRESHOLD_HOURS` | Hours to wait before deleting marked accounts | 720 (30 days) |
 | `DB_ENV`                           | Database environment (`prod` or `test`)       | `prod`        |
 | `DATA_ENV`                         | Data directory environment (`prod` or `test`) | `prod`        |
+| `USE_MONGODB`                      | Use MongoDB (`true`/`false`) | `true`        |
+| `MONGO_URI`                        | MongoDB connection URI (required when `USE_MONGODB=true`) | —             |
+| `MONGO_DB_NAME`                    | MongoDB database name (optional)              | Parsed from `MONGO_URI`, or `chore_db`/`chore_db_test`/`chore_db_e2e` based on `DB_ENV` |
+
+### Database Backend
+
+The application supports two persistence backends:
+
+- **MongoDB** (default): Set `MONGO_URI` (and optionally `MONGO_DB_NAME`). This is the recommended backend for production and managed hosting (e.g., MongoDB Atlas).
+- **TinyDB**: JSON-file storage in `backend/data/db/` (or `backend/test_data/db/` for `test`/`e2e`). Opt in by setting `USE_MONGODB=false`.
+
+#### Migrating from TinyDB to MongoDB
+
+```bash
+cd backend
+# Dry run to preview what will be migrated
+python -m scripts.migrate_to_mongodb --dry-run
+
+# Run the migration (backs up TinyDB files first)
+python -m scripts.migrate_to_mongodb
+```
+
+The migration script reads the existing TinyDB JSON files and inserts each record into the matching MongoDB collection, skipping records that already exist. Original TinyDB files are backed up to `backend/data/db/backups/<timestamp>/`.
+
+#### Rolling Back to TinyDB
+
+Set `USE_MONGODB=false`. The original JSON files remain in place.
+
+#### Gunicorn / Docker
+
+When running multiple Gunicorn workers, each worker must create its own MongoDB client after forking. This is handled automatically by `backend/gunicorn.conf.py`, which is loaded by `backend/Dockerfile` via `-c gunicorn.conf.py`.
 
 ### Account Deletion Scheduler
 
@@ -145,7 +176,7 @@ npm run test
 ├── backend/
 │   ├── api/              # REST API endpoints
 │   ├── config/           # Configuration files
-│   ├── db/               # TinyDB setup
+│   ├── db/               # TinyDB / MongoDB persistence layer
 │   ├── events/           # SSE event system
 │   ├── models/           # Data models
 │   ├── tests/            # Backend tests

backend/Dockerfile

@@ -15,4 +15,4 @@ ENV PYTHONIOENCODING=utf-8
 VOLUME ["/app/data"]
 
 # Use Gunicorn instead of python main.py
-CMD ["gunicorn", "--bind", "0.0.0.0:5000", "-k", "gevent", "--workers", "1", "--timeout", "120", "--access-logfile", "-", "--error-logfile", "-", "--log-level", "info", "main:app"]
+CMD ["gunicorn", "--bind", "0.0.0.0:5000", "-k", "gevent", "--workers", "1", "--timeout", "120", "--access-logfile", "-", "--error-logfile", "-", "--log-level", "info", "-c", "gunicorn.conf.py", "main:app"]

backend/api/auth_api.py

@@ -29,6 +29,8 @@ from db.db import (
     users_db, refresh_tokens_db, child_db, task_db, reward_db, image_db,
     pending_reward_db, pending_confirmations_db, tracking_events_db,
     child_overrides_db, chore_schedules_db, task_extensions_db,
+    routine_db, routine_items_db, routine_schedules_db, routine_extensions_db,
+    push_subscriptions_db, digest_action_tokens_db,
 )
 from db.default import initializeImages, createDefaultTasks, createDefaultRewards
 from api.utils import normalize_email
@@ -43,6 +45,12 @@ try:
     ACCESS_TOKEN_EXPIRY_MINUTES = int(os.environ.get('ACCESS_TOKEN_EXPIRY_MINUTES', '15'))
 except ValueError:
     ACCESS_TOKEN_EXPIRY_MINUTES = 15
+try:
+    REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS = int(
+        os.environ.get('REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS', '30')
+    )
+except ValueError:
+    REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS = 30
 E2E_TEST_EMAIL = 'e2e@test.com'
 E2E_TEST_PASSWORD = 'E2eTestPass1!'
 E2E_TEST_PIN = '1234'
@@ -52,6 +60,9 @@ E2E_DELETE_PIN = '5678'
 E2E_CC_EMAIL = 'e2e-cc@test.com'
 E2E_CC_PASSWORD = 'E2eCCPass1!'
 E2E_CC_PIN = '3456'
+E2E_TUTORIAL_EMAIL = 'e2e-tutorial@test.com'
+E2E_TUTORIAL_PASSWORD = 'E2eTutorialPass1!'
+E2E_TUTORIAL_PIN = '7890'
 
 
 def send_verification_email(to_email, token):
@@ -409,18 +420,21 @@ def refresh():
 
     token_record = RefreshToken.from_dict(token_dict)
 
-    # THEFT DETECTION: token was already used (rotated out) but replayed
-    if token_record.is_used:
-        logger.warning(
-            'Refresh token reuse detected! user_id=%s, family=%s, ip=%s — killing all sessions',
-            token_record.user_id, token_record.token_family, request.remote_addr,
-        )
-        # Nuke ALL refresh tokens for this user
-        refresh_tokens_db.remove(TokenQuery.user_id == token_record.user_id)
-        resp = jsonify({'error': 'Token reuse detected, all sessions invalidated', 'code': REFRESH_TOKEN_REUSE})
+    # Look up the user early (needed for both legitimate rotation and grace-period handling)
+    user_dict = users_db.get(UserQuery.id == token_record.user_id)
+    user = User.from_dict(user_dict) if user_dict else None
+    if not user:
+        refresh_tokens_db.remove(TokenQuery.id == token_record.id)
+        resp = jsonify({'error': 'User not found', 'code': USER_NOT_FOUND})
         _clear_auth_cookies(resp)
         return resp, 401
 
+    if user.marked_for_deletion:
+        refresh_tokens_db.remove(TokenQuery.user_id == user.id)
+        resp = jsonify({'error': 'Account marked for deletion', 'code': ACCOUNT_MARKED_FOR_DELETION})
+        _clear_auth_cookies(resp)
+        return resp, 403
+
     # Check expiry
     try:
         exp = datetime.fromisoformat(token_record.expires_at)
@@ -437,23 +451,59 @@ def refresh():
         _clear_auth_cookies(resp)
         return resp, 401
 
-    # Look up the user
-    user_dict = users_db.get(UserQuery.id == token_record.user_id)
-    user = User.from_dict(user_dict) if user_dict else None
-    if not user:
-        refresh_tokens_db.remove(TokenQuery.id == token_record.id)
-        resp = jsonify({'error': 'User not found', 'code': USER_NOT_FOUND})
+    # THEFT DETECTION: token was already used (rotated out) but replayed
+    if token_record.is_used:
+        # Grace period: tolerate a very recent rotation to avoid false positives
+        # from legitimate concurrent refresh requests (race conditions).
+        grace_period = current_app.config.get(
+            'REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS', REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS
+        )
+        rotated_at = token_record.rotated_at
+        is_race_condition = False
+        if rotated_at:
+            try:
+                rotated_dt = datetime.fromisoformat(rotated_at)
+                if rotated_dt.tzinfo is None:
+                    rotated_dt = rotated_dt.replace(tzinfo=timezone.utc)
+                if (datetime.now(timezone.utc) - rotated_dt).total_seconds() <= grace_period:
+                    is_race_condition = True
+            except ValueError:
+                pass
+
+        if is_race_condition:
+            logger.info(
+                'Refresh token replay within grace period treated as race condition. user_id=%s, family=%s, ip=%s',
+                token_record.user_id, token_record.token_family, request.remote_addr,
+            )
+            raw_new_refresh, _ = _create_refresh_token(user.id, token_family=token_record.token_family)
+            access_token = _create_access_token(user)
+            resp = jsonify({
+                'email': user.email,
+                'id': user.id,
+                'first_name': user.first_name,
+                'last_name': user.last_name,
+                'verified': user.verified,
+            })
+            _set_auth_cookies(resp, access_token, raw_new_refresh)
+            return resp, 200
+
+        logger.warning(
+            'Refresh token reuse detected! user_id=%s, family=%s, ip=%s — killing family sessions',
+            token_record.user_id, token_record.token_family, request.remote_addr,
+        )
+        # Invalidate only the affected family, not every session for the user.
+        refresh_tokens_db.remove(
+            (TokenQuery.user_id == token_record.user_id) & (TokenQuery.token_family == token_record.token_family)
+        )
+        resp = jsonify({'error': 'Token reuse detected, family sessions invalidated', 'code': REFRESH_TOKEN_REUSE})
         _clear_auth_cookies(resp)
         return resp, 401
 
-    if user.marked_for_deletion:
-        refresh_tokens_db.remove(TokenQuery.user_id == user.id)
-        resp = jsonify({'error': 'Account marked for deletion', 'code': ACCOUNT_MARKED_FOR_DELETION})
-        _clear_auth_cookies(resp)
-        return resp, 403
-
     # ROTATION: mark old token as used, create new one in same family
-    refresh_tokens_db.update({'is_used': True}, TokenQuery.id == token_record.id)
+    refresh_tokens_db.update(
+        {'is_used': True, 'rotated_at': datetime.now(timezone.utc).isoformat()},
+        TokenQuery.id == token_record.id,
+    )
     raw_new_refresh, _ = _create_refresh_token(user.id, token_family=token_record.token_family)
 
     # Issue new access token
@@ -499,6 +549,7 @@ def e2e_create_delete_user():
         verified=True,
         role='user',
         pin=E2E_DELETE_PIN,
+        tutorial_enabled=False,
     )
     users_db.insert(user.to_dict())
     return jsonify({'email': norm_email}), 201
@@ -524,6 +575,33 @@ def e2e_create_cc_user():
         verified=True,
         role='user',
         pin=E2E_CC_PIN,
+        tutorial_enabled=False,
+    )
+    users_db.insert(user.to_dict())
+    return jsonify({'email': norm_email}), 201
+
+
+@auth_api.route('/e2e-create-tutorial-user', methods=['POST'])
+def e2e_create_tutorial_user():
+    """Create an isolated e2e test user for tutorial tests. Only available outside production."""
+    if os.environ.get('DB_ENV', 'prod') == 'prod':
+        return jsonify({'error': 'Not available in production'}), 403
+
+    norm_email = normalize_email(E2E_TUTORIAL_EMAIL)
+    # Clean up any children from previous tutorial runs.
+    existing = users_db.get(UserQuery.email == norm_email)
+    if existing:
+        child_db.remove(Query().user_id == existing.get('id'))
+    users_db.remove(UserQuery.email == norm_email)
+    user = User(
+        first_name='E2E',
+        last_name='Tutorial',
+        email=norm_email,
+        password=generate_password_hash(E2E_TUTORIAL_PASSWORD),
+        verified=True,
+        role='user',
+        pin=E2E_TUTORIAL_PIN,
+        tutorial_enabled=False,
     )
     users_db.insert(user.to_dict())
     return jsonify({'email': norm_email}), 201
@@ -547,6 +625,12 @@ def e2e_seed():
     chore_schedules_db.truncate()
     task_extensions_db.truncate()
     refresh_tokens_db.truncate()
+    routine_db.truncate()
+    routine_items_db.truncate()
+    routine_schedules_db.truncate()
+    routine_extensions_db.truncate()
+    push_subscriptions_db.truncate()
+    digest_action_tokens_db.truncate()
 
     # Recreate only baseline defaults for e2e runs.
     initializeImages()
@@ -562,6 +646,7 @@ def e2e_seed():
         verified=True,
         role='user',
         pin=E2E_TEST_PIN,
+        tutorial_enabled=False,
     )
     users_db.insert(user.to_dict())
 

backend/api/child_action_helpers.py

@@ -9,12 +9,14 @@ from datetime import datetime, timezone
 
 from tinydb import Query
 
-from db.db import child_db, task_db, reward_db, pending_confirmations_db
+from db.db import child_db, task_db, reward_db, pending_confirmations_db, routine_db
 from db.child_overrides import get_override
 from db.chore_schedules import get_schedule
+from db.routine_schedules import get_schedule as get_routine_schedule
 from db.tracking import insert_tracking_event
 from events.sse import send_event_to_user
 from events.types.child_chore_confirmation import ChildChoreConfirmation
+from events.types.child_routine_confirmation import ChildRoutineConfirmation
 from events.types.child_reward_request import ChildRewardRequest
 from events.types.child_reward_triggered import ChildRewardTriggered
 from events.types.child_task_triggered import ChildTaskTriggered
@@ -23,6 +25,7 @@ from events.types.event import Event
 from events.types.event_types import EventType
 from models.child import Child
 from models.reward import Reward
+from models.routine import Routine
 from models.task import Task
 from models.tracking_event import TrackingEvent
 from utils.tracking_logger import log_tracking_event
@@ -271,3 +274,84 @@ def deny_reward(user_id: str, child_id: str, reward_id: str) -> dict | None:
                                      ChildRewardRequest(child_id, reward_id, ChildRewardRequest.REQUEST_CANCELLED)))
 
     return {'child_name': child_name}
+
+
+def approve_routine(user_id: str, child_id: str, routine_id: str) -> dict | None:
+    """Award points for a completed routine and mark the pending confirmation approved.
+
+    Returns a result dict on success, or None if already resolved.
+    Raises ValueError if the child or routine cannot be found.
+    """
+    ChildQ = Query()
+    child_result = child_db.get((ChildQ.id == child_id) & (ChildQ.user_id == user_id))
+    if not child_result:
+        raise ValueError(f'Child {child_id} not found for user {user_id}')
+    child = Child.from_dict(child_result)
+
+    if routine_id not in child.routines:
+        logger.info(f'Routine {routine_id} no longer assigned to child {child_id}; skipping approve')
+        return None
+
+    PendingQ = Query()
+    existing = pending_confirmations_db.get(
+        (PendingQ.child_id == child_id) & (PendingQ.entity_id == routine_id) &
+        (PendingQ.entity_type == 'routine') & (PendingQ.status == 'pending') &
+        (PendingQ.user_id == user_id)
+    )
+    if not existing:
+        logger.info(f'No pending routine for child {child_id}, routine {routine_id} — already resolved')
+        return None
+
+    RoutineQ = Query()
+    routine_result = routine_db.get(
+        (RoutineQ.id == routine_id) & ((RoutineQ.user_id == user_id) | (RoutineQ.user_id == None))
+    )
+    if not routine_result:
+        raise ValueError(f'Routine {routine_id} not found')
+    routine = Routine.from_dict(routine_result)
+
+    override = get_override(child_id, routine_id)
+    points_value = override.custom_value if override and override.entity_type == 'routine' else routine.points
+    points_before = child.points
+    child.points += points_value
+    child_db.update({'points': child.points}, ChildQ.id == child_id)
+
+    schedule = get_routine_schedule(child_id, routine_id)
+    now_str = datetime.now(timezone.utc).isoformat()
+    if schedule:
+        pending_confirmations_db.update(
+            {'status': 'approved', 'approved_at': now_str},
+            (PendingQ.child_id == child_id) & (PendingQ.entity_id == routine_id) &
+            (PendingQ.entity_type == 'routine') & (PendingQ.user_id == user_id)
+        )
+    else:
+        pending_confirmations_db.remove(
+            (PendingQ.child_id == child_id) & (PendingQ.entity_id == routine_id) &
+            (PendingQ.entity_type == 'routine') & (PendingQ.user_id == user_id)
+        )
+
+    send_event_to_user(user_id, Event(EventType.CHILD_ROUTINE_CONFIRMATION.value,
+                                     ChildRoutineConfirmation(child_id, routine_id, ChildRoutineConfirmation.OPERATION_APPROVED)))
+
+    return {'routine_name': routine.name, 'child_name': child.name, 'child_id': child_id, 'points': child.points}
+
+
+def reject_routine(user_id: str, child_id: str, routine_id: str) -> None:
+    """Reject a pending routine confirmation. No-op if already resolved."""
+    PendingQ = Query()
+    existing = pending_confirmations_db.get(
+        (PendingQ.child_id == child_id) & (PendingQ.entity_id == routine_id) &
+        (PendingQ.entity_type == 'routine') & (PendingQ.status == 'pending') &
+        (PendingQ.user_id == user_id)
+    )
+    if not existing:
+        logger.info(f'No pending routine for child {child_id}, routine {routine_id} — already resolved')
+        return
+
+    pending_confirmations_db.remove(
+        (PendingQ.child_id == child_id) & (PendingQ.entity_id == routine_id) &
+        (PendingQ.entity_type == 'routine') & (PendingQ.user_id == user_id)
+    )
+
+    send_event_to_user(user_id, Event(EventType.CHILD_ROUTINE_CONFIRMATION.value,
+                                     ChildRoutineConfirmation(child_id, routine_id, ChildRoutineConfirmation.OPERATION_REJECTED)))

backend/api/child_api.py

@@ -1,5 +1,6 @@
 from time import sleep
 from datetime import datetime, timezone
+from zoneinfo import ZoneInfo
 
 from flask import Blueprint, request, jsonify
 from tinydb import Query
@@ -10,7 +11,7 @@ from api.pending_confirmation import PendingConfirmationResponse
 from api.reward_status import RewardStatus
 from api.utils import send_event_for_current_user, get_validated_user_id
 import api.child_action_helpers as chore_actions
-from db.db import child_db, task_db, reward_db, pending_reward_db, pending_confirmations_db, users_db
+from db.db import child_db, task_db, reward_db, routine_db, pending_reward_db, pending_confirmations_db, users_db
 from db.tracking import insert_tracking_event
 from db.child_overrides import get_override, delete_override, delete_overrides_for_child
 from events.types.child_chore_confirmation import ChildChoreConfirmation
@@ -35,11 +36,60 @@ from utils.digest_token import create_action_token
 from collections import defaultdict
 from db.chore_schedules import get_schedule
 from db.task_extensions import get_extension_for_child_task
+from db.routine_schedules import delete_schedules_for_child as delete_routine_schedules_for_child
+from db.routine_extensions import delete_extensions_for_child as delete_routine_extensions_for_child
 import logging
 
 child_api = Blueprint('child_api', __name__)
 logger = logging.getLogger(__name__)
 
+
+def _get_user_timezone(user_id: str) -> str | None:
+    user = users_db.get(Query().id == user_id)
+    if not user:
+        return None
+    return user.get('timezone')
+
+
+def _get_user_today_local(user_id: str) -> tuple[str, str | None]:
+    tz_str = _get_user_timezone(user_id)
+    try:
+        now_local = datetime.now(ZoneInfo(tz_str)) if tz_str else datetime.now(timezone.utc)
+    except Exception:
+        tz_str = None
+        now_local = datetime.now(timezone.utc)
+    return now_local.strftime('%Y-%m-%d'), tz_str
+
+
+def _is_iso_timestamp_on_local_day(timestamp: str | None, local_day: str, tz_str: str | None) -> bool:
+    if not timestamp:
+        return False
+    try:
+        normalized = timestamp.replace('Z', '+00:00')
+        parsed = datetime.fromisoformat(normalized)
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        try:
+            tz = ZoneInfo(tz_str) if tz_str else timezone.utc
+        except Exception:
+            tz = timezone.utc
+        return parsed.astimezone(tz).strftime('%Y-%m-%d') == local_day
+    except (TypeError, ValueError):
+        return False
+
+
+def _is_epoch_timestamp_on_local_day(epoch_ts, local_day: str, tz_str: str | None) -> bool:
+    if epoch_ts is None:
+        return False
+    try:
+        tz = ZoneInfo(tz_str) if tz_str else timezone.utc
+    except Exception:
+        tz = timezone.utc
+    try:
+        return datetime.fromtimestamp(float(epoch_ts), tz).strftime('%Y-%m-%d') == local_day
+    except (TypeError, ValueError, OSError):
+        return False
+
 @child_api.route('/child/<name>', methods=['GET'])
 @child_api.route('/child/<id>', methods=['GET'])
 def get_child(id):
@@ -151,6 +201,14 @@ def delete_child(id):
     if deleted_count > 0:
         logger.info(f"Cascade deleted {deleted_count} overrides for child {id}")
 
+    # Cascade delete routine schedule/extension rows for this child.
+    delete_routine_schedules_for_child(id)
+    delete_routine_extensions_for_child(id)
+
+    # Remove pending routine confirmations for this child.
+    PendingQuery = Query()
+    pending_confirmations_db.remove((PendingQuery.child_id == id) & (PendingQuery.entity_type == 'routine'))
+    
     if child_db.remove((ChildQuery.id == id) & (ChildQuery.user_id == user_id)):
         resp = send_event_for_current_user(Event(EventType.CHILD_MODIFIED.value, ChildModified(id, ChildModified.OPERATION_DELETE)))
         if resp:
@@ -282,6 +340,7 @@ def list_child_tasks(id):
     task_ids = child.get('tasks', [])
 
     TaskQuery = Query()
+    today_local, tz_str = _get_user_today_local(user_id)
     child_tasks = []
     for tid in task_ids:
         task = task_db.get((TaskQuery.id == tid) & ((TaskQuery.user_id == user_id) | (TaskQuery.user_id == None)))
@@ -313,8 +372,21 @@ def list_child_tasks(id):
                 (PendingQuery.entity_type == 'chore') & (PendingQuery.user_id == user_id)
             )
             if pending:
-                ct_dict['pending_status'] = pending.get('status')
-                ct_dict['approved_at'] = pending.get('approved_at')
+                status = pending.get('status')
+                approved_at = pending.get('approved_at')
+                created_at = pending.get('created_at')
+                if status == 'approved' and _is_iso_timestamp_on_local_day(approved_at, today_local, tz_str):
+                    ct_dict['pending_status'] = 'approved'
+                    ct_dict['approved_at'] = approved_at
+                elif status == 'pending' and _is_epoch_timestamp_on_local_day(created_at, today_local, tz_str):
+                    ct_dict['pending_status'] = 'pending'
+                    ct_dict['approved_at'] = None
+                else:
+                    pending_id = pending.get('id')
+                    if pending_id:
+                        pending_confirmations_db.remove(PendingQuery.id == pending_id)
+                    ct_dict['pending_status'] = None
+                    ct_dict['approved_at'] = None
             else:
                 ct_dict['pending_status'] = None
                 ct_dict['approved_at'] = None
@@ -854,6 +926,7 @@ def reward_status(id):
     reward_ids = child.rewards
 
     RewardQuery = Query()
+    today_local, tz_str = _get_user_today_local(user_id)
     statuses = []
     for reward_id in reward_ids:
         reward_dict = reward_db.get((RewardQuery.id == reward_id) & ((RewardQuery.user_id == user_id) | (RewardQuery.user_id == None)))
@@ -872,7 +945,16 @@ def reward_status(id):
             (pending_query.child_id == child.id) & (pending_query.entity_id == reward.id) &
             (pending_query.entity_type == 'reward') & (pending_query.user_id == user_id)
         )
-        status = RewardStatus(reward.id, reward.name, points_needed, cost_value, pending is not None, reward.image_id)
+        redeeming = False
+        if pending and pending.get('status') == 'pending':
+            if _is_epoch_timestamp_on_local_day(pending.get('created_at'), today_local, tz_str):
+                redeeming = True
+            else:
+                pending_id = pending.get('id')
+                if pending_id:
+                    pending_confirmations_db.remove(pending_query.id == pending_id)
+
+        status = RewardStatus(reward.id, reward.name, points_needed, cost_value, redeeming, reward.image_id)
         status_dict = status.to_dict()
         if override:
             status_dict['custom_value'] = override.custom_value
@@ -927,7 +1009,12 @@ def request_reward(id):
         (DupQuery.user_id == user_id)
     )
     if duplicate:
-        return jsonify({'error': 'Reward request already pending', 'code': 'DUPLICATE_REWARD_REQUEST'}), 409
+        today_local, tz_str = _get_user_today_local(user_id)
+        if _is_epoch_timestamp_on_local_day(duplicate.get('created_at'), today_local, tz_str):
+            return jsonify({'error': 'Reward request already pending', 'code': 'DUPLICATE_REWARD_REQUEST'}), 409
+        pending_id = duplicate.get('id')
+        if pending_id:
+            pending_confirmations_db.remove(DupQuery.id == pending_id)
 
     pending = PendingConfirmation(child_id=child.id, entity_id=reward.id, entity_type='reward', user_id=user_id)
     pending_confirmations_db.insert(pending.to_dict())
@@ -1053,6 +1140,7 @@ def list_pending_confirmations():
     if not user_id:
         return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
     PendingQuery = Query()
+    today_local, tz_str = _get_user_today_local(user_id)
     pending_items = pending_confirmations_db.search(
         (PendingQuery.user_id == user_id) & (PendingQuery.status == 'pending')
     )
@@ -1060,11 +1148,16 @@ def list_pending_confirmations():
 
     RewardQuery = Query()
     TaskQuery = Query()
+    RoutineQuery = Query()
     ChildQuery = Query()
 
     for pr in pending_items:
         pending = PendingConfirmation.from_dict(pr)
 
+        if not _is_epoch_timestamp_on_local_day(pending.created_at, today_local, tz_str):
+            pending_confirmations_db.remove(PendingQuery.id == pending.id)
+            continue
+
         # Look up child details
         child_result = child_db.get(ChildQuery.id == pending.child_id)
         if not child_result:
@@ -1074,8 +1167,12 @@ def list_pending_confirmations():
         # Look up entity details based on type
         if pending.entity_type == 'reward':
             entity_result = reward_db.get((RewardQuery.id == pending.entity_id) & ((RewardQuery.user_id == user_id) | (RewardQuery.user_id == None)))
-        else:
+        elif pending.entity_type == 'chore':
             entity_result = task_db.get((TaskQuery.id == pending.entity_id) & ((TaskQuery.user_id == user_id) | (TaskQuery.user_id == None)))
+        elif pending.entity_type == 'routine':
+            entity_result = routine_db.get((RoutineQuery.id == pending.entity_id) & ((RoutineQuery.user_id == user_id) | (RoutineQuery.user_id == None)))
+        else:
+            entity_result = None
         
         if not entity_result:
             continue
@@ -1137,13 +1234,20 @@ def confirm_chore(id):
         (PendingQuery.entity_type == 'chore') & (PendingQuery.user_id == user_id)
     )
     if existing:
+        today_local, tz_str = _get_user_today_local(user_id)
         if existing.get('status') == 'pending':
-            return jsonify({'error': 'Chore already pending confirmation', 'code': 'CHORE_ALREADY_PENDING'}), 400
+            if _is_epoch_timestamp_on_local_day(existing.get('created_at'), today_local, tz_str):
+                return jsonify({'error': 'Chore already pending confirmation', 'code': 'CHORE_ALREADY_PENDING'}), 400
+            pending_id = existing.get('id')
+            if pending_id:
+                pending_confirmations_db.remove(PendingQuery.id == pending_id)
         if existing.get('status') == 'approved':
             approved_at = existing.get('approved_at', '')
-            today_utc = datetime.now(timezone.utc).strftime('%Y-%m-%d')
-            if approved_at and approved_at[:10] == today_utc:
+            if _is_iso_timestamp_on_local_day(approved_at, today_local, tz_str):
                 return jsonify({'error': 'Chore already completed today', 'code': 'CHORE_ALREADY_COMPLETED'}), 400
+            pending_id = existing.get('id')
+            if pending_id:
+                pending_confirmations_db.remove(PendingQuery.id == pending_id)
 
     confirmation = PendingConfirmation(
         child_id=id, entity_id=task_id, entity_type='chore', user_id=user_id

backend/api/child_override_api.py

@@ -2,7 +2,7 @@ from flask import Blueprint, request, jsonify
 from tinydb import Query
 from api.utils import get_validated_user_id, send_event_for_current_user
 from api.error_codes import ErrorCodes
-from db.db import child_db, task_db, reward_db
+from db.db import child_db, task_db, reward_db, routine_db
 from db.child_overrides import (
     insert_override,
     get_override,
@@ -52,8 +52,8 @@ def set_child_override(child_id):
         return jsonify({'error': 'custom_value is required', 'code': ErrorCodes.MISSING_FIELD, 'field': 'custom_value'}), 400
     
     # Validate entity_type
-    if entity_type not in ['task', 'reward']:
-        return jsonify({'error': 'entity_type must be "task" or "reward"', 'code': ErrorCodes.INVALID_VALUE, 'field': 'entity_type'}), 400
+    if entity_type not in ['task', 'reward', 'routine']:
+        return jsonify({'error': 'entity_type must be "task", "reward", or "routine"', 'code': ErrorCodes.INVALID_VALUE, 'field': 'entity_type'}), 400
     
     # Validate custom_value range
     if not isinstance(custom_value, int) or custom_value < 0 or custom_value > 10000:
@@ -74,7 +74,7 @@ def set_child_override(child_id):
         if entity_id not in assigned_tasks:
             return jsonify({'error': 'Task not assigned to child', 'code': ErrorCodes.ENTITY_NOT_ASSIGNED}), 404
     
-    else:  # reward
+    elif entity_type == 'reward':
         EntityQuery = Query()
         entity_result = reward_db.search(
             (EntityQuery.id == entity_id) &
@@ -88,6 +88,19 @@ def set_child_override(child_id):
         if entity_id not in assigned_rewards:
             return jsonify({'error': 'Reward not assigned to child', 'code': ErrorCodes.ENTITY_NOT_ASSIGNED}), 404
 
+    else:  # routine
+        EntityQuery = Query()
+        entity_result = routine_db.search(
+            (EntityQuery.id == entity_id) &
+            ((EntityQuery.user_id == user_id) | (EntityQuery.user_id == None))
+        )
+        if not entity_result:
+            return jsonify({'error': 'Routine not found', 'code': 'ROUTINE_NOT_FOUND'}), 404
+
+        assigned_routines = child_dict.get('routines', [])
+        if entity_id not in assigned_routines:
+            return jsonify({'error': 'Routine not assigned to child', 'code': ErrorCodes.ENTITY_NOT_ASSIGNED}), 404
+    
     # Create and insert override
     try:
         override = ChildOverride.create_override(

backend/api/child_routine_api.py

@@ -0,0 +1,638 @@
+from collections import defaultdict
+from datetime import datetime, timezone
+from zoneinfo import ZoneInfo
+
+from flask import Blueprint, request, jsonify
+from tinydb import Query
+
+from api.error_codes import ErrorCodes
+from api.utils import get_validated_user_id, send_event_for_current_user
+from db.child_overrides import delete_override, get_override
+from db.db import child_db, pending_confirmations_db, routine_db, users_db
+from db.routine_extensions import delete_extension_for_child_routine, get_extension_for_child_routine
+from db.routine_items import get_items_for_routine
+from db.routine_schedules import delete_schedule, get_schedule
+from events.types.child_routine_confirmation import ChildRoutineConfirmation
+from events.types.child_routines_set import ChildRoutinesSet
+from events.types.event import Event
+from events.types.event_types import EventType
+from models.child import Child
+from models.pending_confirmation import PendingConfirmation
+from models.routine import Routine
+from utils.digest_token import create_action_token
+from utils.push_sender import send_push_to_user
+
+child_routine_api = Blueprint('child_routine_api', __name__)
+
+
+def _get_user_timezone(user_id: str) -> str | None:
+    user = users_db.get(Query().id == user_id)
+    if not user:
+        return None
+    return user.get('timezone')
+
+
+def _get_user_today_local(user_id: str) -> tuple[str, str | None]:
+    tz_str = _get_user_timezone(user_id)
+    try:
+        now_local = datetime.now(ZoneInfo(tz_str)) if tz_str else datetime.now(timezone.utc)
+    except Exception:
+        tz_str = None
+        now_local = datetime.now(timezone.utc)
+    return now_local.strftime('%Y-%m-%d'), tz_str
+
+
+def _is_iso_timestamp_on_local_day(timestamp: str | None, local_day: str, tz_str: str | None) -> bool:
+    if not timestamp:
+        return False
+    try:
+        normalized = timestamp.replace('Z', '+00:00')
+        parsed = datetime.fromisoformat(normalized)
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        try:
+            tz = ZoneInfo(tz_str) if tz_str else timezone.utc
+        except Exception:
+            tz = timezone.utc
+        return parsed.astimezone(tz).strftime('%Y-%m-%d') == local_day
+    except (TypeError, ValueError):
+        return False
+
+
+def _is_epoch_timestamp_on_local_day(epoch_ts, local_day: str, tz_str: str | None) -> bool:
+    if epoch_ts is None:
+        return False
+    try:
+        tz = ZoneInfo(tz_str) if tz_str else timezone.utc
+    except Exception:
+        tz = timezone.utc
+    try:
+        return datetime.fromtimestamp(float(epoch_ts), tz).strftime('%Y-%m-%d') == local_day
+    except (TypeError, ValueError, OSError):
+        return False
+
+
+class ChildRoutine:
+    def __init__(self, name, points, image_id, _id):
+        self.id = _id
+        self.name = name
+        self.points = points
+        self.image_id = image_id
+
+    def to_dict(self):
+        return {
+            'id': self.id,
+            'name': self.name,
+            'points': self.points,
+            'image_id': self.image_id,
+        }
+
+
+def _validate_child_for_user(child_id: str, user_id: str):
+    child_q = Query()
+    result = child_db.search((child_q.id == child_id) & (child_q.user_id == user_id))
+    return Child.from_dict(result[0]) if result else None
+
+
+def _resolve_routine_for_user(routine_id: str, user_id: str):
+    routine_q = Query()
+    routine_result = routine_db.get(
+        (routine_q.id == routine_id) & ((routine_q.user_id == user_id) | (routine_q.user_id == None))
+    )
+    return Routine.from_dict(routine_result) if routine_result else None
+
+
+@child_routine_api.route('/child/<id>/assign-routine', methods=['POST'])
+def assign_routine_to_child(id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    data = request.get_json() or {}
+    routine_id = data.get('routine_id')
+    if not routine_id:
+        return jsonify({'error': 'routine_id is required', 'code': ErrorCodes.MISSING_FIELD}), 400
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    routine = _resolve_routine_for_user(routine_id, user_id)
+    if not routine:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    routine_ids = list(child.routines)
+    if routine_id not in routine_ids:
+        routine_ids.append(routine_id)
+        child_db.update({'routines': routine_ids}, Query().id == id)
+
+    send_event_for_current_user(
+        Event(EventType.CHILD_ROUTINES_SET.value, ChildRoutinesSet(id, routine_ids))
+    )
+    return jsonify({'message': f'Routine {routine_id} assigned to {child.name}.'}), 200
+
+
+@child_routine_api.route('/child/<id>/remove-routine', methods=['POST'])
+def remove_routine_from_child(id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    data = request.get_json() or {}
+    routine_id = data.get('routine_id')
+    if not routine_id:
+        return jsonify({'error': 'routine_id is required', 'code': ErrorCodes.MISSING_FIELD}), 400
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    routine_ids = list(child.routines)
+    if routine_id not in routine_ids:
+        return jsonify({'error': 'Routine not assigned to child', 'code': ErrorCodes.ENTITY_NOT_ASSIGNED}), 400
+
+    routine_ids.remove(routine_id)
+    child_db.update({'routines': routine_ids}, Query().id == id)
+
+    override = get_override(id, routine_id)
+    if override and override.entity_type == 'routine':
+        delete_override(id, routine_id)
+
+    delete_schedule(id, routine_id)
+    delete_extension_for_child_routine(id, routine_id)
+
+    pending_q = Query()
+    pending_confirmations_db.remove(
+        (pending_q.child_id == id) & (pending_q.entity_id == routine_id) &
+        (pending_q.entity_type == 'routine') & (pending_q.user_id == user_id)
+    )
+
+    send_event_for_current_user(
+        Event(EventType.CHILD_ROUTINES_SET.value, ChildRoutinesSet(id, routine_ids))
+    )
+    send_event_for_current_user(
+        Event(
+            EventType.CHILD_ROUTINE_CONFIRMATION.value,
+            ChildRoutineConfirmation(id, routine_id, ChildRoutineConfirmation.OPERATION_RESET)
+        )
+    )
+    return jsonify({'message': f'Routine {routine_id} removed from {child.name}.'}), 200
+
+
+@child_routine_api.route('/child/<id>/set-routines', methods=['PUT'])
+def set_child_routines(id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    data = request.get_json() or {}
+    routine_ids = data.get('routine_ids')
+    if not isinstance(routine_ids, list):
+        return jsonify({'error': 'routine_ids must be a list'}), 400
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    routine_q = Query()
+    valid_ids = []
+    for rid in dict.fromkeys(routine_ids):
+        if routine_db.get((routine_q.id == rid) & ((routine_q.user_id == user_id) | (routine_q.user_id == None))):
+            valid_ids.append(rid)
+
+    old_ids = set(child.routines)
+    new_ids = set(valid_ids)
+    unassigned_ids = old_ids - new_ids
+
+    pending_q = Query()
+    for rid in unassigned_ids:
+        override = get_override(id, rid)
+        if override and override.entity_type == 'routine':
+            delete_override(id, rid)
+
+        delete_schedule(id, rid)
+        delete_extension_for_child_routine(id, rid)
+
+        pending_confirmations_db.remove(
+            (pending_q.child_id == id) & (pending_q.entity_id == rid) &
+            (pending_q.entity_type == 'routine') & (pending_q.user_id == user_id)
+        )
+
+    child_db.update({'routines': valid_ids}, Query().id == id)
+    send_event_for_current_user(Event(EventType.CHILD_ROUTINES_SET.value, ChildRoutinesSet(id, valid_ids)))
+
+    return jsonify({'message': f'Routines set for child {id}.', 'routine_ids': valid_ids, 'count': len(valid_ids)}), 200
+
+
+@child_routine_api.route('/child/<id>/list-routines', methods=['GET'])
+def list_child_routines(id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    routine_q = Query()
+    pending_q = Query()
+    today_local, tz_str = _get_user_today_local(user_id)
+
+    child_routines = []
+    for rid in child.routines:
+        routine_record = routine_db.get((routine_q.id == rid) & ((routine_q.user_id == user_id) | (routine_q.user_id == None)))
+        if not routine_record:
+            continue
+
+        routine = Routine.from_dict(routine_record)
+        override = get_override(id, rid)
+        custom_value = override.custom_value if override and override.entity_type == 'routine' else None
+
+        cr = ChildRoutine(routine.name, routine.points, routine.image_id, routine.id)
+        cr_dict = cr.to_dict()
+        if custom_value is not None:
+            cr_dict['custom_value'] = custom_value
+
+        schedule = get_schedule(id, rid)
+        cr_dict['schedule'] = schedule.to_dict() if schedule else None
+
+        extension = get_extension_for_child_routine(id, rid)
+        cr_dict['extension_date'] = extension.date if extension else None
+
+        items = get_items_for_routine(rid)
+        cr_dict['items'] = [item.to_dict() for item in items]
+
+        pending = pending_confirmations_db.get(
+            (pending_q.child_id == id) & (pending_q.entity_id == rid) &
+            (pending_q.entity_type == 'routine') & (pending_q.user_id == user_id)
+        )
+        if pending:
+            status = pending.get('status')
+            approved_at = pending.get('approved_at')
+            created_at = pending.get('created_at')
+            confirmation_id = pending.get('id')
+
+            if status == 'approved' and _is_iso_timestamp_on_local_day(approved_at, today_local, tz_str):
+                cr_dict['pending_status'] = 'approved'
+                cr_dict['approved_at'] = approved_at
+                cr_dict['pending_confirmation_id'] = confirmation_id
+            elif status == 'pending' and _is_epoch_timestamp_on_local_day(created_at, today_local, tz_str):
+                cr_dict['pending_status'] = 'pending'
+                cr_dict['approved_at'] = None
+                cr_dict['pending_confirmation_id'] = confirmation_id
+            else:
+                pending_id = pending.get('id')
+                if pending_id:
+                    pending_confirmations_db.remove(pending_q.id == pending_id)
+                cr_dict['pending_status'] = None
+                cr_dict['approved_at'] = None
+                cr_dict['pending_confirmation_id'] = None
+        else:
+            cr_dict['pending_status'] = None
+            cr_dict['approved_at'] = None
+            cr_dict['pending_confirmation_id'] = None
+
+        child_routines.append(cr_dict)
+
+    return jsonify({'routines': child_routines}), 200
+
+
+@child_routine_api.route('/child/<id>/list-assignable-routines', methods=['GET'])
+def list_assignable_routines(id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    assigned_ids = set(child.routines)
+    all_routines = [r for r in routine_db.all() if r and r.get('id') and r.get('id') not in assigned_ids]
+
+    name_to_routines = defaultdict(list)
+    for routine in all_routines:
+        name_to_routines[routine.get('name')].append(routine)
+
+    filtered_routines = []
+    for _, routines in name_to_routines.items():
+        user_routines = [r for r in routines if r.get('user_id') is not None]
+        if len(user_routines) == 0:
+            filtered_routines.append(routines[0])
+        elif len(user_routines) == 1:
+            filtered_routines.append(user_routines[0])
+        else:
+            filtered_routines.extend(user_routines)
+
+    assignable = [
+        ChildRoutine(r.get('name'), r.get('points'), r.get('image_id'), r.get('id')).to_dict()
+        for r in filtered_routines
+    ]
+    return jsonify({'routines': assignable, 'count': len(assignable)}), 200
+
+
+@child_routine_api.route('/child/<id>/confirm-routine', methods=['POST'])
+def confirm_routine(id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    data = request.get_json() or {}
+    routine_id = data.get('routine_id')
+    if not routine_id:
+        return jsonify({'error': 'routine_id is required', 'code': ErrorCodes.MISSING_FIELD}), 400
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    if routine_id not in child.routines:
+        return jsonify({'error': 'Routine not assigned to child', 'code': ErrorCodes.ENTITY_NOT_ASSIGNED}), 400
+
+    routine = _resolve_routine_for_user(routine_id, user_id)
+    if not routine:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    pending_q = Query()
+    existing = pending_confirmations_db.get(
+        (pending_q.child_id == id) & (pending_q.entity_id == routine_id) &
+        (pending_q.entity_type == 'routine') & (pending_q.user_id == user_id)
+    )
+    if existing:
+        today_local, tz_str = _get_user_today_local(user_id)
+        if existing.get('status') == 'pending':
+            if _is_epoch_timestamp_on_local_day(existing.get('created_at'), today_local, tz_str):
+                return jsonify({'error': 'Routine already pending confirmation', 'code': 'ROUTINE_ALREADY_PENDING'}), 400
+            pending_id = existing.get('id')
+            if pending_id:
+                pending_confirmations_db.remove(pending_q.id == pending_id)
+        if existing.get('status') == 'approved':
+            approved_at = existing.get('approved_at', '')
+            if _is_iso_timestamp_on_local_day(approved_at, today_local, tz_str):
+                return jsonify({'error': 'Routine already completed today', 'code': 'ROUTINE_ALREADY_COMPLETED'}), 400
+            pending_id = existing.get('id')
+            if pending_id:
+                pending_confirmations_db.remove(pending_q.id == pending_id)
+
+    confirmation = PendingConfirmation(
+        child_id=id,
+        entity_id=routine_id,
+        entity_type='routine',
+        user_id=user_id,
+    )
+    pending_confirmations_db.insert(confirmation.to_dict())
+
+    send_event_for_current_user(
+        Event(
+            EventType.CHILD_ROUTINE_CONFIRMATION.value,
+            ChildRoutineConfirmation(id, routine_id, ChildRoutineConfirmation.OPERATION_PENDING)
+        )
+    )
+
+    push_user = users_db.get(Query().id == user_id)
+    if push_user and push_user.get('push_notifications_enabled', True):
+        try:
+            approve_token = create_action_token(user_id, id, routine_id, 'routine', 'approve')
+            deny_token = create_action_token(user_id, id, routine_id, 'routine', 'deny')
+            push_payload = {
+                'type': 'routine_confirmed',
+                'title': 'Routine Pending',
+                'body': f'{child.name} completed {routine.name}',
+                'user_id': user_id,
+                'child_id': id,
+                'child_name': child.name,
+                'entity_id': routine_id,
+                'entity_type': 'routine',
+                'entity_name': routine.name,
+                'approve_token': approve_token.id,
+                'deny_token': deny_token.id,
+            }
+            send_push_to_user(user_id, push_payload)
+        except Exception:
+            pass
+
+    return jsonify({'message': f'Routine {routine.name} confirmed by {child.name}.', 'confirmation_id': confirmation.id}), 200
+
+
+@child_routine_api.route('/child/<id>/cancel-routine-confirmation', methods=['POST'])
+def cancel_routine_confirmation(id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    data = request.get_json() or {}
+    routine_id = data.get('routine_id')
+    if not routine_id:
+        return jsonify({'error': 'routine_id is required', 'code': ErrorCodes.MISSING_FIELD}), 400
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    pending_q = Query()
+    existing = pending_confirmations_db.get(
+        (pending_q.child_id == id) & (pending_q.entity_id == routine_id) &
+        (pending_q.entity_type == 'routine') & (pending_q.status == 'pending') &
+        (pending_q.user_id == user_id)
+    )
+    if not existing:
+        return jsonify({'error': 'No pending confirmation found', 'code': 'PENDING_NOT_FOUND'}), 400
+
+    pending_confirmations_db.remove(
+        (pending_q.child_id == id) & (pending_q.entity_id == routine_id) &
+        (pending_q.entity_type == 'routine') & (pending_q.status == 'pending') &
+        (pending_q.user_id == user_id)
+    )
+
+    send_event_for_current_user(
+        Event(
+            EventType.CHILD_ROUTINE_CONFIRMATION.value,
+            ChildRoutineConfirmation(id, routine_id, ChildRoutineConfirmation.OPERATION_RESET)
+        )
+    )
+    return jsonify({'message': 'Routine confirmation cancelled.'}), 200
+
+
+@child_routine_api.route('/child/<id>/approve-routine/<confirmation_id>', methods=['POST'])
+def approve_routine(id, confirmation_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    pending_q = Query()
+    confirmation = pending_confirmations_db.get(
+        (pending_q.id == confirmation_id) & (pending_q.child_id == id) &
+        (pending_q.entity_type == 'routine') & (pending_q.user_id == user_id)
+    )
+    if not confirmation:
+        return jsonify({'error': 'Pending confirmation not found', 'code': 'PENDING_NOT_FOUND'}), 404
+
+    if confirmation.get('status') != 'pending':
+        return jsonify({'error': 'Confirmation is already resolved', 'code': 'ALREADY_RESOLVED'}), 400
+
+    routine_id = confirmation.get('entity_id')
+    routine = _resolve_routine_for_user(routine_id, user_id)
+    if not routine:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    override = get_override(id, routine_id)
+    points_value = override.custom_value if override and override.entity_type == 'routine' else routine.points
+
+    new_points = max(0, child.points + points_value)
+    child_db.update({'points': new_points}, Query().id == id)
+
+    approved_at = datetime.now(timezone.utc).isoformat()
+    pending_confirmations_db.update(
+        {'status': 'approved', 'approved_at': approved_at},
+        pending_q.id == confirmation_id
+    )
+
+    send_event_for_current_user(
+        Event(
+            EventType.CHILD_ROUTINE_CONFIRMATION.value,
+            ChildRoutineConfirmation(id, routine_id, ChildRoutineConfirmation.OPERATION_APPROVED)
+        )
+    )
+
+    return jsonify({
+        'message': f'Routine {routine.name} approved for {child.name}.',
+        'points': new_points,
+        'id': child.id,
+    }), 200
+
+
+@child_routine_api.route('/child/<id>/reject-routine/<confirmation_id>', methods=['POST'])
+def reject_routine(id, confirmation_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    pending_q = Query()
+    confirmation = pending_confirmations_db.get(
+        (pending_q.id == confirmation_id) & (pending_q.child_id == id) &
+        (pending_q.entity_type == 'routine') & (pending_q.user_id == user_id)
+    )
+    if not confirmation:
+        return jsonify({'error': 'Pending confirmation not found', 'code': 'PENDING_NOT_FOUND'}), 404
+
+    if confirmation.get('status') != 'pending':
+        return jsonify({'error': 'Confirmation is already resolved', 'code': 'ALREADY_RESOLVED'}), 400
+
+    pending_confirmations_db.update({'status': 'rejected', 'approved_at': None}, pending_q.id == confirmation_id)
+
+    send_event_for_current_user(
+        Event(
+            EventType.CHILD_ROUTINE_CONFIRMATION.value,
+            ChildRoutineConfirmation(id, confirmation.get('entity_id'), ChildRoutineConfirmation.OPERATION_REJECTED)
+        )
+    )
+
+    return jsonify({'message': 'Routine confirmation rejected.'}), 200
+
+
+@child_routine_api.route('/child/<id>/reset-routine/<confirmation_id>', methods=['POST'])
+def reset_routine(id, confirmation_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    pending_q = Query()
+    confirmation = pending_confirmations_db.get(
+        (pending_q.id == confirmation_id) & (pending_q.child_id == id) &
+        (pending_q.entity_type == 'routine') & (pending_q.user_id == user_id)
+    )
+    if not confirmation:
+        return jsonify({'error': 'Pending confirmation not found', 'code': 'PENDING_NOT_FOUND'}), 404
+
+    routine_id = confirmation.get('entity_id')
+    pending_confirmations_db.remove(pending_q.id == confirmation_id)
+
+    send_event_for_current_user(
+        Event(
+            EventType.CHILD_ROUTINE_CONFIRMATION.value,
+            ChildRoutineConfirmation(id, routine_id, ChildRoutineConfirmation.OPERATION_RESET)
+        )
+    )
+    return jsonify({'message': 'Routine reset to available.'}), 200
+
+
+@child_routine_api.route('/child/<id>/trigger-routine', methods=['POST'])
+def trigger_child_routine(id):
+    """Parent-triggered routine confirmation — directly awards points."""
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    data = request.get_json() or {}
+    routine_id = data.get('routine_id')
+    if not routine_id:
+        return jsonify({'error': 'routine_id is required', 'code': ErrorCodes.MISSING_FIELD}), 400
+
+    child = _validate_child_for_user(id, user_id)
+    if not child:
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    if routine_id not in child.routines:
+        return jsonify({'error': 'Routine not assigned to child', 'code': ErrorCodes.ENTITY_NOT_ASSIGNED}), 400
+
+    routine = _resolve_routine_for_user(routine_id, user_id)
+    if not routine:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    # Check for override
+    override = get_override(id, routine_id)
+    points_value = override.custom_value if override and override.entity_type == 'routine' else routine.points
+
+    # Award points
+    new_points = max(0, child.points + points_value)
+    child_db.update({'points': new_points}, Query().id == id)
+
+    # Create an approved pending confirmation so it shows as completed in the routine list
+    pending_q = Query()
+    existing = pending_confirmations_db.get(
+        (pending_q.child_id == id) & (pending_q.entity_id == routine_id) &
+        (pending_q.entity_type == 'routine') & (pending_q.user_id == user_id)
+    )
+    if existing:
+        today_local, tz_str = _get_user_today_local(user_id)
+        # Remove old confirmation if it exists and is not from today
+        if existing.get('status') == 'approved' and _is_iso_timestamp_on_local_day(existing.get('approved_at'), today_local, tz_str):
+            return jsonify({'error': 'Routine already completed today', 'code': 'ROUTINE_ALREADY_COMPLETED'}), 400
+        pending_id = existing.get('id')
+        if pending_id:
+            pending_confirmations_db.remove(pending_q.id == pending_id)
+
+    confirmation = PendingConfirmation(
+        child_id=id,
+        entity_id=routine_id,
+        entity_type='routine',
+        user_id=user_id,
+        status='approved',
+        approved_at=datetime.now(timezone.utc).isoformat()
+    )
+    pending_confirmations_db.insert(confirmation.to_dict())
+
+    send_event_for_current_user(
+        Event(
+            EventType.CHILD_ROUTINE_CONFIRMATION.value,
+            ChildRoutineConfirmation(id, routine_id, ChildRoutineConfirmation.OPERATION_APPROVED)
+        )
+    )
+
+    return jsonify({
+        'message': f'Routine {routine.name} awarded to {child.name}.',
+        'points': new_points,
+        'id': child.id,
+    }), 200

backend/api/digest_action_api.py

@@ -5,7 +5,7 @@ from tinydb import Query
 
 from utils.digest_token import validate_and_consume_token, validate_unsubscribe_token, peek_token
 from db.db import users_db
-from api.child_action_helpers import approve_chore, reject_chore, approve_reward_request, deny_reward
+from api.child_action_helpers import approve_chore, reject_chore, approve_reward_request, deny_reward, approve_routine, reject_routine
 from api.utils import get_validated_user_id
 
 digest_action_api = Blueprint('digest_action_api', __name__)
@@ -79,6 +79,10 @@ def execute_digest_action(token_id: str):
             approve_reward_request(user_id, token.child_id, token.entity_id)
         elif token.entity_type == 'reward' and token.action == 'deny':
             deny_reward(user_id, token.child_id, token.entity_id)
+        elif token.entity_type == 'routine' and token.action == 'approve':
+            approve_routine(user_id, token.child_id, token.entity_id)
+        elif token.entity_type == 'routine' and token.action == 'deny':
+            reject_routine(user_id, token.child_id, token.entity_id)
         else:
             return jsonify({'error': 'Unknown action', 'code': 'INVALID_ACTION'}), 400
     except Exception as e:

backend/api/routine_api.py

@@ -0,0 +1,185 @@
+from flask import Blueprint, request, jsonify
+from tinydb import Query
+
+from api.utils import send_event_for_current_user, get_validated_user_id
+from db.db import routine_db, child_db, pending_confirmations_db
+from db.child_overrides import delete_overrides_for_entity
+from db.routine_items import delete_for_routine
+from db.routine_schedules import delete_schedules_for_routine
+from db.routine_extensions import delete_extensions_for_routine
+from events.types.event import Event
+from events.types.event_types import EventType
+from events.types.routine_modified import RoutineModified
+from events.types.child_routines_set import ChildRoutinesSet
+from models.routine import Routine
+
+routine_api = Blueprint('routine_api', __name__)
+
+
+@routine_api.route('/routine/add', methods=['PUT'])
+def add_routine():
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
+
+    data = request.get_json() or {}
+    name = data.get('name')
+    points = data.get('points')
+    image = data.get('image_id', '')
+
+    if not name or points is None:
+        return jsonify({'error': 'Name and points are required'}), 400
+
+    routine = Routine(name=name, points=points, image_id=image, user_id=user_id)
+    routine_db.insert(routine.to_dict())
+
+    send_event_for_current_user(
+        Event(EventType.ROUTINE_MODIFIED.value, RoutineModified(routine.id, RoutineModified.OPERATION_ADD))
+    )
+    return jsonify({'message': f'Routine {name} added.', 'routine': routine.to_dict()}), 201
+
+
+@routine_api.route('/routine/<id>', methods=['GET'])
+def get_routine(id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
+
+    q = Query()
+    result = routine_db.search((q.id == id) & ((q.user_id == user_id) | (q.user_id == None)))
+    if not result:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    return jsonify(result[0]), 200
+
+
+@routine_api.route('/routine/list', methods=['GET'])
+def list_routines():
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
+
+    ids_param = request.args.get('ids')
+    q = Query()
+    routines = routine_db.search((q.user_id == user_id) | (q.user_id == None))
+
+    if ids_param is not None:
+        if ids_param.strip() == '':
+            routines = []
+        else:
+            ids = set(ids_param.split(','))
+            routines = [routine for routine in routines if routine.get('id') in ids]
+
+    user_routines = {r['name'].strip().lower(): r for r in routines if r.get('user_id') == user_id}
+    filtered_routines = []
+    for routine in routines:
+        if routine.get('user_id') is None and routine['name'].strip().lower() in user_routines:
+            continue
+        filtered_routines.append(routine)
+
+    user_created = sorted(
+        [r for r in filtered_routines if r.get('user_id') == user_id],
+        key=lambda x: x['name'].lower(),
+    )
+    default_items = sorted(
+        [r for r in filtered_routines if r.get('user_id') is None],
+        key=lambda x: x['name'].lower(),
+    )
+
+    return jsonify({'routines': user_created + default_items}), 200
+
+
+@routine_api.route('/routine/<id>/edit', methods=['PUT'])
+def edit_routine(id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
+
+    q = Query()
+    existing = routine_db.get((q.id == id) & ((q.user_id == user_id) | (q.user_id == None)))
+    if not existing:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    routine = Routine.from_dict(existing)
+    data = request.get_json(force=True) or {}
+    is_dirty = False
+
+    if 'name' in data:
+        name = data.get('name', '').strip()
+        if not name:
+            return jsonify({'error': 'Name cannot be empty'}), 400
+        routine.name = name
+        is_dirty = True
+
+    if 'points' in data:
+        points = data.get('points')
+        if not isinstance(points, int) or points <= 0:
+            return jsonify({'error': 'Points must be a positive integer'}), 400
+        routine.points = points
+        is_dirty = True
+
+    if 'image_id' in data:
+        routine.image_id = data.get('image_id', '')
+        is_dirty = True
+
+    if not is_dirty:
+        return jsonify({'error': 'No valid fields to update'}), 400
+
+    if routine.user_id is None:
+        new_routine = Routine(name=routine.name, points=routine.points, image_id=routine.image_id, user_id=user_id)
+        routine_db.insert(new_routine.to_dict())
+        send_event_for_current_user(
+            Event(EventType.ROUTINE_MODIFIED.value, RoutineModified(new_routine.id, RoutineModified.OPERATION_ADD))
+        )
+        return jsonify(new_routine.to_dict()), 200
+
+    routine_db.update(routine.to_dict(), q.id == id)
+    send_event_for_current_user(
+        Event(EventType.ROUTINE_MODIFIED.value, RoutineModified(id, RoutineModified.OPERATION_EDIT))
+    )
+    return jsonify(routine.to_dict()), 200
+
+
+@routine_api.route('/routine/<id>', methods=['DELETE'])
+def delete_routine(id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
+
+    q = Query()
+    routine = routine_db.get(q.id == id)
+    if not routine:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    if routine.get('user_id') is None:
+        return jsonify({'error': 'System routines cannot be deleted.'}), 403
+
+    removed = routine_db.remove((q.id == id) & (q.user_id == user_id))
+    if not removed:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    delete_overrides_for_entity(id)
+    delete_for_routine(id)
+    delete_schedules_for_routine(id)
+    delete_extensions_for_routine(id)
+
+    pending_q = Query()
+    pending_confirmations_db.remove(
+        (pending_q.entity_id == id) & (pending_q.entity_type == 'routine') & (pending_q.user_id == user_id)
+    )
+
+    child_q = Query()
+    children = child_db.search(child_q.user_id == user_id)
+    for child in children:
+        routine_ids = child.get('routines', [])
+        if id in routine_ids:
+            routine_ids = [rid for rid in routine_ids if rid != id]
+            child_db.update({'routines': routine_ids}, child_q.id == child.get('id'))
+            send_event_for_current_user(
+                Event(EventType.CHILD_ROUTINES_SET.value, ChildRoutinesSet(child.get('id'), routine_ids))
+            )
+
+    send_event_for_current_user(
+        Event(EventType.ROUTINE_MODIFIED.value, RoutineModified(id, RoutineModified.OPERATION_DELETE))
+    )
+    return jsonify({'message': f'Routine {id} deleted.'}), 200

backend/api/routine_item_api.py

@@ -0,0 +1,126 @@
+from flask import Blueprint, request, jsonify
+from tinydb import Query
+
+from api.utils import get_validated_user_id, send_event_for_current_user
+from db.db import routine_db
+from db.routine_items import add_item, delete_item, get_item, get_items_for_routine, update_item
+from events.types.event import Event
+from events.types.event_types import EventType
+from events.types.routine_modified import RoutineModified
+from models.routine_item import RoutineItem
+
+routine_item_api = Blueprint('routine_item_api', __name__)
+
+
+def _validate_routine_owned_by_user(routine_id: str, user_id: str):
+    q = Query()
+    return routine_db.get((q.id == routine_id) & ((q.user_id == user_id) | (q.user_id == None)))
+
+
+@routine_item_api.route('/routine/<routine_id>/item/add', methods=['PUT'])
+def add_routine_item(routine_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
+
+    routine = _validate_routine_owned_by_user(routine_id, user_id)
+    if not routine:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    data = request.get_json() or {}
+    name = data.get('name', '').strip()
+    image_id = data.get('image_id')
+
+    if not name:
+        return jsonify({'error': 'name is required'}), 400
+
+    existing_items = get_items_for_routine(routine_id)
+    order = data.get('order', len(existing_items))
+
+    item = RoutineItem(routine_id=routine_id, name=name, image_id=image_id, order=order)
+    add_item(item)
+
+    send_event_for_current_user(
+        Event(EventType.ROUTINE_MODIFIED.value, RoutineModified(routine_id, RoutineModified.OPERATION_EDIT))
+    )
+    return jsonify(item.to_dict()), 201
+
+
+@routine_item_api.route('/routine/<routine_id>/item/<item_id>/edit', methods=['PUT'])
+def edit_routine_item(routine_id, item_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
+
+    routine = _validate_routine_owned_by_user(routine_id, user_id)
+    if not routine:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    existing = get_item(item_id)
+    if not existing or existing.routine_id != routine_id:
+        return jsonify({'error': 'Item not found'}), 404
+
+    data = request.get_json(force=True) or {}
+    is_dirty = False
+
+    if 'name' in data:
+        name = data.get('name', '').strip()
+        if not name:
+            return jsonify({'error': 'name cannot be empty'}), 400
+        existing.name = name
+        is_dirty = True
+
+    if 'image_id' in data:
+        existing.image_id = data.get('image_id')
+        is_dirty = True
+
+    if 'order' in data:
+        order = data.get('order')
+        if not isinstance(order, int) or order < 0:
+            return jsonify({'error': 'order must be a non-negative integer'}), 400
+        existing.order = order
+        is_dirty = True
+
+    if not is_dirty:
+        return jsonify({'error': 'No valid fields to update'}), 400
+
+    update_item(existing)
+    send_event_for_current_user(
+        Event(EventType.ROUTINE_MODIFIED.value, RoutineModified(routine_id, RoutineModified.OPERATION_EDIT))
+    )
+    return jsonify(existing.to_dict()), 200
+
+
+@routine_item_api.route('/routine/<routine_id>/item/<item_id>', methods=['DELETE'])
+def delete_routine_item(routine_id, item_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
+
+    routine = _validate_routine_owned_by_user(routine_id, user_id)
+    if not routine:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    item = get_item(item_id)
+    if not item or item.routine_id != routine_id:
+        return jsonify({'error': 'Item not found'}), 404
+
+    delete_item(item_id)
+    send_event_for_current_user(
+        Event(EventType.ROUTINE_MODIFIED.value, RoutineModified(routine_id, RoutineModified.OPERATION_EDIT))
+    )
+    return jsonify({'message': 'Item deleted'}), 200
+
+
+@routine_item_api.route('/routine/<routine_id>/items', methods=['GET'])
+def list_routine_items(routine_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
+
+    routine = _validate_routine_owned_by_user(routine_id, user_id)
+    if not routine:
+        return jsonify({'error': 'Routine not found'}), 404
+
+    items = [item.to_dict() for item in get_items_for_routine(routine_id)]
+    return jsonify({'items': items, 'count': len(items)}), 200

backend/api/routine_schedule_api.py

@@ -0,0 +1,178 @@
+from flask import Blueprint, request, jsonify
+from tinydb import Query
+
+from api.error_codes import ErrorCodes
+from api.utils import get_validated_user_id, send_event_for_current_user
+from db.db import child_db, pending_confirmations_db
+from db.routine_extensions import add_extension, delete_extension_for_child_routine, get_extension
+from db.routine_schedules import delete_schedule, get_schedule, upsert_schedule
+from events.types.child_routine_confirmation import ChildRoutineConfirmation
+from events.types.event import Event
+from events.types.event_types import EventType
+from events.types.routine_schedule_modified import RoutineScheduleModified
+from events.types.routine_time_extended import RoutineTimeExtended
+from models.routine_extension import RoutineExtension
+from models.routine_schedule import RoutineSchedule
+
+routine_schedule_api = Blueprint('routine_schedule_api', __name__)
+
+
+def _validate_child(child_id: str, user_id: str):
+    q = Query()
+    result = child_db.search((q.id == child_id) & (q.user_id == user_id))
+    return result[0] if result else None
+
+
+@routine_schedule_api.route('/child/<child_id>/routine/<routine_id>/schedule', methods=['GET'])
+def get_routine_schedule(child_id, routine_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    if not _validate_child(child_id, user_id):
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    schedule = get_schedule(child_id, routine_id)
+    if not schedule:
+        return jsonify({'error': 'Schedule not found'}), 404
+
+    return jsonify(schedule.to_dict()), 200
+
+
+@routine_schedule_api.route('/child/<child_id>/routine/<routine_id>/schedule', methods=['PUT'])
+def set_routine_schedule(child_id, routine_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    if not _validate_child(child_id, user_id):
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    data = request.get_json() or {}
+    mode = data.get('mode')
+    if mode not in ('days', 'interval'):
+        return jsonify({'error': 'mode must be "days" or "interval"', 'code': ErrorCodes.INVALID_VALUE}), 400
+
+    enabled = data.get('enabled', True)
+    if not isinstance(enabled, bool):
+        return jsonify({'error': 'enabled must be a boolean', 'code': ErrorCodes.INVALID_VALUE}), 400
+
+    if mode == 'days':
+        day_configs = data.get('day_configs', [])
+        if not isinstance(day_configs, list):
+            return jsonify({'error': 'day_configs must be a list', 'code': ErrorCodes.INVALID_VALUE}), 400
+
+        schedule = RoutineSchedule(
+            child_id=child_id,
+            routine_id=routine_id,
+            mode='days',
+            day_configs=day_configs,
+            default_hour=data.get('default_hour', 8),
+            default_minute=data.get('default_minute', 0),
+            default_has_deadline=data.get('default_has_deadline', True),
+            enabled=enabled,
+        )
+    else:
+        interval_days = data.get('interval_days', 2)
+        anchor_date = data.get('anchor_date', '')
+        interval_has_deadline = data.get('interval_has_deadline', True)
+        interval_hour = data.get('interval_hour', 0)
+        interval_minute = data.get('interval_minute', 0)
+
+        if not isinstance(interval_days, int) or not (1 <= interval_days <= 7):
+            return jsonify({'error': 'interval_days must be an integer between 1 and 7', 'code': ErrorCodes.INVALID_VALUE}), 400
+
+        schedule = RoutineSchedule(
+            child_id=child_id,
+            routine_id=routine_id,
+            mode='interval',
+            interval_days=interval_days,
+            anchor_date=anchor_date,
+            interval_has_deadline=interval_has_deadline,
+            interval_hour=interval_hour,
+            interval_minute=interval_minute,
+            enabled=enabled,
+        )
+
+    delete_extension_for_child_routine(child_id, routine_id)
+    upsert_schedule(schedule)
+
+    pending_q = Query()
+    pending_routines = pending_confirmations_db.search(
+        (pending_q.child_id == child_id) & (pending_q.entity_id == routine_id) &
+        (pending_q.entity_type == 'routine') & (pending_q.status == 'pending')
+    )
+    for _ in pending_routines:
+        pending_confirmations_db.remove(
+            (pending_q.child_id == child_id) & (pending_q.entity_id == routine_id) &
+            (pending_q.entity_type == 'routine') & (pending_q.status == 'pending')
+        )
+        send_event_for_current_user(
+            Event(
+                EventType.CHILD_ROUTINE_CONFIRMATION.value,
+                ChildRoutineConfirmation(child_id, routine_id, ChildRoutineConfirmation.OPERATION_RESET)
+            )
+        )
+
+    send_event_for_current_user(
+        Event(
+            EventType.ROUTINE_SCHEDULE_MODIFIED.value,
+            RoutineScheduleModified(child_id, routine_id, RoutineScheduleModified.OPERATION_SET)
+        )
+    )
+
+    return jsonify(schedule.to_dict()), 200
+
+
+@routine_schedule_api.route('/child/<child_id>/routine/<routine_id>/schedule', methods=['DELETE'])
+def delete_routine_schedule(child_id, routine_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    if not _validate_child(child_id, user_id):
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    removed = delete_schedule(child_id, routine_id)
+    if not removed:
+        return jsonify({'error': 'Schedule not found'}), 404
+
+    send_event_for_current_user(
+        Event(
+            EventType.ROUTINE_SCHEDULE_MODIFIED.value,
+            RoutineScheduleModified(child_id, routine_id, RoutineScheduleModified.OPERATION_DELETED)
+        )
+    )
+    return jsonify({'message': 'Schedule deleted'}), 200
+
+
+@routine_schedule_api.route('/child/<child_id>/routine/<routine_id>/extend', methods=['POST'])
+def extend_routine_time(child_id, routine_id):
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': ErrorCodes.UNAUTHORIZED}), 401
+
+    if not _validate_child(child_id, user_id):
+        return jsonify({'error': 'Child not found', 'code': ErrorCodes.CHILD_NOT_FOUND}), 404
+
+    data = request.get_json() or {}
+    date = data.get('date')
+    if not date or not isinstance(date, str):
+        return jsonify({'error': 'date is required (ISO date string)', 'code': ErrorCodes.MISSING_FIELD}), 400
+
+    existing = get_extension(child_id, routine_id, date)
+    if existing:
+        return jsonify({'error': 'Routine already extended for this date', 'code': 'ALREADY_EXTENDED'}), 409
+
+    delete_extension_for_child_routine(child_id, routine_id)
+    extension = RoutineExtension(child_id=child_id, routine_id=routine_id, date=date)
+    add_extension(extension)
+
+    send_event_for_current_user(
+        Event(
+            EventType.ROUTINE_TIME_EXTENDED.value,
+            RoutineTimeExtended(child_id, routine_id)
+        )
+    )
+
+    return jsonify(extension.to_dict()), 200

backend/api/user_api.py

@@ -49,6 +49,8 @@ def get_profile():
         'image_id': user.image_id,
         'email_digest_enabled': user.email_digest_enabled,
         'push_notifications_enabled': user.push_notifications_enabled,
+        'tutorial_enabled': user.tutorial_enabled,
+        'tutorial_progress': user.tutorial_progress or {},
     }), 200
 
 @user_api.route('/user/profile', methods=['PUT'])
@@ -109,6 +111,37 @@ def update_profile():
     
     return jsonify({'message': 'Profile updated'}), 200
 
+@user_api.route('/user/tutorial-progress', methods=['PATCH'])
+def update_tutorial_progress():
+    user_id = get_validated_user_id()
+    if not user_id:
+        return jsonify({'error': 'Unauthorized', 'code': 'UNAUTHORIZED'}), 401
+    user = get_current_user()
+    if not user:
+        return jsonify({'error': 'Unauthorized'}), 401
+    data = request.get_json() or {}
+
+    if data.get('reset') is True:
+        user.tutorial_progress = {}
+    elif 'enabled' in data:
+        user.tutorial_enabled = bool(data.get('enabled'))
+    elif 'step_id' in data:
+        step_id = str(data.get('step_id') or '').strip()
+        if not step_id:
+            return jsonify({'error': 'Missing step_id'}), 400
+        progress = dict(user.tutorial_progress or {})
+        progress[step_id] = bool(data.get('seen', True))
+        user.tutorial_progress = progress
+    else:
+        return jsonify({'error': 'No-op'}), 400
+
+    users_db.update(user.to_dict(), UserQuery.email == user.email)
+    send_event_for_current_user(Event(EventType.PROFILE_UPDATED.value, ProfileUpdated(user.id)))
+    return jsonify({
+        'tutorial_enabled': user.tutorial_enabled,
+        'tutorial_progress': user.tutorial_progress,
+    }), 200
+
 @user_api.route('/user/image', methods=['PUT'])
 def update_image():
     user_id = get_validated_user_id()

backend/config/version.py

@@ -2,7 +2,7 @@
 # file: config/version.py
 import os
 
-BASE_VERSION = "1.0.11"  # update manually when releasing features
+BASE_VERSION = "1.0.16"  # update manually when releasing features
 
 def get_full_version() -> str:
     """

backend/db/db.py

@@ -1,13 +1,42 @@
 # python
 import os
-from config.paths import get_database_dir
 import threading
+from config.paths import get_database_dir
 from tinydb import TinyDB
+from tinydb.queries import QueryInstance
 
+from db.mongo_client import get_mongo_client, get_mongo_db_name
+
+try:
+    from tinydb.table import Document
+except ImportError:  # pragma: no cover - tinydb version compatibility
+    from tinydb.database import Document
+
+
+def _stable_clause_key(clause: dict) -> str:
+    """Return a stable string key for sorting MongoDB filter clauses."""
+    import json
+    return json.dumps(clause, sort_keys=True, default=str)
+
+
+try:
+    from pymongo import ASCENDING
+except ImportError:  # pragma: no cover - pymongo is a required dependency
+    ASCENDING = 1
+
+
+USE_MONGODB = os.environ.get('USE_MONGODB', 'true').lower() == 'true'
+# Resolve the MongoDB database name once at module load so runtime changes to
+# DB_ENV/DATA_ENV in tests do not switch databases mid-process.
+_mongo_db_name = get_mongo_db_name() if USE_MONGODB else None
 base_dir = get_database_dir()
 os.makedirs(base_dir, exist_ok=True)
 
 
+# ---------------------------------------------------------------------------
+# TinyDB-backed table wrapper
+# ---------------------------------------------------------------------------
+
 class LockedTable:
     """
     Thread-safe wrapper around a TinyDB table. All callable attribute access
@@ -65,10 +94,369 @@ class LockedTable:
         with self._lock:
             return self._table.truncate()
 
+    def close(self):
+        with self._lock:
+            return self._table.close()
+
+
+# ---------------------------------------------------------------------------
+# TinyDB Query -> MongoDB filter translator
+# ---------------------------------------------------------------------------
+
+_MONGO_OP_MAP = {
+    '==': '$eq',
+    '!=': '$ne',
+    '<': '$lt',
+    '<=': '$lte',
+    '>': '$gt',
+    '>=': '$gte',
+}
+
+_NEGATED_OPS = {
+    '$eq': '$ne',
+    '$ne': '$eq',
+    '$lt': '$gte',
+    '$lte': '$gt',
+    '$gt': '$lte',
+    '$gte': '$lt',
+}
+
+
+def _field_to_mongo(field_path: tuple) -> str:
+    """Map a TinyDB field path to a MongoDB field name.
+
+    The model ``id`` field is stored as the MongoDB ``_id`` field, so queries
+    on ``id`` are translated to queries on ``_id``.
+    """
+    if len(field_path) == 1:
+        return '_id' if field_path[0] == 'id' else field_path[0]
+    return '.'.join('_id' if p == 'id' else p for p in field_path)
+
+
+def _negate_condition(cond: dict) -> dict | None:
+    """Return a MongoDB condition that negates a single-field condition."""
+    if len(cond) != 1:
+        return None
+    field, inner = next(iter(cond.items()))
+    if not isinstance(inner, dict) or len(inner) != 1:
+        return None
+    op, value = next(iter(inner.items()))
+    if op in _NEGATED_OPS:
+        return {field: {_NEGATED_OPS[op]: value}}
+    return None
+
+
+def _hash_to_mongo_filter(query_hash) -> dict | None:
+    """Translate a TinyDB query hash tuple to a MongoDB filter document.
+
+    Returns ``None`` when the query construct cannot be expressed as a native
+    MongoDB filter, signalling that the caller should fall back to in-memory
+    TinyDB evaluation.
+    """
+    if not isinstance(query_hash, tuple) or len(query_hash) == 0:
+        return None
+
+    op = query_hash[0]
+
+    if op in _MONGO_OP_MAP:
+        field = _field_to_mongo(query_hash[1])
+        value = query_hash[2]
+        return {field: {_MONGO_OP_MAP[op]: value}}
+
+    if op == 'exists':
+        field = _field_to_mongo(query_hash[1])
+        return {field: {'$exists': True}}
+
+    if op == 'one_of':
+        field = _field_to_mongo(query_hash[1])
+        return {field: {'$in': list(query_hash[2])}}
+
+    if op == 'any':
+        field = _field_to_mongo(query_hash[1])
+        return {field: {'$in': list(query_hash[2])}}
+
+    if op == 'all':
+        field = _field_to_mongo(query_hash[1])
+        return {field: {'$all': list(query_hash[2])}}
+
+    if op == 'matches':
+        field = _field_to_mongo(query_hash[1])
+        # TinyDB matches() anchors the regex at the start of the string.
+        return {field: {'$regex': f'^{query_hash[2]}'}}
+
+    if op == 'search':
+        field = _field_to_mongo(query_hash[1])
+        return {field: {'$regex': query_hash[2]}}
+
+    if op == 'and':
+        merged: dict = {}
+        for sub_hash in query_hash[1]:
+            sub = _hash_to_mongo_filter(sub_hash)
+            if sub is None:
+                return None
+            for field, inner in sub.items():
+                if field in merged:
+                    if isinstance(merged[field], dict) and isinstance(inner, dict):
+                        merged[field].update(inner)
+                    elif isinstance(merged[field], list) and isinstance(inner, list):
+                        merged[field].extend(inner)
+                    else:
+                        return None
+                else:
+                    merged[field] = (
+                        dict(inner) if isinstance(inner, dict)
+                        else list(inner) if isinstance(inner, list)
+                        else inner
+                    )
+        return merged
+
+    if op == 'or':
+        clauses = [_hash_to_mongo_filter(sub_hash) for sub_hash in query_hash[1]]
+        if any(c is None for c in clauses):
+            return None
+        return {'$or': sorted(clauses, key=_stable_clause_key)}
+
+    if op == 'not':
+        inner = _hash_to_mongo_filter(query_hash[1])
+        if inner is None:
+            return None
+        negated = _negate_condition(inner)
+        if negated is not None:
+            return negated
+        return None
+
+    # Unsupported operation (test, fragment, noop, etc.) -> fall back.
+    return None
+
+
+def _query_to_mongo_filter(query) -> dict | None:
+    """Translate a TinyDB QueryInstance to a MongoDB filter, if possible."""
+    if isinstance(query, dict):
+        return query
+    if isinstance(query, QueryInstance):
+        return _hash_to_mongo_filter(query._hash)
+    return None
+
+
+def _evaluate_in_memory(docs, query) -> list:
+    """Evaluate a TinyDB query against an in-memory list of documents."""
+    if callable(query):
+        return [doc for doc in docs if query(doc)]
+    return docs
+
+
+# ---------------------------------------------------------------------------
+# MongoDB-backed table wrapper
+# ---------------------------------------------------------------------------
+
+class MongoLockedTable:
+    """Drop-in replacement for ``LockedTable`` that delegates to MongoDB.
+
+    The adapter preserves the existing table API while mapping the model
+    ``id`` field to MongoDB's ``_id`` field on reads and writes.
+    """
+
+    def __init__(self, collection_name: str):
+        self.collection_name = collection_name
+
+    def _collection(self):
+        client = get_mongo_client()
+        return client[_mongo_db_name][self.collection_name]
+
+    @staticmethod
+    def _doc_to_mongo(doc: dict) -> dict:
+        """Store a copy of ``doc`` with ``id`` promoted to MongoDB ``_id``.
+
+        This avoids storing both ``_id`` and ``id`` with identical values.
+        The original ``id`` field is removed from the stored document.
+        """
+        if doc is None:
+            return None
+        d = dict(doc)
+        if 'id' in d:
+            d['_id'] = d.pop('id')
+        return d
+
+    @staticmethod
+    def _doc_from_mongo(doc: dict):
+        """Return a TinyDB-compatible Document with ``doc_id`` set to ``_id``.
+
+        Restores the model ``id`` field from MongoDB's ``_id`` and exposes
+        TinyDB's ``doc_id`` attribute so callers that rely on it continue to
+        work.
+        """
+        if doc is None:
+            return None
+        d = dict(doc)
+        doc_id = d.pop('_id', None)
+        if doc_id is not None:
+            d['id'] = doc_id
+        return Document(d, doc_id=doc_id)
+
+    def _mongo_filter(self, cond):
+        """Translate a TinyDB query or dict to a MongoDB filter."""
+        return _query_to_mongo_filter(cond)
+
+    def all(self):
+        return [self._doc_from_mongo(doc) for doc in self._collection().find({})]
+
+    def search(self, cond):
+        mongo_filter = self._mongo_filter(cond)
+        if mongo_filter is not None:
+            cursor = self._collection().find(mongo_filter)
+            return [self._doc_from_mongo(doc) for doc in cursor]
+
+        # Fallback: fetch all and evaluate the TinyDB query in Python.
+        docs = list(self._collection().find({}))
+        matched = _evaluate_in_memory(
+            [self._doc_from_mongo(doc) for doc in docs], cond
+        )
+        return matched
+
+    def get(self, cond):
+        mongo_filter = self._mongo_filter(cond)
+        if mongo_filter is not None:
+            doc = self._collection().find_one(mongo_filter)
+            return self._doc_from_mongo(doc)
+
+        docs = list(self._collection().find({}))
+        for doc in docs:
+            d = self._doc_from_mongo(doc)
+            if callable(cond) and cond(d):
+                return d
+        return None
+
+    def insert(self, document: dict):
+        doc = self._doc_to_mongo(document)
+        result = self._collection().insert_one(doc)
+        return str(result.inserted_id)
+
+    def insert_multiple(self, documents: list):
+        if not documents:
+            return []
+        docs = [self._doc_to_mongo(d) for d in documents]
+        result = self._collection().insert_many(docs)
+        return [str(iid) for iid in result.inserted_ids]
+
+    def update(self, fields, cond=None, doc_ids=None):
+        is_callable = callable(fields)
+
+        if doc_ids is not None:
+            mongo_filter = {'_id': {'$in': list(doc_ids)}}
+            target_ids = [str(did) for did in doc_ids]
+            if not target_ids:
+                return []
+
+            if is_callable:
+                # Fetch, apply callable in-memory, and replace each document.
+                updated_ids = []
+                for doc in self._collection().find(mongo_filter):
+                    d = self._doc_from_mongo(doc)
+                    fields(d)
+                    new_doc = self._doc_to_mongo(d)
+                    new_doc.pop('_id', None)
+                    self._collection().update_one(
+                        {'_id': doc['_id']}, {'$set': new_doc}
+                    )
+                    updated_ids.append(str(doc['_id']))
+                return updated_ids
+
+            update_doc = self._doc_to_mongo(fields) or {}
+            update_doc.pop('_id', None)
+            update_doc.pop('id', None)
+            if update_doc:
+                self._collection().update_many(mongo_filter, {'$set': update_doc})
+            return target_ids
+
+        mongo_filter = self._mongo_filter(cond)
+        if mongo_filter is not None and not is_callable:
+            update_doc = self._doc_to_mongo(fields) or {}
+            update_doc.pop('_id', None)
+            update_doc.pop('id', None)
+            target_ids = [
+                str(doc['_id'])
+                for doc in self._collection().find(mongo_filter, {'_id': 1})
+            ]
+            if target_ids and update_doc:
+                self._collection().update_many(
+                    mongo_filter, {'$set': update_doc}
+                )
+            return target_ids
+
+        # Fallback: evaluate the query in-memory and update one at a time.
+        docs = list(self._collection().find({}))
+        updated_ids = []
+        for doc in docs:
+            d = self._doc_from_mongo(doc)
+            match = cond(d) if callable(cond) else (mongo_filter is not None)
+            if not match:
+                continue
+            if is_callable:
+                fields(d)
+                new_doc = self._doc_to_mongo(d)
+                new_doc.pop('_id', None)
+                self._collection().update_one(
+                    {'_id': doc['_id']}, {'$set': new_doc}
+                )
+            else:
+                update_doc = self._doc_to_mongo(fields) or {}
+                update_doc.pop('_id', None)
+                update_doc.pop('id', None)
+                if update_doc:
+                    self._collection().update_one(
+                        {'_id': doc['_id']}, {'$set': update_doc}
+                    )
+            updated_ids.append(str(doc['_id']))
+        return updated_ids
+
+    def remove(self, cond):
+        mongo_filter = self._mongo_filter(cond)
+        if mongo_filter is not None:
+            target_ids = [
+                str(doc['_id'])
+                for doc in self._collection().find(mongo_filter, {'_id': 1})
+            ]
+            if target_ids:
+                self._collection().delete_many(mongo_filter)
+            return target_ids
+
+        # Fallback: evaluate the query in-memory and delete one at a time.
+        docs = list(self._collection().find({}))
+        removed_ids = []
+        for doc in docs:
+            d = self._doc_from_mongo(doc)
+            if callable(cond) and cond(d):
+                self._collection().delete_one({'_id': doc['_id']})
+                removed_ids.append(str(doc['_id']))
+        return removed_ids
+
+    def truncate(self):
+        self._collection().delete_many({})
+
+    def close(self):
+        # MongoDB clients are shared and long-lived; nothing to close here.
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Collection factory
+# ---------------------------------------------------------------------------
+
+def _make_table(json_path: str, collection_name: str):
+    if USE_MONGODB:
+        return MongoLockedTable(collection_name)
+    db = TinyDB(json_path, indent=2)
+    return LockedTable(db)
+
+
 # Setup DB files next to this module
 
 child_path = os.path.join(base_dir, 'children.json')
 task_path = os.path.join(base_dir, 'tasks.json')
+routine_path = os.path.join(base_dir, 'routines.json')
+routine_items_path = os.path.join(base_dir, 'routine_items.json')
+routine_schedules_path = os.path.join(base_dir, 'routine_schedules.json')
+routine_extensions_path = os.path.join(base_dir, 'routine_extensions.json')
 reward_path = os.path.join(base_dir, 'rewards.json')
 image_path = os.path.join(base_dir, 'images.json')
 pending_reward_path = os.path.join(base_dir, 'pending_rewards.json')
@@ -82,41 +470,123 @@ refresh_tokens_path = os.path.join(base_dir, 'refresh_tokens.json')
 push_subscriptions_path = os.path.join(base_dir, 'push_subscriptions.json')
 digest_action_tokens_path = os.path.join(base_dir, 'digest_action_tokens.json')
 
-# Use separate TinyDB instances/files for each collection
-_child_db = TinyDB(child_path, indent=2)
-_task_db = TinyDB(task_path, indent=2)
-_reward_db = TinyDB(reward_path, indent=2)
-_image_db = TinyDB(image_path, indent=2)
-_pending_rewards_db = TinyDB(pending_reward_path, indent=2)
-_pending_confirmations_db = TinyDB(pending_confirmations_path, indent=2)
-_users_db = TinyDB(users_path, indent=2)
-_tracking_events_db = TinyDB(tracking_events_path, indent=2)
-_child_overrides_db = TinyDB(child_overrides_path, indent=2)
-_chore_schedules_db = TinyDB(chore_schedules_path, indent=2)
-_task_extensions_db = TinyDB(task_extensions_path, indent=2)
-_refresh_tokens_db = TinyDB(refresh_tokens_path, indent=2)
-_push_subscriptions_db = TinyDB(push_subscriptions_path, indent=2)
-_digest_action_tokens_db = TinyDB(digest_action_tokens_path, indent=2)
+# Expose table objects backed by TinyDB or MongoDB based on USE_MONGODB
+child_db = _make_table(child_path, 'children')
+task_db = _make_table(task_path, 'tasks')
+routine_db = _make_table(routine_path, 'routines')
+routine_items_db = _make_table(routine_items_path, 'routine_items')
+routine_schedules_db = _make_table(routine_schedules_path, 'routine_schedules')
+routine_extensions_db = _make_table(routine_extensions_path, 'routine_extensions')
+reward_db = _make_table(reward_path, 'rewards')
+image_db = _make_table(image_path, 'images')
+pending_reward_db = _make_table(pending_reward_path, 'pending_rewards')
+pending_confirmations_db = _make_table(pending_confirmations_path, 'pending_confirmations')
+users_db = _make_table(users_path, 'users')
+tracking_events_db = _make_table(tracking_events_path, 'tracking_events')
+child_overrides_db = _make_table(child_overrides_path, 'child_overrides')
+chore_schedules_db = _make_table(chore_schedules_path, 'chore_schedules')
+task_extensions_db = _make_table(task_extensions_path, 'task_extensions')
+refresh_tokens_db = _make_table(refresh_tokens_path, 'refresh_tokens')
+push_subscriptions_db = _make_table(push_subscriptions_path, 'push_subscriptions')
+digest_action_tokens_db = _make_table(digest_action_tokens_path, 'digest_action_tokens')
 
-# Expose table objects wrapped with locking
-child_db = LockedTable(_child_db)
-task_db = LockedTable(_task_db)
-reward_db = LockedTable(_reward_db)
-image_db = LockedTable(_image_db)
-pending_reward_db = LockedTable(_pending_rewards_db)
-pending_confirmations_db = LockedTable(_pending_confirmations_db)
-users_db = LockedTable(_users_db)
-tracking_events_db = LockedTable(_tracking_events_db)
-child_overrides_db = LockedTable(_child_overrides_db)
-chore_schedules_db = LockedTable(_chore_schedules_db)
-task_extensions_db = LockedTable(_task_extensions_db)
-refresh_tokens_db = LockedTable(_refresh_tokens_db)
-push_subscriptions_db = LockedTable(_push_subscriptions_db)
-digest_action_tokens_db = LockedTable(_digest_action_tokens_db)
 
+# ---------------------------------------------------------------------------
+# Index management
+# ---------------------------------------------------------------------------
+
+COLLECTION_INDEXES = {
+    # NOTE: The model ``id`` field is stored as MongoDB's primary key ``_id``,
+    # so no separate unique index on ``id`` is needed.  Only secondary indexes
+    # for frequently queried fields are defined here.
+    'children': [
+        {'keys': [('user_id', ASCENDING)]},
+    ],
+    'tasks': [
+        {'keys': [('user_id', ASCENDING)]},
+    ],
+    'routines': [
+        {'keys': [('user_id', ASCENDING)]},
+    ],
+    'routine_items': [
+        {'keys': [('user_id', ASCENDING)]},
+    ],
+    'routine_schedules': [],
+    'routine_extensions': [],
+    'rewards': [
+        {'keys': [('user_id', ASCENDING)]},
+    ],
+    'images': [
+        {'keys': [('user_id', ASCENDING)]},
+    ],
+    'pending_rewards': [
+        {'keys': [('child_id', ASCENDING)]},
+    ],
+    'pending_confirmations': [
+        {'keys': [('user_id', ASCENDING)]},
+        {'keys': [('child_id', ASCENDING)]},
+        {'keys': [('entity_id', ASCENDING), ('entity_type', ASCENDING)]},
+    ],
+    'users': [],
+    'tracking_events': [
+        {'keys': [('user_id', ASCENDING)]},
+        {'keys': [('child_id', ASCENDING)]},
+        {'keys': [('entity_id', ASCENDING), ('entity_type', ASCENDING)]},
+    ],
+    'child_overrides': [
+        {'keys': [('child_id', ASCENDING)]},
+        {'keys': [('entity_id', ASCENDING), ('entity_type', ASCENDING)]},
+    ],
+    'chore_schedules': [
+        {'keys': [('user_id', ASCENDING)]},
+        {'keys': [('child_id', ASCENDING)]},
+    ],
+    'task_extensions': [
+        {'keys': [('user_id', ASCENDING)]},
+        {'keys': [('child_id', ASCENDING)]},
+    ],
+    'refresh_tokens': [
+        {'keys': [('user_id', ASCENDING)]},
+        {'keys': [('token', ASCENDING)], 'unique': True, 'sparse': True},
+    ],
+    'push_subscriptions': [
+        {'keys': [('user_id', ASCENDING)]},
+    ],
+    'digest_action_tokens': [
+        {'keys': [('user_id', ASCENDING)]},
+        {'keys': [('token', ASCENDING)], 'unique': True, 'sparse': True},
+    ],
+}
+
+
+def ensure_mongodb_indexes(client=None, db_name=None):
+    """Create required indexes on all MongoDB collections.
+
+    Safe to call repeatedly: MongoDB treats index creation as idempotent.
+    """
+    if not USE_MONGODB:
+        return
+
+    client = client or get_mongo_client()
+    db_name = db_name or _mongo_db_name
+    db = client[db_name]
+
+    for collection_name, indexes in COLLECTION_INDEXES.items():
+        coll = db[collection_name]
+        for spec in indexes:
+            keys = spec['keys']
+            kwargs = {k: v for k, v in spec.items() if k != 'keys'}
+            coll.create_index(keys, **kwargs)
+
+
+# Clear test collections at import time so tests start with a clean slate.
 if os.environ.get('DB_ENV', 'prod') == 'test':
     child_db.truncate()
     task_db.truncate()
+    routine_db.truncate()
+    routine_items_db.truncate()
+    routine_schedules_db.truncate()
+    routine_extensions_db.truncate()
     reward_db.truncate()
     image_db.truncate()
     pending_reward_db.truncate()
@@ -129,4 +599,3 @@ if os.environ.get('DB_ENV', 'prod') == 'test':
     refresh_tokens_db.truncate()
     push_subscriptions_db.truncate()
     digest_action_tokens_db.truncate()
-

backend/db/mongo_client.py

@@ -0,0 +1,113 @@
+# python
+"""Lazy MongoDB client factory and database-name helpers.
+
+The client is intentionally **not** created at module import.  Use
+``get_mongo_client()`` to obtain a cached singleton.  For Gunicorn multi-worker
+deployments call ``init_mongo_client()`` from a ``post_fork`` hook so each
+worker process owns its own connection pool rather than inheriting the parent
+process's client.
+"""
+import os
+import threading
+from urllib.parse import urlparse
+
+from pymongo import MongoClient
+from pymongo.uri_parser import parse_uri
+
+
+_mongo_client_lock = threading.Lock()
+_mongo_client = None
+
+
+def _create_mongo_client():
+    """Build a fail-fast MongoClient from environment variables."""
+    uri = os.environ.get('MONGO_URI')
+    if not uri:
+        raise RuntimeError(
+            'MONGO_URI environment variable is required when USE_MONGODB=true.'
+        )
+
+    # mongomock is used for unit/integration tests without a real server.
+    if uri.lower().startswith('mongomock') or uri.lower() == 'mongomock':
+        try:
+            import mongomock
+        except ImportError as exc:  # pragma: no cover - test dependency
+            raise RuntimeError(
+                'mongomock is required for test MongoDB mode. '
+                'Install it with: pip install mongomock'
+            ) from exc
+        return mongomock.MongoClient()
+
+    return MongoClient(
+        uri,
+        serverSelectionTimeoutMS=5000,
+        connectTimeoutMS=5000,
+        maxPoolSize=20,
+    )
+
+
+def init_mongo_client():
+    """Create a fresh MongoClient and store it as the process singleton.
+
+    Call this from a Gunicorn ``post_fork`` hook so each worker process gets
+    its own client after forking.  It can also be called in tests to reset the
+    shared client to a known state.
+    """
+    global _mongo_client
+    with _mongo_client_lock:
+        _mongo_client = _create_mongo_client()
+    return _mongo_client
+
+
+def get_mongo_client():
+    """Return the cached process-level MongoClient, creating it lazily once."""
+    global _mongo_client
+    if _mongo_client is None:
+        with _mongo_client_lock:
+            if _mongo_client is None:
+                _mongo_client = _create_mongo_client()
+    return _mongo_client
+
+
+def _db_name_from_uri(uri: str) -> str | None:
+    """Extract the database name from a MongoDB connection URI, if present."""
+    if not uri or uri.lower().startswith('mongomock'):
+        return None
+    try:
+        parsed = parse_uri(uri)
+        return parsed.get('database') or None
+    except Exception:
+        # Fallback to a simple path-based parse for non-standard URIs.
+        try:
+            path = urlparse(uri).path
+            return path.lstrip('/') or None
+        except Exception:
+            return None
+
+
+def get_mongo_db_name() -> str:
+    """Resolve the MongoDB database name from env vars or the connection URI.
+
+    Precedence:
+      1. ``MONGO_DB_NAME`` environment variable.
+      2. Database name parsed from ``MONGO_URI``.
+      3. Default based on ``DATA_ENV`` / ``DB_ENV``:
+           * prod -> ``chore_db``
+           * e2e  -> ``chore_db_e2e``
+           * test -> ``chore_db_test``
+    """
+    env_name = os.environ.get('MONGO_DB_NAME')
+    if env_name:
+        return env_name
+
+    uri = os.environ.get('MONGO_URI', '')
+    db_name = _db_name_from_uri(uri)
+    if db_name:
+        return db_name
+
+    env = (os.environ.get('DATA_ENV') or os.environ.get('DB_ENV', 'prod')).lower()
+    if env == 'prod':
+        return 'chore_db'
+    if env == 'e2e':
+        return 'chore_db_e2e'
+    return 'chore_db_test'

backend/db/routine_extensions.py

@@ -0,0 +1,41 @@
+from tinydb import Query
+from db.db import routine_extensions_db
+from models.routine_extension import RoutineExtension
+
+
+def get_extension(child_id: str, routine_id: str, date: str) -> RoutineExtension | None:
+    q = Query()
+    result = routine_extensions_db.search(
+        (q.child_id == child_id) & (q.routine_id == routine_id) & (q.date == date)
+    )
+    if not result:
+        return None
+    return RoutineExtension.from_dict(result[0])
+
+
+def add_extension(extension: RoutineExtension) -> None:
+    routine_extensions_db.insert(extension.to_dict())
+
+
+def delete_extensions_for_child(child_id: str) -> None:
+    q = Query()
+    routine_extensions_db.remove(q.child_id == child_id)
+
+
+def delete_extensions_for_routine(routine_id: str) -> None:
+    q = Query()
+    routine_extensions_db.remove(q.routine_id == routine_id)
+
+
+def delete_extension_for_child_routine(child_id: str, routine_id: str) -> None:
+    q = Query()
+    routine_extensions_db.remove((q.child_id == child_id) & (q.routine_id == routine_id))
+
+
+def get_extension_for_child_routine(child_id: str, routine_id: str) -> RoutineExtension | None:
+    q = Query()
+    results = routine_extensions_db.search((q.child_id == child_id) & (q.routine_id == routine_id))
+    if not results:
+        return None
+    latest = max(results, key=lambda r: r.get('date', ''))
+    return RoutineExtension.from_dict(latest)

backend/db/routine_items.py

@@ -0,0 +1,45 @@
+from tinydb import Query
+from db.db import routine_items_db
+from models.routine_item import RoutineItem
+
+
+def add_item(item: RoutineItem) -> None:
+    routine_items_db.insert(item.to_dict())
+
+
+def get_item(item_id: str) -> RoutineItem | None:
+    q = Query()
+    result = routine_items_db.search(q.id == item_id)
+    if not result:
+        return None
+    return RoutineItem.from_dict(result[0])
+
+
+def get_items_for_routine(routine_id: str) -> list[RoutineItem]:
+    q = Query()
+    results = routine_items_db.search(q.routine_id == routine_id)
+    items = [RoutineItem.from_dict(r) for r in results]
+    return sorted(items, key=lambda i: (i.order, i.created_at))
+
+
+def update_item(item: RoutineItem) -> bool:
+    q = Query()
+    existing = routine_items_db.get(q.id == item.id)
+    if not existing:
+        return False
+    routine_items_db.update(item.to_dict(), q.id == item.id)
+    return True
+
+
+def delete_item(item_id: str) -> bool:
+    q = Query()
+    existing = routine_items_db.get(q.id == item_id)
+    if not existing:
+        return False
+    routine_items_db.remove(q.id == item_id)
+    return True
+
+
+def delete_for_routine(routine_id: str) -> None:
+    q = Query()
+    routine_items_db.remove(q.routine_id == routine_id)

backend/db/routine_schedules.py

@@ -0,0 +1,42 @@
+from tinydb import Query
+from db.db import routine_schedules_db
+from models.routine_schedule import RoutineSchedule
+
+
+def get_schedule(child_id: str, routine_id: str) -> RoutineSchedule | None:
+    q = Query()
+    result = routine_schedules_db.search((q.child_id == child_id) & (q.routine_id == routine_id))
+    if not result:
+        return None
+    return RoutineSchedule.from_dict(result[0])
+
+
+def upsert_schedule(schedule: RoutineSchedule) -> None:
+    q = Query()
+    existing = routine_schedules_db.get((q.child_id == schedule.child_id) & (q.routine_id == schedule.routine_id))
+    if existing:
+        routine_schedules_db.update(
+            schedule.to_dict(),
+            (q.child_id == schedule.child_id) & (q.routine_id == schedule.routine_id)
+        )
+    else:
+        routine_schedules_db.insert(schedule.to_dict())
+
+
+def delete_schedule(child_id: str, routine_id: str) -> bool:
+    q = Query()
+    existing = routine_schedules_db.get((q.child_id == child_id) & (q.routine_id == routine_id))
+    if not existing:
+        return False
+    routine_schedules_db.remove((q.child_id == child_id) & (q.routine_id == routine_id))
+    return True
+
+
+def delete_schedules_for_child(child_id: str) -> None:
+    q = Query()
+    routine_schedules_db.remove(q.child_id == child_id)
+
+
+def delete_schedules_for_routine(routine_id: str) -> None:
+    q = Query()
+    routine_schedules_db.remove(q.routine_id == routine_id)

backend/db/routines.py

@@ -0,0 +1,39 @@
+from tinydb import Query
+from db.db import routine_db
+from models.routine import Routine
+
+
+def add_routine(routine: Routine) -> None:
+    routine_db.insert(routine.to_dict())
+
+
+def get_routine(routine_id: str) -> Routine | None:
+    q = Query()
+    result = routine_db.search(q.id == routine_id)
+    if not result:
+        return None
+    return Routine.from_dict(result[0])
+
+
+def update_routine(routine: Routine) -> bool:
+    q = Query()
+    existing = routine_db.get(q.id == routine.id)
+    if not existing:
+        return False
+    routine_db.update(routine.to_dict(), q.id == routine.id)
+    return True
+
+
+def delete_routine(routine_id: str) -> bool:
+    q = Query()
+    existing = routine_db.get(q.id == routine_id)
+    if not existing:
+        return False
+    routine_db.remove(q.id == routine_id)
+    return True
+
+
+def list_routines_for_user(user_id: str) -> list[Routine]:
+    q = Query()
+    results = routine_db.search((q.user_id == user_id) | (q.user_id == None))
+    return [Routine.from_dict(r) for r in results]

backend/db/tracking.py

@@ -1,4 +1,5 @@
 """Helper functions for tracking events database operations."""
+import itertools
 import logging
 from typing import Optional, List
 from tinydb import Query
@@ -8,6 +9,10 @@ from models.tracking_event import TrackingEvent, EntityType, ActionType
 
 logger = logging.getLogger(__name__)
 
+# Monotonic sequence used as a deterministic tiebreaker when tracking events
+# share the same ``occurred_at``/``created_at`` timestamps (common in tests).
+_tracking_event_seq = itertools.count()
+
 
 def insert_tracking_event(event: TrackingEvent) -> str:
     """
@@ -20,7 +25,9 @@ def insert_tracking_event(event: TrackingEvent) -> str:
         The event ID
     """
     try:
-        tracking_events_db.insert(event.to_dict())
+        event_dict = event.to_dict()
+        event_dict['_seq'] = next(_tracking_event_seq)
+        tracking_events_db.insert(event_dict)
         logger.info(f"Tracking event created: {event.action} {event.entity_type} {event.entity_id} for child {event.child_id}")
         return event.id
     except Exception as e:
@@ -61,8 +68,12 @@ def get_tracking_events_by_child(
     all_results = tracking_events_db.search(query_condition)
     total = len(all_results)
     
-    # Sort by occurred_at desc, then created_at desc
-    all_results.sort(key=lambda x: (x.get('occurred_at', ''), x.get('created_at', 0)), reverse=True)
+    # Sort by occurred_at desc, then created_at desc, then _seq desc for
+    # deterministic ordering when timestamps collide (common in fast tests).
+    all_results.sort(
+        key=lambda x: (x.get('occurred_at', ''), x.get('created_at', 0), x.get('_seq', 0)),
+        reverse=True,
+    )
 
     paginated = all_results[offset:offset + limit]
     events = [TrackingEvent.from_dict(r) for r in paginated]
@@ -99,7 +110,10 @@ def get_tracking_events_by_user(
     all_results = tracking_events_db.search(query_condition)
     total = len(all_results)
     
-    all_results.sort(key=lambda x: (x.get('occurred_at', ''), x.get('created_at', 0)), reverse=True)
+    all_results.sort(
+        key=lambda x: (x.get('occurred_at', ''), x.get('created_at', 0), x.get('_seq', 0)),
+        reverse=True,
+    )
 
     paginated = all_results[offset:offset + limit]
     events = [TrackingEvent.from_dict(r) for r in paginated]

backend/events/types/child_routine_confirmation.py

@@ -0,0 +1,15 @@
+from events.types.payload import Payload
+
+
+class ChildRoutineConfirmation(Payload):
+    OPERATION_PENDING = "PENDING"
+    OPERATION_APPROVED = "APPROVED"
+    OPERATION_REJECTED = "REJECTED"
+    OPERATION_RESET = "RESET"
+
+    def __init__(self, child_id: str, routine_id: str, operation: str):
+        super().__init__({
+            'child_id': child_id,
+            'routine_id': routine_id,
+            'operation': operation
+        })

backend/events/types/child_routines_set.py

@@ -0,0 +1,9 @@
+from events.types.payload import Payload
+
+
+class ChildRoutinesSet(Payload):
+    def __init__(self, child_id: str, routine_ids: list[str]):
+        super().__init__({
+            'child_id': child_id,
+            'routine_ids': routine_ids
+        })

backend/events/types/event_types.py

@@ -28,4 +28,10 @@ class EventType(Enum):
     CHORE_TIME_EXTENDED = "chore_time_extended"
     CHILD_CHORE_CONFIRMATION = "child_chore_confirmation"
 
+    ROUTINE_MODIFIED = "routine_modified"
+    CHILD_ROUTINES_SET = "child_routines_set"
+    ROUTINE_SCHEDULE_MODIFIED = "routine_schedule_modified"
+    ROUTINE_TIME_EXTENDED = "routine_time_extended"
+    CHILD_ROUTINE_CONFIRMATION = "child_routine_confirmation"
+
     FORCE_LOGOUT = "force_logout"

backend/events/types/routine_modified.py

@@ -0,0 +1,13 @@
+from events.types.payload import Payload
+
+
+class RoutineModified(Payload):
+    OPERATION_ADD = "ADD"
+    OPERATION_EDIT = "EDIT"
+    OPERATION_DELETE = "DELETE"
+
+    def __init__(self, routine_id: str, operation: str):
+        super().__init__({
+            'routine_id': routine_id,
+            'operation': operation
+        })

backend/events/types/routine_schedule_modified.py

@@ -0,0 +1,13 @@
+from events.types.payload import Payload
+
+
+class RoutineScheduleModified(Payload):
+    OPERATION_SET = 'SET'
+    OPERATION_DELETED = 'DELETED'
+
+    def __init__(self, child_id: str, routine_id: str, operation: str):
+        super().__init__({
+            'child_id': child_id,
+            'routine_id': routine_id,
+            'operation': operation,
+        })

backend/events/types/routine_time_extended.py

@@ -0,0 +1,9 @@
+from events.types.payload import Payload
+
+
+class RoutineTimeExtended(Payload):
+    def __init__(self, child_id: str, routine_id: str):
+        super().__init__({
+            'child_id': child_id,
+            'routine_id': routine_id,
+        })

backend/gunicorn.conf.py

@@ -0,0 +1,17 @@
+"""Gunicorn configuration for the chore/reward Flask backend.
+
+This file is automatically loaded by Gunicorn when it is started from the
+backend directory.  It ensures each worker process creates its own MongoDB
+client after forking, avoiding shared socket/file-descriptor issues.
+"""
+
+
+def post_fork(server, worker):
+    """Reinitialize the MongoDB client in each worker process after forking."""
+    try:
+        from db.mongo_client import init_mongo_client
+        init_mongo_client()
+    except Exception:
+        # If MongoDB is not configured (USE_MONGODB=false), there is no client
+        # to initialize; ignore the error silently.
+        pass

backend/main.py

@@ -2,6 +2,7 @@ import logging
 import sys
 import os
 
+from dotenv import load_dotenv
 from flask import Flask, request, jsonify
 
 from api.admin_api import admin_api
@@ -14,6 +15,10 @@ from api.image_api import image_api
 from api.kindness_api import kindness_api
 from api.penalty_api import penalty_api
 from api.reward_api import reward_api
+from api.routine_api import routine_api
+from api.routine_item_api import routine_item_api
+from api.child_routine_api import child_routine_api
+from api.routine_schedule_api import routine_schedule_api
 from api.task_api import task_api
 from api.tracking_api import tracking_api
 from api.user_api import user_api
@@ -22,6 +27,7 @@ from api.digest_action_api import digest_action_api
 from config.version import get_full_version
 
 from db.default import initializeImages, createDefaultTasks, createDefaultRewards
+from db.db import ensure_mongodb_indexes
 from events.broadcaster import Broadcaster
 from events.sse import sse_response_for_user, send_to_user
 from api.utils import get_current_user_id
@@ -30,6 +36,13 @@ from utils.chore_expiry_notification_scheduler import start_chore_expiry_notific
 from utils.digest_scheduler import start_digest_scheduler
 from utils.state_expiry_scheduler import start_state_expiry_scheduler
 
+
+# Load environment variables
+load_dotenv()
+
+# Ensure MongoDB indexes exist when running against MongoDB.
+ensure_mongodb_indexes()
+
 # Configure logging once at application startup
 logging.basicConfig(
     level=logging.INFO,
@@ -54,6 +67,10 @@ app.register_blueprint(chore_schedule_api)
 app.register_blueprint(kindness_api)
 app.register_blueprint(penalty_api)
 app.register_blueprint(reward_api)
+app.register_blueprint(routine_api)
+app.register_blueprint(routine_item_api)
+app.register_blueprint(child_routine_api)
+app.register_blueprint(routine_schedule_api)
 app.register_blueprint(task_api)
 app.register_blueprint(image_api)
 app.register_blueprint(auth_api, url_prefix='/auth')
@@ -135,7 +152,6 @@ def start_background_threads():
     broadcaster.daemon = True
     broadcaster.start()
 
-# TODO: implement users
 initializeImages()
 createDefaultTasks()
 createDefaultRewards()

backend/models/child.py

@@ -6,6 +6,7 @@ class Child(BaseModel):
     name: str
     age: int | None = None
     tasks: list[str] = field(default_factory=list)
+    routines: list[str] = field(default_factory=list)
     rewards: list[str] = field(default_factory=list)
     points: int = 0
     image_id: str | None = None
@@ -17,6 +18,7 @@ class Child(BaseModel):
             name=d.get('name'),
             age=d.get('age'),
             tasks=d.get('tasks', []),
+            routines=d.get('routines', []),
             rewards=d.get('rewards', []),
             points=d.get('points', 0),
             image_id=d.get('image_id'),
@@ -32,6 +34,7 @@ class Child(BaseModel):
             'name': self.name,
             'age': self.age,
             'tasks': self.tasks,
+            'routines': self.routines,
             'rewards': self.rewards,
             'points': self.points,
             'image_id': self.image_id,

backend/models/child_override.py

@@ -16,15 +16,15 @@ class ChildOverride(BaseModel):
     """
     child_id: str
     entity_id: str
-    entity_type: Literal['task', 'reward', 'chore', 'kindness', 'penalty']
+    entity_type: Literal['task', 'reward', 'chore', 'kindness', 'penalty', 'routine']
     custom_value: int
 
     def __post_init__(self):
         """Validate custom_value range and entity_type."""
         if self.custom_value < 0 or self.custom_value > 10000:
             raise ValueError("custom_value must be between 0 and 10000")
-        if self.entity_type not in ['task', 'reward', 'chore', 'kindness', 'penalty']:
-            raise ValueError("entity_type must be 'task', 'reward', 'chore', 'kindness', or 'penalty'")
+        if self.entity_type not in ['task', 'reward', 'chore', 'kindness', 'penalty', 'routine']:
+            raise ValueError("entity_type must be 'task', 'reward', 'chore', 'kindness', 'penalty', or 'routine'")
 
     @classmethod
     def from_dict(cls, d: dict):
@@ -52,7 +52,7 @@ class ChildOverride(BaseModel):
     def create_override(
         child_id: str,
         entity_id: str,
-        entity_type: Literal['task', 'reward', 'chore', 'kindness', 'penalty'],
+        entity_type: Literal['task', 'reward', 'chore', 'kindness', 'penalty', 'routine'],
         custom_value: int
     ) -> 'ChildOverride':
         """Factory method to create a new override."""

backend/models/pending_confirmation.py

@@ -3,7 +3,7 @@ from typing import Literal, Optional
 from models.base import BaseModel
 
 
-PendingEntityType = Literal['chore', 'reward']
+PendingEntityType = Literal['chore', 'reward', 'routine']
 PendingStatus = Literal['pending', 'approved', 'rejected']
 
 

backend/models/refresh_token.py

@@ -9,6 +9,7 @@ class RefreshToken(BaseModel):
     token_family: str = ''
     expires_at: str = ''
     is_used: bool = False
+    rotated_at: str | None = None
 
     def to_dict(self):
         return {
@@ -18,6 +19,7 @@ class RefreshToken(BaseModel):
             'token_family': self.token_family,
             'expires_at': self.expires_at,
             'is_used': self.is_used,
+            'rotated_at': self.rotated_at,
         }
 
     @staticmethod
@@ -31,4 +33,5 @@ class RefreshToken(BaseModel):
             token_family=data.get('token_family', ''),
             expires_at=data.get('expires_at', ''),
             is_used=data.get('is_used', False),
+            rotated_at=data.get('rotated_at'),
         )

backend/models/routine.py

@@ -0,0 +1,32 @@
+from dataclasses import dataclass
+from models.base import BaseModel
+
+
+@dataclass
+class Routine(BaseModel):
+    name: str
+    points: int
+    image_id: str | None = None
+    user_id: str | None = None
+
+    @classmethod
+    def from_dict(cls, d: dict):
+        return cls(
+            name=d.get('name'),
+            points=d.get('points', 0),
+            image_id=d.get('image_id'),
+            user_id=d.get('user_id'),
+            id=d.get('id'),
+            created_at=d.get('created_at'),
+            updated_at=d.get('updated_at')
+        )
+
+    def to_dict(self):
+        base = super().to_dict()
+        base.update({
+            'name': self.name,
+            'points': self.points,
+            'image_id': self.image_id,
+            'user_id': self.user_id
+        })
+        return base

backend/models/routine_extension.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+from models.base import BaseModel
+
+
+@dataclass
+class RoutineExtension(BaseModel):
+    child_id: str
+    routine_id: str
+    date: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> 'RoutineExtension':
+        return cls(
+            child_id=d.get('child_id'),
+            routine_id=d.get('routine_id'),
+            date=d.get('date'),
+            id=d.get('id'),
+            created_at=d.get('created_at'),
+            updated_at=d.get('updated_at'),
+        )
+
+    def to_dict(self) -> dict:
+        base = super().to_dict()
+        base.update({
+            'child_id': self.child_id,
+            'routine_id': self.routine_id,
+            'date': self.date,
+        })
+        return base

backend/models/routine_item.py

@@ -0,0 +1,32 @@
+from dataclasses import dataclass
+from models.base import BaseModel
+
+
+@dataclass
+class RoutineItem(BaseModel):
+    routine_id: str
+    name: str
+    image_id: str | None = None
+    order: int = 0
+
+    @classmethod
+    def from_dict(cls, d: dict):
+        return cls(
+            routine_id=d.get('routine_id'),
+            name=d.get('name'),
+            image_id=d.get('image_id'),
+            order=d.get('order', 0),
+            id=d.get('id'),
+            created_at=d.get('created_at'),
+            updated_at=d.get('updated_at')
+        )
+
+    def to_dict(self):
+        base = super().to_dict()
+        base.update({
+            'routine_id': self.routine_id,
+            'name': self.name,
+            'image_id': self.image_id,
+            'order': self.order
+        })
+        return base

backend/models/routine_schedule.py

@@ -0,0 +1,63 @@
+from dataclasses import dataclass, field
+from typing import Literal
+from models.base import BaseModel
+
+
+@dataclass
+class RoutineSchedule(BaseModel):
+    child_id: str
+    routine_id: str
+    mode: Literal['days', 'interval']
+
+    day_configs: list = field(default_factory=list)
+    default_hour: int = 8
+    default_minute: int = 0
+    default_has_deadline: bool = True
+
+    interval_days: int = 2
+    anchor_date: str = ""
+    interval_has_deadline: bool = True
+    interval_hour: int = 0
+    interval_minute: int = 0
+
+    enabled: bool = True
+
+    @classmethod
+    def from_dict(cls, d: dict) -> 'RoutineSchedule':
+        return cls(
+            child_id=d.get('child_id'),
+            routine_id=d.get('routine_id'),
+            mode=d.get('mode', 'days'),
+            day_configs=d.get('day_configs', []),
+            default_hour=d.get('default_hour', 8),
+            default_minute=d.get('default_minute', 0),
+            default_has_deadline=d.get('default_has_deadline', True),
+            interval_days=d.get('interval_days', 2),
+            anchor_date=d.get('anchor_date', ''),
+            interval_has_deadline=d.get('interval_has_deadline', True),
+            interval_hour=d.get('interval_hour', 0),
+            interval_minute=d.get('interval_minute', 0),
+            enabled=d.get('enabled', True),
+            id=d.get('id'),
+            created_at=d.get('created_at'),
+            updated_at=d.get('updated_at'),
+        )
+
+    def to_dict(self) -> dict:
+        base = super().to_dict()
+        base.update({
+            'child_id': self.child_id,
+            'routine_id': self.routine_id,
+            'mode': self.mode,
+            'day_configs': self.day_configs,
+            'default_hour': self.default_hour,
+            'default_minute': self.default_minute,
+            'default_has_deadline': self.default_has_deadline,
+            'interval_days': self.interval_days,
+            'anchor_date': self.anchor_date,
+            'interval_has_deadline': self.interval_has_deadline,
+            'interval_hour': self.interval_hour,
+            'interval_minute': self.interval_minute,
+            'enabled': self.enabled,
+        })
+        return base

backend/models/user.py

@@ -25,6 +25,8 @@ class User(BaseModel):
     timezone: str | None = None
     email_digest_enabled: bool = True
     push_notifications_enabled: bool = True
+    tutorial_enabled: bool = True
+    tutorial_progress: dict = field(default_factory=dict)
 
     @classmethod
     def from_dict(cls, d: dict):
@@ -51,6 +53,8 @@ class User(BaseModel):
             timezone=d.get('timezone'),
             email_digest_enabled=d.get('email_digest_enabled', True),
             push_notifications_enabled=d.get('push_notifications_enabled', True),
+            tutorial_enabled=d.get('tutorial_enabled', True),
+            tutorial_progress=d.get('tutorial_progress', {}) or {},
             id=d.get('id'),
             created_at=d.get('created_at'),
             updated_at=d.get('updated_at')
@@ -82,5 +86,7 @@ class User(BaseModel):
             'timezone': self.timezone,
             'email_digest_enabled': self.email_digest_enabled,
             'push_notifications_enabled': self.push_notifications_enabled,
+            'tutorial_enabled': self.tutorial_enabled,
+            'tutorial_progress': self.tutorial_progress,
         })
         return base

backend/scripts/migrate_to_mongodb.py

@@ -0,0 +1,203 @@
+# python
+"""
+Migrate existing TinyDB JSON files into MongoDB.
+
+Usage:
+    cd backend
+    python -m scripts.migrate_to_mongodb [--dry-run]
+
+The script reads files from ``data/db/`` (or ``test_data/db/`` when
+``DB_ENV=test``), maps each record's ``id`` field to MongoDB's ``_id`` field,
+and inserts the records idempotently.  TinyDB files are backed up to
+``<db_dir>/backups/<timestamp>/`` before the first migration run.
+"""
+import argparse
+import json
+import os
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from config.paths import get_database_dir
+from db.db import COLLECTION_INDEXES, ensure_mongodb_indexes
+from db.mongo_client import get_mongo_client, get_mongo_db_name
+
+
+# Map TinyDB JSON filenames to MongoDB collection names.
+COLLECTION_FILE_MAP = {
+    'children.json': 'children',
+    'tasks.json': 'tasks',
+    'routines.json': 'routines',
+    'routine_items.json': 'routine_items',
+    'routine_schedules.json': 'routine_schedules',
+    'routine_extensions.json': 'routine_extensions',
+    'rewards.json': 'rewards',
+    'images.json': 'images',
+    'pending_rewards.json': 'pending_rewards',
+    'pending_confirmations.json': 'pending_confirmations',
+    'users.json': 'users',
+    'tracking_events.json': 'tracking_events',
+    'child_overrides.json': 'child_overrides',
+    'chore_schedules.json': 'chore_schedules',
+    'task_extensions.json': 'task_extensions',
+    'refresh_tokens.json': 'refresh_tokens',
+    'push_subscriptions.json': 'push_subscriptions',
+    'digest_action_tokens.json': 'digest_action_tokens',
+}
+
+
+def _load_tinydb_records(path: str) -> list[dict]:
+    """Load all records from a TinyDB JSON file."""
+    with open(path, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+    default_table = data.get('_default', {})
+    return list(default_table.values())
+
+
+def _doc_to_mongo(doc: dict) -> dict:
+    """Map the model ``id`` field to MongoDB's ``_id`` field.
+
+    The original ``id`` field is removed so documents do not store both
+    ``_id`` and ``id`` with identical values.
+    """
+    mongo_doc = dict(doc)
+    if 'id' in mongo_doc:
+        mongo_doc['_id'] = mongo_doc.pop('id')
+    return mongo_doc
+
+
+def migrate(dry_run: bool = False) -> dict:
+    """Migrate TinyDB files to MongoDB and return a per-collection summary."""
+    db_dir = get_database_dir()
+    if not os.path.isdir(db_dir):
+        raise FileNotFoundError(f'Database directory does not exist: {db_dir}')
+
+    client = get_mongo_client()
+    db_name = get_mongo_db_name()
+    db = client[db_name]
+
+    timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
+    backup_dir = os.path.join(db_dir, 'backups', timestamp)
+
+    if not dry_run:
+        os.makedirs(backup_dir, exist_ok=True)
+        ensure_mongodb_indexes(client=client, db_name=db_name)
+
+    summary: dict[str, dict] = {}
+
+    for filename, collection_name in COLLECTION_FILE_MAP.items():
+        path = os.path.join(db_dir, filename)
+        if not os.path.exists(path):
+            summary[collection_name] = {
+                'source_file': filename,
+                'total': 0,
+                'migrated': 0,
+                'skipped': 0,
+                'status': 'missing',
+            }
+            continue
+
+        records = _load_tinydb_records(path)
+
+        if not dry_run:
+            shutil.copy2(path, backup_dir)
+
+        collection = db[collection_name]
+        to_insert: list[dict] = []
+        skipped = 0
+
+        for record in records:
+            doc_id = record.get('id')
+            if not doc_id:
+                skipped += 1
+                continue
+
+            if not dry_run:
+                existing = collection.find_one({'_id': doc_id})
+                if existing:
+                    skipped += 1
+                    continue
+
+            to_insert.append(_doc_to_mongo(record))
+
+        if not dry_run and to_insert:
+            try:
+                collection.insert_many(to_insert, ordered=False)
+            except Exception as exc:  # pragma: no cover - defensive
+                print(
+                    f'  Warning: error inserting into {collection_name}: {exc}',
+                    file=sys.stderr,
+                )
+                raise
+
+        summary[collection_name] = {
+            'source_file': filename,
+            'total': len(records),
+            'migrated': len(to_insert),
+            'skipped': skipped,
+            'status': 'migrated' if not dry_run else 'dry-run',
+        }
+
+    return summary
+
+
+def _print_summary(summary: dict) -> None:
+    """Print a human-readable migration summary."""
+    print('\nMigration Summary')
+    print('-' * 70)
+    print(f'{"Collection":<30}{"Total":>8}{"Migrated":>10}{"Skipped":>10}{"Status":>10}')
+    print('-' * 70)
+    total_records = 0
+    total_migrated = 0
+    total_skipped = 0
+    for collection_name, info in summary.items():
+        print(
+            f'{collection_name:<30}'
+            f'{info["total"]:>8}'
+            f'{info["migrated"]:>10}'
+            f'{info["skipped"]:>10}'
+            f'{info["status"]:>10}'
+        )
+        total_records += info['total']
+        total_migrated += info['migrated']
+        total_skipped += info['skipped']
+    print('-' * 70)
+    print(
+        f'{"TOTAL":<30}'
+        f'{total_records:>8}'
+        f'{total_migrated:>10}'
+        f'{total_skipped:>10}'
+    )
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Migrate TinyDB JSON files to MongoDB.'
+    )
+    parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Analyze files and report counts without writing to MongoDB.',
+    )
+    args = parser.parse_args()
+
+    if os.environ.get('USE_MONGODB', 'true').lower() != 'true':
+        print('Set USE_MONGODB=true to run the migration.', file=sys.stderr)
+        sys.exit(1)
+
+    if not os.environ.get('MONGO_URI'):
+        print('MONGO_URI is required when USE_MONGODB=true.', file=sys.stderr)
+        sys.exit(1)
+
+    if args.dry_run:
+        print('Dry run: no data will be written to MongoDB.')
+
+    summary = migrate(dry_run=args.dry_run)
+    _print_summary(summary)
+
+
+if __name__ == '__main__':
+    main()

backend/scripts/run_integration_tests.ps1

@@ -0,0 +1,79 @@
+<#
+.SYNOPSIS
+    Run the MongoDB adapter integration tests against a local Docker MongoDB container.
+
+.DESCRIPTION
+    Starts a temporary MongoDB container, runs a targeted pytest suite with
+    USE_MONGODB=true, then stops and removes the container.
+
+.EXAMPLE
+    cd backend
+    .\scripts\run_integration_tests.ps1
+#>
+[CmdletBinding()]
+param(
+    [string]$ContainerName = 'chore-db-integration-test',
+    [int]$HostPort = 27017,
+    [string]$Image = 'mongo:8',
+    [string]$DbName = 'chore_db_test',
+    [string]$TestPath = 'tests/test_mongo_adapter.py'
+)
+
+$ErrorActionPreference = 'Stop'
+
+$mongoUri = "mongodb://localhost:${HostPort}/${DbName}"
+
+function Test-ContainerRunning {
+    $containers = docker ps --filter "name=$ContainerName" --format '{{.Names}}' 2>$null
+    return $containers -contains $ContainerName
+}
+
+function Wait-MongoReady {
+    param([int]$TimeoutSeconds = 30)
+    $start = Get-Date
+    while (((Get-Date) - $start).TotalSeconds -lt $TimeoutSeconds) {
+        try {
+            $null = docker exec $ContainerName mongosh --eval 'db.adminCommand({ ping: 1 })' --quiet 2>$null
+            if ($LASTEXITCODE -eq 0) {
+                return
+            }
+        } catch {
+            # Container or mongosh may not be ready yet.
+        }
+        Start-Sleep -Seconds 1
+    }
+    throw "MongoDB container did not become ready within ${TimeoutSeconds} seconds."
+}
+
+# Clean up any leftover container from a previous aborted run.
+if (Test-ContainerRunning) {
+    Write-Host "Removing existing container '$ContainerName'..."
+    docker rm -f $ContainerName | Out-Null
+}
+
+Write-Host "Starting MongoDB container '$ContainerName' on port $HostPort..."
+docker run -d `
+    --name $ContainerName `
+    -p "${HostPort}:27017" `
+    $Image | Out-Null
+
+try {
+    Wait-MongoReady
+    Write-Host "MongoDB is ready. Running integration tests..."
+
+    $env:USE_MONGODB = 'true'
+    $env:MONGO_URI = $mongoUri
+    $env:MONGO_DB_NAME = $DbName
+    $env:DB_ENV = 'test'
+    $env:DATA_ENV = 'test'
+
+    pytest $TestPath
+    if ($LASTEXITCODE -ne 0) {
+        throw "Integration tests failed with exit code $LASTEXITCODE."
+    }
+} finally {
+    Write-Host "Stopping and removing container '$ContainerName'..."
+    docker rm -f $ContainerName | Out-Null
+}
+
+Write-Host "Integration tests complete."

backend/tests/conftest.py

@@ -1,5 +1,7 @@
 import os
 os.environ['DB_ENV'] = 'test'
+os.environ['USE_MONGODB'] = 'true'
+os.environ['MONGO_URI'] = 'mongomock'
 os.environ.setdefault('SECRET_KEY', 'test-secret-key')
 os.environ.setdefault('REFRESH_TOKEN_EXPIRY_DAYS', '90')
 os.environ.setdefault('DIGEST_TOKEN_SECRET', 'test-digest-secret')
@@ -18,5 +20,11 @@ TEST_REFRESH_TOKEN_EXPIRY_DAYS = 90
 @pytest.fixture(scope="session", autouse=True)
 def set_test_db_env():
     os.environ['DB_ENV'] = 'test'
+    os.environ['USE_MONGODB'] = 'true'
+    os.environ['MONGO_URI'] = 'mongomock'
     os.environ['SECRET_KEY'] = TEST_SECRET_KEY
     os.environ['REFRESH_TOKEN_EXPIRY_DAYS'] = str(TEST_REFRESH_TOKEN_EXPIRY_DAYS)
+    # Ensure indexes are created once for the test session.  This is safe to
+    # call repeatedly because MongoDB treats index creation as idempotent.
+    from db.db import ensure_mongodb_indexes
+    ensure_mongodb_indexes()

backend/tests/test_auth_api.py

@@ -1,11 +1,11 @@
 import pytest
 from werkzeug.security import generate_password_hash, check_password_hash
 from flask import Flask
-from api.auth_api import auth_api
+from api.auth_api import auth_api, _hash_token
 from db.db import users_db, refresh_tokens_db
 from tinydb import Query
 from models.user import User
-from datetime import datetime
+from datetime import datetime, timedelta, timezone
 from tests.conftest import TEST_SECRET_KEY, TEST_REFRESH_TOKEN_EXPIRY_DAYS
 
 @pytest.fixture
@@ -189,3 +189,244 @@ def test_migration_script_hashes_plain_text_passwords():
     # Check user2 password unchanged
     user2_dict = users_db.get(Query().email == 'test2@example.com')
     assert user2_dict['password'] == already_hashed
+
+
+def _extract_cookie_value(response, cookie_name):
+    """Extract a raw cookie value from a response's Set-Cookie headers."""
+    for cookie in response.headers.getlist('Set-Cookie'):
+        if cookie.startswith(f'{cookie_name}='):
+            return cookie.split(f'{cookie_name}=', 1)[1].split(';', 1)[0]
+    return None
+
+
+def _create_verified_user(email, password):
+    """Insert a verified user with the given credentials."""
+    users_db.remove(Query().email == email)
+    user = User(
+        first_name='Test',
+        last_name='User',
+        email=email,
+        password=generate_password_hash(password),
+        verified=True,
+    )
+    users_db.insert(user.to_dict())
+    return user
+
+
+def _set_refresh_cookie(client, raw_token):
+    """
+    Set the refresh token cookie on a test client so it is sent to /auth/refresh.
+    Production uses path='/api/auth' because the frontend calls /api/auth/refresh,
+    but the test fixture exposes the blueprint at /auth/refresh directly.
+    """
+    client.set_cookie('refresh_token', raw_token, path='/')
+
+
+def test_refresh_rotates_token(client):
+    """A successful refresh marks the old token used and issues a new one in the same family."""
+    email = 'refresh-rotate@test.com'
+    password = 'password123'
+    _create_verified_user(email, password)
+
+    login_response = client.post('/auth/login', json={'email': email, 'password': password})
+    assert login_response.status_code == 200
+    old_refresh = _extract_cookie_value(login_response, 'refresh_token')
+    assert old_refresh
+
+    _set_refresh_cookie(client, old_refresh)
+    refresh_response = client.post('/auth/refresh')
+    assert refresh_response.status_code == 200
+    new_refresh = _extract_cookie_value(refresh_response, 'refresh_token')
+    assert new_refresh
+    assert new_refresh != old_refresh
+
+    user_dict = users_db.get(Query().email == email)
+    old_hash = _hash_token(old_refresh)
+    new_hash = _hash_token(new_refresh)
+
+    old_record = refresh_tokens_db.get(Query().token_hash == old_hash)
+    assert old_record is not None
+    assert old_record['is_used'] is True
+    assert old_record['rotated_at'] is not None
+
+    new_record = refresh_tokens_db.get(Query().token_hash == new_hash)
+    assert new_record is not None
+    assert new_record['is_used'] is False
+    assert new_record['token_family'] == old_record['token_family']
+
+
+def test_refresh_reuse_only_invalidates_family(client):
+    """Replay of a used refresh token only kills its own family, not other devices."""
+    email = 'refresh-family@test.com'
+    password = 'password123'
+    user = _create_verified_user(email, password)
+
+    # Device A logs in
+    client_a = client
+    login_a = client_a.post('/auth/login', json={'email': email, 'password': password})
+    assert login_a.status_code == 200
+    refresh_a = _extract_cookie_value(login_a, 'refresh_token')
+
+    # Device B logs in (separate client = separate cookie jar)
+    app = client_a.application
+    client_b = app.test_client()
+    login_b = client_b.post('/auth/login', json={'email': email, 'password': password})
+    assert login_b.status_code == 200
+    refresh_b = _extract_cookie_value(login_b, 'refresh_token')
+
+    assert refresh_a != refresh_b
+
+    # Device A refreshes normally
+    _set_refresh_cookie(client_a, refresh_a)
+    refresh_a_response = client_a.post('/auth/refresh')
+    assert refresh_a_response.status_code == 200
+
+    # Capture families before any purge so we can assert afterwards.
+    family_a = refresh_tokens_db.get(Query().token_hash == _hash_token(refresh_a))['token_family']
+    family_b = refresh_tokens_db.get(Query().token_hash == _hash_token(refresh_b))['token_family']
+    assert family_a != family_b
+
+    # Backdate rotation so the replay is past the grace period and treated as theft.
+    old_hash_a = _hash_token(refresh_a)
+    backdated = (datetime.now(timezone.utc) - timedelta(seconds=60)).isoformat()
+    refresh_tokens_db.update({'rotated_at': backdated}, Query().token_hash == old_hash_a)
+
+    # Attacker replays device A's old token
+    _set_refresh_cookie(client_a, refresh_a)
+    reuse_response = client_a.post('/auth/refresh')
+    assert reuse_response.status_code == 401
+    assert reuse_response.json['code'] == 'REFRESH_TOKEN_REUSE'
+
+    # Device B's refresh token should still be valid
+    _set_refresh_cookie(client_b, refresh_b)
+    refresh_b_response = client_b.post('/auth/refresh')
+    assert refresh_b_response.status_code == 200
+
+    # Only family A should be purged; family B should remain
+    remaining = refresh_tokens_db.search(Query().user_id == user.id)
+    remaining_families = {t['token_family'] for t in remaining}
+    assert family_a not in remaining_families
+    assert family_b in remaining_families
+
+
+def test_refresh_reuse_within_grace_period_is_tolerated(client):
+    """A replay within the grace period is treated as a race condition, not theft."""
+    email = 'refresh-race@test.com'
+    password = 'password123'
+    _create_verified_user(email, password)
+
+    login_response = client.post('/auth/login', json={'email': email, 'password': password})
+    assert login_response.status_code == 200
+    refresh_token = _extract_cookie_value(login_response, 'refresh_token')
+
+    # First refresh marks the token as used
+    _set_refresh_cookie(client, refresh_token)
+    first_refresh = client.post('/auth/refresh')
+    assert first_refresh.status_code == 200
+
+    # Immediate replay (same legitimate client racing) should succeed
+    _set_refresh_cookie(client, refresh_token)
+    race_response = client.post('/auth/refresh')
+    assert race_response.status_code == 200
+
+    # The family should still be valid
+    user_dict = users_db.get(Query().email == email)
+    family = refresh_tokens_db.get(Query().token_hash == _hash_token(refresh_token))['token_family']
+    family_tokens = refresh_tokens_db.search(
+        (Query().user_id == user_dict['id']) & (Query().token_family == family)
+    )
+    assert len(family_tokens) >= 1
+    assert any(t['is_used'] is False for t in family_tokens)
+
+
+def test_refresh_reuse_after_grace_period_invalidates_family(client):
+    """A replay after the grace period is treated as theft and kills only that family."""
+    email = 'refresh-theft@test.com'
+    password = 'password123'
+    user = _create_verified_user(email, password)
+
+    login_response = client.post('/auth/login', json={'email': email, 'password': password})
+    assert login_response.status_code == 200
+    refresh_token = _extract_cookie_value(login_response, 'refresh_token')
+
+    # Refresh once, then backdate the rotation timestamp past the grace period
+    _set_refresh_cookie(client, refresh_token)
+    client.post('/auth/refresh')
+
+    old_hash = _hash_token(refresh_token)
+    old_record = refresh_tokens_db.get(Query().token_hash == old_hash)
+    old_family = old_record['token_family']
+    backdated = (datetime.now(timezone.utc) - timedelta(seconds=60)).isoformat()
+    refresh_tokens_db.update({'rotated_at': backdated}, Query().token_hash == old_hash)
+
+    # Replay now should be detected as theft
+    _set_refresh_cookie(client, refresh_token)
+    reuse_response = client.post('/auth/refresh')
+    assert reuse_response.status_code == 401
+    assert reuse_response.json['code'] == 'REFRESH_TOKEN_REUSE'
+
+    remaining = refresh_tokens_db.search(Query().user_id == user.id)
+    remaining_families = {t['token_family'] for t in remaining}
+    assert old_family not in remaining_families
+
+
+def test_refresh_reuse_without_rotated_at_invalidates_family(client):
+    """Legacy used tokens without rotated_at are treated as theft, not race conditions."""
+    email = 'refresh-legacy@test.com'
+    password = 'password123'
+    user = _create_verified_user(email, password)
+
+    login_response = client.post('/auth/login', json={'email': email, 'password': password})
+    assert login_response.status_code == 200
+    refresh_token = _extract_cookie_value(login_response, 'refresh_token')
+
+    # Rotate the token, then strip rotated_at to simulate pre-migration data
+    _set_refresh_cookie(client, refresh_token)
+    client.post('/auth/refresh')
+    old_hash = _hash_token(refresh_token)
+    refresh_tokens_db.update({'rotated_at': None}, Query().token_hash == old_hash)
+
+    old_record = refresh_tokens_db.get(Query().token_hash == old_hash)
+    old_family = old_record['token_family']
+
+    # Replay should be treated as theft because rotated_at is missing
+    _set_refresh_cookie(client, refresh_token)
+    reuse_response = client.post('/auth/refresh')
+    assert reuse_response.status_code == 401
+    assert reuse_response.json['code'] == 'REFRESH_TOKEN_REUSE'
+
+    remaining = refresh_tokens_db.search(Query().user_id == user.id)
+    remaining_families = {t['token_family'] for t in remaining}
+    assert old_family not in remaining_families
+
+
+def test_refresh_reuse_with_zero_grace_period(client):
+    """A grace period of 0 means any replay of a used token is treated as theft."""
+    email = 'refresh-zero-grace@test.com'
+    password = 'password123'
+    user = _create_verified_user(email, password)
+
+    # Configure the app with a 0-second grace period
+    client.application.config['REFRESH_TOKEN_REUSE_GRACE_PERIOD_SECONDS'] = 0
+
+    login_response = client.post('/auth/login', json={'email': email, 'password': password})
+    assert login_response.status_code == 200
+    refresh_token = _extract_cookie_value(login_response, 'refresh_token')
+
+    # Rotate the token; rotated_at is within the normal default grace period
+    _set_refresh_cookie(client, refresh_token)
+    client.post('/auth/refresh')
+
+    old_hash = _hash_token(refresh_token)
+    old_record = refresh_tokens_db.get(Query().token_hash == old_hash)
+    old_family = old_record['token_family']
+
+    # Immediate replay should still be theft with a 0-second grace period
+    _set_refresh_cookie(client, refresh_token)
+    reuse_response = client.post('/auth/refresh')
+    assert reuse_response.status_code == 401
+    assert reuse_response.json['code'] == 'REFRESH_TOKEN_REUSE'
+
+    remaining = refresh_tokens_db.search(Query().user_id == user.id)
+    remaining_families = {t['token_family'] for t in remaining}
+    assert old_family not in remaining_families

backend/tests/test_child_api.py

@@ -4,13 +4,14 @@ import os
 
 from flask import Flask
 from api.child_api import child_api
+import api.child_api as child_api_module
 from api.auth_api import auth_api
 from db.db import child_db, reward_db, task_db, users_db, chore_schedules_db, task_extensions_db, pending_confirmations_db
 from tinydb import Query
 from models.child import Child
 import jwt
 from werkzeug.security import generate_password_hash
-from datetime import date as date_type
+from datetime import date as date_type, datetime, timedelta, timezone
 
 
 # Test user credentials
@@ -382,6 +383,7 @@ def _setup_sched_child_and_tasks(task_db, child_db):
     })
     chore_schedules_db.remove(Query().child_id == CHILD_SCHED_ID)
     task_extensions_db.remove(Query().child_id == CHILD_SCHED_ID)
+    pending_confirmations_db.remove(Query().child_id == CHILD_SCHED_ID)
 
 
 def test_list_child_tasks_always_has_schedule_and_extension_date_keys(client):
@@ -517,6 +519,146 @@ def test_list_child_tasks_no_server_side_filtering(client):
     assert extra_id in returned_ids
 
 
+def test_list_child_tasks_shows_pending_for_today(client):
+    """A chore confirmed today should return pending_status='pending'."""
+    _setup_sched_child_and_tasks(task_db, child_db)
+    now_ts = datetime.now(timezone.utc).timestamp()
+    pending_confirmations_db.insert({
+        'id': 'pend_today_chore',
+        'child_id': CHILD_SCHED_ID,
+        'entity_id': TASK_GOOD_ID,
+        'entity_type': 'chore',
+        'user_id': 'testuserid',
+        'status': 'pending',
+        'approved_at': None,
+        'created_at': now_ts,
+        'updated_at': now_ts,
+    })
+
+    resp = client.get(f'/child/{CHILD_SCHED_ID}/list-tasks')
+    assert resp.status_code == 200
+    tasks = {t['id']: t for t in resp.get_json()['tasks']}
+    assert tasks[TASK_GOOD_ID]['pending_status'] == 'pending'
+    assert tasks[TASK_GOOD_ID]['approved_at'] is None
+
+
+def test_list_child_tasks_clears_stale_approved_and_pending(client):
+    """Yesterday's chore pending/approved records should be reset and ignored."""
+    _setup_sched_child_and_tasks(task_db, child_db)
+    old_ts = (datetime.now(timezone.utc) - timedelta(days=2)).timestamp()
+    old_approved = (datetime.now(timezone.utc) - timedelta(days=2)).isoformat()
+
+    pending_confirmations_db.insert({
+        'id': 'pend_old_chore_pending',
+        'child_id': CHILD_SCHED_ID,
+        'entity_id': TASK_GOOD_ID,
+        'entity_type': 'chore',
+        'user_id': 'testuserid',
+        'status': 'pending',
+        'approved_at': None,
+        'created_at': old_ts,
+        'updated_at': old_ts,
+    })
+
+    resp = client.get(f'/child/{CHILD_SCHED_ID}/list-tasks')
+    assert resp.status_code == 200
+    tasks = {t['id']: t for t in resp.get_json()['tasks']}
+    assert tasks[TASK_GOOD_ID]['pending_status'] is None
+    assert tasks[TASK_GOOD_ID]['approved_at'] is None
+
+    # Reinsert as stale approved and ensure it is also cleared.
+    pending_confirmations_db.insert({
+        'id': 'pend_old_chore_approved',
+        'child_id': CHILD_SCHED_ID,
+        'entity_id': TASK_GOOD_ID,
+        'entity_type': 'chore',
+        'user_id': 'testuserid',
+        'status': 'approved',
+        'approved_at': old_approved,
+        'created_at': old_ts,
+        'updated_at': old_ts,
+    })
+
+    resp2 = client.get(f'/child/{CHILD_SCHED_ID}/list-tasks')
+    assert resp2.status_code == 200
+    tasks2 = {t['id']: t for t in resp2.get_json()['tasks']}
+    assert tasks2[TASK_GOOD_ID]['pending_status'] is None
+    assert tasks2[TASK_GOOD_ID]['approved_at'] is None
+
+
+def test_list_child_tasks_local_day_keeps_approved_across_utc_rollover(client, monkeypatch):
+    """Approved chore should remain completed when UTC date differs but user-local day matches.
+
+    Example: 2026-05-11T22:30:00Z is 2026-05-12 local day in Pacific/Kiritimati (UTC+14).
+    """
+    _setup_sched_child_and_tasks(task_db, child_db)
+
+    # Force deterministic local-day basis for this endpoint call.
+    monkeypatch.setattr(
+        child_api_module,
+        '_get_user_today_local',
+        lambda user_id: ('2026-05-12', 'Pacific/Kiritimati'),
+    )
+
+    pending_confirmations_db.insert({
+        'id': 'pend_local_day_approved',
+        'child_id': CHILD_SCHED_ID,
+        'entity_id': TASK_GOOD_ID,
+        'entity_type': 'chore',
+        'user_id': 'testuserid',
+        'status': 'approved',
+        'approved_at': '2026-05-11T22:30:00+00:00',
+        'created_at': 1778538600,
+        'updated_at': 1778538600,
+    })
+
+    resp = client.get(f'/child/{CHILD_SCHED_ID}/list-tasks')
+    assert resp.status_code == 200
+    tasks = {t['id']: t for t in resp.get_json()['tasks']}
+    assert tasks[TASK_GOOD_ID]['pending_status'] == 'approved'
+    assert tasks[TASK_GOOD_ID]['approved_at'] == '2026-05-11T22:30:00+00:00'
+
+
+def test_confirm_chore_allows_when_previous_pending_is_stale(client):
+    """A stale pending chore record from a prior day must not block confirm-chore."""
+    old_ts = (datetime.now(timezone.utc) - timedelta(days=2)).timestamp()
+    task_db.insert({'id': 't_stale_chore', 'name': 'Stale Chore', 'points': 2, 'type': 'chore', 'user_id': 'testuserid'})
+    child_db.insert({
+        'id': 'child_stale_chore',
+        'name': 'Stale Chore Kid',
+        'age': 8,
+        'points': 0,
+        'tasks': ['t_stale_chore'],
+        'rewards': [],
+        'user_id': 'testuserid',
+    })
+    pending_confirmations_db.insert({
+        'id': 'pend_stale_chore',
+        'child_id': 'child_stale_chore',
+        'entity_id': 't_stale_chore',
+        'entity_type': 'chore',
+        'user_id': 'testuserid',
+        'status': 'pending',
+        'approved_at': None,
+        'created_at': old_ts,
+        'updated_at': old_ts,
+    })
+
+    resp = client.post('/child/child_stale_chore/confirm-chore', json={'task_id': 't_stale_chore'})
+    assert resp.status_code == 200
+
+    active_pending = pending_confirmations_db.search(
+        (Query().child_id == 'child_stale_chore') & (Query().entity_id == 't_stale_chore') &
+        (Query().entity_type == 'chore') & (Query().status == 'pending')
+    )
+    assert len(active_pending) == 1
+    assert active_pending[0].get('id') != 'pend_stale_chore'
+
+    pending_confirmations_db.remove(Query().child_id == 'child_stale_chore')
+    child_db.remove(Query().id == 'child_stale_chore')
+    task_db.remove(Query().id == 't_stale_chore')
+
+
 # ---------------------------------------------------------------------------
 # request-reward: duplicate guard
 # ---------------------------------------------------------------------------
@@ -547,6 +689,82 @@ def test_request_reward_duplicate_returns_409(client):
     reward_db.remove(Query().id == 'r_dup')
 
 
+def test_request_reward_allows_new_when_stale_pending_exists(client):
+    """A stale pending reward from a prior day must not block a new request."""
+    old_ts = (datetime.now(timezone.utc) - timedelta(days=2)).timestamp()
+    reward_db.insert({'id': 'r_stale', 'name': 'Stale Reward', 'cost': 5, 'user_id': 'testuserid'})
+    child_db.insert({
+        'id': 'child_stale',
+        'name': 'Stale Kid',
+        'age': 8,
+        'points': 20,
+        'tasks': [],
+        'rewards': ['r_stale'],
+        'user_id': 'testuserid',
+    })
+    pending_confirmations_db.insert({
+        'id': 'pend_stale_reward',
+        'child_id': 'child_stale',
+        'entity_id': 'r_stale',
+        'entity_type': 'reward',
+        'user_id': 'testuserid',
+        'status': 'pending',
+        'approved_at': None,
+        'created_at': old_ts,
+        'updated_at': old_ts,
+    })
+
+    resp = client.post('/child/child_stale/request-reward', json={'reward_id': 'r_stale'})
+    assert resp.status_code == 200
+
+    active_pending = pending_confirmations_db.search(
+        (Query().child_id == 'child_stale') & (Query().entity_id == 'r_stale') &
+        (Query().entity_type == 'reward') & (Query().status == 'pending')
+    )
+    assert len(active_pending) == 1
+    assert active_pending[0].get('id') != 'pend_stale_reward'
+
+    pending_confirmations_db.remove(Query().child_id == 'child_stale')
+    child_db.remove(Query().id == 'child_stale')
+    reward_db.remove(Query().id == 'r_stale')
+
+
+def test_reward_status_ignores_stale_pending_reward(client):
+    """reward-status should not mark a reward as redeeming if pending is stale."""
+    old_ts = (datetime.now(timezone.utc) - timedelta(days=2)).timestamp()
+    reward_db.insert({'id': 'r_status_stale', 'name': 'Status Reward', 'cost': 4, 'user_id': 'testuserid'})
+    child_db.insert({
+        'id': 'child_status_stale',
+        'name': 'Status Kid',
+        'age': 9,
+        'points': 10,
+        'tasks': [],
+        'rewards': ['r_status_stale'],
+        'user_id': 'testuserid',
+    })
+    pending_confirmations_db.insert({
+        'id': 'pend_status_stale',
+        'child_id': 'child_status_stale',
+        'entity_id': 'r_status_stale',
+        'entity_type': 'reward',
+        'user_id': 'testuserid',
+        'status': 'pending',
+        'approved_at': None,
+        'created_at': old_ts,
+        'updated_at': old_ts,
+    })
+
+    resp = client.get('/child/child_status_stale/reward-status')
+    assert resp.status_code == 200
+    statuses = {s['id']: s for s in resp.get_json()['reward_status']}
+    assert statuses['r_status_stale']['redeeming'] is False
+    assert pending_confirmations_db.get(Query().id == 'pend_status_stale') is None
+
+    pending_confirmations_db.remove(Query().child_id == 'child_status_stale')
+    child_db.remove(Query().id == 'child_status_stale')
+    reward_db.remove(Query().id == 'r_status_stale')
+
+
 # ---------------------------------------------------------------------------
 # deny-reward-request endpoint
 # ---------------------------------------------------------------------------

backend/tests/test_chore_confirmation.py

@@ -3,6 +3,7 @@ from tests.conftest import TEST_SECRET_KEY, TEST_REFRESH_TOKEN_EXPIRY_DAYS
 import os
 from werkzeug.security import generate_password_hash
 from datetime import date as date_type
+import api.child_api as child_api_module
 
 from flask import Flask
 from api.child_api import child_api
@@ -71,6 +72,24 @@ def setup_child_and_chore(child_name='TestChild', age=8, chore_points=10):
     return child['id'], 'chore1'
 
 
+def test_local_day_iso_check_handles_utc_rollover():
+    # 22:30 UTC on 2026-05-11 is 12:30 local on 2026-05-12 in Pacific/Kiritimati (UTC+14).
+    assert child_api_module._is_iso_timestamp_on_local_day(
+        '2026-05-11T22:30:00+00:00',
+        '2026-05-12',
+        'Pacific/Kiritimati',
+    )
+
+
+def test_local_day_epoch_check_handles_utc_rollover():
+    # Same instant as above represented as epoch seconds.
+    assert child_api_module._is_epoch_timestamp_on_local_day(
+        1778538600,
+        '2026-05-12',
+        'Pacific/Kiritimati',
+    )
+
+
 # ---------------------------------------------------------------------------
 # Child Confirm Flow
 # ---------------------------------------------------------------------------

backend/tests/test_mongo_adapter.py

@@ -0,0 +1,201 @@
+import os
+import pytest
+from tinydb import Query
+
+from db.db import (
+    MongoLockedTable,
+    _query_to_mongo_filter,
+    child_db,
+    task_db,
+    users_db,
+    refresh_tokens_db,
+)
+from db.mongo_client import get_mongo_client, get_mongo_db_name
+
+
+# All tests in this module require the mongomock-backed MongoDB adapter.
+pytestmark = pytest.mark.skipif(
+    os.environ.get('USE_MONGODB', 'true').lower() != 'true',
+    reason='MongoDB adapter tests require USE_MONGODB=true',
+)
+
+
+@pytest.fixture(autouse=True)
+def clean_mongo_collections():
+    """Truncate relevant collections before each test."""
+    child_db.truncate()
+    task_db.truncate()
+    users_db.truncate()
+    refresh_tokens_db.truncate()
+    yield
+
+
+class TestQueryTranslation:
+    """Unit tests for TinyDB Query -> MongoDB filter translation."""
+
+    def test_simple_equality(self):
+        q = Query()
+        assert _query_to_mongo_filter(q.id == 'abc') == {'_id': {'$eq': 'abc'}}
+
+    def test_field_other_than_id(self):
+        q = Query()
+        assert _query_to_mongo_filter(q.user_id == 'u1') == {
+            'user_id': {'$eq': 'u1'}
+        }
+
+    def test_and_query(self):
+        q = Query()
+        mongo_filter = _query_to_mongo_filter(
+            (q.id == 'abc') & (q.user_id == 'u1')
+        )
+        assert mongo_filter == {'_id': {'$eq': 'abc'}, 'user_id': {'$eq': 'u1'}}
+
+    def test_or_query(self):
+        q = Query()
+        mongo_filter = _query_to_mongo_filter(
+            (q.user_id == 'u1') | (q.user_id == None)  # noqa: E711
+        )
+        assert mongo_filter == {
+            '$or': [
+                {'user_id': {'$eq': 'u1'}},
+                {'user_id': {'$eq': None}},
+            ]
+        }
+
+    def test_and_with_nested_or(self):
+        q = Query()
+        mongo_filter = _query_to_mongo_filter(
+            (q.id == 'abc') & ((q.user_id == 'u1') | (q.user_id == None))  # noqa: E711
+        )
+        assert mongo_filter == {
+            '_id': {'$eq': 'abc'},
+            '$or': [
+                {'user_id': {'$eq': 'u1'}},
+                {'user_id': {'$eq': None}},
+            ],
+        }
+
+
+class TestMongoCrud:
+    """CRUD tests against the mongomock-backed MongoLockedTable."""
+
+    def test_insert_maps_id_to_underscore_id(self):
+        child_db.insert({'id': 'c1', 'name': 'Alice', 'age': 8})
+
+        raw = get_mongo_client()[get_mongo_db_name()]['children'].find_one(
+            {'_id': 'c1'}
+        )
+        assert raw is not None
+        assert raw['_id'] == 'c1'
+        assert 'id' not in raw
+        assert raw['name'] == 'Alice'
+
+    def test_get_returns_document_without_underscore_id(self):
+        child_db.insert({'id': 'c1', 'name': 'Alice', 'age': 8})
+
+        doc = child_db.get(Query().id == 'c1')
+        assert doc is not None
+        assert doc['id'] == 'c1'
+        assert doc['name'] == 'Alice'
+        assert '_id' not in doc
+
+    def test_get_none_when_missing(self):
+        assert child_db.get(Query().id == 'missing') is None
+
+    def test_search_with_query(self):
+        child_db.insert({'id': 'c1', 'name': 'Alice', 'user_id': 'u1'})
+        child_db.insert({'id': 'c2', 'name': 'Bob', 'user_id': 'u1'})
+        child_db.insert({'id': 'c3', 'name': 'Carol', 'user_id': 'u2'})
+
+        results = child_db.search(Query().user_id == 'u1')
+        assert len(results) == 2
+        assert {r['id'] for r in results} == {'c1', 'c2'}
+
+    def test_search_with_or(self):
+        task_db.insert({'id': 't1', 'name': 'Default', 'user_id': None})
+        task_db.insert({'id': 't2', 'name': 'User task', 'user_id': 'u1'})
+
+        q = Query()
+        results = task_db.search((q.user_id == 'u1') | (q.user_id == None))  # noqa: E711
+        assert len(results) == 2
+
+    def test_update_modifies_matching_documents(self):
+        child_db.insert({'id': 'c1', 'name': 'Alice', 'points': 0})
+        child_db.insert({'id': 'c2', 'name': 'Bob', 'points': 0})
+
+        modified = child_db.update({'points': 10}, Query().id == 'c1')
+        # TinyDB returns a list of updated document ids; the adapter mirrors that.
+        assert modified == ['c1']
+
+        doc = child_db.get(Query().id == 'c1')
+        assert doc['points'] == 10
+
+        other = child_db.get(Query().id == 'c2')
+        assert other['points'] == 0
+
+    def test_update_does_not_overwrite_id(self):
+        child_db.insert({'id': 'c1', 'name': 'Alice'})
+
+        child_db.update({'id': 'c2', 'name': 'Alice Smith'}, Query().id == 'c1')
+        # The id field must remain unchanged; update should have stripped id.
+        assert child_db.get(Query().id == 'c1')['name'] == 'Alice Smith'
+        assert child_db.get(Query().id == 'c2') is None
+
+    def test_remove_deletes_matching_documents(self):
+        child_db.insert({'id': 'c1', 'name': 'Alice'})
+        child_db.insert({'id': 'c2', 'name': 'Bob'})
+
+        deleted = child_db.remove(Query().id == 'c1')
+        # TinyDB returns a list of removed document ids; the adapter mirrors that.
+        assert deleted == ['c1']
+
+        assert child_db.get(Query().id == 'c1') is None
+        assert child_db.get(Query().id == 'c2') is not None
+
+    def test_all_returns_all_documents(self):
+        child_db.insert({'id': 'c1', 'name': 'Alice'})
+        child_db.insert({'id': 'c2', 'name': 'Bob'})
+
+        docs = child_db.all()
+        assert len(docs) == 2
+        assert all('_id' not in d for d in docs)
+
+    def test_truncate_removes_all_documents(self):
+        child_db.insert({'id': 'c1', 'name': 'Alice'})
+        child_db.truncate()
+        assert child_db.all() == []
+
+    def test_insert_multiple(self):
+        ids = child_db.insert_multiple([
+            {'id': 'c1', 'name': 'Alice'},
+            {'id': 'c2', 'name': 'Bob'},
+        ])
+        assert sorted(ids) == ['c1', 'c2']
+        assert len(child_db.all()) == 2
+
+    def test_unique_token_index(self):
+        refresh_tokens_db.insert({'id': 'r1', 'token': 'abc', 'user_id': 'u1'})
+        refresh_tokens_db.insert({'id': 'r2', 'token': 'def', 'user_id': 'u1'})
+
+        # mongomock does not enforce unique indexes by default, but we verify
+        # both records are readable.
+        assert refresh_tokens_db.get(Query().token == 'abc') is not None
+        assert refresh_tokens_db.get(Query().token == 'def') is not None
+
+    def test_user_id_secondary_index_is_created(self):
+        # Insert and query via the secondary index path used by the app.
+        users_db.insert({'id': 'u1', 'email': 'a@example.com', 'verified': True})
+        users_db.insert({'id': 'u2', 'email': 'b@example.com', 'verified': False})
+
+        found = users_db.search(Query().verified == True)  # noqa: E712
+        assert len(found) == 1
+        assert found[0]['id'] == 'u1'
+
+
+class TestAdapterApi:
+    """Tests that the adapter exposes the expected LockedTable-compatible API."""
+
+    def test_close_is_noop(self):
+        # Existing cleanup fixtures call ``*_db.close()``; ensure it does not
+        # raise for the MongoDB-backed adapter.
+        child_db.close()

backend/tests/test_routine_api.py

@@ -0,0 +1,296 @@
+"""Unit tests for routine API endpoints."""
+
+import pytest
+from datetime import datetime, timezone
+from tinydb import Query
+from models.routine import Routine
+from models.routine_item import RoutineItem
+from models.routine_schedule import RoutineSchedule
+from models.routine_extension import RoutineExtension
+from models.pending_confirmation import PendingConfirmation
+from api.error_codes import ErrorCodes
+from db.db import routine_db, routine_items_db, routine_schedules_db, routine_extensions_db, pending_confirmations_db
+
+
+class TestRoutineModel:
+    """Test Routine model serialization and validation."""
+
+    def test_routine_creation(self):
+        """Test creating a routine instance."""
+        routine = Routine(name="Morning Routine", points=50, image_id="img123", user_id="user1")
+        assert routine.name == "Morning Routine"
+        assert routine.points == 50
+        assert routine.image_id == "img123"
+        assert routine.user_id == "user1"
+        assert routine.id is not None
+
+    def test_routine_to_dict(self):
+        """Test routine serialization."""
+        routine = Routine(name="Test", points=10, image_id=None, user_id="user1")
+        data = routine.to_dict()
+        assert data["name"] == "Test"
+        assert data["points"] == 10
+        assert data["id"] == routine.id
+
+    def test_routine_from_dict(self):
+        """Test routine deserialization."""
+        routine_dict = {"id": "r1", "name": "Test", "points": 20, "image_id": "img1", "user_id": "u1"}
+        routine = Routine.from_dict(routine_dict)
+        assert routine.id == "r1"
+        assert routine.name == "Test"
+        assert routine.points == 20
+
+
+class TestRoutineItemModel:
+    """Test RoutineItem model."""
+
+    def test_routine_item_creation(self):
+        """Test creating a routine item."""
+        item = RoutineItem(routine_id="r1", name="Make Bed", image_id=None, order=0)
+        assert item.routine_id == "r1"
+        assert item.name == "Make Bed"
+        assert item.order == 0
+
+    def test_routine_item_to_dict(self):
+        """Test item serialization."""
+        item = RoutineItem(routine_id="r1", name="Get Dressed", image_id="img1", order=1)
+        data = item.to_dict()
+        assert data["routine_id"] == "r1"
+        assert data["name"] == "Get Dressed"
+        assert data["order"] == 1
+
+
+class TestRoutineScheduleModel:
+    """Test RoutineSchedule model."""
+
+    def test_days_mode_schedule_creation(self):
+        """Test creating days mode schedule."""
+        day_configs = [
+            {"day": 0, "hour": 8, "minute": 0},
+            {"day": 1, "hour": 9, "minute": 30},
+        ]
+        schedule = RoutineSchedule(
+            child_id="c1",
+            routine_id="r1",
+            mode="days",
+            enabled=True,
+            day_configs=day_configs,
+            default_hour=8,
+            default_minute=0,
+            default_has_deadline=True,
+        )
+        assert schedule.mode == "days"
+        assert len(schedule.day_configs) == 2
+        assert schedule.enabled is True
+
+    def test_interval_mode_schedule_creation(self):
+        """Test creating interval mode schedule."""
+        schedule = RoutineSchedule(
+            child_id="c1",
+            routine_id="r1",
+            mode="interval",
+            enabled=True,
+            interval_days=3,
+            anchor_date="2026-05-01",
+            interval_has_deadline=True,
+            interval_hour=10,
+            interval_minute=30,
+        )
+        assert schedule.mode == "interval"
+        assert schedule.interval_days == 3
+        assert schedule.interval_hour == 10
+
+
+class TestRoutineExtensionModel:
+    """Test RoutineExtension model."""
+
+    def test_extension_creation(self):
+        """Test creating a routine extension."""
+        extension = RoutineExtension(child_id="c1", routine_id="r1", date="2026-05-10")
+        assert extension.child_id == "c1"
+        assert extension.routine_id == "r1"
+        assert extension.date == "2026-05-10"
+
+
+class TestRoutineDB:
+    """Test routine database operations."""
+
+    def setup_method(self):
+        """Clear routine db before each test."""
+        routine_db.truncate()
+
+    def test_add_routine(self):
+        """Test adding a routine to database."""
+        routine = Routine(name="Test Routine", points=50, image_id=None, user_id="user1")
+        routine_db.insert(routine.to_dict())
+        
+        result = routine_db.search(Query().id == routine.id)
+        assert len(result) == 1
+        assert result[0]["name"] == "Test Routine"
+
+    def test_get_routine_by_id(self):
+        """Test fetching routine by ID."""
+        routine = Routine(name="Fetch Test", points=30, image_id=None, user_id="user1")
+        routine_db.insert(routine.to_dict())
+        
+        result = routine_db.get(Query().id == routine.id)
+        assert result is not None
+        assert result["name"] == "Fetch Test"
+
+    def test_list_user_routines(self):
+        """Test listing routines for a user."""
+        r1 = Routine(name="R1", points=10, image_id=None, user_id="user1")
+        r2 = Routine(name="R2", points=20, image_id=None, user_id="user1")
+        r3 = Routine(name="R3", points=15, image_id=None, user_id="user2")
+        
+        routine_db.insert(r1.to_dict())
+        routine_db.insert(r2.to_dict())
+        routine_db.insert(r3.to_dict())
+        
+        results = routine_db.search(Query().user_id == "user1")
+        assert len(results) == 2
+
+    def test_update_routine(self):
+        """Test updating a routine."""
+        routine = Routine(name="Original", points=50, image_id=None, user_id="user1")
+        routine_db.insert(routine.to_dict())
+        
+        routine_db.update({"name": "Updated", "points": 100}, Query().id == routine.id)
+        result = routine_db.get(Query().id == routine.id)
+        assert result["name"] == "Updated"
+        assert result["points"] == 100
+
+
+class TestRoutineItemDB:
+    """Test routine item database operations."""
+
+    def setup_method(self):
+        """Clear item db before each test."""
+        routine_items_db.truncate()
+
+    def test_add_routine_item(self):
+        """Test adding a routine item."""
+        item = RoutineItem(routine_id="r1", name="Make Bed", image_id=None, order=0)
+        routine_items_db.insert(item.to_dict())
+        
+        result = routine_items_db.search(Query().routine_id == "r1")
+        assert len(result) == 1
+        assert result[0]["name"] == "Make Bed"
+
+    def test_get_items_for_routine(self):
+        """Test fetching all items for a routine."""
+        i1 = RoutineItem(routine_id="r1", name="Item1", image_id=None, order=0)
+        i2 = RoutineItem(routine_id="r1", name="Item2", image_id=None, order=1)
+        i3 = RoutineItem(routine_id="r2", name="Item3", image_id=None, order=0)
+        
+        routine_items_db.insert(i1.to_dict())
+        routine_items_db.insert(i2.to_dict())
+        routine_items_db.insert(i3.to_dict())
+        
+        results = routine_items_db.search(Query().routine_id == "r1")
+        assert len(results) == 2
+
+    def test_delete_item(self):
+        """Test deleting a routine item."""
+        item = RoutineItem(routine_id="r1", name="Test", image_id=None, order=0)
+        routine_items_db.insert(item.to_dict())
+        
+        routine_items_db.remove(Query().id == item.id)
+        result = routine_items_db.search(Query().id == item.id)
+        assert len(result) == 0
+
+
+class TestRoutineScheduleDB:
+    """Test routine schedule database operations."""
+
+    def setup_method(self):
+        """Clear schedule db before each test."""
+        routine_schedules_db.truncate()
+
+    def test_upsert_schedule(self):
+        """Test upserting a routine schedule."""
+        day_configs = [{"day": 0, "hour": 8, "minute": 0}]
+        schedule = RoutineSchedule(
+            child_id="c1",
+            routine_id="r1",
+            mode="days",
+            enabled=True,
+            day_configs=day_configs,
+            default_hour=8,
+            default_minute=0,
+            default_has_deadline=True,
+        )
+        routine_schedules_db.insert(schedule.to_dict())
+        
+        result = routine_schedules_db.get(
+            (Query().child_id == "c1") & (Query().routine_id == "r1")
+        )
+        assert result is not None
+        assert result["mode"] == "days"
+
+    def test_delete_schedule(self):
+        """Test deleting a schedule."""
+        schedule = RoutineSchedule(
+            child_id="c1",
+            routine_id="r1",
+            mode="interval",
+            enabled=True,
+            interval_days=2,
+            anchor_date="2026-05-01",
+            interval_has_deadline=True,
+            interval_hour=10,
+            interval_minute=0,
+        )
+        routine_schedules_db.insert(schedule.to_dict())
+        
+        routine_schedules_db.remove(
+            (Query().child_id == "c1") & (Query().routine_id == "r1")
+        )
+        result = routine_schedules_db.search(Query().child_id == "c1")
+        assert len(result) == 0
+
+
+class TestPendingRoutineConfirmation:
+    """Test pending routine confirmation workflow."""
+
+    def setup_method(self):
+        """Clear db before each test."""
+        pending_confirmations_db.truncate()
+
+    def test_create_routine_confirmation(self):
+        """Test creating a pending routine confirmation."""
+        confirmation = PendingConfirmation(
+            child_id="c1",
+            entity_id="r1",
+            entity_type="routine",
+            user_id="u1",
+            status="pending",
+        )
+        pending_confirmations_db.insert(confirmation.to_dict())
+        
+        result = pending_confirmations_db.get(
+            (Query().child_id == "c1") & (Query().entity_id == "r1") & (Query().entity_type == "routine")
+        )
+        assert result is not None
+        assert result["status"] == "pending"
+
+    def test_approve_routine_confirmation(self):
+        """Test approving a routine confirmation."""
+        confirmation = PendingConfirmation(
+            child_id="c1",
+            entity_id="r1",
+            entity_type="routine",
+            user_id="u1",
+            status="pending",
+        )
+        pending_confirmations_db.insert(confirmation.to_dict())
+        
+        today_utc = datetime.now(timezone.utc).isoformat()
+        pending_confirmations_db.update(
+            {"status": "approved", "approved_at": today_utc},
+            Query().id == confirmation.id,
+        )
+        
+        result = pending_confirmations_db.get(Query().id == confirmation.id)
+        assert result["status"] == "approved"
+        assert result["approved_at"] is not None

backend/tests/test_routine_feature_api.py

@@ -0,0 +1,187 @@
+from flask import Flask
+from tinydb import Query
+from werkzeug.security import generate_password_hash
+
+from tests.conftest import TEST_SECRET_KEY, TEST_REFRESH_TOKEN_EXPIRY_DAYS
+from api.auth_api import auth_api
+from api.routine_api import routine_api
+from api.routine_item_api import routine_item_api
+from api.child_routine_api import child_routine_api
+from api.routine_schedule_api import routine_schedule_api
+from db.db import (
+    users_db,
+    child_db,
+    routine_db,
+    routine_items_db,
+    routine_schedules_db,
+    routine_extensions_db,
+    pending_confirmations_db,
+)
+
+
+TEST_USER_ID = 'routine-user-1'
+TEST_EMAIL = 'routine-user@example.com'
+TEST_PASSWORD = 'testpass'
+
+
+def add_test_user():
+    users_db.remove(Query().email == TEST_EMAIL)
+    users_db.insert({
+        'id': TEST_USER_ID,
+        'first_name': 'Routine',
+        'last_name': 'Tester',
+        'email': TEST_EMAIL,
+        'password': generate_password_hash(TEST_PASSWORD),
+        'verified': True,
+        'image_id': 'boy01',
+    })
+
+
+def login_and_set_cookie(client):
+    resp = client.post('/auth/login', json={'email': TEST_EMAIL, 'password': TEST_PASSWORD})
+    assert resp.status_code == 200
+
+
+def seed_child(child_id: str):
+    child_db.remove(Query().id == child_id)
+    child_db.insert({
+        'id': child_id,
+        'name': 'Routine Kid',
+        'age': 9,
+        'tasks': [],
+        'routines': [],
+        'rewards': [],
+        'points': 0,
+        'image_id': 'boy01',
+        'user_id': TEST_USER_ID,
+    })
+
+
+def _first_routine_id():
+    routines = routine_db.all()
+    assert routines
+    return routines[0]['id']
+
+
+def _first_confirmation_id():
+    confirmations = pending_confirmations_db.all()
+    assert confirmations
+    return confirmations[0]['id']
+
+
+def _make_client():
+    app = Flask(__name__)
+    app.register_blueprint(auth_api, url_prefix='/auth')
+    app.register_blueprint(routine_api)
+    app.register_blueprint(routine_item_api)
+    app.register_blueprint(child_routine_api)
+    app.register_blueprint(routine_schedule_api)
+    app.config['TESTING'] = True
+    app.config['SECRET_KEY'] = TEST_SECRET_KEY
+    app.config['REFRESH_TOKEN_EXPIRY_DAYS'] = TEST_REFRESH_TOKEN_EXPIRY_DAYS
+    return app
+
+
+def setup_function(_):
+    routine_db.truncate()
+    routine_items_db.truncate()
+    routine_schedules_db.truncate()
+    routine_extensions_db.truncate()
+    pending_confirmations_db.truncate()
+    child_db.truncate()
+
+
+def test_routine_crud_flow():
+    app = _make_client()
+    with app.test_client() as client:
+        add_test_user()
+        login_and_set_cookie(client)
+
+        add_resp = client.put('/routine/add', json={'name': 'Morning Routine', 'points': 8, 'image_id': 'sun'})
+        assert add_resp.status_code == 201
+
+        rid = _first_routine_id()
+
+        list_resp = client.get('/routine/list')
+        assert list_resp.status_code == 200
+        routines = list_resp.get_json()['routines']
+        assert len(routines) == 1
+        assert routines[0]['name'] == 'Morning Routine'
+
+        edit_resp = client.put(f'/routine/{rid}/edit', json={'points': 10})
+        assert edit_resp.status_code == 200
+        assert edit_resp.get_json()['points'] == 10
+
+        delete_resp = client.delete(f'/routine/{rid}')
+        assert delete_resp.status_code == 200
+        assert routine_db.all() == []
+
+
+def test_child_routine_assignment_confirmation_and_approval():
+    app = _make_client()
+    with app.test_client() as client:
+        add_test_user()
+        login_and_set_cookie(client)
+
+        seed_child('routine-child-1')
+        client.put('/routine/add', json={'name': 'Evening Routine', 'points': 6, 'image_id': 'moon'})
+        rid = _first_routine_id()
+
+        add_item_resp = client.put(f'/routine/{rid}/item/add', json={'name': 'Brush Teeth', 'order': 0})
+        assert add_item_resp.status_code == 201
+
+        assign_resp = client.post('/child/routine-child-1/assign-routine', json={'routine_id': rid})
+        assert assign_resp.status_code == 200
+
+        list_resp = client.get('/child/routine-child-1/list-routines')
+        assert list_resp.status_code == 200
+        routines = list_resp.get_json()['routines']
+        assert len(routines) == 1
+        assert routines[0]['id'] == rid
+        assert routines[0]['items'][0]['name'] == 'Brush Teeth'
+
+        confirm_resp = client.post('/child/routine-child-1/confirm-routine', json={'routine_id': rid})
+        assert confirm_resp.status_code == 200
+
+        confirmation_id = _first_confirmation_id()
+        approve_resp = client.post(f'/child/routine-child-1/approve-routine/{confirmation_id}')
+        assert approve_resp.status_code == 200
+
+        child = child_db.get(Query().id == 'routine-child-1')
+        assert child['points'] == 6
+
+
+def test_routine_schedule_and_extend_flow():
+    app = _make_client()
+    with app.test_client() as client:
+        add_test_user()
+        login_and_set_cookie(client)
+
+        seed_child('routine-child-2')
+        client.put('/routine/add', json={'name': 'School Routine', 'points': 5, 'image_id': 'book'})
+        rid = _first_routine_id()
+
+        client.post('/child/routine-child-2/assign-routine', json={'routine_id': rid})
+
+        set_resp = client.put(
+            f'/child/routine-child-2/routine/{rid}/schedule',
+            json={
+                'mode': 'days',
+                'day_configs': [{'day': 1, 'hour': 8, 'minute': 0}],
+                'default_hour': 8,
+                'default_minute': 0,
+                'default_has_deadline': True,
+            },
+        )
+        assert set_resp.status_code == 200
+
+        get_resp = client.get(f'/child/routine-child-2/routine/{rid}/schedule')
+        assert get_resp.status_code == 200
+        assert get_resp.get_json()['mode'] == 'days'
+
+        extend_resp = client.post(
+            f'/child/routine-child-2/routine/{rid}/extend',
+            json={'date': '2026-05-04'},
+        )
+        assert extend_resp.status_code == 200
+        assert extend_resp.get_json()['routine_id'] == rid

backend/utils/chore_expiry_notification_scheduler.py

@@ -62,7 +62,7 @@ def get_expiring_chores_for_user(
 
     try:
         from zoneinfo import ZoneInfo
-        local_now = datetime.now(ZoneInfo(tz_str)) if tz_str else now_dt
+        local_now = now_dt.astimezone(ZoneInfo(tz_str)) if tz_str else now_dt
     except Exception:
         local_now = now_dt
 
@@ -106,10 +106,15 @@ def get_expiring_chores_for_user(
                 continue  # Anytime — no expiry
 
             due_hour, due_minute = due
-            # Build a timezone-aware deadline datetime for today
+            # Build a timezone-aware deadline datetime for the next occurrence of the due time.
+            # Schedules run hourly and may span midnight (e.g. a 23:00 run needs to catch
+            # a chore due at 00:15 the next day), so roll forward a day when the candidate
+            # deadline has already passed.
             deadline_dt = local_now.replace(
                 hour=due_hour, minute=due_minute, second=0, microsecond=0
             )
+            if deadline_dt <= local_now:
+                deadline_dt = deadline_dt + timedelta(days=1)
 
             # Include only when deadline is strictly after now and within window
             if not (local_now < deadline_dt <= window_end):

docker-compose.test.yml

@@ -29,9 +29,10 @@ services:
   chores-test-app-frontend: # Test frontend service name
     image: git.ryankegel.com:3000/kegel/chores/frontend:next # Use latest next tag
     ports:
-      - "446:443" # Host 446 -> Container 443 (HTTPS)
+      - "446:80" # Host 446 -> Container 80 (HTTP behind external TLS proxy)
     environment:
       - BACKEND_HOST=chores-test-app-backend # Points to internal backend service
+      - FRONTEND_SSL_ENABLED=false
     depends_on:
       - chores-test-app-backend
     # Add volumes, networks, etc., as needed

docker-compose.yml

@@ -25,9 +25,10 @@ services:
     image: git.ryankegel.com:3000/kegel/chores/frontend:latest # Or specific version tag
     container_name: chores-app-frontend-prod # Added for easy identification
     ports:
-      - "${FRONTEND_HOST_PORT:-4601}:443" # Host port -> Container 443 (HTTPS)
+      - "${FRONTEND_HOST_PORT:-4601}:${FRONTEND_CONTAINER_PORT:-80}" # Host port -> Container 80 (HTTP; SSL terminated by external proxy)
     environment:
       - BACKEND_HOST=chores-app-backend # Points to internal backend service
+      - FRONTEND_SSL_ENABLED=false
     depends_on:
       - chores-app-backend
     networks:

frontend/.env.test

@@ -0,0 +1,4 @@
+# MongoDB configuration for end-to-end tests.
+# Uses mongomock so E2E tests do not require a running MongoDB server.
+USE_MONGODB=true
+MONGO_URI=mongomock

frontend/.gitignore

@@ -37,6 +37,9 @@ __screenshots__/
 
 *.old
 
+# Local dev TLS certs (machine-specific, generated by mkcert)
+*.pem
+
 # Playwright
 /test-results/
 /playwright-report/

frontend/192.168.1.102+1-key.pem

@@ -1,28 +0,0 @@
------BEGIN PRIVATE KEY-----
-MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCh96Qoz16kpDde
-puFkARSFp9PDFs8kUBGCJ0DcBDqJIUuLJj7RT5vxfUj3O7uUUjTtVAVCMJ84/eq/
-IQnyhch1B2Fe5bas51kEgwybzxxEN1bcj3yokbd4aOCpxkpM382TKMPuGH1BXUO8
-ZqqikbvKySJ9glboPImLRA4UvH1cx9Db0kQE9scBl98qqE28exlBqMBsIOjh+mJ0
-rWt3JO+A50OjOSuxO7hdjINlJg5X+jmI1wF3GWE2i9GrCJXh9JVYixnjvsFMIKJo
-Zu9wAZCmtqHvicvwdzDxdDAU8GfACOg4w4hlMOSfIU4pAONxW479Gf5pSFVTw7Zu
-RNrTDsd9AgMBAAECggEAGICASL0wLdt61dqMg8anDl4Yaq2nafCj6WrbRL1uBoMv
-LK59N8hhiKuBj4cthg9WmuWIQx5cY/CDo+TRXqsu60dRy1uYYjlATe6uSF7RQZ+W
-iBi7zLt4hCJnhD9vS4hazs2OsFTrk+kSP2zPmPbPcCqzyUVftNO9ogAKWkg2dcO1
-9KjDnR0pSn17rwj064mfVNoLYiN11nwQ21zyJFLYGM5mXYYW9b+EI9ZnWWyz6Lvo
-+qrYhZh2hR8ul8rpURc0flqFvORaO4FhaQeX5+r5FZFQkRWQYbRfBbAJnIrFVa+N
-8O002E0FLHWI0S7YPsbnBqE+eHRM9fzz1q0p4YrjEQKBgQDDz9n2BLwwQCreXglG
-V2T1SBdi1+MDTMUCHEcak3Gk4ZRIU4r2ofoTdYagEaYCMBGL7/noYECpEfkzF4B5
-u1nXUTtFODq0m1Uc18iL8WMJy8AkoT+LZEmF0y5WDI/fLzzxuQKXpTDyeUwTYf/W
-9xHHi4gckc3wcf1tKtNSswCcMQKBgQDTwJxki8/2OEtIRcPlhhXNQRpSnp6cjgoB
-xQ4J83idR3/HBLWMI9snx47SE1AxGFY4UHIQNvMN3icKt5C7QyfrMfZCpUcRryv6
-1dBFVbvxm0Hvqj/pWsgtjbq+dbiOLtH52zc9nsPAF++FhlYtZz9fJmwsgxsnab1O
-B9dUyXMpDQKBgDj3LRfPhNgcstwCS3x1TF+3W2ZcHCUHnoDgrSbkIjmvjq4D7/eU
-Y+ZpWIMU31Dfnxsw82lRJz6IhhEBE1VW1eo4LaATnbCRSA+eDy/3R7K/3eRKLOxm
-fqU6LM7H1Ms/OOGxyzlGy5ifBSzWY9GsCzYcN7roCBudbfbmcJgsj07hAoGAd2p1
-CCLsub9PfUeSzTrLyr//Nz6q1kEoFY1qeGQszg3HWpYmSAzkh897lK89lyJRZVrA
-qLJEabqxq9KPtXuO5I19gmIw7SErnT69QIyz+/IBwkXx2wjOQRpfiQ9ccBqpYc2l
-noONgyQ8eMGkkeBbFa7WbFfXlWeFUZ8MaY1d+3UCgYBguVXJ9JTvMxeXx5cjnfMI
-eVRhr2BbARTdCJXKUpo4rUUqLrCCSB6BrT4H+DYtRVKO/ZIaXARQIN1ACo03C78o
-U+Rg+mGTyvGh8pVH63zZE9tsohtT+/bSraYm/dLKUmaK3Z9wG75wmOpNLlAEiUqW
-mzkW/UN0WWzg5gyODVbQKQ==
------END PRIVATE KEY-----

frontend/192.168.1.102+1.pem

@@ -1,26 +0,0 @@
------BEGIN CERTIFICATE-----
-MIIEZDCCAsygAwIBAgIQIM51sKaVetu2bhpqghM+2TANBgkqhkiG9w0BAQsFADCB
-kzEeMBwGA1UEChMVbWtjZXJ0IGRldmVsb3BtZW50IENBMTQwMgYDVQQLDCtyeWFu
-QG1hY2Jvb2sudGFpbGExNDZiMy50cy5uZXQgKFJ5YW4gS2VnZWwpMTswOQYDVQQD
-DDJta2NlcnQgcnlhbkBtYWNib29rLnRhaWxhMTQ2YjMudHMubmV0IChSeWFuIEtl
-Z2VsKTAeFw0yNjA0MTYyMjEwMTNaFw0yODA3MTYyMjEwMTNaMFMxJzAlBgNVBAoT
-Hm1rY2VydCBkZXZlbG9wbWVudCBjZXJ0aWZpY2F0ZTEoMCYGA1UECwwfcnlhbkBy
-eWFucy1haXIubGFuIChSeWFuIEtlZ2VsKTCCASIwDQYJKoZIhvcNAQEBBQADggEP
-ADCCAQoCggEBAKH3pCjPXqSkN16m4WQBFIWn08MWzyRQEYInQNwEOokhS4smPtFP
-m/F9SPc7u5RSNO1UBUIwnzj96r8hCfKFyHUHYV7ltqznWQSDDJvPHEQ3VtyPfKiR
-t3ho4KnGSkzfzZMow+4YfUFdQ7xmqqKRu8rJIn2CVug8iYtEDhS8fVzH0NvSRAT2
-xwGX3yqoTbx7GUGowGwg6OH6YnSta3ck74DnQ6M5K7E7uF2Mg2UmDlf6OYjXAXcZ
-YTaL0asIleH0lViLGeO+wUwgomhm73ABkKa2oe+Jy/B3MPF0MBTwZ8AI6DjDiGUw
-5J8hTikA43Fbjv0Z/mlIVVPDtm5E2tMOx30CAwEAAaNzMHEwDgYDVR0PAQH/BAQD
-AgWgMBMGA1UdJQQMMAoGCCsGAQUFBwMBMB8GA1UdIwQYMBaAFLM+akEIDt75nyHZ
-rbkUs/4IQWesMCkGA1UdEQQiMCCCCWxvY2FsaG9zdIINZGV2c2VydmVyLmxhbocE
-wKgBZjANBgkqhkiG9w0BAQsFAAOCAYEAi4pT3LNzoM5mmD3ujX+G+cXx8MOAljvR
-XGrzorysNOujR79+zR5tPPyiLwFfEYASJhWlHarM8n6DG+IgARNt9PuDq0x8+oDp
-V/t9grCS6eV/SQf6y7JBQrywdIBgfYGJbbx6xzVlj187M+7yNV73f3ldS3wPFKlS
-Gp6p50Vt9gmfsiqzW4NDr0FIvdbcBesNfr2DwRccZNgNAcLsr9ys2yVUcUtMnqPF
-IPyarDbREuBLLLpnsYZhY3BJQgI3gDS9QRoviFCMjcbWKNnv0D2W0rVdZkJf9WOj
-ro9X1K2f2C/t61EnFsM6ncqAgMksbBmlORiVi4thAgB44FDydyHX6anf7Hbzfn1t
-sjsiZ03rO9xvFzUb2T9guFMBkU6pBDEhCdN3twYPY3uKPXByHnSmj3q38NJVbULu
-szC1q91VF+2U2UoeoXaNxrXVleKpLiWEUJ/u/iGrbApeuov5ZTktA/y/d/+TDB+h
-Jlo+Ofg3zgZBHpN+fsGTxhRLlJyXSynI
------END CERTIFICATE-----

frontend/Dockerfile

@@ -10,17 +10,15 @@ RUN npm run build
 FROM nginx:alpine
 COPY --from=build /app/dist /usr/share/nginx/html
 COPY nginx.conf.template /etc/nginx/nginx.conf.template
-# Copy SSL certificate and key
-COPY 192.168.1.102+1.pem /etc/nginx/ssl/server.crt
-COPY 192.168.1.102+1-key.pem /etc/nginx/ssl/server.key
+COPY nginx.http.conf.template /etc/nginx/nginx.http.conf.template
+COPY docker/start-nginx.sh /docker/start-nginx.sh
+RUN chmod +x /docker/start-nginx.sh
 
 EXPOSE 80
 EXPOSE 443
-# Copy nginx.conf
-COPY nginx.conf.template /etc/nginx/nginx.conf.template
 
-# Set default BACKEND_HOST (can be overridden at runtime)
+# Set default runtime values (can be overridden at runtime)
 ENV BACKEND_HOST=chore-app-backend
+ENV FRONTEND_SSL_ENABLED=true
 
-# Use sed to replace $BACKEND_HOST with the env value, then start Nginx
-CMD ["/bin/sh", "-c", "sed 's/\\$BACKEND_HOST/'\"$BACKEND_HOST\"'/g' /etc/nginx/nginx.conf.template > /etc/nginx/nginx.conf && nginx -g 'daemon off;'"]
+CMD ["/docker/start-nginx.sh"]

frontend/docker/start-nginx.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+set -eu
+
+backend_host="${BACKEND_HOST:-chore-app-backend}"
+ssl_enabled="$(printf '%s' "${FRONTEND_SSL_ENABLED:-true}" | tr '[:upper:]' '[:lower:]')"
+
+template_file="/etc/nginx/nginx.http.conf.template"
+
+case "$ssl_enabled" in
+  1|true|yes|on)
+    template_file="/etc/nginx/nginx.conf.template"
+    ;;
+esac
+
+sed "s|\$BACKEND_HOST|${backend_host}|g" "$template_file" > /etc/nginx/nginx.conf
+
+nginx -t
+exec nginx -g 'daemon off;'

frontend/e2e/.auth/user-cc.json

@@ -2,20 +2,20 @@
   "cookies": [
     {
       "name": "refresh_token",
-      "value": "1aCKS1DujEPmHYGCELY7JiJ-LfxGjw7_HK1uCymlbh8",
+      "value": "hW7OJbUjHr4XntQRPtefKNhvvctK014R6pzLz_vyJ8g",
       "domain": "localhost",
       "path": "/api/auth",
-      "expires": 1785207783.273047,
+      "expires": 1792774142.289068,
       "httpOnly": true,
       "secure": true,
       "sameSite": "Strict"
     },
     {
       "name": "access_token",
-      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImUyZS1jY0B0ZXN0LmNvbSIsInVzZXJfaWQiOiJhNzY5YzY4Zi04MWQ5LTRiNjctODQwYS1mY2Q5NTVkNzAwNzYiLCJ0b2tlbl92ZXJzaW9uIjowLCJleHAiOjE3Nzc0NDI1ODN9.vdmfmIx0Dg4zKq9HTV7N7tjDbSGaO3EOeGqJbhFSOcQ",
+      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImUyZS1jY0B0ZXN0LmNvbSIsInVzZXJfaWQiOiI5MjUwNzY1MS00YjlmLTRkMTMtOTgxYS1hMzA2ZThjY2JmNzciLCJ0b2tlbl92ZXJzaW9uIjowLCJleHAiOjE3ODUwMDg5NDJ9.15hDvKf9u95pMzyeSbrHesFBDGgTwnxV1FD175p72-w",
       "domain": "localhost",
       "path": "/",
-      "expires": 1777442583.273,
+      "expires": 1785008942.288088,
       "httpOnly": true,
       "secure": true,
       "sameSite": "Lax"
@@ -27,11 +27,11 @@
       "localStorage": [
         {
           "name": "authSyncEvent",
-          "value": "{\"type\":\"logout\",\"at\":1777431783134}"
+          "value": "{\"type\":\"logout\",\"at\":1784998141942}"
         },
         {
           "name": "parentAuth",
-          "value": "{\"expiresAt\":1777604583443}"
+          "value": "{\"expiresAt\":1785170942553}"
         }
       ]
     }

frontend/e2e/.auth/user-delete.json

@@ -2,20 +2,20 @@
   "cookies": [
     {
       "name": "refresh_token",
-      "value": "eDlr3-DaFNFoWQE3EDAybLFpw7TiR3Maj05kLIkZfu0",
+      "value": "PylNoNcxDjRuoocNg4ZmApg_7OIxp9Jfs7ttsX3C5uA",
       "domain": "localhost",
       "path": "/api/auth",
-      "expires": 1785207783.382249,
+      "expires": 1792435594.088028,
       "httpOnly": true,
       "secure": true,
       "sameSite": "Strict"
     },
     {
       "name": "access_token",
-      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImUyZS1kZWxldGVAdGVzdC5jb20iLCJ1c2VyX2lkIjoiNGYwNmY0YTMtMGQwMC00NzJhLWJkMjQtYjM1YjdkMjg4ZDFiIiwidG9rZW5fdmVyc2lvbiI6MCwiZXhwIjoxNzc3NDQyNTgzfQ.F2TXov3xbhFa20P5NLt6J5HfNDlY2aXlnPoSYYDJpoQ",
+      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImUyZS1kZWxldGVAdGVzdC5jb20iLCJ1c2VyX2lkIjoiN2UzNjdjMGItMDU3ZS00MWEzLThlNzYtZWZmNDUyMmFmOTU2IiwidG9rZW5fdmVyc2lvbiI6MCwiZXhwIjoxNzg0NjcwMzk0fQ.cVkoiVTtH1O7TFqW5yQ9BEBlTq7hR8YEya7FW2b_Yh8",
       "domain": "localhost",
       "path": "/",
-      "expires": 1777442583.38218,
+      "expires": 1784670394.08796,
       "httpOnly": true,
       "secure": true,
       "sameSite": "Lax"
@@ -27,11 +27,11 @@
       "localStorage": [
         {
           "name": "authSyncEvent",
-          "value": "{\"type\":\"logout\",\"at\":1777431783225}"
+          "value": "{\"type\":\"logout\",\"at\":1784659593889}"
         },
         {
           "name": "parentAuth",
-          "value": "{\"expiresAt\":1777604583575}"
+          "value": "{\"expiresAt\":1784832394248}"
         }
       ]
     }

frontend/e2e/.auth/user-tutorial.json

@@ -0,0 +1,39 @@
+{
+  "cookies": [
+    {
+      "name": "refresh_token",
+      "value": "5gEK_iLdGl1BAGfetT8hEf6SJK2lQVbYxQjH0BdKWwU",
+      "domain": "localhost",
+      "path": "/api/auth",
+      "expires": 1792813397.168935,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Strict"
+    },
+    {
+      "name": "access_token",
+      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImUyZS10dXRvcmlhbEB0ZXN0LmNvbSIsInVzZXJfaWQiOiJkODk0ZjA0OS0xODU3LTQwM2UtYjgzZC1jMTY2NTNmZDU2MmEiLCJ0b2tlbl92ZXJzaW9uIjowLCJleHAiOjE3ODUwNDgxOTd9.S7frWOrZwXC5xVgtG2RDioXGok04qK_jLCYWvfedD7s",
+      "domain": "localhost",
+      "path": "/",
+      "expires": 1785048197.167997,
+      "httpOnly": true,
+      "secure": true,
+      "sameSite": "Lax"
+    }
+  ],
+  "origins": [
+    {
+      "origin": "https://localhost:5173",
+      "localStorage": [
+        {
+          "name": "authSyncEvent",
+          "value": "{\"type\":\"logout\",\"at\":1785037396813}"
+        },
+        {
+          "name": "parentAuth",
+          "value": "{\"expiresAt\":1785210197388}"
+        }
+      ]
+    }
+  ]
+}

frontend/e2e/.auth/user.json

@@ -2,20 +2,20 @@
   "cookies": [
     {
       "name": "refresh_token",
-      "value": "BGnvmJr7XNXaCsXlzh1k6RcJPIGVxac6_LBXS22gXIA",
+      "value": "Ke6qDj_0RYyrMSI1Z9C69DPtvYo26oUUiLZr_pDXZv4",
       "domain": "localhost",
       "path": "/api/auth",
-      "expires": 1785207781.614965,
+      "expires": 1792813392.716776,
       "httpOnly": true,
       "secure": true,
       "sameSite": "Strict"
     },
     {
       "name": "access_token",
-      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImUyZUB0ZXN0LmNvbSIsInVzZXJfaWQiOiI4YmQxMWY5NC1jNWJhLTRhNmEtOGZhMi1hZjZkYzk3Y2YyMjgiLCJ0b2tlbl92ZXJzaW9uIjowLCJleHAiOjE3Nzc0NDI1ODF9.WVDBt-zfwVMHCWr78maSGWAyfQZhWOSobX5oXKXLHwg",
+      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImUyZUB0ZXN0LmNvbSIsInVzZXJfaWQiOiI3NTYwZDBlNy1iMmVlLTRiMjktYTYwNi1lZTM3NmIzN2Y3ODciLCJ0b2tlbl92ZXJzaW9uIjowLCJleHAiOjE3ODUwNDgxOTJ9.QB4bXo88KC7jr94QSjJI3Y1eVWeU4KNKdHRi1_7zcD0",
       "domain": "localhost",
       "path": "/",
-      "expires": 1777442581.61492,
+      "expires": 1785048192.71579,
       "httpOnly": true,
       "secure": true,
       "sameSite": "Lax"
@@ -27,11 +27,11 @@
       "localStorage": [
         {
           "name": "authSyncEvent",
-          "value": "{\"type\":\"logout\",\"at\":1777431781473}"
+          "value": "{\"type\":\"logout\",\"at\":1785037392502}"
         },
         {
           "name": "parentAuth",
-          "value": "{\"expiresAt\":1777604581743}"
+          "value": "{\"expiresAt\":1785210192904}"
         }
       ]
     }

frontend/e2e/auth-tutorial.setup.ts

@@ -0,0 +1,47 @@
+import { test as setup } from '@playwright/test'
+import {
+  STORAGE_STATE_TUTORIAL,
+  E2E_TUTORIAL_EMAIL,
+  E2E_TUTORIAL_PASSWORD,
+  E2E_TUTORIAL_PIN,
+} from './e2e-constants'
+
+const BACKEND = 'http://localhost:5000'
+
+setup('authenticate tutorial user', async ({ page }) => {
+  // Create the isolated tutorial-test user (separate from the main E2E user)
+  const createRes = await page.request.post(`${BACKEND}/auth/e2e-create-tutorial-user`)
+  if (!createRes.ok()) {
+    throw new Error(
+      `e2e-create-tutorial-user failed: ${createRes.status()} ${await createRes.text()}`,
+    )
+  }
+
+  await page.goto('/auth/login')
+  await page.getByLabel('Email address').fill(E2E_TUTORIAL_EMAIL)
+  await page.getByLabel('Password').fill(E2E_TUTORIAL_PASSWORD)
+  await page.getByRole('button', { name: 'Sign in' }).click()
+
+  await page.waitForURL(/\/(parent|child)/)
+
+  await page.getByRole('button', { name: 'Parent login' }).click()
+
+  const pinInput = page.getByPlaceholder('4–6 digits')
+  await pinInput.waitFor({ timeout: 5000 })
+  await pinInput.fill(E2E_TUTORIAL_PIN)
+  await page.getByLabel('Stay in parent mode on this device').check()
+  await page.getByRole('button', { name: 'OK' }).click()
+
+  await page.waitForURL(/\/parent(\/|$)/)
+
+  try {
+    await page.getByRole('button', { name: 'Add Child' }).waitFor({ timeout: 5000 })
+  } catch {
+    await page.screenshot({ path: 'auth-setup-tutorial-parent-fail.png' })
+    throw new Error(
+      'Tutorial user parent mode not reached after PIN entry. See auth-setup-tutorial-parent-fail.png for details.',
+    )
+  }
+
+  await page.context().storageState({ path: STORAGE_STATE_TUTORIAL })
+})

frontend/e2e/e2e-constants.ts

@@ -3,6 +3,7 @@ export const STORAGE_STATE_NO_PIN = 'e2e/.auth/user-no-pin.json'
 export const STORAGE_STATE_TEMP_PARENT = 'e2e/.auth/user-temp-parent.json'
 export const STORAGE_STATE_DELETE = 'e2e/.auth/user-delete.json'
 export const STORAGE_STATE_CC = 'e2e/.auth/user-cc.json'
+export const STORAGE_STATE_TUTORIAL = 'e2e/.auth/user-tutorial.json'
 export const E2E_EMAIL = 'e2e@test.com'
 export const E2E_PASSWORD = 'E2eTestPass1!'
 export const E2E_PIN = '1234'
@@ -13,3 +14,6 @@ export const E2E_DELETE_PIN = '5678'
 export const E2E_CC_EMAIL = 'e2e-cc@test.com'
 export const E2E_CC_PASSWORD = 'E2eCCPass1!'
 export const E2E_CC_PIN = '3456'
+export const E2E_TUTORIAL_EMAIL = 'e2e-tutorial@test.com'
+export const E2E_TUTORIAL_PASSWORD = 'E2eTutorialPass1!'
+export const E2E_TUTORIAL_PIN = '7890'

frontend/e2e/mode_parent/create-child/validation.spec.ts

@@ -14,6 +14,11 @@ test.describe('Create Child', () => {
 
     // Navigate to parent list and wait for it to fully load before clicking Add Child
     await gotoParentList(page)
+    // Dismiss tutorial overlay if present — it intercepts pointer events
+    const skip = page.getByRole('button', { name: 'Cancel' })
+    if (await skip.isVisible({ timeout: 1000 }).catch(() => false)) {
+      await skip.click()
+    }
     await page.getByRole('button', { name: 'Add Child' }).click()
     await expect(page.getByRole('heading', { name: 'Create Child' })).toBeVisible()
   })
@@ -30,7 +35,7 @@ test.describe('Create Child', () => {
   test('Reject submission when Name is whitespace only', async ({ page }) => {
     // 2. Enter only spaces in Name, enter '7' in Age - Create remains disabled
     const createButton = page.getByRole('button', { name: 'Create' })
-    await page.getByLabel('Name').fill('   ')
+    await page.getByRole('textbox', { name: 'Name' }).fill('   ')
     await page.getByLabel('Age').fill('7')
 
     await expect(createButton).toBeDisabled()
@@ -39,7 +44,7 @@ test.describe('Create Child', () => {
 
   test('Reject submission when Age is empty', async ({ page }) => {
     // 2. Enter 'Charlie', clear Age - Create button should be disabled
-    await page.getByLabel('Name').fill('Charlie')
+    await page.getByRole('textbox', { name: 'Name' }).fill('Charlie')
     await page.getByLabel('Age').clear()
 
     await expect(page.getByRole('button', { name: 'Create' })).toBeDisabled()
@@ -49,7 +54,7 @@ test.describe('Create Child', () => {
   test('Reject negative age', async ({ page }) => {
     // 2. Enter 'Dave', enter '-1' - Create remains disabled
     const createButton = page.getByRole('button', { name: 'Create' })
-    await page.getByLabel('Name').fill('Dave')
+    await page.getByRole('textbox', { name: 'Name' }).fill('Dave')
     await page.getByLabel('Age').fill('-1')
 
     await expect(createButton).toBeDisabled()
@@ -57,7 +62,7 @@ test.describe('Create Child', () => {
   })
 
   test('Enforce maximum Name length of 64 characters', async ({ page, request }) => {
-    const nameInput = page.getByLabel('Name')
+    const nameInput = page.getByRole('textbox', { name: 'Name' })
     const ageInput = page.getByLabel('Age')
     const createButton = page.getByRole('button', { name: 'Create' })
 
@@ -85,7 +90,7 @@ test.describe('Create Child', () => {
 
   test('Reject age greater than 120', async ({ page }) => {
     // 2. Enter 'Eve', enter '121' in Age - Create button should be disabled
-    await page.getByLabel('Name').fill('Eve')
+    await page.getByRole('textbox', { name: 'Name' }).fill('Eve')
     await page.getByLabel('Age').fill('121')
 
     await expect(page.getByRole('button', { name: 'Create' })).toBeDisabled()

frontend/e2e/mode_parent/notifications/push-subscription.spec.ts

@@ -9,6 +9,17 @@ function pushToggle(page: Page) {
     .locator('button.toggle-btn')
 }
 
+async function openNotificationsSection(page: Page): Promise<void> {
+  const header = page
+    .locator('.profile-section')
+    .filter({ has: page.locator('.section-title', { hasText: 'Notifications' }) })
+    .locator('.section-header')
+  if ((await header.getAttribute('aria-expanded')) === 'false') {
+    await header.click()
+  }
+  await page.locator('#section-notifications').waitFor({ state: 'visible' })
+}
+
 test.describe('Push subscription registration', () => {
   // -------------------------------------------------------------------------
   // 1.3 No subscription POST when notification permission not granted
@@ -26,6 +37,7 @@ test.describe('Push subscription registration', () => {
     })
 
     await page.goto('/parent/profile')
+    await openNotificationsSection(page)
     const toggle = pushToggle(page)
     await expect(toggle).toBeVisible({ timeout: 5000 })
     const isDisabled = await toggle.isDisabled().catch(() => false)

frontend/e2e/mode_parent/notifications/reward-notification-deny.spec.ts

@@ -108,8 +108,8 @@ test.describe('Reward Notification — In-App Denial', () => {
     await expect(card).toHaveClass(/item-ready/, { timeout: 3000 })
     await card.click()
 
-    // Look for a Deny button in the dialog
-    const denyBtn = page.getByRole('button', { name: /deny/i })
+    // Look for the reject action in the dialog
+    const denyBtn = page.getByRole('button', { name: 'Reject', exact: true })
     await expect(denyBtn).toBeVisible({ timeout: 5000 })
     await denyBtn.click()
     await expect(denyBtn).not.toBeVisible({ timeout: 5000 })
@@ -127,7 +127,7 @@ test.describe('Reward Notification — In-App Denial', () => {
     await card.click()
     await expect(card).toHaveClass(/item-ready/, { timeout: 3000 })
     await card.click()
-    const denyBtn = page.getByRole('button', { name: /deny/i })
+    const denyBtn = page.getByRole('button', { name: 'Reject', exact: true })
     await expect(denyBtn).toBeVisible({ timeout: 5000 })
     await denyBtn.click()
     await expect(denyBtn).not.toBeVisible({ timeout: 5000 })

frontend/e2e/mode_parent/notifications/user-profile-notification-settings.spec.ts

@@ -16,6 +16,17 @@ function pushToggle(page: Page) {
     .locator('button.toggle-btn')
 }
 
+async function openNotificationsSection(page: Page): Promise<void> {
+  const header = page
+    .locator('.profile-section')
+    .filter({ has: page.locator('.section-title', { hasText: 'Notifications' }) })
+    .locator('.section-header')
+  if ((await header.getAttribute('aria-expanded')) === 'false') {
+    await header.click()
+  }
+  await page.locator('#section-notifications').waitFor({ state: 'visible' })
+}
+
 test.describe('User Profile Notification Settings', () => {
   test.describe.configure({ mode: 'serial' })
 
@@ -24,6 +35,7 @@ test.describe('User Profile Notification Settings', () => {
   // ---------------------------------------------------------------------------
   test('Email Digest toggle is visible on User Profile page', async ({ page }) => {
     await page.goto('/parent/profile')
+    await openNotificationsSection(page)
     await expect(digestToggle(page)).toBeVisible({ timeout: 5000 })
   })
 
@@ -34,11 +46,13 @@ test.describe('User Profile Notification Settings', () => {
     // Set known state: enabled
     await request.put('/api/user/profile', { data: { email_digest_enabled: true } })
     await page.goto('/parent/profile')
+    await openNotificationsSection(page)
     await expect(digestToggle(page)).toHaveAttribute('aria-pressed', 'true', { timeout: 5000 })
 
     // Set known state: disabled
     await request.put('/api/user/profile', { data: { email_digest_enabled: false } })
     await page.reload()
+    await openNotificationsSection(page)
     await expect(digestToggle(page)).toHaveAttribute('aria-pressed', 'false', { timeout: 5000 })
 
     // Restore default
@@ -51,6 +65,7 @@ test.describe('User Profile Notification Settings', () => {
   test('Toggling Email Digest off sends correct API payload', async ({ page, request }) => {
     await request.put('/api/user/profile', { data: { email_digest_enabled: true } })
     await page.goto('/parent/profile')
+    await openNotificationsSection(page)
     // Wait for profile to load and toggle to reflect server state
     await expect(digestToggle(page)).toHaveAttribute('aria-pressed', 'true', { timeout: 5000 })
 
@@ -64,9 +79,7 @@ test.describe('User Profile Notification Settings', () => {
 
     await digestToggle(page).click()
 
-    // Submit the form (Save button)
-    await page.getByRole('button', { name: 'Save' }).click()
-
+    // Toggles auto-save; wait for the PUT and verify the payload.
     await page.waitForTimeout(500)
     expect(capturedBody).not.toBeNull()
     expect((capturedBody as Record<string, unknown>)['email_digest_enabled']).toBe(false)
@@ -82,6 +95,7 @@ test.describe('User Profile Notification Settings', () => {
   test('Toggling Email Digest on sends correct API payload', async ({ page, request }) => {
     await request.put('/api/user/profile', { data: { email_digest_enabled: false } })
     await page.goto('/parent/profile')
+    await openNotificationsSection(page)
     // Wait for profile to load and toggle to reflect server state
     await expect(digestToggle(page)).toHaveAttribute('aria-pressed', 'false', { timeout: 5000 })
 
@@ -94,7 +108,6 @@ test.describe('User Profile Notification Settings', () => {
     })
 
     await digestToggle(page).click()
-    await page.getByRole('button', { name: 'Save' }).click()
 
     await page.waitForTimeout(500)
     expect(capturedBody).not.toBeNull()
@@ -110,6 +123,7 @@ test.describe('User Profile Notification Settings', () => {
   // ---------------------------------------------------------------------------
   test('Push Notifications toggle is visible on User Profile page', async ({ page }) => {
     await page.goto('/parent/profile')
+    await openNotificationsSection(page)
     await expect(pushToggle(page)).toBeVisible({ timeout: 5000 })
   })
 
@@ -121,6 +135,7 @@ test.describe('User Profile Notification Settings', () => {
   }) => {
     // Do NOT grant notifications permission — toggle should start unchecked
     await page.goto('/parent/profile')
+    await openNotificationsSection(page)
     const toggle = pushToggle(page)
     await expect(toggle).toBeVisible({ timeout: 5000 })
     // Either aria-pressed="false" or disabled (when browser denies permissions)
@@ -138,6 +153,7 @@ test.describe('User Profile Notification Settings', () => {
     // Do not grant permission (leave as denied/prompt)
     await context.clearPermissions()
     await page.goto('/parent/profile')
+    await openNotificationsSection(page)
     const toggle = pushToggle(page)
     await expect(toggle).toBeVisible({ timeout: 5000 })
     // When permission is denied, the toggle should be disabled or aria-pressed="false"

frontend/e2e/mode_parent/profile-button/profile-button-temporary.spec.ts

@@ -4,6 +4,11 @@ import { E2E_PIN } from '../../e2e-constants'
 test.describe('Parent profile button – temporary parent mode', () => {
   test.beforeEach(async ({ page }) => {
     await page.goto('/parent')
+    // Dismiss tutorial overlay if present — it intercepts pointer events
+    const skip = page.getByRole('button', { name: 'Cancel' })
+    if (await skip.isVisible({ timeout: 1000 }).catch(() => false)) {
+      await skip.click()
+    }
     // Switch from permanent mode to temporary mode:
     // 1. Exit parent mode via Child Mode
     await page.getByRole('button', { name: 'Parent menu' }).click()

frontend/e2e/mode_parent/profile-button/profile-button.spec.ts

@@ -4,6 +4,11 @@ import { E2E_EMAIL, E2E_FIRST_NAME, E2E_PIN } from '../../e2e-constants'
 test.describe('Parent profile button – permanent parent mode', () => {
   test.beforeEach(async ({ page }) => {
     await page.goto('/parent')
+    // Dismiss tutorial overlay if present — it intercepts pointer events
+    const skip = page.getByRole('button', { name: 'Cancel' })
+    if (await skip.isVisible({ timeout: 1000 }).catch(() => false)) {
+      await skip.click()
+    }
   })
 
   test('Badge – shows 🔒 in permanent parent mode', async ({ page }) => {
@@ -23,7 +28,7 @@ test.describe('Parent profile button – permanent parent mode', () => {
     await page.getByRole('menuitem', { name: 'Profile' }).click()
 
     await expect(page).toHaveURL(/\/parent\/profile/)
-    await expect(page.getByRole('heading', { name: 'User Profile' })).toBeVisible()
+    await expect(page.getByRole('heading', { name: 'Profile' })).toBeVisible()
   })
 
   test('Menu – Child Mode exits parent mode', async ({ page }) => {

frontend/e2e/mode_parent/routines/routine-child-mode.spec.ts

@@ -0,0 +1,213 @@
+import { test, expect, type APIRequestContext, type Page } from '@playwright/test'
+
+const CHILD_NAME = 'RoutineChildModeChild'
+const ROUTINE_NAME = 'RoutineChildModeTest'
+const ROUTINE_POINTS = 10
+const TASK_NAME_1 = 'Brush Teeth'
+const TASK_NAME_2 = 'Wash Face'
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+async function createChild(request: APIRequestContext, name: string): Promise<string> {
+  const pre = await request.get('/api/child/list')
+  for (const c of (await pre.json()).children ?? []) {
+    if (c.name === name) await request.delete(`/api/child/${c.id}`)
+  }
+  await request.put('/api/child/add', { data: { name, age: 8 } })
+  const list = await request.get('/api/child/list')
+  return (await list.json()).children?.find((c: any) => c.name === name)?.id ?? ''
+}
+
+async function createRoutine(
+  request: APIRequestContext,
+  name: string,
+  points: number,
+): Promise<string> {
+  const pre = await request.get('/api/routine/list')
+  for (const r of (await pre.json()).routines ?? []) {
+    if (r.name === name) await request.delete(`/api/routine/${r.id}`)
+  }
+  const res = await request.put('/api/routine/add', { data: { name, points } })
+  return (await res.json()).routine?.id ?? ''
+}
+
+function routineSection(page: Page) {
+  return page.locator('.child-list-container').filter({
+    has: page.locator('h3', { hasText: 'Routines' }),
+  })
+}
+
+// ── suite ─────────────────────────────────────────────────────────────────────
+
+test.describe('Routine child-mode flow', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  let childId = ''
+  let routineId = ''
+
+  test.beforeAll(async ({ request }) => {
+    childId = await createChild(request, CHILD_NAME)
+    routineId = await createRoutine(request, ROUTINE_NAME, ROUTINE_POINTS)
+
+    await request.put(`/api/routine/${routineId}/item/add`, { data: { name: TASK_NAME_1 } })
+    await request.put(`/api/routine/${routineId}/item/add`, { data: { name: TASK_NAME_2 } })
+    await request.post(`/api/child/${childId}/assign-routine`, {
+      data: { routine_id: routineId },
+    })
+  })
+
+  test.afterAll(async ({ request }) => {
+    if (childId) await request.delete(`/api/child/${childId}`)
+    if (routineId) await request.delete(`/api/routine/${routineId}`)
+  })
+
+  // Intercept parentAuth so the router treats this session as child-mode (not parent-authenticated).
+  test.beforeEach(async ({ page }) => {
+    await page.addInitScript(() => {
+      const orig = Storage.prototype.getItem
+      Storage.prototype.getItem = function (key: string) {
+        if (key === 'parentAuth') return null
+        return orig.call(this, key)
+      }
+    })
+  })
+
+  // ── 1. Routine section visible ────────────────────────────────────────────
+
+  test('Routine section appears in child view', async ({ page }) => {
+    await page.goto(`/child/${childId}`)
+
+    const section = routineSection(page)
+    await expect(section).toBeVisible({ timeout: 5000 })
+    await expect(section.locator('.item-card').filter({ hasText: ROUTINE_NAME })).toBeVisible()
+  })
+
+  // ── 2. Overlay opens on two-click ─────────────────────────────────────────
+
+  test('Clicking routine twice opens overlay with correct header', async ({ page }) => {
+    await page.goto(`/child/${childId}`)
+
+    const card = routineSection(page).locator('.item-card').filter({ hasText: ROUTINE_NAME })
+    await card.waitFor({ state: 'visible' })
+
+    // First click enters ready state
+    await card.click()
+    await expect(card).toHaveClass(/item-ready/, { timeout: 3000 })
+
+    // Second click opens overlay
+    await card.click()
+
+    const dialog = page.getByRole('dialog')
+    await expect(dialog).toBeVisible({ timeout: 3000 })
+    await expect(dialog).toContainText('Did you complete')
+    await expect(dialog).toContainText(ROUTINE_NAME)
+  })
+
+  // ── 3. Task cards inside overlay ──────────────────────────────────────────
+
+  test('Overlay shows task cards for each routine item', async ({ page }) => {
+    await page.goto(`/child/${childId}`)
+
+    const card = routineSection(page).locator('.item-card').filter({ hasText: ROUTINE_NAME })
+    await card.waitFor({ state: 'visible' })
+    await card.click()
+    await expect(card).toHaveClass(/item-ready/, { timeout: 3000 })
+    await card.click()
+
+    const dialog = page.getByRole('dialog')
+    await expect(dialog).toBeVisible({ timeout: 3000 })
+    await expect(dialog.getByText(TASK_NAME_1)).toBeVisible()
+    await expect(dialog.getByText(TASK_NAME_2)).toBeVisible()
+  })
+
+  // ── 4. Closing overlay with No ────────────────────────────────────────────
+
+  test('Clicking No closes the overlay without changing state', async ({ page }) => {
+    await page.goto(`/child/${childId}`)
+
+    const card = routineSection(page).locator('.item-card').filter({ hasText: ROUTINE_NAME })
+    await card.waitFor({ state: 'visible' })
+    await card.click()
+    await expect(card).toHaveClass(/item-ready/, { timeout: 3000 })
+    await card.click()
+
+    const dialog = page.getByRole('dialog')
+    await expect(dialog).toBeVisible({ timeout: 3000 })
+    await dialog.getByRole('button', { name: 'No' }).click()
+
+    await expect(dialog).not.toBeVisible({ timeout: 3000 })
+    await expect(card.locator('.pending-stamp')).not.toBeVisible()
+  })
+
+  // ── 5. Yes! confirms routine → PENDING stamp ──────────────────────────────
+
+  test('Clicking Yes! marks routine as PENDING', async ({ page }) => {
+    await page.goto(`/child/${childId}`)
+
+    const card = routineSection(page).locator('.item-card').filter({ hasText: ROUTINE_NAME })
+    await card.waitFor({ state: 'visible' })
+    await card.click()
+    await expect(card).toHaveClass(/item-ready/, { timeout: 3000 })
+    await card.click()
+
+    const dialog = page.getByRole('dialog')
+    await expect(dialog).toBeVisible({ timeout: 3000 })
+    await dialog.getByRole('button', { name: 'Yes!' }).click()
+
+    // Dialog closes
+    await expect(dialog).not.toBeVisible({ timeout: 5000 })
+
+    // Reload to pick up the refreshed state
+    await page.reload()
+    const reloadedCard = routineSection(page)
+      .locator('.item-card')
+      .filter({ hasText: ROUTINE_NAME })
+    await expect(reloadedCard.locator('.pending-stamp')).toBeVisible({ timeout: 5000 })
+  })
+
+  // ── 6. Cancel dialog for pending routine ─────────────────────────────────
+
+  test('Clicking a pending routine shows the cancel dialog', async ({ page }) => {
+    await page.goto(`/child/${childId}`)
+
+    // Routine should still be pending from the previous test
+    const card = routineSection(page).locator('.item-card').filter({ hasText: ROUTINE_NAME })
+    await card.waitFor({ state: 'visible' })
+    await expect(card.locator('.pending-stamp')).toBeVisible({ timeout: 5000 })
+
+    await card.click()
+    await expect(card).toHaveClass(/item-ready/, { timeout: 3000 })
+    await card.click()
+
+    const dialog = page.getByRole('dialog')
+    await expect(dialog).toBeVisible({ timeout: 3000 })
+    await expect(dialog).toContainText('This routine is pending')
+  })
+
+  // ── 7. Canceling pending routine removes PENDING stamp ────────────────────
+
+  test('Confirming cancel removes the PENDING stamp', async ({ page }) => {
+    await page.goto(`/child/${childId}`)
+
+    const card = routineSection(page).locator('.item-card').filter({ hasText: ROUTINE_NAME })
+    await card.waitFor({ state: 'visible' })
+    await card.click()
+    await expect(card).toHaveClass(/item-ready/, { timeout: 3000 })
+    await card.click()
+
+    const dialog = page.getByRole('dialog')
+    await expect(dialog).toBeVisible({ timeout: 3000 })
+    await expect(dialog).toContainText('This routine is pending')
+
+    // "Yes" cancels the pending confirmation
+    await dialog.getByRole('button', { name: 'Yes' }).click()
+
+    await expect(dialog).not.toBeVisible({ timeout: 5000 })
+
+    await page.reload()
+    const reloadedCard = routineSection(page)
+      .locator('.item-card')
+      .filter({ hasText: ROUTINE_NAME })
+    await expect(reloadedCard.locator('.pending-stamp')).not.toBeVisible({ timeout: 5000 })
+  })
+})

frontend/e2e/mode_parent/routines/routine-item-reorder.spec.ts

@@ -0,0 +1,77 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+
+const ROUTINE_NAME = 'ReorderTestRoutine'
+const ROUTINE_POINTS = 10
+const ITEM_A = 'Alpha Task'
+const ITEM_B = 'Beta Task'
+const ITEM_C = 'Gamma Task'
+
+async function createRoutine(
+  request: APIRequestContext,
+  name: string,
+  points: number,
+): Promise<string> {
+  const pre = await request.get('/api/routine/list')
+  for (const r of (await pre.json()).routines ?? []) {
+    if (r.name === name) await request.delete(`/api/routine/${r.id}`)
+  }
+  const res = await request.put('/api/routine/add', { data: { name, points } })
+  return (await res.json()).routine?.id ?? ''
+}
+
+test.describe('Routine item drag-to-reorder', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  let routineId = ''
+
+  test.beforeAll(async ({ request }) => {
+    routineId = await createRoutine(request, ROUTINE_NAME, ROUTINE_POINTS)
+    await request.put(`/api/routine/${routineId}/item/add`, { data: { name: ITEM_A, order: 0 } })
+    await request.put(`/api/routine/${routineId}/item/add`, { data: { name: ITEM_B, order: 1 } })
+    await request.put(`/api/routine/${routineId}/item/add`, { data: { name: ITEM_C, order: 2 } })
+  })
+
+  test.afterAll(async ({ request }) => {
+    if (routineId) await request.delete(`/api/routine/${routineId}`)
+  })
+
+  test('items load in correct initial order', async ({ page }) => {
+    await page.goto(`/parent/tasks/routines/${routineId}/edit`)
+    await page.locator('.item-row').first().waitFor({ state: 'visible' })
+
+    const names = await page.locator('.item-name').allTextContents()
+    expect(names).toEqual([ITEM_A, ITEM_B, ITEM_C])
+  })
+
+  test('dragging first item to last position reorders the list in the UI', async ({ page }) => {
+    await page.goto(`/parent/tasks/routines/${routineId}/edit`)
+    await page.locator('.item-row').first().waitFor({ state: 'visible' })
+
+    await page.locator('.item-row').nth(0).locator('.drag-handle').dragTo(page.locator('.item-row').nth(2))
+
+    const names = await page.locator('.item-name').allTextContents()
+    expect(names).toEqual([ITEM_B, ITEM_C, ITEM_A])
+  })
+
+  test('reordered item order persists after saving', async ({ page }) => {
+    await page.goto(`/parent/tasks/routines/${routineId}/edit`)
+    await page.locator('.item-row').first().waitFor({ state: 'visible' })
+
+    // Drag first to last: [A, B, C] → [B, C, A]
+    await page.locator('.item-row').nth(0).locator('.drag-handle').dragTo(page.locator('.item-row').nth(2))
+
+    // Confirm the drag updated the DOM before saving
+    const afterDrag = await page.locator('.item-name').allTextContents()
+    expect(afterDrag).toEqual([ITEM_B, ITEM_C, ITEM_A])
+
+    await page.getByRole('button', { name: 'Save' }).click()
+    await page.waitForURL(/\/parent\/tasks\/routines$/, { timeout: 5000 })
+
+    // Reload edit view — should now show the saved order
+    await page.goto(`/parent/tasks/routines/${routineId}/edit`)
+    await page.locator('.item-row').first().waitFor({ state: 'visible' })
+
+    const names = await page.locator('.item-name').allTextContents()
+    expect(names).toEqual([ITEM_B, ITEM_C, ITEM_A])
+  })
+})

frontend/e2e/mode_parent/routines/routine-notification.spec.ts

@@ -0,0 +1,98 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+
+const CHILD_NAME = 'RoutineNotifChild'
+const ROUTINE_NAME = 'RoutineNotifTest'
+const ROUTINE_POINTS = 8
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+async function createChild(request: APIRequestContext, name: string): Promise<string> {
+  const pre = await request.get('/api/child/list')
+  for (const c of (await pre.json()).children ?? []) {
+    if (c.name === name) await request.delete(`/api/child/${c.id}`)
+  }
+  await request.put('/api/child/add', { data: { name, age: 8 } })
+  const list = await request.get('/api/child/list')
+  return (await list.json()).children?.find((c: any) => c.name === name)?.id ?? ''
+}
+
+async function createRoutine(
+  request: APIRequestContext,
+  name: string,
+  points: number,
+): Promise<string> {
+  const pre = await request.get('/api/routine/list')
+  for (const r of (await pre.json()).routines ?? []) {
+    if (r.name === name) await request.delete(`/api/routine/${r.id}`)
+  }
+  const res = await request.put('/api/routine/add', { data: { name, points } })
+  return (await res.json()).routine?.id ?? ''
+}
+
+// ── suite ─────────────────────────────────────────────────────────────────────
+
+test.describe('Routine parent notification', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  let childId = ''
+  let routineId = ''
+
+  test.beforeAll(async ({ request }) => {
+    childId = await createChild(request, CHILD_NAME)
+    routineId = await createRoutine(request, ROUTINE_NAME, ROUTINE_POINTS)
+
+    await request.post(`/api/child/${childId}/assign-routine`, {
+      data: { routine_id: routineId },
+    })
+
+    // Simulate the child confirming the routine
+    await request.post(`/api/child/${childId}/confirm-routine`, {
+      data: { routine_id: routineId },
+    })
+  })
+
+  test.afterAll(async ({ request }) => {
+    if (childId) await request.delete(`/api/child/${childId}`)
+    if (routineId) await request.delete(`/api/routine/${routineId}`)
+  })
+
+  // ── 1. Notification appears ───────────────────────────────────────────────
+
+  test('Confirmed routine appears in notification view', async ({ page }) => {
+    await page.goto('/parent/notifications')
+    const item = page.locator('.list-item').filter({ hasText: ROUTINE_NAME })
+    await expect(item).toBeVisible({ timeout: 5000 })
+  })
+
+  // ── 2. Notification shows "completed" ────────────────────────────────────
+
+  test('Notification shows "completed" for routine', async ({ page }) => {
+    await page.goto('/parent/notifications')
+    const item = page.locator('.list-item').filter({ hasText: ROUTINE_NAME })
+    await expect(item).toBeVisible({ timeout: 5000 })
+    await expect(item).toContainText('completed')
+  })
+
+  // ── 3. Notification shows child name ─────────────────────────────────────
+
+  test('Notification shows the child name', async ({ page }) => {
+    await page.goto('/parent/notifications')
+    const item = page.locator('.list-item').filter({ hasText: ROUTINE_NAME })
+    await expect(item).toBeVisible({ timeout: 5000 })
+    await expect(item).toContainText(CHILD_NAME)
+  })
+
+  // ── 4. Clicking notification navigates to parent view ────────────────────
+
+  test('Clicking notification navigates to parent view for the child', async ({ page }) => {
+    await page.goto('/parent/notifications')
+    const item = page.locator('.list-item').filter({ hasText: ROUTINE_NAME })
+    await expect(item).toBeVisible({ timeout: 5000 })
+    await item.click()
+
+    await page.waitForURL(`/parent/${childId}**`, { timeout: 5000 })
+    const url = new URL(page.url())
+    expect(url.searchParams.get('scrollTo')).toBe(routineId)
+    expect(url.searchParams.get('entityType')).toBe('routine')
+  })
+})

frontend/e2e/mode_parent/task-activation/pending-reward-warning.spec.ts

@@ -59,7 +59,9 @@ async function createReward(
   for (const r of (await pre.json()).rewards ?? []) {
     if (r.name === name) await request.delete(`/api/reward/${r.id}`)
   }
-  await request.put('/api/reward/add', { data: { name, description: 'E2E pending-warn test', cost } })
+  await request.put('/api/reward/add', {
+    data: { name, description: 'E2E pending-warn test', cost },
+  })
   const list = await request.get('/api/reward/list')
   return (await list.json()).rewards?.find((r: any) => r.name === name)?.id ?? ''
 }
@@ -160,9 +162,7 @@ test.describe('Pending reward warning dialog', () => {
 
   test('Pending reward card shows PENDING banner', async ({ page }) => {
     await page.goto(`/parent/${childId}`)
-    const card = rewardSection(page)
-      .locator('.item-card')
-      .filter({ hasText: PENDING_REWARD_NAME })
+    const card = rewardSection(page).locator('.item-card').filter({ hasText: PENDING_REWARD_NAME })
     await card.waitFor({ state: 'visible' })
     await expect(card.locator('.pending')).toHaveText('PENDING')
   })
@@ -177,12 +177,12 @@ test.describe('Pending reward warning dialog', () => {
 
     await activateItem(card)
 
-    // Pending reward warning dialog appears (has a "No" button)
-    await expect(page.getByRole('button', { name: 'No', exact: true })).toBeVisible()
-    await page.getByRole('button', { name: 'No', exact: true }).click()
+    // Pending reward warning dialog appears
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).toBeVisible()
+    await page.getByRole('button', { name: 'Reject', exact: true }).click()
 
     // Dialog dismissed; task confirmation dialog must NOT have appeared
-    await expect(page.getByRole('button', { name: 'No', exact: true })).not.toBeVisible()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).not.toBeVisible()
     await expect(page.getByRole('button', { name: 'Cancel' })).not.toBeVisible()
     // Points unchanged
     await expect(page.locator('.points .value')).toHaveText(String(pointsBefore))
@@ -204,8 +204,8 @@ test.describe('Pending reward warning dialog', () => {
     await activateItem(card)
 
     // Pending reward warning dialog
-    await expect(page.getByRole('button', { name: 'No', exact: true })).toBeVisible()
-    await page.getByRole('button', { name: 'Yes' }).click()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).toBeVisible()
+    await page.getByRole('button', { name: 'Approve', exact: true }).click()
 
     // After confirming, the task confirmation dialog appears (has "Cancel" button)
     await expect(page.getByRole('button', { name: 'Cancel' })).toBeVisible({ timeout: 3000 })
@@ -219,7 +219,9 @@ test.describe('Pending reward warning dialog', () => {
 
   // ── kindness ──────────────────────────────────────────────────────────────
 
-  test('Kindness activation — Cancel on pending dialog leaves state unchanged', async ({ page }) => {
+  test('Kindness activation — Cancel on pending dialog leaves state unchanged', async ({
+    page,
+  }) => {
     await page.goto(`/parent/${childId}`)
     const card = kindnessSection(page).locator('.item-card').filter({ hasText: KIND_NAME })
     await card.waitFor({ state: 'visible' })
@@ -227,10 +229,10 @@ test.describe('Pending reward warning dialog', () => {
 
     await activateItem(card)
 
-    await expect(page.getByRole('button', { name: 'No', exact: true })).toBeVisible()
-    await page.getByRole('button', { name: 'No', exact: true }).click()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).toBeVisible()
+    await page.getByRole('button', { name: 'Reject', exact: true }).click()
 
-    await expect(page.getByRole('button', { name: 'No', exact: true })).not.toBeVisible()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).not.toBeVisible()
     await expect(page.getByRole('button', { name: 'Cancel' })).not.toBeVisible()
     await expect(page.locator('.points .value')).toHaveText(String(pointsBefore))
   })
@@ -245,8 +247,8 @@ test.describe('Pending reward warning dialog', () => {
 
     await activateItem(card)
 
-    await expect(page.getByRole('button', { name: 'No', exact: true })).toBeVisible()
-    await page.getByRole('button', { name: 'Yes' }).click()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).toBeVisible()
+    await page.getByRole('button', { name: 'Approve', exact: true }).click()
 
     await expect(page.getByRole('button', { name: 'Cancel' })).toBeVisible({ timeout: 3000 })
     await page.getByRole('button', { name: 'Yes' }).click()
@@ -266,10 +268,10 @@ test.describe('Pending reward warning dialog', () => {
 
     await activateItem(card)
 
-    await expect(page.getByRole('button', { name: 'No', exact: true })).toBeVisible()
-    await page.getByRole('button', { name: 'No', exact: true }).click()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).toBeVisible()
+    await page.getByRole('button', { name: 'Reject', exact: true }).click()
 
-    await expect(page.getByRole('button', { name: 'No', exact: true })).not.toBeVisible()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).not.toBeVisible()
     await expect(page.getByRole('button', { name: 'Cancel' })).not.toBeVisible()
     await expect(page.locator('.points .value')).toHaveText(String(pointsBefore))
   })
@@ -284,8 +286,8 @@ test.describe('Pending reward warning dialog', () => {
 
     await activateItem(card)
 
-    await expect(page.getByRole('button', { name: 'No', exact: true })).toBeVisible()
-    await page.getByRole('button', { name: 'Yes' }).click()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).toBeVisible()
+    await page.getByRole('button', { name: 'Approve', exact: true }).click()
 
     await expect(page.getByRole('button', { name: 'Cancel' })).toBeVisible({ timeout: 3000 })
     await page.getByRole('button', { name: 'Yes' }).click()
@@ -320,10 +322,10 @@ test.describe('Pending reward warning dialog', () => {
     await activateItem(otherCard)
 
     // Pending reward warning dialog appears when another reward has a pending request
-    await expect(page.getByRole('button', { name: 'No', exact: true })).toBeVisible()
-    await page.getByRole('button', { name: 'No', exact: true }).click()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).toBeVisible()
+    await page.getByRole('button', { name: 'Reject', exact: true }).click()
 
-    await expect(page.getByRole('button', { name: 'No', exact: true })).not.toBeVisible()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).not.toBeVisible()
     await expect(page.getByRole('button', { name: 'Cancel' })).not.toBeVisible()
     await expect(page.locator('.points .value')).toHaveText(String(pointsBefore))
     // PENDING banner still visible — reward request was not cancelled
@@ -346,11 +348,11 @@ test.describe('Pending reward warning dialog', () => {
 
     await activateItem(otherCard)
 
-    await expect(page.getByRole('button', { name: 'No', exact: true })).toBeVisible()
-    await page.getByRole('button', { name: 'Yes' }).click()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).toBeVisible()
+    await page.getByRole('button', { name: 'Approve', exact: true }).click()
 
     // Pending dialog closes; reward confirm does NOT auto-open (other reward must be re-clicked)
-    await expect(page.getByRole('button', { name: 'No', exact: true })).not.toBeVisible()
+    await expect(page.getByRole('button', { name: 'Reject', exact: true })).not.toBeVisible()
     await expect(page.getByRole('button', { name: 'Cancel' })).not.toBeVisible()
 
     // The pending reward request was cancelled — PENDING banner should disappear

frontend/e2e/mode_parent/task-activation/reward-redemption.spec.ts

@@ -152,7 +152,7 @@ test.describe('Reward redemption', () => {
 
     await activateItem(card)
     await expect(page.getByRole('button', { name: 'Yes' })).toBeVisible()
-    await page.getByRole('button', { name: 'Cancel' }).click()
+    await page.getByRole('button', { name: 'No', exact: true }).click()
 
     await expect(page.getByRole('button', { name: 'Yes' })).not.toBeVisible()
     await expect(page.locator('.points .value')).toHaveText(String(before))

frontend/e2e/mode_parent/task-assignment/assign-create-fab.spec.ts

@@ -0,0 +1,133 @@
+import { test, expect, type APIRequestContext } from '@playwright/test'
+
+const CHILD_NAME = 'AssignFabChild'
+const CHORE_NAME = 'AssignFabChore'
+const KINDNESS_NAME = 'AssignFabKindness'
+const PENALTY_NAME = 'AssignFabPenalty'
+const REWARD_NAME = 'AssignFabReward'
+const ROUTINE_NAME = 'AssignFabRoutine'
+
+async function createChild(request: APIRequestContext, name: string): Promise<string> {
+  const pre = await request.get('/api/child/list')
+  for (const c of (await pre.json()).children ?? []) {
+    if (c.name === name) await request.delete(`/api/child/${c.id}`)
+  }
+  await request.put('/api/child/add', { data: { name, age: 8 } })
+  const list = await request.get('/api/child/list')
+  return (
+    (await list.json()).children?.find((c: { name: string; id: string }) => c.name === name)?.id ??
+    ''
+  )
+}
+
+async function createTask(
+  request: APIRequestContext,
+  name: string,
+  type: 'chore' | 'kindness' | 'penalty',
+): Promise<string> {
+  const pre = await request.get('/api/task/list')
+  for (const t of (await pre.json()).tasks ?? []) {
+    if (t.name === name) await request.delete(`/api/task/${t.id}`)
+  }
+  await request.put('/api/task/add', { data: { name, points: 5, type } })
+  const list = await request.get('/api/task/list')
+  return (
+    (await list.json()).tasks?.find((t: { name: string; id: string }) => t.name === name)?.id ?? ''
+  )
+}
+
+async function createReward(request: APIRequestContext, name: string): Promise<string> {
+  const pre = await request.get('/api/reward/list')
+  for (const r of (await pre.json()).rewards ?? []) {
+    if (r.name === name) await request.delete(`/api/reward/${r.id}`)
+  }
+  await request.put('/api/reward/add', { data: { name, description: 'E2E fab reward', cost: 10 } })
+  const list = await request.get('/api/reward/list')
+  return (
+    (await list.json()).rewards?.find((r: { name: string; id: string }) => r.name === name)?.id ??
+    ''
+  )
+}
+
+async function createRoutine(request: APIRequestContext, name: string): Promise<string> {
+  const pre = await request.get('/api/routine/list')
+  for (const r of (await pre.json()).routines ?? []) {
+    if (r.name === name) await request.delete(`/api/routine/${r.id}`)
+  }
+  const res = await request.put('/api/routine/add', { data: { name, points: 5 } })
+  return (await res.json()).routine?.id ?? ''
+}
+
+test.describe('Assignment views create FAB', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  let childId = ''
+  let choreId = ''
+  let kindnessId = ''
+  let penaltyId = ''
+  let rewardId = ''
+  let routineId = ''
+
+  test.beforeAll(async ({ request }) => {
+    childId = await createChild(request, CHILD_NAME)
+    choreId = await createTask(request, CHORE_NAME, 'chore')
+    kindnessId = await createTask(request, KINDNESS_NAME, 'kindness')
+    penaltyId = await createTask(request, PENALTY_NAME, 'penalty')
+    rewardId = await createReward(request, REWARD_NAME)
+    routineId = await createRoutine(request, ROUTINE_NAME)
+  })
+
+  test.afterAll(async ({ request }) => {
+    if (childId) await request.delete(`/api/child/${childId}`)
+    if (choreId) await request.delete(`/api/task/${choreId}`)
+    if (kindnessId) await request.delete(`/api/task/${kindnessId}`)
+    if (penaltyId) await request.delete(`/api/task/${penaltyId}`)
+    if (rewardId) await request.delete(`/api/reward/${rewardId}`)
+    if (routineId) await request.delete(`/api/routine/${routineId}`)
+  })
+
+  test('Chore assign view FAB navigates to chore creator', async ({ page }) => {
+    await page.goto(`/parent/${childId}/assign-chores?name=${CHILD_NAME}`)
+    await expect(page.getByRole('heading', { name: 'Assign Chores' })).toBeVisible()
+
+    await page.getByRole('button', { name: 'Create Chore' }).click()
+    await page.waitForURL(/\/parent\/tasks\/chores\/create$/)
+    await expect(page.getByRole('heading', { name: 'Create Chore' })).toBeVisible()
+  })
+
+  test('Kindness assign view FAB navigates to kindness creator', async ({ page }) => {
+    await page.goto(`/parent/${childId}/assign-kindness?name=${CHILD_NAME}`)
+    await expect(page.getByRole('heading', { name: 'Assign Kindness Acts' })).toBeVisible()
+
+    await page.getByRole('button', { name: 'Create Kindness Act' }).click()
+    await page.waitForURL(/\/parent\/tasks\/kindness\/create$/)
+    await expect(page.getByRole('heading', { name: 'Create Kindness Act' })).toBeVisible()
+  })
+
+  test('Penalty assign view FAB navigates to penalty creator', async ({ page }) => {
+    await page.goto(`/parent/${childId}/assign-penalties?name=${CHILD_NAME}`)
+    await expect(page.getByRole('heading', { name: 'Assign Penalties' })).toBeVisible()
+
+    await page.getByRole('button', { name: 'Create Penalty' }).click()
+    await page.waitForURL(/\/parent\/tasks\/penalties\/create$/)
+    await expect(page.getByRole('heading', { name: 'Create Penalty' })).toBeVisible()
+  })
+
+  test('Reward assign view FAB navigates to reward creator', async ({ page }) => {
+    await page.goto(`/parent/${childId}/assign-rewards?name=${CHILD_NAME}`)
+    await expect(page.getByRole('heading', { name: 'Assign Rewards' })).toBeVisible()
+
+    await page.getByRole('button', { name: 'Create Reward' }).click()
+    await page.waitForURL(/\/parent\/rewards\/create$/)
+    await expect(page.getByRole('heading', { name: 'Create Reward' })).toBeVisible()
+  })
+
+  test('Routine assign view FAB navigates to routine creator', async ({ page }) => {
+    await page.goto(`/parent/${childId}/assign-routines?name=${CHILD_NAME}`)
+    await expect(page.getByRole('heading', { name: 'Assign Routines' })).toBeVisible()
+
+    await page.getByRole('button', { name: 'Create Routine' }).click()
+    await page.waitForURL(/\/parent\/tasks\/routines\/create$/)
+    await expect(page.getByRole('heading', { name: 'Create Routine' })).toBeVisible()
+  })
+})

frontend/e2e/mode_parent/task-modification/reward-edit-cost.spec.ts

@@ -45,6 +45,28 @@ async function openEditModal(page: Page, card: Locator): Promise<void> {
   await expect(page.getByRole('button', { name: 'Save' })).toBeVisible()
 }
 
+async function seedPendingReward(
+  request: APIRequestContext,
+  childId: string,
+  rewardId: string,
+  rewardCost: number,
+): Promise<void> {
+  await request.put(`/api/child/${childId}/edit`, { data: { points: rewardCost } })
+
+  const requestResp = await request.post(`/api/child/${childId}/request-reward`, {
+    data: { reward_id: rewardId },
+  })
+
+  if (requestResp.status() === 409) {
+    await request.post(`/api/child/${childId}/cancel-request-reward`, {
+      data: { reward_id: rewardId },
+    })
+    await request.post(`/api/child/${childId}/request-reward`, {
+      data: { reward_id: rewardId },
+    })
+  }
+}
+
 test.describe('Reward edit cost', () => {
   test.describe.configure({ mode: 'serial' })
 
@@ -172,9 +194,8 @@ test.describe('Reward edit cost', () => {
     page,
     request,
   }) => {
-    // Give child enough points to satisfy the original reward cost, then create a pending request
-    await request.put(`/api/child/${childId}/edit`, { data: { points: REWARD_COST } })
-    await request.post(`/api/child/${childId}/request-reward`, { data: { reward_id: rewardId } })
+    // Ensure a fresh pending request exists for this test.
+    await seedPendingReward(request, childId, rewardId, REWARD_COST)
 
     await page.goto(`/parent/${childId}`)
     const card = rewardSection(page).locator('.item-card').filter({ hasText: REWARD_NAME })
@@ -187,18 +208,21 @@ test.describe('Reward edit cost', () => {
     await card.getByTitle('Edit custom value').click()
 
     // PendingRewardDialog should appear warning about the pending state
-    await expect(page.locator('.modal-message')).toContainText('pending')
+    await expect(page.getByText(/currently pending/i)).toBeVisible()
 
-    // Clicking "No" closes the dialog without opening the override modal
-    await page.getByRole('button', { name: 'No', exact: true }).click()
-    await expect(page.locator('.modal-message')).not.toBeVisible()
+    // Clicking "Reject" closes the dialog without opening the override modal
+    await page.getByRole('button', { name: 'Reject', exact: true }).click()
+    await expect(page.getByText(/currently pending/i)).not.toBeVisible()
     await expect(page.getByRole('button', { name: 'Save' })).not.toBeVisible()
   })
 
   test('Editing a pending reward — confirming the warning opens the override modal', async ({
     page,
+    request,
   }) => {
-    // Pending state was established in the previous test; navigate fresh
+    // Seed pending state in this test to avoid cross-test coupling.
+    await seedPendingReward(request, childId, rewardId, REWARD_COST)
+
     await page.goto(`/parent/${childId}`)
     const card = rewardSection(page).locator('.item-card').filter({ hasText: REWARD_NAME })
     await card.waitFor({ state: 'visible' })
@@ -209,10 +233,10 @@ test.describe('Reward edit cost', () => {
     await card.getByTitle('Edit custom value').click()
 
     // PendingRewardDialog visible
-    await expect(page.locator('.modal-message')).toContainText('pending')
+    await expect(page.getByText(/currently pending/i)).toBeVisible()
 
     // Confirming cancels the pending request and opens the override modal
-    await page.getByRole('button', { name: 'Yes' }).click()
+    await page.getByRole('button', { name: 'Approve', exact: true }).click()
     await expect(page.getByRole('button', { name: 'Save' })).toBeVisible({ timeout: 5000 })
     await page.getByRole('button', { name: 'Cancel' }).click()
   })