chore: auto-merge develop → main

Triggered by: cf65e79 Release v1.7.36: recipe stock hints, ghost products, and shopping total fix.

.dockerignore

@@ -1,5 +1,5 @@
 # Docker runtime files
-data/dispensa.db
+data/evershelf.db
 data/*.db-wal
 data/*.db-shm
 data/backups/
@@ -7,7 +7,6 @@ data/cron.log
 data/smart_shopping_cache.json
 data/bring_token.json
 data/bring_catalog.json
-data/dupliclick_token.json
 data/client_debug.log
 data/*.crt
 data/*.pem

.env.example

@@ -1,22 +1,178 @@
-# Dispensa Manager - Configuration
-# Copy this file to .env and fill in your values
-# cp .env.example .env
+# EverShelf — Configuration
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+#
+# All settings here can also be changed from the in-app Settings screen and
+# will be written back to this file automatically.
+# ─────────────────────────────────────────────────────────────────────────────
 
-# Google Gemini AI API Key (required for AI features)
-# Get one at: https://aistudio.google.com/app/apikey
+# ── AI ────────────────────────────────────────────────────────────────────────
+# Google Gemini API key (required for AI features: expiry reading, recipe gen, …)
+# Get one free at: https://aistudio.google.com/app/apikey
 GEMINI_API_KEY=
 
-# Bring! Shopping List credentials (optional)
-# Sign up at: https://www.getbring.com/
+# ── Shopping list (Bring!) ────────────────────────────────────────────────────
+# Credentials for the Bring! app (optional — app works without it)
 BRING_EMAIL=
 BRING_PASSWORD=
 
-# TTS (Text-to-Speech) for cooking mode voice guidance (optional)
-# Works with Home Assistant, or any HTTP endpoint that accepts text
-TTS_URL=
-TTS_TOKEN=
-TTS_METHOD=POST
-TTS_AUTH_TYPE=bearer
-TTS_CONTENT_TYPE=application/json
-TTS_PAYLOAD_KEY=message
+# ── Text-to-Speech (TTS) ─────────────────────────────────────────────────────
+# Works with Home Assistant, a local TTS server, or any HTTP endpoint.
+# TTS_ENABLED: master switch (true/false)
 TTS_ENABLED=false
+# TTS_URL: endpoint that receives the text payload
+TTS_URL=
+# TTS_TOKEN: Authorization token sent as Bearer header (or empty)
+TTS_TOKEN=
+# TTS_METHOD: HTTP method (POST or GET)
+TTS_METHOD=POST
+# TTS_AUTH_TYPE: how the token is sent (bearer | basic | none)
+TTS_AUTH_TYPE=bearer
+# TTS_CONTENT_TYPE: request Content-Type header
+TTS_CONTENT_TYPE=application/json
+# TTS_PAYLOAD_KEY: JSON key that carries the text (e.g. "message", "text")
+TTS_PAYLOAD_KEY=message
+# TTS_ENGINE: preferred browser TTS engine ('browser', 'server', 'custom') — optional
+TTS_ENGINE=
+# TTS_RATE / TTS_PITCH: speech rate and pitch multipliers (1 = normal)
+TTS_RATE=1
+TTS_PITCH=1
+# TTS_AUTH_HEADER_NAME / VALUE: custom HTTP header for authentication (optional)
+TTS_AUTH_HEADER_NAME=
+TTS_AUTH_HEADER_VALUE=
+# TTS_EXTRA_FIELDS: additional JSON fields as key=value pairs, comma-separated (optional)
+TTS_EXTRA_FIELDS=
+
+# ── User preferences ─────────────────────────────────────────────────────────
+# These mirror the toggle switches in the Settings screen.
+DEFAULT_PERSONS=1
+PREF_VELOCE=false
+PREF_POCAFAME=false
+PREF_SCADENZE=true
+PREF_HEALTHY=false
+PREF_OPENED=true
+PREF_ZEROWASTE=false
+# Dietary restrictions shown to the AI (e.g. "vegetariano,senza glutine")
+DIETARY=
+
+# ── Appliances ────────────────────────────────────────────────────────────────
+# Comma-separated list of appliances available in your kitchen.
+# Used by the AI when generating recipes.
+APPLIANCES=Forno,Microonde,Friggitrice ad aria,Pentola a pressione
+
+# ── Camera ───────────────────────────────────────────────────────────────────
+# Default camera for barcode scanning ('environment' = rear, 'user' = front)
+CAMERA_FACING=environment
+
+# ── Smart Kitchen Scale ───────────────────────────────────────────────────────
+# SCALE_ENABLED: enables the scale integration
+SCALE_ENABLED=false
+# SCALE_GATEWAY_URL: address of the EverShelf Scale Gateway (Android app)
+SCALE_GATEWAY_URL=
+
+# ── Meal Plan ────────────────────────────────────────────────────────────────
+# MEAL_PLAN_ENABLED: show the weekly meal planner tab in Settings
+MEAL_PLAN_ENABLED=false
+
+# ── Screensaver (kiosk / tablet mode) ────────────────────────────────────────
+SCREENSAVER_ENABLED=false
+# SCREENSAVER_TIMEOUT: inactivity seconds before screensaver activates (default 5 min)
+SCREENSAVER_TIMEOUT=300
+
+# ── Price estimates ───────────────────────────────────────────────────────────
+# PRICE_ENABLED: show AI-estimated price column on the shopping list
+PRICE_ENABLED=false
+# PRICE_COUNTRY: country used for price context (e.g. "Italia", "Germany")
+PRICE_COUNTRY=Italia
+# PRICE_CURRENCY: ISO 4217 currency code (e.g. EUR, USD, GBP)
+PRICE_CURRENCY=EUR
+# PRICE_UPDATE_MONTHS: how many months to cache a price before re-fetching (default 3)
+PRICE_UPDATE_MONTHS=3
+
+# ── Cleanup / retention ──────────────────────────────────────────────────────
+# RECIPE_RETENTION_DAYS: delete auto-generated recipe plans older than N days
+RECIPE_RETENTION_DAYS=7
+# TRANSACTION_RETENTION_DAYS: keep stock transaction history for N days.
+# Smart Shopping uses this history to compute purchase frequencies.
+# WARNING: values below 30 will cause the shopping list to appear nearly empty.
+# Minimum enforced at runtime: 30 days.
+TRANSACTION_RETENTION_DAYS=90
+
+# ── Local Backup ─────────────────────────────────────────────────────────────
+# BACKUP_ENABLED: run a daily incremental backup via cron (true/false)
+BACKUP_ENABLED=true
+# BACKUP_RETENTION_DAYS: keep local backups for N days (minimum 1)
+BACKUP_RETENTION_DAYS=3
+
+# ── Google Drive Backup ───────────────────────────────────────────────────────
+# GDRIVE_ENABLED: upload the daily backup to Google Drive (requires a service account)
+GDRIVE_ENABLED=false
+#
+# Setup steps:
+#   1. Create a Google Cloud project and enable the Drive API
+#   2. Create a Service Account and download the JSON key
+#   3. Create a Drive folder and share it with the service account email
+#   4. Paste the JSON content below (or set GDRIVE_SERVICE_ACCOUNT_FILE to the path)
+#   5. Set GDRIVE_FOLDER_ID to the Drive folder ID (from its URL)
+#
+# GDRIVE_SERVICE_ACCOUNT_JSON: full JSON content of the service account key
+GDRIVE_SERVICE_ACCOUNT_JSON=
+# GDRIVE_SERVICE_ACCOUNT_FILE: alternative — path to the service account JSON file
+GDRIVE_SERVICE_ACCOUNT_FILE=
+# GDRIVE_FOLDER_ID: ID of the Drive folder where backups will be stored
+GDRIVE_FOLDER_ID=
+# GDRIVE_RETENTION_DAYS: delete Drive backups older than N days (0 = keep all)
+GDRIVE_RETENTION_DAYS=30
+
+# ── Security ─────────────────────────────────────────────────────────────────
+# API_TOKEN: when set, all API calls require header X-API-Token (or ?api_token= for HA).
+# SETTINGS_TOKEN: legacy alias — use API_TOKEN for new installs.
+API_TOKEN=
+SETTINGS_TOKEN=
+
+# CORS_ORIGIN: comma-separated allowed origins (empty = same-origin only, no wildcard)
+CORS_ORIGIN=
+
+# GitHub automatic issue reporting (encrypted storage recommended)
+# Option A — plain ( .env is gitignored ):
+# GH_ISSUE_TOKEN=ghp_...
+# Option B — encrypted (php scripts/encrypt-gh-token.php 'ghp_...' 'secret-key'):
+GH_ISSUE_TOKEN=
+GH_ISSUE_TOKEN_ENC=
+GH_ISSUE_TOKEN_KEY=
+
+# NOTE: Run `php scripts/migrate-env-security.php` once after upgrading to migrate legacy tokens.
+
+# INSTANCE_NAME: display name for this EverShelf instance (used by the HA integration
+# for Zeroconf discovery label and device name in Home Assistant).
+# Defaults to the server hostname if left empty.
+INSTANCE_NAME=
+
+# ── Home Assistant Integration ────────────────────────────────────────────────
+# All HA settings can also be configured from the Settings → 🏠 tab.
+#
+# HA_ENABLED: master switch for all HA features (webhooks, TTS, sensors)
+HA_ENABLED=false
+# HA_URL: base URL of your HA instance — no trailing slash
+# Examples: http://homeassistant.local:8123  or  http://192.168.1.50:8123
+HA_URL=
+# HA_TOKEN: Long-Lived Access Token (HA Profile → Security → Long-Lived Access Tokens)
+HA_TOKEN=
+# HA_TTS_ENTITY: media_player entity for recipe step TTS (e.g. media_player.living_room)
+HA_TTS_ENTITY=
+# HA_WEBHOOK_ID: ID of an HA automation's Webhook trigger
+HA_WEBHOOK_ID=
+# HA_WEBHOOK_EVENTS: comma-separated events to fire webhooks for
+#   Available: expiry, shopping_add, stock_update, barcode_scan
+HA_WEBHOOK_EVENTS=expiry,shopping_add,stock_update
+# HA_NOTIFY_SERVICE: HA notify service for push alerts (e.g. notify.mobile_app_my_phone)
+HA_NOTIFY_SERVICE=
+# HA_EXPIRY_DAYS: days before expiry to trigger expiry alert (default 3)
+HA_EXPIRY_DAYS=3
+
+# ── Developer / demo ─────────────────────────────────────────────────────────
+# DEMO_MODE: when true, all write operations are blocked (for public demos)
+DEMO_MODE=false
+
+# CRON_LOG_MAX_BYTES: rotate data/cron.log when larger (default 524288 = 512 KB)
+CRON_LOG_MAX_BYTES=524288

.github/FUNDING.yml

@@ -0,0 +1 @@
+ko_fi: evershelfproject

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,114 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in EverShelf
+title: "[BUG] "
+labels: ["bug"]
+assignees: ["dadaloop82"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill in the details below.
+        Before submitting, check the [FAQ](https://github.com/dadaloop82/EverShelf/wiki/FAQ) and [existing issues](https://github.com/dadaloop82/EverShelf/issues?q=is%3Aissue+label%3Abug).
+
+  - type: input
+    id: version
+    attributes:
+      label: EverShelf Version
+      description: Found in Settings → About, or in the footer of the web app.
+      placeholder: "e.g. 1.7.13"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of EverShelf is affected?
+      options:
+        - Web app (browser / PWA)
+        - Android Kiosk app
+        - API / PHP backend
+        - Docker setup
+        - Bring! integration
+        - AI features (Gemini)
+        - Smart Scale
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of the bug.
+      placeholder: "What went wrong?"
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this?
+      placeholder: |
+        1. Go to '...'
+        2. Tap '...'
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should have happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include error messages, screenshots, or console output.
+    validations:
+      required: true
+
+  - type: input
+    id: browser
+    attributes:
+      label: Browser / OS
+      placeholder: "e.g. Chrome 124 on Android 13, Safari on iOS 17, Firefox on Ubuntu 22.04"
+
+  - type: input
+    id: php
+    attributes:
+      label: PHP Version (if relevant)
+      placeholder: "e.g. 8.2.12 — run: php -v"
+
+  - type: dropdown
+    id: install
+    attributes:
+      label: Installation Method
+      options:
+        - Docker (docker compose)
+        - Manual (Apache/Nginx)
+        - Other
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs
+      description: PHP error log, browser console output, or `data/error_reports.log` snippet.
+      render: text
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I searched existing issues and this is not a duplicate
+          required: true
+        - label: I checked the FAQ
+          required: true
+        - label: I am on the latest version (or this bug exists on the latest version)
+          required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 📖 Wiki & FAQ
+    url: https://github.com/dadaloop82/EverShelf/wiki/FAQ
+    about: Check the FAQ — your question may already be answered there.
+  - name: 💬 Discussions — Q&A
+    url: https://github.com/dadaloop82/EverShelf/discussions
+    about: General questions, show-and-tell, ideas — use Discussions, not Issues.
+  - name: 🔒 Security Vulnerability
+    url: mailto:evershelfproject@gmail.com
+    about: Please report security vulnerabilities privately via email, not as a public issue.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,68 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+title: "[FEATURE] "
+labels: ["enhancement"]
+assignees: ["dadaloop82"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the idea! Check the [Roadmap](https://github.com/dadaloop82/EverShelf/blob/main/README.md#-roadmap) and [Discussions](https://github.com/dadaloop82/EverShelf/discussions) first — it may already be planned or discussed.
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Category
+      options:
+        - Inventory management
+        - Shopping list
+        - AI / Gemini features
+        - Cooking mode
+        - Dashboard / stats
+        - Kiosk app
+        - Smart Scale
+        - Integrations (Bring!, HA, etc.)
+        - Performance / developer experience
+        - Translations / i18n
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: What pain point does this address? Why do you need this?
+      placeholder: "I'm always frustrated when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe what you'd like to see added or changed.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any workarounds you've tried, or other solutions you considered?
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Screenshots, mockups, links to similar features in other apps, etc.
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      options:
+        - label: I checked the Roadmap and this is not already planned
+          required: true
+        - label: I searched existing issues and discussions — this is not a duplicate
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,47 @@
+## Description
+
+<!-- What does this PR do? Link the related issue: "Closes #123" or "Relates to #123" -->
+
+Closes #
+
+---
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Refactor / cleanup (no functional change)
+- [ ] Documentation update
+- [ ] Translation update
+
+---
+
+## Testing
+
+<!-- How was this tested? -->
+
+- [ ] Tested locally (PHP built-in server or Docker)
+- [ ] Tested on mobile browser
+- [ ] Tested with Docker Compose: `docker compose up --build`
+- [ ] PHP syntax: `php -l api/index.php && php -l api/database.php`
+- [ ] JS syntax: `node --check assets/js/app.js`
+
+---
+
+## Translation
+
+- [ ] New user-visible strings added → translation keys added to **all three** files: `translations/it.json`, `en.json`, `de.json`
+- [ ] No user-visible strings changed
+
+---
+
+## CHANGELOG
+
+- [ ] Entry added to `CHANGELOG.md` under `## [Unreleased]` or the correct version
+
+---
+
+## Screenshots / Video
+
+<!-- If this is a UI change, add before/after screenshots. Delete this section if not applicable. -->

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "ci"
+    labels:
+      - "dependencies"

.github/workflows/build-kiosk.yml

@@ -0,0 +1,81 @@
+name: Build & Release Kiosk APK
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'evershelf-kiosk/**'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build Kiosk APK
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v3
+        with:
+          gradle-version: '8.6'
+
+      - name: Get version name
+        id: version
+        run: |
+          VERSION=$(grep 'versionName' evershelf-kiosk/app/build.gradle.kts | grep -oP '"\K[^"]+')
+          echo "name=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Kiosk version: $VERSION"
+
+      - name: Build debug APK
+        run: gradle assembleDebug --no-daemon
+        working-directory: evershelf-kiosk
+
+      - name: Rename APK
+        run: |
+          mkdir -p artifacts
+          cp evershelf-kiosk/app/build/outputs/apk/debug/app-debug.apk artifacts/evershelf-kiosk.apk
+
+      # Publish with a semver-compatible tag so the in-app update check can
+      # compare versions numerically (tag "kiosk-1.7.0" → norm → "1.7.0").
+      # Also update the "kiosk-latest" tag so the hardcoded download URL still works.
+      - name: Create versioned release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="kiosk-${{ steps.version.outputs.name }}"
+          # Delete old release with same tag if it exists (e.g. re-run on same version)
+          gh release delete "$TAG" --yes 2>/dev/null || true
+          git push --delete origin "$TAG" 2>/dev/null || true
+          gh release create "$TAG" \
+            --title "EverShelf Kiosk v${{ steps.version.outputs.name }}" \
+            --notes "Kiosk mode app. Scarica e installa su Android 7.0+. L'aggiornamento OTA è automatico." \
+            --latest \
+            artifacts/evershelf-kiosk.apk
+
+      - name: Update kiosk-latest tag (for hardcoded download URL)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release delete kiosk-latest --yes 2>/dev/null || true
+          git push --delete origin kiosk-latest 2>/dev/null || true
+          sleep 3
+          gh release create kiosk-latest \
+            --title "EverShelf Kiosk Latest" \
+            --notes "Alias automatico → kiosk-${{ steps.version.outputs.name }}" \
+            --prerelease \
+            artifacts/evershelf-kiosk.apk
+

.github/workflows/build-scale-gateway.yml

@@ -0,0 +1,64 @@
+name: Build & Release Scale Gateway APK (DEPRECATED)
+# ⚠️  This workflow is disabled. The Scale Gateway is deprecated since Kiosk v1.6.0.
+# BLE scale support is now built into the EverShelf Kiosk app.
+# Kept for reference — re-enable manually via workflow_dispatch if needed for legacy setups.
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm:
+        description: "Type 'yes' to confirm you want to build the deprecated gateway APK"
+        required: true
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build APK
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v3
+        with:
+          gradle-version: '8.4'
+
+      - name: Build debug APK
+        run: gradle assembleDebug --no-daemon
+        working-directory: evershelf-scale-gateway
+
+      - name: Rename APK
+        run: |
+          mkdir -p artifacts
+          cp evershelf-scale-gateway/app/build/outputs/apk/debug/app-debug.apk artifacts/evershelf-scale-gateway.apk
+
+      - name: Get version name
+        id: version
+        run: |
+          VERSION=$(grep 'versionName' evershelf-scale-gateway/app/build.gradle.kts | grep -oP '"\K[^"]+')
+          echo "name=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Delete existing latest release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release delete latest --yes || true
+
+      - name: Create GitHub Release and upload APK
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create latest \
+            --title "EverShelf Scale Gateway v${{ steps.version.outputs.name }}" \
+            --notes "Download the APK and install it on your Android device (7.0+). Allow installation from unknown sources in settings." \
+            --latest \
+            artifacts/evershelf-scale-gateway.apk

.github/workflows/ci.yml

@@ -6,12 +6,15 @@ on:
   pull_request:
     branches: [main]
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   lint-php:
     name: PHP Syntax Check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
@@ -27,7 +30,7 @@ jobs:
     name: JavaScript Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Check JS syntax
         run: |
@@ -37,23 +40,23 @@ jobs:
     name: Docker Build Test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Build Docker image
-        run: docker build -t dispensa-test .
+        run: docker build -t evershelf-test .
 
       - name: Test container starts
         run: |
-          docker run -d --name test-dispensa -p 8080:80 dispensa-test
+          docker run -d --name test-evershelf -p 8080:80 evershelf-test
           sleep 5
           curl -f http://localhost:8080/ || exit 1
-          docker stop test-dispensa
+          docker stop test-evershelf
 
   validate-translations:
     name: Validate Translation Files
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Validate JSON syntax
         run: |
@@ -86,3 +89,127 @@ jobs:
               else:
                   print(f'{f}: complete ✓')
           "
+
+  # ── Auto-merge develop → main ────────────────────────────────────────────
+  # Runs automatically after ALL checks pass on develop.
+  # You never need to merge manually again — just push to develop.
+  auto-merge-to-main:
+    name: Auto-merge develop → main
+    needs: [lint-php, lint-js, docker-build, validate-translations]
+    if: github.ref == 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout (full history)
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          # Always use the built-in GITHUB_TOKEN for checkout (read-only fetch).
+          # WORKFLOW_PAT is only needed for the push step below.
+          token: ${{ github.token }}
+
+      - name: Configure git bot identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Merge develop → main
+        run: |
+          # ── ROOT CAUSE FIX ──────────────────────────────────────────────────
+          # actions/checkout writes an http.extraheader (AUTHORIZATION: basic …)
+          # that silently overrides any credentials embedded in git remote URLs.
+          # We must clear it BEFORE setting the remote URL with WORKFLOW_PAT,
+          # otherwise GITHUB_TOKEN is always used for the push and workflow-file
+          # changes are rejected.
+          # ────────────────────────────────────────────────────────────────────
+          git config --local --unset-all http."https://github.com/".extraheader 2>/dev/null || true
+
+          LAST=$(git log --oneline -1 origin/develop)
+          git checkout main
+          git pull --ff-only origin main
+          git merge --no-ff origin/develop \
+            -m "chore: auto-merge develop → main
+
+          Triggered by: $LAST"
+
+          # ── PUSH STRATEGY ───────────────────────────────────────────────────
+          # Priority 1: WORKFLOW_PAT (classic PAT, repo+workflow scopes)
+          #   → can push workflow file changes; set as a repo secret.
+          # Priority 2: GITHUB_TOKEN fallback
+          #   → cannot push workflow files; strip them from the merge commit.
+          # ────────────────────────────────────────────────────────────────────
+          PUSH_TOKEN="${{ secrets.WORKFLOW_PAT }}"
+          if [ -z "$PUSH_TOKEN" ]; then
+            WF=$(git diff --name-only origin/main -- .github/workflows/ 2>/dev/null || echo "")
+            if [ -n "$WF" ]; then
+              echo "::warning::WORKFLOW_PAT not set — stripping workflow changes from merge commit:"
+              echo "$WF"
+              git checkout origin/main -- .github/workflows/
+              git diff --cached --quiet || git commit --amend --no-edit
+            fi
+            PUSH_TOKEN="${{ github.token }}"
+          fi
+
+          git remote set-url origin "https://x-access-token:${PUSH_TOKEN}@github.com/${{ github.repository }}.git"
+          git push origin main
+
+  # ── Auto-create GitHub Release on main ───────────────────────────────────
+  # Runs after auto-merge succeeds. Reads version from index.html,
+  # creates a release tag vX.Y.Z if it doesn't exist yet.
+  # This powers the in-app update badge for self-hosted users.
+  create-release:
+    name: Create GitHub Release
+    needs: [auto-merge-to-main]
+    if: github.ref == 'refs/heads/develop'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v6
+        with:
+          ref: main
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version from index.html
+        id: version
+        run: |
+          VER=$(grep -oP 'header-version">v\K[\d.]+' index.html | head -1)
+          echo "version=v${VER}" >> $GITHUB_OUTPUT
+          echo "Detected version: v${VER}"
+
+      - name: Check if tag already exists
+        id: tag_check
+        run: |
+          if git ls-remote --tags origin "refs/tags/${{ steps.version.outputs.version }}" | grep -q .; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Read CHANGELOG entry for this version
+        id: changelog
+        if: steps.tag_check.outputs.exists == 'false'
+        run: |
+          VER="${{ steps.version.outputs.version }}"
+          # Extract the section for this version from CHANGELOG.md
+          BODY=$(awk "/^## \[?${VER#v}\]?|^## ${VER}/,/^## [0-9]/" CHANGELOG.md | head -50 | tail -n +1 | grep -v "^## [0-9]" || true)
+          if [ -z "$BODY" ]; then
+            BODY="See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details."
+          fi
+          # Multiline output
+          echo "body<<EOF" >> $GITHUB_OUTPUT
+          echo "$BODY" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create release
+        if: steps.tag_check.outputs.exists == 'false'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.version }}
+          name: "EverShelf ${{ steps.version.outputs.version }}"
+          body: ${{ steps.changelog.outputs.body }}
+          target_commitish: main
+          make_latest: true

.github/workflows/security.yml

@@ -0,0 +1,74 @@
+name: Security Scan (Trivy)
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'Dockerfile'
+      - 'docker-compose.yml'
+      - 'api/**'
+      - '.github/workflows/security.yml'
+  schedule:
+    # Run weekly on Monday at 07:00 UTC
+    - cron: '0 7 * * 1'
+  workflow_dispatch:
+
+jobs:
+  trivy-docker:
+    name: Trivy — Docker image scan
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Build Docker image
+        run: docker build -t evershelf:scan .
+
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          image-ref: 'evershelf:scan'
+          format: 'sarif'
+          output: 'trivy-results.sarif'
+          severity: 'CRITICAL,HIGH'
+          ignore-unfixed: true
+          exit-code: '0'   # don't fail the build, just report
+
+      - name: Upload Trivy SARIF to GitHub Security tab
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: 'trivy-results.sarif'
+          category: 'trivy-docker'
+
+  trivy-fs:
+    name: Trivy — Filesystem scan
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Run Trivy filesystem scanner
+        uses: aquasecurity/trivy-action@v0.36.0
+        with:
+          scan-type: 'fs'
+          scan-ref: '.'
+          format: 'sarif'
+          output: 'trivy-fs-results.sarif'
+          severity: 'CRITICAL,HIGH'
+          ignore-unfixed: true
+          exit-code: '0'
+
+      - name: Upload Trivy FS SARIF
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: 'trivy-fs-results.sarif'
+          category: 'trivy-fs'

.gitignore

@@ -2,6 +2,7 @@
 .env
 
 # Data directory (user-specific runtime data)
+data/evershelf.db
 data/dispensa.db
 data/*.db-wal
 data/*.db-shm
@@ -10,7 +11,11 @@ data/cron.log
 data/smart_shopping_cache.json
 data/bring_token.json
 data/bring_catalog.json
-data/dupliclick_token.json
+data/bring_migrate_ts.json
+data/shopping_price_cache.json
+data/anomaly_dismissed.json
+data/opened_shelf_cache.json
+data/shopping_name_cache.json
 data/client_debug.log
 data/rate_limits/
 
@@ -30,3 +35,20 @@ Thumbs.db
 *~
 .idea/
 .vscode/
+
+# Raw screenshots (working folder, not for distribution)
+/screenshots/
+
+# Android kiosk build artifacts (generated by Gradle — not source)
+evershelf-kiosk/.gradle/
+evershelf-kiosk/app/build/
+evershelf-kiosk/build/
+evershelf-scale-gateway/app/build/
+evershelf-scale-gateway/build/
+evershelf-kiosk/local.properties
+data/error_reports.log
+data/latest_release_cache.json
+data/food_facts_cache.json
+data/category_ai_cache.json
+assets/img/logo/*_backup.*
+logs/*.log

.htaccess

@@ -1,5 +1,19 @@
 RewriteEngine On
 
+# Block sensitive files (Apache 2.4+)
+<Files ".env">
+    Require all denied
+</Files>
+<Files ".env.example">
+    Require all denied
+</Files>
+<Files "backup.sh">
+    Require all denied
+</Files>
+<FilesMatch "^\.">
+    Require all denied
+</FilesMatch>
+
 # Force HTTPS
 RewriteCond %{HTTPS} !=on
 RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
@@ -9,3 +23,10 @@ RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule ^api/(.*)$ api/index.php?action=$1&%{QUERY_STRING} [L,QSA]
 AddType application/x-x509-ca-cert .crt
+
+# Prevent caching of JS/CSS so kiosk always gets fresh files
+<FilesMatch "\.(js|css)$">
+    Header set Cache-Control "no-cache, no-store, must-revalidate"
+    Header set Pragma "no-cache"
+    Header set Expires "0"
+</FilesMatch>

CHANGELOG.md

@@ -1,10 +1,521 @@
 # Changelog
 
-All notable changes to Dispensa Manager will be documented in this file.
+All notable changes to EverShelf will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased] — Ideas & Roadmap
+
+> Ideas collected during development. No priority or date implied.
+
+- **Recipe scraps tips** — During cooking steps, detect "waste" generated (peels, cores, bones, eggshells, coffee grounds, citrus zest, etc.) and surface AI-powered tips on how to reuse them (compost, natural cleaner, broth, candied peel, etc.). Could be shown as an optional collapsible hint card below the step that generates the scrap.
+
+## [1.7.36] - 2026-06-04
+
+### Added
+- **Recipe ingredient stock hints** — Pantry ingredients in generated and archived recipes now show a small line under each item: how much you have in stock and how much would remain after use. Quantities are summed across all storage locations.
+- **Zero-waste use-all rule** — When the leftover would be less than **5% of the full sealed package** (or **10%** when less than one full unit is left on an opened pack), the recipe quantity is automatically bumped to use everything on hand (♻️ badge + note in all 5 languages).
+- **Ghost product detection** — Dashboard anomaly banner now surfaces products that vanished from inventory (ledger says stock should exist but no rows remain), with a restore prompt and quantity input.
+- **`inventory_restore_ghost` API** — Restores a vanished product row from the banner without losing transaction history.
+- **`product_merge` API** — Merges duplicate product records (inventory, transactions, aliases) into a single canonical product.
+- **Maintenance scripts** — `scripts/sync-i18n.py` (5-language key sync), `scripts/re-enrich-recipe.php` (re-apply stock hints to archived recipes), `scripts/merge-duplicate-products.php` (batch duplicate merge).
+
+### Fixed
+- **Unified shopping total** — Dashboard, Spesa page and screensaver now share one canonical server-side total (`shopping_total_cache`); background refresh runs during screensaver too.
+- **Recipe stream auth** — `generate_recipe_stream` and other direct `fetch()` calls now send the API token consistently, fixing 401 errors during recipe generation.
+- **Home Assistant auth compatibility** — HA integration endpoints accept the configured API token without breaking legacy setups.
+- **Security hardening** — API bootstrap modularised; scale SSE relay and sensitive routes require auth; env migration script for legacy installs.
+- **Dashboard banner i18n** — Fixed raw translation keys (`dashboard.banner_*`) showing in the UI; full sync across IT/EN/DE/FR/ES with cache bust.
+- **Ghost banner permanently hidden** — Removed incorrect `fin_*` hide logic that suppressed vanished-product alerts after a false "finished" confirmation.
+- **`deleteInventory` / `use_all` dedup** — Inventory deletions now log transactions; duplicate `use_all` within 60 s is deduplicated; `confirmFinished` reconciles ledger mismatches.
+- **Duplicate product prevention** — `saveProduct` blocks creating a second product with the same normalised name.
+- **Recipe qty normalization** — conf+weight ingredients (e.g. ceci, basilico) now keep recipe amounts in grams/ml instead of copying the inventory conf count; use-all percentage is calculated on the sealed package size, not current stock.
+
+## [1.7.35] - 2026-06-02
+
+### Fixed
+- **Barcode scanner accepts invalid codes** — Manual barcode input with an incorrect EAN checksum now blocks the lookup and shows an error (previously showed a warning but proceeded anyway). The native `BarcodeDetector` path now also validates EAN-8/EAN-13/UPC checksum before confirming a scan, consistent with the Quagga fallback which already did this check.
+- **Recipe persons +/− buttons stopped working in the generation dialog** — A duplicate `adjustRecipePersons` function added for the post-generation rescaler was overriding the one that updated the persons input in the recipe setup dialog. The rescaler is now named `scaleRecipePersons` to avoid the conflict.
+
+## [1.7.34] - 2026-05-30
+
+### Added
+- **AI visual barcode fallback** — When the barcode scanner fails to read a barcode within 5 seconds, EverShelf can now automatically capture a camera frame and send it to Gemini Vision to visually identify the product (name, brand, category). On success the product is saved and the inventory form opens just as if a barcode had been scanned. A new toggle in **Settings → Camera** (`AI visual identification (5s fallback)`) lets users enable or disable this feature at any time. Requires Gemini API key configured. Disabled by default.
+
+## [1.7.33] - 2026-05-29
+
+### Fixed
+- **HA sensor `shopping_total` always null** — `haInventorySensor` was reading `shopping_total_cache.json` with a 1-hour TTL (cache populated only by the JS frontend, so it was often empty). Extended TTL to 24 hours and added an inline fallback: when the cache is absent or stale, the sensor now computes the total directly from `shopping_price_cache.json` without any AI calls. Queries `shopping_list` joined to `products` for the canonical `shopping_name`, then looks up both v3 and legacy v0 cache key formats to maximise hit rate. Works in both internal and Bring shopping modes.
+- **HA `ha_refresh_prices` using non-existent columns** — `haInventorySensor` and `haRefreshPrices` were querying `quantity`, `unit`, `checked` from `shopping_list` — columns that do not exist in that table (schema: `id, name, raw_name, specification, added_at, sort_order`). Changed to `SELECT name` with `shopping_name` join and default `qty=1 / unit=pz`.
+
+
+## [1.7.32] - 2026-05-29
+
+### Changed
+- **Smarter expiry u2192 shopping list logic** — The "expiring soon" threshold is now 7 days (was 3), giving enough time to plan the next shopping trip. Items expiring soon are only flagged for restocking when the user is a **regular buyer** (`isRegular`) and either stock is low (<50%) or the consumption rate predicts the item will expire before being used. Non-regular products keep the old 3-day safety-net. Expired items are now only added to the shopping list when `isRegular || buyCount >= 2` — products that expired unused without ever being a staple no longer pollute the list; the expiry banner handles them.
+
+
+## [1.7.31] - 2026-05-29
+
+### Fixed
+- **New pack merges into opened pack on add** — `addToInventory` was looking for ANY existing row for the same product+location and adding the new quantity to it. This caused a newly purchased sealed pack to be silently merged with an already-opened pack, collapsing two physically distinct containers into one row and corrupting the `opened_at` timestamp. The fix now searches only for a **sealed** (unopened) row (`opened_at IS NULL`) to merge into. If only opened rows exist, a new sealed row is created instead — keeping the two packs separate and allowing the anomaly model and shelf-life tracker to work correctly.
+
+
+## [1.7.30] - 2026-05-29
+
+### Fixed
+- **False consumption anomaly with multi-row stock** — The anomaly detection banner was evaluating each inventory row in isolation. Products split across multiple rows (e.g. one opened pack with 1 pz + one sealed pack with 6 pz) incorrectly triggered a "consumed faster than expected" warning because only the opened row (1 pz) was compared against the model. The check now aggregates the total quantity across all rows for the same product before deciding to flag an anomaly. If the combined total ≥ expected remaining, the anomaly is suppressed.
+
+
+## [1.7.29] - 2026-05-29
+
+### Added
+- **Buy-cycle consumption prediction** — Products that are never tracked per-use (salt, spices, cleaning supplies, etc.) now use the average time between restocks as a proxy for consumption rate. When a product has ≥ 3 purchase events and no individual `out` events, EverShelf calculates the average buy cycle (`(lastBuy - firstBuy) / (buyCount - 1)`) and estimates how many days of stock remain in the current cycle. The product appears in the smart shopping list with a reason like "Finisce tra ~12gg (ciclo medio 75gg)" before it runs out, rather than only after. These products are now also treated as `isRegular` so all stock-level urgency checks apply correctly.
+
+
+## [1.7.28] - 2026-05-30
+
+### Fixed
+- **Duplicate auto-reported issues** — The GitHub issue reporter was relying solely on the GitHub Search API for deduplication. Because search indexing has a several-minutes lag, rapid error recurrences each created a new issue before the previous one was indexed, producing ~50 duplicate issues. The reporter now uses a local file cache (`data/reported_issue_fps.json`, with `/tmp/` fallback when `data/` is not writable) as the primary deduplication store. A 30-minute per-fingerprint comment throttle is also applied to prevent flooding an existing issue. GitHub Search is used only on first run or after a cache miss. Closes [#134](https://github.com/dadaloop82/EverShelf/issues/134) (and all duplicates #135–#183).
+
+## [1.7.27] - 2026-05-29
+
+### Added
+- **HA sensor enrichment** — All HA sensor attributes that list products now include full product details: `location`, `brand`, `category`, `days_remaining`, `opened_at`, `vacuum_sealed`, `default_quantity`, `package_unit`, `product_id`, `inventory_id`. Applies to `expiring_list`, the new `expired_list`, and the new `low_stock_list`.
+- **HA `expired_list` attribute** — `sensor.evershelf_overview` now exposes `expired_list` (full details for all expired items, not just a count).
+- **HA `low_stock_list` attribute** — New attribute listing all items with quantity ≤ 1 with full product info.
+- **HA `sensor=product` endpoint** — New `GET /api/?action=ha_sensor&sensor=product` returns the full inventory with all product details. Optional filters: `&id=N`, `&name=...`, `&location=...`.
+- **Inventory edit safety guard** — Confirm dialog when saving a quantity that is unusually large for its unit (e.g. 183 conf), preventing accidental data loss from unit-confusion typos.
+- **Bread shelf-life in fridge** — Opened shelf-life rules added for piadina/crescia (2 days), packaged sliced bread/bauletto (4 days), and generic bread (3 days).
+
+### Fixed
+- **Recipe AI ingredient substitution** — Added explicit rule to both recipe prompts preventing Gemini from substituting ingredient forms (e.g. fresh tomatoes ↔ passata, fresh milk ↔ UHT ↔ cream, flour 00 ↔ wholemeal).
+- **HA cron webhook payload** — Expiry alert webhook items now include full product details (brand, category, location, days_remaining, opened_at, vacuum_sealed) instead of only name/qty/unit/expiry_date.
+
+### Docs
+- `docs/wiki/Home-Assistant.md` — Documented new `sensor=product` endpoint, full product schema table, enriched webhook payload example, and Lovelace/automation template examples using `location` and `days_remaining`.
+
+## [1.7.26] - 2026-05-26
+
+### Added
+- **Monthly stats panel** — Third rotating card in the insight banner (anti-waste → nutrition → monthly stats, 1 minute each). Shows products consumed this month with a trend vs. the previous calendar month (↑/↓/→ with % delta), animated horizontal category bars, and badges for items added, wasted, and top-used product. Falls back gracefully when the current month has no transactions. Closes [#100](https://github.com/dadaloop82/EverShelf/issues/100).
+- **Extended smart-shopping horizon for staples** — Items consumed ≥ 4 times/month now get a 28-day look-ahead window; ≥ 2 times/month get 21 days. Frequently used staples no longer disappear from the smart list between restocks. Closes [#98](https://github.com/dadaloop82/EverShelf/issues/98).
+
+### Fixed
+- **TTS test interactive confirmation** — Test timeout raised from 4 s to 10 s; instead of an error, the UI shows a YES/NO prompt ("Did you hear it?") so users can confirm or report failure explicitly.
+- **`end()` PHP 8 reference error** — `_offFetchProduct()` passed the result of `??` directly to `end()`, which requires a variable. Fixed with a temporary variable.
+- **Database migration crash on fresh installs** — `migrateDB()` tried to rename the `transactions` table before it existed. A `sqlite_master` guard now calls `initializeDB()` and returns early when the schema is absent. Closes [#131](https://github.com/dadaloop82/EverShelf/issues/131), [#133](https://github.com/dadaloop82/EverShelf/issues/133).
+- **Health-check crash on empty database** — `db_row_count` query was executed even when the `inventory` table was missing, causing a fatal PDO error. The query is now skipped until the schema is fully initialised. Closes [#132](https://github.com/dadaloop82/EverShelf/issues/132).
+- **Insight banner stuck on one panel** — Rotation interval was 1 hour (effectively invisible); now 60 seconds. `_applyInsightPhase` also now skips empty panels instead of always falling back to the anti-waste card, so the rotation works correctly even when a panel has no data.
+- **Untranslated OpenFoodFacts category labels** — Categories stored as OFF slugs (`en:plant-based-foods-and-beverages`, `en:dairies`, …) were shown raw. A new `_normalizeCat()` PHP function maps ~60 OFF slugs to Italian app categories; counts are re-aggregated after normalisation so `en:dairies` + `en:milk` both contribute to `latticini`.
+
+## [1.7.25] - 2026-05-25
+
+### Added
+- **Home Assistant integration** — Full bidirectional HA support: inventory sensor (`sensor.evershelf_*`) exposes item counts, expiring items, shopping total, opened items and next-expiry info. Webhooks fire on inventory changes (add/use/shopping). Daily cron alert notifies via HA for items expiring within the configured threshold. TTS announces cooking steps through HA Media Player. New Settings tab 🏠 with connection test, TTS preset (Piper, Google, Nabu Casa), webhook config, and YAML snippet for `configuration.yaml`. Resolves [#111](https://github.com/dadaloop82/EverShelf/issues/111).
+- **Offline mode** — Full offline-first support. Full-screen overlay on network loss; "Continue offline" button after 3 s, auto-enter after 8 s. Inventory and settings are synced to `localStorage` at startup and cached on every successful API call. Writes (add/use/update/delete) are queued and synced on reconnect with optimistic UI updates. Pending operations survive page refresh and are re-synced automatically at next startup. AI/network-dependent sections (anti-waste chart, nutrition analysis, recipe generator, price fetching, Gemini chat) are hidden in offline mode. `remoteLog` and `reportError` are buffered offline and flushed on restore. Broken external images replaced with a grey placeholder.
+- **Offline-computed dashboard** — While offline, `inventory_summary` and `stats` (expiring/expired/opened) are derived client-side from the local cache so all dashboard stat cards and expiry alerts show accurate data.
+
+### Fixed
+- **Offline banner flood** — Opened items in the offline `stats` response lacked `is_edible`; `!undefined` evaluated to `true`, causing every opened item to be shown as "not edible" in the dashboard banner. Field is now set to `true` (client-side shelf-life check already handles genuinely expired items).
+- **Version update badge showing older versions** — `_checkWebappUpdate` used `latestTag !== _loadedVersion` (inequality only), so running a newer dev build triggered an "update available" badge for an older GitHub release. Now uses `_semverGt(latest, current)` so only genuinely newer releases trigger the badge.
+- **Bring! items re-appearing after manual purchase removal** — `removeBringItem` and `confirmShoppingItemFound` now call `_markBringPurchased` immediately, and `autoAddCriticalItems` respects the blocklist for depleted items.
+- **Barcode lookup false "not found"** — New `_offFetchProduct()` tries three barcode candidates (given, UPC-A↔EAN-13 conversion) across two Open Food Facts locales with auto-retry.
+- **Partial throw from expired-items banner** — "Butta" now opens the throw modal (qty + location) instead of silently deleting the entire inventory row.
+- **Related stock display when scanning branded products** — When scanning a product, the action page now shows a green card listing any inventory items from the same generic family already at home.
+
+## [1.7.24] - 2026-05-21
+
+### Fixed
+- **Dark mode resets to Auto on every reload** — `dark_mode` was never saved to `.env` (missing from `saveSettings` and `getServerSettings`). It is now fully server-side like all other settings; `localStorage` retains only a pre-render hint for the flash-prevention IIFE.
+- **Cooking timer — no sound or speech on Android kiosk** — Three independent root causes fixed: (1) `AudioContext` was created fresh outside a user gesture, starting in `suspended` state and failing silently; a shared pre-unlocked context (`_sharedAudioCtx`) is now created during user gestures (`startCookingMode`, `addCookingTimer`). (2) The `_cookingTTS` gate (for step narration) was incorrectly blocking timer alarm speech — timer alerts now always speak regardless of that flag. (3) `_kioskBridge.speak()` (native Android TTS) was never considered as a fallback when `window.speechSynthesis` is absent in the WebView.
+- **Scale use ignored for conf products** — `_scaleAutoFillUse()` returned early when `_activeUnit !== 'sub'`, but conf products default to `conf` mode. The function now auto-switches to sub mode before processing the weight reading. Scale button (`btnUse`) is also now visible for conf products that have a g/ml package unit.
+- **Kiosk — native settings button reappearing unexpectedly** — `closeModal()` was calling `setNativeSettingsVisible(true)`, restoring the native Android settings button after every modal close. `_injectKioskOverlay()` now permanently hides the native button; scattered per-modal show/hide calls removed; a ⚙️ web button opens the in-app settings page.
+- **SQLite database locked during inventory update** — `updateInventory()` made 3–4 separate write statements without a transaction; a concurrent cron job could acquire the write lock between them, causing a `database is locked` PDO error. All writes are now wrapped in `beginTransaction()`/`commit()`, with the Bring! HTTP sync deferred to after `commit()`. Closes [#109](https://github.com/dadaloop82/EverShelf/issues/109), [#110](https://github.com/dadaloop82/EverShelf/issues/110).
+- **Depleted-item urgency incorrect** — Items with zero quantity were assigned urgency based on recency of use rather than consumption frequency. Urgency is now computed from `usesPerMonth` only, so frequently-used depleted items are correctly flagged as urgent.
+- **0.5 conf use and decimal display** — Default mode on the use-quantity page is now conf for conf products; fraction buttons (½, ¼, ¾) work correctly; conf decimals are shown in the transaction history log.
+- **Bring! health check token warning** — Token validity warning was shown even for valid tokens; health check is now restored with correct token-format detection.
+- **Recipe quantities for conf+weight products** — Quantities are now calculated correctly when a conf product has a gram-based package unit.
+- **Shopping settings not syncing across clients** — `shopping_*` keys were missing from `serverKeys` in `_applySyncedSettings`; shopping settings were client-local. All shopping keys now sync from server on load.
+
+### Added
+- **Native shopping list** — Built-in shopping list (no Bring! required) as an alternative mode (`SHOPPING_MODE=internal`). Resolves [#105](https://github.com/dadaloop82/EverShelf/issues/105).
+- **Google Drive backup via localhost OAuth** — GDrive backup no longer requires a public domain; the OAuth redirect flow uses `http://localhost` via a temporary local server, compatible with self-hosted setups. Resolves [#107](https://github.com/dadaloop82/EverShelf/issues/107).
+
+### Changed
+- **All settings fully server-centralised** — Removed remaining `localStorage` usage for user preferences; all settings are now read from and written to `.env` via the API. Preferences are shared across all devices (desktop, phone, kiosk) automatically.
+
+## [1.7.23] - 2026-05-18
+
+### Added
+- **⚙️ Generali tab** — new first tab in Settings groups all global settings: language, currency, theme, screensaver, zero-waste tips, inventory export. Old Language tab removed.
+- **DB auto-cleanup** — `RECIPE_RETENTION_DAYS` (default 7) and `TRANSACTION_RETENTION_DAYS` (default 7) added to `.env`; old rows are deleted automatically every cron cycle, followed by `VACUUM` to compact the database. Manual trigger: `GET /api/?action=db_cleanup`.
+- **Vacuum-sealed expiry grace period** — `VACUUM_EXPIRY_EXTENSION_DAYS` (default 30): vacuum-sealed products are only flagged as expired N days *after* the printed date, preventing false alarms on long-lasting items like cured meats.
+- **Gemini AI usage tracking** — monthly and yearly token/cost stats now shown in Settings → ℹ️ Info tab, using tracked data from `data/ai_usage.json`. Cost rates configurable via `GEMINI_COST_25F_IN/OUT` and `GEMINI_COST_20F_IN/OUT` in `.env`.
+
+### Changed
+- **Auto theme is now time-based** — "Automatico" mode switches to dark at 20:00 and back to light at 07:00, based on server/device clock (not OS preference). Re-evaluates every 5 minutes; ideal for always-on kiosk displays.
+- **`dispensa.db` auto-deleted** — if the legacy empty `dispensa.db` file appears alongside `evershelf.db`, it is now removed automatically by the health check.
+- **ZeroWaste tips and screensaver timeout** — these settings were not being persisted to `.env` on save (missing from POST payload); fixed.
+
+## [1.7.22] - 2026-05-17
+
+### Fixed
+- **DB name corrected** — `health_check` now looks for `evershelf.db` (was wrongly looking for `dispensa.db`). Auto-migration included: if `evershelf.db` is missing but `dispensa.db` exists, it is renamed automatically on startup.
+- **Removed legacy `data/dispensa.db`** — the old database file has been deleted; only `evershelf.db` is used.
+- **Conditional checks** — Bring!, TTS, Scale and Internet checks only run when the respective feature is enabled in `.env` (no more false ❌/⚠️ for unconfigured features).
+- **Backups check** — no longer checks if `data/backups/` is writable by www-data (cron writes as root). Now checks that backup files actually exist and the most recent one is recent.
+- **Bring! token check** — reads `data/bring_token.json` file instead of looking for a non-existent `BRING_ACCESS_TOKEN` env var.
+
+### Changed
+- **Warning popup with 5s countdown** — when non-critical checks fail at startup, a styled popup appears showing each warning with its label and a plain-language hint explaining the problem. A countdown bar auto-closes the popup after 5 seconds, then the app starts normally.
+- **Error blocking popup** — when critical checks fail, a clear blocking panel shows with title "Errore critico", each failed check listed with its explanation hint, and a Retry button. The app does not start.
+- **`db_legacy` check added** — warns (optional) if the old `dispensa.db` file is still present alongside `evershelf.db`.
+- **32 total checks** — added `db_legacy`, `tts_url`, `scale_gateway` to the check set (conditional).
+- **Hint messages** — every check now has an Italian-language `hint` field explaining what is wrong and how to fix it.
+
+## [1.7.21] - 2026-05-20
+
+### Changed
+- **Startup health check** — Complete redesign from a banner checklist to a **real-time progress bar**. The bar fills smoothly as each of 29 diagnostic checks runs, with the current check name shown below in real time. Warnings (⚠️) are displayed as amber badges that remain visible for 2 seconds before the app proceeds. Critical failures turn the bar red and show a detailed error block with a Retry button.
+- **29 comprehensive checks**: PHP version, 8 PHP extensions (pdo_sqlite, curl, json, mbstring, openssl, fileinfo, zip, intl), PHP memory/timeout/upload config, data directory, rate_limits dir, backups dir, disk write test, free disk space, SQLite connection, required tables, integrity (PRAGMA quick_check), WAL mode, DB size, inventory row count, .env file, Gemini AI key, Bring! credentials, Bring! token, cURL SSL, internet reachability.
+- Warnings now clearly visible: each non-critical failure shows as a named amber badge (e.g. "⚠️ Bring! token") that cannot be missed.
+
+## [1.7.20] - 2026-05-20
+
+### Added
+- **Startup health check** — During the splash screen, the app now runs a comprehensive server-side diagnostic before loading: PHP version, required extensions (pdo_sqlite, curl, mbstring, json), `data/` directory writability, SQLite database connection and table integrity, `.env` file presence, Gemini AI key and Bring! token. Results are displayed as an animated checklist (✅ / ⚠️ / ❌). Critical failures (DB, extensions, data dir) block the app with a clear error message and a "Retry" button — the app never starts silently broken. Non-critical warnings (missing Gemini key, Bring! token) are shown as amber items but do not block startup.
+- New `?action=health_check` PHP endpoint (early-exit, no rate-limit, no auth).
+- New translation keys `startup.*` in all 5 languages (IT, EN, DE, FR, ES).
+
+## [1.7.19] - 2026-05-19
+
+### Added
+- **Zero-waste tips during cooking** — When cooking mode is active, a ♻️ card appears below each step that generates reusable scraps (peels, cooking water, egg whites, cheese rinds, bread crusts, vegetable tops, etc.). Gemini generates the tips as part of the recipe JSON at no extra API cost. Tips are dismissible per-step and reset on recipe restart. Opt-in toggle in Settings → Zero-waste tips (default OFF). Resolves [#76](https://github.com/dadaloop82/EverShelf/issues/76).
+- New translation keys `cooking.zerowaste_*` and `settings.zerowaste.*` in all 5 languages (IT, EN, DE, FR, ES).
+
+## [1.7.18] - 2026-05-19
+
+### Added
+- **Dark mode** — New theme selector in Settings (Appearance card): **Off (Light)**, **On (Dark)**, **Auto (follows system)**. Applied immediately on page load to prevent white flash. Resolves [#78](https://github.com/dadaloop82/EverShelf/issues/78).
+- **Export inventory** — New 📤 button in inventory page header opens a modal to download the inventory as **CSV** (UTF-8 with BOM, Excel-compatible) or open a **print-ready HTML page** (auto-triggers print dialog for PDF). Export card also available in Settings tab. Resolves [#64](https://github.com/dadaloop82/EverShelf/issues/64).
+- `translations/de.json`: fixed missing `log.recipe_prefix` key.
+
+## [1.7.17] - 2026-05-19
+
+### Added
+- **French translation (🇫🇷 Français)** — Complete `translations/fr.json` with all 1049 translation keys. Resolves [#77](https://github.com/dadaloop82/EverShelf/issues/77).
+- **Spanish translation (🇪🇸 Español)** — Complete `translations/es.json` with all 1049 translation keys. Resolves [#77](https://github.com/dadaloop82/EverShelf/issues/77).
+- Language selector in Settings now shows all 5 languages: 🇮🇹 Italiano, 🇬🇧 English, 🇩🇪 Deutsch, 🇫🇷 Français, 🇪🇸 Español.
+- Default fallback language changed from Italian to English (for users with unsupported browser locale).
+- Setup wizard "Done" screen and navigation buttons localised for French and Spanish.
+
+## [1.7.16] - 2026-05-17
+
+### Added
+- **Barcode scan history** — Last 20 scanned products are stored server-side (SQLite `app_settings`) and shown as chips in the scan page (`#scan-recents-chips`). Tapping a chip selects the product directly — no need to scan again. Resolves [#68](https://github.com/dadaloop82/EverShelf/issues/68).
+- **Full server-side user-data centralisation** — All user preferences previously siloed in `localStorage` per-device are now synced to the server via `app_settings_save` and loaded back at startup via `app_settings_get`. Affected data: shopping tags, pinned Bring! items, location preferences (use/move), auto-added Bring! entries, Bring! purchased blocklist, no-expiry dismissed products. Data is now shared across all devices (desktop, phone, kiosk, Android app).
+- **One-time localStorage migration** — On first load, any data found in the old localStorage keys (`shopping_tags`, `_userPinnedBring`, `_prefUseLoc`, `_prefMoveLoc`, `_autoAddedBring`, `_bringPurchasedBlocklist`, `_noExpiryDismissed`, `evershelf_scan_recents`) is automatically migrated to the server and the local keys are removed.
+
+## [1.7.15] - 2026-05-16
+
+### Added
+- **Full i18n audit** — Comprehensive sweep of all user-visible strings in `app.js` and `index.html`. 25+ new translation keys added across `it.json`, `en.json`, `de.json`, covering: vacuum toast, TTS voice controls, timer step labels, product note labels, error messages, expiry form, barcode hint, category select placeholder, cooking step fallback, `form.select_placeholder`, `btn.yes_short`/`no_short`, `add.vacuum_question`, `add.vacuum_saved`, `move.vacuum_seal_rest`, `cooking.step_fallback`, `error.prefix`/`unknown`, `product.select_variant`, and more.
+- **Splash screen redesign** — Logo displayed prominently, spinner below, app version shown at the bottom; version label injected dynamically at boot time so it never gets out of sync. Minimum 3-second display duration enforced: `_splashStart` is recorded before `DOMContentLoaded`; the fade-out is delayed by the remaining time if the app loads faster than 3 s.
+- **Demo GIF in README** — `assets/img/demo.gif` (processed at 2× speed, ~36 s) added to the `## 📸 Screenshots` section.
+- **`pz`/`conf` unit labels translated** — "pz" now shows as "pcs" in English and "Stk" in German; "conf" shows as "pkg" / "Pkg". All `unitLabels` objects in JS now use `t('units.pz')` / `t('units.conf')`.
+
+### Fixed
+- **Camera button (📷) opened kiosk SettingsActivity on Android** — The native `btnSettings` ImageButton in the kiosk layout was positioned `top|end` with `alpha=0.12` (nearly invisible), sitting directly on top of the HTML scan button in the webapp header. Every tap on the 📷 button was intercepted by the native View and opened `SettingsActivity`. Fixed: moved `btnSettings` to `bottom|end` (above the bottom nav bar, `marginBottom=80dp`) and increased `alpha` to `0.28` so it is clearly separate from the header. Kiosk versionCode bumped to 16.
+- **Camera button (📷) opened settings on Android Chrome/Brave** — `pointerleave` fired before `pointerup` when finger drifted slightly, cancelling the long-press timer and leaving the browser to dispatch a synthetic `click` that bubbled to an unintended handler. Fixed: added `setPointerCapture` (prevents `pointerleave` during touch) and `preventDefault` (blocks synthetic click); replaced `pointerleave` with `pointercancel` handler. Added `touch-action: manipulation` to `.header-scan-btn` CSS.
+- **Logo white background on splash screen** — Re-processed both `logo.png` and `logo_icon.png` with fuzz 35% alpha extraction, removing the white background that was visible against the dark splash background (`#0f172a`).
+- **Recipe button label** — Shortened to "Ricetta" / "Recipe" / "Rezept" for compact display in the inventory quick-action modal.
+- **Quantity decimal precision** — `qtyNum` in recipe/cooking ingredient buttons and `conf` fallback display in inventory cards now limited to 1 decimal place (was showing 7+ decimal places from raw AI output, e.g. `0.25353223 conf`).
+- **"Errore" / "Error" fallback strings** — All remaining Italian hardcoded `'Errore'` fallbacks in `showToast()` calls replaced with `t('error.generic')`. Italian fallback strings removed from buttons that already used `t()`.
+- **README Italian phrases** — "La quantità è giusta (2 pz)", "🤖 Spiega", "Latte / Affettato / Panna da cucina", "Buon appetito!", "L'ho buttato" replaced with English equivalents in the README.
+- **Appliance chips translated** — `renderAppliances()` now shows translated names (e.g. "Air fryer" in EN, "Heißluftfritteuse" in DE) for all known canonical Italian appliance names via `_applianceDisplayName()` lookup. `addApplianceQuick` toast no longer hardcoded Italian. Remove-button title translated.
+- **Gemini API key not preserved on settings save** — `saveSettings()` was overwriting `s.gemini_key = ""` when the Gemini input field was empty (it is intentionally not pre-populated for security). Key is now preserved if the input is blank. `_geminiAvailable` is re-fetched from the server after every settings save so the recipe buttons reflect the real state immediately.
+
+## [1.7.14] - 2026-05-16
+
+### Added
+- **In-app bug report form** — "Segnala un problema" now opens a modal form instead of redirecting to GitHub. Users can select type (Bug / Feature / Question), write title and description, optionally add reproduction steps. A GitHub issue is created directly with labels and app metadata attached.
+
+### Fixed
+- **Kiosk settings button** — "Apri configurazione kiosk" in webapp settings was showing a toast asking to tap a gear icon that no longer exists. Now calls `openNativeSettings()` bridge directly (opens Android SettingsActivity). Fallback for old APKs shows a proper "update the kiosk app" hint.
+- **False update badge** — `manifest.json` version was `1.7.12` while the app header showed `v1.7.13`, causing the server to report an older deployed version and triggering a spurious update notification.
+- **Kiosk settings gear disappeared** — Race condition where Kotlin's `onPageFinished` injects `#_kiosk_overlay` before JS runs; JS found the element already present and returned early without ever restoring the native gear button. Fixed: JS no longer hides the native gear on load; `closeModal()` restores it with `setNativeSettingsVisible(true)`.
+- **`openNativeSettings()` fragile typeof check** — Android `@JavascriptInterface` methods are not always detected as `'function'` by typeof; replaced with try/catch.
+
+## [1.7.13] - 2026-05-16
+
+### Fixed
+- **Fresh-install crash: `no such column: undone`** — The `transactions` table was created in `initializeDB()` without the `undone` column, but the composite index `idx_transactions_pid_type_undone` immediately referenced it, crashing every new installation at first DB access.  Added `undone INTEGER DEFAULT 0` to the transactions schema in `initializeDB()`.
+- **Race condition: `duplicate column name: package_unit`** — Concurrent API requests on a new installation could all pass the `PRAGMA table_info` guard simultaneously and each try to `ALTER TABLE products ADD COLUMN package_unit`, with all but the first failing with a PDOException.  Wrapped all `ALTER TABLE … ADD COLUMN` calls in try/catch to silently ignore duplicate-column errors.
+
+## [1.7.12] - 2026-05-13
+
+### Fixed
+- **"Use first" banner showed a calculated expiry date** — `_renderUseExpiryHint` was displaying a *calculated* shelf-life date (from opening date) instead of the actual one. When `opened_at` is set, the banner now shows "That one [in the fridge], opened X days ago — use it first!" using the new `use.expiry_warning_opened` translation key.
+- **"Use All / Done" in recipes deleted the inventory row** — `submitRecipeUse(true)` was sending `use_all: true` to the API, which executed a direct `DELETE` on the inventory row without any confirmation. The function now calculates the exact quantity from the available items (`_recipeUseContext.items`) and sends a regular `inventory_use` with an explicit quantity.
+- **Recipes: `qty_number` returned in grams for piece-counted (`pz`) items** — The AI prompt and PHP post-processing now instruct Gemini to express `qty_number` as whole pieces for ingredients with unit `pz` (sliced bread, crackers, etc.). The ingredient list in the prompt includes `[use whole PIECES]` for each `pz` product. The PHP fallback for `pz` items without `default_quantity` no longer divides by 100, but uses the AI-returned `qty_number` if it is a plausible count, otherwise defaults to 1.
+
+### Added
+- **Translation key `use.expiry_warning_opened`** — New key in `it.json`, `en.json`, `de.json` with `{loc}` (location) and `{when}` (days since opening) placeholders.
+
+## [1.7.11] - 2026-05-12
+
+### Added
+- **Scan page redesign** — The scanner page has been completely redesigned for tablet and mobile:
+  - **2× fixed zoom** — hardware zoom if available, otherwise automatic CSS `scale(2)`.
+  - **Torch** — in-viewport button with toast feedback and visual state indicator.
+  - **Camera flip** — front/back switch with persistence in settings.
+  - **3 input tabs** — Barcode / Name / AI for quick access to each scanning mode.
+  - **Recent products** — chips for the last 6 scanned products (localStorage), with category icon.
+  - **Live code overlay** — partially detected barcode shown as overlay in the viewport during partial scan.
+  - **Confirm overlay** — checkmark + product name displayed for 900 ms on successful recognition.
+  - **Guide corners** — visual alignment frame for barcode centering.
+  - **AI Number OCR** — after 4 s without a scan, a "Read numbers with AI" button appears; Gemini analyses the video frame and returns barcode digits even when the optical scanner fails.
+- **PHP `gemini_number_ocr` endpoint** — New POST endpoint; accepts a base64 JPEG image, asks Gemini to locate the EAN-13 / EAN-8 code printed on the product, and returns the digits or `not_found`.
+
+### Fixed
+- **False consumption anomaly positives (e.g. "Mozzarella 3 pcs")** — Removed the `untracked` direction (consumption higher than recorded purchases), which was generating banners for every product with untracked purchase history. Only `phantom` and `missing` anomalies are now reported.
+- **"~0 g/week" consumption prediction** — The model now requires a minimum of 5 transactions (was 3) and a time span of at least 7 days; predictions where consumption is < 15% of the baseline are skipped, eliminating false positives for products with few closely-spaced transactions.
+- **Suggestion dropdown on the Name field (scan page)** — Removed `list="common-products"` from the input field; the datalist is no longer triggered on tablets.
+
+## [1.7.10] - 2026-05-11
+
+### Fixed
+- **"Set expiry" banner did nothing** — `editBannerNoExpiry()` was calling `openEditInventoryModal()` which does not exist. Fixed to call `editInventoryItem()` (the correct function used by all other banner handlers). Added a prefetch of `inventory_list` because `currentInventory` is empty on the dashboard.
+- **"Product not found" when opening modal from a banner** — `currentInventory` is always empty on the dashboard; the inventory fetch now happens before opening the modal (same pattern as `editReviewItem` and `weighBannerItem`).
+- **Expired banner on opened UHT milk** — The banner was showing "Expired!" instead of "Opened too long". Items with `opened_at` now display "Opened X days ago in [location]" in both the title and the banner detail.
+- **Generic milk shelf life 4 → 7 days** — Milk without qualifiers (e.g. "Milk") was treated as fresh (4 days). Fresh milk is still handled explicitly (`latte fresco/intero/parzial/scremato` → 3 days); the generic case now defaults to 7 days (UHT default). Fix applied in both PHP (`database.php`) and JS (`app.js`).
+- **Stale `opened_at` on sealed packages after split** — When a use operation splits a row into "whole sealed packages + opened fraction", the sealed-packages row was not clearing `opened_at`. All 3 split code paths now execute `opened_at = NULL` on the sealed row.
+- **`inventory_update` was not recording transactions** — The quantity-edit modal updated inventory without creating transaction records. The quantity difference is now automatically recorded as `in` or `out` with a `[Manual correction]` note, preventing false positives in the anomaly detector.
+- **False consumption anomalies after restocking** — The prediction baseline was using only the restock quantity (`restockQty`), ignoring pre-existing stock, causing `actual > expected` systematically. New baseline: `current_qty + consumed_since_last_restock`, which correctly reflects the real situation regardless of prior stock levels.
+- **Anomaly banner firing on almost all products** — Two fixes:
+  1. `expected = 0` no longer generates a "more" anomaly (the model assumed you should have run out, but you restocked).
+  2. "More than expected" threshold raised to 400% (was 30%); "less than expected" threshold remains at 30%.
+- **Expired section showing already-discarded products** — The `expired` query was missing `AND i.quantity > 0`; discarded products (qty=0) with a past expiry kept appearing. Query fixed and orphan rows cleaned from the DB.
+- **Hardcoded Italian string `scade il` in banner** — Replaced with the correct i18n key.
+- **Docker: `SQLSTATE[HY000][14] unable to open database file`** — `_ensureDataDir()` in `database.php` now creates the `data/` directory if missing and attempts `chmod(0775)` if not writable, resolving the error on freshly mounted Docker volumes.
+
+### Added
+- **Complete i18n** — Added ~25 missing translation keys for kiosk UI, Gemini responses, banners, scanner, shopping, and appliances across all 3 language files (`it.json`, `en.json`, `de.json`). Total: 934 keys per language.
+
+## [1.7.8] - 2026-05-10
+
+### Added
+- **Transfer to Recipes from chat** — When the Gemini Chef chat generates a recipe, a "📥 Transfer to Recipes" button appears. Pressing it triggers Gemini to convert the chat text into a complete structured JSON (title, meal, ingredients, steps); the backend enriches each ingredient with `product_id` and `location` via fuzzy-match (identical to `generateRecipe`); the recipe is saved and opens directly in the Recipes section with all "Use" buttons and full cooking mode.
+- **"Open recipe" button** — After a successful transfer, the "📥 Transfer to Recipes" button transforms into "📖 Open recipe" (same DOM element), preventing overlap.
+- **Create a recipe from an ingredient** — In the action panel of every inventory item, a "👨‍🍳 Create a recipe with this" button appears (teal, full width). Pressing it, Gemini generates a recipe using that ingredient as the star (same pipeline as `chatToRecipe`: inventory fuzzy-match enrichment, `meal=null`, 8192 token max).
+- **Meal not auto-categorized** — Recipes generated from chat or from an ingredient are no longer auto-categorized (`meal` remains null); the meal tag in the UI is only shown when explicitly set.
+
+### Fixed
+- **Smart shopping: false "running low" alert** — If a product in grams/ml was nearly exhausted (e.g. Butter 30 g = 12%) but the same product was also available as a sealed package (Butter 1 pack = 99%), the system still flagged "running low". Now checks whether the `shopping_name` family has stock from other products; if so, the alert is suppressed.
+- **Corrupted translation JSON** — The `action` section was duplicated in `de.json`, `en.json`, and `it.json`, causing JSON parse errors that blocked CI/CD. The spurious duplicate section has been removed.
+
+## [1.7.7] - 2026-05-10
+
+### Fixed
+- **Smart shopping family suppression** — The `recentlyExhausted` logic (products finished < 14 days ago) was incorrectly bypassing the `shopping_name` family suppression, causing false positives: products like Vanilla Yogurt appeared urgent even with 2 kg of Yogurt in stock. `recentlyExhausted` now only bypasses the token-based loose match; family suppression by `shopping_name` always applies.
+- **Shelf-life pre-warming in cron** — The cron now calls `prewarmShelfLifeCache()` every 5 minutes, pre-loading via Gemini AI the shelf life of opened inventory items (max 5 items per cycle) before the user views them. This eliminates the noticeable delay on first click of "Opened on…".
+
+## [1.7.6] - 2026-05-10
+
+### Fixed
+- **`shopping_name` truncated (Piadina)** — The product "Piadine medie" had `shopping_name='Pi'` (truncated), preventing it from grouping correctly in its family. Fixed to `Piadina`.
+- **Family merges in DB** — Grana Padano now under `Formaggio` (was a `Grana` singleton), Prosciutto cotto now under `Affettato`, Panna acida now under `Panna`.
+- **`daily_rate` over the actual active period** — The daily consumption rate was using `first_in → now` as the window, diluting the rate with periods when the product was already exhausted (e.g. garlic exhausted at day 34 was calculated over 60+ days). Now uses `first_in → last_activity` (last purchase or last use), giving more accurate reorder predictions.
+- **Stable anomaly dismiss key** — The dismiss key was using `product_id + round(expected)`, which changed with every new transaction, causing already-dismissed anomalies to reappear. Now uses `product_id + direction` (phantom/missing/untracked) — stable as long as the direction does not change.
+- **Smart shopping: products exhausted < 14 days ago** — Products finished within the last 14 days are no longer suppressed by the token-coverage check or the shopping_name family check: if you just ran out, you probably want to restock regardless of equivalent stock on hand.
+- **Chat pruning** — `chatSave()` now deletes messages beyond the 200 most recent after each save, preventing unbounded growth of the `chat_messages` table.
+
+
+## [1.7.5] - 2026-05-10
+
+### Added
+- **Vacuum sealed prompt on item use** — After using a conf/weighted-unit item that still has remaining stock, a sliding popup asks "🔒 Messo sotto vuoto?" with Sì/No buttons and an 8-second auto-dismiss countdown bar. Default is Sì if the item was previously sealed, No otherwise. Works for all container units (conf, g, kg, ml, l) and any item previously marked as vacuum sealed.
+- **Multi-function appliance awareness in recipes** — When the user sets a multi-function appliance (Cookeo, Bimby, Thermomix, Monsieur Cuisine, Instant Pot, Multicooker, Robot da cucina) in Settings, all Gemini recipe prompts (chat, recipe generation, weekly meal plan) now explicitly instruct the AI to consolidate as many cooking steps as possible into that single machine. Each appliance's available functions (rosolare, tritare, vapore, cuocere a pressione, etc.) are listed and the AI is required to indicate the specific mode/program at each step.
+- **Server-side Bring! cleanup in cron** — `bringCleanupObsolete()` now runs every 5 minutes via cron without requiring any client page load. Items auto-added by the app (identified by `⚡`/`🟠`/`🛒` markers in their Bring! spec) are automatically removed when the smart shopping engine no longer flags them as needed. Works across all devices/clients.
+- **`shopping_name` in `inventory_list` API** — The `inventory_list` endpoint now returns the `shopping_name` field from the products table, enabling family-based stock matching in the client-side cleanup fallback.
+
+### Fixed
+- **Bring! cleanup: false token match (Succo/Frutta)** — `bringCleanupObsolete` previously indexed smart items by product name tokens. "Pera Italiana **Succo** e polpa **frutta**" (shopping_name: "Pere") caused "Succo" and "Frutta" to be retained on Bring! indefinitely even when fully stocked. Now indexes **only** by `shopping_name` tokens.
+- **Bring! cleanup: expired items with fresh family stock (Verdure)** — When a product is expired but its `shopping_name` family has ≥50% fresh stock from other products (e.g. Minestrone tradizione scaduto 01/05 but 590g fresh Verdure in freezer/pantry), it is no longer flagged as `critical` and is removed from the shopping list.
+- **Bring! remove: catalog items not removed (Formaggio/Käse)** — `bringRemoveItem()` and `bringCleanupObsolete()` now try both the Italian display name and the Bring! internal German catalog key (e.g. `Käse` for `Formaggio`). Previously, catalog items with a German key were silently not removed.
+- **Barcode scanner: EAN auto-submit on manual input** — Typing or pasting a valid 8/13-digit EAN in the manual barcode field now auto-submits immediately without needing to press a button. Checksum validation gives a warning toast for invalid codes without blocking entry.
+- **Shopping list: `isExpiringSoon` false positives** — Products bought in bulk that expire naturally in 3 days (e.g. fresh produce) were flagged `medium` urgency on the shopping list despite having 100%+ stock. Now requires `pctLeft < 50%` before triggering.
+- **Shopping list: expired batch with fresh restock suppressed** — Products with an expired batch AND a recent fresh restock (≥50% fresh stock) are no longer flagged `critical` for shopping. The expired-batch UI banner on the dashboard handles the disposal prompt instead.
+- **Shopping list: cross-device cleanup** — Client-side `cleanupObsoleteBringItems()` now detects app-added items by their spec markers (`⚡`/`🟠`/`🛒`) instead of a per-device localStorage map, making cleanup work correctly on all clients including newly logged-in devices. Throttle reduced from 30 minutes to 3 minutes.
+- **API fetch caching disabled** — All `api()` calls in the frontend now set `cache: 'no-store'` to prevent stale data from browser cache.
+- **Shopping page multi-client sync** — Added 45-second polling on the shopping page so changes made on another device are reflected automatically.
+
+
+
+### Added
+- **AI price estimation for shopping list** — Each item on the Bring! shopping list now shows an estimated retail price badge (per unit and total). Prices are fetched from Gemini AI and cached server-side for 3 months (`PRICE_UPDATE_MONTHS`). The running estimated total is displayed both in the shopping tab and as a green pill badge on the dashboard stat card.
+- **Dashboard price total badge** — The shopping stat card on the dashboard shows a green `ca. €X.XX` badge (top-right, same position as the old urgency badge). It updates in real-time as prices are calculated and persists across navigation via `sessionStorage`.
+- **Background price refresh** — Prices are fetched silently every 2 minutes even when not on the shopping tab, keeping the dashboard badge current without user interaction.
+- **Smart quantity estimation** — The price payload uses `smart_shopping` data (consumption patterns) to send the correct buy quantity per item; falls back to Bring! spec parsing, then to `qty=1, unit=conf` for manually-added items.
+
+### Fixed
+- **`stat-price-total` not visible on dashboard** — The total was only computed when `shoppingItems` was populated (i.e. shopping tab had been visited). Now uses `sessionStorage._pricetotal` as fallback so the badge is visible immediately on any page.
+- **Price bar reloading on every tab switch** — `renderShoppingItems` now checks if ALL items are already cached with matching qty/unit; if so, it applies prices from cache instantly with no loading bar or API call.
+- **`stat-price-total` real-time update** — Dashboard stat now increments as each individual item is priced (not only after the entire fetch completes).
+- **Broken emoji in `log.title`** — Corrupted `\uFFFD` character in `it.json` and `de.json` replaced with `📒`.
+- **`PRICE_CACHE_PATH` undefined crash** — Server-side constant was used inside functions that were called before the define; moved define to the very top of `api/index.php` (line 19). Affected: all `get_shopping_price` and `get_all_shopping_prices` calls from 16:33–16:40 on 2026-05-07.
+
+## [1.7.1] - 2026-05-04
+
+### Fixed
+- **Destructive actions now require confirmation** — "Butta tutto" (`throwAll`) and "Finisci tutto" (`submitUseAll`) now display a confirmation modal before executing. The modal features a 5-second auto-confirm countdown bar (red) with an "Annulla" cancel button, matching the scale auto-confirm UX pattern already in use.
+- **History undo button visibility** — The ↩ undo button in the transaction log was using `color: var(--text-muted)` making it nearly invisible. It now uses a red tint background + border (`#f87171`) with larger font size (1rem) for easy tap targeting.
+- **History undo uses custom modal** — `undoTransactionEntry()` previously used the native browser `confirm()` dialog (broken in Android WebView kiosk mode). It now uses the same `_showDestructiveConfirm()` modal with countdown.
+
+
+
+### Added
+- **Demo mode (JS frontend)** — Full client-side demo experience: Gemini is treated as available, Bring! write operations silently no-op, and a mock pantry + shopping list is shown; activated via `?demo=1` URL param or `.env` `DEMO_MODE=true`; a "DEMO" badge is injected in the header and Settings is hidden to prevent accidental writes
+- **Graceful Bring! no-key state** — When Bring! credentials are not configured the shopping tab shows a friendly localised message with a direct link to the Settings page instead of a raw API error
+- **Use-quantity guard** — Consuming more than the quantity stocked at the selected location is now blocked before the API call; the quantity input shakes (CSS `input-shake` animation) and a toast shows `use.error_exceeds_stock`
+- **Kiosk: smart auto-discovery rewrite** — `autoDiscover()` now uses `ExecutorCompletionService` + `NetworkInterface` (replaces deprecated `WifiManager`), 60 parallel threads, 600 ms TCP pre-check per host, real-time UI feedback every 120 ms, ports `[443, 80, 8080, 8443]`; VPN/cellular interfaces (tun, ppp, rmnet, pdp, ccmni, etc.) are filtered out and `wlan*`/`eth*` interfaces are prioritised
+- **Kiosk: permissions button transform** — After permissions are granted, the button changes to "✅ Permessi concessi — Continua →" (green background, dark text) and advances to step 3 on tap, replacing the separate "permissions granted" card
+- **Kiosk: gateway auto-pre-configuration** — On successful gateway install `finishSetup()` POSTs `scale_enabled=true` + `scale_gateway_url=ws://127.0.0.1:8765` to the server's `save_settings` endpoint so the webapp is scale-ready immediately after setup
+- **Kiosk: ErrorReporter init at setup start** — `SetupActivity.onCreate()` now calls `ErrorReporter.init()` with any previously saved URL, ensuring errors in step 4 (gateway install) are reported even before the user confirms the server URL
+
+### Fixed
+- **Kiosk: wrong subnet scanned** — The previous implementation picked up VPN/tun interfaces and scanned a 10.x.x.x range instead of the device's actual Wi-Fi LAN; fixed by filtering interface names and preferring `wlan`/`eth`
+- **Kiosk: port 443 missing from discovery** — HTTPS servers were never reachable during auto-discovery; ports list extended to `[443, 80, 8080, 8443]`
+- **Kiosk: gateway install status=1 silent failure** — `PackageInstaller.STATUS_FAILURE` (status 1) showed an error card but never called `ErrorReporter`; `ErrorReporter.reportMessage()` is now called with status code, message, and package name
+- **Screensaver toggle in web settings** — The screensaver row was missing a `<span class="toggle-slider">` inside the `<span class="toggle-switch">` wrapper, so no slider was rendered; corrected to use the same `toggle-row` / `toggle-switch` / `toggle-slider` structure as all other settings toggles
+- **antiwaste.title translation** — IT and DE locale files were missing the `antiwaste.title` key, causing a raw key string to appear in the anti-waste section header; added to both `it.json` and `de.json`
+
+### Kiosk (v1.4.0 → v1.5.0)
+- `autoDiscover()` fully rewritten (CompletionService, NetworkInterface, TCP pre-check, real-time feedback, correct LAN subnet)
+- Port 443 added to discovery scan
+- Permissions button transforms after grant (`onPermissionsGranted()`)
+- `ErrorReporter.init()` called at `SetupActivity.onCreate()`
+- `ErrorReporter.reportMessage()` called on gateway install failure
+- `finishSetup()` pre-configures gateway via `save_settings` API call
+
+## [1.6.0] - 2026-05-03
+
+### Added
+- **Dashboard skeleton loading** — Stat cards (Dispensa / Frigo / Freezer) show an animated shimmer placeholder (`…`) instead of the jarring `0` flash that appeared for 3–5 seconds before data loaded; the loading class is applied before the API call and removed atomically when data arrives
+- **Webapp startup preloader** — Full-screen spinner overlay during initial app load, fades out after the dashboard is ready
+- **Webapp update notification** — A dismissible top banner alerts the user when a newer GitHub release is available (checked once every 6 hours, comparison based on `published_at`)
+- **Native Android update banners** — Both Kiosk (v1.4.0) and Scale Gateway (v2.1.0) show a native top bar when a newer APK is available, with one-tap download and install
+
+### Fixed
+- **APK install conflict** — Replaced `ACTION_VIEW`-based APK install with the `PackageInstaller.Session` API (API 21+) in both Kiosk and Scale Gateway; the session-based approach correctly handles:
+  - `STATUS_PENDING_USER_ACTION` → automatically launches the system confirmation dialog
+  - `STATUS_SUCCESS` → success toast
+  - `STATUS_FAILURE_CONFLICT` / `STATUS_FAILURE_INCOMPATIBLE` → `AlertDialog` offering to uninstall the old app (signature mismatch) before reinstalling
+- **Cooking mode z-index** — Update banner and app header are now hidden when `body.cooking-mode-active` is set, and the cooking overlay z-index was raised to `99998` so it can no longer be obscured by UI chrome
+- **Version-aware error reporting** — GitHub Issues are only created when the client is running the latest released version, avoiding noise from stale deployments; non-semver tag names (e.g. `"latest"`) are treated as "always up-to-date"
+- **XOR-obfuscated GitHub token** — The PAT used for GitHub API calls is stored as an XOR-encoded hex string in both the PHP backend and Kotlin apps to prevent accidental exposure via secret scanning
+
+### Kiosk (v1.3.0 → v1.4.0)
+- FileProvider + `REQUEST_INSTALL_PACKAGES` permission added
+- APK download destination moved to `getExternalFilesDir(null)` (no storage permission needed)
+- `PackageInstaller` self-update with signature-conflict recovery
+- BLE scale gateway update banner with download + install flow
+
+### Scale Gateway (v2.0.0 → v2.1.0)
+- Same FileProvider + permission + `PackageInstaller` changes as Kiosk
+- Update banner for self-update
+- CI workflow now triggers on `develop` branch (in addition to `main`)
+
+## [Unreleased] - 2026-04-30
+
+### Fixed
+- **Low-qty banner false positive** — A "suspiciously low quantity" review alert is now suppressed for a partially-used inventory entry when one or more sibling entries for the same product (identified by barcode, or name+brand as fallback) exist in other locations with stock > 0. Prevents noise like "191 ml of milk" when 11 sealed packages are stored in the pantry.
+
+### Changed
+- **Non-alarmist expired banner** — Banner icon, CSS class, and title suffix now adapt to the `getExpiredSafety()` level:
+  - `ok` (long-life products, freezer within margin): green banner, ✅ icon, "— Scaduto (ancora ok)"
+  - `warning` (items that should be inspected): amber/yellow banner, 👀 icon, "— Scaduto (controlla)"
+  - `danger` (raw meat, dairy, fish, etc.): unchanged red 🚫 banner and "— Scaduto!" title
+- Added `expiry.expired_suffix_ok` and `expiry.expired_suffix_warning` i18n keys to all three language files (IT/EN/DE)
+- Added `banner-expired-ok` and `banner-expired-warning` CSS variants (green / amber) in `style.css`
+
+## [1.5.0] - 2026-04-28
+
+### Added
+- **Expired banner for opened products** — Products whose opened-product shelf-life has passed (e.g. fridge cream opened 6 days ago) now appear in the top notification banner, not just the dashboard list
+- **Safety-aware expired banner** — Each expired banner item shows a contextual safety tip (from `getExpiredSafety()`); danger-level items (fridge dairy/meat/fish) get an intense red banner and "L'ho buttato" as the primary button; safe/warning items keep the original button order
+- **AI model fallback** — All Gemini API endpoints (expiry scan, product identification, chat, recipe non-streaming, shopping name classifier) now try `gemini-2.5-flash` first and fall back to `gemini-2.0-flash` automatically, matching the resilience already in place for recipe streaming
+- **Friendly AI quota message** — When the AI returns a quota/rate-limit error the user sees "Quota AI esaurita. Riprova tra qualche minuto." instead of the raw API error string
+- **Cooking TTS auto-read** — Each recipe step is read aloud automatically when navigating forward or backward; the first step is also read when entering cooking mode
+- **Cooking timer 10-second warning** — When a cooking timer reaches 10 seconds the TTS announces "Attenzione! [label]: mancano 10 secondi!"
+- **Cooking recipe completion announcement** — "Ricetta completata! Buon appetito!" is spoken via TTS when the last step is confirmed
+
+### Fixed
+- **Cooking TTS gate** — `speakCookingStep()` was blocked by the global `tts_enabled` setting; the `_cookingTTS` toggle (🔊/🔇 button) is now the only gate; browser Web Speech API is used by default without requiring TTS configuration in Settings
+- **Anomaly dismiss label** — The "La quantità è giusta" button now appends the current inventory quantity, e.g. "La quantità è giusta (2 pz)", so the action is unambiguous
+- **i18n sync** — Added `timer_warning_tts`, `recipe_done_tts`, `error.ai_quota` keys to all three language files (IT/EN/DE)
+
+
+### Added
+- **Generic shopping names** — Products are grouped by type ("Latte", "Affettato", "Pasta") rather than brand; computed via an expanded keyword map with Google Gemini AI as fallback for unknown products
+- **Bring! auto-migration** — Existing list items with old specific names are silently migrated to generic names on every list load, throttled to once per 10 minutes
+- **Bring! catalog coverage** — All 93 shopping_name values now resolve to a German Bring! catalog key (icons and categories in the Bring! app); 24 aliases added to cover previously unmatched names
+- **Auto-add to Bring! on depletion** — When a product reaches zero the app adds it to Bring! automatically using the generic shopping name, with the specific product name and brand in the specification field
+- **Finished-product confirmation banner** — Instead of silently deleting zero-stock entries, a banner prompts the user to confirm; banner title includes the last 3 digits of the product barcode for easier identification
+- **Anomaly detection banner** — Dashboard notifications for suspicious inventory/transaction mismatches and consumption prediction errors, with one-tap inline correction
+- **SSE recipe streaming** — Recipe generation streams live via Server-Sent Events; Gemini agent feedback is shown in real time as it is generated
+- **Smart alert banners** — Configurable expired-only mode with explanatory messages; banner buttons are fully internationalized
+
+### Fixed
+- **Scale double-deduction** — Multiple BLE stable readings of the same weight no longer fire duplicate `inventory_use` events; JS preserves the confirmation sentinel on submit and PHP rejects a second `out` transaction for the same product within 12 seconds
+- **Kiosk native TTS** — CI workflow now builds the APK on `develop` branch too; the native Android `TextToSpeech` bridge bypasses Web Speech API voice-availability issues without requiring offline voice packs
+- **TTS voice loading** — Retries for up to 10 seconds on page load; shows a message if no voices are available and offers a manual refresh button
+- **Bring! migration** — Corrected two bugs: wrong removal API (`DELETE /item` → `PUT remove=item`) and wrong purchase key sent to Bring! (Italian shopping name → German catalog key), which previously created Italian/German duplicate entries
+- **Gemini 429 rate limiting** — API calls are retried with exponential backoff; recipe requests are capped at 5 per minute with a dedicated rate-limit bucket
+
+### Performance
+- **Gemini calls centralized** — All Gemini API requests go through a single `callGemini()` helper with intelligent backoff; Gemini removed from the product-selection and bringSuggest flows in favour of fast offline logic
+
+## [1.3.0] - 2026-04-18
+
+### Added
+- **Expired product banner** — Dashboard notifications for expired products with use, throw away, edit, and dismiss actions
+- **Expiring soon banner** — Dashboard notifications for products expiring within 3 days with use, edit, and dismiss actions
+- **Priority-sorted notifications** — Banner alerts sorted by urgency: expired > expiring > suspicious quantities > consumption predictions
+- **Swipe navigation** — Touch swipe left/right to browse banner notifications, with dot indicators and arrow buttons
+- **Quick-access buttons** — Inventory page shows 4 recently used and up to 8 most popular products for quick selection
+- **Recent & popular products API** — New `recent_popular_products` endpoint
+- **Auto-refresh** — Banner notifications refresh every 5 minutes while on the dashboard
+- **Edit from expiry banner** — Correct expiry dates directly from expired/expiring notifications
+
+### Fixed
+- **Negative scale values** — BLE scale readings with negative weight are now ignored
+- **Banner re-appearing after edit** — Editing from a banner now persists the confirmation so it doesn't reappear on dashboard reload
+- **False consumption predictions** — Manual inventory edits (updated_at > last restock) now use the correct baseline for prediction calculations
+- **Kiosk overlay blocking header** — Removed injected exit/refresh buttons from the web app header in kiosk mode
+
+## [1.2.0] - 2026-04-13
+
+### Changed
+- **Project renamed** from "Dispensa Manager" to **EverShelf**
+- Contact email updated to `evershelfproject@gmail.com`
+- Docker service, container, and volume renamed to `evershelf`
+- SQLite database renamed from `dispensa.db` to `evershelf.db`
+- All localStorage keys migrated: `dispensa_*` → `evershelf_*`
+- Apache config file renamed to `evershelf.conf`
+- CI workflow Docker image/container names updated
+- App name updated in all translations (it, en, de)
+- Navigation title updated to EverShelf across all languages
+
+### Added
+- Version badge (`v1.2.0`) in the app header
+
+### Fixed
+- JS file truncation caused by `sed` in-place edit on large files
+- Browser cache invalidation via bumped asset version strings (`?v=20260413a`)
+
 ## [1.0.0] - 2026-04-10
 
 ### Added

CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainer at **evershelfproject@gmail.com**. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to Dispensa Manager
+# Contributing to EverShelf
 
 Thank you for your interest in contributing! This guide will help you get started.
 
@@ -7,8 +7,8 @@ Thank you for your interest in contributing! This guide will help you get starte
 1. **Fork** the repository
 2. **Clone** your fork:
    ```bash
-   git clone https://github.com/YOUR_USERNAME/dispensa.git
-   cd dispensa
+   git clone https://github.com/YOUR_USERNAME/EverShelf.git
+   cd EverShelf
    ```
 3. **Create a branch** from `develop`:
    ```bash
@@ -55,7 +55,7 @@ Translations are one of the easiest ways to contribute! Each language is a singl
 
 ```json
 {
-  "app.title": "Dispensa Manager",
+  "app.title": "EverShelf",
   "nav.dashboard": "Dashboard",
   "nav.inventory": "Inventario",
   ...
@@ -110,7 +110,7 @@ node -c assets/js/app.js
 python3 -c "import json; json.load(open('translations/it.json'))"
 
 # Test Docker build
-docker build -t dispensa-test .
+docker build -t evershelf-test .
 ```
 
 ## 📝 Pull Request Process

Dockerfile

@@ -1,14 +1,19 @@
-FROM php:8.2-apache
+FROM php:8.2-apache-bookworm
 
-# Install required PHP extensions
-RUN apt-get update && apt-get install -y \
+# Install required PHP extensions + Tesseract OCR for offline expiry date reading
+RUN apt-get update && apt-get upgrade -y && apt-get install -y \
     libsqlite3-dev \
     libcurl4-openssl-dev \
-    && docker-php-ext-install pdo_sqlite curl mbstring \
+    libonig-dev \
+    libgd-dev \
+    tesseract-ocr \
+    tesseract-ocr-ita \
+    tesseract-ocr-eng \
+    && docker-php-ext-install pdo_sqlite curl mbstring gd \
     && apt-get clean && rm -rf /var/lib/apt/lists/*
 
-# Enable Apache mod_rewrite
-RUN a2enmod rewrite
+# Enable Apache mod_rewrite and mod_headers
+RUN a2enmod rewrite headers
 
 # Set working directory
 WORKDIR /var/www/html
@@ -28,8 +33,8 @@ RUN [ ! -f /var/www/html/.env ] && cp /var/www/html/.env.example /var/www/html/.
 RUN echo '<Directory /var/www/html>\n\
     AllowOverride All\n\
     Require all granted\n\
-</Directory>' > /etc/apache2/conf-available/dispensa.conf \
-    && a2enconf dispensa
+</Directory>' > /etc/apache2/conf-available/evershelf.conf \
+    && a2enconf evershelf
 
 # Expose port 80
 EXPOSE 80

README.md

@@ -1,60 +1,177 @@
-# 🏠 Dispensa Manager
+# 🏠 EverShelf
 
 > **Self-hosted pantry management system** — Track your food inventory, scan barcodes, get AI-powered recipe suggestions, and reduce waste.
 
+---
+
+<div align="center">
+
+### 🚀 Try the live demo — no installation required!
+
+**[▶ Open Live Demo](https://evershelfproject.dadaloop.it/demo)**
+&nbsp;·&nbsp;
+[🌐 Project Website](https://evershelfproject.dadaloop.it/)
+&nbsp;·&nbsp;
+[📖 Wiki](https://github.com/dadaloop82/EverShelf/wiki)
+
+*The demo runs with mock pantry data. AI features are fully enabled. All write operations are safely sandboxed.*
+
+</div>
+
+---
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![PHP](https://img.shields.io/badge/PHP-8.0+-blue.svg)](https://www.php.net/)
 [![SQLite](https://img.shields.io/badge/SQLite-3-blue.svg)](https://www.sqlite.org/)
 [![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg)](Dockerfile)
-[![i18n](https://img.shields.io/badge/i18n-IT%20%7C%20EN%20%7C%20DE-orange.svg)](translations/)
+[![i18n](https://img.shields.io/badge/i18n-IT%20%7C%20EN%20%7C%20DE%20%7C%20FR%20%7C%20ES-orange.svg)](translations/)
+[![Version](https://img.shields.io/badge/version-1.7.36-brightgreen.svg)](CHANGELOG.md)
+[![GitHub stars](https://img.shields.io/github/stars/dadaloop82/EverShelf?style=social)](https://github.com/dadaloop82/EverShelf/stargazers)
+[![Last commit](https://img.shields.io/github/last-commit/dadaloop82/EverShelf/main)](https://github.com/dadaloop82/EverShelf/commits/main)
+[![Contributors](https://img.shields.io/github/contributors/dadaloop82/EverShelf)](https://github.com/dadaloop82/EverShelf/graphs/contributors)
+[![GitHub Discussions](https://img.shields.io/github/discussions/dadaloop82/EverShelf)](https://github.com/dadaloop82/EverShelf/discussions)
+[![CI](https://github.com/dadaloop82/EverShelf/actions/workflows/ci.yml/badge.svg)](https://github.com/dadaloop82/EverShelf/actions/workflows/ci.yml)
 
-<!--
-<p align="center">
-  <img src="assets/img/screenshots/dashboard.png" alt="Dashboard Screenshot" width="320" />
-</p>
--->
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/J3J01ZNETZ)
+
+---
+
+> **⚠️ Name disambiguation:** There is an unrelated iOS app also called **EverShelf**, developed and published by [Joshumi Technologies LLC](https://evershelf.joshumi.com/) on the [Apple App Store](https://apps.apple.com/app/evershelf/id6759439940). That application is a **completely separate, independent product** with no affiliation, association, or collaboration with this open-source project. This repository has no connection to Joshumi Technologies LLC, its products, or its services.
 
 ---
 
 ## ✨ Features
 
+### 🏠 NEW — Home Assistant Integration
+
+EverShelf has a **native Home Assistant integration** available on HACS.  
+Connect your pantry to your smart home in minutes — no YAML, no manual sensor setup.
+
+[![Install via HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=dadaloop82&repository=ha-evershelf&category=integration)
+&nbsp;
+[![Add Integration](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=evershelf)
+
+**What you get:**
+
+| | |
+|---|---|
+| **16 sensors** | Expiry counts, stock levels by location (pantry / fridge / freezer), shopping list total, AI API usage, last backup timestamp, days to next expiry |
+| **6 binary sensors** | Expired items, expiring items, expiring today, shopping list active, backup overdue, Bring! connected |
+| **5 action buttons** | Refresh data, Refresh prices, **Suggest Recipe** (AI — result as HA notification), Sync smart shopping, Clear expired rows |
+| **Shopping list todo** | Bidirectional sync — add, remove, check off items directly from HA |
+| **Expiry calendar** | Every product's expiry date as a native HA calendar event — works with the calendar card and any calendar automation |
+| **Quick-add text entity** | Type a product name in HA to instantly add it to the shopping list (great for voice assistants / Assist) |
+| **6 services** | `add_to_shopping`, `mark_used`, `refresh`, `suggest_recipe`, `refresh_prices`, `clear_expired` |
+| **Auto-discovery** | Detected automatically via Zeroconf/mDNS when `avahi-daemon` runs on the EverShelf host |
+| **5 languages** | English, Italian, German, French, Spanish |
+
+> **Requires a self-hosted EverShelf instance.** The integration talks directly to your server — no cloud involved.  
+> Full documentation: [ha-evershelf on GitHub](https://github.com/dadaloop82/ha-evershelf)
+
+---
+
 ### 📦 Inventory Management
-- **Barcode scanning** — Scan products with your phone camera using QuaggaJS
-- **AI identification** — Take a photo and let Google Gemini identify the product
+- **Export inventory** — Download the full inventory as a UTF-8 CSV (Excel-compatible) or open a print-ready page to save as PDF; export button always visible in the inventory page header
+- **Barcode scanning** — Scan products with your phone camera using QuaggaJS; last 20 scanned products saved as tappable chips so you can re-select them without rescanning
+- **AI identification** — Take a photo and let Google Gemini identify the product, with suggestions from your existing inventory; gracefully shows a friendly message when AI quota is exhausted instead of a raw API error
 - **Smart locations** — Track items across Pantry, Fridge, Freezer, and custom locations
 - **Expiry tracking** — Automatic shelf-life estimation based on product type and storage
-- **Opened product tracking** — Reduced shelf-life calculation when packages are opened
-- **Vacuum-sealed support** — Extended expiry dates for vacuum-sealed items
+- **Opened product tracking** — Reduced shelf-life calculation when packages are opened; opened-product expiry is now also checked when building banner alerts (not just the dashboard section)
+- **Vacuum-sealed support** — Extended expiry dates for vacuum-sealed items; products sealed under vacuum are only flagged as expired after a configurable grace period past the printed date (`VACUUM_EXPIRY_EXTENSION_DAYS`, default 30 days, configurable in `.env`)
+- **Anomaly detection** — Banner alerts for suspicious quantities and consumption predictions with inline correction; dismiss button now shows the current inventory quantity so the action is unambiguous ("Quantity is correct (2 pcs)")
 
 ### 🤖 AI-Powered (Google Gemini)
 - **Expiry date reading** — Photograph a label and extract the expiry date automatically
 - **Product identification** — Point your camera at any product for instant recognition
-- **Recipe generation** — Get personalized recipes based on what's in your pantry
+- **Existing product matching** — AI scan shows matching products already in your pantry before suggesting new ones
+- **Storage & shelf-life hint** — When adding a new product, Gemini suggests the optimal storage location and shelf-life in the background; shown as an inline AI badge next to the expiry estimate
+- **Recipe generation** — Get personalized recipes based on what's in your pantry; streams live via Server-Sent Events so results appear as they are generated
+- **Recipe stock hints** — Each pantry ingredient shows how much you have and what remains after use; when the leftover would be less than 5% of the full sealed package (10% for an already-opened partial pack), the recipe automatically uses everything on hand to avoid waste
 - **Smart chat assistant** — Ask questions about your inventory, get cooking tips
-- **Shopping suggestions** — AI-powered purchase recommendations
+- **Shopping suggestions with tips** — AI-powered purchase recommendations, each enriched with a short practical buying/storing tip
+- **Anomaly explanation** — "Explain" button on anomaly banners explains in plain language why a discrepancy likely occurred and what to do
+- **Model fallback** — All AI endpoints try `gemini-2.5-flash` first and fall back to `gemini-2.0-flash` automatically
+- **Graceful no-key state** — When no Gemini key is configured, AI entry points show a friendly message; the header button is visually greyed with an amber dot
 
 ### 🛒 Shopping List
 - **Bring! integration** — Sync with the [Bring!](https://www.getbring.com/) shopping list app
+- **Generic shopping names** — Products are grouped by type (e.g. "Milk", "Cold cuts", "Cooking cream") rather than brand, keeping the Bring! list clean and consolidated
 - **Smart predictions** — Know what you'll need before you run out
-- **Auto-remove on scan** — Products are removed from the shopping list when scanned in
-- **DupliClick integration** — Online grocery ordering (Gruppo Poli)
+- **Auto-add on depletion** — When a product reaches zero the app adds it to Bring! automatically, no confirmation needed
+- **Auto-remove on scan** — Products are removed from the shopping list when scanned in  - **Auto-migration** — Items already on the Bring! list are silently renamed to their generic name in the background (throttled, runs on list load)
+  - **Catalog coverage** — All product types resolve to a German Bring! catalog key for icon and category display in the Bring! app
 
 ### 🍳 Cooking Mode
+- **♻️ Zero-waste tips** — For each cooking step that generates reusable scraps (peels, cooking water, egg whites, cheese rinds, bread crusts, vegetable tops, etc.), a dismissible ♻️ tip card appears with a practical reuse idea; tips are generated by Gemini as part of the recipe at no extra API cost; opt-in toggle in Settings (default OFF)
 - **Step-by-step guidance** — Follow recipes with a hands-free cooking interface
-- **Text-to-Speech** — Voice readout of recipe steps (configurable TTS endpoint)
+- **Text-to-Speech** — Voice readout of recipe steps; supports browser Web Speech API, native Android TTS (kiosk), or a custom REST endpoint (Home Assistant, etc.); retries voice loading for up to 10 seconds with a fallback refresh button; TTS activates automatically without requiring the global TTS setting to be enabled
+- **Auto-read on navigate** — Each step is read aloud automatically when you tap Next or Previous; the first step is read when entering cooking mode
+- **Timer voice alerts** — 10-second countdown warning spoken aloud before each timer expires; expiry announced vocally when time is up
+- **Recipe completion** — "Bon appétit!" announced via TTS when the last step is confirmed
 - **Built-in timer** — Automatic timer suggestions based on recipe instructions
-- **Ingredient tracking** — Mark ingredients as used during cooking
+- **Ingredient tracking** — Mark ingredients as used during cooking; leftover quantities prompt a "move to another location" flow
 
 ### 📊 Dashboard
 - **Waste tracking** — Monitor consumed vs. wasted products over 30 days
+- **Anti-waste report** — Personalised waste rate vs. national average with annual kg estimate; shown above the expiring-items list
 - **Expiry alerts** — Visual warnings for expired and soon-to-expire items
-- **Safety ratings** — Smart assessment of expired product safety (by category)
+- **Opened products panel** — Tracks partially-used items; expiry is recalculated from the opening date using AI (Gemini) + per-category rule fallback; whole sealed packages always keep their original manufacturer expiry; conf items with mixed whole + fractional units are shown as two separate entries
+- **Freezer shelf-life** — Granular per-product estimates (USDA/EFSA): fish 120 d, poultry 270 d, whole red-meat cuts 365 d, mince 120 d, vegetables/fruit 270 d, generic 180 d; AI + cache still take priority over rules
+- **Safety ratings** — Smart assessment of expired product safety (by category and location); expired unsafe items shown with a red danger banner and a discard action as the primary action
+- **Expired product banner** — Products that have passed their effective shelf-life (including opened-product reduced expiry) appear in the top notification banner; icon, colour and title adapt to the actual safety level (✅ green for safe, 👀 amber to check, 🚫 red for danger); high-risk items get a prominent discard action
 - **Quick recipe bar** — One-tap recipe suggestion using expiring products
+- **Anomaly banner** — Scrollable banner with suspicious quantities and consumption prediction mismatches, with one-tap correction or inline edit
+- **Expired/expiring alerts** — Priority-sorted banner notifications for expired and soon-to-expire products with use, throw, edit, and dismiss actions
+- **Swipe navigation** — Touch swipe or tap arrows/dots to browse banner notifications
+- **Quick-access buttons** — Recently used and most popular products shown on the inventory page for fast access
 
-### 📱 Progressive Web App
+### 🌙 Appearance
+- **Dark mode** — Three modes: Light, Dark, and Auto (time-based: dark from 20:00 to 07:00, light otherwise); applies immediately without page reload; auto mode re-evaluates every 5 minutes, so night/day transitions happen automatically even on always-on kiosk displays; theme is applied before the first render to prevent a white flash
+- **Global settings tab** — A dedicated **⚙️ General** tab groups all system-wide settings (language, currency, theme, screensaver, zero-waste tips, export) at the top of the Settings panel
+
+### �️ Database Maintenance
+- **Automatic cleanup** — Recipes older than `RECIPE_RETENTION_DAYS` (default 7) and transactions older than `TRANSACTION_RETENTION_DAYS` (default 7) are deleted automatically on every cron cycle; SQLite `VACUUM` runs after each cleanup to keep the file compact
+- **Manual cleanup** — Trigger immediately via `GET /api/?action=db_cleanup`
+- **Compact by default** — Fresh installs stay small; large accumulated databases shrink back to a few hundred KB within one cron cycle
+
+### �📱 Progressive Web App
 - **Mobile-first design** — Optimized for phones, works on tablets and desktop
 - **Installable** — Add to home screen for a native app experience
-- **Multi-device** — Settings and data sync across devices on the same server
+- **Multi-device** — All user data (shopping tags, pinned items, location preferences, scan history) is stored server-side in SQLite and shared across every device on the same instance; no data is siloed in a single browser's localStorage
+### 📶 Offline Mode
+- **Automatic detection** — Full-screen overlay appears immediately on network loss; shows a "Continue offline" button after 3 s, and auto-enters offline mode after 8 s
+- **Local inventory cache** — Inventory is synced to `localStorage` at every startup and on each successful API call; the offline view always reflects the last known state
+- **Write queue** — Add, use, update and delete operations performed while offline are queued locally and synced to the server automatically on reconnect (including after a page refresh)
+- **Optimistic UI** — Queued writes are applied immediately to the local cache so the interface stays responsive
+- **Offline-computed stats** — Expiring and expired items are derived client-side from the cache; dashboard stat cards show real counts instead of zeros
+- **AI/network sections hidden** — Anti-waste chart, nutrition analysis, recipe generator, price fetching, and Gemini chat are hidden in offline mode; the inventory, history, and manually-managed shopping list remain fully functional
+- **Broken image fallback** — External product images (Open Food Facts, etc.) that fail to load are replaced with a neutral grey placeholder, keeping the layout intact
+- **Startup recovery** — If the page is refreshed while operations are queued, they are detected and synced automatically on the next successful startup
+- **Buffered error reporting** — `remoteLog` and `reportError` calls made while offline are stored locally and flushed to the server (and to GitHub issues) when the connection is restored
+### ⚖️ Smart Scale Integration (Add-on)
+- **Bluetooth gateway** — Connects a BLE smart scale to EverShelf via local WebSocket
+- **SSE relay** — Server-side relay avoids mixed-content (HTTPS→WS) issues
+- **Auto-discovery** — Server scans LAN to find the gateway automatically
+- **Auto weight reading** — When adding/using a product with unit g/ml, weight fills automatically
+- **10g threshold** — Ignores readings that haven't changed enough between products  - **Duplicate-reading prevention** — Server-side 12-second dedup window rejects a second scale-triggered deduction of the same product, guarding against BLE multi-fire- **ml conversion hint** — Shows "weight in grams → will be converted to ml" when product unit is ml
+- **Stability + auto-confirm** — 10s stable wait + 5s countdown before confirming
+- **Real-time status** — Scale connection indicator always visible in the header
+- **Multi-protocol** — Supports Bluetooth SIG Weight Scale, Body Composition, Xiaomi Mi Scale 2 and 100+ models
+- **Built into kiosk (v1.6.0+)** — BLE gateway runs as an integrated foreground service inside the [EverShelf Kiosk](evershelf-kiosk/) app; no separate APK needed.
+
+### 📺 Android Kiosk Mode (Add-on)
+- **Dedicated tablet app** — Full-screen WebView wrapper for wall-mounted kitchen tablets
+- **True kiosk lock** — Screen pinning blocks home/recent buttons
+- **Setup wizard** — 6-step guided configuration (language, welcome, permissions, server URL, BLE scale scan, screensaver, summary)
+- **Smart auto-discovery** — Scans the LAN in parallel (60 threads, TCP pre-check, ports 80/443/8080/8443) with real-time UI feedback; correctly identifies the device's Wi-Fi/Ethernet subnet (VPN and cellular interfaces are filtered out)
+- **Built-in BLE scale gateway** — `GatewayService` foreground service; BLE scanning + WebSocket server `:8765` run directly inside the kiosk app. Select your scale in step 5 of the wizard — no external app required
+- **Scale auto-configuration** — After selecting the BLE device, the wizard writes `scale_enabled` and `scale_gateway_url=ws://127.0.0.1:8765` to the server automatically
+- **Camera & mic permissions** — Full hardware access for barcode scanning and voice; grant button transforms to a green confirmation after granting
+- **Native TTS bridge** — Cooking mode voice readout uses the Android TextToSpeech engine directly, bypassing Web Speech API voice limitations; no offline voice packs required
+- **Hard refresh** — ↻ button clears WebView cache to pick up web app updates
+- **Update notifications** — Checks GitHub releases every 6h, shows banner when updates available
+- **SSL support** — Accepts self-signed certificates
+- **Android kiosk app** — [`evershelf-kiosk/`](evershelf-kiosk/) — downloadable APK
 
 ---
 
@@ -71,8 +188,8 @@
 
 ```bash
 # 1. Clone the repository
-git clone https://github.com/dadaloop82/dispensa.git
-cd dispensa
+git clone https://github.com/dadaloop82/EverShelf.git
+cd EverShelf
 
 # 2. Create configuration file
 cp .env.example .env
@@ -88,8 +205,8 @@ docker compose up -d
 
 ```bash
 # 1. Clone the repository
-git clone https://github.com/dadaloop82/dispensa.git
-cd dispensa
+git clone https://github.com/dadaloop82/EverShelf.git
+cd EverShelf
 
 # 2. Create configuration file
 cp .env.example .env
@@ -117,6 +234,36 @@ BRING_PASSWORD=your_password
 TTS_URL=http://your-home-assistant:8123/api/events/tts_speak
 TTS_TOKEN=your_long_lived_token
 TTS_ENABLED=true
+
+# Optional: DB retention and cleanup (applied automatically each cron cycle)
+RECIPE_RETENTION_DAYS=7        # delete recipe plans older than N days
+TRANSACTION_RETENTION_DAYS=90   # delete stock transactions older than N days (min 30 enforced)
+
+# Optional: Vacuum-sealed expiry grace period
+VACUUM_EXPIRY_EXTENSION_DAYS=30 # extra days before vacuum-sealed items are flagged expired
+
+# Optional: Gemini cost rates (USD per million tokens, for the Info tab cost estimate)
+GEMINI_COST_25F_IN=0.15
+GEMINI_COST_25F_OUT=0.60
+GEMINI_COST_20F_IN=0.10
+GEMINI_COST_20F_OUT=0.40
+
+# Optional: Security — protect all API endpoints
+# Set a strong random string; clients send it as X-API-Token header (or ?api_token= for HA)
+API_TOKEN=
+
+# Optional: Legacy alias for API_TOKEN (settings save only)
+SETTINGS_TOKEN=
+
+# Optional: Demo mode — block all write operations at the router level
+DEMO_MODE=false
+
+# Optional: Logging
+# LOG_LEVEL sets the minimum severity written to disk (DEBUG / INFO / WARN / ERROR)
+# DEBUG also logs every SQL query executed against the database
+LOG_LEVEL=INFO
+LOG_ROTATE_HOURS=24   # hours before opening a new log file (default: 24)
+LOG_MAX_FILES=14      # maximum number of rotated files to keep (default: 14)
 ```
 
 ### Web Server Configuration
@@ -127,7 +274,7 @@ TTS_ENABLED=true
 The app works out of the box with Apache if placed in the web root or a subdirectory. Make sure `mod_rewrite` is enabled and `AllowOverride All` is set.
 
 ```apache
-<Directory /var/www/html/dispensa>
+<Directory /var/www/html/evershelf>
     AllowOverride All
     Require all granted
 </Directory>
@@ -142,7 +289,7 @@ The app works out of the box with Apache if placed in the web root or a subdirec
 server {
     listen 80;
     server_name your-server.local;
-    root /var/www/html/dispensa;
+    root /var/www/html/evershelf;
     index index.html;
 
     location /api/ {
@@ -176,7 +323,7 @@ Set up a cron job for smart shopping predictions:
 
 ```bash
 # Run every 5 minutes
-*/5 * * * * php /path/to/dispensa/api/cron_smart_shopping.php >> /path/to/dispensa/data/cron.log 2>&1
+*/5 * * * * php /path/to/evershelf/api/cron_smart_shopping.php >> /path/to/evershelf/data/cron.log 2>&1
 ```
 
 ### Backup (Optional)
@@ -185,15 +332,33 @@ The included `backup.sh` creates local daily backups of your database:
 
 ```bash
 # Run daily at 3 AM
-0 3 * * * /path/to/dispensa/backup.sh
+0 3 * * * /path/to/evershelf/backup.sh
 ```
 
+### Google Drive Backup (Optional)
+
+EverShelf supports automatic daily backups to Google Drive via OAuth 2.0. This works on any server, including private IP / local network setups (no public domain required).
+
+**Setup:**
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com) and select or create a project.
+2. Enable the **Google Drive API** (`APIs & Services → Enable APIs → Google Drive API`).
+3. Go to `APIs & Services → Credentials → Create Credentials → OAuth client ID`.
+4. Application type: **Web application**.
+5. Add **`http://localhost`** as an Authorized Redirect URI (this is the key — it works even without a real domain).
+6. Copy **Client ID** and **Client Secret** into EverShelf Settings → Backup.
+7. Enter your **Google Drive Folder ID** (the last part of the folder URL).
+8. Click **Authorize with Google** and sign in.
+9. The browser will redirect to `http://localhost` and may show a connection error — **this is expected**. Copy the full URL from the address bar (e.g. `http://localhost/?code=4%2F0A...`) and paste it into the field that appears in EverShelf, then click **Submit**.
+
+> **Note:** While the OAuth app is in *Testing* status in Google Cloud Console, you must add your Google account as a test user under `APIs & Services → OAuth consent screen → Test users`.
+
 ---
 
 ## 🏗️ Architecture
 
 ```
-dispensa/
+evershelf/
 ├── index.html              # Single-page application (SPA)
 ├── manifest.json           # PWA manifest
 ├── .env.example            # Configuration template
@@ -211,9 +376,17 @@ dispensa/
 │   └── img/                # Static images
 │
 └── data/                   # Runtime data (gitignored)
-    ├── dispensa.db         # SQLite database (auto-created)
+    ├── evershelf.db         # SQLite database (auto-created)
     ├── backups/            # Local DB backups
     └── *.json              # Token/cache files
+
+evershelf-scale-gateway/    # ⚖️ Android BLE gateway [DEPRECATED — integrated into kiosk v1.6.0+]
+    ├── README.md           # Deprecation notice + legacy docs
+    └── app/src/            # Kotlin Android source (WebSocket + BLE)
+
+evershelf-kiosk/            # 📺 Android kiosk app (add-on)
+    ├── README.md           # Setup & feature docs
+    └── app/src/            # Kotlin Android source (WebView wrapper)
 ```
 
 ### API Endpoints
@@ -232,6 +405,9 @@ dispensa/
 | | `gemini_expiry` | POST | Read expiry date from photo |
 | | `gemini_chat` | POST | Chat with AI assistant |
 | | `generate_recipe` | POST | Generate recipe from inventory |
+| | `gemini_product_hint` | POST | Storage location + shelf-life hint |
+| | `gemini_shopping_enrich` | POST | Enrich shopping suggestions with tips |
+| | `gemini_anomaly_explain` | POST | Plain-language anomaly explanation |
 | **Shopping** | `bring_list` | GET | Get Bring! shopping list |
 | | `bring_add` | POST | Add items to Bring! |
 | | `smart_shopping` | GET | Smart shopping predictions |
@@ -244,10 +420,15 @@ dispensa/
 
 - **Credentials** are stored in `.env` (server-side, never committed to Git)
 - **Database** stays local — never pushed to remote repositories
-- **API keys** are passed server-side only — never exposed to the browser
+- **Apache/Nginx hardening** — `.env`, `data/`, and `logs/` are blocked from direct HTTP access
+- **API token** — set `API_TOKEN` in `.env` to require `X-API-Token` on all API calls (Home Assistant: `?api_token=`)
+- **API keys are never exposed to the browser** — `get_settings` returns only boolean flags (`gemini_key_set`, `ha_token_set`, …)
+- **GitHub Issues token** — stored encrypted as `GH_ISSUE_TOKEN_ENC` + `GH_ISSUE_TOKEN_KEY` (see `scripts/encrypt-gh-token.php`)
+- **Settings write protection** — `save_settings` requires the same API token when configured; validated with `hash_equals`
+- **Demo / public mode** — set `DEMO_MODE=true` to block all write operations at the PHP router level before any business logic runs
 - The API uses **parameterized SQL queries** (PDO prepared statements) against injection
 - **Input validation** on all inventory operations (quantity bounds, location whitelist)
-- Consider adding **authentication** if the server is accessible from the internet
+- Consider adding **reverse-proxy authentication** (e.g. Authelia, Nginx `auth_basic`) if the server is accessible from the internet
 
 ---
 
@@ -255,7 +436,7 @@ dispensa/
 
 ```bash
 # Run PHP's built-in server for local development
-php -S localhost:8080 -t /path/to/dispensa
+php -S localhost:8080 -t /path/to/evershelf
 
 # Check PHP syntax
 php -l api/index.php
@@ -268,13 +449,7 @@ The application uses no build tools — edit files directly and refresh.
 
 ## 📋 Roadmap
 
-- [ ] Multi-language support (i18n)
-- [ ] User authentication / multi-user support
-- [ ] Docker container for easy deployment
-- [x] REST API documentation (OpenAPI/Swagger) — see [docs/openapi.yaml](docs/openapi.yaml)
-- [ ] Offline mode with service worker
-- [ ] Export/import inventory data
-- [ ] Notification system (Telegram, email) for expiring products
+Feature requests, bug reports and planned work are tracked in the [**EverShelf Roadmap**](https://github.com/users/dadaloop82/projects/2) GitHub Project.
 
 ---
 
@@ -287,6 +462,8 @@ The app supports multiple languages via JSON translation files in the `translati
 | 🇮🇹 Italian (it) | ✅ Complete (base) |
 | 🇬🇧 English (en) | ✅ Complete |
 | 🇩🇪 German (de) | ✅ Complete |
+| 🇫🇷 French (fr) | ✅ Complete |
+| 🇪🇸 Spanish (es) | ✅ Complete |
 
 **Want to add your language?** See the [Translation Guide](CONTRIBUTING.md#-adding-translations) — just copy `translations/it.json`, translate the values, and submit a PR!
 
@@ -302,6 +479,48 @@ Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed g
 4. Push to the branch (`git push origin feature/my-feature`)
 5. Open a Pull Request
 
+### Easiest way to start — translate EverShelf into your language
+
+Translations are just JSON files. No coding, no setup — fork → edit → PR.
+
+```
+translations/
+├── it.json   ✅ Italian (base)
+├── en.json   ✅ English
+├── de.json   ✅ German
+├── fr.json   ✅ French
+├── es.json   ✅ Spanish
+├── pt.json   ❌ Portuguese — wanted!
+├── nl.json   ❌ Dutch — wanted!
+└── ...       ❌ Your language here!
+```
+
+👉 See [issue #93](https://github.com/dadaloop82/EverShelf/issues/93) to claim a language.
+
+### Other ways to contribute
+
+| What | Skill needed |
+|---|---|
+| 🐛 Report a bug | None |
+| 📖 Improve the wiki | Markdown |
+| 🌍 Add a translation | JSON editing |
+| 🎨 Fix a CSS/UI issue | CSS / HTML |
+| ⚙️ Implement a feature | PHP / JS |
+| ⭐ Star the repo | Clicking |
+
+👉 Browse [`help wanted`](https://github.com/dadaloop82/EverShelf/labels/help%20wanted) issues for good starting points.
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide (branch naming, code style, how to run locally).
+
+---
+
+## 💬 Community
+
+Join the conversation in [GitHub Discussions](https://github.com/dadaloop82/EverShelf/discussions):
+- **Vote on upcoming features** — tell us what to build next
+- **Show your setup** — share your kitchen kiosk
+- **Ask questions** — get help from the community
+
 ---
 
 ## 📄 License
@@ -312,6 +531,21 @@ This project is licensed under the **MIT License** — see the [LICENSE](LICENSE
 
 ## 👨‍💻 Author
 
-**Stimpfl Daniel** — [dadaloop82@gmail.com](mailto:dadaloop82@gmail.com)
+**Stimpfl Daniel** — [evershelfproject@gmail.com](mailto:evershelfproject@gmail.com)
 
+- Website: [evershelfproject.dadaloop.it](https://evershelfproject.dadaloop.it/)
 - GitHub: [@dadaloop82](https://github.com/dadaloop82)
+
+---
+
+## 📸 Screenshots
+
+<div align="center">
+
+![EverShelf demo — barcode scan, inventory management and AI recipe generation](assets/img/demo.gif)
+
+</div>
+
+For a live walkthrough with real data and full AI enabled, visit the **[live demo](https://evershelfproject.dadaloop.it/demo)** — no installation required.
+
+> Want to contribute additional screenshots? See [CONTRIBUTING.md](CONTRIBUTING.md) — PRs welcome!

SECURITY.md

@@ -0,0 +1,48 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest released version of EverShelf receives security fixes.
+
+| Version | Supported |
+|---------|-----------|
+| Latest (1.7.x) | ✅ |
+| Older releases | ❌ |
+
+## Reporting a Vulnerability
+
+**Please do NOT open a public GitHub issue for security vulnerabilities.**
+
+Report security issues privately via email:
+
+**📧 evershelfproject@gmail.com**
+
+Include:
+- A description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Your GitHub username (optional — for credit)
+
+I aim to acknowledge reports within **48 hours** and release a fix within **7 days** for critical issues.
+
+## Scope
+
+EverShelf is a **self-hosted** application. The security model assumes:
+
+- It runs on a trusted private network (home LAN)
+- Access from the internet requires the user to set up their own authentication layer (e.g. reverse proxy with Authelia, Nginx `auth_basic`)
+
+Out-of-scope issues:
+- Vulnerabilities that require physical access to the server
+- Issues only affecting users who have not followed the security recommendations in the README
+- Denial-of-service attacks on the demo server
+
+## Security Features
+
+- API keys stored server-side in `.env`, never sent to the browser
+- `get_settings` returns only boolean flags (`gemini_key_set`), never raw key values
+- Optional `SETTINGS_TOKEN` protects write operations (`hash_equals` to prevent timing attacks)
+- `DEMO_MODE=true` blocks all write operations at the router level
+- Parameterized SQL queries (PDO prepared statements) throughout
+- Input validation and length limits on all user-supplied fields
+- `.env` and `data/` directories denied via web server config (see README)

api/bootstrap.php

@@ -0,0 +1,11 @@
+<?php
+/**
+ * EverShelf API bootstrap — shared by HTTP router and cron.
+ */
+require_once __DIR__ . '/lib/env.php';
+require_once __DIR__ . '/lib/constants.php';
+require_once __DIR__ . '/lib/github.php';
+require_once __DIR__ . '/lib/security.php';
+require_once __DIR__ . '/lib/cron_log.php';
+require_once __DIR__ . '/logger.php';
+require_once __DIR__ . '/database.php';

api/cron_smart_shopping.php

@@ -2,7 +2,7 @@
 /**
  * Cron: pre-compute smart shopping list and save to cache.
  * Install with:  crontab -e
- *   *\/5 * * * * php /var/www/html/dispensa/api/cron_smart_shopping.php >> /var/www/html/dispensa/data/cron.log 2>&1
+ *   *\/5 * * * * php /var/www/html/evershelf/api/cron_smart_shopping.php >> /var/www/html/evershelf/data/cron.log 2>&1
  */
 
 // Only allow CLI execution — block HTTP access
@@ -11,14 +11,16 @@ if (PHP_SAPI !== 'cli') {
     exit('Forbidden');
 }
 
-// Define CRON_MODE before loading index.php so the router is skipped
+// Define CRON_MODE before loading bootstrap so the HTTP router is skipped
 define('CRON_MODE', true);
 
-// Load all API functions without running the HTTP router
+require_once __DIR__ . '/bootstrap.php';
 require_once __DIR__ . '/index.php';
 
 const CACHE_FILE = __DIR__ . '/../data/smart_shopping_cache.json';
 
+evershelfRotateCronLog();
+
 try {
     $db = getDB();
 
@@ -39,8 +41,214 @@ try {
         throw new RuntimeException('Cannot write cache file: ' . CACHE_FILE);
     }
 
-    echo '[' . date('Y-m-d H:i:s') . '] OK — ' . count($decoded['items'] ?? []) . " items cached\n";
+    $itemCount = count($decoded['items'] ?? []);
+    echo '[' . date('Y-m-d H:i:s') . '] OK — ' . $itemCount . " items cached\n";
+
+    // ── Bring! server-side cleanup ────────────────────────────────────────
+    // After computing smart shopping, automatically remove stale Bring! items
+    // and add/update critical ones. This runs fully server-side every cron cycle.
+    try {
+        $cleanupResult = bringCleanupObsolete($db);
+        if (isset($cleanupResult['skipped'])) {
+            echo '[' . date('Y-m-d H:i:s') . '] Bring! cleanup skipped: ' . $cleanupResult['skipped'] . "\n";
+        } else {
+            echo '[' . date('Y-m-d H:i:s') . '] Bring! cleanup — removed: ' . ($cleanupResult['removed'] ?? 0)
+                . '/' . ($cleanupResult['candidates'] ?? 0) . ' candidates'
+                . ($cleanupResult['errors'] ? ', errors: ' . $cleanupResult['errors'] : '') . "\n";
+        }
+
+        $addResult = bringAutoAddCritical($db);
+        if (isset($addResult['skipped'])) {
+            echo '[' . date('Y-m-d H:i:s') . '] Bring! auto-add skipped: ' . $addResult['skipped'] . "\n";
+        } else {
+            echo '[' . date('Y-m-d H:i:s') . '] Bring! auto-add — added: ' . ($addResult['added'] ?? 0)
+                . ', updated specs: ' . ($addResult['updated'] ?? 0) . "\n";
+        }
+    } catch (Throwable $be) {
+        echo '[' . date('Y-m-d H:i:s') . '] Bring! sync warning: ' . $be->getMessage() . "\n";
+    }
+
+    // ── Shelf life pre-warming ────────────────────────────────────────────
+    // Pre-warm the opened shelf life cache for opened items not yet cached.
+    // Capped at 5 items per cron cycle to avoid Gemini rate limits.
+    try {
+        $prewarmResult = prewarmShelfLifeCache($db, 5);
+        if ($prewarmResult['warmed'] > 0) {
+            echo '[' . date('Y-m-d H:i:s') . '] Shelf life pre-warm — warmed: ' . $prewarmResult['warmed']
+                . ', skipped: ' . $prewarmResult['skipped'] . "\n";
+        }
+    } catch (Throwable $pe) {
+        echo '[' . date('Y-m-d H:i:s') . '] Shelf life pre-warm warning: ' . $pe->getMessage() . "\n";
+    }
+
+    // ── DB cleanup (retention policy) ────────────────────────────────────
+    // Delete old recipes and transactions based on .env retention settings.
+    try {
+        ob_start();
+        dbCleanup($db);
+        ob_end_clean();
+        echo '[' . date('Y-m-d H:i:s') . '] DB cleanup done'
+            . ' (recipes >' . env('RECIPE_RETENTION_DAYS','7') . 'd'
+            . ', tx >' . env('TRANSACTION_RETENTION_DAYS','90') . 'd' . ")\n";
+    } catch (Throwable $ce) {
+        echo '[' . date('Y-m-d H:i:s') . '] DB cleanup warning: ' . $ce->getMessage() . "\n";
+    }
+
+    // ── Daily incremental backup ──────────────────────────────────────────
+    // Create a local backup at most once every 23 h; also push to Google Drive
+    // if GDRIVE_ENABLED=true.  The guard prevents multiple backups per day even
+    // though the cron runs every 5 minutes.
+    if (env('BACKUP_ENABLED', 'true') === 'true') {
+        try {
+            $lastBackupTs = 0;
+            if (file_exists(BACKUP_LAST_TS_PATH)) {
+                $lastData     = json_decode(file_get_contents(BACKUP_LAST_TS_PATH), true) ?: [];
+                $lastBackupTs = (int)($lastData['ts'] ?? 0);
+            }
+            if (time() - $lastBackupTs >= 82800) { // 23 h
+                $backupResult = createLocalBackup($db);
+                if ($backupResult['success']) {
+                    echo '[' . date('Y-m-d H:i:s') . '] Backup local: ' . $backupResult['filename']
+                        . ' (' . $backupResult['size_kb'] . 'KB, purged ' . $backupResult['purged'] . " old)\n";
+                    if (env('GDRIVE_ENABLED', 'false') === 'true') {
+                        $gResult = backupToGDrive($db);
+                        if ($gResult['success']) {
+                            echo '[' . date('Y-m-d H:i:s') . '] Backup GDrive: OK'
+                                . ' (purged remote: ' . ($gResult['purged_remote'] ?? 0) . ")\n";
+                        } else {
+                            echo '[' . date('Y-m-d H:i:s') . '] Backup GDrive warning: ' . ($gResult['error'] ?? 'unknown') . "\n";
+                        }
+                    }
+                } else {
+                    echo '[' . date('Y-m-d H:i:s') . '] Backup warning: ' . ($backupResult['error'] ?? 'unknown') . "\n";
+                }
+            }
+        } catch (Throwable $be) {
+            echo '[' . date('Y-m-d H:i:s') . '] Backup error: ' . $be->getMessage() . "\n";
+        }
+    }
+
 } catch (Throwable $e) {
-    echo '[' . date('Y-m-d H:i:s') . '] ERROR: ' . $e->getMessage() . "\n";
+    $msg = $e->getMessage();
+    echo '[' . date('Y-m-d H:i:s') . '] ERROR: ' . $msg . "\n";
+    // Report to GitHub Issues (uses the same _phpErrorReport from index.php)
+    _phpErrorReport($msg, $e->getFile(), $e->getLine(), $e->getTraceAsString(), get_class($e));
     exit(1);
 }
+
+// ── Home Assistant: expiry alerts ─────────────────────────────────────────────
+// Fire one HA webhook per expiring item (once per day guard via a simple flag file).
+if (env('HA_ENABLED', 'false') === 'true' && env('HA_WEBHOOK_ID', '') !== '') {
+    try {
+        $haFlagFile = __DIR__ . '/../data/ha_expiry_notified_' . date('Y-m-d') . '.json';
+        if (!file_exists($haFlagFile)) {
+            $expiryDays = max(1, (int)env('HA_EXPIRY_DAYS', '3'));
+            $expiringItems = $db->query(
+                "SELECT p.id AS product_id, i.id AS inventory_id,
+                        p.name, p.brand, p.category, p.unit, p.default_quantity, p.package_unit,
+                        i.quantity, i.location, i.expiry_date, i.opened_at, i.vacuum_sealed
+                 FROM inventory i JOIN products p ON i.product_id = p.id
+                 WHERE i.quantity > 0 AND i.expiry_date IS NOT NULL
+                   AND i.expiry_date BETWEEN date('now') AND date('now', '+{$expiryDays} days')
+                 ORDER BY i.expiry_date ASC LIMIT 20"
+            )->fetchAll(PDO::FETCH_ASSOC);
+
+            $expiredItems = $db->query(
+                "SELECT p.id AS product_id, i.id AS inventory_id,
+                        p.name, p.brand, p.category, p.unit, p.default_quantity, p.package_unit,
+                        i.quantity, i.location, i.expiry_date, i.opened_at, i.vacuum_sealed
+                 FROM inventory i JOIN products p ON i.product_id = p.id
+                 WHERE i.quantity > 0 AND i.expiry_date IS NOT NULL
+                   AND i.expiry_date < date('now')
+                 ORDER BY i.expiry_date ASC LIMIT 10"
+            )->fetchAll(PDO::FETCH_ASSOC);
+
+            // Normalise rows to full product format
+            if (!function_exists('_haFormatProduct')) {
+                function _haFormatProduct(array $row): array {
+                    $daysRemaining = null;
+                    if (!empty($row['expiry_date'])) {
+                        $diff = (new DateTime(date('Y-m-d')))->diff(new DateTime($row['expiry_date']));
+                        $daysRemaining = (int)$diff->format('%r%a');
+                    }
+                    return [
+                        'product_id'       => (int)($row['product_id'] ?? 0),
+                        'inventory_id'     => (int)($row['inventory_id'] ?? 0),
+                        'name'             => $row['name'],
+                        'brand'            => $row['brand'] ?? null,
+                        'category'         => $row['category'] ?? null,
+                        'quantity'         => (float)($row['quantity'] ?? 0),
+                        'unit'             => $row['unit'] ?? '',
+                        'default_quantity' => (float)($row['default_quantity'] ?? 0),
+                        'package_unit'     => $row['package_unit'] ?? null,
+                        'location'         => $row['location'] ?? null,
+                        'expiry_date'      => $row['expiry_date'] ?? null,
+                        'days_remaining'   => $daysRemaining,
+                        'opened_at'        => $row['opened_at'] ?? null,
+                        'vacuum_sealed'    => !empty($row['vacuum_sealed']),
+                    ];
+                }
+            }
+            $expiringItems = array_map('_haFormatProduct', $expiringItems);
+            $expiredItems  = array_map('_haFormatProduct', $expiredItems);
+
+            if (!empty($expiringItems)) {
+                $names = implode(', ', array_column($expiringItems, 'name'));
+                _fireHaWebhook('expiry_alert', [
+                    'count'    => count($expiringItems),
+                    'items'    => $expiringItems,
+                    'type'     => 'expiring_soon',
+                    'days'     => $expiryDays,
+                    'summary'  => $names,
+                ]);
+                // Also send HA notification if service configured
+                if (env('HA_NOTIFY_SERVICE', '') !== '') {
+                    $msg = count($expiringItems) . ' product(s) expiring within ' . $expiryDays . ' days: ' . $names;
+                    _sendHaNotify($msg, ['expiring_items' => $expiringItems]);
+                }
+                echo '[' . date('Y-m-d H:i:s') . '] HA expiry_alert fired: ' . count($expiringItems) . " items\n";
+            }
+
+            if (!empty($expiredItems)) {
+                $expNames = implode(', ', array_column($expiredItems, 'name'));
+                _fireHaWebhook('expiry_alert', [
+                    'count'   => count($expiredItems),
+                    'items'   => $expiredItems,
+                    'type'    => 'expired',
+                    'summary' => $expNames,
+                ]);
+                echo '[' . date('Y-m-d H:i:s') . '] HA expired fired: ' . count($expiredItems) . " items\n";
+            }
+
+            // Mark as done for today
+            file_put_contents($haFlagFile, json_encode(['ts' => time(), 'expiring' => count($expiringItems ?? []), 'expired' => count($expiredItems ?? [])]));
+            // Clean up old flag files (keep last 7 days)
+            foreach (glob(__DIR__ . '/../data/ha_expiry_notified_*.json') as $oldFlag) {
+                $flagDate = str_replace([__DIR__ . '/../data/ha_expiry_notified_', '.json'], '', $oldFlag);
+                if ($flagDate < date('Y-m-d', strtotime('-7 days'))) @unlink($oldFlag);
+            }
+        }
+    } catch (Throwable $haE) {
+        echo '[' . date('Y-m-d H:i:s') . '] HA expiry hook warning: ' . $haE->getMessage() . "\n";
+    }
+}
+
+// ── Avahi/mDNS discovery registration ─────────────────────────────────────────
+// If avahi-daemon is running on this host, register the _evershelf._tcp service
+// so that Home Assistant can auto-discover this instance via Zeroconf.
+if (function_exists('shell_exec')) {
+    try {
+        $avahiService = '/etc/avahi/services/evershelf.xml';
+        // Only create/update if avahi-daemon is installed and the file doesn't exist yet
+        if (!file_exists($avahiService) && (shell_exec('which avahi-daemon 2>/dev/null') || shell_exec('which avahi-publish 2>/dev/null'))) {
+            $template = __DIR__ . '/../docker/avahi-evershelf.xml';
+            if (file_exists($template)) {
+                $xml = file_get_contents($template);
+                @file_put_contents($avahiService, $xml);
+                echo '[' . date('Y-m-d H:i:s') . '] Avahi mDNS service registered at ' . $avahiService . "\n";
+            }
+        }
+    } catch (Throwable $avahiE) {
+        // Non-fatal: avahi not available
+    }
+}

api/database.php

@@ -1,21 +1,66 @@
 <?php
 /**
- * Dispensa Manager - Database initialization, schema, and migrations.
+ * EverShelf - Database initialization, schema, and migrations.
  * Uses SQLite with WAL journal mode for concurrent read/write performance.
  *
- * @author Stimpfl Daniel <dadaloop82@gmail.com>
+ * @author Stimpfl Daniel <evershelfproject@gmail.com>
  * @license MIT
  */
 
-define('DB_PATH', __DIR__ . '/../data/dispensa.db');
+define('DB_PATH', __DIR__ . '/../data/evershelf.db');
+
+/**
+ * Ensure the data directory exists and is writable by the web-server user.
+ * This is needed when a Docker volume is first mounted: the image's chown
+ * step is applied to the image layer, but a fresh named volume starts empty
+ * (owned by root), making SQLite's PDO::__construct fail with HY000[14].
+ */
+function _ensureDataDir(): void {
+    $dir = dirname(DB_PATH);
+    if (!is_dir($dir)) {
+        if (!mkdir($dir, 0775, true) && !is_dir($dir)) {
+            throw new \RuntimeException("Cannot create data directory: $dir");
+        }
+    }
+    if (!is_writable($dir)) {
+        // Try to fix permissions (only works when running as root, e.g. first boot)
+        @chmod($dir, 0775);
+        if (!is_writable($dir)) {
+            throw new \RuntimeException(
+                "Data directory is not writable: $dir — run: chown -R www-data:www-data $dir"
+            );
+        }
+    }
+    // Ensure backups sub-directory exists too
+    $backups = $dir . '/backups';
+    if (!is_dir($backups)) {
+        @mkdir($backups, 0775, true);
+    }
+}
 
 function getDB(): PDO {
+    _ensureDataDir();
+    // logger.php is required by index.php before getDB() is called.
+    // In cron context it may not be loaded yet — guard with class_exists.
+    $useLogging = class_exists('LoggingPDO', false);
     $isNew = !file_exists(DB_PATH);
-    $db = new PDO('sqlite:' . DB_PATH);
+    $db = $useLogging
+        ? new LoggingPDO('sqlite:' . DB_PATH)
+        : new PDO('sqlite:' . DB_PATH);
     $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
+    // Set a busy timeout to prevent "database is locked" errors under high concurrency.
+    // This gives SQLite up to 5 seconds to acquire a lock before throwing an exception.
+    $db->setAttribute(PDO::ATTR_TIMEOUT, 5); // PDO::ATTR_TIMEOUT is in seconds for MySQL, but not directly for SQLite.
+                                             // For SQLite, we use PRAGMA busy_timeout.
+    $db->exec('PRAGMA journal_mode = WAL;');
+    $db->exec('PRAGMA busy_timeout = 5000;'); // 5000 milliseconds = 5 seconds
+
     $db->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_ASSOC);
     $db->exec("PRAGMA journal_mode=WAL");
     $db->exec("PRAGMA foreign_keys=ON");
+    $db->exec("PRAGMA synchronous=NORMAL");    // faster writes, still safe with WAL
+    $db->exec("PRAGMA cache_size=-8000");      // ~8 MB page cache (was 2 MB)
+    $db->exec("PRAGMA temp_store=MEMORY");     // temp tables in RAM
     
     if ($isNew) {
         initializeDB($db);
@@ -39,6 +84,7 @@ function initializeDB(PDO $db): void {
             unit TEXT DEFAULT 'pz',
             default_quantity REAL DEFAULT 1,
             notes TEXT DEFAULT '',
+            shopping_name TEXT DEFAULT '',
             created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
             updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
         );
@@ -61,6 +107,7 @@ function initializeDB(PDO $db): void {
             quantity REAL NOT NULL,
             location TEXT NOT NULL DEFAULT 'dispensa',
             notes TEXT DEFAULT '',
+            undone INTEGER DEFAULT 0,
             created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
             FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE CASCADE
         );
@@ -70,15 +117,35 @@ function initializeDB(PDO $db): void {
         CREATE INDEX IF NOT EXISTS idx_inventory_location ON inventory(location);
         CREATE INDEX IF NOT EXISTS idx_transactions_product ON transactions(product_id);
         CREATE INDEX IF NOT EXISTS idx_transactions_date ON transactions(created_at);
+        -- Composite indexes for hot queries
+        -- getStats(): WHERE type IN (...) AND created_at >= ...
+        CREATE INDEX IF NOT EXISTS idx_transactions_type_date ON transactions(type, created_at);
+        -- smartShopping(): GROUP BY product_id filtering on type+undone
+        CREATE INDEX IF NOT EXISTS idx_transactions_pid_type_undone ON transactions(product_id, type, undone);
     ");
 }
 
 function migrateDB(PDO $db): void {
+    // Guard: if core tables don't exist yet (e.g. DB file present but empty / partial init),
+    // run initializeDB first so all tables are created, then return — no ALTER TABLE needed.
+    $productsExists = $db->query(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='products'"
+    )->fetchColumn();
+    if (!$productsExists) {
+        initializeDB($db);
+        return;
+    }
+
     // Add package_unit column if missing
     $cols = $db->query("PRAGMA table_info(products)")->fetchAll();
     $colNames = array_column($cols, 'name');
     if (!in_array('package_unit', $colNames)) {
-        $db->exec("ALTER TABLE products ADD COLUMN package_unit TEXT DEFAULT ''");
+        try { $db->exec("ALTER TABLE products ADD COLUMN package_unit TEXT DEFAULT ''"); }
+        catch (PDOException $e) { if (strpos($e->getMessage(), 'duplicate column') === false) throw $e; }
+    }
+    if (!in_array('shopping_name', $colNames)) {
+        try { $db->exec("ALTER TABLE products ADD COLUMN shopping_name TEXT DEFAULT ''"); }
+        catch (PDOException $e) { if (strpos($e->getMessage(), 'duplicate column') === false) throw $e; }
     }
 
     // Migrate transactions CHECK constraint to allow 'waste' type
@@ -93,14 +160,19 @@ function migrateDB(PDO $db): void {
                 quantity REAL NOT NULL,
                 location TEXT NOT NULL DEFAULT 'dispensa',
                 notes TEXT DEFAULT '',
+                undone INTEGER DEFAULT 0,
                 created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
                 FOREIGN KEY (product_id) REFERENCES products(id) ON DELETE CASCADE
             )
         ");
-        $db->exec("INSERT INTO transactions SELECT * FROM transactions_old");
+        // Insert with explicit columns: transactions_old may lack 'undone' (pre-v1.7.x DB)
+        $db->exec("INSERT INTO transactions (id, product_id, type, quantity, location, notes, created_at)
+                   SELECT id, product_id, type, quantity, location, notes, created_at FROM transactions_old");
         $db->exec("DROP TABLE transactions_old");
         $db->exec("CREATE INDEX IF NOT EXISTS idx_transactions_product ON transactions(product_id)");
         $db->exec("CREATE INDEX IF NOT EXISTS idx_transactions_date ON transactions(created_at)");
+        $db->exec("CREATE INDEX IF NOT EXISTS idx_transactions_type_date ON transactions(type, created_at)");
+        $db->exec("CREATE INDEX IF NOT EXISTS idx_transactions_pid_type_undone ON transactions(product_id, type, undone)");
     }
 
     // --- New shared tables ---
@@ -155,25 +227,83 @@ function migrateDB(PDO $db): void {
     // Add opened_at column to inventory if missing
     if (!in_array('opened_at', $invColNames)) {
         $db->exec("ALTER TABLE inventory ADD COLUMN opened_at DATETIME DEFAULT NULL");
-        // Backfill: detect already-opened items and set opened_at + recalculate expiry
+        // Backfill: detect already-opened fridge items and set opened_at.
+        // Only frigo items — pantry/freezer fractional quantities don't imply opened.
         backfillOpenedItems($db);
     }
 
+    // Migration: undo incorrect backfill for non-frigo items.
+    // The original backfill also tagged dispensa/freezer items as opened, which overwrote
+    // their manufacturer expiry_date with a short estimated value.  Clear opened_at so they
+    // return to the sealed section; clear expiry_date so users can re-enter the real date.
+    $migDone = $db->query("SELECT value FROM app_settings WHERE key = 'migration_fix_nonfrigo_opened_v1'")->fetchColumn();
+    if (!$migDone) {
+        $db->exec("UPDATE inventory SET opened_at = NULL, expiry_date = NULL
+                   WHERE location NOT IN ('frigo') AND opened_at IS NOT NULL");
+        $db->exec("INSERT OR REPLACE INTO app_settings (key, value)
+                   VALUES ('migration_fix_nonfrigo_opened_v1', '1')");
+    }
+
     // Migration v2: recalculate sealed fridge item expiry (fridge extends shelf life)
     $migrated = $db->query("SELECT value FROM app_settings WHERE key = 'migration_fridge_expiry_v1'")->fetchColumn();
     if (!$migrated) {
         recalcSealedFridgeExpiry($db);
         $db->exec("INSERT OR REPLACE INTO app_settings (key, value) VALUES ('migration_fridge_expiry_v1', '1')");
     }
+
+    // Add undone column to transactions if missing
+    $txCols = $db->query("PRAGMA table_info(transactions)")->fetchAll();
+    $txColNames = array_column($txCols, 'name');
+    if (!in_array('undone', $txColNames)) {
+        $db->exec("ALTER TABLE transactions ADD COLUMN undone INTEGER DEFAULT 0");
+    }
+
+    // Ensure composite indexes exist (added in v1.7.5 for performance)
+    $db->exec("CREATE INDEX IF NOT EXISTS idx_transactions_type_date ON transactions(type, created_at)");
+    $db->exec("CREATE INDEX IF NOT EXISTS idx_transactions_pid_type_undone ON transactions(product_id, type, undone)");
+
+    // Internal shopping list table (v1.8.0) — used when SHOPPING_MODE=internal
+    $shopTables = $db->query("SELECT name FROM sqlite_master WHERE type='table' AND name='shopping_list'")->fetchAll();
+    if (empty($shopTables)) {
+        $db->exec("
+            CREATE TABLE shopping_list (
+                id            INTEGER PRIMARY KEY AUTOINCREMENT,
+                name          TEXT NOT NULL,
+                raw_name      TEXT NOT NULL DEFAULT '',
+                specification TEXT NOT NULL DEFAULT '',
+                added_at      INTEGER DEFAULT (strftime('%s','now')),
+                sort_order    INTEGER DEFAULT 0
+            )
+        ");
+        $db->exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_shopping_list_name ON shopping_list(lower(name))");
+    }
+
+    // Add is_favorite column to recipes if missing (#124)
+    $recCols = array_column($db->query("PRAGMA table_info(recipes)")->fetchAll(), 'name');
+    if (!in_array('is_favorite', $recCols)) {
+        try { $db->exec("ALTER TABLE recipes ADD COLUMN is_favorite INTEGER NOT NULL DEFAULT 0"); }
+        catch (PDOException $e) { if (strpos($e->getMessage(), 'duplicate column') === false) throw $e; }
+    }
+
+    // Add nutriments_json column to products if missing (#118)
+    $prodCols2 = array_column($db->query("PRAGMA table_info(products)")->fetchAll(), 'name');
+    if (!in_array('nutriments_json', $prodCols2)) {
+        try { $db->exec("ALTER TABLE products ADD COLUMN nutriments_json TEXT DEFAULT NULL"); }
+        catch (PDOException $e) { if (strpos($e->getMessage(), 'duplicate column') === false) throw $e; }
+    }
 }
 
 /**
- * Backfill opened_at for existing inventory items that appear to be opened.
+ * Backfill opened_at for frigo items that appear to be opened.
  * An item is considered opened if:
  *  - conf unit with fractional quantity
  *  - weight/volume unit (g,kg,ml,l) with quantity < default_quantity
  * Uses updated_at as the approximate opened_at date.
- * Recalculates expiry_date based on opened shelf life from opened_at.
+ * Does NOT overwrite expiry_date — the manufacturer date is preserved;
+ * getStats computes opened expiry on-the-fly from opened_at.
+ *
+ * Only frigo items: pantry/freezer fractional quantities are normal
+ * (e.g. 3 of 6 UHT milks) and do not indicate a food-safety expiry change.
  */
 function backfillOpenedItems(PDO $db): void {
     $stmt = $db->query("
@@ -181,7 +311,7 @@ function backfillOpenedItems(PDO $db): void {
                p.name, p.category, p.unit, p.default_quantity
         FROM inventory i
         JOIN products p ON i.product_id = p.id
-        WHERE i.quantity > 0
+        WHERE i.quantity > 0 AND i.location = 'frigo'
     ");
     $rows = $stmt->fetchAll();
 
@@ -200,15 +330,9 @@ function backfillOpenedItems(PDO $db): void {
 
         if (!$isOpened) continue;
 
-        $openedAt = $row['updated_at'];
-        $openedDays = estimateOpenedExpiryDaysPHP($row['name'], $row['category'], $row['location']);
-        if ($row['vacuum_sealed']) $openedDays = (int)round($openedDays * 1.5);
-
-        // Calculate new expiry from opened_at
-        $newExpiry = date('Y-m-d', strtotime($openedAt . " +{$openedDays} days"));
-
-        $upd = $db->prepare("UPDATE inventory SET opened_at = ?, expiry_date = ? WHERE id = ?");
-        $upd->execute([$openedAt, $newExpiry, $row['id']]);
+        // Only set opened_at — do NOT touch expiry_date (manufacturer date is preserved)
+        $upd = $db->prepare("UPDATE inventory SET opened_at = ? WHERE id = ? AND opened_at IS NULL");
+        $upd->execute([$row['updated_at'], $row['id']]);
     }
 }
 
@@ -245,8 +369,37 @@ function estimateOpenedExpiryDaysPHP(string $name, string $category, string $loc
         if (preg_match('/\b(lenticchie|ceci|fagioli|piselli)\b/', $n) && !preg_match('/\b(cotto|vapore|scatola)\b/', $n)) return 365;
     }
 
-    // ── D: Freezer ───────────────────────────────────────────────────────
-    if ($loc === 'freezer') return 90;
+    // ── D: Freezer — per-product estimates (USDA/EFSA guidelines) ───────
+    if ($loc === 'freezer') {
+        // Bread, pastry, dough
+        if (preg_match('/\b(pane|bread|toast|brioche|ciabatta|baguette|focaccia|pizza\s*base|impasto)\b/', $n)) return 90;
+        if (preg_match('/\b(pasta\s+fresca|gnocchi|ravioli|tortellini|lasagna\s+fresca)\b/', $n)) return 60;
+        if (preg_match('/\b(croissant|cornetto|pasticceria|dolce|torta|plumcake|muffin|biscotti)\b/', $n)) return 90;
+        // Ice cream / sorbet
+        if (preg_match('/\b(gelato|sorbetto|ice\s*cream|ghiacciolo)\b/', $n)) return 365;
+        // Fish & seafood — shorter (3–6 months)
+        if (preg_match('/\b(salmone|trota|spigola|orata|tonno|merluzzo|baccalà|nasello|sgombro|pesce|calamaro|gambero|gamberetti|polpo|seppia|cozza|vongola|frutti\s+di\s+mare|seafood)\b/', $n)) return 120;
+        // Poultry — 9 months
+        if (preg_match('/\b(pollo|tacchino|anatra|faraona|petto\s+di\s+pollo|coscia|fesa)\b/', $n)) return 270;
+        // Red meat whole cuts — 12 months
+        if (preg_match('/\b(manzo|vitello|agnello|maiale|lonza|costata|arrosto|fesa|fettina|bistecca)\b/', $n)) return 365;
+        // Ground meat / mince — 3–4 months
+        if (preg_match('/\b(macinato|macinata|hamburger|polpette|ragù)\b/', $n)) return 120;
+        // Sausage / cured meat frozen
+        if (preg_match('/\b(salsiccia|würstel|wurstel|salame|pancetta|speck|prosciutto)\b/', $n)) return 60;
+        // Dairy
+        if (preg_match('/\b(burro)\b/', $n)) return 270;
+        if (preg_match('/\b(panna)\b/', $n)) return 90;
+        if (preg_match('/\b(formaggio|mozzarella|ricotta)\b/', $n)) return 90;
+        // Vegetables (blanched/processed for freezer)
+        if (preg_match('/\b(piselli|fagioli|fagiolini|spinaci|broccoli|cavolfiore|carote|mais|edamame|verdure\s+miste|minestrone)\b/', $n)) return 270;
+        // Fruits
+        if (preg_match('/\b(fragole|lamponi|mirtilli|more|ciliegia|frutta\s+mista|frutta)\b/', $n)) return 270;
+        // Stocks, soups, sauces (already cooked)
+        if (preg_match('/\b(brodo|zuppa|minestra|sugo|salsa|passata)\b/', $n)) return 180;
+        // Generic freezer fallback
+        return 180;
+    }
 
     // ── E: Pantry/dispensa — specific products then generic fallback ─────
     if ($loc !== 'frigo') {
@@ -257,18 +410,31 @@ function estimateOpenedExpiryDaysPHP(string $name, string $category, string $loc
         if (preg_match('/\bpane\b/', $n)) return 4;
         // Specific jarred tomato sauce in pantry (opened, not refrigerated)
         if (preg_match('/salsa\s+di\s+(pomodoro|pronta)/', $n)) return 5;
-        return 60; // generic pantry fallback (was 30, doubled)
+        // Dairy opened outside fridge: bad very quickly at room temperature
+        if (preg_match('/\bpanna\b/', $n)) return 3;
+        if (preg_match('/\b(yogurt|yaourt|yoghurt)\b/', $n)) return 2;
+        if (preg_match('/\blatte\b/', $n)) return 1;
+        if (preg_match('/\bformaggio\b/', $n)) return 2;
+        // Root vegetables / tubers in pantry: sfusi in un sacchetto, durano 3-5 settimane
+        if (preg_match('/\b(patata|patate|tubero)\b/', $n)) return 30;
+        if (preg_match('/\b(cipolla|cipolle|aglio|scalogno|porro)\b/', $n)) return 30;
+        if (preg_match('/\b(carota|carote)\b/', $n)) return 14;
+        return 60; // generic pantry fallback
     }
 
     // ── F: Fridge — short-life perishables ──────────────────────────────
     if (preg_match('/latte\s+(fresco|intero|parzial|scremato)/', $n)) return 3;
-    if (preg_match('/latte\s+(uht|a\s+lunga)/', $n)) return 5;
-    if (preg_match('/\blatte\b/', $n)) return 4;
-    if (preg_match('/\byogurt\b/', $n)) return 5;
+    if (preg_match('/latte\s+(uht|a\s+lunga)/', $n)) return 7;
+    // Long-life mountain/brand milks stored in pantry before use (UHT)
+    if (preg_match('/latte.*(montagna|alta\s+qual|parmalat|granarolo|esselunga|conservaz|microfiltrat)/i', $n)) return 7;
+    if (preg_match('/\blatte\b/', $n)) return 7; // generic: default to UHT (most common in IT households)
+    if (preg_match('/\b(yogurt|yaourt|yoghurt)\b/', $n)) return 5;
     if (preg_match('/mozzarella|burrata|stracciatella/', $n)) return 3;
     if (preg_match('/philadelphia|spalmabile/', $n)) return 7;
+    // Specific hard cheeses that contain 'fresco' in their commercial name (e.g. Asiago fresco)
+    // must be matched BEFORE the generic 'formaggio fresco' catch-all
+    if (preg_match('/parmigiano|grana|pecorino|provolone|asiago|fontina|emmental|gruyere|scamorza|groviera/', $n)) return 28;
     if (preg_match('/formaggio.*(fresco|ricotta|mascarpone|stracchino|crescenza)/', $n)) return 5;
-    if (preg_match('/parmigiano|grana|pecorino|provolone/', $n)) return 21;
     if (preg_match('/formaggio/', $n)) return 10;
     if (preg_match('/\bburro\b/', $n)) return 30;
     if (preg_match('/\bpanna\b/', $n)) return 4;
@@ -277,25 +443,34 @@ function estimateOpenedExpiryDaysPHP(string $name, string $category, string $loc
     if (preg_match('/\b(pollo|tacchino|maiale|manzo|vitello|agnello)\b/', $n)) return 2;
     if (preg_match('/salmone|tonno\s+fresco|pesce(?!\s+in)/', $n)) return 2;
     if (preg_match('/\b(passata|pelati|polpa|sugo|salsa\s+di\s+pomodoro)\b/', $n)) return 5;
-    if (preg_match('/insalata|rucola|spinaci|lattuga|crescione|germogli/', $n)) return 2;
+    if (preg_match('/insalata|rucola|spinaci|lattuga|crescione|germogli/', $n)) return 4;
     if (preg_match('/\b(succo|spremuta)\b/', $n)) return 3;
     if (preg_match('/\b(birra|beer)\b/', $n)) return 3;
     if (preg_match('/\bvino\b/', $n)) return 5;
     if (preg_match('/tonno\s+in\s+scatola|tonno\s+rio|sgombro\s+in/', $n)) return 4;
-    // Fruit opened/cut in fridge — much shorter than sealed
-    if (preg_match('/\bavocado\b/', $n)) return 2;
-    if (preg_match('/\b(banana|banane|fragola|lampone|pesca|albicocca|ciliegia|mango|papaya)\b/', $n)) return 2;
-    if (preg_match('/\b(mela|pera|nettarina|prugna|kiwi|ananas|uva|melone|anguria)\b/', $n)) return 3;
-    if (preg_match('/\b(arancia|mandarino|pompelmo|clementina|limone)\b/', $n)) return 3; // cut citrus
-    // Vegetables opened/cut in fridge
-    if (preg_match('/\b(zucchina|zucchine|melanzana|pomodor)\b/', $n)) return 3;
-    if (preg_match('/\b(peperone|peperoni)\b/', $n)) return 3;
-    if (preg_match('/\b(broccolo|broccoli|cavolfiore|cavolo)\b/', $n)) return 3;
-    if (preg_match('/\bsedano\b|\bfinocchio\b/', $n)) return 3;
-    if (preg_match('/\b(cipolla|cipolle|cipollotto|scalogno|porro)\b/', $n)) return 4;
-    if (preg_match('/\b(carota|carote)\b/', $n)) return 5;
-    if (preg_match('/\b(patata|patate|tubero)\b/', $n)) return 3; // cooked/cut potato
-    if (preg_match('/\baglio\b/', $n)) return 10;
+    // Fruit in fridge (opened pack, not necessarily cut)
+    if (preg_match('/\bavocado\b/', $n)) return 3;
+    if (preg_match('/\b(fragola|fragole|lampone|lamponi|mirtillo|mirtilli|mora|more)\b/', $n)) return 4;
+    if (preg_match('/\b(banana|banane|pesca|pesche|albicocca|albicocche|ciliegia|ciliegie|mango|papaya)\b/', $n)) return 4;
+    if (preg_match('/\b(mela|mele|pera|pere|nettarina|prugna|kiwi|ananas|uva|melone|anguria)\b/', $n)) return 5;
+    if (preg_match('/\b(arancia|arance|mandarino|mandarini|pompelmo|clementina|limone|limoni)\b/', $n)) return 7;
+    // Vegetables in fridge (opened pack)
+    if (preg_match('/\b(zucchina|zucchine|melanzana|melanzane|pomodor)\b/', $n)) return 5;
+    if (preg_match('/\b(peperone|peperoni)\b/', $n)) return 5;
+    if (preg_match('/\b(broccolo|broccoli|cavolfiore|cavolo)\b/', $n)) return 4;
+    if (preg_match('/\bsedano\b|\bfinocchio\b/', $n)) return 5;
+    if (preg_match('/\b(cipolla|cipolle|cipollotto|scalogno|porro)\b/', $n)) return 6;
+    if (preg_match('/\b(carota|carote)\b/', $n)) return 7;
+    if (preg_match('/\b(patata|patate|tubero)\b/', $n)) return 4;
+    if (preg_match('/\baglio\b/', $n)) return 14;
+
+    // ── F.extra: Bread in fridge (opened) ──────────────────────────────────
+    // Thin flatbreads (piadina, crescia, tigella) get mold very quickly
+    if (preg_match('/\b(piadina|piadelle?|crescia|tigella)\b/', $n)) return 2;
+    // Packaged sliced bread — preservatives help a bit
+    if (preg_match('/\b(bauletto|pancarrè|pan\s+carr|tramezzin)\b/', $n)) return 4;
+    // Generic bread / sandwich bread in fridge
+    if (preg_match('/\bpane\b/', $cat)) return 3;
 
     // ── G: Fridge condiments — medium shelf-life ─────────────────────────
     if (preg_match('/maionese|mayo|mayon/', $n)) return 90;
@@ -303,7 +478,7 @@ function estimateOpenedExpiryDaysPHP(string $name, string $category, string $loc
     if (preg_match('/\b(senape|mustard)\b/', $n)) return 90;
     if (preg_match('/salsa\s+di\s+soia|soy\s*sauce/', $n)) return 90;
     if (preg_match('/\b(tabasco|worcestershire|sriracha)\b/', $n)) return 180;
-    if (preg_match('/confettura|marmellata/', $n)) return 60;
+    if (preg_match('/confettura|marmellata/', $n)) return 180;
     if (preg_match('/nutella|cioccolat/', $n)) return 60;
 
     // ── H: Category fallbacks ────────────────────────────────────────────
@@ -336,7 +511,7 @@ function estimateSealedExpiryDaysPHP(string $name, string $category, string $loc
     elseif (preg_match('/yogurt/', $n)) $days = 21;
     elseif (preg_match('/mozzarella|burrata|stracciatella/', $n)) $days = 5;
     elseif (preg_match('/formaggio\s+(fresco|ricotta|mascarpone|stracchino|crescenza)/', $n)) $days = 10;
-    elseif (preg_match('/parmigiano|grana|pecorino|provolone/', $n)) $days = 60;
+    elseif (preg_match('/parmigiano|grana|pecorino|provolone|asiago|fontina|emmental|gruyere|scamorza|groviera/', $n)) $days = 60;
     elseif (preg_match('/burro/', $n)) $days = 60;
     elseif (preg_match('/panna/', $n)) $days = 14;
     elseif (preg_match('/prosciutto\s+cotto|mortadella|wurstel/', $n)) $days = 7;
@@ -361,7 +536,7 @@ function estimateSealedExpiryDaysPHP(string $name, string $category, string $loc
     elseif (preg_match('/carota|carote|zucchina|zucchine|peperoni|melanzane/', $n)) $days = 7;
     elseif (preg_match('/broccoli|cavolfiore|cavolo|spinaci|bietola/', $n)) $days = 5;
     elseif (preg_match('/cipolla|cipolle/', $n)) $days = 10;
-    elseif (preg_match('/patata|patate/', $n)) $days = 14;
+    elseif (preg_match('/patata|patate/', $n)) $days = 30; // whole tubers in a bag, pantry: 3-5 weeks
     elseif (preg_match('/biscott|cracker|grissini|fette\s+biscott/', $n)) $days = 180;
     elseif (preg_match('/nutella|marmellata|miele/', $n)) $days = 365;
     elseif (preg_match('/passata|pelati|pomodor/', $n)) $days = 730;

api/lib/constants.php

@@ -0,0 +1,22 @@
+<?php
+/**
+ * EverShelf — shared path constants.
+ */
+
+define('EVERSHELF_ROOT', dirname(__DIR__, 2));
+define('GH_REPO', 'dadaloop82/EverShelf');
+define('PRICE_CACHE_PATH',         EVERSHELF_ROOT . '/data/shopping_price_cache.json');
+define('CATEGORY_CACHE_PATH',      EVERSHELF_ROOT . '/data/category_ai_cache.json');
+define('SHELF_CACHE_PATH',         EVERSHELF_ROOT . '/data/opened_shelf_cache.json');
+define('FOODFACTS_CACHE_PATH',     EVERSHELF_ROOT . '/data/food_facts_cache.json');
+define('SHOPPING_NAME_CACHE_PATH', EVERSHELF_ROOT . '/data/shopping_name_cache.json');
+define('BRING_TOKEN_PATH',         EVERSHELF_ROOT . '/data/bring_token.json');
+define('AI_USAGE_PATH',            EVERSHELF_ROOT . '/data/ai_usage.json');
+define('BACKUP_DIR',               EVERSHELF_ROOT . '/data/backups');
+define('BACKUP_LAST_TS_PATH',      EVERSHELF_ROOT . '/data/backup_last_ts.json');
+define('CRON_LOG_PATH',            EVERSHELF_ROOT . '/data/cron.log');
+
+define('GEMINI_COST_25F_IN',  (float)(getenv('GEMINI_COST_25F_IN')  ?: 0.15));
+define('GEMINI_COST_25F_OUT', (float)(getenv('GEMINI_COST_25F_OUT') ?: 0.60));
+define('GEMINI_COST_20F_IN',  (float)(getenv('GEMINI_COST_20F_IN')  ?: 0.10));
+define('GEMINI_COST_20F_OUT', (float)(getenv('GEMINI_COST_20F_OUT') ?: 0.40));

api/lib/cron_log.php

@@ -0,0 +1,28 @@
+<?php
+/**
+ * Rotate data/cron.log — keep last N MB / lines.
+ */
+
+require_once __DIR__ . '/constants.php';
+
+function evershelfRotateCronLog(?int $maxBytes = null, int $keepRotated = 3): void {
+    $path = CRON_LOG_PATH;
+    if (!file_exists($path)) {
+        return;
+    }
+    $maxBytes = $maxBytes ?? max(65536, (int)env('CRON_LOG_MAX_BYTES', '524288'));
+    $size = filesize($path);
+    if ($size === false || $size <= $maxBytes) {
+        return;
+    }
+    for ($i = $keepRotated; $i >= 1; $i--) {
+        $from = ($i === 1) ? $path : $path . '.' . ($i - 1);
+        $to   = $path . '.' . $i;
+        if ($i === $keepRotated && file_exists($to)) {
+            @unlink($to);
+        }
+        if (file_exists($from)) {
+            @rename($from, $to);
+        }
+    }
+}

api/lib/env.php

@@ -0,0 +1,35 @@
+<?php
+/**
+ * EverShelf — environment variable loader (.env).
+ */
+
+function loadEnv(): array {
+    static $cache = null;
+    if ($cache !== null) {
+        return $cache;
+    }
+    $envFile = dirname(__DIR__, 2) . '/.env';
+    $cache = [];
+    if (file_exists($envFile)) {
+        $lines = file($envFile, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
+        foreach ($lines as $line) {
+            if (strpos($line, '#') === 0 || strpos($line, '=') === false) {
+                continue;
+            }
+            [$key, $val] = explode('=', $line, 2);
+            $cache[trim($key)] = trim($val);
+        }
+    }
+    return $cache;
+}
+
+function env(string $key, string $default = ''): string {
+    $vars = loadEnv();
+    return $vars[$key] ?? $default;
+}
+
+/** Push a single key into the in-memory env cache (after .env write). */
+function envCacheSet(string $key, string $value): void {
+    loadEnv();
+    // Force reload on next call — callers should use loadEnv() return for batch updates
+}

api/lib/github.php

@@ -0,0 +1,69 @@
+<?php
+/**
+ * EverShelf — GitHub issue reporting token (encrypted at rest in .env).
+ *
+ * Configure ONE of:
+ *   GH_ISSUE_TOKEN=ghp_...                    (plain, .env is gitignored)
+ *   GH_ISSUE_TOKEN_ENC=... + GH_ISSUE_TOKEN_KEY=...  (AES-256-GCM, preferred)
+ *
+ * Generate encrypted value: php scripts/encrypt-gh-token.php 'ghp_xxx' 'your-secret-key'
+ */
+
+require_once __DIR__ . '/env.php';
+
+function evershelfDecryptGhToken(string $encB64, string $key): string {
+    $raw = base64_decode($encB64, true);
+    if ($raw === false || strlen($raw) < 28) {
+        return '';
+    }
+    $iv     = substr($raw, 0, 12);
+    $tag    = substr($raw, 12, 16);
+    $cipher = substr($raw, 28);
+    $plain  = openssl_decrypt(
+        $cipher,
+        'aes-256-gcm',
+        hash('sha256', $key, true),
+        OPENSSL_RAW_DATA,
+        $iv,
+        $tag
+    );
+    return ($plain !== false) ? $plain : '';
+}
+
+function evershelfEncryptGhToken(string $plain, string $key): string {
+    $iv = random_bytes(12);
+    $tag = '';
+    $cipher = openssl_encrypt(
+        $plain,
+        'aes-256-gcm',
+        hash('sha256', $key, true),
+        OPENSSL_RAW_DATA,
+        $iv,
+        $tag
+    );
+    return base64_encode($iv . $tag . $cipher);
+}
+
+/** Decode GitHub Issues token at runtime — never stored in source code. */
+function _ghToken(): string {
+    static $token = null;
+    if ($token !== null) {
+        return $token;
+    }
+
+    $plain = env('GH_ISSUE_TOKEN');
+    if ($plain !== '') {
+        $token = $plain;
+        return $token;
+    }
+
+    $enc = env('GH_ISSUE_TOKEN_ENC');
+    $key = env('GH_ISSUE_TOKEN_KEY');
+    if ($enc !== '' && $key !== '') {
+        $token = evershelfDecryptGhToken($enc, $key);
+        return $token;
+    }
+
+    $token = '';
+    return $token;
+}

api/lib/security.php

@@ -0,0 +1,293 @@
+<?php
+/**
+ * EverShelf — authentication, CORS, demo mode, scale gateway allowlist.
+ */
+
+require_once __DIR__ . '/env.php';
+
+/** Effective API token: API_TOKEN takes precedence over legacy SETTINGS_TOKEN. */
+function evershelfEffectiveApiToken(): string {
+    $api = env('API_TOKEN');
+    if ($api !== '') {
+        return $api;
+    }
+    return env('SETTINGS_TOKEN', '');
+}
+
+function evershelfApiTokenRequired(): bool {
+    return evershelfEffectiveApiToken() !== '';
+}
+
+function evershelfGetProvidedApiToken(): string {
+    if (!empty($_SERVER['HTTP_X_API_TOKEN'])) {
+        return (string)$_SERVER['HTTP_X_API_TOKEN'];
+    }
+    if (!empty($_SERVER['HTTP_X_SETTINGS_TOKEN'])) {
+        return (string)$_SERVER['HTTP_X_SETTINGS_TOKEN'];
+    }
+    if (isset($_GET['api_token'])) {
+        return (string)$_GET['api_token'];
+    }
+    // Home Assistant ha-evershelf sends Authorization: Bearer (legacy)
+    $authHeader = $_SERVER['HTTP_AUTHORIZATION']
+        ?? $_SERVER['REDIRECT_HTTP_AUTHORIZATION']
+        ?? '';
+    if (preg_match('/^Bearer\s+(\S+)/i', $authHeader, $m)) {
+        return $m[1];
+    }
+    return evershelfGetProvidedApiTokenFromHeaders();
+}
+
+function evershelfApiTokenValid(): bool {
+    $required = evershelfEffectiveApiToken();
+    if ($required === '') {
+        return true;
+    }
+    $provided = evershelfGetProvidedApiToken();
+    return $provided !== '' && hash_equals($required, $provided);
+}
+
+function evershelfGetProvidedApiTokenFromHeaders(): string {
+    return (string)($_SERVER['HTTP_X_API_TOKEN'] ?? $_SERVER['HTTP_X_SETTINGS_TOKEN'] ?? '');
+}
+
+/** Actions reachable without API token (telemetry + public probes). */
+function evershelfPublicActions(): array {
+    return [
+        'ping',
+        'app_bootstrap',
+        'check_update',
+        'report_error',
+        'report_bug',
+        'client_log',
+        'gdrive_oauth_callback',
+    ];
+}
+
+/** GET actions that mutate state — require auth when token is configured. */
+function evershelfMutatingGetActions(): array {
+    return ['db_cleanup', 'export_inventory'];
+}
+
+function evershelfDestructiveActions(): array {
+    return [
+        'save_settings', 'db_cleanup',
+        'backup_now', 'backup_delete', 'backup_restore',
+        'gdrive_push', 'gdrive_oauth_exchange',
+        'migrate_units',
+    ];
+}
+
+function evershelfActionNeedsAuth(string $action, string $method): bool {
+    if (!evershelfApiTokenRequired()) {
+        return false;
+    }
+    if (in_array($action, evershelfPublicActions(), true)) {
+        return false;
+    }
+    if ($method === 'POST') {
+        return true;
+    }
+    if ($method === 'GET' && in_array($action, evershelfMutatingGetActions(), true)) {
+        return true;
+    }
+    if (in_array($action, ['get_logs', 'gemini_usage', 'get_client_log'], true)) {
+        return true;
+    }
+    if (in_array($action, evershelfDestructiveActions(), true)) {
+        return true;
+    }
+    // Protect all data reads when API token is set
+    return true;
+}
+
+function evershelfRequireApiAuth(string $action, string $method): void {
+    if (!evershelfActionNeedsAuth($action, $method)) {
+        return;
+    }
+    if (evershelfApiTokenValid()) {
+        return;
+    }
+    http_response_code(401);
+    header('Content-Type: application/json; charset=utf-8');
+    echo json_encode([
+        'success'            => false,
+        'error'              => 'unauthorized',
+        'api_token_required' => true,
+    ]);
+    exit;
+}
+
+function evershelfRequireAuthForSensitive(string $action): void {
+    if (!evershelfApiTokenRequired()) {
+        return;
+    }
+    if (evershelfApiTokenValid()) {
+        return;
+    }
+    http_response_code(401);
+    header('Content-Type: application/json; charset=utf-8');
+    echo json_encode(['success' => false, 'error' => 'unauthorized', 'api_token_required' => true]);
+    exit;
+}
+
+function evershelfSendCorsHeaders(): void {
+    $configured = env('CORS_ORIGIN', '');
+    if ($configured === '') {
+        // Same-origin SPA — do not emit wildcard CORS
+        return;
+    }
+    if ($configured === '*') {
+        header('Access-Control-Allow-Origin: *');
+    } else {
+        $reqOrigin = $_SERVER['HTTP_ORIGIN'] ?? '';
+        $allowed   = array_filter(array_map('trim', explode(',', $configured)));
+        if ($reqOrigin !== '' && in_array($reqOrigin, $allowed, true)) {
+            header('Access-Control-Allow-Origin: ' . $reqOrigin);
+            header('Vary: Origin');
+        }
+    }
+    header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
+    header('Access-Control-Allow-Headers: Content-Type, X-EverShelf-Request, X-API-Token, X-Settings-Token');
+}
+
+/** Read-only actions allowed in DEMO_MODE. */
+function evershelfDemoReadOnlyActions(): array {
+    return [
+        'ping', 'check_update', 'health_check', 'get_settings', 'gemini_usage',
+        'search_barcode', 'lookup_barcode', 'stock_for_name',
+        'product_get', 'products_list', 'products_search', 'inventory_search',
+        'inventory_list', 'inventory_summary', 'inventory_finished_items',
+        'transactions_list', 'stats', 'monthly_stats', 'macro_stats',
+        'consumption_predictions', 'inventory_anomalies', 'inventory_duplicate_loss_checks',
+        'recent_popular_products', 'expiry_history', 'food_facts', 'opened_shelf_life',
+        'bring_list', 'bring_suggest', 'shopping_list', 'shopping_suggest', 'smart_shopping',
+        'recipes_list', 'chat_list', 'app_settings_get',
+        'ha_sensor', 'ha_info', 'ha_shopping_items', 'ha_test', 'ha_calendar',
+        'guess_category', 'get_shopping_price', 'get_all_shopping_prices',
+        'backup_list', 'export_inventory',
+    ];
+}
+
+function evershelfDemoBlocksAction(string $action, string $method): bool {
+    if (env('DEMO_MODE') !== 'true') {
+        return false;
+    }
+    if (in_array($action, evershelfDemoReadOnlyActions(), true)) {
+        return false;
+    }
+    // Block all AI generation in demo (cost + writes)
+    if (str_starts_with($action, 'gemini_') || in_array($action, [
+        'generate_recipe', 'generate_recipe_stream', 'chat_to_recipe', 'recipe_from_ingredient',
+    ], true)) {
+        return true;
+    }
+    if ($method === 'POST') {
+        return true;
+    }
+    if (in_array($action, evershelfMutatingGetActions(), true)) {
+        return true;
+    }
+    return !in_array($action, evershelfDemoReadOnlyActions(), true);
+}
+
+/** Hosts allowed for scale WebSocket relay (SSRF guard). */
+function evershelfAllowedScaleHosts(): array {
+    $hosts = ['127.0.0.1', 'localhost', '::1'];
+    $gw    = env('SCALE_GATEWAY_URL', '');
+    if ($gw !== '') {
+        $p = parse_url($gw);
+        if (!empty($p['host'])) {
+            $hosts[] = strtolower($p['host']);
+        }
+    }
+    // Server's own LAN IP — gateway may bind here on kiosk LAN
+    if (function_exists('gethostname')) {
+        $lan = gethostbyname(gethostname());
+        if ($lan && filter_var($lan, FILTER_VALIDATE_IP)) {
+            $hosts[] = $lan;
+        }
+    }
+    return array_values(array_unique($hosts));
+}
+
+function evershelfScaleHostAllowed(string $host): bool {
+    $host = strtolower(trim($host));
+    if ($host === '') {
+        return false;
+    }
+    foreach (evershelfAllowedScaleHosts() as $allowed) {
+        if ($host === strtolower($allowed)) {
+            return true;
+        }
+    }
+    // Allow private /24 only when host matches server's subnet (kiosk on same LAN)
+    $serverIp = evershelfLocalLanIp();
+    if ($serverIp !== '') {
+        $subnet = implode('.', array_slice(explode('.', $serverIp), 0, 3));
+        if (str_starts_with($host, $subnet . '.')) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function evershelfLocalLanIp(): string {
+    $sock = @socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
+    if ($sock) {
+        @socket_connect($sock, '8.8.8.8', 53);
+        @socket_getsockname($sock, $ip);
+        socket_close($sock);
+        if (isset($ip) && filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
+            return $ip;
+        }
+    }
+    return '';
+}
+
+/**
+ * True when the request comes from the EverShelf web UI on the same host.
+ * Used to auto-provision API_TOKEN to the browser without manual .env copy.
+ */
+function evershelfIsSameOriginBrowser(): bool {
+    $host = strtolower(explode(':', $_SERVER['HTTP_HOST'] ?? '')[0]);
+    if ($host === '') {
+        return false;
+    }
+
+    $origin = $_SERVER['HTTP_ORIGIN'] ?? '';
+    if ($origin !== '') {
+        $oh = parse_url($origin, PHP_URL_HOST);
+        return $oh && strtolower($oh) === $host;
+    }
+
+    $referer = $_SERVER['HTTP_REFERER'] ?? '';
+    if ($referer !== '') {
+        $rh = parse_url($referer, PHP_URL_HOST);
+        return $rh && strtolower($rh) === $host;
+    }
+
+    $fetchSite = $_SERVER['HTTP_SEC_FETCH_SITE'] ?? '';
+    if (in_array($fetchSite, ['same-origin', 'same-site'], true)) {
+        return true;
+    }
+
+    return false;
+}
+
+/** Auth for scale endpoints — EventSource cannot send headers; allow query token or same-origin UI. */
+function evershelfRequireScaleAccess(): void {
+    if (!evershelfApiTokenRequired()) {
+        return;
+    }
+    if (evershelfApiTokenValid()) {
+        return;
+    }
+    if (evershelfIsSameOriginBrowser()) {
+        return;
+    }
+    http_response_code(401);
+    header('Content-Type: application/json; charset=utf-8');
+    echo json_encode(['error' => 'unauthorized', 'api_token_required' => true]);
+    exit;
+}

api/logger.php

@@ -0,0 +1,375 @@
+<?php
+/**
+ * EverShelf Logger — rotating file logger with 4 configurable levels.
+ *
+ * Levels (in order of verbosity):
+ *   DEBUG(0) — ogni minima operazione: query, cache, AI payload, function entry/exit
+ *   INFO (1) — azioni completate, AI result summary, sync status             [default]
+ *   WARN (2) — rate limit, cache miss, AI fallback, token renewal, slow op
+ *   ERROR(3) — DB failure, AI API error, file write error, exception
+ *
+ * Config via .env (all optional):
+ *   LOG_LEVEL        = INFO    (DEBUG|INFO|WARN|ERROR)
+ *   LOG_ROTATE_HOURS = 24      (new file every N hours; 1–168; default 24)
+ *   LOG_MAX_FILES    = 14      (max rotated files to keep; default 14)
+ *
+ * Log files: logs/evershelf_YYYY-MM-DD_HH.log
+ * Each line:  [2026-05-18 14:23:11] [INFO ] [rid=a1b2c3d4] [action] Message {ctx}
+ */
+class EverLog {
+
+    // ── Level constants ────────────────────────────────────────────────────
+    const DEBUG = 0;
+    const INFO  = 1;
+    const WARN  = 2;
+    const ERROR = 3;
+
+    private static bool   $initialized  = false;
+    private static int    $level        = self::INFO;
+    private static string $logFile      = '';
+    private static string $logDir       = '';
+    private static int    $rotateHours  = 24;
+    private static int    $maxFiles     = 14;
+    private static string $requestId    = '';
+    private static string $currentAction = '-';
+
+    // ── Init (called lazily on first write) ────────────────────────────────
+    private static function init(): void {
+        if (self::$initialized) return;
+        self::$initialized = true;
+
+        // Read .env values via getenv() (populated by Apache SetEnv or putenv() in index.php)
+        $envLevel    = strtoupper((string)(getenv('LOG_LEVEL')        ?: 'INFO'));
+        $rotateHours = max(1, min(168, (int)(getenv('LOG_ROTATE_HOURS') ?: 24)));
+        $maxFiles    = max(1, min(365, (int)(getenv('LOG_MAX_FILES')    ?: 14)));
+
+        self::$level       = match($envLevel) {
+            'DEBUG' => self::DEBUG,
+            'WARN'  => self::WARN,
+            'ERROR' => self::ERROR,
+            default => self::INFO,
+        };
+        self::$rotateHours = $rotateHours;
+        self::$maxFiles    = $maxFiles;
+        self::$requestId   = substr(bin2hex(random_bytes(4)), 0, 8);
+
+        // Ensure log directory exists
+        $base         = dirname(__DIR__) . '/logs';
+        self::$logDir = $base;
+        if (!is_dir($base)) {
+            @mkdir($base, 0755, true);
+        }
+
+        // Compute current log file path (slot by rotate-hours bucket)
+        $slotTs        = (int)(floor(time() / ($rotateHours * 3600)) * ($rotateHours * 3600));
+        $slotLabel     = gmdate('Y-m-d_H', $slotTs);
+        self::$logFile = "$base/evershelf_{$slotLabel}.log";
+
+        // Rotate (delete oldest files beyond max)
+        self::rotate();
+    }
+
+    // ── Rotate old log files ───────────────────────────────────────────────
+    private static function rotate(): void {
+        $files = glob(self::$logDir . '/evershelf_*.log') ?: [];
+        if (count($files) <= self::$maxFiles) return;
+        sort($files); // oldest first (filenames are lexicographically sortable by date)
+        $toDelete = array_slice($files, 0, count($files) - self::$maxFiles);
+        foreach ($toDelete as $f) {
+            @unlink($f);
+        }
+    }
+
+    // ── Core write ────────────────────────────────────────────────────────
+    private static function write(int $lvl, string $msg, array $ctx, string $action): void {
+        self::init();
+        if ($lvl < self::$level) return;
+
+        $labels = ['DEBUG', 'INFO ', 'WARN ', 'ERROR'];
+        $ts     = gmdate('Y-m-d H:i:s');
+        $act    = $action !== '-' ? $action : self::$currentAction;
+        $ctxStr = empty($ctx) ? '' : ' ' . json_encode($ctx, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+        $line   = "[{$ts}] [{$labels[$lvl]}] [rid=" . self::$requestId . "] [{$act}] {$msg}{$ctxStr}\n";
+
+        @file_put_contents(self::$logFile, $line, FILE_APPEND | LOCK_EX);
+    }
+
+    // ── Public API ────────────────────────────────────────────────────────
+
+    /** Set the current action name (shown in every subsequent log line for this request). */
+    public static function setAction(string $action): void {
+        self::$currentAction = $action;
+    }
+
+    /** Log at DEBUG level — every minor operation, query, cache hit/miss, AI payload. */
+    public static function debug(string $msg, array $ctx = [], string $action = '-'): void {
+        self::write(self::DEBUG, $msg, $ctx, $action);
+    }
+
+    /** Log at INFO level — action completed, recipe generated, sync done. */
+    public static function info(string $msg, array $ctx = [], string $action = '-'): void {
+        self::write(self::INFO, $msg, $ctx, $action);
+    }
+
+    /** Log at WARN level — rate limit, AI fallback, slow op, token renewal. */
+    public static function warn(string $msg, array $ctx = [], string $action = '-'): void {
+        self::write(self::WARN, $msg, $ctx, $action);
+    }
+
+    /** Log at ERROR level — DB failure, AI API error, file write error, exception. */
+    public static function error(string $msg, array $ctx = [], string $action = '-'): void {
+        self::write(self::ERROR, $msg, $ctx, $action);
+    }
+
+    /** Convenience: log a Throwable at ERROR level with class + location. */
+    public static function exception(\Throwable $e, string $action = '-', array $extra = []): void {
+        self::write(self::ERROR, $e->getMessage(), array_merge([
+            'class' => get_class($e),
+            'at'    => basename($e->getFile()) . ':' . $e->getLine(),
+            'trace' => substr($e->getTraceAsString(), 0, 800),
+        ], $extra), $action);
+    }
+
+    /**
+     * Log the start of an action request (INFO).
+     * Automatically sets the current action name so subsequent lines inherit it.
+     */
+    public static function request(string $action, string $method, array $params = []): void {
+        self::setAction($action);
+        // At DEBUG: include all params; at INFO just the action+method
+        if (self::$level <= self::DEBUG) {
+            self::write(self::DEBUG, "→ {$method} /{$action}", $params, $action);
+        } else {
+            self::write(self::INFO, "→ {$method} /{$action}", [], $action);
+        }
+    }
+
+    /**
+     * Log a DB query at DEBUG level.
+     * @param string $sql      Truncated SQL or a descriptive label
+     * @param mixed  $result   Number of rows affected/returned (optional)
+     * @param float  $elapsed  Execution time in seconds (optional)
+     */
+    public static function query(string $sql, $result = null, float $elapsed = 0.0): void {
+        if (self::$level > self::DEBUG) return; // skip entirely unless DEBUG
+        $ctx = [];
+        if ($result !== null) $ctx['rows'] = $result;
+        if ($elapsed > 0)     $ctx['ms']   = round($elapsed * 1000, 1);
+        if ($elapsed > 1.0)   $ctx['SLOW'] = true; // highlight slow queries even in context
+        self::write(self::DEBUG, 'DB: ' . substr($sql, 0, 200), $ctx, self::$currentAction);
+    }
+
+    /**
+     * Log a slow operation as WARN regardless of configured level.
+     * Call this after any operation that took more than $thresholdSec.
+     */
+    public static function slowOp(string $label, float $elapsed, float $thresholdSec = 2.0): void {
+        if ($elapsed < $thresholdSec) return;
+        self::write(self::WARN, "SLOW_OP: {$label}", ['elapsed_s' => round($elapsed, 2)], self::$currentAction);
+    }
+
+    /**
+     * Log an AI call at INFO level (or DEBUG for full payload).
+     * @param string $model      Model name (e.g. 'gemini-2.5-flash')
+     * @param int    $promptLen  Character length of the prompt
+     * @param bool   $isFallback Whether this is the fallback model
+     */
+    public static function aiCall(string $model, int $promptLen, bool $isFallback = false): void {
+        $ctx = ['model' => $model, 'prompt_chars' => $promptLen];
+        if ($isFallback) $ctx['fallback'] = true;
+        $level = $isFallback ? self::WARN : self::INFO;
+        self::write($level, 'AI call', $ctx, self::$currentAction);
+    }
+
+    /**
+     * Log an AI response at INFO level.
+     * @param string $model       Model that responded
+     * @param int    $outputLen   Character length of output
+     * @param float  $elapsed     Call duration in seconds
+     * @param bool   $ok          Whether the call succeeded
+     * @param string $errorMsg    Error message if not ok
+     */
+    public static function aiResponse(string $model, int $outputLen, float $elapsed, bool $ok = true, string $errorMsg = ''): void {
+        $ctx = ['model' => $model, 'output_chars' => $outputLen, 'elapsed_s' => round($elapsed, 2)];
+        if (!$ok) {
+            $ctx['error'] = substr($errorMsg, 0, 200);
+            self::write(self::ERROR, 'AI error', $ctx, self::$currentAction);
+        } else {
+            self::write(self::INFO, 'AI ok', $ctx, self::$currentAction);
+        }
+        // Warn if over 10s
+        if ($ok && $elapsed > 10.0) {
+            self::write(self::WARN, 'AI response slow', ['elapsed_s' => round($elapsed, 2)], self::$currentAction);
+        }
+    }
+
+    /**
+     * Log a cache event at DEBUG level.
+     * @param string $cacheKey  The cache key (or a label)
+     * @param bool   $hit       true = cache hit, false = cache miss
+     * @param string $cacheType 'file', 'session', 'memory'
+     */
+    public static function cache(string $cacheKey, bool $hit, string $cacheType = 'file'): void {
+        if (self::$level > self::DEBUG) return;
+        self::write(self::DEBUG,
+            ($hit ? 'CACHE HIT' : 'CACHE MISS') . " [{$cacheType}]",
+            ['key' => substr($cacheKey, 0, 64)],
+            self::$currentAction
+        );
+    }
+
+    /**
+     * Return the last $lines log lines from all available log files, newest last.
+     * Used by the get_logs API endpoint.
+     */
+    public static function tail(int $lines = 500): array {
+        self::init();
+        $files = glob(self::$logDir . '/evershelf_*.log') ?: [];
+        if (empty($files)) return [];
+        rsort($files); // newest file first
+
+        $collected = [];
+        foreach ($files as $f) {
+            if (count($collected) >= $lines) break;
+            $content = @file_get_contents($f);
+            if ($content === false) continue;
+            $fLines = array_filter(explode("\n", $content));
+            // Prepend so we read newest-first → older lines at front
+            $collected = array_merge(array_values($fLines), $collected);
+        }
+        // Return last $lines, newest at end (chronological order)
+        return array_values(array_slice($collected, -$lines));
+    }
+
+    /** List available log files with their sizes and date ranges. */
+    public static function listFiles(): array {
+        self::init();
+        $files = glob(self::$logDir . '/evershelf_*.log') ?: [];
+        rsort($files);
+        return array_map(fn($f) => [
+            'file'    => basename($f),
+            'size_kb' => round(filesize($f) / 1024, 1),
+            'mtime'   => date('Y-m-d H:i:s', filemtime($f)),
+        ], $files);
+    }
+
+    /** Current effective level name. */
+    public static function levelName(): string {
+        self::init();
+        return ['DEBUG', 'INFO', 'WARN', 'ERROR'][self::$level];
+    }
+
+    /** Current log file path. */
+    public static function currentFile(): string {
+        self::init();
+        return self::$logFile;
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// LoggingPDOStatement — wraps PDOStatement to time and log every execute()
+// ═══════════════════════════════════════════════════════════════════════════
+class LoggingPDOStatement {
+    private \PDOStatement $stmt;
+    private string        $sql;
+
+    public function __construct(\PDOStatement $stmt, string $sql) {
+        $this->stmt = $stmt;
+        $this->sql  = $sql;
+    }
+
+    public function execute(?array $params = null): bool {
+        $t0  = microtime(true);
+        $ok  = $this->stmt->execute($params);
+        $ms  = round((microtime(true) - $t0) * 1000, 2);
+        $ctx = ['ms' => $ms, 'rows' => $this->stmt->rowCount()];
+        if ($ms > 500) $ctx['SLOW'] = true;
+        EverLog::query($this->sql, $this->stmt->rowCount(), (microtime(true) - $t0));
+        return $ok;
+    }
+
+    public function fetch(int $mode = \PDO::FETCH_DEFAULT, ...$args): mixed {
+        return $this->stmt->fetch($mode, ...$args);
+    }
+
+    public function fetchAll(int $mode = \PDO::FETCH_DEFAULT, ...$args): array {
+        return $this->stmt->fetchAll($mode ?: \PDO::FETCH_ASSOC);
+    }
+
+    public function fetchColumn(int $col = 0): mixed {
+        return $this->stmt->fetchColumn($col);
+    }
+
+    public function rowCount(): int {
+        return $this->stmt->rowCount();
+    }
+
+    public function bindValue(int|string $param, mixed $value, int $type = \PDO::PARAM_STR): bool {
+        return $this->stmt->bindValue($param, $value, $type);
+    }
+
+    public function bindParam(int|string $param, mixed &$var, int $type = \PDO::PARAM_STR, int $maxLength = 0): bool {
+        return $this->stmt->bindParam($param, $var, $type, $maxLength);
+    }
+
+    public function closeCursor(): bool {
+        return $this->stmt->closeCursor();
+    }
+
+    public function setFetchMode(int $mode, mixed ...$args): bool {
+        return $this->stmt->setFetchMode($mode, ...$args);
+    }
+
+    public function __get(string $name): mixed {
+        return $this->stmt->$name;
+    }
+
+    public function __call(string $name, array $args): mixed {
+        return $this->stmt->$name(...$args);
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// LoggingPDO — wraps PDO to auto-log all prepare(), query(), exec()
+// Drop-in replacement: return LoggingPDO from getDB() instead of PDO.
+// Type hint: use PDO in all functions (LoggingPDO extends PDO).
+// ═══════════════════════════════════════════════════════════════════════════
+class LoggingPDO extends \PDO {
+    public function prepare(string $query, array $options = []): LoggingPDOStatement|false {
+        $stmt = parent::prepare($query, $options);
+        if ($stmt === false) {
+            EverLog::error('PDO::prepare failed', ['sql' => substr($query, 0, 200)]);
+            return false;
+        }
+        return new LoggingPDOStatement($stmt, $query);
+    }
+
+    public function query(string $query, ?int $fetchMode = null, mixed ...$fetchModeArgs): \PDOStatement|false {
+        $t0   = microtime(true);
+        $stmt = $fetchMode !== null
+            ? parent::query($query, $fetchMode, ...$fetchModeArgs)
+            : parent::query($query);
+        $elapsed = microtime(true) - $t0;
+        if ($stmt !== false) {
+            EverLog::query($query, $stmt->rowCount(), $elapsed);
+        } else {
+            EverLog::error('PDO::query failed', ['sql' => substr($query, 0, 200)]);
+        }
+        return $stmt;
+    }
+
+    public function exec(string $statement): int|false {
+        // Skip WAL/PRAGMA logging below DEBUG (too noisy at startup)
+        $isPragma = stripos(ltrim($statement), 'PRAGMA') === 0;
+        $t0       = microtime(true);
+        $result   = parent::exec($statement);
+        $elapsed  = microtime(true) - $t0;
+        if (!$isPragma) {
+            EverLog::query($statement, $result === false ? 0 : $result, $elapsed);
+        } elseif (EverLog::DEBUG >= 0) {
+            // Log PRAGMAs only at DEBUG level
+            EverLog::query($statement, is_int($result) ? $result : 0, $elapsed);
+        }
+        return $result;
+    }
+}

api/scale_discover.php

@@ -0,0 +1,147 @@
+<?php
+/**
+ * EverShelf Scale Gateway — Auto-discovery (auth + rate limit + LAN only).
+ */
+
+require_once __DIR__ . '/lib/env.php';
+require_once __DIR__ . '/lib/security.php';
+
+header('Content-Type: application/json');
+header('Cache-Control: no-cache');
+evershelfSendCorsHeaders();
+
+if (evershelfApiTokenRequired() && !evershelfApiTokenValid() && !evershelfIsSameOriginBrowser()) {
+    http_response_code(401);
+    echo json_encode(['error' => 'unauthorized', 'api_token_required' => true]);
+    exit;
+}
+
+// Simple rate limit: max 6 scans per minute per IP
+$rlDir = dirname(__DIR__) . '/data/rate_limits';
+if (!is_dir($rlDir)) {
+    @mkdir($rlDir, 0755, true);
+}
+$rlFile = $rlDir . '/scale_discover_' . md5($_SERVER['REMOTE_ADDR'] ?? 'cli') . '.json';
+$now = time();
+$hits = [];
+if (file_exists($rlFile)) {
+    $hits = array_filter(json_decode(file_get_contents($rlFile), true) ?: [], fn($t) => $t > $now - 60);
+}
+if (count($hits) >= 6) {
+    http_response_code(429);
+    echo json_encode(['error' => 'Too many discovery scans']);
+    exit;
+}
+$hits[] = $now;
+@file_put_contents($rlFile, json_encode($hits), LOCK_EX);
+
+$port = (int)($_GET['port'] ?? 8765);
+if ($port < 1 || $port > 65535) {
+    $port = 8765;
+}
+
+$serverIp = evershelfLocalLanIp();
+$parts = explode('.', $serverIp);
+if (count($parts) !== 4) {
+    echo json_encode(['error' => 'Cannot determine local subnet', 'found' => []]);
+    exit;
+}
+$subnet = $parts[0] . '.' . $parts[1] . '.' . $parts[2] . '.';
+
+$candidates = [];
+for ($i = 1; $i <= 254; $i++) {
+    $ip = $subnet . $i;
+    $sock = @stream_socket_client(
+        "tcp://{$ip}:{$port}", $errno, $errstr, 0,
+        STREAM_CLIENT_ASYNC_CONNECT | STREAM_CLIENT_CONNECT
+    );
+    if ($sock !== false) {
+        stream_set_blocking($sock, false);
+        $candidates[$ip] = $sock;
+    }
+}
+
+$found_tcp = [];
+$deadline = microtime(true) + 1.5;
+
+while (!empty($candidates) && microtime(true) < $deadline) {
+    $write  = array_values($candidates);
+    $except = array_values($candidates);
+    $read   = null;
+    $usec   = (int)(max(0, $deadline - microtime(true)) * 1_000_000);
+    $n = @stream_select($read, $write, $except, 0, $usec);
+    if ($n === false || $n === 0) {
+        break;
+    }
+
+    $failed = [];
+    foreach ($except as $s) {
+        $ip = array_search($s, $candidates, true);
+        if ($ip !== false) {
+            $failed[$ip] = true;
+        }
+    }
+    foreach ($write as $s) {
+        $ip = array_search($s, $candidates, true);
+        if ($ip === false) {
+            continue;
+        }
+        if (!isset($failed[$ip])) {
+            $found_tcp[] = $ip;
+        }
+        @fclose($s);
+        unset($candidates[$ip]);
+    }
+    foreach ($failed as $ip => $_) {
+        if (isset($candidates[$ip])) {
+            @fclose($candidates[$ip]);
+            unset($candidates[$ip]);
+        }
+    }
+}
+foreach ($candidates as $s) {
+    @fclose($s);
+}
+
+$gateways = [];
+foreach ($found_tcp as $ip) {
+    $sock = @stream_socket_client("tcp://{$ip}:{$port}", $errno, $errstr, 2);
+    if (!$sock) {
+        continue;
+    }
+    stream_set_timeout($sock, 2);
+
+    $key = base64_encode(random_bytes(16));
+    fwrite($sock,
+        "GET / HTTP/1.1\r\n" .
+        "Host: {$ip}:{$port}\r\n" .
+        "Upgrade: websocket\r\n" .
+        "Connection: Upgrade\r\n" .
+        "Sec-WebSocket-Key: {$key}\r\n" .
+        "Sec-WebSocket-Version: 13\r\n" .
+        "\r\n"
+    );
+
+    $resp = '';
+    $dl = microtime(true) + 2;
+    while (microtime(true) < $dl && !feof($sock)) {
+        $line = fgets($sock, 256);
+        if ($line === false) {
+            break;
+        }
+        $resp .= $line;
+        if ($line === "\r\n") {
+            break;
+        }
+    }
+    fclose($sock);
+
+    if (str_contains($resp, '101')) {
+        $gateways[] = "ws://{$ip}:{$port}";
+    }
+}
+
+echo json_encode([
+    'found'  => $gateways,
+    'subnet' => rtrim($subnet, '.') . '.0/24',
+]);

api/scale_ping.php

@@ -0,0 +1,76 @@
+<?php
+/**
+ * EverShelf Scale Gateway — Connection ping / test (SSRF-hardened)
+ */
+
+require_once __DIR__ . '/lib/env.php';
+require_once __DIR__ . '/lib/security.php';
+
+header('Content-Type: application/json');
+header('Cache-Control: no-cache');
+
+if (evershelfApiTokenRequired() && !evershelfApiTokenValid() && !evershelfIsSameOriginBrowser()) {
+    http_response_code(401);
+    echo json_encode(['ok' => false, 'error' => 'unauthorized', 'api_token_required' => true]);
+    exit;
+}
+
+$rawUrl = $_GET['url'] ?? '';
+
+if (!preg_match('#^ws://[0-9a-zA-Z][\w.\-]*(:\d{1,5})?(/.*)?$#', $rawUrl)) {
+    echo json_encode(['ok' => false, 'error' => 'Invalid gateway URL (must start with ws://)']);
+    exit;
+}
+
+$parsed = parse_url($rawUrl);
+$host   = strtolower($parsed['host'] ?? '');
+$port   = (int)($parsed['port'] ?? 8765);
+$path   = ($parsed['path'] ?? '') ?: '/';
+
+if (!$host || $port < 1 || $port > 65535) {
+    echo json_encode(['ok' => false, 'error' => 'Invalid host or port']);
+    exit;
+}
+
+if (!evershelfScaleHostAllowed($host)) {
+    echo json_encode(['ok' => false, 'error' => 'Gateway host not allowed']);
+    exit;
+}
+
+// Try to open a TCP connection with a 5-second timeout
+$sock = @stream_socket_client("tcp://{$host}:{$port}", $errno, $errstr, 5);
+if (!$sock) {
+    echo json_encode(['ok' => false, 'error' => "Cannot connect to {$host}:{$port} — {$errstr}"]);
+    exit;
+}
+
+stream_set_timeout($sock, 5);
+
+// Perform WebSocket handshake
+$wsKey = base64_encode(random_bytes(16));
+fwrite($sock,
+    "GET {$path} HTTP/1.1\r\n" .
+    "Host: {$host}:{$port}\r\n" .
+    "Upgrade: websocket\r\n" .
+    "Connection: Upgrade\r\n" .
+    "Sec-WebSocket-Key: {$wsKey}\r\n" .
+    "Sec-WebSocket-Version: 13\r\n" .
+    "\r\n"
+);
+
+// Read HTTP response (looking for 101 Switching Protocols)
+$resp = '';
+while (!feof($sock)) {
+    $line = fgets($sock, 1024);
+    if ($line === false) break;
+    $resp .= $line;
+    if ($line === "\r\n") break;
+}
+
+fclose($sock);
+
+if (str_contains($resp, '101')) {
+    echo json_encode(['ok' => true]);
+} else {
+    echo json_encode(['ok' => false, 'error' => 'WebSocket handshake failed — check that the gateway app is running']);
+}

api/scale_relay.php

@@ -0,0 +1,245 @@
+<?php
+/**
+ * EverShelf Scale Gateway — SSE Relay
+ *
+ * Bridges the Android BLE gateway (ws://) to Server-Sent Events (SSE) so that
+ * browsers on HTTPS pages can receive weight data without mixed-content errors.
+ *
+ * Usage: GET /api/scale_relay.php?url=ws%3A%2F%2F192.168.1.100%3A8765
+ */
+
+require_once __DIR__ . '/lib/env.php';
+require_once __DIR__ . '/lib/security.php';
+
+if (evershelfApiTokenRequired() && !evershelfApiTokenValid() && !evershelfIsSameOriginBrowser()) {
+    header('Content-Type: application/json; charset=utf-8');
+    http_response_code(401);
+    echo json_encode(['error' => 'unauthorized', 'api_token_required' => true]);
+    exit;
+}
+
+// ── Input validation ──────────────────────────────────────────────────────────
+$rawUrl = $_GET['url'] ?? '';
+
+// Only accept ws:// scheme with valid host and optional port/path
+if (!preg_match('#^ws://[0-9a-zA-Z][\w.\-]*(:\d{1,5})?(/.*)?$#', $rawUrl)) {
+    header('Content-Type: text/event-stream');
+    echo 'data: ' . json_encode(['type' => 'error', 'message' => 'Invalid gateway URL (must start with ws://)']) . "\n\n";
+    exit;
+}
+
+$parsed = parse_url($rawUrl);
+$wsHost = strtolower($parsed['host'] ?? '');
+$wsPort = (int)($parsed['port'] ?? 8765);
+$wsPath = ($parsed['path'] ?? '') ?: '/';
+
+if (!$wsHost || $wsPort < 1 || $wsPort > 65535) {
+    header('Content-Type: text/event-stream');
+    echo 'data: ' . json_encode(['type' => 'error', 'message' => 'Invalid host or port']) . "\n\n";
+    exit;
+}
+
+if (!evershelfScaleHostAllowed($wsHost)) {
+    header('Content-Type: text/event-stream');
+    echo 'data: ' . json_encode(['type' => 'error', 'message' => 'Gateway host not allowed']) . "\n\n";
+    exit;
+}
+
+// ── SSE headers ───────────────────────────────────────────────────────────────
+header('Content-Type: text/event-stream');
+header('Cache-Control: no-cache, no-store, must-revalidate');
+header('X-Accel-Buffering: no');       // Disable nginx / Caddy buffering
+header('Content-Encoding: identity');  // Prevent gzip/deflate compression
+
+set_time_limit(0);
+ignore_user_abort(false); // stop when browser closes connection
+
+// Clear all PHP output-buffering levels so echo/flush goes straight to SAPI
+while (ob_get_level() > 0) {
+    ob_end_clean();
+}
+
+// ── Connect to Android gateway ────────────────────────────────────────────────
+$sock = @stream_socket_client("tcp://{$wsHost}:{$wsPort}", $errno, $errstr, 5);
+if (!$sock) {
+    echo 'data: ' . json_encode([
+        'type'    => 'error',
+        'message' => "Cannot connect to gateway ({$wsHost}:{$wsPort}): {$errstr}",
+    ]) . "\n\n";
+    flush();
+    exit;
+}
+
+// ── WebSocket handshake (PHP acts as client) ──────────────────────────────────
+// RFC 6455: client frames MUST be masked.
+$wsKey = base64_encode(random_bytes(16));
+
+stream_set_blocking($sock, true);
+stream_set_timeout($sock, 5);
+
+fwrite($sock,
+    "GET {$wsPath} HTTP/1.1\r\n" .
+    "Host: {$wsHost}:{$wsPort}\r\n" .
+    "Upgrade: websocket\r\n" .
+    "Connection: Upgrade\r\n" .
+    "Sec-WebSocket-Key: {$wsKey}\r\n" .
+    "Sec-WebSocket-Version: 13\r\n" .
+    "\r\n"
+);
+
+// Read HTTP 101 Switching Protocols response
+$httpResp = '';
+$deadline = microtime(true) + 5;
+while (microtime(true) < $deadline && !feof($sock)) {
+    $line = fgets($sock, 1024);
+    if ($line === false) break;
+    $httpResp .= $line;
+    if ($line === "\r\n") break;
+}
+
+if (!str_contains($httpResp, '101')) {
+    fclose($sock);
+    echo 'data: ' . json_encode([
+        'type'    => 'error',
+        'message' => 'WebSocket handshake failed — is the gateway URL correct?',
+    ]) . "\n\n";
+    flush();
+    exit;
+}
+
+// Switch to non-blocking for poll-based relay loop
+stream_set_blocking($sock, false);
+stream_set_timeout($sock, 0);
+
+// Ask gateway for current status immediately
+wsSend($sock, json_encode(['type' => 'get_status']));
+
+// ── SSE relay loop ────────────────────────────────────────────────────────────
+$buf      = '';
+$lastPing = time();
+
+while (!connection_aborted()) {
+    $chunk = @fread($sock, 8192);
+
+    if ($chunk === false || (feof($sock) && $chunk === '')) {
+        // Gateway closed the connection
+        echo 'data: ' . json_encode(['type' => 'error', 'message' => 'Gateway disconnected']) . "\n\n";
+        flush();
+        break;
+    }
+
+    if ($chunk !== '') {
+        $buf .= $chunk;
+        while (($payload = wsRead($buf, $sock)) !== null) {
+            if ($payload === false) goto done; // close frame received
+            if ($payload === '') continue;     // ping/pong control frames (handled inside wsRead)
+            echo "data: {$payload}\n\n";
+            flush();
+        }
+    }
+
+    // SSE keep-alive comment + gateway WebSocket ping every 20 seconds
+    if (time() - $lastPing >= 20) {
+        echo ": keep-alive\n\n";
+        flush();
+        $lastPing = time();
+        wsPing($sock);
+    }
+
+    usleep(100_000); // 100 ms polling interval
+}
+
+done:
+fclose($sock);
+
+// ── WebSocket helpers ─────────────────────────────────────────────────────────
+
+/** Send a masked text frame from PHP (client) to the gateway (server). */
+function wsSend($sock, string $payload): void
+{
+    $len  = strlen($payload);
+    $mask = random_bytes(4);
+
+    if ($len < 126) {
+        $header = "\x81" . chr(0x80 | $len);
+    } elseif ($len < 65536) {
+        $header = "\x81\xFE" . pack('n', $len); // opcode=text, mask bit, 2-byte length
+    } else {
+        $header = "\x81\xFF" . pack('J', $len); // opcode=text, mask bit, 8-byte length
+    }
+
+    $masked = '';
+    for ($i = 0; $i < $len; $i++) {
+        $masked .= $payload[$i] ^ $mask[$i % 4];
+    }
+
+    @fwrite($sock, $header . $mask . $masked);
+}
+
+/** Send a masked ping to keep the gateway connection alive. */
+function wsPing($sock): void
+{
+    @fwrite($sock, "\x89\x80" . random_bytes(4)); // FIN+ping, MASK bit, 4-byte mask, no payload
+}
+
+/**
+ * Try to decode one complete WebSocket frame from the read buffer.
+ * The gateway (server) sends unmasked frames to PHP (client).
+ *
+ * Returns:
+ *   string  — decoded text/binary payload
+ *   ''      — control frame (ping/pong) handled internally, skip
+ *   false   — close frame received
+ *   null    — not enough data yet, read more
+ */
+function wsRead(string &$buf, $sock): string|null|false
+{
+    if (strlen($buf) < 2) return null;
+
+    $b0  = ord($buf[0]);
+    $b1  = ord($buf[1]);
+    $op  = $b0 & 0x0F;
+    $msk = ($b1 & 0x80) !== 0; // servers never mask, but handle defensively
+    $len = $b1 & 0x7F;
+    $off = 2;
+
+    if ($len === 126) {
+        if (strlen($buf) < 4) return null;
+        $len = unpack('n', substr($buf, 2, 2))[1];
+        $off = 4;
+    } elseif ($len === 127) {
+        if (strlen($buf) < 10) return null;
+        $len = unpack('J', substr($buf, 2, 8))[1];
+        $off = 10;
+    }
+
+    if ($msk) $off += 4;
+    if (strlen($buf) < $off + $len) return null;
+
+    $maskKey = $msk ? substr($buf, $off - 4, 4) : null;
+    $payload = substr($buf, $off, $len);
+
+    if ($msk && $maskKey) {
+        for ($i = 0; $i < strlen($payload); $i++) {
+            $payload[$i] = $payload[$i] ^ $maskKey[$i % 4];
+        }
+    }
+
+    // Consume frame from buffer
+    $buf = substr($buf, $off + $len);
+
+    if ($op === 0x8) return false;  // close frame
+    if ($op === 0x9) {              // ping → send masked pong
+        $pLen = strlen($payload);
+        $mask = random_bytes(4);
+        $maskedPayload = '';
+        for ($i = 0; $i < $pLen; $i++) {
+            $maskedPayload .= $payload[$i] ^ $mask[$i % 4];
+        }
+        @fwrite($sock, "\x8A" . chr(0x80 | $pLen) . $mask . $maskedPayload);
+        return '';
+    }
+    if ($op === 0xA) return '';     // pong — ignore
+
+    return $payload;               // 0x1 = text, 0x2 = binary
+}

assets/js/core/auth.js

@@ -0,0 +1,77 @@
+/**
+ * EverShelf core — API token storage and auth headers.
+ */
+const EVERSHELF_TOKEN_KEY = 'evershelf_api_token';
+
+function getApiToken() {
+    return localStorage.getItem(EVERSHELF_TOKEN_KEY) || '';
+}
+
+function setApiToken(token) {
+    const t = (token || '').trim();
+    if (t) {
+        localStorage.setItem(EVERSHELF_TOKEN_KEY, t);
+    } else {
+        localStorage.removeItem(EVERSHELF_TOKEN_KEY);
+    }
+}
+
+function apiAuthHeaders() {
+    const fromStorage = getApiToken();
+    const fromSettingsField = document.getElementById('setting-settings-token')?.value.trim() || '';
+    const token = fromSettingsField || fromStorage;
+    if (!token) return {};
+    return { 'X-API-Token': token };
+}
+
+/** Fetch API token from server when loading the UI from the same origin. */
+async function ensureApiToken() {
+    if (getApiToken()) return true;
+    try {
+        const res = await fetch('api/index.php?action=app_bootstrap', { cache: 'no-store' });
+        if (!res.ok) return false;
+        const data = await res.json();
+        window._apiTokenRequired = !!data.api_token_required;
+        if (data.api_token) {
+            setApiToken(data.api_token);
+            return true;
+        }
+    } catch (_) { /* offline / network */ }
+    return !!getApiToken();
+}
+
+function _promptApiTokenIfNeeded() {
+    if (!window._apiTokenRequired) return;
+    if (getApiToken()) return;
+    const existing = document.getElementById('api-token-overlay');
+    if (existing) return;
+    const title = typeof t === 'function' ? t('startup.token_prompt_title') : '🔒 API Token';
+    const hint  = typeof t === 'function' ? t('startup.token_prompt_hint') : 'Enter API_TOKEN from .env';
+    const btn   = typeof t === 'function' ? t('startup.token_prompt_btn') : 'Continue';
+    const overlay = document.createElement('div');
+    overlay.id = 'api-token-overlay';
+    overlay.className = 'modal-overlay';
+    overlay.style.display = 'flex';
+    overlay.innerHTML = `
+        <div class="modal-content" style="max-width:420px;padding:20px">
+            <h3>${title}</h3>
+            <p class="settings-hint">${hint}</p>
+            <input type="password" id="api-token-input" class="form-input" placeholder="API token">
+            <button class="btn btn-primary full-width mt-2" id="api-token-save">${btn}</button>
+        </div>`;
+    document.body.appendChild(overlay);
+    document.getElementById('api-token-save').onclick = () => {
+        const v = document.getElementById('api-token-input').value.trim();
+        if (v) {
+            setApiToken(v);
+            overlay.remove();
+            location.reload();
+        }
+    };
+}
+
+window.getApiToken = getApiToken;
+window.setApiToken = setApiToken;
+window.apiAuthHeaders = apiAuthHeaders;
+window.ensureApiToken = ensureApiToken;
+window._promptApiTokenIfNeeded = _promptApiTokenIfNeeded;

assets/js/core/dom.js

@@ -0,0 +1,11 @@
+/**
+ * EverShelf core — safe HTML escaping (loaded before app.js).
+ */
+function escapeHtml(str) {
+    if (str == null) return '';
+    const div = document.createElement('div');
+    div.textContent = String(str);
+    return div.innerHTML;
+}
+
+window.escapeHtml = escapeHtml;

backup.sh

@@ -1,23 +1,29 @@
 #!/bin/bash
-# Daily backup of Dispensa database (local only)
-# The database is NOT pushed to remote repositories.
-# Runs via cron: creates a local timestamped backup copy
-#
-# Example crontab entry:
-#   0 3 * * * /var/www/html/dispensa/backup.sh
+# Daily backup of EverShelf database (local only)
+# Retention follows BACKUP_RETENTION_DAYS from .env (default 3)
 
-INSTALL_DIR="$(cd "$(dirname "$0")" && pwd)"
+set -euo pipefail
+INSTALL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 BACKUP_DIR="${INSTALL_DIR}/data/backups"
+ENV_FILE="${INSTALL_DIR}/.env"
+
+RETENTION=3
+if [ -f "$ENV_FILE" ]; then
+    val=$(grep -E '^BACKUP_RETENTION_DAYS=' "$ENV_FILE" | tail -1 | cut -d= -f2)
+    if [[ "$val" =~ ^[0-9]+$ ]] && [ "$val" -ge 1 ]; then
+        RETENTION="$val"
+    fi
+fi
 
 mkdir -p "$BACKUP_DIR"
 
-DB_FILE="${INSTALL_DIR}/data/dispensa.db"
+DB_FILE="${INSTALL_DIR}/data/evershelf.db"
 if [ ! -f "$DB_FILE" ]; then
     exit 0
 fi
 
 DATE=$(date '+%Y-%m-%d_%H%M')
-cp "$DB_FILE" "${BACKUP_DIR}/dispensa_${DATE}.db"
+cp "$DB_FILE" "${BACKUP_DIR}/evershelf_${DATE}.db"
 
-# Keep only the last 7 backups
-ls -t "${BACKUP_DIR}"/dispensa_*.db 2>/dev/null | tail -n +8 | xargs -r rm --
+# Keep only the newest N backups
+ls -t "${BACKUP_DIR}"/evershelf_*.db 2>/dev/null | tail -n +$((RETENTION + 1)) | xargs -r rm --

data/.htaccess

@@ -0,0 +1,2 @@
+# Deny all direct HTTP access to runtime data (DB, tokens, caches, logs)
+Require all denied

data/ai_usage.json

@@ -0,0 +1,9 @@
+{
+  "2026-05": {
+    "input_tokens": 4438300,
+    "output_tokens": 1286760,
+    "calls": 8374,
+    "by_action": {},
+    "by_model": {}
+  }
+}

data/anomaly_dismissed.json

@@ -0,0 +1 @@
+{}

data/backup_last_ts.json

@@ -0,0 +1 @@
+{"ts":1779204302,"filename":"evershelf_2026-05-19_1525.db","size_kb":444}

data/shopping_name_cache.json

@@ -0,0 +1,20 @@
+{
+    "dc1bb00e006a5ed073aad9b0ca2f1601": "Toast",
+    "f03b656f4cfaa9d633fc155cdafcb83b": "Sale",
+    "fa1266e5e6bb32602e08aaf9434ec9ad": "Patate",
+    "ca2da3ad2a7b42e717f766e06a83730e": "Verdure",
+    "ce8f4f54fc6ead0f0a8ce36503bba462": "Pasta",
+    "2ddb0faf33c4ceeed89fada2c7c2b9c5": "Ingredienti Spezie",
+    "0290647fcd95ec97f0d6666c46a72943": "Brodo",
+    "405ea6ec33d54042d046599650f422ea": "Succo",
+    "f624c420f14d8eff122c0bb395eb63da": "Snack Dolci",
+    "92751fbb97923590c402bc7810778b36": "Biscotti",
+    "8727f7abcb66764b5eb3d1f036bc18b8": "Tè",
+    "0eb53fe1a5d4d106eac47c8a81d1afe7": "Farina",
+    "0ebada5597d1d166d0ed8f49500bfeba": "Verdure",
+    "fe7456efb7e767a06e3af9f5ec7b3637": "Piatti Pronti",
+    "2a5d2289bb7bc306dd066dfaff7ef581": "Ingredienti Spezie",
+    "b630c06f2ac72a1e2ffbd57d327a3733": "Salsa",
+    "32a05ae91ccfa4d37be454836971436b": "Ingredienti",
+    "a21f0e7718c8f12166d864d0d05f60a0": "Salsa"
+}

data/shopping_total_cache.json

@@ -0,0 +1 @@
+{}

docker-compose.yml

@@ -1,12 +1,12 @@
 services:
-  dispensa:
+  evershelf:
     build: .
-    container_name: dispensa
+    container_name: evershelf
     ports:
       - "8080:80"
     volumes:
       # Persist database and runtime data
-      - dispensa_data:/var/www/html/data
+      - evershelf_data:/var/www/html/data
       # Mount your local .env configuration
       - ./.env:/var/www/html/.env:ro
     restart: unless-stopped
@@ -14,5 +14,5 @@ services:
       - TZ=Europe/Rome
 
 volumes:
-  dispensa_data:
+  evershelf_data:
     driver: local

docker/avahi-evershelf.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" standalone='no'?>
+<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
+<service-group>
+  <name replace-wildcards="yes">EverShelf Pantry (%h)</name>
+  <service>
+    <type>_evershelf._tcp</type>
+    <port>80</port>
+    <txt-record>path=/api/</txt-record>
+    <txt-record>version=1.0</txt-record>
+    <txt-record>app=evershelf</txt-record>
+  </service>
+</service-group>

docs/ARCHITECTURE.md

@@ -0,0 +1,38 @@
+# EverShelf — Architecture (modular layout)
+
+```
+dispensa/
+├── api/
+│   ├── bootstrap.php       # Shared init: env, security, DB, logger
+│   ├── index.php           # HTTP handlers + router (split planned per domain)
+│   ├── database.php        # SQLite schema & migrations
+│   ├── logger.php          # Rotating file logger (logs/)
+│   ├── cron_smart_shopping.php  # CLI cron (uses bootstrap + index handlers)
+│   ├── lib/
+│   │   ├── env.php         # .env loader
+│   │   ├── constants.php   # Paths & pricing constants
+│   │   ├── security.php    # API auth, CORS, demo mode, scale allowlist
+│   │   ├── github.php      # Encrypted GitHub Issues token
+│   │   └── cron_log.php    # data/cron.log rotation
+│   └── scale_*.php         # Scale gateway helpers (auth + SSRF guards)
+├── assets/
+│   ├── js/
+│   │   ├── core/           # auth.js, dom.js (loaded before app.js)
+│   │   └── app.js          # SPA logic (domain modules: future split)
+│   └── vendor/             # Offline CDN fallbacks (quagga, transformers)
+├── data/                   # Runtime data (.htaccess: deny all)
+├── logs/                   # Application logs (.htaccess: deny all)
+└── scripts/                # migrate-env-security, fix-permissions, encrypt-gh-token
+```
+
+## Security model
+
+- **`API_TOKEN`** (or legacy **`SETTINGS_TOKEN`**): when set, every API action requires `X-API-Token` header or `?api_token=` (Home Assistant).
+- Secrets (`HA_TOKEN`, `TTS_TOKEN`, `GEMINI_API_KEY`) stay in `.env`; `get_settings` exposes only `*_set` flags.
+- **`GH_ISSUE_TOKEN_ENC`** + **`GH_ISSUE_TOKEN_KEY`**: AES-256-GCM encrypted GitHub Issues token.
+
+## Planned refactors
+
+1. Split `api/index.php` handlers into `api/handlers/{products,inventory,ai,shopping}.php`
+2. Split `assets/js/app.js` into ES modules under `assets/js/features/`
+3. Optional `npm run build` to minify JS/CSS (see `package.json`)

docs/openapi.yaml

@@ -1,8 +1,8 @@
 openapi: "3.1.0"
 info:
-  title: Dispensa Manager API
+  title: EverShelf API
   description: |
-    REST API for Dispensa Manager — a self-hosted pantry management system.
+    REST API for EverShelf — a self-hosted pantry management system.
     All endpoints use the query parameter `action` to determine the operation.
     
     **Base URL:** `api/index.php?action={action_name}`
@@ -11,10 +11,10 @@ info:
     - General: 120 requests/minute
     - AI endpoints: 15 requests/minute
     - Login endpoints: 5 requests/minute
-  version: "1.0.0"
+  version: "1.2.0"
   contact:
     name: Stimpfl Daniel
-    email: dadaloop82@gmail.com
+    email: evershelfproject@gmail.com
   license:
     name: MIT
     url: https://opensource.org/licenses/MIT
@@ -500,39 +500,6 @@ paths:
         "200":
           description: Recipe deleted
 
-  /index.php?action=dupliclick_login:
-    post:
-      summary: Login to DupliClick (online shopping)
-      tags: [DupliClick]
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                email:
-                  type: string
-                password:
-                  type: string
-      responses:
-        "200":
-          description: Login successful
-
-  /index.php?action=dupliclick_search:
-    get:
-      summary: Search DupliClick product catalog
-      tags: [DupliClick]
-      parameters:
-        - name: q
-          in: query
-          required: true
-          schema:
-            type: string
-      responses:
-        "200":
-          description: Search results
-
   /index.php?action=tts_proxy:
     post:
       summary: Proxy TTS request to external endpoint
@@ -685,7 +652,5 @@ tags:
     description: Recipe storage
   - name: Settings
     description: Application and server settings
-  - name: DupliClick
-    description: DupliClick online shopping integration
   - name: TTS
     description: Text-to-Speech proxy

docs/wiki/API-Reference.md

@@ -0,0 +1,332 @@
+# 🔌 API Reference
+
+EverShelf exposes a single PHP endpoint: **`api/index.php`**. All actions are selected via the `action` query parameter.
+
+> **Full OpenAPI 3.1 spec:** [`docs/openapi.yaml`](https://github.com/dadaloop82/EverShelf/blob/main/docs/openapi.yaml)
+
+---
+
+## Base URL
+
+```
+https://your-server/api/index.php?action=ACTION_NAME
+```
+
+GET requests pass parameters as query params; POST requests send JSON in the body.
+
+---
+
+## Rate Limits
+
+| Tier | Limit | Applies to |
+|------|-------|-----------|
+| Standard | 120 req/min | All general endpoints |
+| AI | 15 req/min | `gemini_*`, `generate_recipe*` |
+| Strict | 5 req/min | `report_error` |
+
+Exceeded limits return HTTP 429 with `{"error": "rate_limit_exceeded"}`.
+
+---
+
+## Products
+
+### `search_barcode` — GET
+Search for a product in the local database by barcode.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `barcode` | string | EAN/UPC barcode |
+
+### `lookup_barcode` — GET
+Look up a barcode on Open Food Facts (external call).
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `barcode` | string | EAN/UPC barcode |
+
+### `product_save` — POST
+Create or update a product. Pass `id` to update.
+
+```json
+{
+  "id": 42,
+  "name": "Pasta Barilla",
+  "brand": "Barilla",
+  "category": "pasta",
+  "unit": "g",
+  "default_quantity": 500,
+  "barcode": "8076800105988"
+}
+```
+
+### `product_get` — GET
+Get product details by `id`.
+
+### `product_delete` — POST
+Delete a product by `id`.
+
+### `products_list` — GET
+List all products.
+
+### `products_search` — GET
+Search products by name (`?q=pasta`).
+
+---
+
+## Inventory
+
+### `inventory_list` — GET
+List all inventory items with product details, grouped.
+
+**Response:**
+```json
+{
+  "inventory": [
+    {
+      "id": 1,
+      "product_id": 42,
+      "name": "Pasta Barilla",
+      "quantity": 2,
+      "unit": "pz",
+      "location": "dispensa",
+      "expiry_date": "2027-03-01",
+      "opened_at": null,
+      "vacuum_sealed": 0
+    }
+  ]
+}
+```
+
+### `inventory_add` — POST
+Add a product to inventory.
+
+```json
+{
+  "product_id": 42,
+  "quantity": 3,
+  "location": "dispensa",
+  "expiry_date": "2027-03-01",
+  "vacuum_sealed": false
+}
+```
+
+**Locations:** `dispensa`, `frigo`, `freezer`, `altro`
+
+### `inventory_use` — POST
+Consume inventory. Set `use_all: true` to consume all stock at a location.
+
+```json
+{
+  "product_id": 42,
+  "quantity": 1,
+  "location": "dispensa"
+}
+```
+
+```json
+{
+  "product_id": 42,
+  "use_all": true,
+  "location": "__all__",
+  "notes": "Buttato"
+}
+```
+
+### `inventory_update` — POST
+Update an inventory entry by `id`.
+
+### `inventory_delete` — POST
+Remove an inventory entry by `id`.
+
+### `inventory_summary` — GET
+Returns item counts per location.
+
+```json
+{
+  "dispensa": 12,
+  "frigo": 5,
+  "freezer": 8
+}
+```
+
+---
+
+## Transactions (Log)
+
+### `transactions_list` — GET
+Returns the operation log.
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `limit` | int | 50 | Results per page |
+| `offset` | int | 0 | Pagination offset |
+
+### `transaction_undo` — POST
+Undo a transaction within 24 hours.
+
+```json
+{ "id": 873 }
+```
+
+**Response on success:**
+```json
+{ "success": true, "name": "Tonno all'olio d'oliva" }
+```
+
+**Error cases:**
+```json
+{ "error": "...", "already_undone": true }
+{ "error": "...", "too_old": true }
+```
+
+### `stats` — GET
+Returns waste and consumption statistics for the last 30 days.
+
+---
+
+## AI / Gemini
+
+All AI endpoints require `GEMINI_API_KEY` to be configured. Rate limit: 15 req/min.
+
+### `gemini_expiry` — POST
+Read an expiry date from a product photo.
+
+```json
+{ "image": "data:image/jpeg;base64,..." }
+```
+
+### `gemini_identify` — POST
+Identify a product from a photo.
+
+```json
+{ "image": "data:image/jpeg;base64,..." }
+```
+
+### `gemini_chat` — POST
+Chat with the AI kitchen assistant.
+
+```json
+{ "message": "Cosa posso fare con la pasta?", "history": [] }
+```
+
+### `generate_recipe` — POST
+Generate a recipe based on current inventory.
+
+```json
+{ "persons": 2, "meal": "dinner", "preferences": {} }
+```
+
+### `generate_recipe_stream` — POST
+Same as `generate_recipe` but streams output via Server-Sent Events.
+
+### `gemini_product_hint` — POST
+Get AI storage location + shelf-life hint for a new product.
+
+### `gemini_shopping_enrich` — POST
+Enrich shopping suggestions with practical tips.
+
+### `gemini_anomaly_explain` — POST
+Get a plain-language explanation for a specific inventory anomaly.
+
+---
+
+## Shopping List (Bring!)
+
+Requires `BRING_EMAIL` and `BRING_PASSWORD` in `.env`.
+
+### `bring_list` — GET
+Get the current Bring! shopping list.
+
+### `bring_add` — POST
+Add items to the Bring! list.
+
+```json
+{ "items": ["Latte", "Pane"] }
+```
+
+### `bring_remove` — POST
+Remove an item from the Bring! list.
+
+```json
+{ "name": "Latte" }
+```
+
+### `smart_shopping` — GET
+Get smart shopping predictions based on consumption history.
+
+---
+
+## Settings
+
+### `get_settings` — GET
+Returns current settings as **boolean flags only** (no raw key values):
+
+```json
+{
+  "gemini_key_set": true,
+  "bring_configured": false,
+  "tts_enabled": false,
+  "scale_enabled": true,
+  "demo_mode": false,
+  "settings_token_set": true
+}
+```
+
+### `save_settings` — POST
+Update server configuration. If `SETTINGS_TOKEN` is set, requires header:
+
+```
+X-Settings-Token: your_token
+```
+
+```json
+{
+  "gemini_api_key": "...",
+  "bring_email": "...",
+  "scale_enabled": true,
+  "scale_gateway_url": "ws://127.0.0.1:8765"
+}
+```
+
+---
+
+## Error Reporting
+
+### `report_error` — POST
+Submit an automatic error report (creates a GitHub Issue).
+
+```json
+{
+  "type": "uncaught-error",
+  "message": "...",
+  "stack": "...",
+  "context": {}
+}
+```
+
+Only creates an issue if:
+- The client is running the latest released version
+- The fingerprint hasn't been seen in the last 24 hours
+
+---
+
+## Anomaly Detection
+
+### `inventory_anomalies` — GET
+Returns inventory rows where stored quantity significantly differs from transaction history.
+
+### `dismiss_anomaly` — POST
+Dismiss an anomaly banner without changing inventory.
+
+---
+
+## Scale Integration
+
+### `scale_relay` (SSE) — GET
+Relays BLE scale readings from the gateway to the browser via Server-Sent Events (avoids HTTPS→WS mixed-content issues).
+
+### `scale_ping` — GET
+Check if the Scale Gateway is reachable.
+
+### `scale_discover` — GET
+Scan the local LAN for a running Scale Gateway instance.

docs/wiki/Android-Kiosk.md

@@ -0,0 +1,152 @@
+# 📺 Android Kiosk App
+
+The EverShelf Kiosk app turns any Android tablet into a dedicated, locked-down kitchen display running EverShelf full-screen.
+
+---
+
+## Download
+
+**[⬇ Download latest APK](https://github.com/dadaloop82/EverShelf/releases/latest/download/evershelf-kiosk.apk)**
+
+> Current version: **v1.6.0** — requires Android 7.0+
+
+---
+
+## What it does
+
+- Displays the EverShelf web app in a **full-screen WebView** (no browser chrome)
+- **Locks the screen** with Android's `startLockTask` — home, recents, and back buttons are blocked
+- Runs the **built-in BLE scale gateway** as an integrated foreground service — no external app required
+- Provides a **native TTS bridge** so Cooking Mode reads steps aloud via Android TextToSpeech
+- Auto-detects your EverShelf server on the LAN with a **smart discovery scanner**
+- Reports errors and install failures back to the developer automatically
+
+---
+
+## Setup Wizard (6 steps)
+
+The wizard runs automatically on first launch.
+
+### Step 1 — Language
+Select the app and web interface language (Italian, English, German).
+
+### Step 2 — Welcome
+Overview of what the wizard will configure.
+
+### Step 3 — Permissions
+Grant camera, microphone, and storage permissions needed by the web app.
+
+The button transforms from **"Grant permissions"** to **"✅ Permissions granted — Continue →"** (green) once all permissions are granted.
+
+### Step 4 — Server URL
+Enter your EverShelf server URL (e.g. `https://192.168.1.100/dispensa`).
+
+**Or tap "Auto-discover"** to let the wizard scan your LAN:
+- 60 parallel threads, TCP pre-check, ports 80/443/8080/8443
+- Only scans your actual Wi-Fi/Ethernet subnet (VPN and cellular interfaces ignored)
+- Real-time feedback as hosts are tested
+
+### Step 5 — Smart Scale
+If you have a Bluetooth LE smart scale, configure it here:
+1. Tap **"Yes, I have a scale"** — the app scans for nearby BLE devices
+2. Tap your scale in the list (devices most likely to be scales are marked with ⭐)
+3. On selection, the app automatically writes `scale_enabled=true` and `scale_gateway_url=ws://127.0.0.1:8765` to your EverShelf server
+
+The BLE gateway runs as a built-in foreground service — **no external APK needed**.
+
+### Step 6 — Screensaver
+Choose whether the screen should go dark after inactivity.
+
+### Summary
+All done — the web app loads in full-screen kiosk mode.
+
+---
+
+## Header Overlay Buttons
+
+Three buttons are injected into the top-left of the web header by the kiosk app:
+
+| Button | Action |
+|--------|--------|
+| **✕** | Exit kiosk mode (confirmation dialog) |
+| **↻** | Hard-refresh — clears WebView cache and reloads the app |
+| **⚙️** | Open EverShelf Settings |
+
+The native Android settings button is permanently hidden once the overlay is injected — the **⚙️** web button replaces it entirely.
+
+---
+
+## Exiting Kiosk Mode
+
+Tap the **✕** button in the header overlay (top-left). A confirmation dialog appears.
+
+---
+
+## Hard Refresh
+
+Tap the **↻** button in the header to clear the WebView cache and reload the latest version of the web app.
+
+---
+
+## Update Notifications
+
+Every 6 hours the app checks GitHub releases. If a newer version is available, a banner appears with a one-tap download and install flow.
+
+---
+
+## Native TTS Bridge
+
+When Cooking Mode reads recipe steps, the kiosk app:
+1. Intercepts the TTS call from the web app via a JavaScript bridge
+2. Uses the Android `TextToSpeech` engine directly
+3. Falls back to the browser Web Speech API if the bridge is unavailable
+
+No internet connection required for TTS. No extra voice packs to install.
+
+---
+
+## SSL / Self-signed Certificates
+
+The WebView accepts self-signed certificates automatically. No configuration needed for local HTTPS servers.
+
+---
+
+## Troubleshooting
+
+### "Server non trovato" during auto-discovery
+- Make sure your tablet and server are on the same Wi-Fi network
+- Ensure the server is not on a VPN-only interface
+- Try entering the URL manually
+
+### Screen pinning / back button not working
+- Screen pinning requires the app to be set as Device Owner or the user to confirm the pin prompt
+- Some Android skins (Samsung, Xiaomi) may require additional accessibility permissions
+
+### App crashes on startup
+- Force-stop the app, clear its data (Settings → Apps → EverShelf Kiosk → Clear data), and relaunch
+
+---
+
+## Building from Source
+
+```bash
+cd evershelf-kiosk
+./gradlew assembleRelease
+# APK: app/build/outputs/apk/release/app-release.apk
+```
+
+Requires Android Studio or JDK 17+ with the Android SDK.
+
+---
+
+## Permissions
+
+| Permission | Purpose |
+|-----------|---------|
+| `INTERNET` | Load the EverShelf web app |
+| `CAMERA` | Barcode scanning and AI photo identification |
+| `RECORD_AUDIO` | Voice input in AI chat |
+| `WAKE_LOCK` | Keep the screen on |
+| `REQUEST_INSTALL_PACKAGES` | Over-the-air kiosk self-updates (installs new APK from GitHub releases) |
+| `ACCESS_WIFI_STATE` | LAN auto-discovery |
+| `REORDER_TASKS` | Bring the kiosk app to foreground when needed |

docs/wiki/Configuration.md

@@ -0,0 +1,157 @@
+# ⚙️ Configuration
+
+EverShelf is configured via a `.env` file in the project root. Copy `.env.example` to `.env` and edit it — the app reads this file on every API call.
+
+**Never commit `.env` to Git.** It is already in `.gitignore`.
+
+---
+
+## Full `.env` Reference
+
+```ini
+# ─────────────────────────────────────────────
+# AI — Google Gemini
+# ─────────────────────────────────────────────
+
+# Your Gemini API key (required for all AI features)
+# Get one free at: https://aistudio.google.com/app/apikey
+GEMINI_API_KEY=
+
+# ─────────────────────────────────────────────
+# Shopping List — Bring! Integration
+# ─────────────────────────────────────────────
+
+# Your Bring! account credentials
+# Leave blank to disable Bring! integration
+BRING_EMAIL=
+BRING_PASSWORD=
+
+# ─────────────────────────────────────────────
+# Text-to-Speech (for Cooking Mode)
+# ─────────────────────────────────────────────
+
+# URL to a TTS endpoint (e.g. Home Assistant event endpoint)
+TTS_URL=
+
+# Bearer token for the TTS endpoint
+TTS_TOKEN=
+
+# Set to true to enable server-side TTS (the browser Web Speech API is always used as fallback)
+TTS_ENABLED=false
+
+# ─────────────────────────────────────────────
+# Security
+# ─────────────────────────────────────────────
+
+# Protect the save_settings endpoint with a token
+# If set, the Settings UI will prompt for this value before saving
+# Validated with hash_equals() to prevent timing attacks
+SETTINGS_TOKEN=
+
+# ─────────────────────────────────────────────
+# Demo / Public Mode
+# ─────────────────────────────────────────────
+
+# Set to true to block ALL write operations at the PHP router level
+# Useful for public demos or read-only kiosk deployments
+# Also activatable per-request via ?demo=1 URL parameter
+DEMO_MODE=false
+
+# ─────────────────────────────────────────────
+# Scale Gateway
+# ─────────────────────────────────────────────
+
+# Enable the BLE scale integration
+SCALE_ENABLED=false
+
+# WebSocket URL of the Scale Gateway app running on the same device
+# Default for Android kiosk: ws://127.0.0.1:8765
+SCALE_GATEWAY_URL=ws://127.0.0.1:8765
+```
+
+---
+
+## Settings UI
+
+Most settings can also be configured from the browser via **Settings → ⚙️**:
+
+| Setting | `.env` key | Notes |
+|---------|-----------|-------|
+| Gemini API key | `GEMINI_API_KEY` | Stored server-side, never exposed to browser |
+| Bring! email | `BRING_EMAIL` | — |
+| Bring! password | `BRING_PASSWORD` | — |
+| TTS URL | `TTS_URL` | — |
+| TTS token | `TTS_TOKEN` | — |
+| TTS enabled | `TTS_ENABLED` | — |
+| Scale enabled | `SCALE_ENABLED` | — |
+| Scale gateway URL | `SCALE_GATEWAY_URL` | — |
+| Settings token | `SETTINGS_TOKEN` | Write-only; current value never shown |
+
+> **Security note:** `get_settings` returns only **boolean flags** (`gemini_key_set: true/false`), never raw key values. Raw values are only accessible server-side.
+
+---
+
+## Protecting Settings with a Token
+
+If your EverShelf instance is accessible from untrusted networks, set `SETTINGS_TOKEN` to a strong random string:
+
+```bash
+# Generate a strong token
+openssl rand -hex 32
+```
+
+```ini
+SETTINGS_TOKEN=a3f9b2c1d4e5...
+```
+
+Users will be prompted for this token before any Settings save. If the token doesn't match, the request is rejected with HTTP 403.
+
+---
+
+## Demo Mode
+
+Two ways to enable demo mode:
+
+1. **Permanent:** Set `DEMO_MODE=true` in `.env`
+2. **Per-session:** Append `?demo=1` to any URL (e.g. `https://evershelfproject.dadaloop.it/demo`)
+
+In demo mode:
+- All POST/write API calls return success without touching the database
+- A "DEMO" badge appears in the header
+- Gemini AI is treated as available (mock responses)
+- Bring! write operations are silently no-op'd
+- A mock pantry with sample data is loaded
+
+---
+
+## API Rate Limiting
+
+EverShelf applies file-based rate limiting to protect AI endpoints:
+
+| Tier | Limit | Endpoints |
+|------|-------|-----------|
+| Standard | 120 req/min | All general endpoints |
+| AI | 15 req/min | `gemini_*`, `generate_recipe` |
+| Strict | 5 req/min | `report_error` |
+
+Rate limit state is stored in `data/rate_limits/`. To reset, delete the files in that directory.
+
+---
+
+## Database
+
+EverShelf uses **SQLite** stored at `data/evershelf.db`. The file is created automatically on first run.
+
+Schema migrations run automatically whenever `database.php` is loaded — no manual migration steps needed.
+
+To back up the database:
+
+```bash
+cp data/evershelf.db data/backups/evershelf-$(date +%Y%m%d).db
+```
+
+Or use the included `backup.sh`:
+
+```bash
+./backup.sh
+```

docs/wiki/Contributing.md

@@ -0,0 +1,164 @@
+# 🤝 Contributing
+
+Contributions of all kinds are welcome — bug fixes, new features, translations, documentation improvements.
+
+---
+
+## Getting Started
+
+### 1. Fork and clone
+
+```bash
+git clone https://github.com/YOUR_USERNAME/EverShelf.git
+cd EverShelf
+```
+
+### 2. Create a branch
+
+```bash
+git checkout -b feature/my-feature
+# or
+git checkout -b fix/my-bug-fix
+```
+
+### 3. Set up a local server
+
+```bash
+# Option A: PHP built-in server
+php -S localhost:8080
+
+# Option B: Docker
+docker compose up -d
+```
+
+Open `http://localhost:8080` in your browser.
+
+### 4. Make your changes
+
+The app has **no build step**. Edit files directly and refresh the browser.
+
+Key files:
+- `assets/js/app.js` — all frontend logic
+- `assets/css/style.css` — all styles
+- `api/index.php` — all API endpoints
+- `api/database.php` — SQLite schema and migrations
+- `translations/*.json` — i18n strings
+
+### 5. Test
+
+```bash
+# Check PHP syntax
+php -l api/index.php
+php -l api/database.php
+
+# Check JS syntax
+node --check assets/js/app.js
+```
+
+There are no automated JS tests yet — manual testing in the browser is the current approach. If you add a feature, test the full flow: add, use, undo.
+
+### 6. Commit
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+git commit -m "feat(inventory): add bulk delete"
+git commit -m "fix(scale): handle BLE disconnect during countdown"
+git commit -m "docs: update kiosk setup guide"
+git commit -m "chore: bump version to 1.8.0"
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+Scopes: `inventory`, `ai`, `shopping`, `cooking`, `scale`, `kiosk`, `gateway`, `webapp`, `api`, `db`
+
+### 7. Push and open a PR
+
+```bash
+git push origin feature/my-feature
+```
+
+Open a Pull Request against the `develop` branch (not `main`).
+
+---
+
+## Branch Strategy
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Production — auto-deployed, never commit directly |
+| `develop` | Integration branch — all PRs target here |
+| `feature/*` | New features |
+| `fix/*` | Bug fixes |
+
+CI auto-merges `develop → main` on every push to `develop`.
+
+---
+
+## CI / CD Pipeline
+
+GitHub Actions runs on every push to `develop` and `main`:
+
+1. **PHP lint** — `php -l` on all PHP files
+2. **JS syntax check** — `node --check assets/js/app.js`
+3. **Translation validation** — checks that all language files have the same keys
+4. **Docker build** — verifies the Docker image builds successfully
+5. **Android build** — (on tagged commits) builds Kiosk and Scale Gateway APKs
+
+---
+
+## Adding Translations
+
+See the full guide in [Translations](Translations).
+
+Short version:
+1. Copy `translations/it.json` → `translations/xx.json`
+2. Translate all values
+3. Add `'xx'` to `SUPPORTED_LANGUAGES` in `app.js`
+4. Open a PR
+
+---
+
+## Reporting Bugs
+
+Open an issue on GitHub. Include:
+- Steps to reproduce
+- Expected vs. actual behaviour
+- Browser/OS version
+- Any console errors (F12 → Console)
+
+---
+
+## Code Style
+
+- **PHP:** PSR-12, 4-space indent, type hints where practical
+- **JavaScript:** ES2020+, `async/await`, no frameworks, 4-space indent
+- **CSS:** BEM-ish class names, CSS custom properties for theming
+- **SQL:** parameterized queries (PDO), no raw string interpolation
+
+---
+
+## Adding a New API Endpoint
+
+1. Add a `case 'my_action':` to the router in `api/index.php`
+2. Implement `function myAction(PDO $db): void`
+3. Add the endpoint to `docs/openapi.yaml`
+4. Add translations for any new UI strings to all 3 language files
+
+---
+
+## Security
+
+If you find a security vulnerability, **do not open a public issue**. Email [evershelfproject@gmail.com](mailto:evershelfproject@gmail.com) directly.
+
+Relevant resources:
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- All SQL must use PDO prepared statements
+- Never expose API keys in API responses (boolean flags only)
+- Use `hash_equals()` for token comparison
+
+---
+
+## License
+
+By contributing you agree that your code will be licensed under the [MIT License](https://github.com/dadaloop82/EverShelf/blob/main/LICENSE).

docs/wiki/FAQ.md

@@ -0,0 +1,162 @@
+# ❓ FAQ & Troubleshooting
+
+---
+
+## Installation
+
+### The app shows a blank page after setup
+
+- Open the browser console (F12 → Console) and check for errors
+- Make sure PHP is running and `api/index.php` is reachable: visit `https://your-server/dispensa/api/index.php?action=get_settings` — it should return JSON
+- Check your web server error log: `tail -f /var/log/apache2/error.log`
+
+### Camera doesn't work / barcode scanner won't open
+
+Camera access requires **HTTPS**. On plain HTTP, browsers block `getUserMedia()`.
+
+- Set up HTTPS with Let's Encrypt, Caddy, or a self-signed certificate
+- On Android, you can also add a security exception in Chrome: `chrome://flags/#allow-insecure-localhost`
+
+### "Permission denied" error for the data directory
+
+```bash
+chmod 755 data/
+chown -R www-data:www-data data/
+```
+
+### Docker container exits immediately
+
+```bash
+docker compose logs evershelf
+```
+
+Usually a permission issue on the mounted `data/` volume. Try:
+
+```bash
+docker compose down
+rm -rf data/
+mkdir data/
+docker compose up -d
+```
+
+---
+
+## AI Features
+
+### "AI not available" error
+
+1. Check that `GEMINI_API_KEY` is set in `.env`
+2. Verify the key is valid at [aistudio.google.com](https://aistudio.google.com)
+3. Check that you haven't exceeded the free tier quota (15 req/min, 1500 req/day)
+4. Look for errors in the PHP error log
+
+This is usually a Gemini API timeout. The app streams results via SSE — if the server PHP timeout is too low, the stream is cut short. Increase `max_execution_time` in `php.ini`:
+
+```ini
+max_execution_time = 120
+```
+
+---
+
+## Shopping List (Bring!)
+
+### "Bring! not configured" message in the shopping tab
+
+Add your Bring! credentials to `.env`:
+
+```ini
+BRING_EMAIL=your@email.com
+BRING_PASSWORD=yourpassword
+```
+
+### Items aren't syncing to Bring!
+
+- Verify your credentials are correct by logging into [getbring.com](https://web.getbring.com/)
+- Check for rate-limit errors in the PHP error log — Bring! has API limits
+
+---
+
+## Scale Integration
+
+### Scale readings don't appear in EverShelf
+
+1. Confirm the gateway app is running and shows the WebSocket URL
+2. Check the Gateway URL in EverShelf Settings matches exactly
+3. Make sure both the Android device and the EverShelf server are on the same network
+4. Look at the scale status indicator (⚖️) in the header — "disconnected" means no WebSocket connection
+
+### Scale shows weight but form doesn't auto-fill
+
+- The auto-fill only triggers for products with unit `g` or `ml`
+- Make sure you tapped **"⚖️ Read Scale"** first to activate the scale modal
+- The weight must stabilize (stay within 10g) for the countdown to start
+
+### Bluetooth scale not appearing in the gateway app
+
+- Wake up the scale (step on it or press its button)
+- Make sure Bluetooth and Location permissions are granted to the gateway app (Location is required by Android for BLE scanning)
+- Restart the gateway app
+
+---
+
+## Kiosk App
+
+### Setup wizard can't find my server
+
+- Make sure the tablet is on the same Wi-Fi network as the server
+- Try entering the URL manually instead of using auto-discovery
+- Check that the server responds on the expected port (80/443/8080/8443)
+
+### Kiosk app update fails
+
+The kiosk checks for a new release every 6 hours and downloads it from GitHub. If the install fails:
+
+| Symptom | Fix |
+|---------|-----|
+| "Install from unknown sources" dialog | Enable the setting for the EverShelf Kiosk app in Android Settings |
+| Persistent failure after download | Force-stop the app, clear its data, and relaunch the update flow |
+| Not enough space | Free up storage on the device |
+
+### Exit button (✕) is not visible
+
+Three buttons are always visible in the kiosk header overlay: **✕** (exit), **↻** (refresh), **⚙️** (settings). If the page failed to load entirely, tap **↻** first. If nothing is visible, restart the device.
+
+### App is stuck in kiosk mode after a crash
+
+Restart the device. Screen pinning is released on reboot.
+
+---
+
+## General
+
+### The version shown in the app is outdated
+
+The version is cached by the browser. Do a hard refresh:
+- Desktop: `Ctrl+Shift+R` / `Cmd+Shift+R`
+- Android: tap the ↻ button (kiosk) or clear site data in Chrome settings
+
+### Transactions are missing from the log
+
+The log shows the last 50 entries by default. Tap **"Load more"** to load more. Entries older than the database creation date won't appear.
+
+### "Can only undo transactions within 24 hours"
+
+The undo window is 24 hours. For older operations, manually correct the inventory via the Edit function on the affected product.
+
+### Error reports keep creating duplicate GitHub issues
+
+EverShelf uses a fingerprint to deduplicate — the same error from the same device won't create a new issue within 24 hours. If you're seeing duplicates, check the `data/rate_limits/` folder and clear old files.
+
+---
+
+## Getting Help
+
+- **Open an issue:** [github.com/dadaloop82/EverShelf/issues](https://github.com/dadaloop82/EverShelf/issues)
+- **Email:** [evershelfproject@gmail.com](mailto:evershelfproject@gmail.com)
+- **Try the demo:** [evershelfproject.dadaloop.it/demo](https://evershelfproject.dadaloop.it/demo)
+
+When reporting a bug, include:
+1. EverShelf version (shown in the header as `v1.x.x`)
+2. Browser and OS
+3. Steps to reproduce
+4. Any error messages from the browser console (F12)

docs/wiki/Features.md

@@ -0,0 +1,219 @@
+# ✨ Features
+
+A complete walkthrough of EverShelf's features.
+
+---
+
+## 📦 Inventory Management
+
+### Adding Products
+
+- Tap **➕** to open the add form
+- Search by name or scan a barcode
+- Select storage location: Pantry, Fridge, Freezer, or a custom location
+- Enter quantity and expiry date (or let AI estimate it)
+- Mark as vacuum-sealed or opened for adjusted shelf-life calculation
+
+### Barcode Scanning
+
+Tap the barcode icon to open the camera scanner (QuaggaJS). The app:
+1. Checks your local database first
+2. Falls back to [Open Food Facts](https://world.openfoodfacts.org/) for unknown barcodes
+3. Pre-fills the product form with name, brand, category
+
+### AI Product Identification
+
+Point the camera at any product — Gemini identifies it and:
+- Shows matching products **already in your pantry** first
+- Suggests a new product entry with pre-filled fields
+- Provides a storage location hint and estimated shelf-life
+
+### Storage Locations
+
+| Location | Icon | Notes |
+|----------|------|-------|
+| Pantry | 🏠 | Room temperature |
+| Fridge | ❄️ | Refrigerated |
+| Freezer | 🧊 | Frozen |
+| Custom | 📦 | Any name you choose |
+
+### Opened Product Tracking
+
+When you partially use a product and mark it as "opened":
+- Shelf-life is recalculated from the opening date
+- Uses AI (Gemini) + per-category rules (e.g. fish: 2 days, milk: 3 days)
+- Whole sealed packages always keep their original manufacturer expiry
+- Products with mixed whole + fractional units show as two separate entries
+
+### Vacuum-Sealed Support
+
+Mark any product as vacuum-sealed to extend its estimated expiry date (typically 2–3× the normal shelf-life).
+
+---
+
+## 🤖 AI Features (Google Gemini)
+
+All AI features require a `GEMINI_API_KEY` in `.env`. They degrade gracefully when the key is missing or quota is exceeded.
+
+### Expiry Date Reading
+
+Photograph the label on a product — Gemini extracts the expiry date and fills the field automatically.
+
+### Product Identification
+
+Camera-based identification with pantry matching. See [Adding Products](#adding-products) above.
+
+### Storage & Shelf-life Hint
+
+When adding a new product, a background Gemini call suggests:
+- Optimal storage location
+- Estimated shelf-life in days
+
+Shown as an inline AI badge next to the expiry estimate. Does not block the form.
+
+### Recipe Generation
+
+Tap **🍳 Recipes** → **Generate Recipe** to get a recipe using:
+- Ingredients about to expire (prioritised)
+- What's currently in your pantry
+- Your language preference
+
+Recipes stream live via Server-Sent Events so results appear as they are generated.
+
+### AI Chat Assistant
+
+Open **💬 Chat** to ask questions like:
+- "What can I make with eggs and pasta?"
+- "How long does cooked ham last once opened in the fridge?"
+- "Suggest a quick snack"
+
+The assistant knows your current inventory.
+
+### Shopping Suggestions with Tips
+
+Smart shopping predictions include a short AI-generated practical tip per item (e.g. "Buy the 2 kg bag — it freezes well").
+
+### Anomaly Explanation
+
+When the dashboard shows a suspicious quantity banner, tap **🤖 Spiega** to get a plain-language explanation of why the discrepancy likely occurred and what to do about it.
+
+### Model Fallback
+
+All AI endpoints try `gemini-2.5-flash` first and automatically fall back to `gemini-2.0-flash` if unavailable.
+
+---
+
+## 🛒 Shopping List (Bring! Integration)
+
+Configure `BRING_EMAIL` and `BRING_PASSWORD` in `.env` to enable.
+
+### Features
+
+- **View and manage** your Bring! list inside EverShelf
+- **Auto-add on depletion** — when stock hits zero, the product is added to Bring! automatically
+- **Auto-remove on scan** — scanning a product in removes it from the shopping list
+- **Generic names** — products are grouped by type ("Latte", "Panna da cucina") not brand, keeping the list clean
+- **Auto-migration** — items already on Bring! are silently renamed to their generic name on list load
+- **Catalog coverage** — 100+ product types mapped to Bring! catalog keys for icons and categories in the Bring! app
+- **AI fallback** — unknown product types use Gemini to determine the best generic name
+
+---
+
+## 🍳 Cooking Mode
+
+Start cooking mode from any recipe by tapping **▶ Start Cooking**.
+
+### Features
+
+- **Step-by-step guidance** — fullscreen, distraction-free interface
+- **Text-to-Speech** — each step is read aloud automatically when you navigate; supports:
+  - Browser Web Speech API (default)
+  - Native Android TTS (kiosk app)
+  - Custom REST endpoint (e.g. Home Assistant)
+- **Built-in timers** — automatic timer suggestions based on recipe text; 10-second vocal countdown warning before expiry
+- **Ingredient tracking** — mark ingredients as used; leftover quantities prompt a "move to another location" flow
+- **Recipe completion** — "Buon appetito!" *(Enjoy your meal!)* spoken on the last step
+
+---
+
+## 📊 Dashboard
+
+### Inventory Overview
+
+Three stat cards at the top show item counts for Pantry, Fridge, and Freezer with animated skeleton loading while data fetches.
+
+### Expiry Alerts Banner
+
+Priority-sorted notifications for:
+- Expired products (with safety assessment — green ✅ safe, amber 👀 check, red 🚫 danger)
+- Products expiring within 3 days
+
+Actions per item: Use, Throw away, Edit, Dismiss. Swipe or tap arrows to navigate.
+
+### Anomaly Banner
+
+Highlights suspicious quantities (e.g. "You have 0 eggs but used 12 this month"). Actions:
+- One-tap correction to the suggested quantity
+- Inline edit with free-form quantity
+- "🤖 Explain" for AI explanation
+- Dismiss (with current quantity shown: "The quantity is correct (2 pcs)")
+
+### Anti-Waste Report
+
+Shows your waste rate vs. the national average with an estimated annual kg of food wasted.
+
+### Quick Recipe Bar
+
+One-tap recipe suggestion using the ingredients closest to expiry.
+
+---
+
+## 📱 Progressive Web App (PWA)
+
+EverShelf is installable as a PWA on any device:
+
+1. Open in Chrome/Safari/Edge
+2. Tap **"Add to Home Screen"** (browser menu)
+3. Launch from the home screen like a native app
+
+Features:
+- Offline-capable shell (assets cached)
+- Full-screen mode on mobile
+- Multi-device: all data syncs via the shared server
+
+---
+
+## 🔔 Update Notifications
+
+When a new EverShelf release is published on GitHub, a small pill appears in the header. Click it to see the changelog. Checked on load and every 30 minutes.
+
+---
+
+## 🌍 Multi-language
+
+The app auto-detects your browser language. Supported: 🇮🇹 Italian, 🇬🇧 English, 🇩🇪 German.
+
+Change the language in **Settings → Language**.
+
+See [Translations](Translations) to add a new language.
+
+---
+
+## ↩ Transaction History & Undo
+
+**Settings → Storico** shows all inventory operations (adds, uses, throws).
+
+- Any operation within the **last 24 hours** shows a red ↩ undo button
+- Tapping ↩ shows a 5-second countdown confirmation before reversing the transaction
+- The original stock is restored and a counter-transaction is logged
+
+---
+
+## 🔒 Security Features
+
+- API keys never exposed to the browser (`get_settings` returns boolean flags only)
+- `save_settings` protected by optional `SETTINGS_TOKEN` (validated with `hash_equals`)
+- `DEMO_MODE=true` blocks all write operations at the PHP router level
+- Parameterized SQL queries (PDO prepared statements) throughout
+- Input validation on all inventory operations (quantity bounds, location whitelist)
+- See [Configuration](Configuration) for details

docs/wiki/Home-Assistant.md

@@ -0,0 +1,308 @@
+# Home Assistant Integration
+
+EverShelf integrates natively with [Home Assistant](https://www.home-assistant.io/) to bring your pantry data into your smart-home automations.
+
+**Capabilities:**
+- 📡 **REST sensors** — expose pantry counts as HA sensor entities (expiring, expired, shopping list, total items)
+- 🔔 **Webhooks** — trigger HA automations on pantry events (expiry alerts, shopping additions, stock updates)
+- 📣 **Push notifications** — send alerts to your phone via any HA `notify.*` service
+- 🔊 **TTS on smart speakers** — read recipe steps aloud on any HA `media_player` entity
+- ⚙️ **In-app config panel** — configure everything from Settings → 🏠 tab (no need to edit `.env` manually)
+
+---
+
+## Quick Setup
+
+1. **Generate a Long-Lived Access Token** in Home Assistant:
+   - Open HA → your **Profile** (bottom-left avatar) → **Security** → **Long-Lived Access Tokens** → **Create Token**
+   - Copy the generated token — you won't see it again.
+
+2. **Open EverShelf Settings** → tab **🏠 Home Assistant**.
+
+3. Fill in **Home Assistant URL** (e.g. `http://homeassistant.local:8123`) and paste the token.
+
+4. Click **Test connection** — you should see ✅.
+
+5. Enable the features you want (TTS, Webhooks, REST Sensors) and click **Save HA settings**.
+
+---
+
+## REST Sensors
+
+Add EverShelf pantry data as native HA sensor entities that update automatically.
+
+### Endpoints
+
+| URL | Returns | Sensor |
+|-----|---------|--------|
+| `/api/?action=ha_sensor` | Items expiring soon (≤`HA_EXPIRY_DAYS` days) | `sensor.evershelf_overview` |
+| `/api/?action=ha_sensor&sensor=expired` | Expired items count | `sensor.evershelf_expired` |
+| `/api/?action=ha_sensor&sensor=shopping` | Shopping list item count | `sensor.evershelf_shopping` |
+| `/api/?action=ha_sensor&sensor=total` | Total pantry items | `sensor.evershelf_total` |
+| `/api/?action=ha_sensor&sensor=product` | Full inventory — all items with complete details | `sensor.evershelf_products` |
+| `/api/?action=ha_sensor&sensor=product&id=42` | Full details for inventory row `id=42` | — |
+| `/api/?action=ha_sensor&sensor=product&name=milk` | Full details for items whose name contains "milk" | — |
+| `/api/?action=ha_sensor&sensor=product&location=frigo` | All items in a specific location | — |
+
+### Generate & Copy YAML
+
+In Settings → 🏠 Home Assistant → **REST Sensors** card, click **Copy YAML** to get a ready-to-paste `configuration.yaml` block that already contains your EverShelf URL.
+
+### Manual YAML example
+
+```yaml
+# configuration.yaml
+sensor:
+  - platform: rest
+    name: "EverShelf Overview"
+    unique_id: evershelf_overview
+    resource: "http://YOUR_EVERSHELF_URL/api/?action=ha_sensor"
+    scan_interval: 300        # seconds
+    value_template: "{{ value_json.state }}"
+    json_attributes:
+      - expiring_soon
+      - expiring_3d
+      - expired_items
+      - total_items
+      - shopping_items
+      - expiring_list      # full product details for expiring items
+      - expired_list       # full product details for expired items
+      - low_stock_list     # full product details for items with quantity ≤ 1
+      - next_expiry_name
+      - next_expiry_date
+      - days_to_next_expiry
+      - last_updated
+    unit_of_measurement: "items"
+
+  - platform: rest
+    name: "EverShelf Shopping Count"
+    unique_id: evershelf_shopping
+    resource: "http://YOUR_EVERSHELF_URL/api/?action=ha_sensor&sensor=shopping"
+    scan_interval: 180
+    value_template: "{{ value_json.state }}"
+    unit_of_measurement: "items"
+
+  # Full product inventory — each item includes all details (location, brand, category, …)
+  - platform: rest
+    name: "EverShelf Products"
+    unique_id: evershelf_products
+    resource: "http://YOUR_EVERSHELF_URL/api/?action=ha_sensor&sensor=product"
+    scan_interval: 600
+    value_template: "{{ value_json.state }}"
+    json_attributes:
+      - items
+      - last_updated
+    unit_of_measurement: "items"
+```
+
+Restart Home Assistant after editing `configuration.yaml`.
+
+Every product entry inside `expiring_list`, `expired_list`, `low_stock_list`, and `sensor=product` responses follows the same schema:
+
+```json
+{
+  "product_id":       42,
+  "inventory_id":     7,
+  "name":             "Latte intero",
+  "brand":            "Parmalat",
+  "category":         "Lattiero-caseari",
+  "quantity":         2.0,
+  "unit":             "conf",
+  "default_quantity": 1000.0,
+  "package_unit":     "ml",
+  "location":         "frigo",
+  "expiry_date":      "2025-06-15",
+  "days_remaining":   3,
+  "opened_at":        "2025-06-10",
+  "vacuum_sealed":    false
+}
+```
+
+Field details:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `product_id` | int | Products table ID |
+| `inventory_id` | int | Inventory row ID |
+| `name` | string | Product name |
+| `brand` | string\|null | Brand (if set) |
+| `category` | string\|null | Category (if set) |
+| `quantity` | float | Current quantity in inventory |
+| `unit` | string | Unit (`conf`, `g`, `ml`, `pz`, …) |
+| `default_quantity` | float | Default package size (e.g. 1000 for 1-litre carton) |
+| `package_unit` | string\|null | Unit of the default package (`g`, `ml`) |
+| `location` | string\|null | Storage location (`frigo`, `freezer`, `dispensa`, …) |
+| `expiry_date` | string\|null | ISO date `YYYY-MM-DD` |
+| `days_remaining` | int\|null | Days until expiry (negative = already expired) |
+| `opened_at` | string\|null | ISO date when the package was opened |
+| `vacuum_sealed` | bool | Whether the item is vacuum-sealed |
+
+---
+
+## Webhook Automations
+
+EverShelf fires an HTTP POST to your HA webhook URL when pantry events occur.
+
+### Create the HA Webhook Automation
+
+1. HA → **Settings** → **Automations & Scenes** → **Create Automation**
+2. Click **Add Trigger** → choose **Webhook**
+3. HA generates a **Webhook ID** — copy it
+4. Paste the ID into **Settings → 🏠 Home Assistant → Webhook ID**
+5. Select which events should trigger the webhook
+
+### Supported Events
+
+| Event key | When it fires |
+|-----------|--------------|
+| `expiry` | Daily cron — items expiring within `HA_EXPIRY_DAYS` days |
+| `shopping_add` | Item added to the shopping list |
+| `stock_update` | Inventory quantity changed |
+| `barcode_scan` | (reserved for future use) |
+
+### Webhook Payload (POST body)
+
+```json
+{
+  "event": "expiry_alert",
+  "timestamp": "2025-06-12T08:00:00+00:00",
+  "data": {
+    "type": "expiring_soon",
+    "count": 3,
+    "days": 3,
+    "summary": "Milk, Yogurt, Butter",
+    "items": [
+      {
+        "product_id": 42,
+        "inventory_id": 7,
+        "name": "Milk",
+        "brand": "Parmalat",
+        "category": "Dairy",
+        "quantity": 2.0,
+        "unit": "conf",
+        "default_quantity": 1000.0,
+        "package_unit": "ml",
+        "location": "frigo",
+        "expiry_date": "2025-06-14",
+        "days_remaining": 2,
+        "opened_at": "2025-06-10",
+        "vacuum_sealed": false
+      }
+    ]
+  }
+}
+```
+
+### Example: Expiry Alert → Telegram
+
+```yaml
+alias: EverShelf Expiry Alert
+trigger:
+  - platform: webhook
+    webhook_id: "evershelf_webhook_abc123"   # ← your Webhook ID
+action:
+  - service: notify.telegram_bot
+    data:
+      message: >
+        🥫 EverShelf: {{ trigger.json.data.count }} product(s) expiring soon
+        {% for item in trigger.json.data.items %}
+        — {{ item.name }}{% if item.brand %} ({{ item.brand }}){% endif %} ·
+          {{ item.quantity }} {{ item.unit }} · 📍 {{ item.location }} ·
+          expires {{ item.expiry_date }} ({{ item.days_remaining }} days)
+        {% endfor %}
+```
+
+### Example: Automation on location
+
+You can filter by location in the automation template to only alert for fridge items:
+
+```yaml
+condition:
+  - condition: template
+    value_template: >
+      {{ trigger.json.data.items | selectattr('location','eq','frigo') | list | length > 0 }}
+```
+
+---
+
+## Push Notifications
+
+If you prefer to receive push alerts without using webhooks, configure a **HA notify service** directly:
+
+1. Find your notify service name in HA: **Developer Tools → Services** → search `notify`
+2. Paste it into **Settings → 🏠 → Notify service** (e.g. `notify.mobile_app_my_phone`)
+3. Save
+
+EverShelf will call this service from the cron job whenever expiry alerts fire.
+
+---
+
+## TTS on Smart Speakers
+
+Read recipe steps aloud on an Amazon Echo, Google Home, Sonos, or any HA `media_player`.
+
+### Configuration
+
+1. Enter the **Entity ID** of your media player (e.g. `media_player.kitchen_display`)
+   - Find it in HA: **Developer Tools → States**
+2. Click **Apply HA preset to TTS tab** — this auto-fills the TTS tab with the correct HA endpoint and auth headers
+3. Save settings
+
+### How it Works
+
+When recipe step TTS is triggered, EverShelf calls:
+
+```
+POST /api/services/tts/speak
+Authorization: Bearer <HA_TOKEN>
+{
+  "entity_id": "media_player.kitchen_display",
+  "message": "Add 200 g of flour and mix well."
+}
+```
+
+The request is proxied through the EverShelf PHP backend (avoids CORS / mixed-content issues).
+
+---
+
+## Environment Variables Reference
+
+All settings are configurable from `.env` or from the in-app Settings panel.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HA_ENABLED` | `false` | Master switch for all HA features |
+| `HA_URL` | _(empty)_ | Base URL of HA instance, no trailing slash |
+| `HA_TOKEN` | _(empty)_ | Long-Lived Access Token |
+| `HA_TTS_ENTITY` | _(empty)_ | `media_player` entity for TTS |
+| `HA_WEBHOOK_ID` | _(empty)_ | Webhook trigger ID from HA automation |
+| `HA_WEBHOOK_EVENTS` | `expiry,shopping_add,stock_update` | Comma-separated list of events |
+| `HA_NOTIFY_SERVICE` | _(empty)_ | HA notify service (e.g. `notify.mobile_app_phone`) |
+| `HA_EXPIRY_DAYS` | `3` | Days before expiry to trigger the daily alert |
+
+---
+
+## Troubleshooting
+
+**Test shows ❌ "Connection failed"**
+- Verify the URL is reachable from the EverShelf server (not just your browser)
+- If using HTTPS with a self-signed certificate, the server-side cURL request may fail — use HTTP on the local network instead
+- Check that port 8123 (or your custom port) is open on the HA host
+
+**Test shows ❌ "bad_token"**
+- The Long-Lived Access Token may have expired or been revoked — generate a new one in HA Profile
+
+**Webhook not firing**
+- Confirm HA_ENABLED=true and the Webhook ID is exactly as shown in HA
+- Check the EverShelf cron is running (`/api/cron_smart_shopping.php` every 5 minutes)
+- For shopping/stock events: verify the event name is in `HA_WEBHOOK_EVENTS`
+
+**TTS not speaking**
+- Ensure the media player entity is online in HA (check its state in Developer Tools)
+- Try the "Apply HA preset to TTS tab" button and send a test from the TTS tab
+- Check HA logs for `tts.speak` errors (some platforms require `tts_options`)
+
+**Sensors show unavailable in HA**
+- The EverShelf URL must be reachable from the HA host
+- If running EverShelf behind a reverse proxy, ensure `/api/` is accessible
+- Use `scan_interval` ≥ 60 to avoid hammering the server

docs/wiki/Home.md

@@ -0,0 +1,96 @@
+# 🏠 EverShelf Wiki
+
+Welcome to the **EverShelf** project wiki — your complete reference for installation, configuration, features, and development.
+
+---
+
+## 🚀 Try it now
+
+> **[▶ Live Demo](https://evershelfproject.dadaloop.it/demo)** — no installation, no login, full AI enabled  
+> **[🌐 Project Website](https://evershelfproject.dadaloop.it/)**
+
+---
+
+## 📚 Wiki Contents
+
+| Page | Description |
+|------|-------------|
+| [Installation](Installation) | Docker, manual setup, HTTPS, web server config |
+| [Configuration](Configuration) | `.env` reference — all options explained |
+| [Features](Features) | Complete feature documentation |
+| [API Reference](API-Reference) | All REST endpoints, parameters, and responses |
+| [Android Kiosk](Android-Kiosk) | Tablet kiosk app setup and usage |
+| [Scale Gateway](Scale-Gateway) | BLE smart scale integration |
+| [Translations](Translations) | Adding and editing language files |
+| [Contributing](Contributing) | Development workflow and PR process |
+| [FAQ & Troubleshooting](FAQ) | Common issues and solutions |
+
+---
+
+## ✨ What is EverShelf?
+
+EverShelf is a **self-hosted pantry management system** that runs entirely on your own server. It:
+
+- Tracks food inventory across multiple storage locations (pantry, fridge, freezer, custom)
+- Scans barcodes and uses **Google Gemini AI** to identify products from photos
+- Suggests recipes based on what's in your pantry — especially items about to expire
+- Predicts what you'll need to buy before you run out
+- Integrates with the **Bring!** shopping list app
+- Supports a **BLE smart scale** for weight-based tracking
+- Runs as a **Progressive Web App** installable on any device
+- Optionally pairs with a dedicated **Android kiosk tablet app**
+
+All data stays on your server. No cloud, no subscriptions.
+
+---
+
+## 🆕 What's New
+
+### v1.7.13 (2026-05-16)
+- **Fix:** Kiosk Settings button (⚙️) added to the web overlay — tapping the camera button no longer accidentally opens kiosk settings
+- **Fix:** Opened-item expiry badge is now consistent with the top banner: low-risk items (jams, condiments) show amber ⚠️ "Check soon" instead of misleading red ⛔ "Expired"
+- **Cooking Mode:** 3D wheel UI with perspective card flip, ghost steps (prev/next), float animation, and full `prefers-reduced-motion` support
+- **CI:** `data/category_ai_cache.json` added to `.gitignore`
+- **Critical fix (DB):** Fresh-install crash resolved — `transactions` schema was missing the `undone` column
+
+### v1.7.12 (2026-05-13)
+- "Use first" banner now shows opening date and location instead of a confusing calculated expiry
+- "Use All / Done" in recipes no longer deletes the inventory row — uses exact quantity instead
+- Scan page fully redesigned: 2× zoom, torch, camera flip, 3 input tabs, AI Number OCR, recent products chips
+- Anomaly detection: false positives eliminated (untracked direction removed, minimum 5 txn + 7-day span)
+- AI price estimation for each Bring! shopping item with real-time dashboard total badge
+- Kiosk v1.6.0: BLE scale gateway is now built-in — no separate APK needed
+- Complete i18n: 934 keys per language
+
+→ See the full [CHANGELOG](https://github.com/dadaloop82/EverShelf/blob/main/CHANGELOG.md)
+
+---
+
+## 📦 Repository Structure
+
+```
+EverShelf/
+├── index.html                  # Single-page application entry point
+├── manifest.json               # PWA manifest
+├── .env.example                # Configuration template
+├── api/
+│   ├── index.php               # Main API router
+│   ├── database.php            # SQLite schema + migrations
+│   └── cron_smart_shopping.php # Background predictions job
+├── assets/
+│   ├── css/style.css
+│   ├── js/app.js
+│   └── img/
+├── translations/               # i18n JSON files (it, en, de)
+├── docs/openapi.yaml           # OpenAPI 3.0 spec
+├── evershelf-kiosk/            # Android kiosk app (Kotlin)
+└── evershelf-scale-gateway/    # Android BLE gateway app (Kotlin) — DEPRECATED, built into kiosk since v1.6.0
+```
+
+---
+
+## 📄 License
+
+MIT — free to use, modify, and distribute. See [LICENSE](https://github.com/dadaloop82/EverShelf/blob/main/LICENSE).
+
+**Author:** Stimpfl Daniel — [evershelfproject@gmail.com](mailto:evershelfproject@gmail.com)

docs/wiki/Installation.md

@@ -0,0 +1,233 @@
+# 📦 Installation
+
+EverShelf runs on any server with PHP 8.0+ and SQLite. Docker is the recommended approach for the fastest setup.
+
+---
+
+## Prerequisites
+
+| Requirement | Minimum | Notes |
+|-------------|---------|-------|
+| PHP | 8.0+ | Extensions: `pdo_sqlite`, `curl`, `mbstring`, `json` |
+| Web server | Apache 2.4+ or Nginx | Apache `.htaccess` included |
+| SQLite | 3.x | Bundled with PHP on most distros |
+| HTTPS | Recommended | Required for camera access on mobile browsers |
+| RAM | 256 MB | 512 MB+ recommended if using AI features |
+
+---
+
+## Option A: Docker (recommended)
+
+The fastest way to get started.
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/dadaloop82/EverShelf.git
+cd EverShelf
+
+# 2. Create your configuration
+cp .env.example .env
+nano .env          # set GEMINI_API_KEY and other options
+
+# 3. Start
+docker compose up -d
+
+# 4. Open in browser
+# → http://localhost:8080
+```
+
+The Docker image:
+- Uses PHP-Apache on Debian Bookworm slim
+- Auto-creates the `data/` directory with correct permissions
+- Exposes port `8080` by default (configurable in `docker-compose.yml`)
+- Persists data in a named Docker volume
+
+### Changing the port
+
+Edit `docker-compose.yml`:
+
+```yaml
+ports:
+  - "8080:80"   # change 8080 to your desired host port
+```
+
+### Using HTTPS with Docker
+
+Add a reverse proxy (e.g. Traefik, Caddy, or Nginx Proxy Manager) in front of the container for automatic TLS.
+
+---
+
+## Option B: Manual (Apache)
+
+```bash
+# 1. Clone into your web root
+git clone https://github.com/dadaloop82/EverShelf.git /var/www/html/dispensa
+cd /var/www/html/dispensa
+
+# 2. Create configuration
+cp .env.example .env
+nano .env
+
+# 3. Set permissions on the data directory
+chmod 755 data/
+chown -R www-data:www-data data/
+```
+
+Make sure `mod_rewrite` is enabled:
+
+```bash
+sudo a2enmod rewrite
+sudo systemctl restart apache2
+```
+
+Apache virtual host (or add to `.htaccess` which is already included):
+
+```apache
+<VirtualHost *:443>
+    ServerName evershelf.local
+    DocumentRoot /var/www/html/dispensa
+
+    <Directory /var/www/html/dispensa>
+        AllowOverride All
+        Require all granted
+    </Directory>
+
+    # Hide sensitive paths
+    <LocationMatch "^/(data|\.env|backup\.sh)">
+        Require all denied
+    </LocationMatch>
+
+    SSLEngine on
+    SSLCertificateFile    /etc/ssl/certs/evershelf.crt
+    SSLCertificateKeyFile /etc/ssl/private/evershelf.key
+</VirtualHost>
+```
+
+---
+
+## Option C: Manual (Nginx)
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name evershelf.local;
+    root /var/www/html/dispensa;
+    index index.html;
+
+    ssl_certificate     /etc/ssl/certs/evershelf.crt;
+    ssl_certificate_key /etc/ssl/private/evershelf.key;
+
+    location /api/ {
+        try_files $uri $uri/ =404;
+        location ~ \.php$ {
+            fastcgi_pass unix:/run/php/php8.2-fpm.sock;
+            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
+            include fastcgi_params;
+        }
+    }
+
+    # Block sensitive files
+    location ~ /\.env        { deny all; }
+    location ~ /data/        { deny all; }
+    location ~ /backup\.sh   { deny all; }
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}
+```
+
+---
+
+## HTTPS Setup
+
+Camera and microphone access (barcode scanning, voice) **require HTTPS** on all modern mobile browsers.
+
+### Self-signed certificate (local network)
+
+```bash
+openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
+  -keyout /etc/ssl/private/evershelf.key \
+  -out /etc/ssl/certs/evershelf.crt \
+  -subj "/CN=evershelf.local" \
+  -addext "subjectAltName=IP:192.168.1.100,DNS:evershelf.local"
+```
+
+Android will show a certificate warning — tap "Advanced → Proceed" once. The kiosk app accepts self-signed certificates automatically.
+
+### Let's Encrypt (public server)
+
+```bash
+sudo apt install certbot python3-certbot-apache
+sudo certbot --apache -d evershelf.yourdomain.com
+```
+
+### Caddy (automatic TLS)
+
+```
+evershelf.yourdomain.com {
+    root * /var/www/html/dispensa
+    php_fastcgi unix//run/php/php8.2-fpm.sock
+    file_server
+    respond /data/* 403
+    respond /.env 403
+}
+```
+
+---
+
+## Cron Job (optional)
+
+For smart shopping predictions to stay up to date:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add (runs every 5 minutes)
+*/5 * * * * php /var/www/html/dispensa/api/cron_smart_shopping.php >> /var/www/html/dispensa/data/cron.log 2>&1
+```
+
+---
+
+## Backup (optional)
+
+```bash
+# Edit crontab
+crontab -e
+
+# Daily backup at 3 AM
+0 3 * * * /var/www/html/dispensa/backup.sh
+```
+
+The `backup.sh` script copies `data/evershelf.db` to `data/backups/` with a timestamp.
+
+---
+
+## Updating
+
+```bash
+cd /var/www/html/dispensa
+git pull origin main
+# Database migrations run automatically on next page load
+```
+
+With Docker:
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+---
+
+## Post-installation
+
+Once the app is running, open it in your browser and:
+
+1. Go to **Settings** (⚙️ icon in the header)
+2. Enter your **Gemini API key** (get one free at [aistudio.google.com](https://aistudio.google.com/app/apikey))
+3. Optionally configure Bring!, TTS, and scale settings
+4. Add your first product via the ➕ button or barcode scan
+
+See [Configuration](Configuration) for the full list of settings.

docs/wiki/Scale-Gateway.md

@@ -0,0 +1,162 @@
+# ⚠️ Scale Gateway — Deprecated
+
+> **As of EverShelf Kiosk v1.6.0, BLE scale support is fully integrated into the Kiosk app.**
+> You no longer need to install or configure this separate gateway.
+>
+> 📱 **Using the EverShelf Kiosk app?** → See [Android Kiosk](Android-Kiosk) — configure your scale in Step 5 of the setup wizard.
+>
+> 💻 **Not using the kiosk app?** The legacy gateway APK below still works for non-kiosk setups, but receives no new updates.
+
+---
+
+# Scale Gateway (legacy)
+
+---
+
+## How it works
+
+```
+Smart Scale
+    │ (Bluetooth LE)
+    ▼
+Android device (Scale Gateway app)
+    │ (WebSocket — ws://127.0.0.1:8765)
+    ▼
+EverShelf Server (scale_relay.php — SSE relay)
+    │ (Server-Sent Events)
+    ▼
+EverShelf Web App (auto-fills weight in add/use forms)
+```
+
+The Gateway runs a local WebSocket server on port **8765**. The EverShelf server proxies scale readings to the browser via SSE, avoiding HTTPS→WS mixed-content issues.
+
+---
+
+## Download
+
+**[⬇ Download latest APK](https://github.com/dadaloop82/EverShelf/releases/latest/download/evershelf-scale-gateway.apk)**
+
+> Current version: **v2.1.0** — requires Android 7.0+
+
+---
+
+## Supported Scales
+
+| Protocol | BLE Service | Notes |
+|----------|------------|-------|
+| Bluetooth SIG Weight Scale | `0x181D` / char `0x2A9D` | Most compatible |
+| Bluetooth SIG Body Composition | `0x181B` / char `0x2A9C` | Weight + body fat |
+| Generic fallback | Any notifiable characteristic | Auto-heuristic for 100+ models |
+
+**Verified compatible models:**
+- Xiaomi Mi Body Composition Scale 2
+- Renpho Smart Body Fat Scale
+- Any scale supported by [openScale](https://github.com/oliexdev/openScale/wiki/Supported-scales)
+
+---
+
+## Setup
+
+### 1. Install
+
+Download and install the APK. You may need to enable "Install from unknown sources" in Android Settings.
+
+### 2. Launch the app
+
+The gateway server starts immediately. Note the **Gateway URL** shown (e.g. `ws://192.168.1.100:8765`).
+
+### 3. Configure EverShelf
+
+In EverShelf **Settings → Scale**:
+- Enable scale integration
+- Enter the Gateway URL (or let auto-discovery find it)
+
+> **Kiosk users:** this is done automatically during setup.
+
+### 4. Connect your scale
+
+Tap **"Find Bluetooth Scales"**. Make sure your scale is powered on. Tap it in the list to pair and connect.
+
+---
+
+## Using the Scale in EverShelf
+
+When scale integration is enabled:
+
+1. Open the **Add** or **Use** form for any product with unit `g` or `ml`
+2. A **"⚖️ Read Scale"** button appears
+3. Tap it — a live weight display appears with a stability indicator
+4. Step on or place the product on the scale
+5. When the reading stabilizes, a **5-second countdown** starts
+6. The weight auto-fills the quantity field and the form submits
+
+### Thresholds and de-duplication
+
+- **10g threshold** — readings that haven't changed enough between products are ignored to prevent stale readings
+- **12-second server-side dedup** — a second scale-triggered deduction of the same product within 12 seconds is rejected (guards against BLE multi-fire)
+- **ml conversion** — when the product unit is `ml`, the weight in grams is accepted and a hint is shown: "weight in grams → will be converted to ml"
+
+---
+
+## Scale Status Indicator
+
+The header of the EverShelf web app shows a real-time scale status icon (⚖️):
+
+| State | Meaning |
+|-------|---------|
+| ⚖️ green | Connected and ready |
+| ⚖️ amber | Searching / reconnecting |
+| ⚖️ grey | Disconnected |
+| ⚖️ red | Error |
+
+---
+
+## Update Notifications
+
+Every 6 hours the gateway app checks GitHub releases. If a newer version is available, a banner appears with a one-tap download and install.
+
+---
+
+## Troubleshooting
+
+### Scale not appearing in the Bluetooth list
+- Make sure BLE is enabled on the Android device
+- Step on/shake the scale to wake it up (most scales enter sleep mode quickly)
+- Some scales only advertise while someone stands on them
+
+### Weight not appearing in EverShelf
+- Confirm the Gateway URL in EverShelf Settings matches the URL shown in the gateway app
+- Check that the Android device and the EverShelf server are on the same network
+- Tap "Disconnect / Reconnect" in the gateway app to refresh the WebSocket connection
+
+### "Mixed content" error in browser
+- Make sure you are accessing EverShelf over HTTPS (not plain HTTP)
+- The SSE relay (`scale_relay.php`) handles the HTTP→WS bridging — ensure the relay script is reachable
+
+---
+
+## Building from Source
+
+```bash
+cd evershelf-scale-gateway
+./gradlew assembleRelease
+# APK: app/build/outputs/apk/release/app-release.apk
+```
+
+Requires Android Studio or JDK 17+ with the Android SDK.
+
+---
+
+## BLE Protocol Details
+
+The gateway uses the following GATT profile order:
+
+1. **Weight Scale** (`0x181D`) — standard weight only
+2. **Body Composition** (`0x181B`) — weight + additional metrics
+3. **Generic fallback** — subscribes to all notifiable characteristics and applies a heuristic parser that handles byte-order variations used by the majority of consumer smart scales
+
+Weight values are extracted in kg, converted to grams, and broadcast over WebSocket as:
+
+```json
+{ "weight_g": 1234, "stable": true, "unit": "g" }
+```

docs/wiki/Translations.md

@@ -0,0 +1,143 @@
+# 🌍 Translations
+
+EverShelf uses JSON translation files in the `translations/` folder. The app auto-detects the browser language on load and falls back to English.
+
+---
+
+## Currently Supported Languages
+
+| Language | File | Status |
+|----------|------|--------|
+| 🇮🇹 Italian | `translations/it.json` | ✅ Complete (base language) |
+| 🇬🇧 English | `translations/en.json` | ✅ Complete |
+| 🇩🇪 German | `translations/de.json` | ✅ Complete |
+
+---
+
+## Adding a New Language
+
+### 1. Copy the base file
+
+```bash
+cp translations/it.json translations/fr.json
+```
+
+### 2. Translate all values
+
+Open `fr.json` in your editor and translate every **value** (leave the **keys** unchanged).
+
+```json
+{
+  "app": {
+    "name": "EverShelf",
+    "loading": "Chargement..."   ← translate this
+  },
+  "nav": {
+    "title": "🏠 EverShelf",    ← keep emoji, translate text
+    "home": "Accueil"
+  }
+}
+```
+
+**Rules:**
+- Never change the key names (left side of `:`)
+- Keep `{placeholder}` tokens unchanged — they are replaced at runtime
+  - Example: `"toast.added": "Added {name} to {location}"` — keep `{name}` and `{location}`
+- Keep HTML tags if present (rare): `<strong>`, `<br>`
+- Keep emojis (they are part of the UX design)
+- Plurals: some keys have `_one` / `_many` variants — translate both
+
+### 3. Register the language in the app
+
+Open `assets/js/app.js` and find the `SUPPORTED_LANGUAGES` constant (near the top):
+
+```js
+const SUPPORTED_LANGUAGES = ['it', 'en', 'de'];
+```
+
+Add your language code:
+
+```js
+const SUPPORTED_LANGUAGES = ['it', 'en', 'de', 'fr'];
+```
+
+### 4. Add the language to `translations/` badge list
+
+Update the `README.md` badge:
+
+```markdown
+[![i18n](https://img.shields.io/badge/i18n-IT%20%7C%20EN%20%7C%20DE%20%7C%20FR-orange.svg)](translations/)
+```
+
+### 5. Test
+
+Open the app with `?lang=fr` in the URL to force your language:
+
+```
+http://localhost:8080/?lang=fr
+```
+
+Check for missing keys — they will show the raw key name in the UI (e.g. `nav.title`).
+
+### 6. Submit a PR
+
+Open a pull request with your new `translations/fr.json` and the updated `app.js` line. See [Contributing](Contributing).
+
+---
+
+## Translation Key Structure
+
+The file is a nested JSON object. Here are the main sections:
+
+| Section | Description |
+|---------|-------------|
+| `app` | General app strings |
+| `nav` | Navigation labels |
+| `btn` | Button labels |
+| `locations` | Storage location names |
+| `categories` | Product category names |
+| `dashboard` | Dashboard section titles |
+| `inventory` | Inventory page strings |
+| `use` | Use/consume form strings |
+| `add` | Add product form strings |
+| `scan` | Barcode scanner strings |
+| `recipes` | Recipe page strings |
+| `cooking` | Cooking mode strings |
+| `shopping` | Shopping list strings |
+| `log` | Transaction log strings |
+| `settings` | Settings page strings |
+| `scale` | Scale integration strings |
+| `toast` | Toast notification messages |
+| `error` | Error messages |
+| `confirm` | Confirmation dialog strings |
+
+---
+
+## Updating Existing Translations
+
+If a new feature adds keys to `it.json` (the base), you need to add the same keys to `en.json` and `de.json`.
+
+The CI pipeline validates that all language files contain the same keys — a missing key will fail the build.
+
+To check locally:
+
+```bash
+node -e "
+const it = require('./translations/it.json');
+const en = require('./translations/en.json');
+// flatten and compare keys...
+"
+```
+
+Or just open a PR — CI will flag any missing keys automatically.
+
+---
+
+## Language Detection Order
+
+1. `?lang=xx` URL parameter (forces a specific language)
+2. `localStorage.getItem('lang')` (last manually selected language)
+3. `navigator.language` / `navigator.languages` (browser preference)
+4. Fallback: `en`
+
+Users can change the language in **Settings → Language**.

evershelf-kiosk/README.md

@@ -0,0 +1,167 @@
+# EverShelf Kiosk
+
+Android kiosk app for wall-mounted kitchen tablets. Full-screen WebView wrapper with integrated BLE scale gateway — no external apps required.
+
+> **Version:** 1.6.0 (versionCode 10)
+> **Package:** `it.dadaloop.evershelf.kiosk`
+> **Min SDK:** Android 7.0 (API 24)
+
+---
+
+## Features
+
+### Kiosk Mode
+- **Full-screen WebView** — immersive mode hides status bar and navigation bar
+- **True kiosk lock** — screen pinning (`startLockTask`) blocks home/recent/back buttons
+- **Exit button (✕)** — visible in header, requires confirmation dialog to exit kiosk
+- **Hard refresh (↻)** — clears WebView cache to pick up web app updates instantly
+- **SSL support** — accepts self-signed certificates for local HTTPS servers
+- **Update notifications** — checks GitHub releases every 6 hours, shows auto-dismiss banner
+- **Native TTS bridge** — cooking mode voice readout uses Android TextToSpeech directly
+- **Settings activity** — change server URL, test connection, re-run setup wizard
+
+### BLE Scale Gateway (integrated, no external app)
+- **Built-in BLE gateway** — `GatewayService` foreground service handles BLE scanning and connection automatically when a scale is configured
+- **WebSocket server** — exposes scale data on `ws://127.0.0.1:8765`, fully protocol-compatible with the legacy standalone gateway app (no webapp JS changes needed)
+- **Auto-start** — service starts automatically on kiosk launch if a scale device is configured
+- **Auto-reconnect** — reconnects automatically after 8 seconds if the BLE link drops
+- **Multi-protocol** — supports Bluetooth SIG Weight Scale (`0x181D`/`0x2A9D`), Body Composition (`0x181B`/`0x2A9C`), QN/Yolanda scales, and 100+ models via generic fallback heuristic
+
+### Setup Wizard (6 steps)
+1. **Language** — choose Italian / English / German
+2. **Welcome** — intro and privacy information
+3. **Permissions** — camera, microphone, BLE permissions with in-wizard grant flow
+4. **Server URL** — enter your EverShelf URL; auto-discovery scans the LAN (60 parallel threads, ports 80/443/8080/8443)
+5. **Smart Scale** — optional: scan for BLE scales and select yours from the discovered device list (mandatory before proceeding if you choose "yes")
+6. **Screensaver** — toggle display sleep after inactivity
+
+---
+
+## Architecture
+
+```
+KioskActivity (WebView — full-screen EverShelf)
+    ├── SetupActivity (6-step wizard, shown on first launch only)
+    ├── SettingsActivity (URL, scale status, re-run wizard)
+    ├── Immersive mode (SYSTEM_UI_FLAG_IMMERSIVE_STICKY)
+    ├── Screen pinning (startLockTask / stopLockTask)
+    ├── JS bridge (_kioskBridge: exit, hardReload)
+    └── GatewayService (foreground service — BLE + WebSocket)
+            ├── BleScaleManager   — BLE scanning, GATT, auto-reconnect
+            ├── GatewayWebSocketServer — WebSocket server :8765
+            └── ScaleProtocol     — multi-protocol BLE weight parser
+```
+
+The kiosk app is fully self-contained. No separate gateway app is required.
+
+---
+
+## Setup
+
+1. Install the **EverShelf Kiosk** APK on your Android tablet
+2. Launch the app — the setup wizard starts automatically
+3. Choose your language
+4. Grant camera, microphone and Bluetooth permissions when prompted
+5. Enter your EverShelf server URL (e.g. `https://192.168.1.100/dispensa`) or use auto-discovery
+6. If you have a Bluetooth scale: tap **"Yes, I have a scale"**, wait for the BLE scan, then tap your scale in the list
+7. Done — the web app loads in full-screen kiosk mode
+
+### Scale Configuration
+
+BLE scale setup happens inside the kiosk app itself — **no external app needed**:
+
+- During the **setup wizard (step 5)**, the app scans for nearby BLE scales and shows them in a list. Devices most likely to be scales are marked with ⭐.
+- Tap a device to select it. The selection is saved and the "Next" button becomes enabled.
+- From the **Settings screen**, you can restart the BLE service or reconfigure the scale device.
+
+### Exiting Kiosk Mode
+
+Tap the **✕** button in the header. A confirmation dialog appears — tap **"Exit"** to confirm.
+
+---
+
+## Permissions
+
+| Permission | Purpose |
+|---|---|
+| `INTERNET` | Load EverShelf web app |
+| `ACCESS_NETWORK_STATE` | Check connectivity |
+| `ACCESS_WIFI_STATE` | LAN subnet detection for auto-discovery |
+| `WAKE_LOCK` | Keep screen on |
+| `CAMERA` | Barcode scanning, AI photo identification |
+| `RECORD_AUDIO` | Voice input in chat assistant |
+| `READ_MEDIA_IMAGES` / `READ_EXTERNAL_STORAGE` | Image access for AI scan |
+| `REORDER_TASKS` | Bring kiosk to foreground |
+| `BLUETOOTH` / `BLUETOOTH_ADMIN` | BLE (Android ≤ 11) |
+| `BLUETOOTH_SCAN` / `BLUETOOTH_CONNECT` | BLE scan and connect (Android 12+) |
+| `ACCESS_FINE_LOCATION` | Required for BLE scan on Android < 12 |
+| `FOREGROUND_SERVICE` | Run BLE gateway as foreground service |
+| `FOREGROUND_SERVICE_CONNECTED_DEVICE` | Service type for BLE (Android 14+) |
+
+---
+
+## Supported Scale Protocols
+
+| Protocol | Service UUID | Notes |
+|---|---|---|
+| **Bluetooth SIG Weight Scale** | `0x181D` / char `0x2A9D` | Most compatible |
+| **Bluetooth SIG Body Composition** | `0x181B` / char `0x2A9C` | Weight + body fat %, BMI |
+| **QN/Yolanda** | Custom UUIDs | Xiaomi Mi Scale 2, Renpho, etc. |
+| **Generic fallback** | Any notifiable characteristic | Auto-heuristic parsing for 100+ models |
+
+### Verified compatible scales
+- Xiaomi Mi Body Composition Scale 2
+- Renpho Smart Body Fat Scale
+- INEVIFIT Smart Body Fat Scale
+- Any [openScale-compatible scale](https://github.com/oliexdev/openScale/wiki/Supported-scales)
+
+---
+
+## WebSocket Protocol
+
+The built-in WebSocket server speaks the same protocol as the legacy standalone gateway app — the EverShelf webapp needs no changes.
+
+**Server → client:**
+```json
+{"type":"status","state":"connected","device":"Mi Scale 2","battery":85}
+{"type":"status","state":"disconnected"}
+{"type":"weight","value":72.50,"unit":"kg","stable":true,"timestamp":1712345678000}
+{"type":"pong"}
+```
+
+**Client → server:**
+```json
+{"type":"get_status"}
+{"type":"get_weight"}
+{"type":"ping"}
+```
+
+---
+
+## Building
+
+```bash
+cd evershelf-kiosk
+./gradlew assembleDebug
+# APK at app/build/outputs/apk/debug/app-debug.apk
+```
+
+For release:
+```bash
+./gradlew assembleRelease
+```
+
+---
+
+## Requirements
+
+- Android 7.0+ (API 24)
+- Bluetooth LE support (for scale integration)
+- Network access to EverShelf server
+
+---
+
+## License
+
+MIT — see [LICENSE](../LICENSE)
+

evershelf-kiosk/app/build.gradle.kts

@@ -0,0 +1,60 @@
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "it.dadaloop.evershelf.kiosk"
+    compileSdk = 35
+
+    defaultConfig {
+        applicationId = "it.dadaloop.evershelf.kiosk"
+        minSdk = 24
+        targetSdk = 35
+        versionCode = 18
+        versionName = "1.7.17"
+    }
+
+    signingConfigs {
+        // Project keystore — same on every machine so OTA updates always work.
+        create("project") {
+            storeFile = file("../evershelf.jks")
+            storePassword = "evershelf123"
+            keyAlias = "evershelf"
+            keyPassword = "evershelf123"
+        }
+    }
+
+    buildTypes {
+        debug {
+            signingConfig = signingConfigs.getByName("project")
+        }
+        release {
+            isMinifyEnabled = false
+            signingConfig = signingConfigs.getByName("project")
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
+        }
+    }
+
+    buildFeatures {
+        viewBinding = true
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_1_8
+        targetCompatibility = JavaVersion.VERSION_1_8
+    }
+    kotlinOptions {
+        jvmTarget = "1.8"
+    }
+}
+
+dependencies {
+    implementation("androidx.core:core-ktx:1.12.0")
+    implementation("androidx.appcompat:appcompat:1.6.1")
+    implementation("com.google.android.material:material:1.11.0")
+    implementation("androidx.constraintlayout:constraintlayout:2.1.4")
+    implementation("androidx.webkit:webkit:1.10.0")
+    implementation("androidx.recyclerview:recyclerview:1.3.2")
+    implementation("org.java-websocket:Java-WebSocket:1.5.5")
+}

evershelf-kiosk/app/src/main/AndroidManifest.xml

@@ -0,0 +1,99 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!-- Network -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
+
+    <!-- Keep screen on -->
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+
+    <!-- Camera & Microphone (for barcode scan, photo, voice) -->
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-feature android:name="android.hardware.camera" android:required="false" />
+    <uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />
+
+    <!-- Storage (file upload/download) -->
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" />
+    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="29" />
+    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
+
+    <!-- Move task to front -->
+    <uses-permission android:name="android.permission.REORDER_TASKS" />
+
+    <!-- Self-update: install own APK at runtime -->
+    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
+
+    <!-- ── BLE Scale Gateway (integrated) ───────────────────────────── -->
+    <!-- Legacy BLE permissions (Android ≤ 11) -->
+    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
+    <!-- Fine location required for BLE scan on Android < 12 -->
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
+    <!-- Android 12+ BLE permissions -->
+    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
+        android:usesPermissionFlags="neverForLocation"
+        tools:targetApi="s" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+    <!-- Foreground service for keeping BLE+WebSocket alive -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" />
+    <!-- BLE hardware — not required, app gracefully disables scale if absent -->
+    <uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />
+
+    <application
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:usesCleartextTraffic="true"
+        android:theme="@style/Theme.MaterialComponents.Light.NoActionBar">
+
+        <activity
+            android:name=".KioskActivity"
+            android:exported="true"
+            android:launchMode="singleTask"
+            android:configChanges="orientation|screenSize|keyboard|keyboardHidden"
+            android:windowSoftInputMode="adjustResize">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <activity
+            android:name=".SetupActivity"
+            android:exported="false"
+            android:theme="@style/Theme.MaterialComponents.Light.NoActionBar"
+            android:configChanges="orientation|screenSize|keyboard|keyboardHidden"
+            android:windowSoftInputMode="adjustResize" />
+
+        <activity
+            android:name=".SettingsActivity"
+            android:exported="false"
+            android:theme="@style/Theme.MaterialComponents.Light.NoActionBar" />
+
+        <!-- GatewayService: runs BLE scan + WebSocket server as a foreground service -->
+        <service
+            android:name=".scale.GatewayService"
+            android:exported="false"
+            android:foregroundServiceType="connectedDevice" />
+
+        <!-- FileProvider for serving the downloaded APK to the installer -->
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.provider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/file_paths" />
+        </provider>
+
+    </application>
+
+</manifest>

evershelf-kiosk/app/src/main/kotlin/it/dadaloop/evershelf/kiosk/ErrorReporter.kt

@@ -0,0 +1,354 @@
+package it.dadaloop.evershelf.kiosk
+
+import android.app.ActivityManager
+import android.app.ApplicationExitInfo
+import android.content.Context
+import android.os.Build
+import android.util.Log
+import androidx.annotation.RequiresApi
+import org.json.JSONObject
+import java.io.OutputStreamWriter
+import java.net.HttpURLConnection
+import java.net.URL
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.concurrent.Executors
+
+/**
+ * Centralized error reporter for EverShelf Kiosk.
+ *
+ * Sends structured JSON payloads to the EverShelf backend
+ * (POST /api/?action=report_error) which in turn creates or
+ * updates a GitHub Issue automatically.
+ *
+ * Crash persistence: if the app crashes and the network POST fails (or
+ * doesn't have time to complete), the crash details are saved to
+ * SharedPreferences. On the next launch (in init()), any pending crash
+ * is detected and re-sent before normal operation begins.
+ *
+ * Usage:
+ *   // In Application or Activity onCreate:
+ *   ErrorReporter.init(this, prefs.getString("evershelf_url", "")!!)
+ *
+ *   // To report a caught exception:
+ *   ErrorReporter.report(e, "myMethod", mapOf("extra" to "data"))
+ *
+ *   // To report a non-exception event:
+ *   ErrorReporter.reportMessage("webview-crash", "WebView died unexpectedly")
+ */
+object ErrorReporter {
+
+    private const val TAG = "EverShelfErrorReporter"
+
+    // SharedPreferences for crash persistence
+    private const val PREFS_NAME  = "evershelf_kiosk_errors"
+    private const val KEY_PENDING     = "pending_crash_json"
+    private const val KEY_WAS_RUNNING = "was_running_dirty"
+    private const val KEY_LAST_EXIT_TS = "last_reported_exit_ts"
+
+    private val executor = Executors.newSingleThreadExecutor()
+
+    // Fingerprints already sent in this process to avoid flooding
+    private val sentFingerprints = mutableSetOf<String>()
+
+    private var serverBaseUrl: String = ""
+    private var appVersion: String = ""
+    private var deviceInfo: String = ""
+    private lateinit var appContext: Context
+
+    /**
+     * Call once (e.g. in KioskActivity.onCreate) before reporting any errors.
+     * @param context   Application or Activity context.
+     * @param baseUrl   The EverShelf server URL, e.g. "http://192.168.1.10:8080"
+     */
+    fun init(context: Context, baseUrl: String) {
+        appContext = context.applicationContext
+        serverBaseUrl = baseUrl.trimEnd('/')
+        try {
+            val pi = context.packageManager.getPackageInfo(context.packageName, 0)
+            appVersion = pi.versionName ?: "unknown"
+        } catch (_: Exception) {}
+        deviceInfo = buildString {
+            val mfr   = Build.MANUFACTURER.takeIf { it.isNotBlank() && it != "unknown" }
+                ?: Build.PRODUCT.takeIf { it.isNotBlank() && it != "unknown" }
+                ?: Build.BOARD
+            val model = Build.MODEL.takeIf { it.isNotBlank() && it != "unknown" }
+                ?: Build.HARDWARE
+            append("$mfr $model (Android ${Build.VERSION.RELEASE}/${Build.VERSION.SDK_INT})")
+        }
+
+        // Send any crash that was saved to prefs during a previous session
+        sendPendingCrash()
+
+        // Detect ANR / OOM / native crashes from the previous run
+        detectPreviousCrash()
+
+        // Install a global UncaughtExceptionHandler so ANY unhandled crash is reported
+        val previousHandler = Thread.getDefaultUncaughtExceptionHandler()
+        Thread.setDefaultUncaughtExceptionHandler { thread, throwable ->
+            try {
+                val type    = "uncaught-exception"
+                val message = throwable.message ?: throwable.javaClass.simpleName
+                val stack   = throwable.stackTraceToString()
+                val ctx     = mapOf("thread" to thread.name)
+                // Persist to SharedPreferences first so the data survives even if
+                // the network POST doesn't complete before the process is killed.
+                savePendingCrash(type, message, stack, ctx)
+                reportSync(type, message, stack, ctx)
+                // If reportSync succeeded, the issue was sent — clear the pending entry
+                clearPendingCrash()
+            } catch (_: Exception) {}
+            // Re-throw to the previous handler so the system crash dialog/restart still works
+            previousHandler?.uncaughtException(thread, throwable)
+        }
+    }
+
+    /**
+     * Call from Activity.onDestroy() on a *clean* exit (back-pressed, settings, shutdown).
+     * Clears the dirty-launch sentinel so the next start does not report a false positive.
+     */
+    fun markCleanStop() {
+        if (::appContext.isInitialized) {
+            appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .edit().putBoolean(KEY_WAS_RUNNING, false).apply()
+        }
+    }
+
+    /**
+     * Report a caught [Throwable] asynchronously (does not block UI thread).
+     */
+    fun report(
+        throwable: Throwable,
+        location: String = "",
+        extra: Map<String, Any?> = emptyMap()
+    ) {
+        val ctx = mutableMapOf<String, Any?>("device" to deviceInfo)
+        if (location.isNotEmpty()) ctx["location"] = location
+        ctx.putAll(extra)
+        reportAsync(
+            type    = "kiosk-exception",
+            message = "${throwable.javaClass.simpleName}: ${throwable.message}",
+            stack   = throwable.stackTraceToString(),
+            context = ctx
+        )
+    }
+
+    /**
+     * Report a non-exception message (e.g. WebView page error, network failure).
+     * @param forceReport if true, bypasses the in-session dedup so retries are always sent.
+     */
+    fun reportMessage(
+        type: String,
+        message: String,
+        extra: Map<String, Any?> = emptyMap(),
+        forceReport: Boolean = false
+    ) {
+        val ctx = mutableMapOf<String, Any?>("device" to deviceInfo)
+        ctx.putAll(extra)
+        reportAsync(type = type, message = message, stack = "", context = ctx, force = forceReport)
+    }
+
+    // ── Internal ─────────────────────────────────────────────────────────────
+
+    /**
+     * Detects whether the *previous* run of the app ended with a crash, ANR or OOM kill.
+     *
+     * On Android 11+ (API 30) we use [ActivityManager.getHistoricalProcessExitReasons] which
+     * gives the exact reason and (for Java crashes) a stack trace.
+     *
+     * On Android 7–10 we use a "dirty-launch sentinel": a boolean in SharedPreferences that is
+     * set to `true` on every start and `false` only when the activity is destroyed cleanly via
+     * [markCleanStop]. If it is still `true` on the next start, the previous run was not clean.
+     */
+    private fun detectPreviousCrash() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            detectExitReasonApi30()
+        } else {
+            // API 24–29: dirty-launch sentinel
+            val prefs = appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            if (prefs.getBoolean(KEY_WAS_RUNNING, false)) {
+                reportAsync(
+                    type    = "crash-sentinel",
+                    message = "App was not cleanly shut down on previous run (ANR / OOM / native crash suspected).",
+                    stack   = "",
+                    context = mapOf(
+                        "device" to deviceInfo,
+                        "note"   to "Detected via dirty-launch sentinel (API ${Build.VERSION.SDK_INT})"
+                    )
+                )
+            }
+        }
+        // Mark this launch as running — will be cleared by markCleanStop() on clean exit
+        appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            .edit().putBoolean(KEY_WAS_RUNNING, true).apply()
+    }
+
+    @RequiresApi(Build.VERSION_CODES.R)
+    private fun detectExitReasonApi30() {
+        try {
+            val am = appContext.getSystemService(ActivityManager::class.java) ?: return
+            // Check the last 5 exits; stop at the first we already reported
+            val exits = am.getHistoricalProcessExitReasons(null, 0, 5)
+            if (exits.isEmpty()) return
+
+            val prefs         = appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            val lastReportedTs = prefs.getLong(KEY_LAST_EXIT_TS, 0L)
+
+            val crashReasons = setOf(
+                ApplicationExitInfo.REASON_CRASH,
+                ApplicationExitInfo.REASON_CRASH_NATIVE,
+                ApplicationExitInfo.REASON_ANR,
+                ApplicationExitInfo.REASON_LOW_MEMORY
+            )
+
+            var newestTs = lastReportedTs
+            for (exit in exits) {
+                if (exit.timestamp <= lastReportedTs) continue     // already reported
+                if (exit.reason !in crashReasons) continue
+
+                val reasonName = when (exit.reason) {
+                    ApplicationExitInfo.REASON_CRASH        -> "crash-java"
+                    ApplicationExitInfo.REASON_CRASH_NATIVE -> "crash-native"
+                    ApplicationExitInfo.REASON_ANR          -> "anr"
+                    ApplicationExitInfo.REASON_LOW_MEMORY   -> "oom-kill"
+                    else                                    -> "exit-${exit.reason}"
+                }
+                val msg = exit.description?.takeIf { it.isNotEmpty() }
+                    ?: "${exit.processName ?: "app"} terminated (reason ${exit.reason})"
+
+                // Java crashes include a tombstone trace — read up to 4KB
+                var stack = ""
+                try {
+                    exit.traceInputStream?.bufferedReader()?.use { stack = it.readText().take(4000) }
+                } catch (_: Exception) {}
+
+                val ctx = mutableMapOf<String, Any?>(
+                    "device"  to deviceInfo,
+                    "reason"  to exit.reason,
+                    "process" to (exit.processName ?: ""),
+                    "crash_ts" to SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.US).format(Date(exit.timestamp)),
+                    "note"    to "Detected via ApplicationExitInfo on restart (API ${Build.VERSION.SDK_INT})"
+                )
+                reportAsync(type = reasonName, message = msg, stack = stack, context = ctx)
+
+                if (exit.timestamp > newestTs) newestTs = exit.timestamp
+            }
+
+            if (newestTs > lastReportedTs) {
+                prefs.edit().putLong(KEY_LAST_EXIT_TS, newestTs).apply()
+            }
+        } catch (_: Exception) {}
+    }
+
+    private fun fingerprint(type: String, message: String): String {
+        val key = "$type:${message.take(120)}"
+        return key.hashCode().toString(16)
+    }
+
+    private fun reportAsync(type: String, message: String, stack: String, context: Map<String, Any?>, force: Boolean = false) {
+        val fp = fingerprint(type, message)
+        if (!force) {
+            synchronized(sentFingerprints) {
+                if (!sentFingerprints.add(fp)) return // already reported this session
+            }
+        } else {
+            synchronized(sentFingerprints) { sentFingerprints.add(fp) }
+        }
+        executor.execute { doPost(type, message, stack, context) }
+    }
+
+    /** Synchronous variant used only in the UncaughtExceptionHandler (already off main thread). */
+    private fun reportSync(type: String, message: String, stack: String, context: Map<String, Any?>) {
+        val fp = fingerprint(type, message)
+        synchronized(sentFingerprints) { sentFingerprints.add(fp) }
+        doPost(type, message, stack, context)
+    }
+
+    // ── Crash persistence helpers ─────────────────────────────────────────────
+
+    private fun savePendingCrash(type: String, message: String, stack: String, context: Map<String, Any?>) {
+        try {
+            val ctxJson = JSONObject()
+            context.forEach { (k, v) -> ctxJson.put(k, v) }
+            val payload = JSONObject().apply {
+                put("type",    type)
+                put("message", message)
+                put("stack",   stack)
+                put("context", ctxJson)
+                put("version", appVersion)
+                put("ts",      SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.US).format(Date()))
+            }
+            appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .edit().putString(KEY_PENDING, payload.toString()).apply()
+        } catch (_: Exception) {}
+    }
+
+    private fun clearPendingCrash() {
+        appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            .edit().remove(KEY_PENDING).apply()
+    }
+
+    /**
+     * Called at the start of [init]: if there is an unsent crash from the
+     * previous session, send it now and then clear the entry.
+     */
+    private fun sendPendingCrash() {
+        val json = appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            .getString(KEY_PENDING, null) ?: return
+        // Clear immediately so we don't re-send if THIS launch also crashes
+        clearPendingCrash()
+        executor.execute {
+            try {
+                val p       = JSONObject(json)
+                val type    = p.optString("type", "uncaught-exception")
+                val message = p.optString("message", "")
+                val stack   = p.optString("stack", "")
+                val savedTs = p.optString("ts", "")
+                val ctxJson = p.optJSONObject("context") ?: JSONObject()
+                val ctx     = mutableMapOf<String, Any?>("note" to "Sent on next launch after crash")
+                if (savedTs.isNotEmpty()) ctx["crash_ts"] = savedTs
+                ctxJson.keys().forEach { k -> ctx[k] = ctxJson.opt(k) }
+                doPost("$type-survived", message, stack, ctx)
+            } catch (_: Exception) {}
+        }
+    }
+
+    private fun doPost(type: String, message: String, stack: String, context: Map<String, Any?>) {
+        val url = serverBaseUrl.ifEmpty { return }
+        val endpoint = "$url/api/?action=report_error"
+        try {
+            val ctxJson = JSONObject()
+            context.forEach { (k, v) -> ctxJson.put(k, v) }
+
+            val payload = JSONObject().apply {
+                put("source",     "kiosk")
+                put("type",       type)
+                put("message",    message)
+                put("stack",      stack)
+                put("context",    ctxJson)
+                put("version",    appVersion)
+                put("user_agent", "EverShelf-Kiosk/$appVersion (Android ${Build.VERSION.RELEASE}; ${Build.MODEL})")
+                put("url",        url)
+                put("ts",         SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.US).format(Date()))
+            }
+
+            val conn = URL(endpoint).openConnection() as HttpURLConnection
+            conn.requestMethod = "POST"
+            conn.setRequestProperty("Content-Type", "application/json; charset=utf-8")
+            conn.setRequestProperty("Accept", "application/json")
+            conn.doOutput = true
+            conn.connectTimeout = 8000
+            conn.readTimeout    = 8000
+
+            OutputStreamWriter(conn.outputStream, Charsets.UTF_8).use { it.write(payload.toString()) }
+            val responseCode = conn.responseCode
+            conn.disconnect()
+
+            Log.d(TAG, "Reported '$type' → HTTP $responseCode")
+        } catch (e: Exception) {
+            // Never rethrow from the error reporter itself
+            Log.w(TAG, "Failed to report error '$type': ${e.message}")
+        }
+    }
+}

evershelf-kiosk/app/src/main/kotlin/it/dadaloop/evershelf/kiosk/SettingsActivity.kt

@@ -0,0 +1,218 @@
+package it.dadaloop.evershelf.kiosk
+
+import android.content.Context
+import android.content.Intent
+import android.content.SharedPreferences
+import android.os.Build
+import android.os.Bundle
+import android.view.WindowManager
+import android.widget.EditText
+import android.widget.TextView
+import android.widget.Toast
+import androidx.appcompat.app.AppCompatActivity
+import com.google.android.material.button.MaterialButton
+import com.google.android.material.switchmaterial.SwitchMaterial
+import it.dadaloop.evershelf.kiosk.scale.GatewayService
+import java.net.URL
+import javax.net.ssl.HttpsURLConnection
+import javax.net.ssl.SSLContext
+import javax.net.ssl.TrustManager
+import javax.net.ssl.X509TrustManager
+
+class SettingsActivity : AppCompatActivity() {
+
+    private lateinit var prefs: SharedPreferences
+    private lateinit var urlEdit: EditText
+
+    companion object {
+        private const val PREFS_NAME = "evershelf_kiosk"
+        private const val KEY_URL = "evershelf_url"
+        private const val KEY_SETUP_COMPLETE = "setup_complete"
+        private const val KEY_SCREENSAVER = "screensaver_enabled"
+        private const val KEY_HAS_SCALE = "has_scale"
+    }
+
+    override fun attachBaseContext(newBase: Context) {
+        val lang = newBase.getSharedPreferences("evershelf_kiosk", Context.MODE_PRIVATE)
+            .getString("kiosk_language", null)
+        super.attachBaseContext(if (lang != null) SetupActivity.applyLocale(newBase, lang) else newBase)
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_settings)
+
+        prefs = getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        urlEdit = findViewById(R.id.urlEdit)
+
+        urlEdit.setText(prefs.getString(KEY_URL, "") ?: "")
+
+        // Screensaver toggle (default OFF = keep screen on)
+        val switchScreensaver = findViewById<SwitchMaterial>(R.id.switchScreensaver)
+        switchScreensaver.isChecked = prefs.getBoolean(KEY_SCREENSAVER, false)
+
+        // ── Smart Scale (BLE gateway service) ──────────────────────────────
+        val hasScale    = prefs.getBoolean(KEY_HAS_SCALE, false)
+        val deviceName  = prefs.getString("scale_device_name", null)
+        val deviceAddr  = prefs.getString("scale_device_address", null)
+        val statusView  = findViewById<TextView>(R.id.scaleGatewayStatus)
+        val deviceView  = findViewById<TextView>(R.id.scaleDeviceInfo)
+        val btnScaleAction = findViewById<MaterialButton>(R.id.btnConfigureGateway)
+        val btnReconfigureScale = findViewById<MaterialButton>(R.id.btnReconfigureScale)
+
+        when {
+            !hasScale || deviceAddr == null -> {
+                statusView.text = "Non configurata"
+                statusView.setTextColor(0xFF94a3b8.toInt())
+                deviceView.text = "Nessuna bilancia configurata — riesegui il wizard per aggiungerne una"
+                btnScaleAction.visibility = android.view.View.VISIBLE
+                btnScaleAction.text = "⚙️  Configura bilancia"
+                btnScaleAction.setOnClickListener {
+                    prefs.edit().putBoolean(KEY_SETUP_COMPLETE, false).apply()
+                    startActivity(Intent(this, SetupActivity::class.java))
+                    finish()
+                }
+            }
+            else -> {
+                statusView.text = "Configurata"
+                statusView.setTextColor(0xFF34d399.toInt())
+                deviceView.text = deviceName ?: deviceAddr
+                btnScaleAction.visibility = android.view.View.VISIBLE
+                btnScaleAction.text = "🔄  Riavvia servizio bilancia"
+                btnScaleAction.setOnClickListener {
+                    GatewayService.stop(this)
+                    GatewayService.start(this)
+                    Toast.makeText(this, "Servizio bilancia riavviato", Toast.LENGTH_SHORT).show()
+                }
+                btnReconfigureScale.visibility = android.view.View.VISIBLE
+                btnReconfigureScale.setOnClickListener {
+                    GatewayService.stop(this)
+                    prefs.edit()
+                        .remove("scale_device_address")
+                        .remove("scale_device_name")
+                        .putBoolean(KEY_HAS_SCALE, false)
+                        .putBoolean(KEY_SETUP_COMPLETE, false)
+                        .apply()
+                    val intent = Intent(this, SetupActivity::class.java)
+                    intent.putExtra("start_step", 4)
+                    startActivity(intent)
+                    finish()
+                }
+                // Probe WebSocket port to show live status
+                Thread {
+                    val running = try {
+                        java.net.Socket().use { s ->
+                            s.connect(java.net.InetSocketAddress("127.0.0.1", 8765), 1200); true
+                        }
+                    } catch (_: Exception) { false }
+                    runOnUiThread {
+                        if (running) {
+                            statusView.text = "Attivo ✅"
+                            statusView.setTextColor(0xFF34d399.toInt())
+                            deviceView.text = "${deviceName ?: "Bilancia"} — ws://127.0.0.1:8765"
+                        } else {
+                            statusView.text = "Non avviato ⚠️"
+                            statusView.setTextColor(0xFFfbbf24.toInt())
+                            deviceView.text = "${deviceName ?: "Bilancia"} — servizio non in esecuzione"
+                        }
+                    }
+                }.start()
+            }
+        }
+
+        // Back
+        findViewById<android.widget.ImageButton>(R.id.btnBack).setOnClickListener { finish() }
+
+        // Advanced settings → back to webapp (where HA, Gemini, Bring! etc. are configured)
+        findViewById<MaterialButton>(R.id.btnOpenAppSettings).setOnClickListener { finish() }
+
+        // Test connection
+        findViewById<MaterialButton>(R.id.btnTestConnection).setOnClickListener { testConnection() }
+
+        // Run wizard again
+        findViewById<MaterialButton>(R.id.btnRunWizard).setOnClickListener {
+            prefs.edit().putBoolean(KEY_SETUP_COMPLETE, false).apply()
+            startActivity(Intent(this, SetupActivity::class.java))
+            finish()
+        }
+
+        // Save
+        findViewById<MaterialButton>(R.id.btnSave).setOnClickListener {
+            val url = urlEdit.text.toString().trim()
+            if (url.isEmpty()) {
+                Toast.makeText(this, "URL cannot be empty", Toast.LENGTH_SHORT).show()
+                return@setOnClickListener
+            }
+            val screensaverOn = switchScreensaver.isChecked
+            prefs.edit()
+                .putString(KEY_URL, url)
+                .putBoolean(KEY_SCREENSAVER, screensaverOn)
+                .apply()
+            // Screen always stays on in kiosk mode — no FLAG_KEEP_SCREEN_ON change needed here.
+            // Push screensaver preference to the webapp so the in-app clock overlay is toggled.
+            Thread {
+                try {
+                    val apiUrl = "$url/api/index.php?action=save_settings"
+                    val body   = "{\"screensaver_enabled\":$screensaverOn}"
+                    val conn   = (java.net.URL(apiUrl).openConnection() as java.net.HttpURLConnection).apply {
+                        requestMethod = "POST"
+                        setRequestProperty("Content-Type", "application/json")
+                        connectTimeout = 5000
+                        readTimeout    = 5000
+                        doOutput = true
+                    }
+                    conn.outputStream.use { it.write(body.toByteArray()) }
+                    conn.inputStream.close()
+                    conn.disconnect()
+                } catch (_: Exception) {}
+            }.start()
+            Toast.makeText(this, "Impostazioni salvate", Toast.LENGTH_SHORT).show()
+            finish()
+        }
+    }
+
+    private fun testConnection() {
+        val url = urlEdit.text.toString().trim()
+        if (url.isEmpty()) {
+            Toast.makeText(this, "Enter a URL first", Toast.LENGTH_SHORT).show()
+            return
+        }
+
+        Thread {
+            try {
+                val conn = URL(url).openConnection()
+
+                if (conn is HttpsURLConnection) {
+                    val trustAll = arrayOf<TrustManager>(object : X509TrustManager {
+                        override fun checkClientTrusted(chain: Array<java.security.cert.X509Certificate>?, authType: String?) {}
+                        override fun checkServerTrusted(chain: Array<java.security.cert.X509Certificate>?, authType: String?) {}
+                        override fun getAcceptedIssuers(): Array<java.security.cert.X509Certificate> = arrayOf()
+                    })
+                    val sc = SSLContext.getInstance("TLS")
+                    sc.init(null, trustAll, java.security.SecureRandom())
+                    conn.sslSocketFactory = sc.socketFactory
+                    conn.hostnameVerifier = javax.net.ssl.HostnameVerifier { _, _ -> true }
+                }
+
+                conn.connectTimeout = 5000
+                conn.readTimeout = 5000
+                if (conn is java.net.HttpURLConnection) {
+                    conn.requestMethod = "GET"
+                    val code = conn.responseCode
+                    conn.disconnect()
+                    runOnUiThread {
+                        if (code in 200..399) {
+                            Toast.makeText(this, "✓ Connection successful!", Toast.LENGTH_SHORT).show()
+                        } else {
+                            Toast.makeText(this, "⚠ Server responded: $code", Toast.LENGTH_SHORT).show()
+                        }
+                    }
+                }
+            } catch (e: Exception) {
+                runOnUiThread {
+                    Toast.makeText(this, "✗ Cannot reach server", Toast.LENGTH_SHORT).show()
+                }
+            }
+        }.start()
+    }
+}

evershelf-kiosk/app/src/main/kotlin/it/dadaloop/evershelf/kiosk/scale/BleScaleManager.kt

@@ -0,0 +1,295 @@
+package it.dadaloop.evershelf.kiosk.scale
+
+import android.Manifest
+import android.bluetooth.*
+import android.bluetooth.le.*
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import androidx.core.content.ContextCompat
+
+private const val TAG = "BleScaleManager"
+private const val SCAN_PERIOD_MS = 20_000L
+private const val PREFS_NAME = "evershelf_kiosk"
+private const val PREF_SCALE_ADDRESS = "scale_device_address"
+private const val PREF_SCALE_NAME    = "scale_device_name"
+
+data class BleDeviceInfo(
+    val device: BluetoothDevice,
+    val name: String,
+    val rssi: Int,
+    val proximity: String,
+    val scaleScore: Int,
+)
+
+interface BleScaleListener {
+    fun onDeviceFound(info: BleDeviceInfo)
+    fun onConnecting(device: BluetoothDevice)
+    fun onConnected(deviceName: String)
+    fun onDisconnected()
+    fun onWeightReceived(reading: WeightReading)
+    fun onBatteryReceived(level: Int)
+    fun onError(message: String)
+    fun onScanStopped()
+    fun onDebugEvent(message: String)
+}
+
+class BleScaleManager(
+    private val context: Context,
+    private val listener: BleScaleListener,
+) {
+    private val bluetoothManager = context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
+    private val bluetoothAdapter: BluetoothAdapter? get() = bluetoothManager.adapter
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    private var leScanner: BluetoothLeScanner? = null
+    private var gatt: BluetoothGatt? = null
+    private var isScanning = false
+    private var connectedDeviceName: String = ""
+    private var autoConnectAddress: String? = null
+    private val pendingSubscriptions = ArrayDeque<BluetoothGattCharacteristic>()
+
+    val isConnected: Boolean get() = gatt != null && connectedDeviceName.isNotEmpty()
+
+    fun getSavedDeviceAddress(): String? =
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            .getString(PREF_SCALE_ADDRESS, null)
+
+    fun getSavedDeviceName(): String? =
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            .getString(PREF_SCALE_NAME, null)
+
+    fun saveDevice(address: String, name: String) {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            .edit()
+            .putString(PREF_SCALE_ADDRESS, address)
+            .putString(PREF_SCALE_NAME, name)
+            .apply()
+    }
+
+    fun clearSavedDevice() {
+        context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+            .edit()
+            .remove(PREF_SCALE_ADDRESS)
+            .remove(PREF_SCALE_NAME)
+            .apply()
+    }
+
+    fun enableAutoConnect() {
+        autoConnectAddress = getSavedDeviceAddress()
+    }
+
+    fun hasRequiredPermissions(): Boolean {
+        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            ContextCompat.checkSelfPermission(context, Manifest.permission.BLUETOOTH_SCAN) == PackageManager.PERMISSION_GRANTED &&
+            ContextCompat.checkSelfPermission(context, Manifest.permission.BLUETOOTH_CONNECT) == PackageManager.PERMISSION_GRANTED
+        } else {
+            ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
+        }
+    }
+
+    fun startScan() {
+        val adapter = bluetoothAdapter ?: run { listener.onError("Bluetooth non disponibile"); return }
+        if (!adapter.isEnabled) { listener.onError("Bluetooth disabilitato"); return }
+        if (isScanning) stopScan()
+        leScanner = adapter.bluetoothLeScanner
+        val settings = ScanSettings.Builder().setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY).build()
+        isScanning = true
+        try { leScanner?.startScan(null, settings, scanCallback) }
+        catch (_: Exception) { leScanner?.startScan(scanCallback) }
+        mainHandler.postDelayed({ stopScan(); listener.onScanStopped() }, SCAN_PERIOD_MS)
+    }
+
+    fun stopScan() {
+        if (!isScanning) return
+        isScanning = false
+        try { leScanner?.stopScan(scanCallback) } catch (_: Exception) {}
+        leScanner = null
+    }
+
+    private val scanCallback = object : ScanCallback() {
+        override fun onScanResult(callbackType: Int, result: ScanResult) {
+            val device = result.device
+            val name = result.scanRecord?.deviceName?.takeIf { it.isNotBlank() }
+                ?: try { device.name?.takeIf { it.isNotBlank() } } catch (_: SecurityException) { null }
+                ?: return  // skip unnamed devices
+            val score = scoreLikelyScale(name, result.scanRecord)
+            val info  = BleDeviceInfo(device, name, result.rssi, rssiToProximity(result.rssi), score)
+            mainHandler.post { listener.onDeviceFound(info) }
+            if (autoConnectAddress != null && device.address == autoConnectAddress && !isConnected) {
+                autoConnectAddress = null
+                mainHandler.post { connect(device) }
+            }
+        }
+        override fun onScanFailed(errorCode: Int) {
+            isScanning = false
+            mainHandler.post { listener.onError("BLE scan failed (code $errorCode)") }
+        }
+    }
+
+    private fun rssiToProximity(rssi: Int) = when {
+        rssi >= -60 -> "📶 Vicino"
+        rssi >= -80 -> "📶 Medio"
+        else        -> "📶 Lontano"
+    }
+
+    private fun scoreLikelyScale(name: String, scanRecord: ScanRecord?): Int {
+        var score = 0
+        val lower = name.lowercase()
+        val foodKeywords = listOf("scale","bilancia","kitchen","food","cucina","coffee","caffe",
+            "balance","weight","waage","arboleaf","ck10","ck20","ek-","acaia","felicita",
+            "timemore","brewista","hario","ozeri","etekcity","nutri","nicewell","koios","renpho")
+        if (foodKeywords.any { lower.contains(it) }) score += 10
+        val bodyKeywords = listOf("body","fat","bmi","composition","fitness","mi body","lepulse")
+        if (bodyKeywords.any { lower.contains(it) }) score -= 5
+        scanRecord?.serviceUuids?.let { uuids ->
+            val us = uuids.map { it.uuid.toString().lowercase() }
+            if (us.any { it.startsWith("0000181d") }) score += 15
+            if (us.any { it.startsWith("0000ffe0") || it.startsWith("0000fff0") }) score += 10
+            if (us.any { it.startsWith("49535343") }) score += 20
+            if (us.any { it.startsWith("0000181b") }) score -= 10
+        }
+        return score
+    }
+
+    fun connect(device: BluetoothDevice) {
+        stopScan()
+        disconnect()
+        connectedDeviceName = ""
+        ScaleProtocol.resetState()
+        mainHandler.post { listener.onConnecting(device) }
+        try {
+            gatt = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
+                device.connectGatt(context, false, gattCallback, BluetoothDevice.TRANSPORT_LE)
+            } else {
+                device.connectGatt(context, false, gattCallback)
+            }
+        } catch (e: SecurityException) {
+            mainHandler.post { listener.onError("Permesso mancante: ${e.message}") }
+        }
+    }
+
+    fun disconnect() {
+        pendingSubscriptions.clear()
+        try { gatt?.disconnect(); gatt?.close() } catch (_: Exception) {}
+        gatt = null
+        connectedDeviceName = ""
+    }
+
+    private val gattCallback = object : BluetoothGattCallback() {
+        override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
+            when (newState) {
+                BluetoothProfile.STATE_CONNECTED -> {
+                    mainHandler.postDelayed({ gatt.discoverServices() }, 500)
+                }
+                BluetoothProfile.STATE_DISCONNECTED -> {
+                    this@BleScaleManager.gatt?.close()
+                    this@BleScaleManager.gatt = null
+                    connectedDeviceName = ""
+                    mainHandler.post { listener.onDisconnected() }
+                }
+            }
+        }
+
+        override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
+            if (status != BluetoothGatt.GATT_SUCCESS) {
+                mainHandler.post { listener.onError("Servizi GATT non trovati") }
+                return
+            }
+            val targetChars = mutableListOf<BluetoothGattCharacteristic>()
+            gatt.getService(BleUuids.WEIGHT_SCALE_SERVICE)?.getCharacteristic(BleUuids.WEIGHT_MEASUREMENT_CHAR)?.let { targetChars.add(it) }
+            gatt.getService(BleUuids.FFE0)?.getCharacteristic(BleUuids.FFE1)?.let { targetChars.add(it) }
+            gatt.getService(BleUuids.FFF0)?.let { svc ->
+                svc.getCharacteristic(BleUuids.FFF4)?.let { targetChars.add(it) }
+                    ?: svc.getCharacteristic(BleUuids.FFF1)?.let { targetChars.add(it) }
+            }
+            gatt.getService(BleUuids.ACAIA_SERVICE)?.getCharacteristic(BleUuids.ACAIA_CHAR)?.let { targetChars.add(it) }
+            if (targetChars.isEmpty()) {
+                for (service in gatt.services) {
+                    if (service.uuid.toString().startsWith("00001800") || service.uuid.toString().startsWith("00001801")) continue
+                    for (char in service.characteristics) {
+                        val props = char.properties
+                        if ((props and BluetoothGattCharacteristic.PROPERTY_NOTIFY) != 0 ||
+                            (props and BluetoothGattCharacteristic.PROPERTY_INDICATE) != 0) {
+                            if (!targetChars.contains(char)) targetChars.add(char)
+                        }
+                    }
+                }
+            }
+            if (targetChars.isEmpty()) {
+                mainHandler.post { listener.onError("Nessuna caratteristica peso trovata") }
+                return
+            }
+            gatt.getService(BleUuids.BATTERY_SERVICE)?.getCharacteristic(BleUuids.BATTERY_LEVEL_CHAR)?.let { targetChars.add(it) }
+            try { gatt.device?.address?.let { saveDevice(it, connectedDeviceName) } } catch (_: SecurityException) {}
+            pendingSubscriptions.clear()
+            pendingSubscriptions.addAll(targetChars)
+            val deviceName = try { gatt.device?.name ?: "Scale" } catch (_: SecurityException) { "Scale" }
+            connectedDeviceName = deviceName
+            mainHandler.post { listener.onConnected(deviceName) }
+            subscribeNext(gatt)
+        }
+
+        override fun onDescriptorWrite(gatt: BluetoothGatt, descriptor: BluetoothGattDescriptor, status: Int) {
+            subscribeNext(gatt)
+        }
+
+        @Suppress("DEPRECATION")
+        override fun onCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic) {
+            processCharacteristicData(characteristic, characteristic.value ?: return)
+        }
+
+        override fun onCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, value: ByteArray) {
+            processCharacteristicData(characteristic, value)
+        }
+
+        @Suppress("DEPRECATION")
+        override fun onCharacteristicRead(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int) {
+            if (status == BluetoothGatt.GATT_SUCCESS && characteristic.uuid == BleUuids.BATTERY_LEVEL_CHAR) {
+                val level = characteristic.value?.firstOrNull()?.toInt()?.and(0xFF)
+                if (level != null) mainHandler.post { listener.onBatteryReceived(level) }
+            }
+        }
+    }
+
+    private fun subscribeNext(gatt: BluetoothGatt) {
+        val char = pendingSubscriptions.removeFirstOrNull() ?: return
+        if (char.uuid == BleUuids.BATTERY_LEVEL_CHAR) {
+            try { gatt.readCharacteristic(char) } catch (_: SecurityException) {}
+            return
+        }
+        val props = char.properties
+        val notifyType = when {
+            (props and BluetoothGattCharacteristic.PROPERTY_INDICATE) != 0 ->
+                BluetoothGattDescriptor.ENABLE_INDICATION_VALUE
+            else -> BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE
+        }
+        try {
+            gatt.setCharacteristicNotification(char, true)
+            val descriptor = char.getDescriptor(CCCD_UUID) ?: run { subscribeNext(gatt); return }
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                gatt.writeDescriptor(descriptor, notifyType)
+            } else {
+                @Suppress("DEPRECATION")
+                descriptor.value = notifyType
+                @Suppress("DEPRECATION")
+                gatt.writeDescriptor(descriptor)
+            }
+        } catch (_: SecurityException) {}
+    }
+
+    private fun processCharacteristicData(char: BluetoothGattCharacteristic, data: ByteArray) {
+        if (char.uuid == BleUuids.BATTERY_LEVEL_CHAR && data.isNotEmpty()) {
+            val level = data[0].toInt() and 0xFF
+            mainHandler.post { listener.onBatteryReceived(level) }
+            return
+        }
+        val reading = ScaleProtocol.parse(char, data) { msg -> mainHandler.post { listener.onDebugEvent(msg) } }
+        if (reading != null && reading.value > 0f) {
+            mainHandler.post { listener.onWeightReceived(reading) }
+        }
+    }
+}

evershelf-kiosk/app/src/main/kotlin/it/dadaloop/evershelf/kiosk/scale/GatewayService.kt

@@ -0,0 +1,249 @@
+package it.dadaloop.evershelf.kiosk.scale
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+import android.bluetooth.BluetoothDevice
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import android.os.Handler
+import android.os.IBinder
+import android.os.Looper
+import android.util.Log
+import it.dadaloop.evershelf.kiosk.KioskActivity
+import it.dadaloop.evershelf.kiosk.R
+
+private const val TAG = "GatewayService"
+private const val WS_PORT = 8765
+private const val NOTIF_ID = 1001
+private const val CHANNEL_ID = "evershelf_gateway"
+private const val RECONNECT_DELAY_MS = 8_000L
+
+/**
+ * Foreground service that keeps the BLE scale connection and WebSocket server alive
+ * independently of the KioskActivity lifecycle.
+ *
+ * The WebSocket server on port 8765 is protocol-compatible with the standalone
+ * evershelf-scale-gateway app, so the EverShelf webapp JS needs no changes.
+ */
+class GatewayService : Service(), BleScaleListener, ServerEventListener {
+
+    private lateinit var bleManager: BleScaleManager
+    private var wsServer: GatewayWebSocketServer? = null
+    private val handler = Handler(Looper.getMainLooper())
+    private var connectedDeviceName: String? = null
+    private var batteryLevel: Int? = null
+    private var reconnectPending = false
+
+    companion object {
+        const val ACTION_START = "evershelf.gateway.START"
+        const val ACTION_STOP  = "evershelf.gateway.STOP"
+
+        /** Returns true if the service can try to connect (BLE permissions ok, device saved). */
+        fun canStart(context: Context): Boolean {
+            val prefs = context.getSharedPreferences("evershelf_kiosk", Context.MODE_PRIVATE)
+            val hasScale  = prefs.getBoolean("has_scale", false)
+            val hasDevice = prefs.getString("scale_device_address", null) != null
+            return hasScale && hasDevice
+        }
+
+        fun start(context: Context) {
+            val intent = Intent(context, GatewayService::class.java).apply {
+                action = ACTION_START
+            }
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                context.startForegroundService(intent)
+            } else {
+                context.startService(intent)
+            }
+        }
+
+        fun stop(context: Context) {
+            context.startService(Intent(context, GatewayService::class.java).apply {
+                action = ACTION_STOP
+            })
+        }
+    }
+
+    override fun onCreate() {
+        super.onCreate()
+        bleManager = BleScaleManager(this, this)
+        createNotificationChannel()
+        startForeground(NOTIF_ID, buildNotification("Avvio bilancia…"))
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        when (intent?.action) {
+            ACTION_STOP -> {
+                stopSelf()
+                return START_NOT_STICKY
+            }
+            else -> {
+                startWsServer()
+                connectToSavedScale()
+            }
+        }
+        return START_STICKY
+    }
+
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    override fun onDestroy() {
+        handler.removeCallbacksAndMessages(null)
+        bleManager.disconnect()
+        try { wsServer?.stop(1000) } catch (_: Exception) {}
+        wsServer = null
+        super.onDestroy()
+    }
+
+    // ── WebSocket server ──────────────────────────────────────────────────────
+
+    private fun startWsServer() {
+        if (wsServer != null) return
+        try {
+            wsServer = GatewayWebSocketServer(WS_PORT, this)
+            wsServer!!.isReuseAddr = true
+            wsServer!!.start()
+            Log.i(TAG, "WebSocket server started on :$WS_PORT")
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to start WebSocket server", e)
+            updateNotification("⚠️ WebSocket non avviato: ${e.message}")
+        }
+    }
+
+    // ── BLE connection ────────────────────────────────────────────────────────
+
+    private fun connectToSavedScale() {
+        if (!bleManager.hasRequiredPermissions()) {
+            updateNotification("⚠️ Permessi Bluetooth mancanti")
+            return
+        }
+        val addr = bleManager.getSavedDeviceAddress() ?: run {
+            updateNotification("Nessuna bilancia configurata")
+            return
+        }
+        val name = bleManager.getSavedDeviceName() ?: addr
+        updateNotification("🔍 Connessione a $name…")
+        // Enable auto-connect: the scan callback will connect when the saved device is found
+        bleManager.enableAutoConnect()
+        bleManager.startScan()
+    }
+
+    private fun scheduleReconnect() {
+        if (reconnectPending) return
+        reconnectPending = true
+        handler.postDelayed({
+            reconnectPending = false
+            if (bleManager.getSavedDeviceAddress() != null) {
+                updateNotification("🔄 Riconnessione bilancia…")
+                bleManager.enableAutoConnect()
+                bleManager.startScan()
+            }
+        }, RECONNECT_DELAY_MS)
+    }
+
+    // ── BleScaleListener ─────────────────────────────────────────────────────
+
+    override fun onDeviceFound(info: BleDeviceInfo) { /* handled by autoConnect */ }
+
+    override fun onConnecting(device: BluetoothDevice) {
+        val name = try { device.name ?: device.address } catch (_: SecurityException) { device.address }
+        updateNotification("⏳ Connessione a $name…")
+    }
+
+    override fun onConnected(deviceName: String) {
+        connectedDeviceName = deviceName
+        updateNotification("✅ $deviceName connessa")
+        wsServer?.publishStatus("connected", deviceName, batteryLevel)
+        Log.i(TAG, "BLE scale connected: $deviceName")
+    }
+
+    override fun onDisconnected() {
+        val name = connectedDeviceName ?: "bilancia"
+        connectedDeviceName = null
+        updateNotification("⚠️ $name disconnessa — riconnessione…")
+        wsServer?.publishStatus("disconnected", null, null)
+        scheduleReconnect()
+    }
+
+    override fun onWeightReceived(reading: WeightReading) {
+        wsServer?.publishWeight(reading.value, reading.unit, reading.stable, batteryLevel)
+    }
+
+    override fun onBatteryReceived(level: Int) {
+        batteryLevel = level
+        connectedDeviceName?.let { wsServer?.publishStatus("connected", it, level) }
+    }
+
+    override fun onError(message: String) {
+        Log.w(TAG, "BLE error: $message")
+        scheduleReconnect()
+    }
+
+    override fun onScanStopped() {
+        // If not connected yet, schedule a retry so we keep searching after the scale powers on
+        if (!bleManager.isConnected) scheduleReconnect()
+    }
+
+    override fun onDebugEvent(message: String) {
+        Log.d(TAG, message)
+    }
+
+    // ── ServerEventListener ───────────────────────────────────────────────────
+
+    override fun onClientConnected(address: String) {
+        Log.d(TAG, "WS client connected: $address")
+    }
+
+    override fun onClientDisconnected(address: String) {
+        Log.d(TAG, "WS client disconnected: $address")
+    }
+
+    override fun onClientRequestedWeight() { /* weight is pushed via onWeightReceived */ }
+
+    // ── Notification ──────────────────────────────────────────────────────────
+
+    private fun createNotificationChannel() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel = NotificationChannel(
+                CHANNEL_ID,
+                "EverShelf Scale Gateway",
+                NotificationManager.IMPORTANCE_LOW
+            ).apply {
+                description = "Bilancia smart integrata"
+                setShowBadge(false)
+            }
+            (getSystemService(NOTIFICATION_SERVICE) as NotificationManager)
+                .createNotificationChannel(channel)
+        }
+    }
+
+    private fun buildNotification(text: String): Notification {
+        val pendingIntent = PendingIntent.getActivity(
+            this, 0,
+            Intent(this, KioskActivity::class.java),
+            PendingIntent.FLAG_IMMUTABLE
+        )
+        val builder = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            Notification.Builder(this, CHANNEL_ID)
+        } else {
+            @Suppress("DEPRECATION")
+            Notification.Builder(this)
+        }
+        return builder
+            .setContentTitle("EverShelf Scale")
+            .setContentText(text)
+            .setSmallIcon(R.mipmap.ic_launcher)
+            .setContentIntent(pendingIntent)
+            .setOngoing(true)
+            .build()
+    }
+
+    private fun updateNotification(text: String) {
+        val nm = getSystemService(NOTIFICATION_SERVICE) as NotificationManager
+        nm.notify(NOTIF_ID, buildNotification(text))
+    }
+}

evershelf-kiosk/app/src/main/kotlin/it/dadaloop/evershelf/kiosk/scale/GatewayWebSocketServer.kt

@@ -0,0 +1,98 @@
+package it.dadaloop.evershelf.kiosk.scale
+
+import android.util.Log
+import org.java_websocket.WebSocket
+import org.java_websocket.handshake.ClientHandshake
+import org.java_websocket.server.WebSocketServer
+import org.json.JSONObject
+import java.net.InetSocketAddress
+import java.util.Collections
+
+private const val TAG = "GatewayWsServer"
+
+interface ServerEventListener {
+    fun onClientConnected(address: String)
+    fun onClientDisconnected(address: String)
+    fun onClientRequestedWeight()
+}
+
+/**
+ * WebSocket server that exposes BLE scale data to EverShelf running in a browser.
+ * Protocol is identical to the standalone gateway app so the webapp JS needs no changes.
+ */
+class GatewayWebSocketServer(
+    port: Int,
+    private val eventListener: ServerEventListener?,
+) : WebSocketServer(InetSocketAddress(port)) {
+
+    private val pendingWeightRequests: MutableSet<WebSocket> =
+        Collections.synchronizedSet(mutableSetOf())
+
+    @Volatile private var lastStatusJson: String = buildStatusJson("disconnected", null, null)
+    @Volatile private var lastWeightJson: String? = null
+
+    override fun onStart() {
+        Log.i(TAG, "WebSocket server started on port ${address.port}")
+        connectionLostTimeout = 30
+    }
+
+    override fun onOpen(conn: WebSocket, handshake: ClientHandshake) {
+        conn.send(lastStatusJson)
+        lastWeightJson?.let { conn.send(it) }
+        eventListener?.onClientConnected(conn.remoteSocketAddress?.toString() ?: "?")
+    }
+
+    override fun onClose(conn: WebSocket, code: Int, reason: String, remote: Boolean) {
+        pendingWeightRequests.remove(conn)
+        eventListener?.onClientDisconnected(conn.remoteSocketAddress?.toString() ?: "?")
+    }
+
+    override fun onMessage(conn: WebSocket, message: String) {
+        try {
+            when (JSONObject(message).optString("type")) {
+                "ping"       -> conn.send("""{"type":"pong"}""")
+                "get_status" -> conn.send(lastStatusJson)
+                "get_weight" -> {
+                    pendingWeightRequests.add(conn)
+                    eventListener?.onClientRequestedWeight()
+                    lastWeightJson?.let { conn.send(it) }
+                }
+            }
+        } catch (_: Exception) {}
+    }
+
+    override fun onError(conn: WebSocket?, ex: Exception) {
+        Log.e(TAG, "WebSocket error", ex)
+    }
+
+    fun publishStatus(state: String, deviceName: String?, battery: Int?) {
+        lastStatusJson = buildStatusJson(state, deviceName, battery)
+        broadcast(lastStatusJson)
+    }
+
+    fun publishWeight(value: Float, unit: String, stable: Boolean, battery: Int? = null) {
+        val json = buildWeightJson(value, unit, stable)
+        lastWeightJson = json
+        broadcast(json)
+        if (stable) synchronized(pendingWeightRequests) { pendingWeightRequests.clear() }
+    }
+
+    private fun buildStatusJson(state: String, device: String?, battery: Int?): String {
+        val obj = JSONObject()
+        obj.put("type", "status")
+        obj.put("state", state)
+        if (device != null) obj.put("device", device)
+        if (battery != null) obj.put("battery", battery)
+        return obj.toString()
+    }
+
+    private fun buildWeightJson(value: Float, unit: String, stable: Boolean): String {
+        val obj = JSONObject()
+        obj.put("type", "weight")
+        obj.put("value", Math.round(value * 10f) / 10.0)
+        obj.put("unit", unit)
+        obj.put("stable", stable)
+        obj.put("timestamp", System.currentTimeMillis())
+        return obj.toString()
+    }
+}

evershelf-kiosk/app/src/main/kotlin/it/dadaloop/evershelf/kiosk/scale/ScaleProtocol.kt

@@ -0,0 +1,131 @@
+package it.dadaloop.evershelf.kiosk.scale
+
+import android.bluetooth.BluetoothGattCharacteristic
+import java.util.UUID
+
+// ── Data model ────────────────────────────────────────────────────────────────
+
+data class WeightReading(
+    val value: Float,
+    val unit: String,
+    val stable: Boolean,
+)
+
+// ── UUIDs ─────────────────────────────────────────────────────────────────────
+
+val CCCD_UUID: UUID = UUID.fromString("00002902-0000-1000-8000-00805f9b34fb")
+
+object BleUuids {
+    val WEIGHT_SCALE_SERVICE    = UUID.fromString("0000181d-0000-1000-8000-00805f9b34fb")
+    val WEIGHT_MEASUREMENT_CHAR = UUID.fromString("00002a9d-0000-1000-8000-00805f9b34fb")
+    val BATTERY_SERVICE    = UUID.fromString("0000180f-0000-1000-8000-00805f9b34fb")
+    val BATTERY_LEVEL_CHAR = UUID.fromString("00002a19-0000-1000-8000-00805f9b34fb")
+    val FFE0 = UUID.fromString("0000ffe0-0000-1000-8000-00805f9b34fb")
+    val FFE1 = UUID.fromString("0000ffe1-0000-1000-8000-00805f9b34fb")
+    val FFF0 = UUID.fromString("0000fff0-0000-1000-8000-00805f9b34fb")
+    val FFF1 = UUID.fromString("0000fff1-0000-1000-8000-00805f9b34fb")
+    val FFF4 = UUID.fromString("0000fff4-0000-1000-8000-00805f9b34fb")
+    val ACAIA_SERVICE = UUID.fromString("49535343-fe7d-4ae5-8fa9-9fafd205e455")
+    val ACAIA_CHAR    = UUID.fromString("49535343-8841-43f4-a8d4-ecbe34729bb3")
+    val QN_AE00 = UUID.fromString("0000ae00-0000-1000-8000-00805f9b34fb")
+    val QN_AE02 = UUID.fromString("0000ae02-0000-1000-8000-00805f9b34fb")
+}
+
+// ── Scale protocol parser ─────────────────────────────────────────────────────
+
+object ScaleProtocol {
+
+    private const val MAX_GRAMS = 15000f
+    private const val MIN_GRAMS = 0.5f
+
+    fun resetState() { /* reserved */ }
+
+    fun parse(
+        char: BluetoothGattCharacteristic,
+        data: ByteArray,
+        debug: ((String) -> Unit)? = null,
+    ): WeightReading? {
+        if (data.size < 2) {
+            debug?.invoke("skip: packet too short (${data.size}B)")
+            return null
+        }
+        when (char.uuid) {
+            BleUuids.WEIGHT_MEASUREMENT_CHAR -> return parseSigWeight(data, debug)
+        }
+        if (data.size == 18
+            && (data[0].toInt() and 0xFF) == 0x10
+            && (data[1].toInt() and 0xFF) == 0x12) {
+            return parseQNFood(data, debug)
+        }
+        return parseGeneric(data, debug)
+    }
+
+    private fun parseSigWeight(data: ByteArray, debug: ((String) -> Unit)? = null): WeightReading? {
+        if (data.size < 3) return null
+        val flags     = data[0].toInt() and 0xFF
+        val isImperial = (flags and 0x01) != 0
+        val raw       = u16le(data, 1)
+        return if (isImperial) {
+            val lb = raw * 0.01f
+            debug?.invoke("SIG 2A9D: raw=$raw -> ${lb}lb")
+            if (lb < 0.01f || lb > 33f) null
+            else WeightReading(lb, "lb", stable = true)
+        } else {
+            val g = raw * 5f
+            debug?.invoke("SIG 2A9D: raw=$raw -> ${g}g")
+            if (g < MIN_GRAMS || g > MAX_GRAMS) null
+            else WeightReading(g, "g", stable = true)
+        }
+    }
+
+    private fun parseQNFood(data: ByteArray, debug: ((String) -> Unit)? = null): WeightReading? {
+        val calc = data.take(17).sumOf { it.toInt() and 0xFF } and 0xFF
+        if (calc != (data[17].toInt() and 0xFF)) {
+            debug?.invoke("QN-KS: CRC mismatch")
+            return null
+        }
+        val rawValue = u16be(data, 9)
+        val stable   = (data[8].toInt() and 0x08) != 0
+        val unit     = when (data[4].toInt() and 0xFF) {
+            0x01 -> "g"; 0x02 -> "oz"; 0x03 -> "ml"; 0x04 -> "ml"; else -> "g"
+        }
+        val value = rawValue / 10f
+        debug?.invoke("QN-KS: ${value}${unit} stable=$stable")
+        if (rawValue == 0) return null
+        val valueG = if (unit == "oz") value * 28.3495f else value
+        if (valueG < MIN_GRAMS || valueG > MAX_GRAMS) return null
+        return WeightReading(value, unit, stable)
+    }
+
+    private fun parseGeneric(data: ByteArray, debug: ((String) -> Unit)? = null): WeightReading? {
+        if (data.size < 3) return null
+        data class C(val pos: Int, val be: Boolean, val div: Float, val label: String)
+        val candidates = listOf(
+            C(1, false, 1f, "pos1 LE g"), C(1, true, 1f, "pos1 BE g"),
+            C(2, false, 1f, "pos2 LE g"), C(2, true, 1f, "pos2 BE g"),
+            C(3, false, 1f, "pos3 LE g"), C(3, true, 1f, "pos3 BE g"),
+            C(1, false, 10f, "pos1 LE 0.1g"), C(1, true, 10f, "pos1 BE 0.1g"),
+            C(2, false, 10f, "pos2 LE 0.1g"), C(2, true, 10f, "pos2 BE 0.1g"),
+            C(3, false, 10f, "pos3 LE 0.1g"), C(3, true, 10f, "pos3 BE 0.1g"),
+            C(1, false, 2f, "pos1 LE 0.5g"), C(1, true, 2f, "pos1 BE 0.5g"),
+            C(1, false, 0.1f, "pos1 LE cg"), C(1, true, 0.1f, "pos1 BE cg"),
+        )
+        for (c in candidates) {
+            if (c.pos + 1 >= data.size) continue
+            val raw = if (c.be) u16be(data, c.pos) else u16le(data, c.pos)
+            if (raw == 0) continue
+            val g = raw / c.div
+            if (g in MIN_GRAMS..MAX_GRAMS) {
+                debug?.invoke("generic [${c.label}]: raw=$raw -> ${g}g")
+                return WeightReading(g, "g", stable = false)
+            }
+        }
+        return null
+    }
+
+    private fun u16le(data: ByteArray, offset: Int) =
+        (data[offset].toInt() and 0xFF) or ((data[offset + 1].toInt() and 0xFF) shl 8)
+
+    private fun u16be(data: ByteArray, offset: Int) =
+        ((data[offset].toInt() and 0xFF) shl 8) or (data[offset + 1].toInt() and 0xFF)
+}