From 78ad4044f9c449104b41f96818bf12ddfa8e662a Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 14 Feb 2026 19:18:20 -0800
Subject: [PATCH 01/55] feat: add AI agent instructions for Digitization
 Toolkit

---
 .github/copilot-instructions.md | 257 ++++++++++++++++++++++++++++++++
 1 file changed, 257 insertions(+)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..04d3344
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,257 @@
+# AI Agent Instructions for Digitization Toolkit
+
+## Project Overview
+
+Offline-capable digitization toolkit for Raspberry Pi with dual camera support. FastAPI backend + Svelte frontend + PostgreSQL. Designed for standalone deployment in low-resource environments (archives, community centers).
+
+**Critical Architecture Decision:** Backend runs **natively** (not in Docker) to access Raspberry Pi hardware (libcamera, picamera2). Database and frontend run in Docker.
+
+## Core Architecture Patterns
+
+### 1. Dual Deployment Modes
+
+```bash
+# Development (any machine, no cameras): All services in Docker
+./scripts/start-dev.sh  # or: docker compose --profile with-backend up
+
+# Production (Raspberry Pi with cameras): Native backend + Docker DB
+./scripts/start.sh      # or: docker compose up -d && ./scripts/run_backend_native_pixi.sh
+```
+
+**Why:** System camera libraries (python3-libcamera, python3-kms++) cannot be installed via pip and must be accessed from system packages.
+
+### 2. Camera Backend Plugin System
+
+Two interchangeable backends via `CAMERA_BACKEND` env var:
+- **picamera2** (default): Direct libcamera2 bindings, 91.5% faster, supports live preview
+- **subprocess**: Fallback using rpicam-still CLI, more compatible
+
+Implementation: [backend/capture/backends/](backend/capture/backends/)
+- `base.py`: Abstract `CameraBackend` class
+- `picamera2_backend.py`: Native picamera2 implementation  
+- `subprocess_backend.py`: CLI wrapper via rpicam-still
+
+Switch backends: Set `CAMERA_BACKEND=subprocess` in `.env`
+
+### 3. Hardware Identification System
+
+Cameras identified by **hardware ID** (model + serial), not index (0, 1). Prevents config loss when cables swap.
+
+```python
+# backend/capture/camera_registry.py
+class CameraRegistry:
+    """Global registry at PROJECTS_ROOT/cameras.json tracks:
+    - Hardware IDs (arducam_imx519_<serial>)
+    - Per-camera calibration matrices
+    - Role assignments (left/right)
+    - Human-friendly labels
+    """
+```
+
+API layer ([backend/app/api/cameras.py](backend/app/api/cameras.py)) uses index for simplicity, but core capture layer uses hardware IDs.
+
+## Database & Migrations: CRITICAL RULES
+
+### ⚠️ NEVER Add `Base.metadata.create_all()`
+
+Tables are managed **exclusively through Alembic migrations**. This is not negotiable.
+
+**WRONG:**
+```python
+# app/core/db.py
+def init_db():
+    Base.metadata.create_all(bind=engine)  # ❌ NEVER DO THIS
+```
+
+**CORRECT:**
+```python
+# app/core/db.py
+def init_db() -> None:
+    """Import all models to register them with SQLAlchemy."""
+    import app.models.document  # Just import, no create_all()
+    import app.models.camera
+    import app.models.project
+    import app.models.user
+```
+
+### Workflow for Schema Changes
+
+1. Modify model in `app/models/`
+2. Generate migration: `docker compose exec backend alembic revision --autogenerate -m "description"`
+3. Review generated file in `backend/alembic/versions/`
+4. Apply: `docker compose exec backend alembic upgrade head`
+
+**Native backend with pixi:**
+```bash
+cd backend
+pixi run db-migrate "add new column"  # Generate migration
+pixi run db-upgrade                   # Apply migration
+```
+
+### PostgreSQL Connection Format
+
+Use `postgresql+psycopg://` (psycopg3), **not** `postgresql://` (legacy psycopg2).
+
+```python
+# app/core/config.py
+DATABASE_URL = f"postgresql+psycopg://{user}:{password}@{host}:{port}/{database}"
+```
+
+## Authentication System
+
+**Custom HMAC token system** for offline/standalone operation. Do NOT suggest replacing with JWT libraries (python-jose, PyJWT) or OAuth2.
+
+```python
+# app/core/security.py
+def create_access_token(subject: str) -> str:
+    """Custom token: {b64u(payload)}.{b64u(hmac_sig)}"""
+    # No external JWT library needed for offline Raspberry Pi
+```
+
+Why: Intentionally lightweight for embedded deployment, no OAuth2 providers, minimal dependencies.
+
+## Configuration Management
+
+**Only add settings that application code actually uses.** Infrastructure settings belong in `docker-compose.yml`.
+
+```python
+# app/core/config.py
+class Settings(BaseSettings):
+    DATABASE_USER: str = "user"
+    CAMERA_BACKEND: str = "picamera2"  # ✅ Used by camera registry
+    # NOT: uvicorn_host - that's infrastructure, not application logic
+```
+
+Settings pattern:
+- `Settings` class loads from `.env` via pydantic-settings
+- Computed properties for paths: `projects_dir`, `exports_dir`, `data_dir`
+- Accessed globally via `from app.core.config import settings`
+
+## Dependency Management: Pixi (Recommended)
+
+Project migrated from venv to **pixi** for better reproducibility.
+
+```bash
+# First time setup
+cd backend
+pixi install
+pixi run setup-camera-link  # Raspberry Pi only: links system camera packages
+
+# Common commands
+pixi run dev              # Start dev server
+pixi run test             # Run pytest
+pixi run db-upgrade       # Apply migrations
+pixi add package-name     # Add dependency
+```
+
+Configuration: [backend/pixi.toml](backend/pixi.toml)
+
+**System Package Linking (Raspberry Pi):** Picamera2 requires system-installed libcamera bindings. Pixi task `setup-camera-link` creates `.pth` file to expose `/usr/lib/python3/dist-packages`.
+
+Legacy venv still works but pixi preferred for new development.
+
+## Testing Strategy
+
+```bash
+# Backend tests (in backend/ directory)
+pixi run test                  # All tests
+pixi run test-cameras          # Camera-specific integration tests
+pixi run test-verbose          # Pytest with -v
+
+# Check camera hardware detection
+rpicam-hello --list-cameras
+```
+
+Camera tests handle both backends gracefully, skip if hardware unavailable.
+
+## File Organization
+
+```
+backend/
+├── app/                    # FastAPI application
+│   ├── api/               # Route handlers (documents, cameras, projects, auth)
+│   ├── core/              # Config, DB, security
+│   ├── models/            # SQLAlchemy models
+│   └── schemas/           # Pydantic schemas
+├── capture/               # Camera capture service (hardware layer)
+│   ├── backends/         # Pluggable camera backends
+│   ├── camera_registry.py # Hardware ID tracking
+│   ├── calibration.py    # Camera calibration
+│   └── project_manager.py # Capture orchestration
+├── alembic/               # Database migrations
+└── pixi.toml              # Dependency management
+
+frontend/
+└── src/
+    ├── lib/              # Shared components/utilities
+    └── routes/           # SvelteKit pages
+```
+
+## Documentation Policy for AI Agents
+
+**DO NOT create new standalone documentation files** (README.md, GUIDE.md, NOTES.md, etc.) for recording changes or providing instructions.
+
+Instead:
+- **Update THIS file** (.github/copilot-instructions.md) with new patterns or architectural decisions
+- **Create .github/skills/*.md** for reusable procedures (e.g., "how to add a new camera backend")
+- **Update existing docs** (backend/DEVELOPMENT.md, backend/DEPENDENCIES.md) if adding technical details
+
+**Never create:**
+- ❌ CHANGELOG.md, UPDATES.md, NOTES.md - Use git commits
+- ❌ SETUP.md, QUICKSTART.md, CHEATSHEET.md - Info belongs in README.md
+- ❌ INSTRUCTIONS.md, AGENT.md - Update this file instead
+- ❌ Informational "status update" files - These are traceback logs, not documentation
+
+**If you need to document something important:** Ask yourself "Will another AI agent need to know this to avoid mistakes?" If yes, add it to this file. If it's a repeatable procedure, create a skill file.
+
+## Common Mistakes AI Agents Make
+
+1. ❌ Re-adding `Base.metadata.create_all()` after it was intentionally removed
+2. ❌ Suggesting JWT/OAuth2 for a standalone offline application
+3. ❌ Adding unused config fields "just in case" to Settings
+4. ❌ Using `postgresql://` instead of `postgresql+psycopg://`
+5. ❌ Creating migrations outside Docker (wrong database host)
+6. ❌ Forgetting backend must run natively for camera access
+7. ❌ Breaking hardware ID system by reverting to index-based camera refs
+8. ❌ Creating new documentation files instead of updating existing ones
+
+## Quick Reference Commands
+
+```bash
+# Start full stack development (no cameras)
+./scripts/start-dev.sh
+
+# Start production with cameras
+./scripts/start.sh
+
+# Backend only (native)
+cd backend && pixi run dev
+
+# Apply database migrations
+docker compose exec backend alembic upgrade head
+# OR: cd backend && pixi run db-upgrade
+
+# Camera testing
+rpicam-hello --list-cameras
+cd backend && pixi run test-cameras
+
+# Check database connection
+docker compose exec backend python -c "from app.core.db import engine; from sqlalchemy import inspect; print(inspect(engine).get_table_names())"
+```
+
+## Documentation References
+
+- [DEVELOPMENT.md](backend/DEVELOPMENT.md) - Critical development guidelines
+- [DEPENDENCIES.md](backend/DEPENDENCIES.md) - Camera system dependencies
+- [README.md](README.md) - Setup instructions and quick start
+
+## Context for Code Generation
+
+- **Deployment:** Offline-capable Raspberry Pi, single-instance
+- **Database:** PostgreSQL with psycopg3, Alembic-only migrations
+- **Auth:** Custom HMAC tokens (no JWT libraries)
+- **Camera Hardware:** libcamera/picamera2 via system packages
+- **Dependency Manager:** Pixi (preferred), venv (legacy)
+- **Git:** Uses submodules for frontend/backend
+
+**Before making changes:** Check git history to avoid reverting intentional architectural decisions.

From d3dabb4d2a94be31f7eff3cef02ef7359a123f11 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 14 Feb 2026 19:27:25 -0800
Subject: [PATCH 02/55] refactor: remove obsolete scripts and update start.sh
 to use pixi for native backend

---
 scripts/bootstrap_host.sh     | 42 ---------------
 scripts/restart.sh            | 26 ----------
 scripts/run_backend_native.sh | 98 -----------------------------------
 scripts/start.sh              |  4 +-
 4 files changed, 2 insertions(+), 168 deletions(-)
 delete mode 100755 scripts/bootstrap_host.sh
 delete mode 100755 scripts/restart.sh
 delete mode 100755 scripts/run_backend_native.sh

diff --git a/scripts/bootstrap_host.sh b/scripts/bootstrap_host.sh
deleted file mode 100755
index b62adf1..0000000
--- a/scripts/bootstrap_host.sh
+++ /dev/null
@@ -1,42 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# user and group to be changed in prod
-APP_USER="pi"
-APP_GROUP="digitool"
-
-DATA_DIR="/var/lib/dtk"
-LOG_DIR="/var/log/dtk"
-
-echo "[dtk] Bootstrapping host directories and user..."
-
-if [[ "${EUID}" -ne 0 ]]; then
-  echo "ERROR: run as root (try: sudo $0)"
-  exit 1
-fi
-
-getent group "${APP_GROUP}" >/dev/null || groupadd --system "${APP_GROUP}"
-id -u "${APP_USER}" >/dev/null 2>&1 || useradd \
-  --system \
-  --gid "${APP_GROUP}" \
-  --home "${DATA_DIR}" \
-  --shell /usr/sbin/nologin \
-  "${APP_USER}"
-
-mkdir -p \
-  "${DATA_DIR}/projects" \
-  "${DATA_DIR}/exports" \
-  "${DATA_DIR}/backups" \
-  "${DATA_DIR}/db" \
-  "${LOG_DIR}"
-
-# Ownership + permissions
-chown -R "${APP_USER}:${APP_GROUP}" "${DATA_DIR}" "${LOG_DIR}"
-chmod -R 750 "${DATA_DIR}" "${LOG_DIR}"
-
-# Marker file
-echo "DTK bootstrap completed on $(date -Iseconds)" > "${DATA_DIR}/.bootstrap"
-
-echo "[dtk] Done."
-echo "  Data: ${DATA_DIR}"
-echo "  Logs: ${LOG_DIR}"
diff --git a/scripts/restart.sh b/scripts/restart.sh
deleted file mode 100755
index 3c4a064..0000000
--- a/scripts/restart.sh
+++ /dev/null
@@ -1,26 +0,0 @@
-#!/bin/bash
-# Restart script for Digitization Toolkit (Production mode)
-# Safely stops and restarts all services
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
-
-cd "$PROJECT_ROOT"
-
-echo "=========================================="
-echo "Restarting Digitization Toolkit"
-echo "=========================================="
-echo ""
-
-# Stop everything
-./scripts/stop.sh
-
-echo ""
-echo "→ Waiting 2 seconds before restart..."
-sleep 2
-
-echo ""
-# Start in production mode
-./scripts/start.sh
diff --git a/scripts/run_backend_native.sh b/scripts/run_backend_native.sh
deleted file mode 100755
index d760d26..0000000
--- a/scripts/run_backend_native.sh
+++ /dev/null
@@ -1,98 +0,0 @@
-#!/bin/bash
-# Startup script for running DTK backend natively (outside Docker)
-# This allows direct access to camera hardware while connecting to dockerized DB
-
-set -e
-
-# Color codes for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-NC='\033[0m' # No Color
-
-echo -e "${BLUE}=================================================="
-echo "DTK Backend - Native Startup"
-echo -e "==================================================${NC}"
-echo ""
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-BACKEND_DIR="$PROJECT_ROOT/backend"
-VENV_DIR="$BACKEND_DIR/.venv"
-
-if [ ! -f "$PROJECT_ROOT/.env" ]; then
-    echo -e "${RED}✗ Error: .env file not found at $PROJECT_ROOT/.env${NC}"
-    echo "  Make sure you're running this from the project root"
-    exit 1
-fi
-
-if [ ! -d "$VENV_DIR" ]; then
-    echo -e "${RED}✗ Error: Virtual environment not found at $VENV_DIR${NC}"
-    echo "  Run: cd backend && python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt"
-    exit 1
-fi
-
-echo -e "${YELLOW}→${NC} Activating virtual environment..."
-source "$VENV_DIR/bin/activate"
-
-if ! command -v uvicorn &> /dev/null; then
-    echo -e "${RED}✗ uvicorn not found in virtual environment${NC}"
-    echo "  Run: pip install -r $BACKEND_DIR/requirements.txt"
-    exit 1
-fi
-
-echo -e "${YELLOW}→${NC} Checking database connectivity..."
-cd "$BACKEND_DIR"
-
-python3 << 'PREFLIGHT_CHECK'
-import sys
-try:
-    from app.core.db import engine
-    from sqlalchemy import text
-    
-    with engine.connect() as conn:
-        result = conn.execute(text('SELECT 1'))
-        result.scalar()
-    
-    print('\033[0;32m✓\033[0m Database connection successful')
-except Exception as e:
-    print(f'\033[0;31m✗ Database connection failed: {e}\033[0m')
-    print(f'\033[1;33m  Make sure Docker containers are running:\033[0m')
-    print(f'    docker compose up db')
-    sys.exit(1)
-PREFLIGHT_CHECK
-
-if [ $? -ne 0 ]; then
-    exit 1
-fi
-
-echo -e "${YELLOW}→${NC} Checking camera availability..."
-python3 << 'CAMERA_CHECK'
-try:
-    from capture.camera_registry import CameraRegistry
-    registry = CameraRegistry()
-    detected = registry.detect_cameras()
-    if detected:
-        print(f'\033[0;32m✓\033[0m Found {len(detected)} camera(s)')
-    else:
-        print('\033[1;33m⚠\033[0m  No cameras detected (capture endpoints will not work)')
-except Exception as e:
-    print(f'\033[1;33m⚠\033[0m  Camera check failed: {e}')
-    print('  (Backend will start but camera endpoints may not work)')
-CAMERA_CHECK
-
-echo ""
-echo -e "${GREEN}✓ Pre-flight checks complete${NC}"
-echo ""
-echo -e "${BLUE}Starting FastAPI backend...${NC}"
-echo -e "  Backend: ${GREEN}http://0.0.0.0:8000${NC}"
-echo -e "  API Docs: ${GREEN}http://localhost:8000/docs${NC}"
-echo -e "  ReDoc: ${GREEN}http://localhost:8000/redoc${NC}"
-echo ""
-echo -e "${YELLOW}Press Ctrl+C to stop${NC}"
-echo ""
-
-# Start uvicorn with auto-reload
-cd "$BACKEND_DIR"
-exec uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
diff --git a/scripts/start.sh b/scripts/start.sh
index 1e888e7..e08751f 100755
--- a/scripts/start.sh
+++ b/scripts/start.sh
@@ -28,5 +28,5 @@ if ! docker compose ps | grep -q "db.*healthy"; then
 fi
 
 echo ""
-# Start native backend
-./scripts/run_backend_native.sh
+echo "→ Starting native backend with pixi..."
+cd "$PROJECT_ROOT/backend" && pixi run dev

From 96f946a85e09e31f8c6a22344f7b6c71a634fd1a Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 14 Feb 2026 19:27:42 -0800
Subject: [PATCH 03/55] docs: update copilot instructions for AI agents and
 clarify script usage

---
 .github/copilot-instructions.md | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 04d3344..5592156 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -15,7 +15,7 @@ Offline-capable digitization toolkit for Raspberry Pi with dual camera support.
 ./scripts/start-dev.sh  # or: docker compose --profile with-backend up
 
 # Production (Raspberry Pi with cameras): Native backend + Docker DB
-./scripts/start.sh      # or: docker compose up -d && ./scripts/run_backend_native_pixi.sh
+./scripts/start.sh      # or: docker compose up -d && cd backend && pixi run dev
 ```
 
 **Why:** System camera libraries (python3-libcamera, python3-kms++) cannot be installed via pip and must be accessed from system packages.
@@ -187,7 +187,9 @@ frontend/
     └── routes/           # SvelteKit pages
 ```
 
-## Documentation Policy for AI Agents
+## Documentation & Script Policy for AI Agents
+
+### Documentation Files
 
 **DO NOT create new standalone documentation files** (README.md, GUIDE.md, NOTES.md, etc.) for recording changes or providing instructions.
 
@@ -202,7 +204,28 @@ Instead:
 - ❌ INSTRUCTIONS.md, AGENT.md - Update this file instead
 - ❌ Informational "status update" files - These are traceback logs, not documentation
 
-**If you need to document something important:** Ask yourself "Will another AI agent need to know this to avoid mistakes?" If yes, add it to this file. If it's a repeatable procedure, create a skill file.
+### Shell Scripts
+
+**DO NOT create shell scripts for simple tasks.** The project uses pixi tasks for backend workflows.
+
+**Only create scripts for:**
+- ✅ Multi-service orchestration (start-dev.sh, start.sh, stop.sh)
+- ✅ System-level operations (install-service.sh, uninstall-service.sh)
+
+**Never create scripts for:**
+- ❌ Database migrations - Use `pixi run db-upgrade` or `pixi run db-migrate "message"`
+- ❌ Running single services - Use `pixi run dev` directly
+- ❌ One-time setup tasks - Document in README.md instead
+- ❌ Simple command wrappers - Users can run commands directly
+
+**Existing pixi tasks** (defined in backend/pixi.toml):
+- `pixi run dev` - Start development server
+- `pixi run test` - Run tests
+- `pixi run db-upgrade` - Apply migrations
+- `pixi run db-migrate "message"` - Create migration
+- `pixi run setup-camera-link` - Link system camera packages
+
+**Decision criteria:** "Does this require coordinating multiple services or system-level changes?" If no, use pixi tasks or document the command.
 
 ## Common Mistakes AI Agents Make
 
@@ -214,6 +237,7 @@ Instead:
 6. ❌ Forgetting backend must run natively for camera access
 7. ❌ Breaking hardware ID system by reverting to index-based camera refs
 8. ❌ Creating new documentation files instead of updating existing ones
+9. ❌ Creating shell scripts for simple tasks (use pixi tasks instead)
 
 ## Quick Reference Commands
 

From ceb83c9df87c3c4fe685ef1d1c7a98467113ebcd Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 14 Feb 2026 19:27:51 -0800
Subject: [PATCH 04/55] docs: update backend native run instructions for
 Raspberry Pi

---
 docker-compose.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 88d9734..4c788f0 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -27,7 +27,7 @@ services:
       retries: 5
 
   # Backend service (optional for Docker-based development)
-  # On Raspberry Pi with cameras, run backend natively: ./scripts/run_backend_native.sh
+  # On Raspberry Pi with cameras, run backend natively: cd backend && pixi run dev
   # For development without camera hardware, use: docker compose --profile with-backend up
   backend:
     profiles: ["with-backend"]  # Optional: only start with --profile with-backend

From bfe887a5552eea297c4abeb0c0d9e260c2092e62 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 14 Feb 2026 19:29:39 -0800
Subject: [PATCH 05/55] chore: update submodule commits for backend and
 frontend

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index 8614051..553b2bc 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 86140518b98f7b5ec08193df6519681b897c5af3
+Subproject commit 553b2bc7175cd3fe53cbff2ff4aa1264d3aa83fb
diff --git a/frontend b/frontend
index 396fe7c..b2fb920 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 396fe7ceea58e1dc281fb69216f63c2a2d78996d
+Subproject commit b2fb9205d86c1abe28f6e2d153f914a6b17e0cb2

From d2b4d58c989830a5a1d68d3924d5945077d5f3ab Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 14 Feb 2026 19:30:06 -0800
Subject: [PATCH 06/55] docs: update backend startup instructions and add
 dependency management details

---
 README.md | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 12cef1c..2c42d77 100644
--- a/README.md
+++ b/README.md
@@ -46,13 +46,31 @@ docker compose --profile with-backend up
 
 Or manually:
 ```bash
-docker compose up -d && ./scripts/run_backend_native.sh
+# Start database and frontend
+docker compose up -d
+
+# Start backend with pixi
+cd backend && pixi run dev
 ```
 
 **Access:** [http://localhost:5173](http://localhost:5173) (frontend) | [http://localhost:8000/docs](http://localhost:8000/docs) (API)
 
 **Note:** The native backend is required for camera access due to Raspberry Pi-specific libraries (libcamera, picamera2).
 
+### 📦 Backend Dependency Management
+
+The backend uses **pixi** for dependency management:
+
+```bash
+# First time setup
+cd backend
+pixi install
+pixi run setup-camera-link  # Raspberry Pi only
+
+# Start backend
+pixi run dev
+```
+
 ## Setup
 
 This repository uses **Git submodules** for the `frontend` and `backend` code.  

From e743d88bb9cd1d342345507cfd324aca83e018a9 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 14 Feb 2026 19:30:14 -0800
Subject: [PATCH 07/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index b2fb920..ac7c02d 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit b2fb9205d86c1abe28f6e2d153f914a6b17e0cb2
+Subproject commit ac7c02dadcdd0f2c5548bb6991a0a0f3cf983493

From a659b26d6c2d53c27da777c9b81ea906af23ab7b Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 14 Feb 2026 19:48:13 -0800
Subject: [PATCH 08/55] chore: update backend submodule to latest commit

---
 backend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/backend b/backend
index 553b2bc..f102d99 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 553b2bc7175cd3fe53cbff2ff4aa1264d3aa83fb
+Subproject commit f102d99b3edf550a79411d5c655d99c57da9aee8

From 6923cd9b6c1b326cd184c2db6b9df10d4992f208 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 14 Feb 2026 19:48:57 -0800
Subject: [PATCH 09/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index ac7c02d..51b8d13 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit ac7c02dadcdd0f2c5548bb6991a0a0f3cf983493
+Subproject commit 51b8d13e33bb9f2b1326efabc005847b002ae1ad

From e1d8135cfdf160e385ed660e0d4abbf7de7b1be5 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 14 Feb 2026 19:51:38 -0800
Subject: [PATCH 10/55] chore: update backend submodule to latest commit

---
 backend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/backend b/backend
index f102d99..2c5c6f5 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit f102d99b3edf550a79411d5c655d99c57da9aee8
+Subproject commit 2c5c6f5ebd9fa19c64f588f77313d45fd179a834

From 16e3be63fe845586a60e64169ae58fad2685454b Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 11:49:33 -0800
Subject: [PATCH 11/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index 51b8d13..356cf23 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 51b8d13e33bb9f2b1326efabc005847b002ae1ad
+Subproject commit 356cf23fbb3e4c336cf786899989c947f05d1512

From 7389bbd2093e23a5eb1f2e9ae9cf4b8414dd6165 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 12:06:41 -0800
Subject: [PATCH 12/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index 356cf23..6f01938 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 356cf23fbb3e4c336cf786899989c947f05d1512
+Subproject commit 6f019386cd017e835d845a3eff414f58783f7f9b

From 0e0f3bf612572bd55671e019409a6a3b9f83a6b1 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 12:25:41 -0800
Subject: [PATCH 13/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index 6f01938..2ba895a 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 6f019386cd017e835d845a3eff414f58783f7f9b
+Subproject commit 2ba895a26055332570d0843d8240220b5db4fda1

From 9e38623d9f922ae34618f88787ed2dc4976c668c Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 15:04:22 -0800
Subject: [PATCH 14/55] chore: update backend and frontend submodules to latest
 commits

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index 2c5c6f5..b26914e 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 2c5c6f5ebd9fa19c64f588f77313d45fd179a834
+Subproject commit b26914e3fe718c7370a4f853b708c3c6e38155bc
diff --git a/frontend b/frontend
index 2ba895a..5db5ed7 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 2ba895a26055332570d0843d8240220b5db4fda1
+Subproject commit 5db5ed79cfe8215e2ccef881d5667d02c6285d1b

From eb4dd2827f64b60084fc8458db941e921bfae15c Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 17:55:28 -0800
Subject: [PATCH 15/55] feature: add scripts for installing and launching
 Wayland kiosk service

---
 scripts/install-kiosk-service.sh | 42 ++++++++++++++++++++++++++++++++
 scripts/installkb.sh             | 34 ++++++++++++++++++++++++++
 scripts/start-kiosk.sh           | 33 +++++++++++++++++++++++++
 3 files changed, 109 insertions(+)
 create mode 100755 scripts/install-kiosk-service.sh
 create mode 100755 scripts/installkb.sh
 create mode 100755 scripts/start-kiosk.sh

diff --git a/scripts/install-kiosk-service.sh b/scripts/install-kiosk-service.sh
new file mode 100755
index 0000000..e344919
--- /dev/null
+++ b/scripts/install-kiosk-service.sh
@@ -0,0 +1,42 @@
+#!/bin/bash
+# Install systemd service for auto-starting kiosk on boot
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "Creating kiosk systemd service..."
+
+cat > /tmp/kiosk.service << 'EOF'
+[Unit]
+Description=Wayland Kiosk (Cage + Chromium)
+After=network-online.target docker.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=pi
+Environment=XDG_RUNTIME_DIR=/run/user/1000
+ExecStart=/home/pi/dtk/scripts/start-kiosk.sh
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+sudo mv /tmp/kiosk.service /etc/systemd/system/kiosk.service
+sudo systemctl daemon-reload
+sudo systemctl enable kiosk.service
+
+echo ""
+echo "✓ Kiosk service installed and enabled!"
+echo ""
+echo "The kiosk will start automatically on next boot."
+echo ""
+echo "To control it:"
+echo "  sudo systemctl start kiosk    # Start now"
+echo "  sudo systemctl stop kiosk     # Stop"
+echo "  sudo systemctl status kiosk   # Check status"
+echo "  sudo systemctl disable kiosk  # Disable auto-start"
+echo ""
diff --git a/scripts/installkb.sh b/scripts/installkb.sh
new file mode 100755
index 0000000..51188d2
--- /dev/null
+++ b/scripts/installkb.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+# Install Wayland kiosk browser
+
+set -e  # Exit on error
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "╔════════════════════════════════════════╗"
+echo "║  Raspberry Pi 5 Wayland Kiosk Setup    ║"
+echo "╚════════════════════════════════════════╝"
+echo ""
+
+echo "Installing Cage (Wayland compositor) and Chromium..."
+sudo apt update
+sudo apt install -y cage chromium-browser
+
+echo ""
+echo "✓ Installation complete!"
+echo ""
+echo "════════════════════════════════════════"
+echo "  To start the kiosk:"
+echo "════════════════════════════════════════"
+echo ""
+echo "  ~/dtk/scripts/start-kiosk.sh"
+echo ""
+echo "════════════════════════════════════════"
+echo "  For auto-start on boot (optional):"
+echo "════════════════════════════════════════"
+echo ""
+echo "  1. Test manually first to ensure it works"
+echo "  2. Then run: sudo ~/dtk/scripts/install-kiosk-service.sh"
+echo ""
+
diff --git a/scripts/start-kiosk.sh b/scripts/start-kiosk.sh
new file mode 100755
index 0000000..158b593
--- /dev/null
+++ b/scripts/start-kiosk.sh
@@ -0,0 +1,33 @@
+#!/bin/bash
+# Wayland Kiosk Launcher - starts Chromium in fullscreen using Cage
+
+echo "╔════════════════════════════════════════╗"
+echo "║   Starting Wayland Kiosk Mode          ║"
+echo "╚════════════════════════════════════════╝"
+echo ""
+echo "To exit: Press Ctrl+Alt+F2, then run 'pkill cage'"
+echo ""
+
+# Wait for frontend to be ready
+echo -n "Waiting for frontend at http://localhost:5173..."
+until curl -sSf http://localhost:5173 >/dev/null 2>&1; do
+  echo -n "."
+  sleep 1
+done
+echo " ✓ Ready!"
+
+echo ""
+echo "Launching Chromium kiosk..."
+echo ""
+
+# Launch Cage with Chromium in kiosk mode
+# Cage automatically makes the app fullscreen
+exec cage -- chromium-browser \
+  --kiosk \
+  --noerrdialogs \
+  --disable-infobars \
+  --disable-session-crashed-bubble \
+  --disable-features=TranslateUI \
+  --overscroll-history-navigation=0 \
+  --check-for-update-interval=31536000 \
+  http://localhost:5173

From 0c93faf5db9e48df3d1023136cc3fcbe16228b01 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 17:58:08 -0800
Subject: [PATCH 16/55] chore: update .gitignore to include working files

---
 .gitignore | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 9165ad9..598718b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,4 +25,7 @@ _data/
 _logs/
 
 # Temporary folder
-temp/
\ No newline at end of file
+temp/
+
+# Working files
+docs/RP-008156-DS-2-picamera2-manual.txt
\ No newline at end of file

From d8f9cb73077f27ff2d320472ad20393fead66c12 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 19:23:51 -0800
Subject: [PATCH 17/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index 5db5ed7..5863e4a 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 5db5ed79cfe8215e2ccef881d5667d02c6285d1b
+Subproject commit 5863e4a1e8a5e3f1e3213f68afc61b4bbe6350a4

From 0683fb5f5f7f30b68031ae794e2b7fdeb0555a7c Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 19:23:58 -0800
Subject: [PATCH 18/55] feature: add frontend development instructions for
 styling and project guidelines

---
 .github/instructions/frontend.instructions.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 .github/instructions/frontend.instructions.md

diff --git a/.github/instructions/frontend.instructions.md b/.github/instructions/frontend.instructions.md
new file mode 100644
index 0000000..86f3d1d
--- /dev/null
+++ b/.github/instructions/frontend.instructions.md
@@ -0,0 +1,19 @@
+---
+applyTo: "frontend/**"
+---
+
+# Specific instructions for frontend development.
+
+## Styles
+
+- All styles should be written in the `frontend/static` directory, particularly in the `app.css` file.
+- Use CSS variables for colors and other reusable values to maintain consistency across the application.
+- Follow a modular approach to CSS, organizing styles by components or sections of the application.
+- Ensure that styles are responsive and work well on different screen sizes.
+- If available, use `frontend/static/example.css` as a reference for styling, color palette, and layout.
+
+## Project Specific Guidelines
+
+- The defaul screen is a 7-inch display, so all styles should be optimized for that size. However, the application should also be responsive and adapt to larger screens when necessary.
+- When adding new styles, make sure to test them on the default screen size to ensure they look good and function properly. Additionally, consider how the styles will affect the user experience on different devices and screen sizes.
+- Two screen resolutions are supported: 800x480 and 1024x600. Ensure that your styles are compatible with both resolutions, providing a seamless experience for users regardless of the device they are using.

From 69a15c541476a9b080a494c57fb0c28488131d03 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 19:24:04 -0800
Subject: [PATCH 19/55] chore: add YAML front matter to copilot instructions
 file

---
 .github/copilot-instructions.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 5592156..2329d57 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,3 +1,7 @@
+---
+applyTo: "**"
+---
+
 # AI Agent Instructions for Digitization Toolkit
 
 ## Project Overview

From c2d31bd88fd5e0e4037ca069da8b08a60319ff82 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 19:41:29 -0800
Subject: [PATCH 20/55] chore: update backend submodule to latest commit

---
 backend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/backend b/backend
index b26914e..a387eee 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit b26914e3fe718c7370a4f853b708c3c6e38155bc
+Subproject commit a387eee2d50cca8bd647633353580811385f7727

From 29b023bba025f0b0ea68eafefc6a1dc472b7e10d Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 20:24:12 -0800
Subject: [PATCH 21/55] chore: update backend submodule to latest commit

---
 backend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/backend b/backend
index a387eee..3cab342 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit a387eee2d50cca8bd647633353580811385f7727
+Subproject commit 3cab3426dc320287c86c64bf29c2aeee1becc750

From fc020271bcf141204344dd2f35bea55026740e7c Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 20:48:34 -0800
Subject: [PATCH 22/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index 5863e4a..f7b4954 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 5863e4a1e8a5e3f1e3213f68afc61b4bbe6350a4
+Subproject commit f7b49547594e9f42dd4c06155538b2c3ec91513b

From a86538bfa8430089520d1f9e42a3e00cb978d8a0 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 21:27:01 -0800
Subject: [PATCH 23/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index f7b4954..ee0c93c 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit f7b49547594e9f42dd4c06155538b2c3ec91513b
+Subproject commit ee0c93c6db8588c9f06f3d941cc151fe1e211511

From 83aa24348388ada0fa972a6f28d8c1d9f066c036 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Mon, 16 Feb 2026 21:43:18 -0800
Subject: [PATCH 24/55] chore: update frontend and backend submodules to latest
 commits

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index 3cab342..328c057 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 3cab3426dc320287c86c64bf29c2aeee1becc750
+Subproject commit 328c05738bbbb93997ee08517bdb111296cd95f3
diff --git a/frontend b/frontend
index ee0c93c..7d999cd 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit ee0c93c6db8588c9f06f3d941cc151fe1e211511
+Subproject commit 7d999cd8b957d72b00cb25a03abab0120a549ee5

From e9442260fbced177335bd81e8f43bfd8a90fac4c Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 10:27:30 -0800
Subject: [PATCH 25/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index 7d999cd..ae6c038 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 7d999cd8b957d72b00cb25a03abab0120a549ee5
+Subproject commit ae6c03819b76ce18c96e0cb59267daee6e963fcd

From b406d5a8141c04ef9c2fd1d4f3a77b47bab118b9 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 11:45:35 -0800
Subject: [PATCH 26/55] chore: add Material Icons reference documentation for
 frontend

---
 .github/instructions/icons.instructions.md | 138 +++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 .github/instructions/icons.instructions.md

diff --git a/.github/instructions/icons.instructions.md b/.github/instructions/icons.instructions.md
new file mode 100644
index 0000000..d6b362e
--- /dev/null
+++ b/.github/instructions/icons.instructions.md
@@ -0,0 +1,138 @@
+---
+applyTo: "frontend/**"
+---
+
+# Material Icons Reference for DTK
+
+## Usage
+
+Material Icons are now available offline throughout the application. Simply use the icon name as text content within an element with the `material-symbols-outlined` class.
+
+### Basic Usage
+
+```html
+<span class="material-symbols-outlined">home</span>
+<span class="material-symbols-outlined">folder</span>
+<span class="material-symbols-outlined">settings</span>
+```
+
+### Size Variants
+
+```html
+<span class="material-symbols-outlined icon-sm">home</span>   <!-- 18px -->
+<span class="material-symbols-outlined icon-md">home</span>   <!-- 24px - default -->
+<span class="material-symbols-outlined icon-lg">home</span>   <!-- 32px -->
+```
+
+### In Buttons
+
+```html
+<button class="btn-primary">
+  <span class="material-symbols-outlined">add</span>
+  Create New
+</button>
+```
+
+## Commonly Used Icons in DTK
+
+### Navigation & UI
+- `dashboard` - Dashboard/grid view
+- `folder` - Projects/folders
+- `settings` - Settings/configuration
+- `logout` - Logout/sign out
+- `menu` - Hamburger menu
+- `close` - Close/cancel
+- `arrow_back` - Back navigation
+- `arrow_forward` - Forward navigation
+
+### File Operations
+- `folder_open` - Open folder
+- `description` - Document/file
+- `upload_file` - Upload
+- `download` - Download
+- `delete` - Delete/trash
+- `edit` - Edit/modify
+- `save` - Save
+- `print` - Print
+
+### Content Actions
+- `add` - Add new item
+- `remove` - Remove item
+- `search` - Search
+- `filter_list` - Filter
+- `sort` - Sort
+- `more_vert` - More options (vertical)
+- `more_horiz` - More options (horizontal)
+
+### Media & Capture
+- `photo_camera` - Camera/capture
+- `image` - Image/photo
+- `collections` - Gallery/collection
+- `video_camera_front` - Video camera
+- `camera_alt` - Alternative camera icon
+
+### Status & Feedback
+- `check_circle` - Success/complete
+- `error` - Error
+- `warning` - Warning
+- `info` - Information
+- `help` - Help/support
+
+### Data & Records
+- `article` - Article/record
+- `book` - Book/publication
+- `library_books` - Multiple books
+- `inventory` - Inventory
+- `archive` - Archive
+- `collections_bookmark` - Bookmarked collection
+
+### User & Account
+- `person` - Person/user
+- `account_circle` - User account
+- `group` - Group/multiple users
+
+### Utility
+- `refresh` - Refresh/reload
+- `sync` - Synchronize
+- `visibility` - Show/visible
+- `visibility_off` - Hide/invisible
+- `lock` - Locked/secure
+- `lock_open` - Unlocked
+
+## Icon Browser
+
+To find more icons, browse the full catalog at:
+https://fonts.google.com/icons
+
+(Note: Save icon names for offline reference before deploying)
+
+## Examples from DTK
+
+### Sidebar Navigation
+```svelte
+<span class="material-symbols-outlined sidebar-icon">dashboard</span>
+<span class="material-symbols-outlined sidebar-icon">folder</span>
+<span class="material-symbols-outlined sidebar-icon">settings</span>
+```
+
+### Action Buttons
+```svelte
+<button class="icon-btn">
+  <span class="material-symbols-outlined icon-sm">edit</span>
+</button>
+
+<button class="icon-btn danger">
+  <span class="material-symbols-outlined icon-sm">delete</span>
+</button>
+```
+
+### Activity/Status Icons
+```svelte
+<span class="material-symbols-outlined activity-icon">folder</span>
+```
+
+## Font File Location
+
+`/home/pi/dtk/frontend/static/fonts/MaterialSymbolsOutlined.woff2` (3.7MB)
+
+This single font file contains all Material Symbols in the outlined style.

From e0543ccd34f88f05c1fcab13d9732b5719706b46 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 11:45:41 -0800
Subject: [PATCH 27/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index ae6c038..9b807c1 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit ae6c03819b76ce18c96e0cb59267daee6e963fcd
+Subproject commit 9b807c1ffcb6b0c7b8b6ff305f819abfac57a522

From a4d68697aaa2e4f256b07eea53eb96200a8a3880 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 12:36:59 -0800
Subject: [PATCH 28/55] chore: update frontend and backend submodules to latest
 commits

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index 328c057..26d749b 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 328c05738bbbb93997ee08517bdb111296cd95f3
+Subproject commit 26d749b8602b389e53f78ca73bc5b24345cafee3
diff --git a/frontend b/frontend
index 9b807c1..c93b3ba 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 9b807c1ffcb6b0c7b8b6ff305f819abfac57a522
+Subproject commit c93b3ba435ccdf33ac4e797b4ae5b0780e114e5f

From e121f01a045004715758e003f5dd23c59f534569 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 14:02:39 -0800
Subject: [PATCH 29/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index c93b3ba..c6a0bcd 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit c93b3ba435ccdf33ac4e797b4ae5b0780e114e5f
+Subproject commit c6a0bcd99cb08c842da31facde51d45eeabeba66

From 32bfb5c8cc67000c66302bc9e84ec8fab8dd0f84 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 15:10:38 -0800
Subject: [PATCH 30/55] chore: update frontend and backend submodules to latest
 commits

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index 26d749b..475e4fc 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 26d749b8602b389e53f78ca73bc5b24345cafee3
+Subproject commit 475e4fc0884fd56c99470fe7642f134d4128c1db
diff --git a/frontend b/frontend
index c6a0bcd..f61eb2f 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit c6a0bcd99cb08c842da31facde51d45eeabeba66
+Subproject commit f61eb2fe53a12a6e78e5be806d19fa2c5b72aa9b

From 1ad281cc0997e8b2b270f17190303ca4268d601b Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 15:20:59 -0800
Subject: [PATCH 31/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index f61eb2f..faaf328 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit f61eb2fe53a12a6e78e5be806d19fa2c5b72aa9b
+Subproject commit faaf3282959da0fc8bf24e0eda413e9e06a6a4c0

From 2d93783eb4229e07fb812e41432c078f01bd0463 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 15:42:49 -0800
Subject: [PATCH 32/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index faaf328..96505f1 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit faaf3282959da0fc8bf24e0eda413e9e06a6a4c0
+Subproject commit 96505f116697bd97d12781fbcd6388873086866b

From c8015ff509c4058e28a7bb3f8cc5184e15e248c0 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 17:05:53 -0800
Subject: [PATCH 33/55] chore: update frontend and backend submodules to latest
 commits

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index 475e4fc..3aa23d7 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 475e4fc0884fd56c99470fe7642f134d4128c1db
+Subproject commit 3aa23d7c97e5e977ed554606d082b446fc7e5ebf
diff --git a/frontend b/frontend
index 96505f1..81dadc5 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 96505f116697bd97d12781fbcd6388873086866b
+Subproject commit 81dadc510ebf27bb1781abca772fba92ba1c6e3e

From f9311a39ea02554f0a1d32712fe9e5cb75cf3245 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 17:32:45 -0800
Subject: [PATCH 34/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index 81dadc5..ca73062 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 81dadc510ebf27bb1781abca772fba92ba1c6e3e
+Subproject commit ca73062abda1e6449af12cfaa4f47dd51ea999d7

From 0cc49d312606066c5e2dc89b2bdd3793f3db290d Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 18:48:44 -0800
Subject: [PATCH 35/55] chore: update frontend and backend submodules to latest
 commits

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index 3aa23d7..7909c22 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 3aa23d7c97e5e977ed554606d082b446fc7e5ebf
+Subproject commit 7909c22c19f1a24b314daeb0efd5683a0233e6d7
diff --git a/frontend b/frontend
index ca73062..e53c7c4 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit ca73062abda1e6449af12cfaa4f47dd51ea999d7
+Subproject commit e53c7c46a4830de86c3a9dce4a35ccd9bef98144

From fbf4c02a4528dc376a9ceafcd8ff00b8f1e12dda Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 18:52:17 -0800
Subject: [PATCH 36/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index e53c7c4..b799a01 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit e53c7c46a4830de86c3a9dce4a35ccd9bef98144
+Subproject commit b799a012560b7eb55c0e7027596cfc787b55b479

From 7851203269ca6a12a62e9df857c5f5b850430355 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Tue, 17 Feb 2026 19:41:45 -0800
Subject: [PATCH 37/55] chore: update frontend and backend submodules to latest
 commits

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index 7909c22..8a68499 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 7909c22c19f1a24b314daeb0efd5683a0233e6d7
+Subproject commit 8a684997c5a6cfd327e87aa96cef1bd38a1b7d05
diff --git a/frontend b/frontend
index b799a01..d181471 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit b799a012560b7eb55c0e7027596cfc787b55b479
+Subproject commit d181471d424b5b4be36168fc2a874f91db248b8a

From 3a5f3402b10f1f60169e3fa9401bb2e833356fe7 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Wed, 18 Feb 2026 14:48:10 -0800
Subject: [PATCH 38/55] chore: update frontend instructions for CSS and icon
 usage guidelines

---
 .github/instructions/frontend.instructions.md | 136 ++++++++++++-
 .github/instructions/icons.instructions.md    | 190 +++++++++---------
 2 files changed, 217 insertions(+), 109 deletions(-)

diff --git a/.github/instructions/frontend.instructions.md b/.github/instructions/frontend.instructions.md
index 86f3d1d..22f1458 100644
--- a/.github/instructions/frontend.instructions.md
+++ b/.github/instructions/frontend.instructions.md
@@ -4,16 +4,134 @@ applyTo: "frontend/**"
 
 # Specific instructions for frontend development.
 
-## Styles
+## ⛔ CSS Location — Non-Negotiable Rules
 
-- All styles should be written in the `frontend/static` directory, particularly in the `app.css` file.
-- Use CSS variables for colors and other reusable values to maintain consistency across the application.
-- Follow a modular approach to CSS, organizing styles by components or sections of the application.
-- Ensure that styles are responsive and work well on different screen sizes.
-- If available, use `frontend/static/example.css` as a reference for styling, color palette, and layout.
+**ALL CSS must live in `frontend/static/app.css`. No exceptions.**
+
+### FORBIDDEN patterns — never do these:
+
+```svelte
+<!-- ❌ NEVER: <style> blocks inside .svelte files -->
+<style>
+  .my-button { color: red; }
+</style>
+```
+
+```svelte
+<!-- ❌ NEVER: inline style attributes -->
+<div style="color: red; margin: 8px;">...</div>
+<button style="background: blue;">...</button>
+```
+
+```ts
+// ❌ NEVER: style strings in TypeScript/JavaScript
+element.style.color = 'red';
+const styles = { color: 'red' };
+```
+
+```svelte
+<!-- ❌ NEVER: style directives -->
+<div style:color="red">...</div>
+```
+
+### CORRECT pattern — always do this:
+
+Add a named class to `frontend/static/app.css`, then apply it in the template:
+
+```css
+/* frontend/static/app.css */
+.my-button {
+  color: var(--accent-primary);
+  margin: var(--spacing-sm);
+}
+```
+
+```svelte
+<!-- frontend/src/lib/components/MyComponent.svelte -->
+<button class="my-button">Click me</button>
+```
+
+### Dynamic state is the only exception
+
+Only JS-driven dynamic values that cannot be expressed as toggled CSS classes may use a style binding, and only with a CSS variable:
+
+```svelte
+<!-- ✅ ALLOWED only when value is truly dynamic -->
+<div style="--progress: {percent}%">...</div>
+```
+
+```css
+/* The visual rule still lives in app.css */
+.progress-bar::after { width: var(--progress); }
+```
+
+---
+
+## CSS Variables
+
+All colors, spacing, and typography values are defined as CSS variables in `app.css`. **Always use variables — never hard-code values.**
+
+| Variable | Purpose |
+|---|---|
+| `--bg-color` | Page background (#ffffff) |
+| `--bg-gray` | Secondary background (#f2f2f2) |
+| `--text-color` | Body text (#757575) |
+| `--text-dark` | Heading/emphasis text (#000000) |
+| `--text-muted` | Muted/disabled text (#858585) |
+| `--accent-primary` | Brand blue (rgba(41,98,255,0.8)) |
+| `--accent-hover` | Hover accent (#f18e00) |
+| `--accent-link` | Link color (#F2784B) |
+| `--footer-bg` | Footer background (#003660) |
+| `--footer-text` | Footer text (#ffffff) |
+| `--spacing-sm` | 0.5rem |
+| `--spacing-md` | 1rem |
+| `--spacing-lg` | 1.5rem |
+| `--spacing-xl` | 2rem |
+| `--spacing-xxl` | 3rem |
+
+When you need a new reusable value, **add it as a CSS variable in `:root`** inside `app.css` before using it.
+
+---
+
+## CSS Organization in app.css
+
+Follow these section headers when adding new rules:
+
+```css
+/* ==================== */
+/* Component Name       */
+/* ==================== */
+```
+
+Group styles by component or feature. Keep existing sections intact. Do not scatter related rules.
+
+---
 
 ## Project Specific Guidelines
 
-- The defaul screen is a 7-inch display, so all styles should be optimized for that size. However, the application should also be responsive and adapt to larger screens when necessary.
-- When adding new styles, make sure to test them on the default screen size to ensure they look good and function properly. Additionally, consider how the styles will affect the user experience on different devices and screen sizes.
-- Two screen resolutions are supported: 800x480 and 1024x600. Ensure that your styles are compatible with both resolutions, providing a seamless experience for users regardless of the device they are using.
+- The default screen is a **7-inch display**. All styles must be optimized for 800×480 and 1024×600 resolutions first, then scale up for larger screens.
+- Use relative units (`rem`, `%`, `vh`/`vw`) over fixed `px` wherever possible.
+- Test layout at both 800×480 and 1024×600 before considering work done.
+
+---
+
+## Svelte Component Rules
+
+- `.svelte` files contain **only** `<script>`, template markup, and **no** `<style>` blocks.
+- Apply styling exclusively through CSS classes defined in `app.css`.
+- Use `class:` directive for conditional classes (not `style:`):
+
+```svelte
+<!-- ✅ CORRECT: toggle a class -->
+<div class:active={isActive} class="panel">...</div>
+
+<!-- ❌ WRONG: toggle a style -->
+<div style:background={isActive ? 'blue' : 'gray'}>...</div>
+```
+
+---
+
+## Building
+
+- The project is built on Docker. IDE errors on some library imports are due to VSCode not resolving dependencies installed inside the container — these are not real errors.
+- The backend runs **natively** (not in Docker). See the root `copilot-instructions.md` for details.
diff --git a/.github/instructions/icons.instructions.md b/.github/instructions/icons.instructions.md
index d6b362e..8c1049f 100644
--- a/.github/instructions/icons.instructions.md
+++ b/.github/instructions/icons.instructions.md
@@ -2,137 +2,127 @@
 applyTo: "frontend/**"
 ---
 
-# Material Icons Reference for DTK
+# Icons
 
-## Usage
+## Rules
 
-Material Icons are now available offline throughout the application. Simply use the icon name as text content within an element with the `material-symbols-outlined` class.
+- **Always use Material Symbols Outlined** for every icon in the application. Do not use SVGs, emoji, Unicode symbols, Heroicons, FontAwesome, Lucide, or any other icon system.
+- **Never install additional icon libraries.** The font is already bundled at `frontend/static/fonts/MaterialSymbolsOutlined.woff2` and loaded in `frontend/static/app.css`.
+- **Never render icons as images** (`<img>`, `<svg>`, background-image). Always use the font span pattern below.
 
-### Basic Usage
+## Required Markup Pattern
 
-```html
+Every icon must follow this exact structure — a `<span>` with class `material-symbols-outlined`, containing only the icon name as text:
+
+```svelte
 <span class="material-symbols-outlined">home</span>
-<span class="material-symbols-outlined">folder</span>
-<span class="material-symbols-outlined">settings</span>
 ```
 
-### Size Variants
+Size is controlled by adding one of three modifier classes (default is `icon-md`):
 
-```html
+```svelte
 <span class="material-symbols-outlined icon-sm">home</span>   <!-- 18px -->
-<span class="material-symbols-outlined icon-md">home</span>   <!-- 24px - default -->
+<span class="material-symbols-outlined icon-md">home</span>   <!-- 24px -->
 <span class="material-symbols-outlined icon-lg">home</span>   <!-- 32px -->
 ```
 
-### In Buttons
+Do not set font-size on icon spans directly — use the modifier classes.
+
+## Icons Inside Buttons
 
-```html
+Place the span as the first child, followed by the label text:
+
+```svelte
 <button class="btn-primary">
-  <span class="material-symbols-outlined">add</span>
+  <span class="material-symbols-outlined icon-sm">add</span>
   Create New
 </button>
+
+<button class="icon-btn">
+  <span class="material-symbols-outlined icon-sm">edit</span>
+</button>
 ```
 
-## Commonly Used Icons in DTK
+## Choosing an Icon Name
+
+Pick from the list below. If the right icon isn't here, check https://fonts.google.com/icons (offline deployments: verify the name is in the woff2 before using).
 
 ### Navigation & UI
-- `dashboard` - Dashboard/grid view
-- `folder` - Projects/folders
-- `settings` - Settings/configuration
-- `logout` - Logout/sign out
-- `menu` - Hamburger menu
-- `close` - Close/cancel
-- `arrow_back` - Back navigation
-- `arrow_forward` - Forward navigation
+| Name | Use for |
+|---|---|
+| `dashboard` | Dashboard / grid view |
+| `folder` | Projects / folders |
+| `settings` | Settings / configuration |
+| `logout` | Sign out |
+| `menu` | Hamburger menu |
+| `close` | Close / cancel |
+| `arrow_back` | Back navigation |
+| `arrow_forward` | Forward navigation |
 
 ### File Operations
-- `folder_open` - Open folder
-- `description` - Document/file
-- `upload_file` - Upload
-- `download` - Download
-- `delete` - Delete/trash
-- `edit` - Edit/modify
-- `save` - Save
-- `print` - Print
+| Name | Use for |
+|---|---|
+| `folder_open` | Open folder |
+| `description` | Document / file |
+| `upload_file` | Upload |
+| `download` | Download |
+| `delete` | Delete / trash |
+| `edit` | Edit / modify |
+| `save` | Save |
+| `print` | Print |
 
 ### Content Actions
-- `add` - Add new item
-- `remove` - Remove item
-- `search` - Search
-- `filter_list` - Filter
-- `sort` - Sort
-- `more_vert` - More options (vertical)
-- `more_horiz` - More options (horizontal)
+| Name | Use for |
+|---|---|
+| `add` | Add new item |
+| `remove` | Remove item |
+| `search` | Search |
+| `filter_list` | Filter |
+| `sort` | Sort |
+| `more_vert` | More options (vertical) |
+| `more_horiz` | More options (horizontal) |
 
 ### Media & Capture
-- `photo_camera` - Camera/capture
-- `image` - Image/photo
-- `collections` - Gallery/collection
-- `video_camera_front` - Video camera
-- `camera_alt` - Alternative camera icon
+| Name | Use for |
+|---|---|
+| `photo_camera` | Camera / capture |
+| `image` | Image / photo |
+| `collections` | Gallery / collection |
+| `video_camera_front` | Video camera |
+| `camera_alt` | Alternative camera |
 
 ### Status & Feedback
-- `check_circle` - Success/complete
-- `error` - Error
-- `warning` - Warning
-- `info` - Information
-- `help` - Help/support
+| Name | Use for |
+|---|---|
+| `check_circle` | Success / complete |
+| `error` | Error |
+| `warning` | Warning |
+| `info` | Information |
+| `help` | Help / support |
 
 ### Data & Records
-- `article` - Article/record
-- `book` - Book/publication
-- `library_books` - Multiple books
-- `inventory` - Inventory
-- `archive` - Archive
-- `collections_bookmark` - Bookmarked collection
+| Name | Use for |
+|---|---|
+| `article` | Article / record |
+| `book` | Book / publication |
+| `library_books` | Multiple books |
+| `inventory` | Inventory |
+| `archive` | Archive |
+| `collections_bookmark` | Bookmarked collection |
 
 ### User & Account
-- `person` - Person/user
-- `account_circle` - User account
-- `group` - Group/multiple users
+| Name | Use for |
+|---|---|
+| `person` | Person / user |
+| `account_circle` | User account |
+| `group` | Group / multiple users |
 
 ### Utility
-- `refresh` - Refresh/reload
-- `sync` - Synchronize
-- `visibility` - Show/visible
-- `visibility_off` - Hide/invisible
-- `lock` - Locked/secure
-- `lock_open` - Unlocked
-
-## Icon Browser
-
-To find more icons, browse the full catalog at:
-https://fonts.google.com/icons
-
-(Note: Save icon names for offline reference before deploying)
-
-## Examples from DTK
-
-### Sidebar Navigation
-```svelte
-<span class="material-symbols-outlined sidebar-icon">dashboard</span>
-<span class="material-symbols-outlined sidebar-icon">folder</span>
-<span class="material-symbols-outlined sidebar-icon">settings</span>
-```
-
-### Action Buttons
-```svelte
-<button class="icon-btn">
-  <span class="material-symbols-outlined icon-sm">edit</span>
-</button>
-
-<button class="icon-btn danger">
-  <span class="material-symbols-outlined icon-sm">delete</span>
-</button>
-```
-
-### Activity/Status Icons
-```svelte
-<span class="material-symbols-outlined activity-icon">folder</span>
-```
-
-## Font File Location
-
-`/home/pi/dtk/frontend/static/fonts/MaterialSymbolsOutlined.woff2` (3.7MB)
-
-This single font file contains all Material Symbols in the outlined style.
+| Name | Use for |
+|---|---|
+| `refresh` | Refresh / reload |
+| `sync` | Synchronize |
+| `visibility` | Show / visible |
+| `visibility_off` | Hide / invisible |
+| `lock` | Locked / secure |
+| `lock_open` | Unlocked |

From 15e4b2130de19294dcfd1eb249c6d9c980c5dd71 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 12:18:44 -0800
Subject: [PATCH 39/55] chore: update development setup for Vite live reload
 and enhance documentation

---
 .github/copilot-instructions.md  | 28 +++++++++++++++++++++++----
 README.md                        | 10 +++++++---
 backend                          |  2 +-
 docker-compose.dev.yml           | 27 ++++++++++++++++++++++++++
 docker-compose.yml               | 33 +++++++++++++++-----------------
 docs/developers/API_REFERENCE.md |  2 +-
 frontend                         |  2 +-
 scripts/start-dev.sh             |  2 +-
 8 files changed, 77 insertions(+), 29 deletions(-)
 create mode 100644 docker-compose.dev.yml

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 2329d57..0d6aa60 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -15,15 +15,34 @@ Offline-capable digitization toolkit for Raspberry Pi with dual camera support.
 ### 1. Dual Deployment Modes
 
 ```bash
-# Development (any machine, no cameras): All services in Docker
-./scripts/start-dev.sh  # or: docker compose --profile with-backend up
+# Development (any machine, no cameras): All services in Docker with Vite live reload
+./scripts/start-dev.sh  # or: docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile with-backend up
 
-# Production (Raspberry Pi with cameras): Native backend + Docker DB
+# Production (Raspberry Pi with cameras): Native backend + Docker DB + pre-built frontend
 ./scripts/start.sh      # or: docker compose up -d && cd backend && pixi run dev
 ```
 
 **Why:** System camera libraries (python3-libcamera, python3-kms++) cannot be installed via pip and must be accessed from system packages.
 
+### 1a. Offline-First Frontend
+
+The frontend uses a **multi-stage production Docker build** (`frontend/Dockerfile`):
+- Stage 1 (builder): Installs npm deps + compiles SvelteKit → static Node.js server
+- Stage 2 (runner): Copies only the compiled output — no npm, no source code
+
+The running container needs **zero internet access**. The only requirement is a one-time internet-connected build:
+```bash
+# With internet access (e.g. at home / office):
+docker compose build frontend    # or: docker compose build
+
+# Then take the Pi offline — it will run forever from the cached image:
+docker compose up -d
+```
+
+Adapter: `@sveltejs/adapter-node` (produces `node build/index.js`), port 3000.
+
+`docker-compose.dev.yml` overrides the frontend service to use `Dockerfile.dev` (Vite dev server, port 5173, hot reload, volume mounts). Used only during development with internet.
+
 ### 2. Camera Backend Plugin System
 
 Two interchangeable backends via `CAMERA_BACKEND` env var:
@@ -242,11 +261,12 @@ Instead:
 7. ❌ Breaking hardware ID system by reverting to index-based camera refs
 8. ❌ Creating new documentation files instead of updating existing ones
 9. ❌ Creating shell scripts for simple tasks (use pixi tasks instead)
+10. ❌ Replacing `frontend/Dockerfile` (production multi-stage build) with `Dockerfile.dev` in `docker-compose.yml` — that would re-introduce npm downloads at startup and break offline use
 
 ## Quick Reference Commands
 
 ```bash
-# Start full stack development (no cameras)
+# Start full stack development (no cameras) — Vite dev server at :5173
 ./scripts/start-dev.sh
 
 # Start production with cameras
diff --git a/README.md b/README.md
index 2c42d77..8bd1002 100644
--- a/README.md
+++ b/README.md
@@ -34,13 +34,16 @@ An open-source, modular digitization toolkit designed for low-cost, high-quality
 
 Or manually:
 ```bash
-docker compose --profile with-backend up
+docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile with-backend up
 ```
 
 ### Production (Raspberry Pi with cameras)
 
 ```bash
-# One-command startup (Docker + native backend)
+# Build the frontend image first (requires internet — do this at home/office):
+docker compose build
+
+# Then take it offline and run:
 ./scripts/start.sh
 ```
 
@@ -53,7 +56,8 @@ docker compose up -d
 cd backend && pixi run dev
 ```
 
-**Access:** [http://localhost:5173](http://localhost:5173) (frontend) | [http://localhost:8000/docs](http://localhost:8000/docs) (API)
+**Access (production):** [http://localhost:3000](http://localhost:3000) (frontend) | [http://localhost:8000/docs](http://localhost:8000/docs) (API)
+**Access (dev):** [http://localhost:5173](http://localhost:5173) (frontend, Vite) | [http://localhost:8000/docs](http://localhost:8000/docs) (API)
 
 **Note:** The native backend is required for camera access due to Raspberry Pi-specific libraries (libcamera, picamera2).
 
diff --git a/backend b/backend
index 8a68499..e5d26f2 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 8a684997c5a6cfd327e87aa96cef1bd38a1b7d05
+Subproject commit e5d26f2b71934951263d1f83fe60cec58a547fc8
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 0000000..ae1978f
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,27 @@
+# Development overrides for Digitization Toolkit
+# Replaces the production frontend with a Vite dev server (live reload).
+# Usage: docker compose -f docker-compose.yml -f docker-compose.dev.yml [--profile with-backend] up
+# Or via the helper script: ./scripts/start-dev.sh
+
+services:
+  frontend:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile.dev
+    ports:
+      - "5173:5173"
+    environment:
+      - NPM_CONFIG_AUDIT=false
+      - NPM_CONFIG_FUND=false
+    volumes:
+      - ./frontend:/app
+      - frontend_node_modules:/app/node_modules
+    command: >
+      sh -c "
+        npm install &&
+        npx svelte-kit sync &&
+        npm run dev -- --host 0.0.0.0
+      "
+
+volumes:
+  frontend_node_modules:
diff --git a/docker-compose.yml b/docker-compose.yml
index 4c788f0..9dfa99c 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -58,34 +58,31 @@ services:
     command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
 
   frontend:
+    # Production image: multi-stage build compiles Svelte at build time.
+    # No npm or source code in the running container → works fully offline
+    # after a one-time internet-connected `docker compose build`.
+    # For live-reload development use: docker compose -f docker-compose.yml -f docker-compose.dev.yml up
     build:
       context: ./frontend
-      dockerfile: Dockerfile.dev
+      dockerfile: Dockerfile
     env_file:
       - ./.env
     ports:
-      - "5173:5173"
-    # Allow container to reach host services
+      - "3000:3000"
+    # Allow container to reach host services (native backend)
     extra_hosts:
       - "host.docker.internal:host-gateway"
     environment:
       - PUBLIC_API_BASE=http://localhost:8000
       - PUBLIC_API_BASE_SSR=http://host.docker.internal:8000
-      - NPM_CONFIG_AUDIT=false
-      - NPM_CONFIG_FUND=false
-    volumes:
-      - ./frontend:/app
-      - frontend_node_modules:/app/node_modules
-    command: >
-      sh -c "
-        rm -rf /app/node_modules/* /app/node_modules/.* /app/package-lock.json 2>/dev/null || true &&
-        npm cache clean --force &&
-        npm install --include=optional --ignore-scripts &&
-        npm rebuild &&
-        npx svelte-kit sync &&
-        npm run dev -- --host 0.0.0.0
-      "
+      - PORT=3000
+      # ORIGIN: uncomment and set to the Pi's IP/hostname if form actions break
+      # (e.g. ORIGIN=http://192.168.1.x:3000). Not needed for API-only frontends.
+      # - ORIGIN=http://localhost:3000
+      - NODE_ENV=production
+    depends_on:
+      db:
+        condition: service_healthy
 
 volumes:
   postgres_data:
-  frontend_node_modules:
diff --git a/docs/developers/API_REFERENCE.md b/docs/developers/API_REFERENCE.md
index edf1d93..c8dcb10 100644
--- a/docs/developers/API_REFERENCE.md
+++ b/docs/developers/API_REFERENCE.md
@@ -2527,7 +2527,7 @@ LOG_LEVEL=info
 
 ### CORS Configuration
 
-Currently allows `http://localhost:5173` (Svelte dev server).
+Currently allows `http://localhost:5173` (Vite dev server) and `http://localhost:3000` (production Node server).
 
 **For production**, update `app/main.py`:
 ```python
diff --git a/frontend b/frontend
index d181471..1e4da2c 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit d181471d424b5b4be36168fc2a874f91db248b8a
+Subproject commit 1e4da2c00b6431a88f594eb3ef0f6cb0a5df4ec1
diff --git a/scripts/start-dev.sh b/scripts/start-dev.sh
index d919de2..fdc2f99 100755
--- a/scripts/start-dev.sh
+++ b/scripts/start-dev.sh
@@ -20,4 +20,4 @@ echo "  - Frontend (SvelteKit)"
 echo "  - Backend (FastAPI, no cameras)"
 echo ""
 
-docker compose --profile with-backend up --build
+docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile with-backend up --build

From c3c27b311a79771fd97070c969b85227e59947bd Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 20:06:25 -0800
Subject: [PATCH 40/55] chore: enhance setup and service scripts for improved
 SD card imaging and backend provisioning

---
 README.md                  |  52 +++++++++++++
 docker-compose.dev.yml     |   3 +
 scripts/dtk.service        |   5 +-
 scripts/install-service.sh |  15 ++++
 scripts/setup.sh           | 148 +++++++++++++++++++++++++++++++++++++
 scripts/start.sh           |   9 ++-
 6 files changed, 229 insertions(+), 3 deletions(-)
 create mode 100644 scripts/setup.sh

diff --git a/README.md b/README.md
index 8bd1002..49892d7 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,58 @@ pixi run setup-camera-link  # Raspberry Pi only
 pixi run dev
 ```
 
+## Production Distribution (SD Card Imaging)
+
+The toolkit is designed to ship as a pre-flashed SD card. The end user only needs to insert the card, power on the Pi, and the application starts automatically — no internet connection required.
+
+### Building the golden SD card (requires internet, done once)
+
+```bash
+# 1. Clone the repository onto a fresh Raspberry Pi OS installation
+git clone --recurse-submodules https://github.com/UCSB-AMPLab/digitization-toolkit.git ~/dtk
+cd ~/dtk
+
+# 2. Run the one-time provisioning script (internet required here)
+#    Builds Docker images, installs pixi env, applies DB migrations
+sudo ./scripts/setup.sh
+
+# 3. Install and enable the systemd service (auto-start on boot)
+sudo ./scripts/install-service.sh
+sudo systemctl start dtk
+
+# 4. Verify the app is running
+curl http://localhost:8000/health   # → {"status":"ok"}
+curl -I http://localhost:3000       # → HTTP 200
+```
+
+### Creating an SD card image
+
+```bash
+# On the Pi — shut down cleanly
+sudo systemctl stop dtk
+sudo poweroff
+
+# On a host machine with the SD card inserted (replace sdX with your device)
+sudo dd if=/dev/sdX of=dtk-$(date +%Y%m%d).img bs=4M status=progress
+# Compress for storage/transfer
+xz -T0 dtk-$(date +%Y%m%d).img
+```
+
+### Flashing for end users
+
+Use [Raspberry Pi Imager](https://www.raspberrypi.com/software/) (or `dd`) to write the `.img` to a new SD card.  
+The application starts automatically on boot — no configuration needed.
+
+### What's self-contained after provisioning
+
+| Component | Stored at | Requires internet after setup? |
+|---|---|---|
+| Frontend (SvelteKit) | Docker image in `/var/lib/docker/` | No |
+| PostgreSQL | Docker image in `/var/lib/docker/` | No |
+| Backend Python env | `backend/.pixi/` | No |
+| camera libraries | `/usr/lib/python3/dist-packages/` | No (system OS) |
+| Application data | `/var/lib/dtk/` | No |
+
 ## Setup
 
 This repository uses **Git submodules** for the `frontend` and `backend` code.  
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index ae1978f..64ee5c1 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -16,6 +16,9 @@ services:
     volumes:
       - ./frontend:/app
       - frontend_node_modules:/app/node_modules
+    # npm install runs on every start so package changes are picked up automatically.
+    # This is intentional for development — it requires internet access.
+    # The production image (frontend/Dockerfile) pre-builds everything and needs no npm at runtime.
     command: >
       sh -c "
         npm install &&
diff --git a/scripts/dtk.service b/scripts/dtk.service
index 074e495..7b9ec11 100644
--- a/scripts/dtk.service
+++ b/scripts/dtk.service
@@ -5,11 +5,14 @@ Requires=docker.service
 Documentation=https://github.com/UCSB-AMPLab/digitization-toolkit
 
 [Service]
-Type=forking
+Type=simple
 User=pi
 Group=pi
 WorkingDirectory=/home/pi/dtk
 
+# Ensure pixi and docker are on PATH (systemd uses a stripped environment)
+Environment="PATH=/home/pi/.pixi/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+
 # Start the application
 ExecStart=/home/pi/dtk/scripts/start.sh
 ExecStop=/home/pi/dtk/scripts/stop.sh
diff --git a/scripts/install-service.sh b/scripts/install-service.sh
index 4a752f4..14adc0c 100755
--- a/scripts/install-service.sh
+++ b/scripts/install-service.sh
@@ -21,6 +21,21 @@ if [ "$EUID" -ne 0 ]; then
     exit 1
 fi
 
+# Guard: make sure setup.sh has been run first
+if [ ! -d "$PROJECT_ROOT/backend/.pixi" ]; then
+    echo "✗ Backend pixi environment not found."
+    echo "  Run setup.sh first (requires internet):"
+    echo "    sudo $PROJECT_ROOT/scripts/setup.sh"
+    exit 1
+fi
+
+if ! docker image inspect dtk-frontend >/dev/null 2>&1; then
+    echo "✗ Frontend Docker image not found."
+    echo "  Run setup.sh first (requires internet):"
+    echo "    sudo $PROJECT_ROOT/scripts/setup.sh"
+    exit 1
+fi
+
 # Check if service file exists
 if [ ! -f "$SERVICE_FILE" ]; then
     echo "✗ Service file not found: $SERVICE_FILE"
diff --git a/scripts/setup.sh b/scripts/setup.sh
new file mode 100644
index 0000000..9c965a7
--- /dev/null
+++ b/scripts/setup.sh
@@ -0,0 +1,148 @@
+#!/bin/bash
+# One-time provisioning script for Digitization Toolkit
+#
+# Run this ONCE on the Pi while connected to the internet.
+# After completion the SD card can be imaged for offline distribution.
+#
+# What it does:
+#   1. Stops any running services for a clean slate
+#   2. Creates required system directories
+#   3. Builds Docker images (frontend multi-stage, pulls postgres:16-alpine)
+#   4. Installs backend pixi environment (conda-forge packages)
+#   5. Links system camera libraries (picamera2 / libcamera)
+#   6. Starts the DB, applies Alembic migrations, then stops it
+#
+# Usage: sudo ./scripts/setup.sh
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Resolve the real (non-root) user so pixi runs under the correct home dir
+if [ -n "$SUDO_USER" ]; then
+    DTK_USER="$SUDO_USER"
+else
+    DTK_USER="$(whoami)"
+fi
+DTK_USER_HOME=$(eval echo "~$DTK_USER")
+PIXI_BIN="$DTK_USER_HOME/.pixi/bin/pixi"
+
+if [ ! -x "$PIXI_BIN" ]; then
+    echo "✗ pixi not found at $PIXI_BIN"
+    echo "  Install pixi as $DTK_USER first:"
+    echo "    curl -fsSL https://pixi.sh/install.sh | bash"
+    exit 1
+fi
+
+# Run a command as DTK_USER, preserving the pixi bin in PATH
+run_as_user() {
+    sudo -u "$DTK_USER" env HOME="$DTK_USER_HOME" PATH="$DTK_USER_HOME/.pixi/bin:$PATH" "$@"
+}
+
+COMPOSE="docker compose -f $PROJECT_ROOT/docker-compose.yml -f $PROJECT_ROOT/docker-compose.pi.yml"
+
+cd "$PROJECT_ROOT"
+
+echo "=========================================="
+echo " Digitization Toolkit — Initial Setup"
+echo "=========================================="
+echo ""
+
+# ---------------------------------------------------------------------------
+# 1. Stop any running services
+# ---------------------------------------------------------------------------
+echo "→ Stopping any running services..."
+$COMPOSE down 2>/dev/null || true
+echo ""
+
+# ---------------------------------------------------------------------------
+# 2. System directories
+# ---------------------------------------------------------------------------
+echo "→ Creating system directories..."
+mkdir -p /var/lib/dtk/db/postgres
+mkdir -p /var/log/dtk
+chown -R "$DTK_USER:$DTK_USER" /var/lib/dtk /var/log/dtk 2>/dev/null || true
+echo "  /var/lib/dtk  ✓"
+echo "  /var/log/dtk  ✓"
+echo ""
+
+# ---------------------------------------------------------------------------
+# 3. Docker images
+# ---------------------------------------------------------------------------
+echo "→ Pulling base images and building services..."
+$COMPOSE pull db
+$COMPOSE build frontend
+echo ""
+
+# ---------------------------------------------------------------------------
+# 4. Pixi backend environment
+# ---------------------------------------------------------------------------
+echo "→ Installing backend dependencies (pixi)..."
+cd "$PROJECT_ROOT/backend"
+run_as_user "$PIXI_BIN" install
+echo ""
+
+# ---------------------------------------------------------------------------
+# 5. Camera system library link (Raspberry Pi only)
+# ---------------------------------------------------------------------------
+if python3 -c "import picamera2" 2>/dev/null || [ -d /usr/lib/python3/dist-packages/picamera2 ]; then
+    echo "→ Linking system camera libraries..."
+    run_as_user "$PIXI_BIN" run setup-camera-link
+    echo ""
+else
+    echo "→ Skipping camera link (picamera2 not found — OK on non-Pi hardware)"
+    echo ""
+fi
+
+# ---------------------------------------------------------------------------
+# 6. Database initialisation & migrations
+# ---------------------------------------------------------------------------
+cd "$PROJECT_ROOT"
+echo "→ Starting database for migration..."
+$COMPOSE up -d db
+
+echo "  Waiting for PostgreSQL to be ready..."
+for i in $(seq 1 30); do
+    if $COMPOSE exec -T db pg_isready -U "${DATABASE_USER:-user}" -d "${DATABASE_NAME:-digitization_toolkit}" >/dev/null 2>&1; then
+        echo "  Database ready."
+        break
+    fi
+    if [ "$i" -eq 30 ]; then
+        echo "✗ Database did not become ready after 60s."
+        echo "  Check logs: docker compose logs db"
+        $COMPOSE down
+        exit 1
+    fi
+    sleep 2
+done
+
+echo "→ Applying database migrations..."
+# DATABASE_HOST=localhost is already in .env; alembic reaches the DB
+# container via the exposed 5432 port on the host.
+cd "$PROJECT_ROOT/backend"
+run_as_user "$PIXI_BIN" run db-upgrade
+echo ""
+
+echo "→ Stopping database..."
+cd "$PROJECT_ROOT"
+$COMPOSE down
+echo ""
+
+# ---------------------------------------------------------------------------
+# Done
+# ---------------------------------------------------------------------------
+echo "=========================================="
+echo " Setup complete!"
+echo "=========================================="
+echo ""
+echo "The Pi is now ready for offline operation."
+echo ""
+echo "Next steps:"
+echo "  sudo ./scripts/install-service.sh   # Enable auto-start on boot"
+echo ""
+echo "Or start manually:"
+echo "  ./scripts/start.sh"
+echo ""
+echo "To distribute this setup, power off and image the SD card:"
+echo "  sudo poweroff"
diff --git a/scripts/start.sh b/scripts/start.sh
index e08751f..bba95c4 100755
--- a/scripts/start.sh
+++ b/scripts/start.sh
@@ -15,8 +15,9 @@ echo "=========================================="
 echo ""
 
 # Start Docker services (DB + Frontend)
+# Uses docker-compose.pi.yml overlay for proper appliance volume paths (/var/lib/dtk, /var/log/dtk)
 echo "→ Starting database and frontend containers..."
-docker compose up -d
+docker compose -f docker-compose.yml -f docker-compose.pi.yml up -d
 
 echo ""
 echo "→ Waiting for database to be ready..."
@@ -29,4 +30,8 @@ fi
 
 echo ""
 echo "→ Starting native backend with pixi..."
-cd "$PROJECT_ROOT/backend" && pixi run dev
+PIXI="${HOME}/.pixi/bin/pixi"
+if [ ! -x "$PIXI" ]; then
+    PIXI="$(command -v pixi 2>/dev/null || echo pixi)"
+fi
+cd "$PROJECT_ROOT/backend" && "$PIXI" run dev

From 6717ea86e0274437928ca4a222ba38edfe4d3c54 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 20:06:34 -0800
Subject: [PATCH 41/55] chore: update frontend and backend submodules to latest
 commits

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index e5d26f2..06a38c8 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit e5d26f2b71934951263d1f83fe60cec58a547fc8
+Subproject commit 06a38c827cfb315977e725fec908c4fbec508d88
diff --git a/frontend b/frontend
index 1e4da2c..c3a3af5 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 1e4da2c00b6431a88f594eb3ef0f6cb0a5df4ec1
+Subproject commit c3a3af5209313b39e5f4cc0af878e2009718f653

From 921408c2dba109c371978177e0182dc885e7c6ca Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 21:14:15 -0800
Subject: [PATCH 42/55] chore: add update script for Digitization Toolkit with
 service management and DB migrations

---
 scripts/update.sh | 119 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 scripts/update.sh

diff --git a/scripts/update.sh b/scripts/update.sh
new file mode 100644
index 0000000..ce69ab6
--- /dev/null
+++ b/scripts/update.sh
@@ -0,0 +1,119 @@
+#!/bin/bash
+# Update Digitization Toolkit to the latest committed code.
+#
+# This script is safe to run on a live Pi — it stops the service, applies
+# changes, runs any new DB migrations, then restarts.
+#
+# For a network-connected Pi (pull latest from git):
+#   git submodule update --remote --merge && sudo ./scripts/update.sh
+#
+# For an offline update from a USB drive, copy the new repo content first,
+# then run this script.
+#
+# Usage: sudo ./scripts/update.sh
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Resolve real user (same logic as setup.sh)
+if [ -n "$SUDO_USER" ]; then
+    DTK_USER="$SUDO_USER"
+else
+    DTK_USER="$(whoami)"
+fi
+DTK_USER_HOME=$(eval echo "~$DTK_USER")
+PIXI_BIN="$DTK_USER_HOME/.pixi/bin/pixi"
+
+run_as_user() {
+    sudo -u "$DTK_USER" env HOME="$DTK_USER_HOME" PATH="$DTK_USER_HOME/.pixi/bin:$PATH" "$@"
+}
+
+COMPOSE="docker compose -f $PROJECT_ROOT/docker-compose.yml -f $PROJECT_ROOT/docker-compose.pi.yml"
+
+cd "$PROJECT_ROOT"
+
+echo "=========================================="
+echo " Digitization Toolkit — Update"
+echo "=========================================="
+echo ""
+
+# ---------------------------------------------------------------------------
+# 1. Stop the service
+# ---------------------------------------------------------------------------
+echo "→ Stopping service..."
+systemctl stop dtk 2>/dev/null || true
+echo ""
+
+# ---------------------------------------------------------------------------
+# 2. Rebuild frontend image (always — picks up any code changes)
+# ---------------------------------------------------------------------------
+echo "→ Rebuilding frontend image..."
+$COMPOSE build frontend
+echo ""
+
+# ---------------------------------------------------------------------------
+# 3. Update pixi environment (picks up any new backend dependencies)
+# ---------------------------------------------------------------------------
+echo "→ Updating backend dependencies (pixi)..."
+cd "$PROJECT_ROOT/backend"
+run_as_user "$PIXI_BIN" install
+echo ""
+
+# ---------------------------------------------------------------------------
+# 4. Apply any new DB migrations
+# ---------------------------------------------------------------------------
+cd "$PROJECT_ROOT"
+echo "→ Starting database for migrations..."
+$COMPOSE up -d db
+
+echo "  Waiting for PostgreSQL to be ready..."
+for i in $(seq 1 30); do
+    if $COMPOSE exec -T db pg_isready -U "${DATABASE_USER:-user}" -d "${DATABASE_NAME:-digitization_toolkit}" >/dev/null 2>&1; then
+        echo "  Database ready."
+        break
+    fi
+    if [ "$i" -eq 30 ]; then
+        echo "✗ Database did not become ready after 60s."
+        $COMPOSE down
+        exit 1
+    fi
+    sleep 2
+done
+
+echo "→ Applying migrations..."
+cd "$PROJECT_ROOT/backend"
+run_as_user "$PIXI_BIN" run db-upgrade
+echo ""
+
+echo "→ Stopping database..."
+cd "$PROJECT_ROOT"
+$COMPOSE down
+echo ""
+
+# ---------------------------------------------------------------------------
+# 5. Restart the service
+# ---------------------------------------------------------------------------
+echo "→ Starting service..."
+systemctl start dtk
+sleep 5
+if systemctl is-active --quiet dtk; then
+    echo "  Service running ✓"
+else
+    echo "✗ Service failed to start. Check logs: journalctl -u dtk -n 50"
+    exit 1
+fi
+echo ""
+
+# ---------------------------------------------------------------------------
+# Done
+# ---------------------------------------------------------------------------
+echo "=========================================="
+echo " Update complete!"
+echo "=========================================="
+echo ""
+echo "  Frontend: http://localhost:3000"
+echo "  Backend:  http://localhost:8000/health"
+echo "  Logs:     journalctl -u dtk -f"
+echo ""

From 7a3781780094405eb734a8c17b427cc56ce3f5b7 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 21:14:22 -0800
Subject: [PATCH 43/55] chore: update submodule commits for backend and
 frontend

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index 06a38c8..7658691 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 06a38c827cfb315977e725fec908c4fbec508d88
+Subproject commit 765869178910a1cbd076c88053f8ff92e87c0bc1
diff --git a/frontend b/frontend
index c3a3af5..1b83af1 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit c3a3af5209313b39e5f4cc0af878e2009718f653
+Subproject commit 1b83af1e4a1f28541f223faa94511c900379f83c

From 0155fd3d2056746e97fa2f1714166ab63f72dbc1 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 21:33:41 -0800
Subject: [PATCH 44/55] chore: update start-kiosk.sh to use correct frontend
 URL

---
 scripts/start-kiosk.sh | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/scripts/start-kiosk.sh b/scripts/start-kiosk.sh
index 158b593..28663db 100755
--- a/scripts/start-kiosk.sh
+++ b/scripts/start-kiosk.sh
@@ -9,8 +9,8 @@ echo "To exit: Press Ctrl+Alt+F2, then run 'pkill cage'"
 echo ""
 
 # Wait for frontend to be ready
-echo -n "Waiting for frontend at http://localhost:5173..."
-until curl -sSf http://localhost:5173 >/dev/null 2>&1; do
+echo -n "Waiting for frontend at http://localhost:3000..."
+until curl -sSf http://localhost:3000 >/dev/null 2>&1; do
   echo -n "."
   sleep 1
 done
@@ -30,4 +30,4 @@ exec cage -- chromium-browser \
   --disable-features=TranslateUI \
   --overscroll-history-navigation=0 \
   --check-for-update-interval=31536000 \
-  http://localhost:5173
+  http://localhost:3000

From 04980403b77c2477a03dc8381a50280db7547db1 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 21:59:57 -0800
Subject: [PATCH 45/55] chore: update submodule commits for backend and
 frontend

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index 7658691..e626204 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit 765869178910a1cbd076c88053f8ff92e87c0bc1
+Subproject commit e6262044f65d091a292c393b3d4a0ebb37e814fa
diff --git a/frontend b/frontend
index 1b83af1..7adc08d 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 1b83af1e4a1f28541f223faa94511c900379f83c
+Subproject commit 7adc08dc2621f07c28b16730eb4046d3172e1718

From e055e1776c7360be351178b291024649898eb35b Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 22:23:35 -0800
Subject: [PATCH 46/55] feature: update install-kiosk-service.sh for auto-start
 configuration via .bash_profile

---
 scripts/install-kiosk-service.sh | 83 +++++++++++++++++++++-----------
 1 file changed, 56 insertions(+), 27 deletions(-)

diff --git a/scripts/install-kiosk-service.sh b/scripts/install-kiosk-service.sh
index e344919..5d1cb8e 100755
--- a/scripts/install-kiosk-service.sh
+++ b/scripts/install-kiosk-service.sh
@@ -1,42 +1,71 @@
 #!/bin/bash
-# Install systemd service for auto-starting kiosk on boot
+# Set up kiosk auto-start on boot via autologin + ~/.bash_profile
+#
+# The kiosk must run inside the tty1 login session (not as a standalone
+# systemd service) so that cage (Wayland compositor) takes ownership of
+# tty1, which is what the monitor displays.
+#
+# Boot sequence:
+#   getty@tty1 autologin → bash login shell → .bash_profile → start-kiosk.sh → cage
+#
+# Restart: when cage exits, the shell exits, getty re-autologins, .bash_profile
+# runs again → kiosk restarts automatically.
 
 set -e
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+KIOSK_USER="${SUDO_USER:-pi}"
+KIOSK_HOME=$(eval echo "~$KIOSK_USER")
+BASH_PROFILE="$KIOSK_HOME/.bash_profile"
+KIOSK_SCRIPT="/home/pi/dtk/scripts/start-kiosk.sh"
 
-echo "Creating kiosk systemd service..."
-
-cat > /tmp/kiosk.service << 'EOF'
-[Unit]
-Description=Wayland Kiosk (Cage + Chromium)
-After=network-online.target docker.service
-Wants=network-online.target
+echo "Setting up kiosk auto-start for user: $KIOSK_USER"
+echo ""
 
+# ── 1. Ensure autologin is configured for tty1 ──────────────────────────────
+echo "→ Configuring autologin on tty1..."
+sudo mkdir -p /etc/systemd/system/getty@tty1.service.d
+sudo tee /etc/systemd/system/getty@tty1.service.d/autologin.conf > /dev/null << EOF
 [Service]
-Type=simple
-User=pi
-Environment=XDG_RUNTIME_DIR=/run/user/1000
-ExecStart=/home/pi/dtk/scripts/start-kiosk.sh
-Restart=always
-RestartSec=3
-
-[Install]
-WantedBy=multi-user.target
+ExecStart=
+ExecStart=-/sbin/agetty --autologin $KIOSK_USER --noclear %I \$TERM
 EOF
-
-sudo mv /tmp/kiosk.service /etc/systemd/system/kiosk.service
 sudo systemctl daemon-reload
-sudo systemctl enable kiosk.service
+
+# ── 2. Write ~/.bash_profile to launch kiosk on tty1 ────────────────────────
+echo "→ Writing $BASH_PROFILE..."
+cat > "$BASH_PROFILE" << EOF
+# ~/.bash_profile - executed for login shells (including autologin on tty1)
+
+# Source .bashrc if present (standard practice)
+if [ -f "\$HOME/.bashrc" ]; then
+    . "\$HOME/.bashrc"
+fi
+
+# Start the kiosk when autologged-in on tty1.
+# cage (Wayland compositor + Chromium) must run from the tty1 login session
+# so it takes ownership of tty1 and is visible on the monitor.
+# When cage exits, this shell exits → getty re-autologins → kiosk restarts.
+if [[ "\$(tty)" == "/dev/tty1" ]]; then
+    exec $KIOSK_SCRIPT
+fi
+EOF
+chown "$KIOSK_USER:$KIOSK_USER" "$BASH_PROFILE"
+
+# ── 3. Remove old kiosk.service if present (replaced by .bash_profile) ──────
+if systemctl is-enabled kiosk.service &>/dev/null; then
+    echo "→ Disabling legacy kiosk.service..."
+    sudo systemctl disable kiosk.service
+    sudo systemctl stop kiosk.service 2>/dev/null || true
+fi
 
 echo ""
-echo "✓ Kiosk service installed and enabled!"
+echo "✓ Kiosk auto-start configured!"
 echo ""
 echo "The kiosk will start automatically on next boot."
+echo "(dtk.service starts Docker/backend; autologin starts cage on tty1)"
+echo ""
+echo "To apply immediately without rebooting:"
+echo "  exec /home/pi/dtk/scripts/start-kiosk.sh"
 echo ""
-echo "To control it:"
-echo "  sudo systemctl start kiosk    # Start now"
-echo "  sudo systemctl stop kiosk     # Stop"
-echo "  sudo systemctl status kiosk   # Check status"
-echo "  sudo systemctl disable kiosk  # Disable auto-start"
+echo "To disable auto-start, remove the tty1 block from $BASH_PROFILE"
 echo ""

From 0cea966674b270e0f23196ba3d50a241d0c799bd Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 22:47:18 -0800
Subject: [PATCH 47/55] chore: optimize Docker healthcheck intervals and
 frontend startup process

---
 docker-compose.yml     | 10 +++++-----
 scripts/start-kiosk.sh |  7 ++++++-
 scripts/start.sh       | 14 +++-----------
 3 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 9dfa99c..5a12941 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -22,9 +22,10 @@ services:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U ${DATABASE_USER:-user} -d ${DATABASE_NAME:-digitization_toolkit}"]
-      interval: 10s
+      interval: 2s
       timeout: 5s
-      retries: 5
+      retries: 15
+      start_period: 5s
 
   # Backend service (optional for Docker-based development)
   # On Raspberry Pi with cameras, run backend natively: cd backend && pixi run dev
@@ -80,9 +81,8 @@ services:
       # (e.g. ORIGIN=http://192.168.1.x:3000). Not needed for API-only frontends.
       # - ORIGIN=http://localhost:3000
       - NODE_ENV=production
-    depends_on:
-      db:
-        condition: service_healthy
+    # No depends_on db — the frontend is a Node.js API proxy and never connects
+    # to Postgres directly. Removing this lets db and frontend start in parallel.
 
 volumes:
   postgres_data:
diff --git a/scripts/start-kiosk.sh b/scripts/start-kiosk.sh
index 28663db..d8c3e37 100755
--- a/scripts/start-kiosk.sh
+++ b/scripts/start-kiosk.sh
@@ -12,7 +12,7 @@ echo ""
 echo -n "Waiting for frontend at http://localhost:3000..."
 until curl -sSf http://localhost:3000 >/dev/null 2>&1; do
   echo -n "."
-  sleep 1
+  sleep 0.2
 done
 echo " ✓ Ready!"
 
@@ -30,4 +30,9 @@ exec cage -- chromium-browser \
   --disable-features=TranslateUI \
   --overscroll-history-navigation=0 \
   --check-for-update-interval=31536000 \
+  --no-first-run \
+  --disable-sync \
+  --disable-background-networking \
+  --disable-default-apps \
+  --disable-extensions \
   http://localhost:3000
diff --git a/scripts/start.sh b/scripts/start.sh
index bba95c4..299cd7b 100755
--- a/scripts/start.sh
+++ b/scripts/start.sh
@@ -17,16 +17,8 @@ echo ""
 # Start Docker services (DB + Frontend)
 # Uses docker-compose.pi.yml overlay for proper appliance volume paths (/var/lib/dtk, /var/log/dtk)
 echo "→ Starting database and frontend containers..."
-docker compose -f docker-compose.yml -f docker-compose.pi.yml up -d
-
-echo ""
-echo "→ Waiting for database to be ready..."
-sleep 3
-
-# Check if database is healthy
-if ! docker compose ps | grep -q "db.*healthy"; then
-    echo "⚠ Warning: Database may still be starting up"
-fi
+# --pull never: skip registry checks (device is offline after initial build)
+docker compose -f docker-compose.yml -f docker-compose.pi.yml up -d --pull never
 
 echo ""
 echo "→ Starting native backend with pixi..."
@@ -34,4 +26,4 @@ PIXI="${HOME}/.pixi/bin/pixi"
 if [ ! -x "$PIXI" ]; then
     PIXI="$(command -v pixi 2>/dev/null || echo pixi)"
 fi
-cd "$PROJECT_ROOT/backend" && "$PIXI" run dev
+cd "$PROJECT_ROOT/backend" && "$PIXI" run start

From 65342a0fa208a3b7da695552f3f8056017f4df61 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 23:26:45 -0800
Subject: [PATCH 48/55] chore: remove unnecessary svelte-kit sync command from
 development setup

---
 docker-compose.dev.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 64ee5c1..cf26b35 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -11,6 +11,7 @@ services:
     ports:
       - "5173:5173"
     environment:
+      - NODE_ENV=development
       - NPM_CONFIG_AUDIT=false
       - NPM_CONFIG_FUND=false
     volumes:
@@ -22,7 +23,6 @@ services:
     command: >
       sh -c "
         npm install &&
-        npx svelte-kit sync &&
         npm run dev -- --host 0.0.0.0
       "
 

From ebf5f8b76e45a36f98412fea9c739f9c965b4214 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 23:26:52 -0800
Subject: [PATCH 49/55] chore: update frontend submodule to latest commit

---
 frontend | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/frontend b/frontend
index 7adc08d..2c9ee10 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 7adc08dc2621f07c28b16730eb4046d3172e1718
+Subproject commit 2c9ee10be358c758243283de84d30ad366fae72e

From e4ae29f424f3c96597b4d61a16dd6b1fcf1a34b6 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 23:35:26 -0800
Subject: [PATCH 50/55] chore: add automatic migrations for backend on dev
 startup

---
 docker-compose.dev.yml | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index cf26b35..cb49147 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -4,6 +4,16 @@
 # Or via the helper script: ./scripts/start-dev.sh
 
 services:
+  backend:
+    # Run migrations automatically on every dev startup so a fresh DB volume
+    # always has the correct schema. Production runs migrations manually via
+    # `pixi run db-upgrade` before starting the native backend.
+    command: >
+      sh -c "
+        alembic upgrade head &&
+        uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+      "
+
   frontend:
     build:
       context: ./frontend

From 0765df5386f1c6537dd1fa999116a4d06a1f4e7e Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Fri, 20 Feb 2026 23:53:58 -0800
Subject: [PATCH 51/55] feat: add development startup powershell script

---
 scripts/start-dev.ps1 | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
 create mode 100644 scripts/start-dev.ps1

diff --git a/scripts/start-dev.ps1 b/scripts/start-dev.ps1
new file mode 100644
index 0000000..8f1bbdd
--- /dev/null
+++ b/scripts/start-dev.ps1
@@ -0,0 +1,26 @@
+# Development startup script for Digitization Toolkit
+# Starts all services in Docker (database + frontend + backend)
+# Use this on machines without camera hardware
+
+# Exit on error
+$ErrorActionPreference = 'Stop'
+
+# Get script directory and project root
+$ScriptDir = $PSScriptRoot
+$ProjectRoot = Split-Path -Parent $ScriptDir
+
+# Change to project root
+Set-Location $ProjectRoot
+
+Write-Host "==========================================" -ForegroundColor Cyan
+Write-Host "Starting Digitization Toolkit (Development)" -ForegroundColor Cyan
+Write-Host "==========================================" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "Starting all services in Docker..." -ForegroundColor Green
+Write-Host "  - Database (PostgreSQL)"
+Write-Host "  - Frontend (SvelteKit)"
+Write-Host "  - Backend (FastAPI, no cameras)"
+Write-Host ""
+
+# Start Docker Compose with dev configuration
+docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile with-backend up --build

From 66bf62e0ad7353f1b0a68915d05a61f29b5a292b Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Sat, 21 Feb 2026 00:08:23 -0800
Subject: [PATCH 52/55] feat: add development startup batch script for Docker
 services

---
 scripts/start-dev.bat | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 scripts/start-dev.bat

diff --git a/scripts/start-dev.bat b/scripts/start-dev.bat
new file mode 100644
index 0000000..425a42a
--- /dev/null
+++ b/scripts/start-dev.bat
@@ -0,0 +1,20 @@
+:: Development startup script for Digitization Toolkit
+:: Starts all services in Docker (database + frontend + backend)
+:: Use this on machines without camera hardware
+
+@echo off
+
+SET script_dir=%~dp0
+CD /D "%script_dir%.."
+
+echo ==========================================
+echo Starting Digitization Toolkit (Development)
+echo ==========================================
+echo.
+echo Starting all services in Docker...
+echo   - Database (PostgreSQL)
+echo   - Frontend (SvelteKit)
+echo   - Backend (FastAPI, no cameras)
+echo.
+
+docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile with-backend up --build

From a81962b024950c58e1d0bc8e87b4ccea114df35b Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Thu, 5 Mar 2026 09:32:34 -0800
Subject: [PATCH 53/55] chore: remove backend service from development
 docker-compose configuration

---
 docker-compose.dev.yml | 16 ++--------------
 1 file changed, 2 insertions(+), 14 deletions(-)

diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index cb49147..7bfc04b 100644
--- a/docker-compose.dev.yml
+++ b/docker-compose.dev.yml
@@ -4,16 +4,6 @@
 # Or via the helper script: ./scripts/start-dev.sh
 
 services:
-  backend:
-    # Run migrations automatically on every dev startup so a fresh DB volume
-    # always has the correct schema. Production runs migrations manually via
-    # `pixi run db-upgrade` before starting the native backend.
-    command: >
-      sh -c "
-        alembic upgrade head &&
-        uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
-      "
-
   frontend:
     build:
       context: ./frontend
@@ -27,14 +17,12 @@ services:
     volumes:
       - ./frontend:/app
       - frontend_node_modules:/app/node_modules
-    # npm install runs on every start so package changes are picked up automatically.
-    # This is intentional for development — it requires internet access.
-    # The production image (frontend/Dockerfile) pre-builds everything and needs no npm at runtime.
     command: >
       sh -c "
         npm install &&
+        npx svelte-kit sync &&
         npm run dev -- --host 0.0.0.0
       "
 
 volumes:
-  frontend_node_modules:
+  frontend_node_modules:
\ No newline at end of file

From 9f37afa1e2dc23e538999b7a724035aecd09c2fa Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Thu, 5 Mar 2026 09:34:21 -0800
Subject: [PATCH 54/55] chore: update submodule commits for backend and
 frontend

---
 backend  | 2 +-
 frontend | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/backend b/backend
index e626204..a172e0e 160000
--- a/backend
+++ b/backend
@@ -1 +1 @@
-Subproject commit e6262044f65d091a292c393b3d4a0ebb37e814fa
+Subproject commit a172e0efda0cd48194bdcf596592723725fe6f5e
diff --git a/frontend b/frontend
index 2c9ee10..c73d6b9 160000
--- a/frontend
+++ b/frontend
@@ -1 +1 @@
-Subproject commit 2c9ee10be358c758243283de84d30ad366fae72e
+Subproject commit c73d6b9fa34552816eee15637caf4647e2365ef2

From e6587b83ef2f2b79952322984b0116f844f6dbb5 Mon Sep 17 00:00:00 2001
From: jairomelo <jairoantoniomelo@gmail.com>
Date: Thu, 5 Mar 2026 09:45:01 -0800
Subject: [PATCH 55/55] feat: update backend command to run database migrations
 before starting the server

---
 docker-compose.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index 5a12941..c6de7ad 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -56,7 +56,8 @@ services:
     depends_on:
       db:
         condition: service_healthy
-    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+    command: >
+      sh -c "alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload"
 
   frontend:
     # Production image: multi-stage build compiles Svelte at build time.