PotholeIQ: initial deployable build (Box + Supabase, HF Spaces Docker)

.dockerignore

@@ -0,0 +1,10 @@
+node_modules
+data
+.git
+*.log
+server.pid
+__pycache__
+*.pyc
+.DS_Store
+Dockerfile
+.dockerignore

.gitattributes

@@ -0,0 +1,9 @@
+# HuggingFace requires ALL binary files to be stored via Git LFS.
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+*.docx filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,29 @@
+# Dependencies
+node_modules/
+
+# Local data + secrets — data/config.json holds Box credentials locally.
+# On hosted deployments (HF Spaces) all of this comes from env-var secrets.
+data/
+start.bat
+start.local.bat
+.env
+.env.*
+
+# Logs / runtime
+*.log
+server.pid
+*.stderr.log
+*.stdout.log
+
+# Python
+__pycache__/
+*.pyc
+
+# OS / editor
+.DS_Store
+Thumbs.db
+
+# Scratch
+*.tmp
+_*.png
+_*.html

BACKEND_SETUP.md

@@ -0,0 +1,95 @@
+# Backend Setup
+
+## What This Backend Does
+
+- Serves the app and API from one Node server
+- Stores shared cases and workflow state in `data/cases.json`
+- Accepts frontend case syncs and workflow actions
+- Stores artifacts in Box while the backend/database stays the source of truth
+- Optionally accepts legacy Box Automate updates at `POST /api/box/automate-update`
+
+## Start It
+
+Run:
+
+```bat
+START_SERVER.bat
+```
+
+Preferred mode is Node.js. The server runs at:
+
+```txt
+http://localhost:3030
+```
+
+Health check:
+
+```txt
+GET http://localhost:3030/api/health
+```
+
+## Optional Secret For Box Automate
+
+Set this before starting the server if you want Box callback protection:
+
+```powershell
+$env:BOX_AUTOMATE_SECRET="replace-with-a-secret"
+node server.js
+```
+
+Box Automate should then send the same value in:
+
+```txt
+X-Box-Automate-Secret
+```
+
+or as:
+
+```txt
+?secret=replace-with-a-secret
+```
+
+## Main API Endpoints
+
+- `GET /api/health`
+- `GET /api/cases`
+- `GET /api/cases/:caseId`
+- `POST /api/cases/upsert`
+- `POST /api/cases/bulk-upsert`
+- `POST /api/cases/:caseId/patch`
+- `POST /api/workflow/supervisor-decision`
+- `POST /api/workflow/dispatch-plan`
+- `POST /api/workflow/crew-closeout`
+- `POST /api/workflow/resolve-case`
+- `POST /api/box/automate-update`
+
+## Box Automate Payload Shape
+
+Send JSON like this from Box:
+
+```json
+{
+  "caseId": "PHL-20260530-ABCDE1",
+  "workflowStage": "crew_dispatch",
+  "workflowStatus": "Assigned",
+  "workflowPriority": "high",
+  "workflowNextAction": "Dispatch crew",
+  "folderId": "1234567890",
+  "boxPath": "Potholes/Ward-29/Case-PHL-20260530-ABCDE1",
+  "assignedTo": "dispatch@city.gov",
+  "resolutionNotes": ""
+}
+```
+
+## What You Still Need From Box
+
+- A Box folder ID for the app root
+- Supervisor email
+- Dispatch or crew email/group
+- A public URL for this backend when you want Box to call it from the cloud
+
+For local testing with Box cloud callbacks, use a tunnel such as `ngrok` or `cloudflared`, then point Box Automate `HTTPS Request` to:
+
+```txt
+https://your-public-url/api/box/automate-update
+```

CLIENT_DEMO_QUESTIONS.md

@@ -0,0 +1,73 @@
+# PotholeIQ — Client Demo: Questions & Inputs to Collect
+
+Use this during the session. ⭐ = blocker (get it or we can't deploy). 📥 = a file/credential to collect. ✅ = a decision to confirm.
+
+---
+
+## 1. Box Access & Authentication ⭐ (blocks everything — token expires every 60 min)
+- ⭐ Who is your Box **enterprise admin**? Can they **authorize a custom app**? (needed for permanent auth)
+- ✅ Auth method: **CCG** (admin authorizes once → permanent, recommended) or **OAuth** (one user login → 60-day)?
+- 📥 Box **Enterprise ID** + the **folder** to use (intake folder, case-root folder).
+- ✅ Which Box features are **enabled/licensed**: Relay (Automate), **Sign**, **Doc Gen**, **Forms**, **Apps** (custom dashboards)?
+- 📥 A **service/bot Box account** to run the integration as (so it's not tied to a person)?
+
+## 2. City, GIS & Department
+- ✅ Confirm **city / jurisdiction** (demo = Philadelphia).
+- ⭐📥 GIS boundary files for **districts** and **maintenance/service zones** — not just wards. Format? (GeoJSON / Shapefile). *(Today we only have ward polygons and derive the rest.)*
+- 📥 Official **ward → district → maintenance-zone** mapping, if it exists.
+- 📥 **Department name + logo / letterhead** for documents (work order, review sheet, closeout).
+
+## 3. Roles, People & Crew Dispatch
+- 📥 **Reviewers / district engineers / supervisors** — names + **Box account emails**.
+- ✅ Who **approves** a case, and who **dispatches** the crew?
+- ✅ How is the **crew chosen per pothole**? (we built: reviewer types the crew email at approval — confirm)
+- ✅ Are **crews Box users**, or external (email only — affects Sign vs notifications)?
+- ✅ Who gets **notified** at each stage (new case / approved / dispatched / resolved)?
+
+## 4. Metadata Template & Fields
+- ✅ Confirm the **case fields + dropdown values**. Known quirks to fix or keep:
+  - `weatherRisk` = **Low / Medium / Large** (no "High" — typo?)
+  - `duplicateStatus` = `new / "duplicate " / pending` (**trailing space** on "duplicate")
+  - `status` includes **`In progress`** (odd capitalization)
+- ✅ Any **additional fields** they track today (asset ID, 311 reference, etc.)?
+
+## 5. Severity Scoring, SLA & Cost
+- ✅ Agree with the **severity factors** (prior reports, traffic/road class, damage/size, weather) and **weights**?
+- ✅ **SLA targets** by severity (e.g. Critical = N days)? → drives "target completion" + days-to-resolve.
+- 📥 **Actual repair-cost** figures by size? (we use researched estimates: Small ~$90–180, Medium ~$250–450, Large ~$450–800).
+
+## 6. Forms & Documents
+- ✅ Confirm **citizen intake** fields and **crew closeout** form fields (current closeout: Case ID, Repair completed?, Method, Materials, Labor hours, After photo, Crew name, Crew contact).
+- ✅ Confirm **Work Order / Review Sheet / Closeout** layouts — fields to add/remove?
+- ✅ **Box Sign** — how many signatures and who? (we set crew + supervisor).
+
+## 7. Duplicates, Data & Volume
+- ✅ **Duplicate radius** (we use 80 m) — confirm.
+- ✅ OK with an **external DB** (Supabase / PostGIS) for fast geo/duplicate search, or **all-in-Box** only?
+- 📥 **Historical case data** to import?
+- ✅ Expected **volume** (reports/day) — for sizing.
+
+## 8. AI / Detection
+- ✅ Is the **open-source YOLO** pothole detector + size classification acceptable, or a specific accuracy bar / different model?
+- ✅ Size thresholds (Small/Medium/Large) — tune to their definition?
+
+## 9. Deployment & Infra
+- ⭐ Where will the **backend + portal + dashboard** be hosted? **Domain/URL**?
+- ⭐ **HTTPS + public endpoint** for Box callbacks/forms — who provides it?
+- ✅ Weather: use **our OpenWeather key** or **theirs** (their account/limits)?
+- ✅ Who can access the **supervisor dashboard** (login list)?
+
+## 10. The Big Decision — Architecture
+- ✅ Which model do they want?
+  1. **Fully inside Box** (Relay + Sign + Doc Gen + Apps)
+  2. **Box as storage only** (our portal + backend do the logic)
+  3. **Hybrid (recommended)** — backend does geo/scoring/duplicate/weather + AI; Box does content, workflow, docs, sign, dashboard, governance
+
+---
+
+### Fast "must-leave-with" list (the 5 that unblock everything)
+1. ⭐ Admin to authorize the app (permanent auth) — or schedule it.
+2. ⭐ District + maintenance-zone GIS data (or confirm we derive from ward).
+3. ⭐ Hosting + HTTPS endpoint owner.
+4. 📥 Reviewer/supervisor Box emails + department name/logo.
+5. ✅ Architecture option (1 / 2 / 3).

Dockerfile

@@ -0,0 +1,43 @@
+# PotholeIQ — Node backend + Python YOLO classifier + Chromium PDF rendering.
+# Built for HuggingFace Spaces (Docker SDK, app_port 7860) but runs anywhere.
+FROM node:20-slim
+
+# System deps:
+#  - python3 + pip        -> YOLOv8 classifier (ai/pothole_server.py) + docx generation
+#  - chromium             -> before/after PDF rendering (htmlToPdf)
+#  - libgl1 / libglib2.0  -> OpenCV runtime used by ultralytics
+#  - fonts-liberation     -> readable PDF text
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      python3 python3-pip \
+      chromium fonts-liberation \
+      libgl1 libglib2.0-0 \
+  && rm -rf /var/lib/apt/lists/*
+
+# Python deps. CPU-only torch first (much smaller than the default CUDA build).
+COPY requirements.txt /tmp/requirements.txt
+RUN pip3 install --no-cache-dir --break-system-packages \
+      torch torchvision --index-url https://download.pytorch.org/whl/cpu \
+  && pip3 install --no-cache-dir --break-system-packages -r /tmp/requirements.txt
+
+WORKDIR /app
+
+# Node deps (cached layer)
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+# App code (see .dockerignore for exclusions — no secrets, no local data)
+COPY . .
+
+# Runtime env. PORT 7860 is what HuggingFace Spaces routes to.
+ENV PORT=7860 \
+    HOST=0.0.0.0 \
+    PYTHON_BIN=python3 \
+    CHROME_PATH=/usr/bin/chromium \
+    YOLO_CONFIG_DIR=/tmp/ultralytics
+
+# HF Spaces runs the container as an arbitrary non-root user; make the app dir
+# writable for the ephemeral data store (data/cases.json etc.).
+RUN mkdir -p /app/data && chmod -R 777 /app/data && chmod 1777 /tmp
+
+EXPOSE 7860
+CMD ["node", "server.js"]

LICENSE

@@ -0,0 +1,31 @@
+CONFIDENTIAL & PROPRIETARY LICENSE AGREEMENT
+
+Copyright (c) 2026 Varun. All rights reserved.
+
+NOTICE: All information contained herein is, and remains the property of the Copyright Holder (Varun). The intellectual and technical concepts contained herein are proprietary to the Copyright Holder and may be covered by patents, patents in process, and are protected by trade secret or copyright law.
+
+Dissemination of this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from the Copyright Holder.
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION:
+
+1. DEFINITIONS:
+   "Software" shall mean the Citizen Pothole Submission Wizard, Pothole Citizen Portal, and all associated files, source code, scripts, HTML, CSS, assets, and documentation located in this repository.
+   "Licensor" or "Copyright Holder" shall mean Varun, the sole owner and author of the Software.
+   "You" (or "Your") shall mean any individual or Legal Entity exercising permissions granted by this License.
+
+2. OWNERSHIP AND INTELLECTUAL PROPERTY:
+   The Software is licensed, not sold. All rights, title, and interest in and to the Software, including but not limited to all copyrights, trade secrets, patents, trademarks, and other intellectual property rights, are and shall remain the exclusive property of the Licensor.
+
+3. RESTRICTIONS:
+   You may NOT:
+   a. Copy, reproduce, redistribute, republish, upload, post, transmit, or distribute the Software in any way, in whole or in part, without explicit, prior written authorization from the Licensor.
+   b. Modify, translate, adapt, merge, make derivative works of, disassemble, decompile, decrypt, or reverse engineer any part of the Software.
+   c. Remove, alter, or obscure any copyright, trademark, or other proprietary rights notices contained in or on the Software.
+   d. Sublicense, rent, lease, lend, sell, or distribute the Software or any portion thereof to any third party.
+   e. Use the Software for any unauthorized, unlawful, or competitive commercial purpose.
+
+4. NO WARRANTY:
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+5. TERMINATION:
+   This License and Your right to use the Software shall terminate automatically and immediately if You fail to comply with any of its terms. Upon termination, You must immediately cease all use of the Software and destroy all copies of the Software in Your possession.

Pothole Case Review Sheet (DocGen).docx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e2eae884c5096fb92b1d34307234a69c19a00574737620161f8f4d5da9e43c75
+size 37165

Pothole Closeout Job Sheet (DocGen Template).docx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1a0710f1d930941db1d3829ba41d0e921e00e9b7c852d35d5f7f5f56de182427
+size 37725

Pothole Closeout Job Sheet (DocGen).docx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:18dda542dafb4a50b2ed2f35b3759e4a49ee7ec8495379ecc7008581db397a12
+size 17378

Pothole Closeout Job Sheet SAMPLE.docx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7e08e6fba69dba8d55e447cab92f8e2f1b8719076ea798b03b14e0da23af458f
+size 165704

Pothole Repair Work Order (DocGen).docx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:624994a7611c4f44265b3c1b3f11ead562a97f6c5c2ba5eb728a0e3b8bce0d90
+size 17356

Pothole Repair Work Order.docx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:111c6b2732a42a2a855360391ffde13ba8db380e20202dffa74ad1ff7c2b77b1
+size 17188

Pothole Work Order (DocGen Template).docx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:46b6ee4a88ad6ba10f5bd7238fe653987fc457a9c8451a85db019b1fcb711389
+size 39063

Pothole Work Order SAMPLE.docx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:82c7a27628716fc0e93f01260e8223c1c020d82cf5fb8e798f4ac9f8c2010965
+size 195767

README.md

@@ -0,0 +1,67 @@
+---
+title: PotholeIQ
+emoji: 🛣️
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# PotholeIQ — Pothole Management on the Box Platform
+
+One workflow from citizen intake to verified repair: AI photo classification
+(YOLOv8), severity scoring, GIS mapping, supervisor review, crew dispatch,
+digital closeout, and an auditable **before/after report** — with **Box** as the
+content system of record and **Supabase** as the data mirror.
+
+## Pages
+
+| Page | Purpose |
+|---|---|
+| `/index.html` | Citizen submission portal (photo + GPS, AI classification) |
+| `/command-center.html` | Supervisor Command Center (KPIs, map, approve/dispatch/resolve) |
+| `/crew-closeout.html?case=ID` | Standalone crew closeout form (locked to one case) |
+| `/case-report.html?case=ID` | Printable before/after report |
+| `/track.html` | Citizen case tracking |
+
+## Configuration (Space secrets → env vars)
+
+**Box (required)**
+
+| Secret | Example / note |
+|---|---|
+| `BOX_AUTH_MODE` | `client_credentials` |
+| `BOX_CLIENT_ID` | Box app client id |
+| `BOX_CLIENT_SECRET` | Box app client secret |
+| `BOX_SUBJECT_TYPE` | `enterprise` |
+| `BOX_SUBJECT_ID` | Box enterprise id |
+| `BOX_INTAKE_FOLDER_ID` | Intake folder id |
+| `BOX_CASE_ROOT_FOLDER_ID` | Case root folder id (often same as intake) |
+| `BOX_METADATA_SCOPE` | `enterprise` |
+| `BOX_METADATA_TEMPLATE_KEY` | `potholeCase` |
+
+**Supabase (recommended — data mirror + supervisor login)**
+
+| Secret | Note |
+|---|---|
+| `SUPABASE_URL` | `https://<ref>.supabase.co` |
+| `SUPABASE_SECRET_KEY` | service-role key (server-side only) |
+| `DASHBOARD_AUTH` | `true` to require supervisor login on dashboard APIs |
+
+**Optional**
+
+| Secret | Note |
+|---|---|
+| `CLOSEOUT_NOTIFY_RECIPIENTS` | Comma-separated default recipients for before/after reports |
+| `BOX_AUTOMATE_SECRET` | Shared secret for Box Automate → `/api/box/automate-update` |
+| `DATA_DIR` | Set to `/data/potholeiq` if HF persistent storage is enabled |
+| `BOX_CASES_TTL_MS` | Box case-list cache TTL (default 45000) |
+
+## Architecture notes
+
+- **Box = source of truth for content**: photos, sidecars, generated documents,
+  before/after PDFs (in `Closeout Reports`), metadata (`potholeCase` template).
+- **Supabase = data mirror** (`db/schema.sql`, run once in the Supabase SQL editor).
+- The local `data/` store is a working cache only — safe to lose on restarts.
+- First AI classification after a cold start takes ~30–60 s (model load).

START_SERVER.bat

@@ -0,0 +1,60 @@
+@echo off
+title Pothole Portal - Local Server
+color 0A
+echo.
+echo  ============================================
+echo   POTHOLE CITIZEN PORTAL - LOCAL SERVER
+echo  ============================================
+echo.
+echo  Starting server on port 3030...
+echo.
+
+REM Prefer the Node backend because it serves both the app and the API
+node --version >nul 2>&1
+if %errorlevel% == 0 (
+    echo  [Node.js] Full app + API server running at:
+    echo.
+    echo     http://localhost:3030
+    echo.
+    echo  This includes the Box workflow backend endpoints.
+    echo  Press Ctrl+C to stop.
+    echo.
+    node server.js
+    goto end
+)
+
+REM Fallback to Python static hosting if Node is unavailable
+python --version >nul 2>&1
+if %errorlevel% == 0 (
+    echo  [Python] Static server running at:
+    echo.
+    echo     http://localhost:3030
+    echo.
+    echo  WARNING: API backend endpoints will NOT be available in this mode.
+    echo.
+    python -m http.server 3030
+    goto end
+)
+
+REM Try Python3
+python3 --version >nul 2>&1
+if %errorlevel% == 0 (
+    echo  [Python3] Static server running at:
+    echo.
+    echo     http://localhost:3030
+    echo.
+    echo  WARNING: API backend endpoints will NOT be available in this mode.
+    echo.
+    python3 -m http.server 3030
+    goto end
+)
+
+echo  ERROR: Neither Node.js nor Python was found.
+echo.
+echo  Please install Node.js from https://nodejs.org
+echo  or Python from https://python.org
+echo  then run this file again.
+echo.
+
+:end
+pause

WORKFLOW_STORAGE_ONLY_GUIDE.md

@@ -0,0 +1,260 @@
+# Pothole Workflow: Box Storage Only
+
+This is the recommended workflow if Box is used only as the shared content repository.
+
+In this model:
+
+- Box stores photos, JSON files, case folders, review summaries, closeout proof, and reports
+- The app and backend handle review, approvals, dispatch, authority notification, crew forms, and reporting logic
+- GIS, weather, duplicate checks, and severity scoring all happen outside Box
+
+## 1. Architecture
+
+Use this split everywhere:
+
+- `Box`
+  - intake photo storage
+  - intake JSON storage
+  - organized case folders
+  - enriched JSON files
+  - human-readable review summaries
+  - after-photos and repair proof
+  - generated reports
+
+- `Backend / app`
+  - GIS mapping
+  - reverse geocoding
+  - duplicate detection
+  - weather enrichment
+  - severity scoring
+  - supervisor review decisions
+  - authority email
+  - crew assignment and routing
+  - crew completion form
+  - before/after report generation
+
+## 2. End-to-End Flow
+
+### Stage 1. Citizen Intake
+
+Owner:
+- citizen portal
+
+System actions:
+- collect photo
+- collect GPS or manual pin
+- reverse geocode address
+- capture AI review status and pothole size
+- upload photo to Box `Incoming Detections`
+- upload JSON sidecar to Box `Incoming Detections`
+- upsert the same case into the backend
+
+Status:
+- `Submitted`
+
+Main files:
+- `index.html`
+- `box-upload.js`
+- `box-service.js`
+
+### Stage 2. Ops Enrichment
+
+Owner:
+- ops review console
+
+System actions:
+- load submitted case from backend
+- resolve official GIS ward, district, and maintenance zone
+- check duplicates by GPS radius
+- pull weather risk
+- calculate severity score and severity level
+- organize the case into the right Box folder
+- write enriched JSON into the case folder
+- write a readable review summary into the case folder
+- write Box metadata for reporting and indexing
+
+Status:
+- `Under Review`
+
+Main files:
+- `ops-review.html`
+- `enrichment.js`
+- `gis.js`
+- `box-folders.js`
+
+### Stage 3. Supervisor Review
+
+Owner:
+- supervisor using our app, not Box
+
+System actions:
+- review image
+- review readable summary
+- review severity, duplicate status, weather, ward, district, and zone
+- choose:
+  - approve
+  - reject
+  - merge duplicate
+
+Status:
+- `Under Review` until approved or rejected
+
+Suggested result fields:
+- `supervisorDecision`
+- `supervisorReason`
+- `supervisorAt`
+- `supervisorBy`
+
+### Stage 4. Authority Notification
+
+Owner:
+- backend
+
+System actions:
+- only for approved primary cases
+- look up authority by district or maintenance zone
+- send authority email with case details
+- include Box folder path or Box link
+
+Status:
+- stays `Under Review` until dispatch is created
+
+### Stage 5. Work Order and Dispatch
+
+Owner:
+- dispatcher or backend
+
+System actions:
+- create work order outside Box
+- assign crew
+- generate route plan
+- save dispatch artifact to Box
+- patch backend case with crew assignment
+
+Status:
+- `Assigned`
+
+Main files:
+- `deploy-crew.html`
+
+### Stage 6. Crew Work Start
+
+Owner:
+- field crew
+
+System actions:
+- crew accepts assignment
+- mark start time
+- mark assigned crew and route stop
+
+Status:
+- `In Progress`
+
+### Stage 7. Crew Completion
+
+Owner:
+- field crew
+
+System actions:
+- submit after-photo
+- submit materials used
+- submit labor hours
+- submit repair notes
+- submit signature if required
+- upload closeout files to Box
+
+Status:
+- still `In Progress` until verified
+
+Suggested fields:
+- `afterPhotoFileId`
+- `materialsUsed`
+- `laborHours`
+- `resolutionNotes`
+- `crewSignature`
+- `completedAt`
+
+### Stage 8. Supervisor Closeout
+
+Owner:
+- supervisor
+
+System actions:
+- verify repair proof
+- verify after-photo
+- mark case resolved
+- optionally notify citizen
+
+Status:
+- `Resolved`
+
+### Stage 9. Reporting
+
+Owner:
+- backend
+
+System actions:
+- generate before/after report
+- generate daily and weekly summaries
+- upload reports to Box `Reports`
+
+Outputs:
+- per-case audit report
+- daily summary report
+- weekly summary report
+
+## 3. Box Folder Responsibilities
+
+Use Box for these artifacts only:
+
+- original photo
+- original JSON sidecar
+- enriched JSON
+- readable review summary
+- before and after photos
+- work order file
+- dispatch plan export
+- audit report
+- daily and weekly reports
+
+## 4. JSON Fields To Keep Standard
+
+These are the business fields we should keep stable:
+
+- `caseId`
+- `submittedAt`
+- `address`
+- `areaLabel`
+- `location.lat`
+- `location.lng`
+- `location.source`
+- `ward`
+- `district`
+- `maintenanceZone`
+- `duplicateStatus`
+- `weatherStatus`
+- `potholeSize`
+- `aiResult`
+- `aiPrediction`
+- `aiReviewStatus`
+- `aiReviewMessage`
+
+## 5. Current Best Operating Order
+
+1. Citizen submits report
+2. Box stores photo and intake JSON
+3. Ops review enriches the case outside Box
+4. Box stores the enriched JSON and review summary
+5. Supervisor reviews in our app
+6. Backend sends authority notification
+7. Dispatcher assigns crew and route
+8. Crew uploads closeout proof
+9. Backend generates reports into Box
+
+## 6. Immediate Next Build Order
+
+1. Supervisor decision outside Box
+2. Authority email automation outside Box
+3. Crew completion form outside Box
+4. Before/after report generator outside Box
+5. Save all artifacts back into Box

WORKFLOW_V2_GUIDE.md

@@ -0,0 +1,434 @@
+# Pothole Operations Workflow V2
+
+This is the recommended operating workflow for the current `pothole box` app.
+
+It is designed around the code that already exists:
+
+- Citizen intake: `index.html`, `app.js`, `box-upload.js`
+- Ops review and enrichment: `ops-review.html`, `enrichment.js`, `box-folders.js`
+- Shared case state: `server.js`, `backend-api.js`
+- Crew dispatch: `deploy-crew.html`
+- Citizen tracking: `track.html`
+- GIS routing: `gis.js`
+- Weather enrichment: `enrichment.js`
+
+## 1. Core Rules
+
+Use these rules everywhere.
+
+1. Keep only these public case statuses:
+   `Submitted`, `Under Review`, `Assigned`, `In Progress`, `Resolved`, `Rejected`
+
+2. Box is the file and metadata system:
+   photos, JSON sidecars, case folders, enriched files, dispatch artifacts, completion proof
+
+3. The backend is the shared live case state:
+   every screen should read and write through the backend, not only `localStorage`
+
+4. GIS, weather, AI, and duplicate detection are decision inputs:
+   they help routing and prioritization, but they do not auto-dispatch by themselves
+
+5. Authority email must not be sent on raw citizen submission:
+   send it only after supervisor approval and duplicate review
+
+6. Duplicate child cases must not create extra crew jobs:
+   one pothole cluster should have one active operational case owner
+
+7. A case is not truly closed until repair proof exists:
+   after-photo, crew notes, completion timestamp, and supervisor confirmation
+
+## 2. Recommended End-to-End Workflow
+
+### Stage 1. Citizen Submission
+
+Owner: citizen portal
+
+Trigger:
+- User submits photo, location, and optional contact
+
+System actions:
+- Run image and road checks
+- Capture GPS and reverse geocode
+- Resolve GIS mapping if configured
+- Upload photo and metadata sidecar to Box
+- Create initial workflow metadata
+- Upsert case to backend
+
+Status after this stage:
+- `Submitted`
+
+Files involved:
+- `index.html`
+- `app.js`
+- `box-upload.js`
+
+### Stage 2. Ops Enrichment
+
+Owner: ops review console
+
+Trigger:
+- New `Submitted` case appears in ops queue
+
+System actions:
+- Run severity enrichment
+- Check duplicates by GPS radius
+- Pull weather risk
+- Resolve district, ward, and maintenance zone
+- Organize the case into the correct Box folder
+- Write enriched metadata back to Box and backend
+
+Status after this stage:
+- `Under Review`
+
+Files involved:
+- `ops-review.html`
+- `enrichment.js`
+- `box-folders.js`
+- `gis.js`
+
+### Stage 3. Supervisor Decision
+
+Owner: supervisor
+
+Supervisor can choose one of three outcomes:
+
+1. Reject
+- Use when the report is invalid, unsafe, or not a pothole
+- Final status: `Rejected`
+
+2. Merge into an existing active case
+- Use when duplicate detection is confirmed
+- Do not create a new crew assignment
+- Do not send a new authority email
+- Keep one primary operational case for the cluster
+- Child case should stay linked to the parent in metadata
+
+3. Approve for action
+- Use when it is a valid pothole and should move to operations
+- Continue to authority notification and dispatch
+
+Status after approval:
+- Keep `Under Review` until authority notification and dispatch preparation are done
+
+Files involved:
+- `ops-review.html`
+
+### Stage 4. Authority Notification
+
+Owner: backend automation
+
+Trigger:
+- Supervisor approved the case
+- Case is the primary case in its duplicate cluster
+- District and maintenance zone are known
+
+Notification policy:
+
+1. Critical severity
+- Send immediately to the concerned authority and dispatch lead
+
+2. High, Medium, Low severity
+- Send in district or zone digest batches every 30 to 60 minutes
+
+Email must include:
+- Case ID
+- Address
+- GIS district, ward, maintenance zone
+- Severity score and level
+- Duplicate count and linked cases
+- Reporter count if relevant
+- Box folder path or Box folder link
+- Recommended next action
+
+Important guardrail:
+- Do not send one email per duplicate report
+
+Status after this stage:
+- Still `Under Review` until a crew is actually assigned
+
+Build needed:
+- Add backend email service and routing table
+
+### Stage 5. Crew Dispatch
+
+Owner: dispatcher or supervisor
+
+Trigger:
+- Approved primary case is ready for field work
+
+System actions:
+- Group approved active potholes by ward or zone
+- Generate route plan
+- Assign crew
+- Save dispatch plan
+- Push assignment to backend
+
+Status after this stage:
+- `Assigned`
+
+Files involved:
+- `deploy-crew.html`
+
+### Stage 6. Crew Work Start
+
+Owner: field crew
+
+Trigger:
+- Crew accepts the assignment or starts work on site
+
+System actions:
+- Mark case start time
+- Mark assigned crew
+- Optionally capture ETA or on-site note
+
+Status after this stage:
+- `In Progress`
+
+Build needed:
+- Crew action form or simple crew mobile screen
+
+### Stage 7. Crew Completion Form
+
+Owner: field crew
+
+Required fields:
+- Case ID
+- Crew name
+- Completion timestamp
+- After-photo
+- Repair notes
+- Material used or fill quantity
+- Could not complete reason, if blocked
+
+System actions:
+- Upload completion proof to Box
+- Patch backend case
+- Flag case for supervisor closeout
+
+Status after this stage:
+- Keep `In Progress` until supervisor verifies proof
+
+Build needed:
+- New crew completion form page tied to Box and backend
+
+### Stage 8. Supervisor Closeout
+
+Owner: supervisor
+
+Trigger:
+- Crew completion proof received
+
+System actions:
+- Review after-photo and notes
+- Confirm repair is complete
+- Mark resolved timestamp
+- Optionally notify citizen if contact was provided
+
+Status after this stage:
+- `Resolved`
+
+### Stage 9. Reporting
+
+Owner: backend automation
+
+Trigger:
+- Scheduled daily and weekly jobs
+
+Reports to generate:
+- New cases by district and ward
+- Duplicate clusters
+- Average approval time
+- Average assignment time
+- Average repair completion time
+- Open active cases by zone
+- Rejected reports
+- Weather-linked spikes
+- Crew productivity summary
+
+Output:
+- Save CSV or PDF report into a Box reports folder
+- Email summary to management if needed
+
+Build needed:
+- Scheduled report generator on backend
+
+## 3. Status Rules
+
+Use this as the single status policy.
+
+### `Submitted`
+
+Meaning:
+- Citizen report received
+- Photo and metadata saved
+- Waiting for ops enrichment
+
+### `Under Review`
+
+Meaning:
+- Ops is validating the report
+- Duplicate and routing checks are in progress
+- Supervisor approval is pending or just completed but dispatch is not done yet
+
+### `Assigned`
+
+Meaning:
+- A crew has been assigned
+- Dispatch plan exists
+
+### `In Progress`
+
+Meaning:
+- Crew is actively working or has started the job
+
+### `Resolved`
+
+Meaning:
+- Repair proof exists
+- Supervisor or workflow confirmed the fix
+
+### `Rejected`
+
+Meaning:
+- The report is invalid or closed without field action
+
+## 4. What Should Live Where
+
+### Keep in Box
+
+- Original photo
+- Original metadata sidecar
+- Enriched metadata file
+- Case folder metadata
+- Dispatch sheet
+- After-photo and repair proof
+- Final reports
+
+### Keep in Backend
+
+- Current status
+- Current assignee
+- Workflow timestamps
+- Parent and child duplicate links
+- Authority email audit trail
+- Crew start and completion data
+
+### Keep as Integrations
+
+- GIS boundary lookup
+- Weather forecast lookup
+- Email delivery
+
+## 5. Safe Rollout Order
+
+This is the best order to implement without breaking the app.
+
+### Step 1. Stabilize shared case state
+
+Do first.
+
+Goal:
+- Make the backend the live source of truth across intake, ops review, dispatch, and tracking
+
+Why:
+- Right now some workflow still depends on `localStorage`, which is risky for multi-user operations
+
+### Step 2. Lock the status model
+
+Do second.
+
+Goal:
+- Use only the six public statuses already supported by the tracking UI
+
+Why:
+- Avoid adding new public statuses until the tracking and review UIs are updated together
+
+### Step 3. Add authority routing table
+
+Do third.
+
+Goal:
+- Map each district or maintenance zone to the correct authority email list
+
+Needed fields:
+- `district`
+- `ward`
+- `maintenanceZone`
+- `authorityEmails`
+- `dispatchEmails`
+
+### Step 4. Add real authority email automation
+
+Do fourth.
+
+Goal:
+- Send approved active pothole notifications from the backend
+
+Rules:
+- Immediate for `Critical`
+- Batched digest for the rest
+- No email for duplicate child cases
+
+### Step 5. Add crew completion form
+
+Do fifth.
+
+Goal:
+- Give crews a proper way to upload after-photos and repair notes
+
+### Step 6. Add closeout verification
+
+Do sixth.
+
+Goal:
+- Resolve only after proof is reviewed
+
+### Step 7. Add scheduled reporting
+
+Do seventh.
+
+Goal:
+- Auto-generate daily and weekly reports into Box
+
+### Step 8. Move secrets off the browser
+
+Do this before production use.
+
+Goal:
+- Remove Box and weather secrets from browser storage
+- Keep them on the backend instead
+
+## 6. Immediate Next Recommendation
+
+If you want the cleanest next build step, do this first:
+
+1. Make backend case sync the source of truth
+2. Add authority email automation on approved primary cases
+3. Add crew completion form
+4. Add daily and weekly report generator
+
+That order gives you the biggest operational improvement with the least confusion.
+
+## 7. Short Version
+
+The correct workflow is:
+
+1. Citizen submits report
+2. Ops enriches and checks duplicates
+3. Supervisor rejects, merges, or approves
+4. Backend notifies the correct authority
+5. Dispatcher assigns crew
+6. Crew marks work in progress
+7. Crew submits completion proof
+8. Supervisor closes the case
+9. Backend generates reports
+
+The most important correction is this:
+
+Do not treat Box alone as the whole system.
+
+Use:
+- Box for files and workflow metadata
+- Backend for live state and automation
+- GIS and weather as decision inputs
+- Email and reports as backend-driven automations

add-supervisor.js

@@ -0,0 +1,38 @@
+/**
+ * Add (or update) a supervisor who can access the Command Center.
+ *
+ * Usage:
+ *   SUPABASE_URL=... SUPABASE_SECRET_KEY=sb_secret_... \
+ *     node add-supervisor.js <email> <password>
+ *
+ * Creates an auto-confirmed Supabase user with app_metadata.role = "supervisor"
+ * (the role the backend + login page require). Re-running for an existing email
+ * resets the password and ensures the role.
+ */
+'use strict';
+const { createClient } = require('@supabase/supabase-js');
+
+const URL = process.env.SUPABASE_URL;
+const SECRET = process.env.SUPABASE_SECRET_KEY || process.env.SUPABASE_KEY;
+const [email, password] = process.argv.slice(2);
+
+if (!URL || !SECRET) { console.error('Set SUPABASE_URL and SUPABASE_SECRET_KEY env vars.'); process.exit(1); }
+if (!email || !password) { console.error('Usage: node add-supervisor.js <email> <password>'); process.exit(1); }
+
+(async () => {
+  const admin = createClient(URL, SECRET, { auth: { persistSession: false } });
+  const { error } = await admin.auth.admin.createUser({
+    email, password, email_confirm: true, app_metadata: { role: 'supervisor' },
+  });
+  if (error && /already/i.test(error.message)) {
+    const list = await admin.auth.admin.listUsers();
+    const u = list.data.users.find((x) => x.email === email);
+    if (!u) { console.error('User exists but could not be located.'); process.exit(1); }
+    await admin.auth.admin.updateUserById(u.id, { password, app_metadata: { role: 'supervisor' } });
+    console.log('Updated supervisor:', email);
+  } else if (error) {
+    console.error('Error:', error.message); process.exit(1);
+  } else {
+    console.log('Created supervisor:', email);
+  }
+})().catch((e) => { console.error('ERROR', e.message); process.exit(1); });

ai/detect_pothole.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python
+"""
+Open-source pothole classifier — YOLOv8 (Ultralytics), runs locally, no API cost.
+Model: peterhdd/pothole-detection-yolov8 (single "pothole" class).
+
+Usage:  python ai/detect_pothole.py <image_path>
+Output: one line of JSON on stdout:
+  {"isPothole": bool, "confidence": float, "size": "Small|Medium|Large"|null,
+   "count": int, "largestAreaFraction": float, "boxes": [...], "model": "..."}
+Errors are also returned as JSON: {"error": "..."}.
+"""
+import sys
+import os
+import json
+
+# Size thresholds: largest detection box area as a fraction of the whole frame.
+# A single 2D photo has no true scale, so this is a heuristic proxy (tune as needed).
+SIZE_LARGE = 0.12
+SIZE_MEDIUM = 0.04
+CONF_THRESHOLD = 0.25
+MODEL_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "pothole-yolov8.pt")
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(json.dumps({"error": "usage: detect_pothole.py <image_path>"}))
+        return
+    image_path = sys.argv[1]
+    if not os.path.exists(image_path):
+        print(json.dumps({"error": "image not found: " + image_path}))
+        return
+    if not os.path.exists(MODEL_FILE):
+        print(json.dumps({"error": "model file missing: " + MODEL_FILE}))
+        return
+    try:
+        from ultralytics import YOLO
+    except Exception as e:  # noqa: BLE001
+        print(json.dumps({"error": "ultralytics not installed: " + str(e)}))
+        return
+
+    try:
+        model = YOLO(MODEL_FILE)
+        result = model.predict(image_path, conf=CONF_THRESHOLD, verbose=False)[0]
+        h, w = result.orig_shape
+        frame_area = float(h * w) if h and w else 1.0
+
+        boxes = []
+        max_frac = 0.0
+        max_conf = 0.0
+        for b in result.boxes:
+            x1, y1, x2, y2 = (float(v) for v in b.xyxy[0].tolist())
+            conf = float(b.conf[0])
+            frac = ((x2 - x1) * (y2 - y1)) / frame_area
+            boxes.append({
+                "x1": round(x1), "y1": round(y1), "x2": round(x2), "y2": round(y2),
+                "conf": round(conf, 3), "areaFraction": round(frac, 4),
+            })
+            max_frac = max(max_frac, frac)
+            max_conf = max(max_conf, conf)
+
+        is_pothole = len(boxes) > 0
+        if not is_pothole:
+            size = None
+        elif max_frac >= SIZE_LARGE:
+            size = "Large"
+        elif max_frac >= SIZE_MEDIUM:
+            size = "Medium"
+        else:
+            size = "Small"
+
+        print(json.dumps({
+            "isPothole": is_pothole,
+            "confidence": round(max_conf, 3),
+            "size": size,
+            "count": len(boxes),
+            "largestAreaFraction": round(max_frac, 4),
+            "boxes": boxes,
+            "model": "peterhdd/pothole-detection-yolov8",
+        }))
+    except Exception as e:  # noqa: BLE001
+        print(json.dumps({"error": str(e)}))
+
+
+if __name__ == "__main__":
+    main()

ai/gen_closeout.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python
+"""Generate a clean Pothole Repair CLOSEOUT / Job Completion Sheet (.docx).
+
+The post-repair record the crew completes (often via Box Forms): what was done,
+materials, hours, before/after photos, actual cost, inspection, sign-off.
+
+Usage:  python gen_closeout.py <spec.json> <output.docx>
+Works for live docs AND as a Box Doc Gen template when values are {{tags}}.
+"""
+import sys
+import os
+import json
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from docx import Document
+from docx.shared import Pt, Inches, RGBColor
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.enum.table import WD_ALIGN_VERTICAL
+from docx.oxml.ns import qn
+from docx.oxml import OxmlElement
+# reuse the work order's polished styling helpers for a consistent look
+from gen_workorder import (
+    NAVY, GREY, LIGHT, DARK, WHITE,
+    shade, no_borders, grid, cell_pad, widths, run, spacer, section, info_grid, sign_block,
+)
+
+GREEN = RGBColor(0x15, 0x7A, 0x3F)
+
+
+def photo_row(doc, before, after):
+    """Two-column before/after photo row (embeds files; otherwise shows the link/placeholder)."""
+    t = doc.add_table(rows=2, cols=2)
+    no_borders(t)
+    cell_pad(t, top=20, bottom=20, left=20, right=80)
+    run(t.cell(0, 0).paragraphs[0], "BEFORE (reported)", size=7.5, bold=True, color=LIGHT, caps=True)
+    run(t.cell(0, 1).paragraphs[0], "AFTER (repaired)", size=7.5, bold=True, color=LIGHT, caps=True)
+    for col, val in ((0, before), (1, after)):
+        cell = t.cell(1, col)
+        p = cell.paragraphs[0]
+        if val and os.path.exists(str(val)):
+            try:
+                run(p, "")
+                p.add_run().add_picture(val, width=Inches(3.0))
+                continue
+            except Exception:
+                pass
+        if val:
+            run(p, str(val), size=9, color=NAVY)
+        else:
+            run(p, "☐  photo attached", size=9.5, color=GREY)
+    widths(t, [3.45, 3.45])
+
+
+def main():
+    if len(sys.argv) < 3:
+        print(json.dumps({"error": "usage: gen_closeout.py <spec.json> <output.docx>"}))
+        return
+    with open(sys.argv[1], "r", encoding="utf-8") as f:
+        s = json.load(f)
+    out_path = sys.argv[2]
+    g = lambda k, d="": s.get(k) if s.get(k) not in (None, "") else d  # noqa: E731
+
+    doc = Document()
+    normal = doc.styles["Normal"]
+    normal.font.name = "Calibri"
+    normal.font.size = Pt(10)
+    normal.font.color.rgb = DARK
+    for sec in doc.sections:
+        sec.left_margin = sec.right_margin = Inches(0.75)
+        sec.top_margin = sec.bottom_margin = Inches(0.6)
+
+    # ── Header ───────────────────────────────────────────────────────────────
+    head = doc.add_table(rows=1, cols=2)
+    no_borders(head)
+    cell_pad(head, 0, 0, 0, 0)
+    L = head.cell(0, 0).paragraphs[0]
+    run(L, g("city", "City of Philadelphia"), size=9, bold=True, color=NAVY)
+    L.add_run("\n")
+    run(L, g("department", "Department of Streets · Road Maintenance Division"), size=8.5, color=GREY)
+    L.add_run("\n\n")
+    run(L, "Pothole Repair — Closeout Job Sheet", size=18, bold=True, color=DARK)
+    R = head.cell(0, 1)
+    rp = R.paragraphs[0]
+    rp.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    run(rp, "CASE ID", size=7.5, bold=True, color=LIGHT, caps=True)
+    rp2 = R.add_paragraph(); rp2.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    run(rp2, g("caseId", "____________"), size=15, bold=True, color=NAVY)
+    rp4 = R.add_paragraph(); rp4.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    run(rp4, "Status  ", size=9, color=GREY)
+    run(rp4, "COMPLETED", size=9, bold=True, color=GREEN)
+    widths(head, [4.0, 3.0])
+
+    rule = doc.add_paragraph(); rule.paragraph_format.space_before = Pt(4); rule.paragraph_format.space_after = Pt(2)
+    pbdr = OxmlElement("w:pBdr"); b = OxmlElement("w:bottom")
+    b.set(qn("w:val"), "single"); b.set(qn("w:sz"), "18"); b.set(qn("w:color"), "0B3D91")
+    pbdr.append(b); rule._p.get_or_add_pPr().append(pbdr)
+
+    # ── Repair details (ONLY the crew closeout form fields) ──────────────────
+    section(doc, "Repair Details")
+    info_grid(doc, [
+        ("Case ID", g("caseId")),
+        ("Repair Completed?", g("repairCompleted", "☐ Yes    ☐ No")),
+        ("Repair Method", g("repairMethods", "____________________")),
+        ("Materials Used", g("materialsUsed", "____________________")),
+        ("Labor Hours", g("laborHours", "________")),
+    ])
+
+    # ── Crew (from the form) ─────────────────────────────────────────────────
+    section(doc, "Crew")
+    info_grid(doc, [
+        ("Crew Name", g("crewName", "____________________")),
+        ("Crew Contact Number", g("crewContact", "____________________")),
+    ], cols=2)
+
+    # ── Reported photo (the citizen's pre-repair photo, so the crew sees what to fix) ──
+    reported = s.get("reportedPhotoPath")
+    if reported and os.path.exists(str(reported)):
+        section(doc, "Reported Photo (Pre-Repair)")
+        try:
+            doc.add_picture(reported, width=Inches(4.2))
+        except Exception:
+            pass
+
+    # ── After photo (from the form) ──────────────────────────────────────────
+    section(doc, "After Photo")
+    after = s.get("afterPhotoPath") or g("afterPhoto")
+    if after and os.path.exists(str(after)):
+        try:
+            doc.add_picture(after, width=Inches(4.2))
+        except Exception:
+            run(doc.add_paragraph(), str(after), size=9.5, color=NAVY)
+    elif after:
+        run(doc.add_paragraph(), str(after), size=9.5, color=NAVY)
+    else:
+        run(doc.add_paragraph(), "☐  photo attached to closeout form", size=9.5, color=GREY)
+
+    # ── Sign-off ─────────────────────────────────────────────────────────────
+    section(doc, "Sign-Off")
+    sign_block(doc, ["Crew Foreman", "Supervisor"])
+
+    foot = doc.add_paragraph(); foot.paragraph_format.space_before = Pt(10)
+    run(foot, "Generated by PotholeIQ" + ("  ·  " + g("completedDate") if g("completedDate") else ""), size=8, italic=True, color=LIGHT)
+
+    doc.save(out_path)
+    print(json.dumps({"ok": True, "output": out_path}))
+
+
+if __name__ == "__main__":
+    main()

ai/gen_doc.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python
+"""Generate a styled .docx (Review Sheet or Work Order) with the pothole photo embedded.
+
+Box Doc Gen cannot reliably embed an image-from-URL, so we render the document here
+with python-docx (the image embeds cleanly and Box previews .docx natively).
+
+Usage:  python gen_doc.py <spec.json> <output.docx>
+
+spec.json:
+{
+  "title": "...", "subtitle": "...",
+  "meta": [["Label","Value"], ...],          # small lines under the title (optional)
+  "sections": [ {"heading":"...", "fields":[["Label","Value"], ...]}, ... ],
+  "imagePath": "/abs/path/photo.jpg" | null,
+  "imageCaption": "..." | null,
+  "notes": "..." | null,
+  "accent": "0061D5"                          # hex, optional (Box blue default)
+}
+"""
+import sys
+import os
+import json
+from docx import Document
+from docx.shared import Pt, Inches, RGBColor
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+
+
+def hex_rgb(h, default=(0x00, 0x61, 0xD5)):
+    try:
+        h = (h or "").lstrip("#")
+        return RGBColor(int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
+    except Exception:
+        return RGBColor(*default)
+
+
+GREY = RGBColor(0x5B, 0x64, 0x76)
+DARK = RGBColor(0x17, 0x20, 0x33)
+
+
+def add_title(doc, title, subtitle, accent):
+    p = doc.add_paragraph()
+    r = p.add_run(title or "")
+    r.bold = True
+    r.font.size = Pt(22)
+    r.font.color.rgb = accent
+    if subtitle:
+        p2 = doc.add_paragraph()
+        r2 = p2.add_run(subtitle)
+        r2.font.size = Pt(11)
+        r2.font.color.rgb = GREY
+
+
+def add_meta(doc, meta):
+    if not meta:
+        return
+    for label, value in meta:
+        p = doc.add_paragraph()
+        p.paragraph_format.space_after = Pt(0)
+        rl = p.add_run(f"{label}:  ")
+        rl.bold = True
+        rl.font.size = Pt(9)
+        rl.font.color.rgb = GREY
+        rv = p.add_run("" if value is None else str(value))
+        rv.font.size = Pt(9)
+        rv.font.color.rgb = DARK
+
+
+def add_heading(doc, text, accent):
+    p = doc.add_paragraph()
+    p.paragraph_format.space_before = Pt(12)
+    r = p.add_run((text or "").upper())
+    r.bold = True
+    r.font.size = Pt(11)
+    r.font.color.rgb = accent
+
+
+def add_images_grid(doc, images, accent):
+    """Lay out a list of {path, caption} images. Two images -> side-by-side
+    before/after; otherwise stacked. Each gets its caption underneath."""
+    valid = [im for im in images if im.get("path") and os.path.exists(im["path"])]
+    if not valid:
+        return
+    add_heading(doc, "Before / After Photos", accent)
+    if len(valid) == 2:
+        table = doc.add_table(rows=1, cols=2)
+        for cell, im in zip(table.rows[0].cells, valid):
+            p = cell.paragraphs[0]
+            p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+            try:
+                p.add_run().add_picture(im["path"], width=Inches(3.05))
+            except Exception as e:  # noqa: BLE001
+                p.add_run(f"[photo could not be embedded: {e}]").font.size = Pt(9)
+            cap = cell.add_paragraph()
+            cap.alignment = WD_ALIGN_PARAGRAPH.CENTER
+            rc = cap.add_run(im.get("caption") or "")
+            rc.bold = True
+            rc.font.size = Pt(9)
+            rc.font.color.rgb = GREY
+        return
+    for im in valid:
+        try:
+            doc.add_picture(im["path"], width=Inches(4.6))
+            doc.paragraphs[-1].alignment = WD_ALIGN_PARAGRAPH.LEFT
+        except Exception as e:  # noqa: BLE001
+            doc.add_paragraph().add_run(f"[photo could not be embedded: {e}]").font.size = Pt(9)
+        cap = im.get("caption")
+        if cap:
+            pc = doc.add_paragraph()
+            rc = pc.add_run(cap)
+            rc.italic = True
+            rc.font.size = Pt(9)
+            rc.font.color.rgb = GREY
+
+
+def add_kv_table(doc, fields):
+    table = doc.add_table(rows=0, cols=2)
+    table.style = "Light List Accent 1"
+    for label, value in fields:
+        cells = table.add_row().cells
+        rl = cells[0].paragraphs[0].add_run(str(label))
+        rl.bold = True
+        rl.font.size = Pt(9)
+        rl.font.color.rgb = GREY
+        val = "—" if value in (None, "") else str(value)
+        rv = cells[1].paragraphs[0].add_run(val)
+        rv.font.size = Pt(11)
+        rv.font.color.rgb = DARK
+    for row in table.rows:
+        row.cells[0].width = Inches(2.3)
+        row.cells[1].width = Inches(4.0)
+
+
+def main():
+    if len(sys.argv) < 3:
+        print(json.dumps({"error": "usage: gen_doc.py <spec.json> <output.docx>"}))
+        return
+    spec_path, out_path = sys.argv[1], sys.argv[2]
+    with open(spec_path, "r", encoding="utf-8") as f:
+        spec = json.load(f)
+
+    accent = hex_rgb(spec.get("accent"))
+    doc = Document()
+    for s in doc.sections:
+        s.left_margin = s.right_margin = Inches(0.8)
+        s.top_margin = s.bottom_margin = Inches(0.7)
+
+    add_title(doc, spec.get("title"), spec.get("subtitle"), accent)
+    add_meta(doc, spec.get("meta") or [])
+
+    for section in spec.get("sections") or []:
+        add_heading(doc, section.get("heading"), accent)
+        add_kv_table(doc, section.get("fields") or [])
+
+    # Multi-image (e.g. before/after) takes precedence over a single site photo.
+    images = spec.get("images")
+    if isinstance(images, list) and images:
+        add_images_grid(doc, images, accent)
+
+    image_path = spec.get("imagePath")
+    if not (isinstance(images, list) and images) and image_path and os.path.exists(image_path):
+        add_heading(doc, "Site Photo", accent)
+        try:
+            doc.add_picture(image_path, width=Inches(4.6))
+            doc.paragraphs[-1].alignment = WD_ALIGN_PARAGRAPH.LEFT
+            cap = spec.get("imageCaption")
+            if cap:
+                pc = doc.add_paragraph()
+                rc = pc.add_run(cap)
+                rc.italic = True
+                rc.font.size = Pt(9)
+                rc.font.color.rgb = GREY
+        except Exception as e:  # noqa: BLE001
+            pe = doc.add_paragraph()
+            pe.add_run(f"[photo could not be embedded: {e}]").font.size = Pt(9)
+
+    notes = spec.get("notes")
+    if notes:
+        add_heading(doc, "Notes", accent)
+        doc.add_paragraph(str(notes))
+
+    doc.save(out_path)
+    print(json.dumps({"ok": True, "output": out_path}))
+
+
+if __name__ == "__main__":
+    main()

ai/gen_workorder.py

@@ -0,0 +1,343 @@
+#!/usr/bin/env python
+"""Generate a clean, professional municipal Pothole Repair WORK ORDER (.docx).
+
+Modeled on standard public-works work order forms. Known data is filled in;
+crew-completed sections are blank lines / checkboxes.
+
+Usage:  python gen_workorder.py <spec.json> <output.docx>
+(Same spec keys as before — works for live docs AND as a Box Doc Gen template
+when values are passed as {{tags}}.)
+"""
+import sys
+import os
+import json
+from docx import Document
+from docx.shared import Pt, Inches, RGBColor
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.enum.table import WD_ALIGN_VERTICAL
+from docx.oxml.ns import qn
+from docx.oxml import OxmlElement
+
+NAVY = RGBColor(0x0B, 0x3D, 0x91)
+GREY = RGBColor(0x6B, 0x72, 0x80)
+LIGHT = RGBColor(0x9A, 0xA1, 0xAD)
+DARK = RGBColor(0x1A, 0x1F, 0x2B)
+WHITE = RGBColor(0xFF, 0xFF, 0xFF)
+
+
+# ── low-level helpers ────────────────────────────────────────────────────────
+def shade(cell, hex_fill):
+    tcPr = cell._tc.get_or_add_tcPr()
+    shd = OxmlElement("w:shd")
+    shd.set(qn("w:val"), "clear")
+    shd.set(qn("w:color"), "auto")
+    shd.set(qn("w:fill"), hex_fill)
+    tcPr.append(shd)
+
+
+def no_borders(table):
+    borders = OxmlElement("w:tblBorders")
+    for edge in ("top", "left", "bottom", "right", "insideH", "insideV"):
+        e = OxmlElement(f"w:{edge}")
+        e.set(qn("w:val"), "none")
+        borders.append(e)
+    table._tbl.tblPr.append(borders)
+
+
+def hairlines(table, color="E3E7EE"):
+    """Subtle horizontal rules only — clean ledger look."""
+    borders = OxmlElement("w:tblBorders")
+    for edge in ("top", "left", "right", "insideV"):
+        e = OxmlElement(f"w:{edge}")
+        e.set(qn("w:val"), "none")
+        borders.append(e)
+    for edge in ("bottom", "insideH"):
+        e = OxmlElement(f"w:{edge}")
+        e.set(qn("w:val"), "single")
+        e.set(qn("w:sz"), "4")
+        e.set(qn("w:color"), color)
+        borders.append(e)
+    table._tbl.tblPr.append(borders)
+
+
+def grid(table, color="D7DCE5"):
+    borders = OxmlElement("w:tblBorders")
+    for edge in ("top", "left", "bottom", "right", "insideH", "insideV"):
+        e = OxmlElement(f"w:{edge}")
+        e.set(qn("w:val"), "single")
+        e.set(qn("w:sz"), "4")
+        e.set(qn("w:color"), color)
+        borders.append(e)
+    table._tbl.tblPr.append(borders)
+
+
+def cell_pad(table, top=60, bottom=60, left=100, right=100):
+    mar = OxmlElement("w:tblCellMar")
+    for side, val in (("top", top), ("bottom", bottom), ("left", left), ("right", right)):
+        e = OxmlElement(f"w:{side}")
+        e.set(qn("w:w"), str(val))
+        e.set(qn("w:type"), "dxa")
+        mar.append(e)
+    table._tbl.tblPr.append(mar)
+
+
+def widths(table, ws):
+    for row in table.rows:
+        for i, w in enumerate(ws):
+            if i < len(row.cells):
+                row.cells[i].width = Inches(w)
+
+
+def run(p, text, size=10, bold=False, color=DARK, italic=False, caps=False):
+    r = p.add_run(text)
+    r.bold = bold
+    r.italic = italic
+    r.font.size = Pt(size)
+    r.font.color.rgb = color
+    if caps:
+        rPr = r._element.get_or_add_rPr()
+        c = OxmlElement("w:caps")
+        c.set(qn("w:val"), "true")
+        rPr.append(c)
+    return r
+
+
+def spacer(doc, pt=6):
+    p = doc.add_paragraph()
+    p.paragraph_format.space_after = Pt(0)
+    p.paragraph_format.space_before = Pt(0)
+    p.add_run("").font.size = Pt(pt)
+
+
+# ── building blocks ──────────────────────────────────────────────────────────
+def section(doc, text):
+    spacer(doc, 4)
+    t = doc.add_table(rows=1, cols=1)
+    no_borders(t)
+    cell_pad(t, top=50, bottom=50, left=120, right=120)
+    c = t.cell(0, 0)
+    shade(c, "0B3D91")
+    p = c.paragraphs[0]
+    run(p, text, size=9.5, bold=True, color=WHITE, caps=True)
+    spacer(doc, 2)
+
+
+def info_grid(doc, pairs, cols=2):
+    rows = (len(pairs) + cols - 1) // cols
+    t = doc.add_table(rows=rows, cols=cols)
+    hairlines(t)
+    cell_pad(t, top=70, bottom=70, left=40, right=160)
+    for i, (label, value) in enumerate(pairs):
+        cell = t.cell(i // cols, i % cols)
+        cell.vertical_alignment = WD_ALIGN_VERTICAL.CENTER
+        p = cell.paragraphs[0]
+        p.paragraph_format.space_after = Pt(1)
+        run(p, label, size=7.5, bold=True, color=LIGHT, caps=True)
+        p2 = cell.add_paragraph()
+        p2.paragraph_format.space_before = Pt(0)
+        run(p2, "—" if value in (None, "") else str(value), size=10.5, color=DARK)
+    widths(t, [3.45] * cols)
+    return t
+
+
+def checklist(doc, title, items, per_row=3):
+    p = doc.add_paragraph()
+    p.paragraph_format.space_after = Pt(3)
+    run(p, title, size=8.5, bold=True, color=GREY, caps=True)
+    rows = (len(items) + per_row - 1) // per_row
+    t = doc.add_table(rows=rows, cols=per_row)
+    no_borders(t)
+    cell_pad(t, top=30, bottom=30, left=20, right=40)
+    for i, item in enumerate(items):
+        run(t.cell(i // per_row, i % per_row).paragraphs[0], "☐  " + item, size=9.5, color=DARK)
+
+
+def sign_block(doc, roles):
+    t = doc.add_table(rows=len(roles), cols=3)
+    no_borders(t)
+    cell_pad(t, top=130, bottom=40, left=0, right=80)
+    for i, role in enumerate(roles):
+        run(t.cell(i, 0).paragraphs[0], role, size=9, bold=True, color=GREY, caps=True)
+        run(t.cell(i, 1).paragraphs[0], "—" * 26, size=10, color=RGBColor(0xC2, 0xC8, 0xD2))
+        run(t.cell(i, 2).paragraphs[0], "Date: " + "—" * 10, size=9, color=GREY)
+    widths(t, [1.7, 3.2, 1.4])
+
+
+# ── main ─────────────────────────────────────────────────────────────────────
+def main():
+    if len(sys.argv) < 3:
+        print(json.dumps({"error": "usage: gen_workorder.py <spec.json> <output.docx>"}))
+        return
+    with open(sys.argv[1], "r", encoding="utf-8") as f:
+        s = json.load(f)
+    out_path = sys.argv[2]
+    g = lambda k, d="": s.get(k) if s.get(k) not in (None, "") else d  # noqa: E731
+
+    doc = Document()
+    normal = doc.styles["Normal"]
+    normal.font.name = "Calibri"
+    normal.font.size = Pt(10)
+    normal.font.color.rgb = DARK
+    for sec in doc.sections:
+        sec.left_margin = sec.right_margin = Inches(0.75)
+        sec.top_margin = sec.bottom_margin = Inches(0.6)
+
+    # ── Header band ──────────────────────────────────────────────────────────
+    head = doc.add_table(rows=1, cols=2)
+    no_borders(head)
+    cell_pad(head, top=0, bottom=0, left=0, right=0)
+    L = head.cell(0, 0).paragraphs[0]
+    run(L, g("city", "City of Philadelphia"), size=9, bold=True, color=NAVY)
+    L.add_run("\n")
+    run(L, g("department", "Department of Streets · Road Maintenance Division"), size=8.5, color=GREY)
+    L.add_run("\n\n")
+    run(L, "Pothole Repair Work Order", size=19, bold=True, color=DARK)
+
+    R = head.cell(0, 1)
+    R.vertical_alignment = WD_ALIGN_VERTICAL.TOP
+    rp = R.paragraphs[0]
+    rp.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    run(rp, "WORK ORDER NO.", size=7.5, bold=True, color=LIGHT, caps=True)
+    rp2 = R.add_paragraph()
+    rp2.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    run(rp2, g("workOrderId", "WO-________"), size=15, bold=True, color=NAVY)
+    rp3 = R.add_paragraph()
+    rp3.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    run(rp3, "Issued  ", size=9, color=GREY)
+    run(rp3, g("issuedDate", "____________"), size=9, bold=True, color=DARK)
+    rp4 = R.add_paragraph()
+    rp4.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    run(rp4, "Priority  ", size=9, color=GREY)
+    run(rp4, g("priority", "________"), size=9, bold=True, color=RGBColor(0xC2, 0x41, 0x0C))
+    run(rp4, "    Status  ", size=9, color=GREY)
+    run(rp4, g("status", "OPEN"), size=9, bold=True, color=DARK)
+    widths(head, [4.0, 3.0])
+
+    # navy rule
+    rule = doc.add_paragraph()
+    rule.paragraph_format.space_before = Pt(4)
+    rule.paragraph_format.space_after = Pt(2)
+    pbdr = OxmlElement("w:pBdr")
+    b = OxmlElement("w:bottom")
+    b.set(qn("w:val"), "single")
+    b.set(qn("w:sz"), "18")
+    b.set(qn("w:color"), "0B3D91")
+    pbdr.append(b)
+    rule._p.get_or_add_pPr().append(pbdr)
+
+    # ── Sections ─────────────────────────────────────────────────────────────
+    section(doc, "Request Information")
+    info_grid(doc, [
+        ("Case / Request ID", g("caseId")),
+        ("Date Reported", g("reportedDate")),
+        ("Reported By", g("reportedBy", "Citizen")),
+        ("Source", g("source", "Citizen Portal (PotholeIQ)")),
+        ("AI Review Status", g("aiReviewStatus")),
+        ("Duplicate Status", g("duplicateStatus")),
+    ])
+
+    section(doc, "Location")
+    info_grid(doc, [
+        ("Address", g("address")),
+        ("GPS Coordinates", g("coords")),
+        ("Ward", g("ward")),
+        ("District", g("district")),
+        ("Maintenance Zone", g("zone")),
+        ("Cross Streets", g("crossStreets", "—")),
+    ])
+
+    section(doc, "Defect Description")
+    info_grid(doc, [
+        ("Defect Type", g("defectType", "Pothole")),
+        ("Pothole Size (AI)", g("size")),
+        ("Severity Score", g("severityScore")),
+        ("Severity Level", g("severityLevel")),
+        ("Road Surface", g("roadSurface", "Asphalt")),
+        ("Weather Risk", g("weatherRisk")),
+    ])
+
+    if s.get("summary"):
+        section(doc, "AI Case Summary")
+        run(doc.add_paragraph(), s.get("summary"), size=10, color=DARK)
+
+    img = s.get("imagePath")
+    if img and os.path.exists(img):
+        section(doc, "Site Photo (Pre-Repair)")
+        try:
+            doc.add_picture(img, width=Inches(4.4))
+            run(doc.add_paragraph(), "Citizen-submitted, AI-classified photo. Verify extent on arrival.", size=8.5, italic=True, color=GREY)
+        except Exception as e:  # noqa: BLE001
+            run(doc.add_paragraph(), f"[photo not embedded: {e}]", size=9, color=GREY)
+    elif s.get("photoUrl"):
+        section(doc, "Site Photo (Pre-Repair)")
+        p = doc.add_paragraph()
+        run(p, "View photo:  ", size=9.5, bold=True, color=GREY)
+        run(p, s.get("photoUrl"), size=9.5, color=NAVY)
+
+    section(doc, "Assignment & Scheduling")
+    info_grid(doc, [
+        ("Assigned Crew / Foreman", g("assignedCrew", "____________________")),
+        ("Crew ID", g("crewId", "____________")),
+        ("Scheduled Date", g("scheduledDate", "____________")),
+        ("Target Completion (SLA)", g("targetDate", "____________")),
+        ("Estimated Labor Hours", g("estHours", "________")),
+        ("Authorized By", g("authorizedBy", "____________________")),
+    ])
+
+    section(doc, "Materials & Equipment")
+    checklist(doc, "Materials  (check + enter quantity)", [
+        "Cold Mix Asphalt   ____ t", "Hot Mix Asphalt   ____ t", "Tack Coat",
+        "Crack Sealant", "Aggregate / Gravel   ____", "Other:  __________",
+    ])
+    spacer(doc, 3)
+    checklist(doc, "Equipment", [
+        "Asphalt Roller", "Plate Compactor", "Dump Truck",
+        "Air Compressor", "Saw Cutter", "Hand Tools",
+    ])
+
+    section(doc, "Labor & Cost")
+    cost = doc.add_table(rows=5, cols=5)
+    grid(cost)
+    cell_pad(cost, top=50, bottom=50, left=90, right=90)
+    for j, h in enumerate(["Crew Member", "Role", "Hours", "Rate ($)", "Cost ($)"]):
+        c = cost.cell(0, j)
+        shade(c, "EEF2F9")
+        run(c.paragraphs[0], h, size=8.5, bold=True, color=NAVY)
+    widths(cost, [2.4, 1.4, 0.9, 1.0, 1.2])
+    tot = doc.add_paragraph()
+    tot.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    tot.paragraph_format.space_before = Pt(4)
+    run(tot, "Labor $ ______    Materials $ ______    Equipment $ ______    ", size=9.5, color=GREY)
+    run(tot, "TOTAL $ __________", size=10, bold=True, color=DARK)
+
+    section(doc, "Completion & Sign-Off")
+    run(doc.add_paragraph(), "Work Performed", size=8.5, bold=True, color=GREY, caps=True)
+    for _ in range(2):
+        p = doc.add_paragraph()
+        run(p, "—" * 78, size=10, color=RGBColor(0xD7, 0xDC, 0xE5))
+    spacer(doc, 2)
+    info_grid(doc, [
+        ("Date Started", "____________"),
+        ("Date Completed", "____________"),
+        ("Actual Labor Hours", "________"),
+        ("After Photo Attached", "☐ Yes    ☐ No"),
+    ])
+    spacer(doc, 4)
+    sign_block(doc, ["Crew Foreman", "Supervisor Approval", "Inspector Sign-Off"])
+
+    section(doc, "Safety / Traffic Control")
+    checklist(doc, "Measures used", [
+        "Cones / Barricades", "Flagger", "Lane Closure",
+        "Advance Warning Signage", "Arrow Board", "None Required",
+    ])
+
+    foot = doc.add_paragraph()
+    foot.paragraph_format.space_before = Pt(10)
+    run(foot, "Generated by PotholeIQ" + ("  ·  " + g("issuedDate") if g("issuedDate") else ""), size=8, italic=True, color=LIGHT)
+
+    doc.save(out_path)
+    print(json.dumps({"ok": True, "output": out_path}))
+
+
+if __name__ == "__main__":
+    main()

ai/pothole-yolov8.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:af2ac6ce7bfec72e71643659ac946caf80ced84869e526a60135c457abfbb200
+size 22524266

ai/pothole_server.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python
+"""Persistent YOLOv8 pothole classifier worker (real-time).
+
+Loads the model ONCE at startup, then serves one request per line from stdin
+and writes one JSON result per line to stdout. This avoids the multi-second
+cold start of loading torch + the model on every request.
+
+Protocol:
+  startup -> emits {"ready": true}  (or {"error": "..."} and exits)
+  stdin   -> one image file path per line ("__quit__" to stop)
+  stdout  -> one JSON result per line:
+             {"isPothole":bool,"confidence":float,"size":"Small|Medium|Large"|null,
+              "count":int,"largestAreaFraction":float,"boxes":[...],"model":"..."}
+             or {"error":"..."} for that request.
+"""
+import sys
+import os
+import json
+
+# Size = area (as a fraction of the whole frame) of the largest *confident* pothole
+# detection. A single 2D photo has no true scale, so box area is a heuristic proxy.
+#   >= SIZE_LARGE  -> Large
+#   >= SIZE_MEDIUM -> Medium
+#   else           -> Small
+# Thresholds are calibrated to the ground-truth pothole box-area distribution
+# (3,625 annotated boxes): SIZE_MEDIUM ~= 40th percentile, SIZE_LARGE ~= 82nd
+# percentile. That yields a sensible operational split of roughly 40% Small /
+# 42% Medium / 18% Large instead of over-calling everything "Small".
+SIZE_LARGE = 0.09
+SIZE_MEDIUM = 0.013
+# CONF_THRESHOLD: minimum confidence for a box to count as a detection at all.
+CONF_THRESHOLD = 0.25
+# SIZE_CONF_FLOOR: a box must clear this higher bar before its area is allowed to
+# drive the size label. This stops low-confidence, sprawling false boxes (e.g. a
+# shadow spanning the frame) from inflating a real, smaller pothole to "Large".
+SIZE_CONF_FLOOR = 0.45
+MODEL_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "pothole-yolov8.pt")
+
+
+def emit(obj):
+    sys.stdout.write(json.dumps(obj) + "\n")
+    sys.stdout.flush()
+
+
+def classify(model, image_path):
+    if not os.path.exists(image_path):
+        return {"error": "image not found: " + image_path}
+    try:
+        result = model.predict(image_path, conf=CONF_THRESHOLD, verbose=False)[0]
+        h, w = result.orig_shape
+        frame_area = float(h * w) if h and w else 1.0
+
+        boxes = []
+        max_frac = 0.0          # largest box area (any confidence) — reported for transparency
+        max_conf = 0.0          # best detection confidence
+        size_frac = 0.0         # area that actually drives the size label (confident boxes only)
+        best_conf_frac = 0.0    # area of the single highest-confidence box (fallback)
+        best_conf = -1.0
+        for b in result.boxes:
+            x1, y1, x2, y2 = (float(v) for v in b.xyxy[0].tolist())
+            conf = float(b.conf[0])
+            frac = ((x2 - x1) * (y2 - y1)) / frame_area
+            boxes.append({
+                "x1": round(x1), "y1": round(y1), "x2": round(x2), "y2": round(y2),
+                "conf": round(conf, 3), "areaFraction": round(frac, 4),
+            })
+            max_frac = max(max_frac, frac)
+            max_conf = max(max_conf, conf)
+            if conf >= SIZE_CONF_FLOOR:
+                size_frac = max(size_frac, frac)
+            if conf > best_conf:
+                best_conf = conf
+                best_conf_frac = frac
+
+        is_pothole = len(boxes) > 0
+        # Prefer the largest confident pothole; if none clear the floor, fall back to
+        # the area of the single most-confident detection (never a noisy wide box).
+        sizing_frac = size_frac if size_frac > 0 else best_conf_frac
+        if not is_pothole:
+            size = None
+        elif sizing_frac >= SIZE_LARGE:
+            size = "Large"
+        elif sizing_frac >= SIZE_MEDIUM:
+            size = "Medium"
+        else:
+            size = "Small"
+
+        return {
+            "isPothole": is_pothole,
+            "confidence": round(max_conf, 3),
+            "size": size,
+            "count": len(boxes),
+            "largestAreaFraction": round(max_frac, 4),
+            "sizeAreaFraction": round(sizing_frac, 4),
+            "boxes": boxes,
+            "model": "peterhdd/pothole-detection-yolov8",
+        }
+    except Exception as e:  # noqa: BLE001
+        return {"error": str(e)}
+
+
+def main():
+    if not os.path.exists(MODEL_FILE):
+        emit({"error": "model file missing: " + MODEL_FILE})
+        return
+    try:
+        from ultralytics import YOLO
+    except Exception as e:  # noqa: BLE001
+        emit({"error": "ultralytics not installed: " + str(e)})
+        return
+    try:
+        model = YOLO(MODEL_FILE)
+    except Exception as e:  # noqa: BLE001
+        emit({"error": "model load failed: " + str(e)})
+        return
+
+    emit({"ready": True})
+
+    for line in sys.stdin:
+        path = line.strip()
+        if not path:
+            continue
+        if path == "__quit__":
+            break
+        emit(classify(model, path))
+
+
+if __name__ == "__main__":
+    main()

authority-routing.json

@@ -0,0 +1,13 @@
+{
+  "default": {
+    "authorityName": "Department of Streets — Road Maintenance Division",
+    "authorityEmails": [
+      "road.maintenance@city.example.gov"
+    ],
+    "dispatchEmails": [
+      "field.dispatch@city.example.gov"
+    ]
+  },
+  "districts": {},
+  "zones": {}
+}

backend-api.js

@@ -0,0 +1,293 @@
+'use strict';
+
+(function initPotholeBackend(globalScope) {
+  const API_PREFIX = '/api';
+
+  function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+  }
+
+  function deepMerge(baseValue, incomingValue) {
+    if (!isPlainObject(baseValue) || !isPlainObject(incomingValue)) {
+      return incomingValue === undefined ? baseValue : incomingValue;
+    }
+
+    const result = { ...baseValue };
+    for (const [key, incoming] of Object.entries(incomingValue)) {
+      const existing = result[key];
+      if (Array.isArray(incoming)) {
+        result[key] = incoming.slice();
+        continue;
+      }
+      if (isPlainObject(existing) && isPlainObject(incoming)) {
+        result[key] = deepMerge(existing, incoming);
+        continue;
+      }
+      if (incoming !== undefined) {
+        result[key] = incoming;
+      }
+    }
+    return result;
+  }
+
+  function stripPhotoDataUrl(value) {
+    if (Array.isArray(value)) {
+      return value.map((item) => stripPhotoDataUrl(item));
+    }
+
+    if (!isPlainObject(value)) {
+      return value;
+    }
+
+    const clone = {};
+    for (const [key, child] of Object.entries(value)) {
+      if (key === 'photoDataUrl') continue;
+      clone[key] = stripPhotoDataUrl(child);
+    }
+    return clone;
+  }
+
+  function toTimestamp(value) {
+    const parsed = Date.parse(String(value || ''));
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+
+  function caseFreshness(record) {
+    if (!record || typeof record !== 'object') return 0;
+    const report = record.report || {};
+    return Math.max(
+      toTimestamp(record.updatedAt),
+      toTimestamp(record.statusUpdatedAt),
+      toTimestamp(record.ts),
+      toTimestamp(record.timestamp),
+      toTimestamp(report.workflowLastUpdatedAt),
+      toTimestamp(report.resolvedAt),
+      toTimestamp(report.supervisor?.at),
+      toTimestamp(report.enrichment?.enrichedAt),
+      toTimestamp(report.submittedAt)
+    );
+  }
+
+  function mergeCaseLists(localCases, remoteCases) {
+    const merged = new Map();
+    const allCases = [...(Array.isArray(localCases) ? localCases : []), ...(Array.isArray(remoteCases) ? remoteCases : [])];
+
+    allCases.forEach((record) => {
+      if (!record || !record.caseId) return;
+      const existing = merged.get(record.caseId);
+      if (!existing) {
+        merged.set(record.caseId, record);
+        return;
+      }
+
+      const existingFreshness = caseFreshness(existing);
+      const nextFreshness = caseFreshness(record);
+      const nextPreferred = nextFreshness >= existingFreshness;
+      merged.set(
+        record.caseId,
+        nextPreferred ? deepMerge(existing, record) : deepMerge(record, existing)
+      );
+    });
+
+    return Array.from(merged.values()).sort((a, b) => {
+      const aTs = caseFreshness(a);
+      const bTs = caseFreshness(b);
+      if (aTs !== bTs) return aTs - bTs;
+      return String(a.caseId || '').localeCompare(String(b.caseId || ''));
+    });
+  }
+
+  async function request(path, options = {}) {
+    const response = await fetch(`${API_PREFIX}${path}`, {
+      headers: {
+        'Content-Type': 'application/json',
+        ...(options.headers || {}),
+      },
+      ...options,
+    });
+
+    let payload = null;
+    try {
+      payload = await response.json();
+    } catch {
+      payload = null;
+    }
+
+    if (!response.ok) {
+      const errorMessage = payload?.error || `Request failed with HTTP ${response.status}`;
+      throw new Error(errorMessage);
+    }
+
+    return payload;
+  }
+
+  async function health() {
+    const payload = await request('/health', { method: 'GET' });
+    return payload?.ok === true;
+  }
+
+  async function getCases() {
+    const payload = await request('/cases', { method: 'GET' });
+    return Array.isArray(payload?.cases) ? payload.cases : [];
+  }
+
+  async function getCase(caseId) {
+    if (!caseId) return null;
+    const payload = await request(`/cases/${encodeURIComponent(caseId)}`, { method: 'GET' });
+    return payload?.case || null;
+  }
+
+  async function upsertCase(record) {
+    const payload = await request('/cases/upsert', {
+      method: 'POST',
+      body: JSON.stringify(stripPhotoDataUrl(record || {})),
+    });
+    return payload?.case || null;
+  }
+
+  async function bulkUpsertCases(cases) {
+    const payload = await request('/cases/bulk-upsert', {
+      method: 'POST',
+      body: JSON.stringify({
+        cases: Array.isArray(cases) ? cases.map((record) => stripPhotoDataUrl(record || {})) : [],
+      }),
+    });
+    return Array.isArray(payload?.cases) ? payload.cases : [];
+  }
+
+  async function patchCase(caseId, patch) {
+    if (!caseId) throw new Error('caseId is required.');
+    const payload = await request(`/cases/${encodeURIComponent(caseId)}/patch`, {
+      method: 'POST',
+      body: JSON.stringify(stripPhotoDataUrl(patch || {})),
+    });
+    return payload?.case || null;
+  }
+
+  async function submitSupervisorDecision(caseId, decisionPayload = {}) {
+    if (!caseId) throw new Error('caseId is required.');
+    const payload = await request('/workflow/supervisor-decision', {
+      method: 'POST',
+      body: JSON.stringify(stripPhotoDataUrl({
+        caseId,
+        ...decisionPayload,
+      })),
+    });
+    return payload || null;
+  }
+
+  async function submitCrewCloseout(caseId, closeoutPayload = {}) {
+    if (!caseId) throw new Error('caseId is required.');
+    const payload = await request('/workflow/crew-closeout', {
+      method: 'POST',
+      body: JSON.stringify(stripPhotoDataUrl({
+        caseId,
+        ...closeoutPayload,
+      })),
+    });
+    return payload || null;
+  }
+
+  async function submitDispatchPlan(dispatchPayload = {}) {
+    const payload = await request('/workflow/dispatch-plan', {
+      method: 'POST',
+      body: JSON.stringify(stripPhotoDataUrl(dispatchPayload || {})),
+    });
+    return payload || null;
+  }
+
+  async function resolveCase(caseId, resolvePayload = {}) {
+    if (!caseId) throw new Error('caseId is required.');
+    const payload = await request('/workflow/resolve-case', {
+      method: 'POST',
+      body: JSON.stringify(stripPhotoDataUrl({
+        caseId,
+        ...resolvePayload,
+      })),
+    });
+    return payload || null;
+  }
+
+  async function uploadCaseFile(caseId, fileName, fileBlob, contentType = '') {
+    if (!caseId) throw new Error('caseId is required.');
+    if (!fileName) throw new Error('fileName is required.');
+    if (!(fileBlob instanceof Blob)) {
+      throw new Error('fileBlob must be a Blob or File.');
+    }
+
+    const response = await fetch(
+      `${API_PREFIX}/box/upload-case-file?caseId=${encodeURIComponent(caseId)}&fileName=${encodeURIComponent(fileName)}`,
+      {
+        method: 'POST',
+        headers: contentType ? { 'Content-Type': contentType } : {},
+        body: fileBlob,
+      }
+    );
+
+    let payload = null;
+    try {
+      payload = await response.json();
+    } catch {
+      payload = null;
+    }
+
+    if (!response.ok) {
+      throw new Error(payload?.error || `Request failed with HTTP ${response.status}`);
+    }
+
+    return payload?.upload || null;
+  }
+
+  async function hydrateCasesIntoLocalStorage(storageKey = 'submitted_cases') {
+    if (typeof localStorage === 'undefined') return null;
+
+    let localCases = [];
+    try {
+      localCases = JSON.parse(localStorage.getItem(storageKey) || '[]');
+    } catch {
+      localCases = [];
+    }
+
+    const remoteCases = await getCases();
+    const mergedCases = mergeCaseLists(localCases, remoteCases);
+    localStorage.setItem(storageKey, JSON.stringify(mergedCases));
+
+    const remoteIds = new Set(remoteCases.map((item) => item?.caseId).filter(Boolean));
+    const unsyncedLocal = localCases.filter((item) => item?.caseId && !remoteIds.has(item.caseId));
+    if (unsyncedLocal.length) {
+      bulkUpsertCases(unsyncedLocal).catch((err) => {
+        console.warn('[PotholeBackend] could not sync local-only cases:', err);
+      });
+    }
+
+    return mergedCases;
+  }
+
+  async function syncLocalStorageCases(storageKey = 'submitted_cases') {
+    if (typeof localStorage === 'undefined') return [];
+    try {
+      const cases = JSON.parse(localStorage.getItem(storageKey) || '[]');
+      return bulkUpsertCases(cases);
+    } catch (err) {
+      console.warn('[PotholeBackend] could not read local cases for sync:', err);
+      return [];
+    }
+  }
+
+  globalScope.PotholeBackend = {
+    health,
+    getCases,
+    getCase,
+    upsertCase,
+    bulkUpsertCases,
+    patchCase,
+    submitSupervisorDecision,
+    submitDispatchPlan,
+    submitCrewCloseout,
+    resolveCase,
+    uploadCaseFile,
+    hydrateCasesIntoLocalStorage,
+    syncLocalStorageCases,
+    mergeCaseLists,
+  };
+})(window);

box-build/BOX_APP_CONSOLE.md

@@ -0,0 +1,123 @@
+# Box App — Pothole Operations Console Build Guide
+
+This builds the operational dashboard + review console as a **Box App** (Box's no-code app
+builder over your content + metadata), replacing the custom [ops-review.html](../ops-review.html).
+
+> **Accuracy note:** the Box Apps no-code builder's exact control names evolve. This guide is
+> correct at the structure/concept level (data source → views → fields → actions → roles).
+> Confirm the equivalent control as you build, and tell me what you see if a step doesn't match —
+> I'll adjust.
+
+> **Hard dependency:** the app reads/writes the `potholeCase` metadata template
+> ([metadata-template.json](metadata-template.json)). Build that template first, and have at
+> least a few enriched cases in `Pothole Operations/Cases/` so the views show real data.
+
+---
+
+## App: "Pothole Operations Console"
+
+**Data source:** the `potholeCase` metadata template, scoped to the
+`Pothole Operations/Cases/` folder tree. Each case folder = one record; the case photo +
+generated PDFs are the folder's files.
+
+---
+
+### View 1 — Operations Queue (default landing)
+
+A filterable table of all cases.
+
+- **Columns:** `caseId`, `status`, `severityLevel`, `ward`, `address`, `duplicateStatus`,
+  `submittedAt`, `assignedCrew`.
+- **Default sort:** `severityScore` descending (Critical at top).
+- **Saved filters / tabs:**
+  - *Needs Review* → `status = Under Review`
+  - *Critical* → `severityLevel = Critical`
+  - *Assigned* → `status = Assigned`
+  - *Resolved* → `status = Resolved`
+- **Color rules:** Critical = red, High = orange, Medium = amber, Low = grey
+  (match the colors already in your data's `enrichment.severityColor`).
+
+### View 2 — Case Detail
+
+Opens when a row is clicked.
+
+- **Header:** `caseId` + `status` badge.
+- **Photo:** preview the case photo from the folder.
+- **AI summary panel:** the Box AI-generated case summary (set up in AI Studio) +
+  `aiReviewStatus`, `potholeSize`.
+- **Severity breakdown:** `severityScore`, `severityLevel`, `weatherRisk`
+  (the prior/traffic/damage/weather detail lives in the backend `enrichment.severityBreakdown`
+  — surface it via the AI summary or an embedded note).
+- **Location:** `address`, `ward`, `district`, `maintenanceZone`, `latitude`/`longitude`
+  (link out to a map).
+- **Duplicate panel:** `duplicateStatus`, `duplicateCount`, `linkedCaseIds`.
+- **Generated docs:** list the work order PDF + audit report from the folder.
+
+### View 3 — Dashboard (management)
+
+Charts over the same data source:
+
+- Cases by `status` (funnel: Submitted → Under Review → Assigned → In Progress → Resolved).
+- Cases by `ward` (bar).
+- `severityLevel` distribution (donut).
+- Open cases older than N days (SLA watch).
+
+### View 4 (optional) — Citizen Status (read-only, externally shareable)
+
+- Single-record lookup by `caseId`.
+- Show **only**: `status`, `submittedAt`, `ward`, `resolvedAt`. Hide reporter contact,
+  internal notes, severity internals.
+
+---
+
+## Actions (buttons that drive the workflow)
+
+Wire these on the Case Detail view. Each either writes metadata (which a Relay flow reacts to)
+or calls your backend:
+
+| Button            | What it does                                                                 |
+|-------------------|------------------------------------------------------------------------------|
+| **Approve**       | Set `status = Assigned`, `supervisor = {current user}` → Flow 2/3 fire.       |
+| **Reject**        | Set `status = Rejected` (prompt for reason).                                  |
+| **Adjust severity** | Edit `severityLevel` before approving.                                      |
+| **Generate work order** | Trigger Box Doc Gen (or it auto-fires from the status change in Flow 3).|
+| **Open in city system** | (Optional) HTTPS call to the external work-order system.               |
+
+> If the Box App builder in your tenant can't call outgoing webhooks directly, do it the
+> metadata-driven way: the button just sets a metadata field, and **Box Automate (Relay)**
+> watches that field and performs the action. This is the more robust pattern anyway.
+
+---
+
+## Roles & permissions
+
+| Role             | Sees / can do                                                        |
+|------------------|----------------------------------------------------------------------|
+| Ops reviewer     | All cases; Approve/Reject/Adjust.                                     |
+| Ward engineer    | Cases for their `ward`; Approve/Reject (Relay assigns the approval).  |
+| Crew             | Assigned cases only; closeout via the **Box Form**, not this app.    |
+| Management        | Dashboard view; read-only.                                          |
+| Citizen (public) | View 4 only, via a shared link.                                      |
+
+---
+
+## Build order
+
+1. Confirm `potholeCase` template exists and a few enriched cases are present.
+2. Create the app → point its data source at `Cases/` + the template.
+3. Build View 1 (Queue) → verify real cases appear.
+4. Add View 2 (Detail) + the Approve/Reject buttons → test one approval end-to-end with
+   [BOX_AUTOMATE_WORKFLOW.md](BOX_AUTOMATE_WORKFLOW.md) Flow 2 watching the field.
+5. Add View 3 (Dashboard) and View 4 (Citizen) last.
+
+---
+
+## How this maps to the old custom app
+
+| Old custom page                     | New Box-native home              |
+|-------------------------------------|----------------------------------|
+| [ops-review.html](../ops-review.html) | Box App Views 1–3 + actions    |
+| [deploy-crew.html](../deploy-crew.html) | Box App action + Relay Flow 3  |
+| [crew-closeout.html](../crew-closeout.html) | Box Form + Box Sign (Flow 4) |
+| [track.html](../track.html)         | Box App View 4 (citizen)         |
+| [index.html](../index.html) intake  | Box Form intake (AI dashcam stays as optional smart client) |

box-build/BOX_APP_DASHBOARD.md

@@ -0,0 +1,69 @@
+# PotholeIQ — Box App Dashboard Build (complete)
+
+Mirrors the ops-review console: hero metrics → overview charts → case lists → case
+detail with severity breakdown + photo. All blocks read the `Pothole Case`
+(`enterprise/potholeCase`) metadata template.
+
+**Block types available:** View (filtered metadata list), Chart, Item List, File or Folder, Form, App, AutoFiler, Shortcut.
+**A "View" block = one saved Box metadata view** (its own columns/filter/sort, edited in the Box metadata view editor).
+
+> ⚠️ Filters must use EXACT enum values:
+> `status`: submitted · under review · assigned · `In progress` · resolved · rejected
+> `severityLevel`: low · medium · high · critical
+> `duplicateStatus`: new · `duplicate ` *(trailing space)* · pending
+
+---
+
+## PAGE 1 — "Operations Overview"  (the landing page)
+
+### Section A — KPI row  (Section type: **Grid**)
+Four **Chart** blocks. Use chart type **Number/Metric** if available; else a small Donut.
+| Block | Source | Measure | Filter |
+|---|---|---|---|
+| Cases In Queue | Pothole Case | Count | `status` = under review |
+| Needs Attention | Pothole Case | Count | `status` ≠ resolved AND ≠ rejected |
+| Priority Queue | Pothole Case | Count | `severityLevel` = critical OR high |
+| Resolved | Pothole Case | Count | `status` = resolved |
+
+### Section B — distribution  (Grid, 2 columns)
+| Block | Type | Dimension (group by) | Measure |
+|---|---|---|---|
+| Cases by Severity | Donut | `severityLevel` | Count |
+| Cases by Ward | Column | `ward` | Count |
+
+### Section C — the breakdown  (Grid, 2 columns)
+| Block | Type | Detail |
+|---|---|---|
+| **What Drives Severity** | Bar (grouped) | Measures = Average of `priorNoticeScore`, `trafficScore`, `damageScore`, `weatherScore`. *(If only one measure is allowed, make 4 small bar charts, one per factor avg.)* |
+| Cases by Status | Column | group by `status`, Count (the pipeline) |
+
+---
+
+## PAGE 2 — "Case Queue"  (the working lists)
+One **View** block per saved view (create each, name it, pick Pothole Case, then set columns/filter/sort in the metadata view editor):
+
+| View block | Filter | Sort | Columns |
+|---|---|---|---|
+| **All Cases** | none | submittedAt ↓ | caseId · status · severityLevel · severityScore0100 · ward · address · submittedAt |
+| **Triage Queue** | status = under review | severityScore0100 ↓ | caseId · severityScore0100 · severityLevel · ward · address · priorNoticeScore · trafficScore · damageScore · weatherScore |
+| **Duplicates** | duplicateStatus = `duplicate ` | — | caseId · linkedCaseIds · duplicateCount · severityScore0100 · ward |
+| **In Progress** | status = assigned / In progress | — | caseId · assignedCrew · workOrderId · severityLevel · ward |
+| **Resolved** | status = resolved | resolvedAt ↓ | caseId · resolvedAt · assignedCrew · severityLevel · ward |
+
+---
+
+## PAGE 3 — "Case Detail & Evidence"
+- **File or Folder block** → point at the `Potholes/` tree. Opening a case folder previews the
+  **initial pothole photo** + work order / closeout / audit docs inline.
+- **The severity breakdown panel is native:** open any case folder → Box's **metadata sidebar**
+  shows all `Pothole Case` fields, including the 4 breakdown **Scores + Details** and the total.
+  No extra block needed — that's the per-case breakdown.
+
+Breakdown reads as: Prior Notice _/30 · Traffic _/25 · Damage _/25 · Weather _/10 → Total /100 → Level.
+
+---
+
+## Notes
+- **No email from the App** — any dispatch/notify routes through Relay or the backend.
+- **Views/charts are empty until cases carry `potholeCase` metadata** — backend seeds that.
+- Build order: Page 1 charts → Page 2 views → Page 3 evidence. Then Save & Preview.

box-build/BOX_AUTOMATE_WORKFLOW.md

@@ -0,0 +1,145 @@
+# Box Automate (Relay) — Pothole Workflow Build Guide
+
+This guide builds the end-to-end pothole workflow as **Box Relay** flows (the no-code
+workflow tool your setup calls "Box Automate"). It is written click-by-click but exact
+button labels vary slightly by Box release — confirm the equivalent control in your tenant.
+
+> **Division of labor:** Relay flows are built in the Box web console (Relay app). The code
+> side (metadata template, enrichment Skill, Doc Gen template, backend callback) is in this
+> repo. Each flow below names exactly which code asset it touches.
+
+---
+
+## Prerequisites (do these first, in order)
+
+1. **CCG connection live.** The service account must be able to read/write the case folders.
+   (Still pending your Box **Enterprise ID** so we can finish this in `data/config.json`.)
+2. **Metadata template created.** Create `potholeCase` from
+   [metadata-template.json](metadata-template.json) — Admin Console → **Content** →
+   **Metadata** → New Template (or POST it to `/2.0/metadata_templates/schema`).
+3. **Folder structure exists:**
+   - `Pothole Operations/Incoming Reports/`  ← intake drop folder (your current intake
+     folder id `386202381022`)
+   - `Pothole Operations/Cases/`             ← case folders get created here as `Ward-XYZ/Case-<id>/`
+   - `Pothole Operations/Reports/`           ← Doc Gen output + audit reports
+4. **Backend reachable from Box cloud.** Relay's *HTTPS Request* action calls your backend.
+   Expose it with a tunnel (`ngrok http 3030` or `cloudflared`) and note the public URL,
+   e.g. `https://abc123.ngrok.io`. Your backend already exposes the callback endpoint
+   `POST /api/box/automate-update` (see [BACKEND_SETUP.md](../BACKEND_SETUP.md)).
+
+---
+
+## Flow 1 — Intake & Enrichment
+
+**Goal:** when a new report lands, enrich it (severity, ward, duplicate, weather) and stamp
+metadata. The hard math (GIS ward mapping, 50–100 m duplicate radius, deterministic severity,
+weather) is NOT something Box AI can do — it runs in your enrichment endpoint, which Relay calls.
+
+- **Trigger:** *When a file is uploaded* to `Pothole Operations/Incoming Reports`
+  (fire on the `*.json` sidecar so you enrich once per case, not once per photo).
+- **Action 1 — HTTPS Request (enrichment):**
+  - Method: `POST`
+  - URL: `https://<your-public-url>/api/box/enrich`  *(endpoint I will add to the backend)*
+  - Body (JSON): `{ "caseId": "{file name without extension}", "sidecarFileId": "{file id}" }`
+  - The endpoint computes severityScore/Level, ward/district/zone, duplicateStatus +
+    linkedCaseIds, weatherRisk and **writes them straight onto the `potholeCase` metadata**.
+- **Action 2 — Apply Metadata** (`potholeCase`): set `status = Under Review` if not already set.
+- **Action 3 — Create/Move:** move the photo + sidecar into `Cases/Ward-{ward}/Case-{caseId}/`.
+  *(Relay folder-from-metadata naming is limited; the enrichment endpoint can create the case
+  folder via API instead — your [box-folders.js](../box-folders.js) already does this.)*
+
+> **Alternative (more native):** instead of the Relay HTTPS Request, register the enrichment
+> endpoint as a **custom Box Skill** on the Incoming folder. Then enrichment fires
+> automatically on upload and writes metadata cards — no Relay step needed for Flow 1.
+
+---
+
+## Flow 2 — Review & Approval Routing
+
+**Goal:** notify the right ward engineer and capture approve / reject / adjust.
+
+- **Trigger:** *When metadata field updates* — `potholeCase.status` becomes `Under Review`.
+- **Condition (severity routing):**
+  - If `severityLevel = Critical` → **immediate** path.
+  - Else → standard path (optionally a scheduled digest flow).
+- **Action — Assign Approval** to the ward engineer:
+  - Route by `ward` (use a Relay condition per ward → assignee email, or a single group).
+  - Approver opens the case in Box web/mobile, reviews the photo + metadata + AI summary,
+    and can edit `severityLevel` (that's just editing a metadata field) before deciding.
+- **On Approve:**
+  - Set `status = Assigned`, `supervisor = {approver}`.
+  - HTTPS Request → `POST /api/box/automate-update` with
+    `{ "caseId": "...", "workflowStatus": "Assigned", "workflowStage": "crew_dispatch" }`
+    so your backend DB stays in sync.
+- **On Reject:** set `status = Rejected`; HTTPS Request with `workflowStatus: "Rejected"`.
+
+---
+
+## Flow 3 — Work Order Generation (Box Doc Gen)
+
+**Goal:** on approval, produce the work order / job sheet PDF into the case folder.
+
+- **Trigger:** `potholeCase.status` becomes `Assigned`.
+- **Action — Generate Document (Box Doc Gen):**
+  - Template: the Doc Gen template I'll create from [workorder_template.html](../workorder_template.html).
+  - Data source: the `potholeCase` metadata on the case folder (merge tags map 1:1 to the
+    field keys — see `04` mapping doc once created).
+  - Output: `Cases/Ward-{ward}/Case-{caseId}/Work-Order-{workOrderId}.pdf`.
+- **Action — Apply Metadata:** write `workOrderId`.
+- *(Optional)* HTTPS Request to push the work order into the city system of record.
+
+---
+
+## Flow 4 — Crew Closeout, Sign & Audit
+
+**Goal:** field crew submits proof, signs, case is archived audit-ready.
+
+- **Trigger:** a **Box Form** submission (crew closeout — built separately) lands a closeout
+  record / after-photo in the case folder, OR `status` becomes `In Progress` then closeout.
+- **Action — Request Signature (Box Sign):** send the completion certificate for the crew
+  lead's e-signature (replaces the current typed-name field).
+- **On signed:** set `status = Resolved`, `resolvedAt = {now}`; HTTPS Request →
+  `/api/box/automate-update` with `workflowStatus: "Resolved"` (your backend then auto-builds
+  the before/after + audit report — see `generateAndUploadAuditReport` in [server.js](../server.js)).
+- **Action — Apply Governance:** apply a **retention policy / legal hold** to the case folder
+  (Box Governance) so the record is audit-ready with full version history.
+
+---
+
+## Field reference (Relay conditions & HTTPS payloads)
+
+These are the `potholeCase` keys Relay reads/writes, and the matching `report.*` keys your
+backend already uses (so the callback payload to `/api/box/automate-update` lines up):
+
+| Metadata key (Box)   | Backend `report.*` key        | Used in flow |
+|----------------------|-------------------------------|--------------|
+| `status`             | `workflowStatus`              | all          |
+| `severityLevel`      | `enrichment.severityLevel`    | 1, 2         |
+| `severityScore`      | `enrichment.severityScore`    | 1, 2         |
+| `ward` / `district`  | `ward` / `district`           | 1, 2, 3      |
+| `duplicateStatus`    | `enrichment.duplicate.*`      | 1            |
+| `weatherRisk`        | `enrichment.weather.riskLevel`| 1            |
+| `assignedCrew`       | `dispatchPlan.crewName`       | 3, 4         |
+| `workOrderId`        | `workOrderId`                 | 3            |
+| `resolvedAt`         | `resolvedAt`                  | 4            |
+
+**Backend callback contract** (already implemented): `POST /api/box/automate-update`
+```json
+{
+  "caseId": "POT-20260604-Q2H0GR",
+  "workflowStage": "crew_dispatch",
+  "workflowStatus": "Assigned",
+  "assignedTo": "ward-12-crew@city.gov"
+}
+```
+If you set `BOX_AUTOMATE_SECRET` on the server, add the same value as an
+`X-Box-Automate-Secret` header on every Relay HTTPS Request action.
+
+---
+
+## What I still owe you (code side)
+
+- [ ] `POST /api/box/enrich` endpoint (wraps existing [enrichment.js](../enrichment.js) +
+      [gis.js](../gis.js)) that writes `potholeCase` metadata directly — for Flow 1.
+- [ ] Box Doc Gen template + field-mapping doc — for Flow 3.
+- [ ] (Optional) custom Box Skill manifest if you prefer the auto-on-upload enrichment path.

box-build/REVISED_WORKFLOW.md

@@ -0,0 +1,149 @@
+# Pothole Operations — Revised Workflow (Recommended)
+
+This is the recommended end-to-end design after reviewing the codebase, the Box Relay
+build, and the platform constraints. It is optimized to be **robust** (works even if Box AI
+is disabled), **demoable now** (no tunnel, no external city system required), and **honest**
+(every step does what it claims).
+
+---
+
+## Design decisions (the "why")
+
+1. **The backend computes enrichment AND writes Box metadata directly at upload.**
+   Severity, GPS→ward, duplicate, and weather are computed in our service the moment a report
+   is submitted, written into the JSON, and **also applied as Box metadata via the Box API
+   during upload.** This is the single most important change.
+   - ✅ The workflow does **not depend on Box AI / Box Extract being enabled** (which the Relay
+     screenshots showed as "no longer enabled"). If Extract is on, it's a confirming bonus.
+   - ✅ **No tunnel required** — the backend *pushes* complete data to Box; Box never calls back
+     just to enrich.
+   - ✅ Relay, the Box App, Doc Gen, and Sign all run natively on clean metadata.
+
+2. **Metadata is the contract.** Box's no-code tools branch and route on **metadata**, never on
+   raw file contents. The `potholeCase` template ([metadata-template.json](metadata-template.json))
+   is the shared schema everything reads.
+
+3. **Source of truth = backend; Box = content + metadata + workflow + audit.** The backend owns
+   live state; Box owns the authoritative files, the metadata mirror that drives Relay/App, and
+   the audit record. Every Box-side action (approval, closeout) calls back to the backend so the
+   two never drift.
+
+4. **Work order is generated in Box (Doc Gen), not an external city system.** Removes the only
+   hard external dependency. "Push to city system via REST" stays as an *optional future* step.
+
+5. **Citizens track status in the portal, never in Box.** No Box login for the public.
+
+6. **Six statuses only:** `Submitted` · `Under Review` · `Assigned` · `In Progress` · `Resolved` · `Rejected`.
+
+---
+
+## End-to-end flow
+
+```
+CITIZEN PORTAL (web/mobile)
+   │  photo(s) + location + reporter info + on-device AI size detection
+   ▼
+BACKEND  ── enrich at submission ───────────────────────────────┐
+   │   • GPS → ward / district / zone   (point-in-polygon GeoJSON)
+   │   • severity score + level         (weighted formula)
+   │   • duplicate check 50–100 m       (radius across open cases)
+   │   • weather risk                   (OpenWeather)
+   │   • assemble COMPLETE JSON
+   ▼
+BOX  ── backend uploads photo + complete JSON + applies metadata ┘
+   │   Incoming Reports/  (+ potholeCase metadata set on the file)
+   ▼
+BOX RELAY  (triggers on upload; runs on metadata)
+   │
+   ├── duplicate? ──► link to existing case · boost severity · notify owner · STOP
+   │
+   └── new ──► create  Cases/Ward-{ward}/Case-{caseId}/ · status = Under Review
+                 │
+                 ▼
+        REVIEW  ── notify ward engineer (folder link · photo · AI summary · nearby cases)
+                 │   engineer approves / adjusts severity / rejects  (Box web or mobile)
+                 │   → callback to backend (keep state in sync)
+                 ▼
+        APPROVED ── backend stamps workOrderId · BOX DOC GEN → Work Order PDF
+                 │   status = Assigned
+                 ▼
+        FIELD  ── crew gets job sheet + mobile BOX FORM
+                 │   repair method · materials · labor hours · after-photo(s)
+                 │   status = In Progress
+                 ▼
+        SIGN-OFF ── BOX SIGN (crew lead signature)
+                 │   status = Resolved · notify supervisor + risk mgmt
+                 │   backend generates before/after + audit report → case folder
+                 ▼
+        AUDIT  ── Box Governance (retention / legal hold) + native version history
+                 │
+CITIZEN PORTAL ◄─ status synced from backend (track.html) — no Box login
+```
+
+---
+
+## Phase table
+
+| # | Phase | Owner | Key actions | Output | Status |
+|---|-------|-------|-------------|--------|--------|
+| 1 | Intake | Portal | Photo, location (EXIF/device/manual), reporter, on-device AI size | Report posted | `Submitted` |
+| 2 | Enrich | **Backend** | ward, severity, duplicate, weather → complete JSON | Complete JSON | `Submitted` |
+| 3 | Store | **Backend → Box** | Upload photo + JSON; **apply `potholeCase` metadata** | Files + metadata in Box | `Submitted` |
+| 4 | Route | Box Relay | Conditional Split on `duplicateStatus`; create case folder | Case folder / dup link | `Under Review` |
+| 5 | Review | Ward engineer (Box) | Notify + approve/adjust/reject; callback to backend | Decision | `Under Review` → `Rejected`/approved |
+| 6 | Work order | Box Doc Gen | Stamp `workOrderId`; generate Job Sheet PDF | PDF in folder | `Assigned` |
+| 7 | Field | Crew (Box Form) | Method, materials, labor, after-photo | Closeout record | `In Progress` |
+| 8 | Sign-off | Box Sign | Signature; notify supervisor/risk; audit report | Signed cert + reports | `Resolved` |
+| 9 | Transparency | Portal | Citizen looks up case | Status view | (read) |
+| 10 | Audit | Box Governance | Retention, version history, access control | Audit-ready folder | (retained) |
+
+---
+
+## What runs where
+
+**Backend (our service)** — the things Box can't do:
+- GPS→ward (geometry), severity (scoring), duplicate (geo-radius), weather (external API)
+- Assemble complete JSON, upload to Box, **apply Box metadata**
+- Generate work order PDF source + before/after + audit reports (already implemented)
+- Hold authoritative live state; expose status to the citizen portal
+
+**Box (native, no custom code)** — configured in the console:
+- Relay: trigger, duplicate split, folder creation, approval routing, notifications
+- Doc Gen: Work Order / Job Sheet PDF
+- Box Form: crew closeout · Box Sign: signature
+- Governance + version history: audit
+- (Optional) Box App: ops console + dashboards · Box AI: image summary if/when enabled
+
+---
+
+## Why this is the advisable version
+
+- **Resilient to the disabled-AI problem** — the backend writes metadata directly, so Relay
+  works whether or not Box Extract/Agent is enabled.
+- **No tunnel, no external system** — fully demoable as "files + metadata land in Box and Box
+  runs the workflow."
+- **No drift** — single source of truth + callback on every Box action.
+- **Honest on the call** — Box genuinely runs content, workflow, Doc Gen, Sign, and audit; our
+  service genuinely runs the geospatial scoring it feeds Box.
+
+---
+
+## Build checklist
+
+**Done**
+- [x] `potholeCase` metadata schema — [metadata-template.json](metadata-template.json)
+- [x] GIS endpoint no longer 500s; serves local ward GeoJSON if present — [server.js](../server.js)
+- [x] Credible authority routing defaults — [authority-routing.json](../authority-routing.json)
+
+**Next (backend — I can build)**
+- [ ] Enrich-at-submission: run ward + severity + duplicate + weather before the sidecar uploads
+- [ ] Apply `potholeCase` Box metadata during upload (uses existing metadataScope/templateKey config)
+- [ ] Work-order/approval endpoint for the Doc Gen + status sync
+- [ ] Box Doc Gen template + field map from [workorder_template.html](../workorder_template.html)
+
+**Next (Box console — your team)**
+- [ ] Connect CCG (needs Enterprise ID + share intake folder with service account)
+- [ ] Build the Relay flow per [BOX_AUTOMATE_WORKFLOW.md](BOX_AUTOMATE_WORKFLOW.md) (metadata-driven)
+- [ ] Doc Gen template, Box Form, Box Sign, Governance policy
+- [ ] (Optional) Box App console per [BOX_APP_CONSOLE.md](BOX_APP_CONSOLE.md)
+- [ ] (Optional) drop real ward GeoJSON at `data/ward-boundaries.geojson`

box-build/WORKFLOW_ONE_BUILD.md

@@ -0,0 +1,86 @@
+# Workflow One — Intake → Dispatch (Relay build walkthrough)
+
+Build this in the Box Relay canvas, top to bottom. After each node, click **+** and pick the
+palette item named in **bold**. Workflow name: **Workflow One**.
+
+**Prereqs:** `Pothole Case` metadata template exists · folders `Incoming Detections`,
+`Cases/`, `Cases/Duplicates/`, `Cases/Rejected/` exist.
+
+---
+
+## TRIGGER — Flow Triggers → File Uploaded
+- **Folder:** `Incoming Detections`
+- **Filter (recommended):** file name *contains* `_metadata.json`
+  → fires once per case on the JSON sidecar, not the photo.
+
+## 1. AI Agents → Extract Agent
+- **Input file:** the triggering file.
+- **Map to `Pothole Case` metadata:** `Case ID`, `Latitude`, `Longitude`, `Address`, `Ward`,
+  `District`, `Pothole Size`, `Severity Score`, `Severity Level`, `Duplicate Status`,
+  `Weather Risk`, `AI Review Status`.
+
+## 2. AI Agents → Box Agent
+- **Instruction:** "Read the case file and metadata; write a short plain-language case summary
+  and confirm the severity level."
+- **Output to metadata:** `AI Summary`.
+
+## 3. Branching → Conditional Split  *(name it "Duplicate?")*
+- **Condition:** `Pothole Case` › `Duplicate Status` **is** `duplicate`
+- Creates two paths: **Duplicate** (true) and **New** (Else).
+
+---
+
+### ▸ DUPLICATE path
+**4a. Outcomes → File Action → Move** → `Cases/Duplicates/`
+**5a. Outcomes → Add Metadata** → `Status = Under Review`
+→ *path ends (no new work order; it's linked via `Linked Case IDs`).*
+
+---
+
+### ▸ NEW path
+**4b. Outcomes → Folder Action → Create Folder**
+- **Name (use variables):** `Case-{Case ID}`
+- **Parent path:** `Cases / Ward-{Ward}`
+
+**5b. Outcomes → File Action → Move** → into the new `Case-{Case ID}` folder.
+
+**6. Outcomes → Add Metadata** → `Status = Under Review`.
+
+**7. Outcomes → Send Notification**
+- **To:** ward engineer (route by `Ward`, or a fixed group for the demo).
+- **Message:** include `{AI Summary}`, `{Severity Level}`, and the case folder link.
+
+**8. Outcomes → Task Action**  *(approval)*
+- **Title:** `Pothole Repair Work Order – {Case ID}`
+- **Assignee:** ward engineer
+- **Instructions:** "Approve, adjust severity, or reject."
+
+**9. Branching → Conditional Split** on the task result → **Approved** / **Rejected**
+
+#### ▹ APPROVED
+**10. Outcomes → HTTPS Request**
+- **Method:** POST
+- **URL:** `https://<backend-url>/api/box/workorder`  *(endpoint I'll provide)*
+- **Body:** `{ "caseId": "{Case ID}" }`
+- Backend stamps `Work Order ID` + generates the **Box Doc Gen** Job Sheet PDF into the folder.
+
+**11. Outcomes → Add Metadata** → `Status = Assigned`, `Work Order ID = {returned id}`.
+→ **End of Workflow One.**
+
+#### ▹ REJECTED
+**10r. Outcomes → Add Metadata** → `Status = Rejected`
+**11r. Outcomes → File Action → Move** → `Cases/Rejected/`
+**12r. Outcomes → Send Notification** → reporter (if contact on file).
+
+---
+
+## Notes
+- **Doc Gen is not a Relay action** in your palette — that's why step 10 is an **HTTPS Request**
+  to the backend (which runs Doc Gen). It needs the backend reachable from Box (a tunnel for the
+  demo). If the backend isn't up yet, **stop Workflow One at step 11 (`Status = Assigned`)** and
+  generate the work order later — the flow is still complete and demoable.
+- **Guard against loops:** the Add Metadata steps write `Status`; make sure no trigger in this
+  flow is "metadata updated," or it can re-fire. This flow triggers on *file upload* only, so
+  you're safe.
+- **Crew closeout, Box Sign, resolve** all live in **Workflow Two** (triggered by the Box Form),
+  not here.

box-build/WORKFLOW_TWO_BUILD.md

@@ -0,0 +1,65 @@
+# Workflow Two — Crew Reporting & Closeout
+
+Triggered by the crew **Box Form** submission. Build the Form first (it's the trigger), then the flow.
+
+**Prereqs:** Box Form "Crew Closeout" built · folder `Cases/Closeouts/` (where the form saves) ·
+Box Sign enabled · Box Governance retention policy on `Cases/` (set once, separately).
+
+---
+
+## Step A — Box Form: "Crew Closeout" (build this first)
+
+Fields:
+| Field | Type | Notes |
+|---|---|---|
+| Case ID | Text (required) | crew enters/scans the case it belongs to |
+| Repair Method | Dropdown | Cold patch / Hot mix / Full-depth |
+| Materials Used | Text | |
+| Labor Hours | Number | |
+| After Photo | File upload (required) | the "after" proof |
+| Crew Name | Text | |
+| Notes | Long text | optional |
+
+- **Save destination:** `Cases/Closeouts/` (a single intake folder is simplest).
+- If the Form can **map answers to metadata**, map them to the matching Pothole Case fields.
+
+---
+
+## Step B — Workflow Two (Relay)
+
+**TRIGGER:** Box Form submitted — "Crew Closeout"
+*(If there's no native Form trigger, use **File Uploaded → `Cases/Closeouts/`** instead.)*
+
+**1. AI Agents → Extract Agent** *(only if the Form didn't write metadata directly)*
+- Pull form values → Pothole Case metadata: `repairMethod`, `materialsUsed`, `laborHours`, `crewName`, `afterPhotoFileId`.
+
+**2. Outcomes → Add Metadata**
+- `Status = In Progress` + the closeout fields above.
+
+**3. Outcomes → Request Signature (Box Sign)**
+- Sign the **completion certificate / closeout report**.
+- ⚠️ Box Sign needs an actual file to sign. The nice version is the **Doc Gen closeout report** (backend-generated). Until that's wired, point Sign at the **work order PDF** or a simple completion doc.
+
+**4. Branch on the signature outcome → Completed / Declined / Expired / Cancelled**
+
+### ▹ Completed
+- **Add Metadata** → `Status = Resolved`, `resolvedAt = {now}`
+- **HTTPS Request → backend** → generate **Closeout Report (Doc Gen)** + audit report into the case folder *(backend step — deferred until backend is up; for now skip and just set Resolved)*
+- **Send Notification** → supervisor + risk management (Box users)
+- *(Optional)* **File Action → Apply Classification** → "Closed – Retain" (Box Shield/Governance)
+
+### ▹ Declined
+- **Send Notification** → re-route / fix and resubmit.
+
+### ▹ Expired
+- **Send Notification** → remind the signer.
+
+### ▹ Cancelled
+- **Add Metadata** → hold / note.
+
+---
+
+## Notes
+- **Box Governance** (retention / legal hold) is a **policy set once on the `Cases/` folder** — it auto-applies, it's not a Relay node.
+- **Citizen** sees `Resolved` via the **portal** (no Box notification to them).
+- **Two pieces wait on the backend:** the Doc Gen **closeout report** fill, and (ideally) the document Box Sign signs. Everything else is native Relay and buildable now.

box-build/add-breakdown-fields.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Adds the 4 severity sub-score floats + 4 detail strings to the potholeCase
+# metadata template so the breakdown can be shown in the Box App dashboard.
+# Additive only — does not touch existing fields or Relay flows.
+# Usage:  bash add-breakdown-fields.sh <FRESH_DEV_TOKEN>
+set -euo pipefail
+TOKEN="${1:?Pass a fresh Box dev token as the first argument}"
+
+curl -s -w "\nHTTP %{http_code}\n" \
+  -X PUT "https://api.box.com/2.0/metadata_templates/enterprise/potholeCase/schema" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json-patch+json" \
+  -d '[
+ {"op":"addField","data":{"type":"float","key":"priorNoticeScore","displayName":"Prior Notice Score (0-30)"}},
+ {"op":"addField","data":{"type":"float","key":"trafficScore","displayName":"Traffic Score (0-25)"}},
+ {"op":"addField","data":{"type":"float","key":"damageScore","displayName":"Damage Score (0-25)"}},
+ {"op":"addField","data":{"type":"float","key":"weatherScore","displayName":"Weather Score (0-10)"}},
+ {"op":"addField","data":{"type":"string","key":"priorNoticeDetail","displayName":"Prior Notice Detail"}},
+ {"op":"addField","data":{"type":"string","key":"trafficDetail","displayName":"Traffic Detail"}},
+ {"op":"addField","data":{"type":"string","key":"damageDetail","displayName":"Damage Detail"}},
+ {"op":"addField","data":{"type":"string","key":"weatherDetail","displayName":"Weather Detail"}}
+]'

box-build/metadata-template.json

@@ -0,0 +1,93 @@
+{
+  "_comment": "Box metadata template for a pothole case. This is the single shared schema that Box Automate (Relay) conditions, Box Doc Gen merge fields, the Box App console, and the enrichment Skill all read and write. Create it once via the Box Admin Console (Content > Metadata) or POST this payload to https://api.box.com/2.0/metadata_templates/schema. Field keys match the report.* fields the backend already produces in data/cases.json.",
+  "scope": "enterprise",
+  "templateKey": "potholeCase",
+  "displayName": "Pothole Case",
+  "hidden": false,
+  "copyInstanceOnItemCopy": true,
+  "fields": [
+    { "type": "string", "key": "caseId", "displayName": "Case ID" },
+    {
+      "type": "enum",
+      "key": "status",
+      "displayName": "Status",
+      "options": [
+        { "key": "Submitted" },
+        { "key": "Under Review" },
+        { "key": "Assigned" },
+        { "key": "In Progress" },
+        { "key": "Resolved" },
+        { "key": "Rejected" }
+      ]
+    },
+    { "type": "date", "key": "submittedAt", "displayName": "Submitted At" },
+    { "type": "string", "key": "address", "displayName": "Address" },
+    { "type": "string", "key": "ward", "displayName": "Ward" },
+    { "type": "string", "key": "district", "displayName": "District" },
+    { "type": "string", "key": "maintenanceZone", "displayName": "Maintenance Zone" },
+    { "type": "float", "key": "latitude", "displayName": "Latitude" },
+    { "type": "float", "key": "longitude", "displayName": "Longitude" },
+    { "type": "float", "key": "severityScore", "displayName": "Severity Score (0-100)" },
+    {
+      "type": "enum",
+      "key": "severityLevel",
+      "displayName": "Severity Level",
+      "options": [
+        { "key": "Low" },
+        { "key": "Medium" },
+        { "key": "High" },
+        { "key": "Critical" }
+      ]
+    },
+    {
+      "type": "enum",
+      "key": "potholeSize",
+      "displayName": "Pothole Size",
+      "options": [
+        { "key": "Small" },
+        { "key": "Medium" },
+        { "key": "Large" }
+      ]
+    },
+    {
+      "type": "enum",
+      "key": "duplicateStatus",
+      "displayName": "Duplicate Status",
+      "options": [
+        { "key": "new" },
+        { "key": "duplicate" },
+        { "key": "pending" }
+      ]
+    },
+    { "type": "float", "key": "duplicateCount", "displayName": "Duplicate Count" },
+    { "type": "string", "key": "linkedCaseIds", "displayName": "Linked Case IDs" },
+    {
+      "type": "enum",
+      "key": "weatherRisk",
+      "displayName": "Weather Risk",
+      "options": [
+        { "key": "low" },
+        { "key": "medium" },
+        { "key": "high" }
+      ]
+    },
+    {
+      "type": "enum",
+      "key": "aiReviewStatus",
+      "displayName": "AI Review Status",
+      "options": [
+        { "key": "auto_confirmed" },
+        { "key": "manual_review" },
+        { "key": "manual_confirmed" },
+        { "key": "manual_rejected" }
+      ]
+    },
+    { "type": "string", "key": "aiSummary", "displayName": "AI Summary" },
+    { "type": "string", "key": "assignedCrew", "displayName": "Assigned Crew" },
+    { "type": "string", "key": "workOrderId", "displayName": "Work Order ID" },
+    { "type": "string", "key": "supervisor", "displayName": "Supervisor / Ward Engineer" },
+    { "type": "date", "key": "resolvedAt", "displayName": "Resolved At" },
+    { "type": "string", "key": "reporterContact", "displayName": "Reporter Contact" },
+    { "type": "string", "key": "boxCaseFolderId", "displayName": "Case Folder ID" }
+  ]
+}

box-build/relay-flow-diagram.html

@@ -0,0 +1,277 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Pothole Portal — Box Automate (Relay) Flows</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    font-family: 'Segoe UI', Inter, system-ui, Arial, sans-serif;
+    color: #1f2733;
+    background-color: #fbfbfc;
+    background-image: radial-gradient(#e3e6ee 1px, transparent 1px);
+    background-size: 22px 22px;
+    padding: 36px 16px 70px;
+  }
+  .wrap { max-width: 760px; margin: 0 auto; }
+  h1 { font-size: 22px; font-weight: 800; text-align: center; color: #0b1f3a; }
+  .wname { text-align:center; font-size:12px; color:#69728a; margin-top:6px; }
+  .wname b { color:#0b1f3a; }
+
+  .banner {
+    margin: 16px auto 10px; max-width: 620px; background: #eaf2fd; border: 1px solid #b6d3f5;
+    color: #134a8e; border-radius: 9px; padding: 9px 14px; font-size: 12px; text-align: center;
+  }
+  .banner b { color:#0b3c78; }
+
+  .flowhdr {
+    display:flex; align-items:center; gap:10px; justify-content:center; margin: 30px auto 16px;
+  }
+  .flowhdr .pill {
+    font-size: 12px; font-weight: 800; letter-spacing:.04em; color:#0b1f3a;
+    background:#fff; border:1px solid #d3d9e6; border-radius: 24px; padding: 6px 16px;
+    box-shadow: 0 1px 3px rgba(15,30,60,.06);
+  }
+  .flowhdr .trig { font-size: 11px; color:#69728a; }
+
+  .col { display: flex; flex-direction: column; align-items: center; }
+
+  .node {
+    width: 380px; max-width: 100%; background: #fff; border: 1px solid #e4e7ef;
+    border-radius: 11px; box-shadow: 0 1px 3px rgba(15,30,60,.07);
+    padding: 11px 13px; display: flex; gap: 11px; align-items: flex-start;
+  }
+  .ico {
+    flex: 0 0 30px; width: 30px; height: 30px; border-radius: 8px; color: #fff;
+    display: flex; align-items: center; justify-content: center; font-size: 15px; font-weight: 700;
+  }
+  .node .title { font-size: 13.5px; font-weight: 700; line-height: 1.25; }
+  .node .kind { font-size: 10.5px; color:#969db0; font-weight:600; margin-top:1px; }
+  .node .desc { font-size: 11.5px; color:#5d6678; margin-top: 5px; line-height: 1.35; }
+  .aibadge { display:inline-block; margin-left:6px; font-size:9px; font-weight:800; vertical-align:middle;
+    color:#7c2bd6; background:#f3e8ff; border:1px solid #ddbdf7; border-radius:10px; padding:0 6px; letter-spacing:.05em; }
+  .note { display:inline-block; margin-top:6px; font-size:10px; font-weight:600; color:#8a5a0a;
+    background:#fff6e3; border:1px solid #f1c878; border-radius:8px; padding:2px 8px; }
+  .repl { display:inline-block; margin-top:6px; font-size:10px; font-weight:700; color:#0c6b46;
+    background:#e7f7ef; border:1px solid #b6e3cd; border-radius:20px; padding:1px 8px; }
+
+  /* icon colors */
+  .c-trigger { background:#0061d5; }
+  .c-extract { background:#a855f7; }
+  .c-agent   { background:#d946ef; }
+  .c-split   { background:#64748b; }
+  .c-folder  { background:#0a73e0; }
+  .c-file    { background:#3b8ee8; }
+  .c-meta    { background:#7c3aed; }
+  .c-http    { background:#0e9f6e; }
+  .c-notify  { background:#e8920c; }
+  .c-task    { background:#2563eb; }
+  .c-form    { background:#0891b2; }
+  .c-sign    { background:#9333ea; }
+  .c-gov     { background:#475569; }
+  .c-end     { background:#94a3b8; }
+
+  .conn { width: 2px; height: 22px; background: #c4cad8; }
+  .plus {
+    width: 18px; height: 18px; border-radius: 50%; border: 1.5px solid #c4cad8; color:#9aa2b4;
+    display:flex; align-items:center; justify-content:center; font-size:13px; line-height:1; background:#fff;
+  }
+
+  .branchbar { width: 100%; }
+  .branchbar .hline { height: 2px; background: #c4cad8; margin: 0 auto; }
+  .cols { display: grid; gap: 14px; }
+  .cols.two  { grid-template-columns: 1fr 1fr; }
+  .cols.four { grid-template-columns: repeat(4, 1fr); }
+  .bcol { display:flex; flex-direction:column; align-items:center; }
+  .tick { width:2px; height:14px; background:#c4cad8; }
+  .blabel {
+    font-size: 10.5px; font-weight: 700; letter-spacing:.03em; color:#54607a;
+    background:#eef1f7; border:1px solid #d8deea; border-radius: 20px; padding: 2px 11px; margin-bottom: 8px;
+  }
+  .blabel.yes { color:#0c6b46; background:#e7f7ef; border-color:#b6e3cd; }
+  .blabel.no  { color:#ad2222; background:#fdeaea; border-color:#f1bcbc; }
+
+  .node.sm { width: 100%; padding: 9px 10px; }
+  .node.sm .ico { flex-basis:24px; width:24px; height:24px; font-size:12px; border-radius:6px; }
+  .node.sm .title { font-size: 12px; }
+  .node.sm .desc { font-size: 10.5px; margin-top:3px; }
+
+  .endpill { font-size:10.5px; font-weight:700; color:#64748b; background:#eef1f7;
+    border:1px solid #d8deea; border-radius:20px; padding:3px 12px; margin-top:8px; }
+
+  .divider { display:flex; align-items:center; gap:12px; width:100%; max-width:560px; margin:8px auto; color:#8a93a6; font-size:11.5px; font-weight:600; }
+  .divider::before, .divider::after { content:""; flex:1; height:1px; background:#d3d9e6; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>Box Automate (Relay) — Pothole Portal</h1>
+  <div class="wname">Two flows · <b>Box Extract</b> + <b>Box Agent</b> enabled · backend supplies the GIS &amp; weather data AI can't compute</div>
+  <div class="banner"><b>Full Box-native build:</b> AI agents do extraction, scoring &amp; summary; a lightweight data lookup provides GPS→ward &amp; weather inputs.</div>
+
+  <!-- ============ FLOW 1 ============ -->
+  <div class="flowhdr">
+    <span class="pill">FLOW 1 — Intake → Dispatch</span>
+    <span class="trig">triggered by file upload</span>
+  </div>
+
+  <div class="col">
+
+    <div class="node">
+      <div class="ico c-trigger">⚡</div>
+      <div><div class="title">File Uploaded</div>
+        <div class="kind">TRIGGER · Incoming Reports</div>
+        <div class="desc">Citizen report lands: photo + <b>_metadata.json</b>.</div></div>
+    </div>
+    <div class="conn"></div>
+
+    <div class="node">
+      <div class="ico c-extract">⊞</div>
+      <div><div class="title">Extract Agent <span class="aibadge">AI</span></div>
+        <div class="kind">BOX EXTRACT · file → metadata</div>
+        <div class="desc">Reads the JSON and writes the <b>potholeCase</b> metadata: caseId, location, AI size, road score.</div></div>
+    </div>
+    <div class="conn"></div>
+
+    <div class="node">
+      <div class="ico c-agent">✦</div>
+      <div><div class="title">Box Agent — Enrichment &amp; Scoring <span class="aibadge">AI</span></div>
+        <div class="kind">BOX AGENT · reasoning</div>
+        <div class="desc">Evaluates severity score &amp; level, writes a case summary, and reasons over duplicate likelihood.</div>
+        <span class="note">GPS→ward &amp; weather supplied via HTTPS data lookup (AI can't compute geometry)</span></div>
+    </div>
+    <div class="conn"></div>
+
+    <div class="node">
+      <div class="ico c-split">◇</div>
+      <div><div class="title">Duplicate Check</div>
+        <div class="kind">CONDITIONAL SPLIT · metadata: duplicateStatus</div>
+        <div class="desc">Within 50–100 m of an open case?</div></div>
+    </div>
+
+    <div class="branchbar">
+      <div class="hline" style="width:70%;"></div>
+      <div class="cols two">
+        <div class="bcol">
+          <div class="tick"></div><div class="blabel">DUPLICATE</div>
+          <div class="node sm"><div class="ico c-file">▤</div>
+            <div><div class="title">Link to Parent Case</div><div class="kind">FILE ACTION + ADD METADATA</div>
+            <div class="desc">Move to Duplicates · boost severity.</div></div></div>
+          <div class="endpill">END · no new work order</div>
+        </div>
+        <div class="bcol">
+          <div class="tick"></div><div class="blabel">NEW REPORT</div>
+          <div class="node sm"><div class="ico c-folder">▣</div>
+            <div><div class="title">Create Case Folder</div><div class="kind">FOLDER ACTION</div>
+            <div class="desc">Potholes / Ward-{ward} / Case-{caseId}</div></div></div>
+        </div>
+      </div>
+    </div>
+
+    <div class="conn"></div>
+    <div class="node"><div class="ico c-meta">M</div>
+      <div><div class="title">Set Status &amp; Move Into Folder</div>
+        <div class="kind">ADD METADATA + FILE ACTION</div>
+        <div class="desc">status = <b>Under Review</b>.</div></div></div>
+    <div class="conn"></div>
+
+    <div class="node"><div class="ico c-notify">✉</div>
+      <div><div class="title">Notify Ward Engineer</div>
+        <div class="kind">SEND NOTIFICATION</div>
+        <div class="desc">Folder link · photo · AI summary · severity · nearby cases.</div></div></div>
+    <div class="conn"></div>
+
+    <div class="node"><div class="ico c-task">✓</div>
+      <div><div class="title">Review &amp; Approval</div>
+        <div class="kind">TASK ACTION · Approval from authority</div>
+        <div class="desc">Approve · adjust severity · or reject (web / mobile).</div></div></div>
+
+    <div class="branchbar">
+      <div class="hline" style="width:70%;"></div>
+      <div class="cols two">
+        <div class="bcol">
+          <div class="tick"></div><div class="blabel no">REJECTED</div>
+          <div class="node sm"><div class="ico c-meta">M</div>
+            <div><div class="title">Reject &amp; Archive</div><div class="kind">ADD METADATA + FILE ACTION</div>
+            <div class="desc">status = Rejected · notify reporter.</div></div></div>
+          <div class="endpill">END</div>
+        </div>
+        <div class="bcol">
+          <div class="tick"></div><div class="blabel yes">APPROVED</div>
+          <div class="node sm"><div class="ico c-http">⇄</div>
+            <div><div class="title">Generate Work Order</div><div class="kind">HTTPS → backend → Box Doc Gen</div>
+            <div class="desc">Stamp workOrderId · Job Sheet PDF into folder.</div>
+            <span class="repl">No city-system API</span></div></div>
+          <div class="tick"></div>
+          <div class="node sm"><div class="ico c-meta">M</div>
+            <div><div class="title">status = Assigned</div><div class="kind">ADD METADATA</div></div></div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <div class="flowhdr" style="margin-top:18px;"><span class="trig">— job sheet sent · crew repairs on site —</span></div>
+
+  <!-- ============ FLOW 2 ============ -->
+  <div class="flowhdr">
+    <span class="pill">FLOW 2 — Crew Reporting &amp; Closeout</span>
+    <span class="trig">triggered by Box Form submission</span>
+  </div>
+
+  <div class="col">
+
+    <div class="node">
+      <div class="ico c-form">▦</div>
+      <div><div class="title">Crew Submits Box Form (mobile)</div>
+        <div class="kind">TRIGGER · Box Form · on-site</div>
+        <div class="desc">Repair method (cold patch / hot mix / full-depth) · materials · labor hours · <b>after-photo(s)</b> → case folder.</div></div>
+    </div>
+    <div class="conn"></div>
+
+    <div class="node"><div class="ico c-meta">M</div>
+      <div><div class="title">Record Closeout Data</div>
+        <div class="kind">ADD METADATA</div>
+        <div class="desc">status = <b>In Progress</b> · materials, labor, after-photo IDs written to the case.</div></div></div>
+    <div class="conn"></div>
+
+    <div class="node"><div class="ico c-sign">✎</div>
+      <div><div class="title">Request Signature</div>
+        <div class="kind">REQUEST SIGNATURE · Box Sign</div>
+        <div class="desc">Crew lead signs the completion certificate.</div></div></div>
+
+    <div class="branchbar">
+      <div class="hline" style="width:86%;"></div>
+      <div class="cols four">
+        <div class="bcol"><div class="tick"></div><div class="blabel yes">COMPLETED</div>
+          <div class="node sm"><div class="ico c-http">⇄</div>
+            <div><div class="title">Resolve Case</div><div class="kind">HTTPS → backend</div>
+            <div class="desc">status = Resolved · audit + before/after report.</div></div></div></div>
+        <div class="bcol"><div class="tick"></div><div class="blabel no">DECLINED</div>
+          <div class="node sm"><div class="ico c-notify">✉</div>
+            <div><div class="title">Re-route</div><div class="kind">SEND NOTIFICATION</div></div></div></div>
+        <div class="bcol"><div class="tick"></div><div class="blabel">EXPIRED</div>
+          <div class="node sm"><div class="ico c-notify">✉</div>
+            <div><div class="title">Remind</div><div class="kind">SEND NOTIFICATION</div></div></div></div>
+        <div class="bcol"><div class="tick"></div><div class="blabel">CANCELLED</div>
+          <div class="node sm"><div class="ico c-meta">M</div>
+            <div><div class="title">Hold</div><div class="kind">ADD METADATA</div></div></div></div>
+      </div>
+    </div>
+
+    <div class="conn"></div>
+    <div class="node"><div class="ico c-notify">✉</div>
+      <div><div class="title">Notify Supervisor + Risk Management</div>
+        <div class="kind">SEND NOTIFICATION</div>
+        <div class="desc">Citizen portal status updated to “Resolved”.</div></div></div>
+    <div class="conn"></div>
+
+    <div class="node"><div class="ico c-gov">G</div>
+      <div><div class="title">Audit-Ready Case Record</div>
+        <div class="kind">BOX GOVERNANCE</div>
+        <div class="desc">Retention / legal hold · full version history · activity log · access control.</div></div></div>
+
+  </div>
+</div>
+</body>
+</html>

box-build/revised-workflow-diagram.html

@@ -0,0 +1,206 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Pothole Operations — Revised Workflow</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    font-family: 'Segoe UI', Inter, system-ui, Arial, sans-serif;
+    background: #f4f6fb;
+    color: #1f2733;
+    padding: 40px 16px 64px;
+    line-height: 1.4;
+  }
+  .wrap { max-width: 860px; margin: 0 auto; }
+  h1 { font-size: 26px; font-weight: 800; text-align: center; color: #0b1f3a; }
+  .subtitle { text-align: center; color: #5b6679; font-size: 14px; margin-top: 6px; }
+
+  .legend { display: flex; gap: 18px; justify-content: center; margin: 18px 0 28px; flex-wrap: wrap; }
+  .legend span { display: inline-flex; align-items: center; gap: 7px; font-size: 12.5px; color: #44506a; }
+  .dot { width: 12px; height: 12px; border-radius: 3px; display: inline-block; }
+
+  .phase {
+    text-align: center; font-size: 12px; font-weight: 700; letter-spacing: .08em;
+    text-transform: uppercase; color: #7a8499; margin: 26px 0 14px;
+    border-top: 1px dashed #c4ccda; padding-top: 12px;
+  }
+
+  .row { display: grid; grid-template-columns: 1fr minmax(280px, 360px) 1fr; align-items: center; gap: 12px; }
+  .row .center { grid-column: 2; }
+
+  .node {
+    border-radius: 12px; padding: 14px 18px; text-align: center;
+    border: 1px solid; box-shadow: 0 2px 6px rgba(15,30,60,.06);
+  }
+  .node .t { font-weight: 700; font-size: 15px; }
+  .node .d { font-size: 12.5px; margin-top: 4px; opacity: .92; }
+
+  .portal { background: #e7f7ef; border-color: #9ae0c0; color: #0c6b46; }
+  .backend { background: #f1ecfe; border-color: #c3b1f5; color: #4c2aa3; }
+  .box     { background: #e9f2fd; border-color: #a9cdf6; color: #0a4a9c; }
+  .review  { background: #e7f7ef; border-color: #9ae0c0; color: #0c6b46; }
+  .crew    { background: #fdeaea; border-color: #f4b4b4; color: #ad2222; }
+  .audit   { background: #eef2f8; border-color: #ccd6e6; color: #3b475e; }
+  .decision {
+    background: #fff6e3; border: 1px solid #f1c878; color: #92600c;
+    border-radius: 12px; padding: 14px 18px; text-align: center; font-weight: 700; font-size: 15px;
+    box-shadow: 0 2px 6px rgba(15,30,60,.06);
+  }
+
+  .note {
+    background: #fff; border: 1px solid #e1e7f0; border-radius: 9px;
+    padding: 9px 11px; font-size: 11.5px; color: #5b6679; box-shadow: 0 1px 3px rgba(15,30,60,.05);
+  }
+  .note b { color: #34405a; display: block; margin-bottom: 3px; font-size: 11px; }
+  .note.left { justify-self: end; } .note.right { justify-self: start; }
+
+  .status {
+    display: inline-block; margin-top: 8px; font-size: 11px; font-weight: 700;
+    background: rgba(255,255,255,.6); border-radius: 20px; padding: 2px 10px; letter-spacing: .03em;
+  }
+
+  .conn { width: 2px; height: 26px; background: #b9c3d4; margin: 4px auto; }
+  .conn.sm { height: 16px; }
+
+  .branch { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; max-width: 720px; margin: 0 auto; }
+  .branch .lbl { text-align: center; font-size: 11px; font-weight: 700; color: #7a8499; margin-bottom: 6px; letter-spacing:.05em; }
+  .tag-yes { color: #ad7100; } .tag-no { color: #0a4a9c; }
+
+  .footer-note {
+    margin: 26px auto 0; max-width: 720px; background: #fff; border: 1px dashed #b9c3d4;
+    border-radius: 10px; padding: 12px 16px; font-size: 12.5px; color: #44506a; text-align: center;
+  }
+  .footer-note b { color: #0b1f3a; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>Pothole Operations — Revised Workflow</h1>
+  <div class="subtitle">Backend computes the geospatial scoring · Box runs content, workflow, documents, signature &amp; audit</div>
+
+  <div class="legend">
+    <span><i class="dot" style="background:#0c6b46"></i> Citizen portal</span>
+    <span><i class="dot" style="background:#4c2aa3"></i> Our backend service</span>
+    <span><i class="dot" style="background:#0a4a9c"></i> Box (native)</span>
+    <span><i class="dot" style="background:#92600c"></i> Decision</span>
+    <span><i class="dot" style="background:#ad2222"></i> Field crew</span>
+  </div>
+
+  <!-- PHASE 1 -->
+  <div class="phase">Phase 1 — Citizen Intake</div>
+  <div class="row">
+    <div class="note left"><b>Form fields</b>Name / contact · Location or address · Photo upload(s)</div>
+    <div class="center node portal">
+      <div class="t">Citizen Submission Portal</div>
+      <div class="d">Web form · mobile app · 311 integration</div>
+      <span class="status">Submitted</span>
+    </div>
+    <div class="note right"><b>Auto-captured</b>GPS coordinates · Timestamp (UTC) · On-device AI size detection</div>
+  </div>
+
+  <div class="conn"></div>
+
+  <!-- PHASE 2 -->
+  <div class="phase">Phase 2 — Backend Enrichment (at submission)</div>
+  <div class="row">
+    <div class="note left"><b>Severity inputs</b>Damage size / depth · Road classification · Prior 311 notices · Weather forecast</div>
+    <div class="center node backend">
+      <div class="t">Backend Service — Enrich &amp; Score</div>
+      <div class="d">GPS → ward / district · Severity score · Weather risk · builds the <b>complete JSON</b></div>
+    </div>
+    <div class="note right"><b>Why backend</b>Geometry, scoring &amp; weather aren't AI tasks — computed here, then handed to Box ready-to-use</div>
+  </div>
+
+  <div class="conn"></div>
+  <div class="decision">Duplicate within 50–100&nbsp;m radius?</div>
+  <div class="conn sm"></div>
+
+  <div class="branch">
+    <div>
+      <div class="lbl tag-yes">YES</div>
+      <div class="node backend">
+        <div class="t">Link to existing case</div>
+        <div class="d">Boost severity · no new work order</div>
+      </div>
+    </div>
+    <div>
+      <div class="lbl tag-no">NO</div>
+      <div class="node backend">
+        <div class="t">Create new case</div>
+        <div class="d">Fresh case ID</div>
+      </div>
+    </div>
+  </div>
+
+  <div class="conn"></div>
+
+  <!-- PHASE 3 -->
+  <div class="phase">Phase 3 — Box Storage &amp; Routing</div>
+  <div class="row">
+    <div class="note left"><b>Lands in Box</b>Photo + complete JSON → Incoming Reports folder</div>
+    <div class="center node box">
+      <div class="t">Upload to Box + Apply Metadata</div>
+      <div class="d">Backend writes <b>potholeCase</b> metadata directly — works even if Box AI / Extract is off</div>
+    </div>
+    <div class="note right"><b>Box Extract</b>Confirms / maps JSON → metadata when enabled (optional, not required)</div>
+  </div>
+
+  <div class="conn"></div>
+  <div class="row">
+    <div class="center node box">
+      <div class="t">Case Folder Created + Metadata Applied</div>
+      <div class="d">Box Relay · Potholes / Ward-XYZ / Case-ABC123</div>
+      <span class="status">Under Review</span>
+    </div>
+  </div>
+
+  <div class="conn"></div>
+
+  <!-- PHASE 4 -->
+  <div class="phase">Phase 4 — Human Review &amp; Dispatch</div>
+  <div class="row">
+    <div class="center node review">
+      <div class="t">Ward Engineer Notified (Box Relay)</div>
+      <div class="d">Folder link · photo · AI summary · nearby cases → approve / adjust severity / reject</div>
+    </div>
+  </div>
+  <div class="conn sm"></div>
+  <div class="row">
+    <div class="center node box">
+      <div class="t">Work Order Generated (Box Doc Gen)</div>
+      <div class="d">Job Sheet PDF from case metadata — no external system needed</div>
+      <span class="status">Assigned</span>
+    </div>
+  </div>
+  <div class="conn sm"></div>
+  <div class="row">
+    <div class="center node crew">
+      <div class="t">Crew Completes Box Form (mobile)</div>
+      <div class="d">Repair method · materials · labor hours · after-photo · <b>Box Sign</b></div>
+      <span class="status">In Progress</span>
+    </div>
+  </div>
+
+  <div class="conn"></div>
+
+  <!-- PHASE 5 -->
+  <div class="phase">Phase 5 — Closeout &amp; Audit Record</div>
+  <div class="row">
+    <div class="note left"><b>Notifications</b>Supervisor + risk management · citizen portal updated to “Resolved”</div>
+    <div class="center node audit">
+      <div class="t">Audit-Ready Case Record</div>
+      <div class="d">Box Governance — retention / legal hold · full version history · activity log · access control</div>
+      <span class="status">Resolved</span>
+    </div>
+    <div class="note right"><b>Citizen view</b>Status checked in the portal — no Box login required</div>
+  </div>
+
+  <div class="footer-note">
+    <b>Two external dependencies are removed:</b> work orders are generated in Box (Doc Gen), and enrichment runs in our backend —
+    so the workflow needs <b>no tunnel</b> and <b>no city-system API</b> to demo. The city work-order REST push and live 311 sync remain optional future integrations.
+  </div>
+</div>
+</body>
+</html>

box-build/seed-demo-cases.js

@@ -0,0 +1,116 @@
+/**
+ * Seed demo pothole cases into Box for the PotholeIQ dashboard / Command Center.
+ * Runs the real backend pipeline (folders + files + potholeCase metadata on the case
+ * FOLDER only, incl. severity breakdown), then sets each case's lifecycle status.
+ *
+ * Usage:  node box-build/seed-demo-cases.js <FRESH_DEV_TOKEN> [intakeFolderId]
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const bf = require(path.join(__dirname, '..', 'box-folders.js'));
+
+const TOKEN = process.argv[2];
+const INTAKE = process.argv[3] || '386202381022';
+if (!TOKEN) { console.error('Pass a fresh Box dev token as arg 1.'); process.exit(1); }
+
+const tmpl = { scope: 'enterprise', templateKey: 'potholeCase' };
+const now = () => new Date().toISOString();
+const daysAgo = (d) => new Date(Date.now() - d * 864e5).toISOString();
+
+// ---- ward lookup from the bundled Philadelphia GeoJSON (point-in-polygon) ----
+const geo = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'data', 'ward-boundaries.geojson'), 'utf8'));
+function pip(pt, poly){let [x,y]=pt,inside=false,n=poly.length,j=n-1;for(let i=0;i<n;i++){const[xi,yi]=poly[i],[xj,yj]=poly[j];if(((yi>y)!=(yj>y))&&(x<(xj-xi)*(y-yi)/(yj-yi)+xi))inside=!inside;j=i;}return inside;}
+function wardOf(lat,lng){for(const f of geo.features){const g=f.geometry,polys=g.type==='MultiPolygon'?g.coordinates:[g.coordinates];for(const mp of polys){if(pip([lng,lat],mp[0]))return f.properties.ward_num||f.properties.ward||'?';}}return 'Unknown';}
+
+// ---- factor detail text (mirrors enrichment.js) ----
+const PN = s => s>=30?'3+ prior reports — high prior notice / strong legal weight':s>=22?'2 prior reports — notable prior notice':s>=12?'1 prior report found within 80 m':'No prior reports at this location';
+const TR = s => s>=25?'Critical infrastructure / high-traffic route (school, hospital, arterial)':s>=18?'Major arterial or collector road — high traffic volume':s>=12?'Local collector street — moderate traffic':'Residential / low-traffic street';
+const DM = s => s>=25?'Large — bowl-shaped, severe damage affecting ride and safety':s>=15?'Medium — noticeable damage, not yet vehicle-threatening':'Small — initial / emerging surface defect';
+const WE = s => s>=10?'Freeze-thaw + heavy precipitation — extreme expansion risk':s>=8?'Freeze-thaw cycle predicted — high expansion risk':s>=7?'Heavy rain/snow forecast — accelerated deterioration':s>=4?'Moderate precipitation expected — moderate risk':'Dry / stable forecast — minimal weather risk';
+const sizeFromDamage = s => s>=25?'Large':s>=15?'Medium':'Small';
+const riskFromWeather = s => s>=7?'high':s>=4?'medium':'low';
+const levelFromScore = s => s>=76?'Critical':s>=56?'High':s>=31?'Medium':'Low';
+// prior-notice score derived from the duplicate count, so "N prior reports" always == duplicateCount
+const pnFromDup = d => d>=3?30:d>=2?22:d>=1?12:0;
+// real demo photos (so the dashboard shows actual images, not text)
+const DEMO_IMAGES = fs.readdirSync(path.join(__dirname, '..', 'demo pothole images')).filter(f => /\.jpe?g$/i.test(f));
+
+// [name, lat, lng, prior, traffic, damage, weather, status, crew, dupCount]
+const RAW = [
+  ['City Hall',            39.9526,-75.1652, 22,25,25,10, 'under review','',          2],
+  ['Kensington Ave',       39.9905,-75.1190, 30,18,25, 8, 'assigned','Crew Alpha',    3],
+  ['Broad & Erie',         40.0090,-75.1490, 22,25,25, 7, 'in progress','Crew Bravo', 0],
+  ['Frankford Ave',        39.9690,-75.1300, 22,18,15, 7, 'under review','',          1],
+  ['Germantown Ave',       40.0330,-75.1730, 22,18,15, 6, 'assigned','Crew Charlie',  0],
+  ['Fairmount Ave',        39.9670,-75.1750, 12,25,15, 7, 'resolved','Crew Alpha',    0],
+  ['Frankford NE',         40.0220,-75.0840, 14,18,15,10, 'under review','',          0],
+  ['Lancaster Ave',        39.9612,-75.2090, 12,18, 6, 4, 'under review','',          0],
+  ['Manayunk Main St',     40.0260,-75.2230,  0,18,15, 4, 'assigned','Crew Delta',    0],
+  ['Point Breeze Ave',     39.9320,-75.1830, 12,12, 6, 7, 'resolved','Crew Bravo',    0],
+  ['Mount Airy',           40.0560,-75.1880,  0,18,15, 0, 'in progress','Crew Charlie',0],
+  ['Old City 2nd St',      39.9510,-75.1430, 12,12, 6, 4, 'under review','',          0],
+  ['Roxborough Ridge',     40.0440,-75.2230,  0,12, 6, 4, 'resolved','Crew Delta',    0],
+  ['Snyder Ave',           39.9210,-75.1700,  0, 6, 6, 4, 'rejected','',              0],
+  ['Bustleton Ave',        40.0600,-75.0500,  0, 6, 6, 0, 'rejected','',              0],
+];
+
+const CASES = RAW.map(([name,lat,lng,pn0,tr,dm,we,status,crew,dup],i)=>{
+  const pn = pnFromDup(dup);   // keep prior-notice consistent with duplicate count
+  const score = pn+tr+dm+we;
+  return {
+    suffix: String(i+1).padStart(2,'0'), name, lat, lng, status, crew,
+    ward: String(wardOf(lat,lng)),
+    address: `${name}, Philadelphia, PA`,
+    size: sizeFromDamage(dm), score, level: levelFromScore(score),
+    dupCount: dup, linked: dup>0 ? [`PHX-LEGACY-${100+i}`,`PHX-LEGACY-${200+i}`].slice(0,dup) : [],
+    submittedAt: daysAgo((i%10)+1),
+    bd: {
+      priorNotice:{score:pn,detail:PN(pn)}, traffic:{score:tr,detail:TR(tr)},
+      damage:{score:dm,detail:DM(dm)}, weather:{score:we,detail:WE(we),riskLevel:riskFromWeather(we)},
+    },
+  };
+});
+
+async function uploadFile(name, bytes){
+  const fd=new FormData();
+  fd.append('attributes',JSON.stringify({name,parent:{id:INTAKE}}));
+  fd.append('file',new Blob([bytes]),name);
+  const r=await fetch('https://upload.box.com/api/2.0/files/content',{method:'POST',headers:{Authorization:`Bearer ${TOKEN}`},body:fd}).then(x=>x.json());
+  return r.entries[0].id;
+}
+const md = (id) => fetch(`https://api.box.com/2.0/folders/${id}/metadata/enterprise/potholeCase`,{headers:{Authorization:`Bearer ${TOKEN}`}}).then(r=>r.json());
+
+(async () => {
+  const me = await fetch('https://api.box.com/2.0/users/me?fields=name,login',{headers:{Authorization:`Bearer ${TOKEN}`}}).then(r=>r.json());
+  if(!me.login){console.error('Token invalid:',JSON.stringify(me));process.exit(1);}
+  console.log('Auth OK:', me.name);
+
+  let dist={Critical:0,High:0,Medium:0,Low:0};
+  for(const c of CASES){
+    const caseId=`PHX-DEMO-${c.suffix}`;
+    const report={caseId,submittedAt:c.submittedAt,address:c.address,location:{lat:c.lat,lng:c.lng,source:'gps'},aiResult:c.size,aiPrediction:c.size,aiConfidence:0.9,aiReviewStatus:'auto_confirmed'};
+    const enrichment={severityScore:c.score,severityLevel:c.level,enrichedAt:c.submittedAt,
+      district:{district:`District ${c.ward}`,ward:c.ward,maintenanceZone:`Zone-${c.ward}`},
+      duplicate:{isDuplicate:c.dupCount>0,duplicateCount:c.dupCount,linkedCaseIds:c.linked,effectiveSeverityBoost:c.dupCount*4},
+      severityBreakdown:{priorNotice:{...c.bd.priorNotice,max:30},traffic:{...c.bd.traffic,max:25},damage:{...c.bd.damage,max:25},weather:{...c.bd.weather,max:10}},
+      report};
+    const imgBytes=fs.readFileSync(path.join(__dirname,'..','demo pothole images',DEMO_IMAGES[(parseInt(c.suffix,10)-1)%DEMO_IMAGES.length]));
+    const photoFileId=await uploadFile(`${caseId}_photo.jpg`,imgBytes);
+    const sidecarFileId=await uploadFile(`${caseId}_metadata.json`,JSON.stringify(report,null,2));
+    const res=await bf.organizeInBox({caseId,ward:c.ward,district:`District ${c.ward}`,photoFileId,sidecarFileId,enrichment,reportPayload:report,rootFolderId:INTAKE,metadataTemplate:tmpl,token:TOKEN,onStep:()=>{}});
+    // set lifecycle status (organizeInBox defaults to 'under review')
+    if(c.status!=='under review'){
+      const patch={status:c.status};
+      if(c.crew)patch.assignedCrew=c.crew;
+      if(c.status==='resolved'){patch.resolvedAt=now();patch.supervisorWardEngineer='Eng. R. Diaz';}
+      await bf.applyFolderMetadata(res.caseFolderId,patch,TOKEN,{template:tmpl});
+    } else if(c.crew){
+      await bf.applyFolderMetadata(res.caseFolderId,{assignedCrew:c.crew},TOKEN,{template:tmpl});
+    }
+    dist[c.level]++;
+    console.log(`  ${caseId}  Ward ${c.ward.padStart(2)}  ${c.level.padEnd(8)} ${String(c.score).padStart(3)}  ${c.status}`);
+  }
+  console.log('\nSeeded',CASES.length,'cases  |  severity:',JSON.stringify(dist));
+  console.log('Open: http://localhost:3030/command-center.html');
+})().catch(e=>{console.error('ERROR',e);process.exit(1);});

box-build/wf1-revised-diagram.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Workflow One — Revised (Intake → Dispatch)</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: 'Segoe UI', Inter, system-ui, Arial, sans-serif; background: #f4f6fb; color: #1f2733; padding: 36px 16px 64px; line-height: 1.4; }
+  .wrap { max-width: 900px; margin: 0 auto; }
+  h1 { font-size: 24px; font-weight: 800; text-align: center; color: #0b1f3a; }
+  .subtitle { text-align: center; color: #5b6679; font-size: 13.5px; margin-top: 6px; }
+  .legend { display: flex; gap: 16px; justify-content: center; margin: 16px 0 26px; flex-wrap: wrap; font-size: 12.5px; color: #44506a; }
+  .legend span { display: inline-flex; align-items: center; gap: 7px; }
+  .dot { width: 12px; height: 12px; border-radius: 3px; display: inline-block; }
+  .node { border-radius: 12px; padding: 12px 16px; text-align: center; border: 1px solid; box-shadow: 0 2px 6px rgba(15,30,60,.06); max-width: 420px; margin: 0 auto; }
+  .node .t { font-weight: 700; font-size: 14.5px; }
+  .node .d { font-size: 12px; margin-top: 3px; opacity: .92; }
+  .trigger { background:#e9f2fd; border-color:#a9cdf6; color:#0a4a9c; }
+  .ai      { background:#f1ecfe; border-color:#c3b1f5; color:#4c2aa3; }
+  .action  { background:#e7f7ef; border-color:#9ae0c0; color:#0c6b46; }
+  .doc     { background:#fff4e6; border-color:#f4c68a; color:#9a5b06; }
+  .notify  { background:#fdeaf5; border-color:#f3b6da; color:#a01f72; }
+  .end     { background:#eef2f8; border-color:#ccd6e6; color:#3b475e; font-size:12.5px; }
+  .removed { background:#fdeaea; border-color:#f4b4b4; color:#ad2222; text-decoration: line-through; opacity:.8; }
+  .decision { background:#fff6e3; border:1px solid #f1c878; color:#92600c; border-radius:12px; padding:11px 16px; text-align:center; font-weight:700; font-size:14px; max-width:420px; margin:0 auto; box-shadow:0 2px 6px rgba(15,30,60,.06); }
+  .conn { width:2px; height:22px; background:#b9c3d4; margin:5px auto; }
+  .conn.sm { height:14px; }
+  .branch { display:grid; grid-template-columns:1fr 1fr; gap:18px; max-width:820px; margin:0 auto; }
+  .lbl { text-align:center; font-size:11px; font-weight:700; color:#7a8499; margin-bottom:6px; letter-spacing:.05em; text-transform:uppercase; }
+  .col { display:flex; flex-direction:column; gap:0; }
+  .note { background:#fff; border:1px dashed #b9c3d4; border-radius:9px; padding:8px 12px; font-size:11.5px; color:#44506a; max-width:520px; margin:6px auto 0; text-align:center; }
+  .phase { text-align:center; font-size:11px; font-weight:700; letter-spacing:.08em; text-transform:uppercase; color:#7a8499; margin:22px auto 12px; border-top:1px dashed #c4ccda; padding-top:10px; max-width:600px; }
+  .star { color:#9a5b06; font-weight:800; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>Workflow One — Revised</h1>
+  <div class="subtitle">Backend owns folders + metadata · WF1 = human workflow only · <span class="star">+ Work Order added</span></div>
+
+  <div class="legend">
+    <span><i class="dot" style="background:#0a4a9c"></i> Trigger</span>
+    <span><i class="dot" style="background:#4c2aa3"></i> Box AI</span>
+    <span><i class="dot" style="background:#0c6b46"></i> Metadata / Action</span>
+    <span><i class="dot" style="background:#a01f72"></i> Notification</span>
+    <span><i class="dot" style="background:#9a5b06"></i> Doc Gen</span>
+    <span><i class="dot" style="background:#ad2222"></i> Remove</span>
+  </div>
+
+  <!-- TRIGGER -->
+  <div class="node trigger"><div class="t">⚡ Trigger — Metadata Event</div><div class="d">potholeCase · <b>status = under review</b> &nbsp;(fires after the backend applies metadata — loop-safe, no race)</div></div>
+  <div class="note">⛔ CHANGED from "File Uploaded → Incoming Detections" (that raced the backend & fired before metadata existed)</div>
+  <div class="conn"></div>
+
+  <!-- REMOVED Extract -->
+  <div class="node removed"><div class="t">Default Standard Extract Agent</div><div class="d">DELETE — backend already wrote the metadata; this node was halting the flow</div></div>
+  <div class="conn"></div>
+
+  <!-- Box Agent -->
+  <div class="node ai"><div class="t">🤖 Box Agent — AI Summary</div><div class="d">2–3 sentence case summary → write to <b>aiSummary</b></div></div>
+  <div class="conn"></div>
+
+  <!-- Decision: duplicate -->
+  <div class="decision">Conditional Split — duplicateStatus = "duplicate "?</div>
+  <div class="conn sm"></div>
+
+  <div class="branch">
+    <div class="col">
+      <div class="lbl">Branch 1 — DUPLICATE</div>
+      <div class="node removed"><div class="t">Move → duplicates/</div><div class="d">DELETE — backend already placed the file</div></div>
+      <div class="conn sm"></div>
+      <div class="node notify"><div class="t">🔔 Send Notification</div><div class="d">Alert ward engineer: linked to existing cluster ({linkedCaseIds})</div></div>
+      <div class="conn sm"></div>
+      <div class="node end">⛔ End — no work order (it's a duplicate)</div>
+    </div>
+
+    <div class="col">
+      <div class="lbl">Else — NEW CASE</div>
+      <div class="node removed"><div class="t">Create "Case-{caseId}" folder</div><div class="d">DELETE — backend creates Potholes/{ward}/Case-{id}</div></div>
+      <div class="conn sm"></div>
+      <div class="node notify"><div class="t">🔔 Send Notification → ward engineer</div><div class="d">New case {caseId} · {severityLevel} · {aiSummary} + folder link</div></div>
+      <div class="conn sm"></div>
+      <div class="node action"><div class="t">✅ Approval Task</div><div class="d">"Approve, adjust severity, or reject" → ward engineer</div></div>
+    </div>
+  </div>
+
+  <div class="phase">New case · on task result</div>
+  <div class="decision">Conditional Split — Task Approved?</div>
+  <div class="conn sm"></div>
+
+  <div class="branch">
+    <div class="col">
+      <div class="lbl">Approved</div>
+      <div class="node action"><div class="t">🏷️ Add Metadata</div><div class="d">status = <b>assigned</b></div></div>
+      <div class="conn sm"></div>
+      <div class="node doc"><div class="t">📄 Generate Document — WORK ORDER ★</div><div class="d">Template: <b>Pothole Repair Work Order (DocGen)</b> · save PDF to case folder<br>Tags from metadata by <b>caseId</b>: caseId · severityLevel · address · ward · assignedCrew</div></div>
+      <div class="conn sm"></div>
+      <div class="node action"><div class="t">🏷️ Add Metadata</div><div class="d">workOrderId = {generated doc name / id}</div></div>
+      <div class="conn sm"></div>
+      <div class="node end">⛔ End — case Assigned, work order filed</div>
+    </div>
+    <div class="col">
+      <div class="lbl">Rejected</div>
+      <div class="node action"><div class="t">🏷️ Add Metadata</div><div class="d">status = <b>rejected</b></div></div>
+      <div class="conn sm"></div>
+      <div class="node notify"><div class="t">🔔 Send Notification</div><div class="d">"Case {caseId} ({severityLevel}) was rejected"</div></div>
+      <div class="conn sm"></div>
+      <div class="node end">⛔ End — case Rejected</div>
+    </div>
+  </div>
+
+  <div class="note" style="margin-top:24px;border-color:#9a5b06;color:#7a4a05;">
+    <b>★ The work order you flagged:</b> add a <b>Generate Document</b> node in the Approved branch.
+    Crew may not be assigned yet at approval, so <b>assignedCrew</b> can be blank here and filled at the deploy-crew step.
+  </div>
+</div>
+</body>
+</html>

box-folders.js

@@ -0,0 +1,656 @@
+/**
+ * box-folders.js
+ * Box folder hierarchy creation, file moving, and metadata writing
+ * for the pothole operations enrichment pipeline.
+ *
+ * Creates structure:
+ *   [Root Incoming Folder]
+ *     \- Potholes/
+ *          \- Ward-29/
+ *               \- Case-PHX-1234/
+ *                    |- PHX-1234_photo.jpg
+ *                    \- PHX-1234_metadata.json
+ *
+ * Uses Box generic "properties" metadata for compatibility and can also write
+ * to a named Box metadata template when one is configured.
+ */
+
+'use strict';
+
+const BOX_API = 'https://api.box.com/2.0';
+const BOX_UPLOAD = 'https://upload.box.com/api/2.0';
+const boxWorkflowModule = (typeof module !== 'undefined' && module.exports)
+  ? require('./box-workflow.js')
+  : null;
+
+async function boxRequest(method, path, token, body = null) {
+  const opts = {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(body ? { 'Content-Type': 'application/json' } : {}),
+    },
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  };
+  const res = await fetch(`${BOX_API}${path}`, opts);
+  const data = await res.json().catch(() => ({}));
+  return { ok: res.ok, status: res.status, data };
+}
+
+function normalizeTemplateConfig(config = {}) {
+  return {
+    scope: String(config?.scope || '').trim(),
+    templateKey: String(config?.templateKey || '').trim(),
+  };
+}
+
+function shouldApplyCustomTemplate(config = {}) {
+  const normalized = normalizeTemplateConfig(config);
+  if (!normalized.scope || !normalized.templateKey) return false;
+  return !(normalized.scope === 'global' && normalized.templateKey === 'properties');
+}
+
+// --- Structured metadata template projection -------------------------------
+// A Box metadata template REJECTS unknown keys, wrong value types (float/date),
+// and enum values that don't exactly match a stored option key. The backend's
+// rich review object can't be sent as-is, so we project it onto the live schema:
+// pick the right source value per field, coerce its type, and snap enum values
+// to the exact option key the template stores (case/whitespace insensitive).
+
+const __templateSchemaCache = new Map();
+
+async function getTemplateSchema(scope, templateKey, token) {
+  const cacheKey = `${scope}/${templateKey}`;
+  if (__templateSchemaCache.has(cacheKey)) return __templateSchemaCache.get(cacheKey);
+  const { ok, data } = await boxRequest('GET', `/metadata_templates/${scope}/${templateKey}/schema`, token);
+  const schema = ok && Array.isArray(data.fields) ? data : null;
+  __templateSchemaCache.set(cacheKey, schema);
+  return schema;
+}
+
+// template field key -> ordered source keys in the review kvMap (first non-empty wins)
+const TEMPLATE_KEY_ALIASES = {
+  severityScore0100: ['severityScore0100', 'severityScore'],
+  weatherRisk: ['weatherRisk', 'weatherStatus', 'weatherRiskLevel'],
+  supervisorWardEngineer: ['supervisorWardEngineer', 'supervisor'],
+  caseFolderId: ['caseFolderId', 'boxCaseFolderId', 'boxFolderId'],
+  linkedCaseIds: ['linkedCaseIds', 'linkedCases'],
+  status: ['status', 'workflowStatus'],
+};
+
+// Per-field input-value remaps applied BEFORE matching against the schema options.
+// Needed where the source vocabulary differs from the template's option set.
+const ENUM_VALUE_ALIASES = {
+  weatherRisk: { high: 'large', severe: 'large' }, // template has no "High" option (Low/Medium/Large)
+};
+
+function pickSourceValue(kvMap, templateKey) {
+  const aliases = TEMPLATE_KEY_ALIASES[templateKey] || [templateKey];
+  for (const alias of aliases) {
+    const v = kvMap[alias];
+    if (v !== undefined && v !== null && String(v).trim() !== '') return v;
+  }
+  return undefined;
+}
+
+function matchEnumOption(value, options = []) {
+  const norm = (s) => String(s).trim().toLowerCase();
+  const target = norm(value);
+  const opt = options.find((o) => norm(o.key) === target);
+  return opt ? opt.key : null; // return EXACT stored key (preserves casing/trailing spaces)
+}
+
+function coerceForField(field, rawValue) {
+  if (rawValue === undefined || rawValue === null) return undefined;
+  const sval = String(rawValue).trim();
+  if (sval === '') return undefined;
+  switch (field.type) {
+    case 'float': {
+      const n = Number(sval);
+      return Number.isFinite(n) ? n : undefined;
+    }
+    case 'date': {
+      const d = new Date(sval);
+      if (Number.isNaN(d.getTime())) return undefined;
+      return d.toISOString().replace(/\.\d{3}Z$/, 'Z'); // RFC3339, no milliseconds
+    }
+    case 'enum':
+    case 'multiSelect': {
+      const valAlias = (ENUM_VALUE_ALIASES[field.key] || {})[sval.toLowerCase()];
+      return matchEnumOption(valAlias || sval, field.options) || undefined;
+    }
+    default:
+      return sval;
+  }
+}
+
+function projectToTemplateSchema(kvMap, schema) {
+  const out = {};
+  for (const field of schema.fields || []) {
+    const coerced = coerceForField(field, pickSourceValue(kvMap, field.key));
+    if (coerced !== undefined) out[field.key] = coerced;
+  }
+  return out;
+}
+
+async function getOrCreateFolder(parentId, name, token) {
+  console.log(`[BoxFolders] getOrCreateFolder("${name}") in parent ${parentId}`);
+  const { ok, status, data } = await boxRequest('POST', '/folders', token, {
+    name,
+    parent: { id: parentId },
+  });
+
+  if (ok) {
+    console.log(`[BoxFolders] Folder created: "${name}" -> id=${data.id}`);
+    return data.id;
+  }
+
+  if (status === 409) {
+    const existingId = data.context_info?.conflicts?.[0]?.id || null;
+    if (existingId) {
+      console.log(`[BoxFolders] Folder already exists: "${name}" -> id=${existingId}`);
+      return existingId;
+    }
+
+    const items = await boxRequest('GET', `/folders/${parentId}/items?limit=200`, token);
+    const match = (items.data?.entries || []).find((entry) => entry.type === 'folder' && entry.name === name);
+    if (match) {
+      console.log(`[BoxFolders] Folder found via listing: "${name}" -> id=${match.id}`);
+      return match.id;
+    }
+
+    throw new Error(`Could not resolve existing folder "${name}" in parent ${parentId}`);
+  }
+
+  throw new Error(`Create folder "${name}" failed (${status}): ${data.message || JSON.stringify(data)}`);
+}
+
+async function moveFile(fileId, destFolderId, token) {
+  console.log(`[BoxFolders] moveFile fileId=${fileId} -> folder ${destFolderId}`);
+  const { ok, status, data } = await boxRequest('PUT', `/files/${fileId}`, token, {
+    parent: { id: destFolderId },
+  });
+  if (!ok) throw new Error(`Move file ${fileId} failed (${status}): ${data.message || ''}`);
+  console.log(
+    `[BoxFolders] File moved. New path: ${(data.path_collection?.entries || []).map((entry) => entry.name).join('/')}`
+  );
+  return data;
+}
+
+async function uploadGeneratedFile(caseFolderId, fileName, contents, mimeType, token) {
+  const blob = new Blob([contents], { type: mimeType });
+  const attributes = JSON.stringify({ name: fileName, parent: { id: caseFolderId } });
+
+  const form = new FormData();
+  form.append('attributes', attributes);
+  form.append('file', blob, fileName);
+
+  const res = await fetch(`${BOX_UPLOAD}/files/content`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}` },
+    body: form,
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(`Generated file upload failed (${res.status}): ${err.message || ''}`);
+  }
+
+  const data = await res.json();
+  console.log(`[BoxFolders] Generated file uploaded: ${fileName} -> id=${data.entries?.[0]?.id}`);
+  return data.entries?.[0]?.id || null;
+}
+
+async function uploadEnrichedSidecar(caseFolderId, caseId, enrichedPayload, token) {
+  const fileName = `${caseId}_enriched_metadata.json`;
+  const contents = JSON.stringify(enrichedPayload, null, 2);
+  return uploadGeneratedFile(caseFolderId, fileName, contents, 'application/json', token);
+}
+
+function buildReviewSummary(caseId, reportPayload, enrichment, reviewMetadata, folderPath) {
+  const address = reportPayload?.address || 'Address not available';
+  const district = reviewMetadata.district || 'Unknown';
+  const ward = reviewMetadata.ward || 'Unknown';
+  const zone = reviewMetadata.maintenanceZone || 'Unknown';
+  const severity = `${reviewMetadata.severityLevel || 'Unknown'} (${reviewMetadata.severityScore || 'n/a'}/100)`;
+  const road = reviewMetadata.trafficDetail || 'Road classification unavailable';
+  const weather = reviewMetadata.weatherDetail || 'Weather risk unavailable';
+  const weatherStatus = reviewMetadata.weatherStatus || reviewMetadata.weatherRiskLevel || 'Unknown';
+  const potholeSize = reviewMetadata.potholeSize || reviewMetadata.aiResult || reviewMetadata.aiPrediction || 'Unknown';
+  const aiConfidence = reviewMetadata.aiConfidence !== ''
+    ? `${reviewMetadata.aiConfidence}%`
+    : 'Unavailable';
+  const visualVerification = reviewMetadata.needsVisualVerification === 'true'
+    ? 'Yes - AI was not confident this is a pothole. Send image for Box-side visual verification.'
+    : 'No - base model confidence was sufficient.';
+  const duplicate = reviewMetadata.isDuplicate === 'true'
+    ? `Yes (${reviewMetadata.duplicateCount || 0} related case(s), linked: ${reviewMetadata.linkedCases || 'none'})`
+    : 'No';
+  const priorNotice = reviewMetadata.priorNoticeDetail || 'No prior notice detail';
+  const damage = reviewMetadata.damageDetail || 'Damage detail unavailable';
+  const reporterNote = reportPayload?.description || reportPayload?.notes || 'No additional citizen notes.';
+
+  return [
+    `POTHOLE REVIEW SUMMARY`,
+    ``,
+    `Case ID: ${caseId}`,
+    `Address: ${address}`,
+    `Ward: ${ward}`,
+    `District: ${district}`,
+    `Maintenance Zone: ${zone}`,
+    `Box Path: ${folderPath}`,
+    ``,
+    `SUPERVISOR REVIEW DATA`,
+    `Severity: ${severity}`,
+    `Pothole Size: ${potholeSize}`,
+    `Road Context: ${road}`,
+    `Road Classification: ${reviewMetadata.roadClassification || 'unknown'}`,
+    `Weather Risk: ${weather}`,
+    `Weather Status: ${weatherStatus}`,
+    `AI Confidence: ${aiConfidence}`,
+    `Needs Visual Verification: ${visualVerification}`,
+    `Duplicate Cluster: ${duplicate}`,
+    `Prior Notice: ${priorNotice}`,
+    `Damage Assessment: ${damage}`,
+    ``,
+    `REPORTER NOTES`,
+    `${reporterNote}`,
+    ``,
+    `REVIEW INSTRUCTION`,
+    `Check the photo, summary, severity, duplicate context, ward/district/zone, and decide the next operational step.`,
+    ``,
+    `Generated: ${reviewMetadata.enrichedAt || new Date().toISOString()}`,
+  ].join('\n');
+}
+
+async function uploadReviewSummary(caseFolderId, caseId, reviewSummary, token, options = {}) {
+  const fileName = options.needsVisualVerification
+    ? `${caseId}_review_summary_uncertain.txt`
+    : `${caseId}_review_summary.txt`;
+  return uploadGeneratedFile(caseFolderId, fileName, reviewSummary, 'text/plain', token);
+}
+
+function buildFolderWorkflowMetadata(reportPayload, enrichment, context) {
+  if (typeof window !== 'undefined' && window.BoxWorkflow?.buildEnrichedWorkflow) {
+    return window.BoxWorkflow.buildEnrichedWorkflow(reportPayload, enrichment, context);
+  }
+  if (boxWorkflowModule?.buildEnrichedWorkflow) {
+    return boxWorkflowModule.buildEnrichedWorkflow(reportPayload, enrichment, context);
+  }
+
+  return {
+    template: 'pothole_box_ops_v1',
+    currentStage: 'supervisor_review',
+    currentStageLabel: 'Supervisor Review',
+    status: 'Under Review',
+    queue: 'Supervisor Review',
+    nextAction: 'Supervisor approve the case and send it to crew routing',
+    priority: 'normal',
+    boxPath: context.folderPath || '',
+    lastUpdatedAt: enrichment?.enrichedAt || new Date().toISOString(),
+  };
+}
+
+function flattenFolderWorkflow(workflow) {
+  if (typeof window !== 'undefined' && window.BoxWorkflow?.flattenWorkflowForBox) {
+    return window.BoxWorkflow.flattenWorkflowForBox(workflow);
+  }
+  if (boxWorkflowModule?.flattenWorkflowForBox) {
+    return boxWorkflowModule.flattenWorkflowForBox(workflow);
+  }
+
+  return {
+    workflowTemplate: workflow.template || 'pothole_box_ops_v1',
+    workflowStage: workflow.currentStage || '',
+    workflowStageLabel: workflow.currentStageLabel || '',
+    workflowStatus: workflow.status || '',
+    workflowQueue: workflow.queue || '',
+    workflowNextAction: workflow.nextAction || '',
+    workflowPriority: workflow.priority || '',
+    workflowBoxPath: workflow.boxPath || '',
+    workflowLastUpdatedAt: workflow.lastUpdatedAt || '',
+  };
+}
+
+async function writeMetadataDocument(itemType, itemId, kvMap, token, config = {}, options = {}) {
+  const { stringifyValues = true } = options;
+  const normalized = normalizeTemplateConfig(config);
+  const scope = normalized.scope || 'global';
+  const templateKey = normalized.templateKey || 'properties';
+  const path = `/${itemType}/${itemId}/metadata/${scope}/${templateKey}`;
+  const payload = stringifyValues
+    ? Object.fromEntries(Object.entries(kvMap).map(([key, value]) => [key, String(value ?? '')]))
+    : { ...kvMap };
+  if (!Object.keys(payload).length) {
+    console.log(`[BoxFolders] No template-valid fields to write for ${itemType.slice(0, -1)} ${itemId} (${scope}/${templateKey})`);
+    return;
+  }
+
+  const { ok, status } = await boxRequest('POST', path, token, payload);
+  if (ok) {
+    console.log(`[BoxFolders] Metadata applied to ${itemType.slice(0, -1)} ${itemId} (${scope}/${templateKey})`);
+    return;
+  }
+
+  if (status === 409) {
+    const ops = Object.entries(payload).map(([key, value]) => ({ op: 'add', path: `/${key}`, value }));
+    const patchRes = await fetch(`${BOX_API}${path}`, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json-patch+json',
+      },
+      body: JSON.stringify(ops),
+    });
+    if (!patchRes.ok) {
+      const patchErr = await patchRes.json().catch(() => ({}));
+      throw new Error(`Metadata patch failed (${patchRes.status}): ${patchErr.message || ''}`.trim());
+    }
+    console.log(`[BoxFolders] Metadata patched (${patchRes.status}) for ${itemType.slice(0, -1)} ${itemId} (${scope}/${templateKey})`);
+    return;
+  }
+
+  throw new Error(`Metadata write failed (${status}) for ${itemType.slice(0, -1)} ${itemId} (${scope}/${templateKey})`);
+}
+
+async function applyMetadata(itemType, itemId, kvMap, token, options = {}) {
+  // Generic freeform properties: accepts any key, values as strings.
+  await writeMetadataDocument(itemType, itemId, kvMap, token, { scope: 'global', templateKey: 'properties' });
+
+  if (shouldApplyCustomTemplate(options.template)) {
+    const { scope, templateKey } = normalizeTemplateConfig(options.template);
+    const schema = await getTemplateSchema(scope, templateKey, token);
+    if (!schema) {
+      console.warn(`[BoxFolders] Schema unavailable for ${scope}/${templateKey}; skipping structured template.`);
+      return;
+    }
+    const projected = projectToTemplateSchema(kvMap, schema);
+    await writeMetadataDocument(itemType, itemId, projected, token, options.template, { stringifyValues: false });
+  }
+}
+
+async function applyFolderMetadata(folderId, kvMap, token, options = {}) {
+  return applyMetadata('folders', folderId, kvMap, token, options);
+}
+
+async function applyFileMetadata(fileId, kvMap, token, options = {}) {
+  return applyMetadata('files', fileId, kvMap, token, options);
+}
+
+function classifyRoadContext(detail = '') {
+  const normalized = String(detail || '').toLowerCase();
+  if (normalized.includes('critical infrastructure') || normalized.includes('high-traffic')) return 'critical';
+  if (normalized.includes('major arterial') || normalized.includes('high traffic')) return 'high';
+  if (normalized.includes('residential') || normalized.includes('low-traffic')) return 'low';
+  if (normalized.includes('moderate')) return 'medium';
+  return 'unknown';
+}
+
+function isUncertainPotholeCase(reportPayload = {}) {
+  const reviewStatus = String(reportPayload?.aiReviewStatus || '').toLowerCase().trim();
+  const aiResult = String(reportPayload?.aiResult || '').trim();
+  return reviewStatus === 'manual_review' && !aiResult;
+}
+
+function buildReviewMetadata(caseId, ward, district, folderPath, enrichment, workflowFields) {
+  const breakdown = enrichment?.severityBreakdown || {};
+  const priorNotice = breakdown.priorNotice || {};
+  const traffic = breakdown.traffic || {};
+  const damage = breakdown.damage || {};
+  const weather = breakdown.weather || {};
+  const duplicate = enrichment?.duplicate || {};
+  const districtData = enrichment?.district || {};
+  const reportPayload = enrichment?.report || {};
+  const aiReviewStatus = String(reportPayload.aiReviewStatus || '').trim();
+  const aiResult = String(reportPayload.aiResult || '').trim();
+  const aiPrediction = String(reportPayload.aiPrediction || '').trim();
+  const aiConfidenceRaw = reportPayload.aiConfidence;
+  const aiConfidence = Number.isFinite(Number(aiConfidenceRaw))
+    ? Math.round(Number(aiConfidenceRaw) * 100)
+    : '';
+  const needsVisualVerification = isUncertainPotholeCase(reportPayload);
+  const duplicateStatus = duplicate.isDuplicate ? 'duplicate' : 'new';
+  const weatherStatus = weather.riskLevel || (weather.detail ? 'available' : 'pending');
+  const potholeSize = aiResult || aiPrediction || String(reportPayload.potholeSize || '').trim();
+
+  return {
+    caseId,
+    submittedAt: reportPayload.submittedAt || '',
+    address: reportPayload.address || '',
+    areaLabel: reportPayload.areaLabel || '',
+    latitude: reportPayload.location?.lat ?? '',
+    longitude: reportPayload.location?.lng ?? '',
+    locationSource: reportPayload.location?.source || reportPayload.locationSource || '',
+    district: districtData.district || district || 'Unknown',
+    ward: districtData.ward || ward || 'Unknown',
+    maintenanceZone: districtData.maintenanceZone || 'Zone-X',
+    duplicateStatus,
+    severityScore: enrichment?.severityScore ?? '',
+    severityLevel: enrichment?.severityLevel || '',
+    priorNoticeScore: priorNotice.score ?? '',
+    priorNoticeDetail: priorNotice.detail || '',
+    trafficScore: traffic.score ?? '',
+    trafficDetail: traffic.detail || '',
+    roadClassification: classifyRoadContext(traffic.detail),
+    damageScore: damage.score ?? '',
+    damageDetail: damage.detail || '',
+    weatherScore: weather.score ?? '',
+    weatherDetail: weather.detail || '',
+    weatherRiskLevel: weather.riskLevel || '',
+    weatherStatus,
+    potholeSize,
+    aiResult,
+    aiPrediction,
+    aiReviewStatus,
+    aiReviewMessage: reportPayload.aiReviewMessage || '',
+    aiConfidence,
+    needsVisualVerification: needsVisualVerification ? 'true' : 'false',
+    duplicateCount: duplicate.duplicateCount ?? '',
+    duplicateBoost: duplicate.effectiveSeverityBoost ?? '',
+    isDuplicate: duplicate.isDuplicate ? 'true' : 'false',
+    linkedCases: (duplicate.linkedCaseIds || []).join(', '),
+    boxPath: folderPath,
+    enrichedAt: enrichment?.enrichedAt || '',
+    enrichedBy: 'ops-console-v2',
+    workflowStage: 'supervisor_review',
+    workflowStatus: 'Under Review',
+    workflowNextAction: 'Supervisor review pending',
+    workflowPriority: enrichment?.severityLevel === 'Critical' ? 'urgent'
+      : enrichment?.severityLevel === 'High' ? 'high'
+      : enrichment?.severityLevel === 'Medium' ? 'medium'
+      : 'normal',
+    ...workflowFields,
+  };
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.caseId
+ * @param {string} opts.ward
+ * @param {string} opts.district
+ * @param {string} [opts.photoFileId]
+ * @param {string} [opts.sidecarFileId]
+ * @param {object} opts.enrichment
+ * @param {object} opts.reportPayload
+ * @param {string} opts.rootFolderId
+ * @param {string} opts.token
+ * @param {(label: string, status: string) => void} [opts.onStep]
+ * @returns {Promise<{ folderPath: string, caseFolderId: string, potholesId: string, wardId: string, enrichedFileId: string|null, reviewSummaryFileId: string|null }>}
+ */
+async function organizeInBox(opts = {}) {
+  if (typeof window !== 'undefined') {
+    const response = await fetch('/api/box/organize-case', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(opts),
+    });
+
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+      throw new Error(payload?.error || `Box organize failed with HTTP ${response.status}`);
+    }
+
+    return payload?.result || null;
+  }
+
+  const {
+    caseId,
+    ward,
+    district,
+    photoFileId,
+    sidecarFileId,
+    enrichment,
+    reportPayload,
+    rootFolderId,
+    metadataTemplate = {},
+    token,
+    onStep = () => {},
+  } = opts;
+  const step = (label, status) => onStep(label, status);
+  const metadataOptions = { template: normalizeTemplateConfig(metadataTemplate) };
+
+  step('Creating Potholes/ root folder...', 'running');
+  const potholesId = await getOrCreateFolder(rootFolderId, 'Potholes', token);
+  step(`Potholes/ folder ready (id: ${potholesId})`, 'done');
+
+  const wardSlug = (ward || 'Ward-Unknown').replace(/\s+/g, '-');
+  step(`Creating ${wardSlug}/ subfolder...`, 'running');
+  const wardId = await getOrCreateFolder(potholesId, wardSlug, token);
+  step(`${wardSlug}/ ready (id: ${wardId})`, 'done');
+
+  const caseFolderName = `Case-${caseId}`;
+  step(`Creating case folder ${caseFolderName}/...`, 'running');
+  const caseFolderId = await getOrCreateFolder(wardId, caseFolderName, token);
+  step(`Case folder created (id: ${caseFolderId})`, 'done');
+
+  const folderPath = `Potholes/${wardSlug}/${caseFolderName}`;
+
+  if (photoFileId) {
+    step('Moving photo into case folder...', 'running');
+    await moveFile(photoFileId, caseFolderId, token).catch((error) => {
+      step(`Photo move warning: ${error.message}`, 'warn');
+    });
+    step('Photo moved OK', 'done');
+  }
+
+  if (sidecarFileId) {
+    step('Moving original metadata JSON...', 'running');
+    await moveFile(sidecarFileId, caseFolderId, token).catch((error) => {
+      step(`Sidecar move warning: ${error.message}`, 'warn');
+    });
+    step('Metadata JSON moved OK', 'done');
+  }
+
+  const workflow = buildFolderWorkflowMetadata(reportPayload, enrichment, { folderPath, rootFolderId });
+  const workflowFields = flattenFolderWorkflow(workflow);
+  const reviewMetadata = buildReviewMetadata(caseId, ward, district, folderPath, enrichment, workflowFields);
+  const reviewSummary = buildReviewSummary(caseId, reportPayload, enrichment, reviewMetadata, folderPath);
+  const needsVisualVerification = isUncertainPotholeCase(reportPayload);
+
+  step('Uploading enriched metadata JSON...', 'running');
+  const enrichedPayload = {
+    caseId,
+    submittedAt: reportPayload.submittedAt || '',
+    enrichedAt: enrichment.enrichedAt,
+    address: reportPayload.address || '',
+    areaLabel: reportPayload.areaLabel || '',
+    location: reportPayload.location || null,
+    locationSource: reportPayload.location?.source || reportPayload.locationSource || '',
+    severityScore: enrichment.severityScore,
+    severityLevel: enrichment.severityLevel,
+    district: enrichment.district?.district || district,
+    ward: enrichment.district?.ward || ward,
+    maintenanceZone: enrichment.district?.maintenanceZone || 'Zone-X',
+    duplicateStatus: enrichment.duplicate?.isDuplicate ? 'duplicate' : 'new',
+    isDuplicate: enrichment.duplicate?.isDuplicate,
+    duplicateCount: enrichment.duplicate?.duplicateCount ?? 0,
+    duplicateBoost: enrichment.duplicate?.effectiveSeverityBoost ?? 0,
+    linkedCases: enrichment.duplicate?.linkedCaseIds?.join(', ') || '',
+    weatherStatus: enrichment.severityBreakdown?.weather?.riskLevel || 'pending',
+    potholeSize: reportPayload.aiResult || reportPayload.aiPrediction || '',
+    aiResult: reportPayload.aiResult || '',
+    aiPrediction: reportPayload.aiPrediction || '',
+    aiReviewStatus: reportPayload.aiReviewStatus || '',
+    aiReviewMessage: reportPayload.aiReviewMessage || '',
+    priorNoticeScore: enrichment.severityBreakdown?.priorNotice?.score ?? '',
+    priorNoticeDetail: enrichment.severityBreakdown?.priorNotice?.detail || '',
+    trafficScore: enrichment.severityBreakdown?.traffic?.score ?? '',
+    trafficDetail: enrichment.severityBreakdown?.traffic?.detail || '',
+    roadClassification: classifyRoadContext(enrichment.severityBreakdown?.traffic?.detail),
+    damageScore: enrichment.severityBreakdown?.damage?.score ?? '',
+    damageDetail: enrichment.severityBreakdown?.damage?.detail || '',
+    weatherScore: enrichment.severityBreakdown?.weather?.score ?? '',
+    weatherDetail: enrichment.severityBreakdown?.weather?.detail || '',
+    weatherRiskLevel: enrichment.severityBreakdown?.weather?.riskLevel || '',
+    weatherRisk: enrichment.weather
+      ? `${enrichment.severityBreakdown?.weather?.riskLevel || 'unknown'} - ${enrichment.severityBreakdown?.weather?.detail}`
+      : 'Unavailable',
+    boxPath: folderPath,
+    workflow,
+    ...workflowFields,
+    severityBreakdown: enrichment.severityBreakdown,
+    report: reportPayload,
+  };
+  const enrichedFileId = await uploadEnrichedSidecar(caseFolderId, caseId, enrichedPayload, token).catch((error) => {
+    step(`Enriched sidecar warning: ${error.message}`, 'warn');
+    return null;
+  });
+  step('Enriched metadata JSON uploaded OK', 'done');
+
+  step('Uploading human-readable review summary...', 'running');
+  const reviewSummaryFileId = await uploadReviewSummary(caseFolderId, caseId, reviewSummary, token, {
+    needsVisualVerification,
+  }).catch((error) => {
+    step(`Review summary warning: ${error.message}`, 'warn');
+    return null;
+  });
+  step('Review summary uploaded OK', 'done');
+
+  step('Applying Box folder metadata template...', 'running');
+  await applyFolderMetadata(caseFolderId, reviewMetadata, token, metadataOptions).catch((error) => {
+    step(`Metadata warning: ${error.message}`, 'warn');
+  });
+  step('Box metadata template applied OK', 'done');
+
+  // NOTE: only the case FOLDER carries the structured potholeCase template (it's the
+  // canonical case record). Helper files get freeform properties only ({} = no custom
+  // template) so the App's metadata view counts 1 record per case, not 3.
+  if (enrichedFileId) {
+    step('Applying Box metadata to enriched review file...', 'running');
+    await applyFileMetadata(enrichedFileId, reviewMetadata, token, {}).catch((error) => {
+      step(`Review file metadata warning: ${error.message}`, 'warn');
+    });
+    step('Review file metadata applied OK', 'done');
+  }
+
+  if (reviewSummaryFileId) {
+    step('Applying Box metadata to review summary file...', 'running');
+    await applyFileMetadata(reviewSummaryFileId, reviewMetadata, token, {}).catch((error) => {
+      step(`Review summary metadata warning: ${error.message}`, 'warn');
+    });
+    step('Review summary metadata applied OK', 'done');
+  }
+
+  console.log(`[BoxFolders] organizeInBox complete -> ${folderPath}`);
+  return { folderPath, caseFolderId, wardId, potholesId, enrichedFileId, reviewSummaryFileId };
+}
+
+if (typeof window !== 'undefined') {
+  window.BoxFolders = { organizeInBox, getOrCreateFolder, moveFile, applyFolderMetadata };
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    organizeInBox,
+    getOrCreateFolder,
+    moveFile,
+    applyFolderMetadata,
+    applyFileMetadata,
+    getTemplateSchema,
+    projectToTemplateSchema,
+    coerceForField,
+    matchEnumOption,
+  };
+}

box-service.js

@@ -0,0 +1,1318 @@
+'use strict';
+
+const {
+  buildInitialWorkflow,
+  flattenWorkflowForBox,
+} = require('./box-workflow.js');
+const {
+  organizeInBox,
+  applyFolderMetadata,
+  getOrCreateFolder,
+} = require('./box-folders.js');
+
+const BOX_API_BASE = 'https://api.box.com/2.0';
+const BOX_UPLOAD_URL = 'https://upload.box.com/api/2.0/files/content';
+const BOX_OAUTH_TOKEN_URL = 'https://api.box.com/oauth2/token';
+const DEFAULT_GIS_BOUNDARY_URL = 'https://opendata.arcgis.com/datasets/philly-political-wards.geojson';
+const TOKEN_REFRESH_SKEW_MS = 2 * 60 * 1000;
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizeString(value) {
+  return String(value ?? '').trim();
+}
+
+// The citizen contact field is free-text ("email or phone" and may include a name),
+// so pull the email out of whatever string (or JSON blob) we're handed. Phone-only
+// values yield '' and never trigger a notify.
+function extractEmail(value) {
+  const match = String(value || '').match(/[^\s@<>"'(),;:]+@[^\s@<>"'(),;:]+\.[^\s@<>"'(),;:]+/);
+  return match ? match[0].replace(/[.,;:>)\]]+$/, '') : '';
+}
+
+// Friendly, citizen-facing copy for each status — the body of the Box status note.
+const CITIZEN_STATUS_COPY = {
+  'under review': 'Your report is being reviewed by our team. We will update you once a decision is made.',
+  submitted: 'Thanks — your report has been received and logged. We will review it shortly.',
+  assigned: 'Good news! Your report has been approved and a repair crew has been assigned. A work order has been created.',
+  'in progress': 'A crew is now actively working on the repair at the reported location.',
+  resolved: 'The pothole has been repaired and your case is now closed. Thank you for helping keep our roads safe.',
+  rejected: 'After review, this report was closed without a repair being dispatched. See the notes in your case for details.',
+};
+
+function buildCitizenStatusNote(caseId, statusLabel, caseRecord = null) {
+  const report = caseRecord?.report || {};
+  const key = String(statusLabel || '').trim().toLowerCase();
+  const message = CITIZEN_STATUS_COPY[key] || `Your report status has been updated to "${statusLabel}".`;
+  const lines = [
+    `Pothole Report — Status Update`,
+    ``,
+    `Case Reference: ${caseId}`,
+    `Current Status: ${statusLabel}`,
+    report.address ? `Location: ${report.address}` : '',
+    `Updated: ${new Date().toLocaleString()}`,
+    ``,
+    message,
+    ``,
+    `You can view live progress any time on the Track Your Report page using your Case Reference number.`,
+  ];
+  return lines.filter((line) => line !== '').join('\n');
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function parseRetryAfter(headers) {
+  const raw = headers?.get?.('retry-after');
+  if (!raw) return null;
+
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1000;
+  }
+
+  const when = Date.parse(raw);
+  if (Number.isFinite(when)) {
+    return Math.max(0, when - Date.now());
+  }
+
+  return null;
+}
+
+async function readErrorMessage(response) {
+  const contentType = response.headers.get('content-type') || '';
+  try {
+    if (contentType.includes('application/json')) {
+      const payload = await response.json();
+      return payload?.message || payload?.error || JSON.stringify(payload);
+    }
+
+    const text = await response.text();
+    return text || `HTTP ${response.status}`;
+  } catch {
+    return `HTTP ${response.status}`;
+  }
+}
+
+async function fetchWithRetry(url, options = {}, retryOptions = {}) {
+  const {
+    retries = 3,
+    baseDelayMs = 600,
+    maxDelayMs = 5000,
+    label = 'request',
+    retryStatuses = [408, 429, 500, 502, 503, 504],
+  } = retryOptions;
+
+  let lastError = null;
+
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      const response = await fetch(url, options);
+      if (!retryStatuses.includes(response.status) || attempt === retries) {
+        return response;
+      }
+
+      const retryDelay = parseRetryAfter(response.headers)
+        ?? Math.min(maxDelayMs, baseDelayMs * (2 ** attempt));
+      console.warn(`[retry] ${label} returned ${response.status}; retrying in ${retryDelay}ms`);
+      await delay(retryDelay);
+    } catch (error) {
+      lastError = error;
+      if (attempt === retries) throw error;
+
+      const retryDelay = Math.min(maxDelayMs, baseDelayMs * (2 ** attempt));
+      console.warn(`[retry] ${label} failed (${error.message}); retrying in ${retryDelay}ms`);
+      await delay(retryDelay);
+    }
+  }
+
+  throw lastError || new Error(`${label} failed.`);
+}
+
+function stripPhotoDataUrl(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stripPhotoDataUrl(item));
+  }
+
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  const clone = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (key === 'photoDataUrl') continue;
+    clone[key] = stripPhotoDataUrl(child);
+  }
+  return clone;
+}
+
+function isStoredTokenFresh(boxConfig) {
+  const accessToken = normalizeString(boxConfig.accessToken);
+  if (!accessToken) return false;
+
+  const expiresAt = normalizeString(boxConfig.accessTokenExpiresAt);
+  if (!expiresAt) return true;
+
+  const expiryTime = Date.parse(expiresAt);
+  if (!Number.isFinite(expiryTime)) return true;
+  return expiryTime - TOKEN_REFRESH_SKEW_MS > Date.now();
+}
+
+function hasBoxAuth(boxConfig = {}) {
+  const authMode = normalizeString(boxConfig.authMode || 'oauth_refresh').toLowerCase();
+  if (authMode === 'access_token') {
+    return !!normalizeString(boxConfig.accessToken);
+  }
+  if (authMode === 'client_credentials') {
+    return !!(
+      normalizeString(boxConfig.clientId) &&
+      normalizeString(boxConfig.clientSecret) &&
+      normalizeString(boxConfig.subjectType) &&
+      normalizeString(boxConfig.subjectId)
+    );
+  }
+  return !!(
+    normalizeString(boxConfig.accessToken) ||
+    (
+      normalizeString(boxConfig.refreshToken) &&
+      normalizeString(boxConfig.clientId) &&
+      normalizeString(boxConfig.clientSecret)
+    )
+  );
+}
+
+function computeBoxStatus(boxConfig = {}) {
+  const intakeFolderId = normalizeString(boxConfig.intakeFolderId);
+  const caseRootFolderId = normalizeString(boxConfig.caseRootFolderId || intakeFolderId);
+  const metadataScope = normalizeString(boxConfig.metadataScope);
+  const metadataTemplateKey = normalizeString(boxConfig.metadataTemplateKey);
+  return {
+    authMode: normalizeString(boxConfig.authMode || 'oauth_refresh').toLowerCase(),
+    configured: hasBoxAuth(boxConfig) && !!intakeFolderId,
+    hasAuth: hasBoxAuth(boxConfig),
+    intakeFolderId,
+    caseRootFolderId,
+    metadataScope,
+    metadataTemplateKey,
+    hasCustomMetadataTemplate: !!(metadataScope && metadataTemplateKey),
+    hasIntakeFolderId: !!intakeFolderId,
+    hasCaseRootFolderId: !!caseRootFolderId,
+    usingTemporaryAccessToken: normalizeString(boxConfig.authMode).toLowerCase() === 'access_token',
+  };
+}
+
+function buildBoxConfigError(boxConfig = {}) {
+  const authMode = normalizeString(boxConfig.authMode || 'oauth_refresh').toLowerCase();
+  if (authMode === 'client_credentials') {
+    return 'Box client credentials are incomplete. Save client ID, client secret, subject type, subject ID, and the intake folder in settings.html.';
+  }
+  if (authMode === 'access_token') {
+    return 'Box access token is missing. Open settings.html and save the Box integration first.';
+  }
+  return 'Box OAuth refresh credentials are incomplete. Save the client ID, client secret, refresh token, and intake folder in settings.html.';
+}
+
+function createBoxService({ configStore }) {
+  let tokenRefreshPromise = null;
+
+  async function readBoxConfig() {
+    const config = await configStore.readConfig();
+    const fileBox = config.box || {};
+    // Env-var overrides so the Box CCG connection survives on hosts that wipe disk
+    // (HuggingFace Spaces, Render, Railway, etc.). Set these as the host's secrets.
+    const E = process.env;
+    const env = {};
+    if (E.BOX_AUTH_MODE) env.authMode = E.BOX_AUTH_MODE;
+    if (E.BOX_CLIENT_ID) env.clientId = E.BOX_CLIENT_ID;
+    if (E.BOX_CLIENT_SECRET) env.clientSecret = E.BOX_CLIENT_SECRET;
+    if (E.BOX_SUBJECT_TYPE) env.subjectType = E.BOX_SUBJECT_TYPE;
+    if (E.BOX_SUBJECT_ID) env.subjectId = E.BOX_SUBJECT_ID;
+    if (E.BOX_INTAKE_FOLDER_ID) env.intakeFolderId = E.BOX_INTAKE_FOLDER_ID;
+    if (E.BOX_CASE_ROOT_FOLDER_ID) env.caseRootFolderId = E.BOX_CASE_ROOT_FOLDER_ID;
+    if (E.BOX_METADATA_SCOPE) env.metadataScope = E.BOX_METADATA_SCOPE;
+    if (E.BOX_METADATA_TEMPLATE_KEY) env.metadataTemplateKey = E.BOX_METADATA_TEMPLATE_KEY;
+    return { ...fileBox, ...env };
+  }
+
+  async function getClientConfig() {
+    const boxConfig = await readBoxConfig();
+    return configStore.sanitizeBoxConfigForClient(boxConfig);
+  }
+
+  async function getStatus() {
+    return computeBoxStatus(await readBoxConfig());
+  }
+
+  async function saveConfig(patch = {}, options = {}) {
+    const updated = await configStore.queueMutation((config) => ({
+      ...config,
+      box: configStore.mergeBoxConfig(config.box, patch, options),
+    }));
+
+    return {
+      config: configStore.sanitizeBoxConfigForClient(updated.box),
+      status: computeBoxStatus(updated.box),
+    };
+  }
+
+  async function resetConfig() {
+    return saveConfig({}, { reset: true });
+  }
+
+  async function persistTokens(tokenPatch = {}) {
+    const updated = await configStore.queueMutation((config) => ({
+      ...config,
+      box: configStore.mergeBoxConfig(config.box, tokenPatch),
+    }));
+    return updated.box;
+  }
+
+  async function requestBoxTokenViaRefresh(boxConfig, { persist = true } = {}) {
+    const refreshToken = normalizeString(boxConfig.refreshToken);
+    const clientId = normalizeString(boxConfig.clientId);
+    const clientSecret = normalizeString(boxConfig.clientSecret);
+    if (!refreshToken || !clientId || !clientSecret) {
+      throw new Error(buildBoxConfigError(boxConfig));
+    }
+
+    const body = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      client_id: clientId,
+      client_secret: clientSecret,
+    });
+
+    const response = await fetchWithRetry(BOX_OAUTH_TOKEN_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body,
+    }, { label: 'Box OAuth refresh token request' });
+
+    if (!response.ok) {
+      throw new Error(`Box token refresh failed (${response.status}): ${await readErrorMessage(response)}`);
+    }
+
+    const payload = await response.json();
+    const expiresAt = payload.expires_in
+      ? new Date(Date.now() + (Number(payload.expires_in) * 1000)).toISOString()
+      : '';
+
+    if (persist) {
+      await persistTokens({
+        accessToken: payload.access_token || '',
+        accessTokenExpiresAt: expiresAt,
+        refreshToken: payload.refresh_token || refreshToken,
+      });
+    }
+
+    return normalizeString(payload.access_token);
+  }
+
+  async function requestBoxTokenViaClientCredentials(boxConfig, { persist = true } = {}) {
+    const clientId = normalizeString(boxConfig.clientId);
+    const clientSecret = normalizeString(boxConfig.clientSecret);
+    const subjectType = normalizeString(boxConfig.subjectType);
+    const subjectId = normalizeString(boxConfig.subjectId);
+    if (!clientId || !clientSecret || !subjectType || !subjectId) {
+      throw new Error(buildBoxConfigError(boxConfig));
+    }
+
+    const body = new URLSearchParams({
+      grant_type: 'client_credentials',
+      client_id: clientId,
+      client_secret: clientSecret,
+      box_subject_type: subjectType,
+      box_subject_id: subjectId,
+    });
+
+    const response = await fetchWithRetry(BOX_OAUTH_TOKEN_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body,
+    }, { label: 'Box client credentials token request' });
+
+    if (!response.ok) {
+      throw new Error(`Box client credentials token request failed (${response.status}): ${await readErrorMessage(response)}`);
+    }
+
+    const payload = await response.json();
+    const expiresAt = payload.expires_in
+      ? new Date(Date.now() + (Number(payload.expires_in) * 1000)).toISOString()
+      : '';
+
+    if (persist) {
+      await persistTokens({
+        accessToken: payload.access_token || '',
+        accessTokenExpiresAt: expiresAt,
+      });
+    }
+
+    return normalizeString(payload.access_token);
+  }
+
+  async function resolveAccessToken(boxConfig = null, options = {}) {
+    const persist = options.persist !== false;
+    const effectiveConfig = boxConfig || await readBoxConfig();
+    const authMode = normalizeString(effectiveConfig.authMode || 'oauth_refresh').toLowerCase();
+    const canRefreshOAuth = !!(
+      normalizeString(effectiveConfig.refreshToken) &&
+      normalizeString(effectiveConfig.clientId) &&
+      normalizeString(effectiveConfig.clientSecret)
+    );
+
+    if (authMode === 'access_token') {
+      const token = normalizeString(effectiveConfig.accessToken);
+      if (!token) throw new Error(buildBoxConfigError(effectiveConfig));
+      return token;
+    }
+
+    if ((authMode === 'oauth_refresh' && canRefreshOAuth && normalizeString(effectiveConfig.accessTokenExpiresAt) && isStoredTokenFresh(effectiveConfig))
+      || (authMode === 'oauth_refresh' && !canRefreshOAuth && isStoredTokenFresh(effectiveConfig))
+      || (authMode === 'client_credentials' && normalizeString(effectiveConfig.accessTokenExpiresAt) && isStoredTokenFresh(effectiveConfig))) {
+      return normalizeString(effectiveConfig.accessToken);
+    }
+
+    if (tokenRefreshPromise) {
+      return tokenRefreshPromise;
+    }
+
+    tokenRefreshPromise = (async () => {
+      if (authMode === 'client_credentials') {
+        return requestBoxTokenViaClientCredentials(effectiveConfig, { persist });
+      }
+      return requestBoxTokenViaRefresh(effectiveConfig, { persist });
+    })();
+
+    try {
+      return await tokenRefreshPromise;
+    } finally {
+      tokenRefreshPromise = null;
+    }
+  }
+
+  async function boxRequestJson(boxPath, options = {}, overrideConfig = null) {
+    const boxConfig = overrideConfig || await readBoxConfig();
+    const accessToken = await resolveAccessToken(boxConfig, { persist: !overrideConfig });
+    const response = await fetchWithRetry(`${BOX_API_BASE}${boxPath}`, {
+      method: options.method || 'GET',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        ...(options.body ? { 'Content-Type': 'application/json' } : {}),
+        ...(options.headers || {}),
+      },
+      ...(options.body ? { body: JSON.stringify(options.body) } : {}),
+    }, { label: options.label || `Box ${options.method || 'GET'} ${boxPath}` });
+
+    if (!response.ok) {
+      throw new Error(`${options.label || 'Box request'} failed (${response.status}): ${await readErrorMessage(response)}`);
+    }
+
+    if (options.rawResponse) return response;
+    return response.json();
+  }
+
+  async function uploadBufferToBox({ folderId, fileName, buffer, contentType, boxConfig = null }) {
+    const effectiveConfig = boxConfig || await readBoxConfig();
+    const accessToken = await resolveAccessToken(effectiveConfig, { persist: !boxConfig });
+
+    const formData = new FormData();
+    formData.append('attributes', JSON.stringify({
+      name: fileName,
+      parent: { id: folderId },
+    }));
+    formData.append('file', new Blob([buffer], { type: contentType || 'application/octet-stream' }), fileName);
+
+    const response = await fetchWithRetry(BOX_UPLOAD_URL, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+      body: formData,
+    }, { label: `Box upload ${fileName}` });
+
+    if (!response.ok) {
+      if (response.status === 409) {
+        try {
+          const conflictData = await response.json();
+          const existingFileId = conflictData.context_info?.conflicts?.id
+            || conflictData.context_info?.conflicts?.[0]?.id;
+
+          if (existingFileId) {
+            console.log(`[BoxService] File "${fileName}" already exists (id: ${existingFileId}). Uploading new version.`);
+            const versionFormData = new FormData();
+            versionFormData.append('file', new Blob([buffer], { type: contentType || 'application/octet-stream' }), fileName);
+
+            const versionUrl = `https://upload.box.com/api/2.0/files/${existingFileId}/content`;
+            const versionResponse = await fetchWithRetry(versionUrl, {
+              method: 'POST',
+              headers: {
+                Authorization: `Bearer ${accessToken}`,
+              },
+              body: versionFormData,
+            }, { label: `Box upload new version ${fileName}` });
+
+            if (versionResponse.ok) {
+              const versionPayload = await versionResponse.json();
+              const entry = versionPayload.entries?.[0] || {};
+              return {
+                fileId: normalizeString(entry.id),
+                fileName: normalizeString(entry.name),
+                sharedLink: entry.shared_link?.url || null,
+              };
+            } else {
+              throw new Error(`Box upload new version failed (${versionResponse.status}): ${await readErrorMessage(versionResponse)}`);
+            }
+          }
+        } catch (conflictError) {
+          throw new Error(`Box upload conflict resolution failed: ${conflictError.message}`);
+        }
+      }
+      throw new Error(`Box upload failed (${response.status}): ${await readErrorMessage(response)}`);
+    }
+
+    const payload = await response.json();
+    const entry = payload.entries?.[0] || {};
+    return {
+      fileId: normalizeString(entry.id),
+      fileName: normalizeString(entry.name),
+      sharedLink: entry.shared_link?.url || null,
+    };
+  }
+
+  async function testConnection() {
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.hasAuth) {
+      return { ok: false, error: buildBoxConfigError(boxConfig) };
+    }
+    if (!status.hasIntakeFolderId) {
+      return { ok: false, error: 'Incoming intake folder ID is required.' };
+    }
+
+    try {
+      const intakeFolder = await boxRequestJson(`/folders/${encodeURIComponent(status.intakeFolderId)}`, {
+        label: 'Box intake folder lookup',
+      }, boxConfig);
+
+      let caseRootFolder = null;
+      if (status.caseRootFolderId && status.caseRootFolderId !== status.intakeFolderId) {
+        caseRootFolder = await boxRequestJson(`/folders/${encodeURIComponent(status.caseRootFolderId)}`, {
+          label: 'Box case root folder lookup',
+        }, boxConfig);
+      }
+
+      return {
+        ok: true,
+        folderName: intakeFolder.name || '(unknown)',
+        caseRootFolderName: caseRootFolder?.name || intakeFolder.name || '(unknown)',
+      };
+    } catch (error) {
+      return { ok: false, error: error.message };
+    }
+  }
+
+  // Create an open, downloadable shared link and return its direct download_url
+  // (what Box Doc Gen needs to fetch+embed the photo as an image tag).
+  async function createDirectSharedLink(fileId, boxConfig) {
+    try {
+      const token = await resolveAccessToken(boxConfig);
+      const response = await fetchWithRetry(`${BOX_API_BASE}/files/${encodeURIComponent(fileId)}?fields=shared_link`, {
+        method: 'PUT',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ shared_link: { access: 'open', permissions: { can_download: true } } }),
+      }, { label: `Box shared link ${fileId}` });
+      if (!response.ok) return '';
+      const data = await response.json();
+      return normalizeString(data.shared_link?.download_url || data.shared_link?.url || '');
+    } catch (error) {
+      console.warn('[box-service] createDirectSharedLink failed:', error.message);
+      return '';
+    }
+  }
+
+  async function uploadPhoto({ caseId, fileBuffer, contentType = 'image/jpeg' }) {
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) {
+      throw new Error(buildBoxConfigError(boxConfig));
+    }
+
+    // Photos go to a SEPARATE "Pothole Photos" folder — not the trigger folder —
+    // so the photo upload never fires WF1 (which would crash the Extract Agent on an image).
+    let photoFolderId = status.intakeFolderId;
+    try {
+      const token = await resolveAccessToken(boxConfig);
+      photoFolderId = await getOrCreateFolder(status.intakeFolderId, 'Pothole Photos', token);
+    } catch (e) {
+      console.warn('[box-service] could not create Pothole Photos folder, using intake:', e.message);
+    }
+    const upload = await uploadBufferToBox({
+      folderId: photoFolderId,
+      fileName: `${caseId}_photo.jpg`,
+      buffer: fileBuffer,
+      contentType,
+      boxConfig,
+    });
+    // photoUrl = direct shared link to the photo (used in the JSON, the mail, and docs).
+    let photoUrl = await createDirectSharedLink(upload.fileId, boxConfig);
+    if (!photoUrl) {
+      // Box can briefly reject a shared link right after upload — retry once.
+      await new Promise((r) => setTimeout(r, 700));
+      photoUrl = await createDirectSharedLink(upload.fileId, boxConfig);
+    }
+    return { ...upload, photoUrl };
+  }
+
+  function buildSubmissionSidecar(metadata = {}, intakeFolderId = '') {
+    const sanitized = stripPhotoDataUrl(metadata);
+    const caseId = normalizeString(sanitized.caseId);
+    const submittedAt = normalizeString(sanitized.submittedAt) || nowIso();
+    const workflow = buildInitialWorkflow(
+      { ...sanitized, caseId, submittedAt },
+      { folderId: intakeFolderId, folderName: 'Incoming Detections' }
+    );
+
+    return {
+      caseId,
+      submittedAt,
+      ...sanitized,
+      workflow,
+      ...flattenWorkflowForBox(workflow),
+    };
+  }
+
+  async function uploadSidecar({ caseId, metadata }) {
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) {
+      throw new Error(buildBoxConfigError(boxConfig));
+    }
+
+    const sidecarPayload = buildSubmissionSidecar({ ...metadata, caseId }, status.intakeFolderId);
+    const sidecarBuffer = Buffer.from(JSON.stringify(sidecarPayload, null, 2), 'utf8');
+    const result = await uploadBufferToBox({
+      folderId: status.intakeFolderId,
+      fileName: `${caseId}_metadata.json`,
+      buffer: sidecarBuffer,
+      contentType: 'application/json',
+      boxConfig,
+    });
+
+    return {
+      ...result,
+      sidecarPayload,
+    };
+  }
+
+  async function generateAndUploadAuditReport({ caseId, caseRecord }) {
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) {
+      throw new Error(buildBoxConfigError(boxConfig));
+    }
+
+    const report = caseRecord.report || {};
+    const folderId = report.boxFolderId || status.caseRootFolderId || status.intakeFolderId;
+
+    const mdContent = `# Pothole Case Audit Report - ${caseId}
+**Status:** Resolved
+**Generated on:** ${nowIso()}
+
+---
+
+## 1. Intake Information
+* **Case ID:** ${caseId}
+* **Submission Timestamp:** ${report.submittedAt || caseRecord.createdAt || 'N/A'}
+* **Location:** ${report.address || 'Unknown Address'}
+* **GPS Coordinates:** ${report.location?.lat ?? 'N/A'}, ${report.location?.lng ?? 'N/A'}
+* **Reporter Name:** ${report.anonymous ? 'Anonymous' : (report.reporterName || 'N/A')}
+* **Reporter Contact:** ${report.anonymous ? 'Anonymous' : (report.reporterContact || 'N/A')}
+* **Initial Description:** ${report.description || 'No description provided.'}
+* **AI Initial Classification:** ${report.aiResult || 'N/A'}
+
+---
+
+## 2. Enrichment & Severity Triage
+* **Enriched At:** ${report.enrichment?.enrichedAt || 'N/A'}
+* **Severity Score:** ${report.enrichment?.severityScore ?? 'N/A'} / 100
+* **Severity Level:** ${report.enrichment?.severityLevel || 'N/A'}
+* **Ward / District:** ${report.ward || 'N/A'} / ${report.district || 'N/A'}
+* **Maintenance Zone:** ${report.maintenanceZone || 'N/A'}
+* **Duplicate Status:** ${report.enrichment?.duplicate?.isDuplicate ? `Duplicate (${report.enrichment.duplicate.duplicateCount} prior reports)` : 'New Incident'}
+* **Weather Risk:** ${report.enrichment?.weather?.condition || 'N/A'} (Risk Level: ${report.enrichment?.weather?.riskLevel || 'N/A'})
+
+---
+
+## 3. Dispatch & Field Operations
+* **Assigned Crew / Lead:** ${report.crewName || report.assignedTo || 'Unassigned'}
+* **Work Status:** ${caseRecord.status || 'Resolved'}
+
+---
+
+## 4. Completion & Resolution Proof
+* **Completion Timestamp:** ${report.resolvedAt || 'N/A'}
+* **Resolution Notes:** ${report.resolutionNotes || 'No notes provided.'}
+* **Materials Used / Quantity:** ${report.materialsUsed || 'N/A'}
+* **Labor Hours Expended:** ${report.laborHours || 'N/A'}
+* **Crew Digital Signature:** ${report.crewSignature || 'N/A'}
+
+---
+
+## 5. Visual Evidence (Before vs. After)
+* **Before Photo (Intake):** ${report.photoFileId ? `[View Intake Photo](https://app.box.com/file/${report.photoFileId})` : 'N/A'}
+* **After Photo (Resolution):** ${report.afterPhotoFileId ? `[View Repair Photo](https://app.box.com/file/${report.afterPhotoFileId})` : 'N/A'}
+
+---
+
+## 6. System Logs & Audit Trail
+* **Created At:** ${caseRecord.createdAt || 'N/A'}
+* **Last Updated At:** ${caseRecord.updatedAt || 'N/A'}
+`;
+
+    const reportBuffer = Buffer.from(mdContent, 'utf8');
+    const fileName = `${caseId}_audit_report.md`;
+
+    return uploadBufferToBox({
+      folderId,
+      fileName,
+      buffer: reportBuffer,
+      contentType: 'text/markdown',
+      boxConfig,
+    });
+  }
+
+  // Locate the Box case folder for a case: prefer the stored boxFolderId, else
+  // search for the "Case-{caseId}" folder by name.
+  async function findCaseFolderId(caseId, caseRecord, boxConfig) {
+    const stored = caseRecord?.report?.boxFolderId || caseRecord?.boxFolderId;
+    if (stored) return String(stored);
+    try {
+      const params = new URLSearchParams({ query: `Case-${caseId}`, type: 'folder', limit: '10' });
+      const payload = await boxRequestJson(`/search?${params.toString()}`, {
+        label: `Box folder search ${caseId}`,
+      }, boxConfig);
+      const match = (payload.entries || []).find(
+        (e) => e.type === 'folder' && e.name === `Case-${caseId}`,
+      );
+      return match ? String(match.id) : null;
+    } catch (error) {
+      console.warn('[box-service] findCaseFolderId failed:', error.message);
+      return null;
+    }
+  }
+
+  // Flip the case folder's potholeCase metadata to status=resolved + resolvedAt,
+  // so the Box App "Resolved" view (which reads metadata) reflects the closeout.
+  async function markCaseResolvedInBox({ caseId, caseRecord, resolvedAt, resolvedBy } = {}) {
+    const id = String(caseId || caseRecord?.caseId || '').trim();
+    if (!id) return { skipped: true, reason: 'missing_case_id' };
+
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) return { skipped: true, reason: 'box_not_configured' };
+    if (!status.hasCustomMetadataTemplate) return { skipped: true, reason: 'no_metadata_template' };
+
+    const folderId = await findCaseFolderId(id, caseRecord, boxConfig);
+    if (!folderId) return { skipped: true, reason: 'case_folder_not_found' };
+
+    const token = await resolveAccessToken(boxConfig);
+    const template = { scope: boxConfig.metadataScope, templateKey: boxConfig.metadataTemplateKey };
+    const kv = {
+      status: 'resolved',
+      resolvedAt: resolvedAt || nowIso(),
+      supervisorWardEngineer: String(resolvedBy || '').trim(),
+    };
+    await applyFolderMetadata(folderId, kv, token, { template });
+    return { ok: true, folderId, applied: kv };
+  }
+
+  // Set any status on a case folder's metadata (Approve/Resolve/Reject/Reopen from the dashboard).
+  async function setCaseStatusInBox({ caseId, caseRecord, status, by } = {}) {
+    const id = String(caseId || caseRecord?.caseId || '').trim();
+    if (!id) return { skipped: true, reason: 'missing_case_id' };
+    const boxConfig = await readBoxConfig();
+    const st = computeBoxStatus(boxConfig);
+    if (!st.configured) return { skipped: true, reason: 'box_not_configured' };
+    if (!st.hasCustomMetadataTemplate) return { skipped: true, reason: 'no_metadata_template' };
+    const folderId = await findCaseFolderId(id, caseRecord, boxConfig);
+    if (!folderId) return { skipped: true, reason: 'case_folder_not_found' };
+    const token = await resolveAccessToken(boxConfig);
+    const template = { scope: boxConfig.metadataScope, templateKey: boxConfig.metadataTemplateKey };
+    const kv = { status };
+    if (by) kv.supervisorWardEngineer = String(by).trim();
+    if (String(status).toLowerCase() === 'resolved') kv.resolvedAt = nowIso();
+    await applyFolderMetadata(folderId, kv, token, { template });
+    return { ok: true, folderId, applied: kv };
+  }
+
+  async function uploadCaseArtifact({ caseId, caseRecord, fileName, content, contentType = 'text/plain; charset=utf-8' }) {
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) {
+      return {
+        skipped: true,
+        reason: 'box_not_configured',
+      };
+    }
+
+    const report = caseRecord?.report || {};
+    const folderId = report.boxFolderId || status.caseRootFolderId || status.intakeFolderId;
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(String(content ?? ''), 'utf8');
+
+    const upload = await uploadBufferToBox({
+      folderId,
+      fileName,
+      buffer,
+      contentType,
+      boxConfig,
+    });
+
+    return {
+      caseId: normalizeString(caseId || caseRecord?.caseId),
+      folderId,
+      ...upload,
+    };
+  }
+
+  // Ensure a single dedicated "Closeout Reports" folder under the case root. All
+  // before/after reports go here so a collaborator can watch ONE folder and get
+  // exactly one notification per closeout (no per-case-folder photo/audit noise).
+  const _closeoutReportsFolderCache = {};
+  const CLOSEOUT_REPORTS_FOLDER_NAME = 'Closeout Reports';
+  async function ensureCloseoutReportsFolder(boxConfig) {
+    const status = computeBoxStatus(boxConfig);
+    const rootId = normalizeString(status.caseRootFolderId || status.intakeFolderId);
+    if (!rootId) return '';
+    if (_closeoutReportsFolderCache[rootId]) return _closeoutReportsFolderCache[rootId];
+    const token = await resolveAccessToken(boxConfig);
+    const folderId = await getOrCreateFolder(rootId, CLOSEOUT_REPORTS_FOLDER_NAME, token);
+    _closeoutReportsFolderCache[rootId] = folderId;
+    return folderId;
+  }
+
+  // Upload a before/after report into the dedicated "Closeout Reports" folder.
+  async function uploadCloseoutReport({ caseId, fileName, content, contentType = 'application/octet-stream' }) {
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) return { skipped: true, reason: 'box_not_configured' };
+
+    const folderId = await ensureCloseoutReportsFolder(boxConfig);
+    if (!folderId) return { skipped: true, reason: 'no_root_folder' };
+
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(String(content ?? ''), 'utf8');
+    const upload = await uploadBufferToBox({ folderId, fileName, buffer, contentType, boxConfig });
+    return {
+      caseId: normalizeString(caseId),
+      folderId,
+      fileName,
+      ...upload,
+    };
+  }
+
+  // Upload a backend-generated document (.docx) to the case folder (or a dedicated
+  // "Pothole Documents" folder) — never the trigger root — and return a shared link.
+  async function uploadGeneratedDoc({ caseId, caseRecord, fileName, buffer }) {
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) throw new Error(buildBoxConfigError(boxConfig));
+
+    let folderId = await findCaseFolderId(caseId, caseRecord, boxConfig);
+    if (!folderId) {
+      const token = await resolveAccessToken(boxConfig);
+      folderId = await getOrCreateFolder(status.intakeFolderId, 'Pothole Documents', token);
+    }
+
+    const upload = await uploadBufferToBox({
+      folderId,
+      fileName,
+      buffer,
+      contentType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      boxConfig,
+    });
+
+    let sharedLink = '';
+    try { sharedLink = await createDirectSharedLink(upload.fileId, boxConfig); } catch (_) {}
+    if (!sharedLink) {
+      // Box can briefly reject a shared link right after upload — retry once.
+      await new Promise((r) => setTimeout(r, 700));
+      try { sharedLink = await createDirectSharedLink(upload.fileId, boxConfig); } catch (_) {}
+    }
+
+    return { caseId: normalizeString(caseId || caseRecord?.caseId), folderId, fileName, sharedLink, ...upload };
+  }
+
+  // Create a Box Sign request — emails the signer(s) a fillable doc to complete + sign (WF2 crew closeout).
+  async function createSignRequest({ sourceFileId, parentFolderId, signers, emailSubject, emailMessage } = {}) {
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) throw new Error(buildBoxConfigError(boxConfig));
+    if (!sourceFileId) throw new Error('sourceFileId is required for the sign request.');
+    if (!Array.isArray(signers) || !signers.length) throw new Error('At least one signer email is required.');
+    const token = await resolveAccessToken(boxConfig);
+    const body = {
+      source_files: [{ id: String(sourceFileId), type: 'file' }],
+      signers: signers.map((s, i) => ({ email: s.email, role: 'signer', order: i + 1 })),
+    };
+    if (parentFolderId) body.parent_folder = { id: String(parentFolderId), type: 'folder' };
+    if (emailSubject) body.email_subject = emailSubject;
+    if (emailMessage) body.email_message = emailMessage;
+    const response = await fetchWithRetry(`${BOX_API_BASE}/sign_requests`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    }, { label: 'Box Sign request' });
+    if (!response.ok) {
+      throw new Error(`Box Sign request failed (${response.status}): ${await readErrorMessage(response)}`);
+    }
+    const data = await response.json();
+    return {
+      ok: true,
+      signRequestId: data.id,
+      status: data.status,
+      signers: (data.signers || []).map((s) => s.email),
+      prepareUrl: data.prepare_url || '',
+    };
+  }
+
+  async function organizeCase(payload = {}) {
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) {
+      throw new Error(buildBoxConfigError(boxConfig));
+    }
+
+    const accessToken = await resolveAccessToken(boxConfig);
+    return organizeInBox({
+      caseId: normalizeString(payload.caseId),
+      ward: normalizeString(payload.ward),
+      district: normalizeString(payload.district),
+      photoFileId: normalizeString(payload.photoFileId),
+      sidecarFileId: normalizeString(payload.sidecarFileId),
+      enrichment: stripPhotoDataUrl(payload.enrichment || {}),
+      reportPayload: stripPhotoDataUrl(payload.reportPayload || {}),
+      rootFolderId: status.caseRootFolderId || status.intakeFolderId,
+      metadataTemplate: {
+        scope: normalizeString(boxConfig.metadataScope),
+        templateKey: normalizeString(boxConfig.metadataTemplateKey),
+      },
+      token: accessToken,
+    });
+  }
+
+  async function getFileContent(fileId) {
+    const boxConfig = await readBoxConfig();
+    const accessToken = await resolveAccessToken(boxConfig);
+    const response = await fetchWithRetry(`${BOX_API_BASE}/files/${encodeURIComponent(fileId)}/content`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    }, { label: `Box file content ${fileId}` });
+
+    if (!response.ok) {
+      throw new Error(`Box file preview failed (${response.status}): ${await readErrorMessage(response)}`);
+    }
+
+    return {
+      contentType: response.headers.get('content-type') || 'application/octet-stream',
+      contentLength: response.headers.get('content-length') || '',
+      body: Buffer.from(await response.arrayBuffer()),
+    };
+  }
+
+  // Look up a single case straight from Box and return its REAL status (read from
+  // the case folder's potholeCase metadata) so the citizen tracker reflects live
+  // supervisor decisions instead of being pinned to "Under Review".
+  async function searchCase(caseId) {
+    const id = String(caseId || '').trim();
+    if (!id) return null;
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) return null;
+
+    try {
+      const folderId = await findCaseFolderId(id, null, boxConfig);
+      if (!folderId) return null;
+
+      const scope = normalizeString(boxConfig.metadataScope) || 'enterprise';
+      const templateKey = normalizeString(boxConfig.metadataTemplateKey) || 'potholeCase';
+      let md = {};
+      try {
+        md = await boxRequestJson(
+          `/folders/${folderId}/metadata/${scope}/${templateKey}`,
+          { label: `Box case metadata ${id}` },
+          boxConfig,
+        );
+      } catch (_) {
+        // Folder exists but has no potholeCase metadata yet — treat as freshly submitted.
+        md = {};
+      }
+
+      const num = (v) => (v === undefined || v === null || v === '' ? null : Number(v));
+      const lat = num(md.latitude);
+      const lng = num(md.longitude);
+      return {
+        caseId: md.caseId || id,
+        status: normalizeString(md.status) || 'Under Review',
+        ts: md.submittedAt || Date.now(),
+        address: md.address || '',
+        ward: md.ward || '',
+        location: (lat != null && lng != null) ? { lat, lng } : null,
+        reporterContact: md.reporterContact || '',
+        potholeSize: md.potholeSize || '',
+        severityLevel: md.severityLevel || '',
+        severityScore: num(md.severityScore0100),
+        weatherRisk: md.weatherRisk || '',
+        district: md.district || '',
+        maintenanceZone: md.maintenanceZone || '',
+        resolvedAt: md.resolvedAt || '',
+        folderId,
+        source: 'box',
+      };
+    } catch (error) {
+      console.warn('[box-service] searchCase failed:', error.message);
+    }
+
+    return null;
+  }
+
+  // Pull the citizen's email out of the case folder's JSON sidecar(s). The submission
+  // sidecar ({caseId}_metadata.json) and enriched metadata carry reporterContact even
+  // when the Box metadata template field is empty — so read the JSON and extract it.
+  async function extractCitizenEmailFromCaseJson(caseId, folderId, boxConfig) {
+    try {
+      const items = await boxRequestJson(
+        `/folders/${folderId}/items?fields=id,name,type&limit=1000`,
+        { label: `case items ${caseId}` },
+        boxConfig,
+      );
+      const score = (name) => {
+        if (/_metadata\.json$/i.test(name) && !/enriched/i.test(name)) return 3; // submission sidecar
+        if (/enriched.*\.json$/i.test(name)) return 2;
+        return 1;
+      };
+      const jsonFiles = (items.entries || [])
+        .filter((e) => e.type === 'file' && /\.json$/i.test(e.name))
+        .sort((a, b) => score(b.name) - score(a.name));
+
+      for (const file of jsonFiles) {
+        let text;
+        try {
+          const content = await getFileContent(file.id);
+          text = content.body.toString('utf8');
+        } catch (_) { continue; }
+
+        let email = '';
+        try {
+          const obj = JSON.parse(text);
+          email = extractEmail(
+            obj.reporterContact || obj.reporterEmail || obj.contact || obj.email
+            || obj.report?.reporterContact || obj.report?.reporterEmail || obj.report?.contact || '',
+          );
+        } catch (_) { /* not valid JSON — fall through to a raw scan */ }
+        if (!email) email = extractEmail(text);
+        if (email) return email;
+      }
+    } catch (error) {
+      console.warn('[box-service] extractCitizenEmailFromCaseJson failed:', error.message);
+    }
+    return '';
+  }
+
+  // Read the submission sidecar JSON for a case and return the reporter + location data
+  // captured at submission (reporterName, reporterContact, anonymous, address, location).
+  // The metadata template often doesn't carry the reporter name, but the sidecar does.
+  async function getCaseSubmissionData(caseId) {
+    const id = String(caseId || '').trim();
+    if (!id) return null;
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) return null;
+    const folderId = await findCaseFolderId(id, null, boxConfig);
+    if (!folderId) return null;
+    try {
+      const items = await boxRequestJson(
+        `/folders/${folderId}/items?fields=id,name,type&limit=1000`,
+        { label: `case items ${id}` },
+        boxConfig,
+      );
+      const score = (name) => (/_metadata\.json$/i.test(name) && !/enriched/i.test(name)) ? 3 : (/enriched.*\.json$/i.test(name) ? 2 : 1);
+      const jsonFiles = (items.entries || [])
+        .filter((e) => e.type === 'file' && /\.json$/i.test(e.name))
+        .sort((a, b) => score(b.name) - score(a.name));
+      for (const file of jsonFiles) {
+        let obj;
+        try { obj = JSON.parse((await getFileContent(file.id)).body.toString('utf8')); } catch (_) { continue; }
+        const r = (obj && obj.report) ? obj.report : (obj || {});
+        return {
+          reporterName: normalizeString(r.reporterName || obj.reporterName),
+          reporterContact: normalizeString(r.reporterContact || obj.reporterContact || r.reporterEmail || obj.reporterEmail),
+          anonymous: (r.anonymous !== undefined ? r.anonymous : obj.anonymous),
+          address: normalizeString(r.address || obj.address),
+          location: r.location || obj.location || null,
+          ward: normalizeString(r.ward || obj.ward),
+        };
+      }
+    } catch (error) {
+      console.warn('[box-service] getCaseSubmissionData failed:', error.message);
+    }
+    return null;
+  }
+
+  // Notify a citizen of a status change *via Box*: drop a short status-update note
+  // into the case folder, then collaborate the citizen (viewer) on that note with
+  // notify=true so Box emails them a link — the same Box-native "share the summary"
+  // path used elsewhere, so no separate email service is needed.
+  async function notifyCitizenViaBox({ caseId, caseRecord, status, citizenEmail, summary } = {}) {
+    const id = String(caseId || caseRecord?.caseId || '').trim();
+    if (!id) return { skipped: true, reason: 'missing_case_id' };
+
+    const boxConfig = await readBoxConfig();
+    const st = computeBoxStatus(boxConfig);
+    if (!st.configured) return { skipped: true, reason: 'box_not_configured' };
+
+    const folderId = await findCaseFolderId(id, caseRecord, boxConfig);
+    if (!folderId) return { skipped: true, reason: 'case_folder_not_found' };
+
+    // Extract the citizen email: first from whatever contact string we were handed,
+    // then from the case-folder JSON sidecar (reporterContact lives in the JSON even
+    // when the Box metadata field is blank).
+    let email = extractEmail(citizenEmail || caseRecord?.report?.reporterContact || '');
+    if (!email) email = await extractCitizenEmailFromCaseJson(id, folderId, boxConfig);
+    if (!email) return { skipped: true, reason: 'no_citizen_email' };
+
+    const statusLabel = String(status || caseRecord?.status || 'Updated').trim();
+    const stamp = nowIso().slice(0, 10);
+    const fileName = `Status Update - Case ${id} - ${statusLabel} (${stamp}).txt`;
+    const body = summary || buildCitizenStatusNote(id, statusLabel, caseRecord);
+
+    let upload;
+    try {
+      upload = await uploadBufferToBox({
+        folderId,
+        fileName,
+        buffer: Buffer.from(body, 'utf8'),
+        contentType: 'text/plain; charset=utf-8',
+        boxConfig,
+      });
+    } catch (error) {
+      return { ok: false, emailed: false, reason: 'note_upload_failed', error: error.message };
+    }
+
+    let sharedLink = '';
+    try { sharedLink = await createDirectSharedLink(upload.fileId, boxConfig); } catch (_) {}
+
+    // Add the citizen as a viewer on the note file -> Box emails them the invite/link.
+    try {
+      const collab = await boxRequestJson('/collaborations?notify=true', {
+        method: 'POST',
+        label: `Box notify citizen ${id}`,
+        body: {
+          item: { type: 'file', id: String(upload.fileId) },
+          accessible_by: { type: 'user', login: email },
+          role: 'viewer',
+        },
+      }, boxConfig);
+      return {
+        ok: true,
+        emailed: true,
+        to: email,
+        status: statusLabel,
+        fileId: upload.fileId,
+        sharedLink,
+        collaborationId: collab?.id || '',
+      };
+    } catch (error) {
+      // The note is in Box even if the collaboration email failed (e.g. external
+      // collaboration disabled) — surface that without failing the status update.
+      return { ok: false, emailed: false, to: email, fileId: upload.fileId, sharedLink, error: error.message };
+    }
+  }
+
+  // Give a supervisor/ops recipient access to closeout reports *via Box*, as a ONE-TIME
+  // invite. Rather than collaborating them on each case's report file (which would email
+  // a fresh "invite to collaborate" for every case), we collaborate them once on the
+  // stable case-root folder. Box emails that single invite the first time; on every
+  // later case they are already a collaborator, so no repeat invite is sent — they just
+  // have standing access, and we hand back a direct shared link to the new report.
+  async function notifyCloseoutViaBox({ caseId, caseRecord, reportFileId, recipientEmail } = {}) {
+    const id = String(caseId || caseRecord?.caseId || '').trim();
+    if (!id) return { skipped: true, reason: 'missing_case_id' };
+
+    const email = extractEmail(recipientEmail || '');
+    if (!email) return { skipped: true, reason: 'no_recipient_email' };
+
+    const boxConfig = await readBoxConfig();
+    const st = computeBoxStatus(boxConfig);
+    if (!st.configured) return { skipped: true, reason: 'box_not_configured' };
+
+    // Direct shared link to THIS case's report (handy for the response/UI regardless).
+    const fileId = String(reportFileId || '').trim();
+    let sharedLink = '';
+    if (fileId) { try { sharedLink = await createDirectSharedLink(fileId, boxConfig); } catch (_) {} }
+
+    // Grant standing access to the dedicated "Closeout Reports" folder so the recipient
+    // can watch exactly that one folder for new before/after reports.
+    const rootFolderId = await ensureCloseoutReportsFolder(boxConfig);
+    if (!rootFolderId) {
+      // No stable workspace folder to grant standing access — the report link still works.
+      return { ok: !!sharedLink, emailed: false, to: email, fileId, sharedLink, reason: 'no_root_folder' };
+    }
+
+    // One-time collaboration on the Closeout Reports folder -> Box invites them once.
+    try {
+      const collab = await boxRequestJson('/collaborations?notify=true', {
+        method: 'POST',
+        label: `Box closeout access ${email}`,
+        body: {
+          item: { type: 'folder', id: rootFolderId },
+          accessible_by: { type: 'user', login: email },
+          role: 'viewer',
+        },
+      }, boxConfig);
+      return { ok: true, emailed: true, firstTime: true, to: email, fileId, sharedLink, folderId: rootFolderId, collaborationId: collab?.id || '' };
+    } catch (error) {
+      // Already a collaborator -> they were invited once before. No new invite is sent;
+      // they keep standing access to every report. This is the intended steady state.
+      if (/already a collaborator/i.test(error.message || '')) {
+        return { ok: true, emailed: false, alreadyHasAccess: true, to: email, fileId, sharedLink, folderId: rootFolderId };
+      }
+      // The report is saved in Box even if the collaboration failed (e.g. external
+      // collaboration disabled) — surface that without failing the closeout.
+      return { ok: false, emailed: false, to: email, fileId, sharedLink, error: error.message };
+    }
+  }
+
+  // List all cases straight from Box: walk Potholes/{ward}/Case-* and read each
+  // case folder's potholeCase metadata (incl. severity breakdown) + its photo file id.
+  async function listBoxCases() {
+    const boxConfig = await readBoxConfig();
+    const status = computeBoxStatus(boxConfig);
+    if (!status.configured) return [];
+    const rootId = status.caseRootFolderId || status.intakeFolderId;
+
+    const listItems = (folderId, label) =>
+      boxRequestJson(`/folders/${folderId}/items?fields=id,name,type&limit=1000`, { label }, boxConfig)
+        .then((r) => r.entries || [])
+        .catch(() => []);
+
+    const rootItems = await listItems(rootId, 'list root');
+    const potholes = rootItems.find((e) => e.type === 'folder' && e.name === 'Potholes');
+    if (!potholes) return [];
+
+    const wards = (await listItems(potholes.id, 'list wards')).filter((e) => e.type === 'folder');
+
+    // List all wards' case folders in parallel, then fetch each case's metadata +
+    // items through a bounded worker pool. Sequential calls took 100s+ with ~40
+    // cases, which times out behind hosted proxies (e.g. HuggingFace Spaces).
+    const wardFolderLists = await Promise.all(
+      wards.map(async (ward) => (await listItems(ward.id, 'list cases'))
+        .filter((e) => e.type === 'folder')
+        .map((cf) => ({ ward, cf })))
+    );
+    const caseFolders = wardFolderLists.flat();
+
+    const num = (v) => (v === undefined || v === null || v === '' ? null : Number(v));
+    const cases = [];
+    let cursor = 0;
+    const CONCURRENCY = 8;
+    async function worker() {
+      while (cursor < caseFolders.length) {
+        const { ward, cf } = caseFolders[cursor++];
+        let md;
+        let items;
+        try {
+          [md, items] = await Promise.all([
+            boxRequestJson(`/folders/${cf.id}/metadata/enterprise/potholeCase`, { label: 'case md' }, boxConfig),
+            listItems(cf.id, 'case items'),
+          ]);
+        } catch (e) { continue; } // no potholeCase metadata -> not a case record
+        const photo = items.find((e) => e.type === 'file' && /\.(jpe?g|png)$/i.test(e.name));
+        cases.push({
+          folderId: cf.id, folderName: cf.name, ward: ward.name,
+          photoFileId: photo ? photo.id : '',
+          caseId: md.caseId || cf.name.replace(/^Case-/, ''),
+          status: md.status || '', severityLevel: md.severityLevel || '',
+          potholeSize: md.potholeSize || '',
+          district: md.district || '', maintenanceZone: md.maintenanceZone || '',
+          aiReviewStatus: md.aiReviewStatus || '', reporterContact: md.reporterContact || '',
+          severityScore: num(md.severityScore0100), address: md.address || '',
+          submittedAt: md.submittedAt || '', resolvedAt: md.resolvedAt || '',
+          duplicateStatus: (md.duplicateStatus || '').trim(),
+          duplicateCount: num(md.duplicateCount) || 0, linkedCaseIds: md.linkedCaseIds || '',
+          latitude: num(md.latitude), longitude: num(md.longitude),
+          weatherRisk: md.weatherRisk || '', aiSummary: md.aiSummary || '',
+          breakdown: {
+            priorNotice: { score: num(md.priorNoticeScore), max: 30, detail: md.priorNoticeDetail || '' },
+            traffic: { score: num(md.trafficScore), max: 25, detail: md.trafficDetail || '' },
+            damage: { score: num(md.damageScore), max: 25, detail: md.damageDetail || '' },
+            weather: { score: num(md.weatherScore), max: 10, detail: md.weatherDetail || '' },
+          },
+        });
+      }
+    }
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, caseFolders.length || 1) }, worker));
+    return cases;
+  }
+
+  async function fetchOfficialBoundaries() {
+    const response = await fetchWithRetry(DEFAULT_GIS_BOUNDARY_URL, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/geo+json, application/json;q=0.9, */*;q=0.1',
+      },
+    }, { label: 'Official GIS boundary fetch' });
+
+    if (!response.ok) {
+      throw new Error(`Official GIS boundary fetch failed (${response.status}): ${await readErrorMessage(response)}`);
+    }
+
+    return {
+      contentType: response.headers.get('content-type') || 'application/json; charset=utf-8',
+      body: await response.text(),
+    };
+  }
+
+  return {
+    DEFAULT_GIS_BOUNDARY_URL,
+    fetchWithRetry,
+    stripPhotoDataUrl,
+    getClientConfig,
+    getStatus,
+    saveConfig,
+    resetConfig,
+    testConnection,
+    uploadPhoto,
+    uploadSidecar,
+    generateAndUploadAuditReport,
+    markCaseResolvedInBox,
+    setCaseStatusInBox,
+    notifyCitizenViaBox,
+    notifyCloseoutViaBox,
+    getCaseSubmissionData,
+    uploadCloseoutReport,
+    createSignRequest,
+    uploadCaseArtifact,
+    uploadGeneratedDoc,
+    organizeCase,
+    getFileContent,
+    searchCase,
+    listBoxCases,
+    fetchOfficialBoundaries,
+    buildSubmissionSidecar,
+  };
+}
+
+module.exports = {
+  createBoxService,
+  fetchWithRetry,
+  stripPhotoDataUrl,
+  DEFAULT_GIS_BOUNDARY_URL,
+};

box-upload.js

@@ -0,0 +1,200 @@
+'use strict';
+
+const API_PREFIX = '/api';
+
+let __boxStatusCache = null;
+let __boxStatusFetchedAt = 0;
+
+function stripPhotoDataUrl(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stripPhotoDataUrl(item));
+  }
+
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  const clone = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (key === 'photoDataUrl') continue;
+    clone[key] = stripPhotoDataUrl(child);
+  }
+  return clone;
+}
+
+async function parseApiResponse(response) {
+  let payload = null;
+  try {
+    payload = await response.json();
+  } catch {
+    payload = null;
+  }
+
+  if (!response.ok) {
+    throw new Error(payload?.error || payload?.message || `Request failed with HTTP ${response.status}`);
+  }
+
+  return payload;
+}
+
+async function apiRequest(path, options = {}) {
+  const response = await fetch(`${API_PREFIX}${path}`, {
+    method: options.method || 'GET',
+    headers: {
+      ...(options.rawBody ? {} : { 'Content-Type': 'application/json' }),
+      ...(options.headers || {}),
+    },
+    ...(options.body !== undefined ? { body: options.body } : {}),
+  });
+
+  return parseApiResponse(response);
+}
+
+async function getBoxStatus(options = {}) {
+  const { force = false } = options;
+  if (__boxStatusCache && !force && (Date.now() - __boxStatusFetchedAt) < 10000) {
+    return __boxStatusCache;
+  }
+
+  const payload = await apiRequest('/box/status', { method: 'GET' });
+  __boxStatusCache = payload?.status || {};
+  __boxStatusFetchedAt = Date.now();
+  return __boxStatusCache;
+}
+
+function buildMissingConfigMessage(status = {}) {
+  if (!status.hasAuth) {
+    return 'Box authentication is not configured on the backend. Open settings.html and save the Box integration first.';
+  }
+  if (!status.hasIntakeFolderId) {
+    return 'Incoming intake folder ID is not configured. Open settings.html and save the Box integration first.';
+  }
+  return 'Box is not configured on the backend. Open settings.html and save the Box integration first.';
+}
+
+async function testBoxConnection() {
+  try {
+    const payload = await apiRequest('/box/test-connection', {
+      method: 'POST',
+      body: JSON.stringify({}),
+    });
+    __boxStatusCache = null;
+    __boxStatusFetchedAt = 0;
+    return payload;
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+}
+
+async function uploadPhoto(file, caseId) {
+  if (!file) {
+    throw new Error('Photo file is required.');
+  }
+
+  const status = await getBoxStatus();
+  if (!status.configured) {
+    throw new Error(buildMissingConfigMessage(status));
+  }
+
+  const payload = await apiRequest(`/box/upload-photo?caseId=${encodeURIComponent(caseId)}`, {
+    method: 'POST',
+    rawBody: true,
+    headers: {
+      'Content-Type': file.type || 'application/octet-stream',
+    },
+    body: file,
+  });
+
+  return {
+    fileId: payload.fileId || '',
+    sharedLink: payload.sharedLink || null,
+    photoUrl: payload.photoUrl || '',
+  };
+}
+
+async function uploadSidecar(metadata, caseId) {
+  const status = await getBoxStatus();
+  if (!status.configured) {
+    throw new Error(buildMissingConfigMessage(status));
+  }
+
+  const payload = await apiRequest('/box/upload-sidecar', {
+    method: 'POST',
+    body: JSON.stringify({
+      caseId,
+      metadata: stripPhotoDataUrl(metadata || {}),
+    }),
+  });
+
+  return {
+    fileId: payload.fileId || '',
+    sidecarPayload: payload.sidecarPayload || null,
+  };
+}
+
+async function submitToBox(photoFile, metadata) {
+  const providedCaseId = metadata && typeof metadata.caseId === 'string'
+    ? metadata.caseId.trim()
+    : '';
+  const randomSuffix = Math.random()
+    .toString(36)
+    .toUpperCase()
+    .replace(/[^A-Z]/g, '')
+    .slice(0, 4)
+    .padEnd(4, 'X');
+
+  const caseId = providedCaseId || `PHX-${Date.now()}-${randomSuffix}`;
+  const submittedAt = metadata?.submittedAt || new Date().toISOString();
+  const sanitizedMetadata = stripPhotoDataUrl({
+    ...metadata,
+    caseId,
+    submittedAt,
+  });
+
+  try {
+    const photoResult = await uploadPhoto(photoFile, caseId);
+    const sidecarResult = await uploadSidecar({
+      ...sanitizedMetadata,
+      photoFileId: photoResult.fileId || '',
+      photoUrl: photoResult.photoUrl || '',
+    }, caseId);
+
+    return {
+      success: true,
+      caseId,
+      photoFileId: photoResult.fileId || '',
+      sidecarFileId: sidecarResult.fileId || '',
+      sidecarPayload: sidecarResult.sidecarPayload || sanitizedMetadata,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    getBoxStatus,
+    testBoxConnection,
+    uploadPhoto,
+    uploadSidecar,
+    submitToBox,
+    stripPhotoDataUrl,
+  };
+}
+
+if (typeof window !== 'undefined') {
+  window.getBoxStatus = getBoxStatus;
+  window.testBoxConnection = testBoxConnection;
+  window.submitToBox = submitToBox;
+  window.BoxUpload = {
+    getBoxStatus,
+    testBoxConnection,
+    uploadPhoto,
+    uploadSidecar,
+    submitToBox,
+    stripPhotoDataUrl,
+  };
+}

box-workflow.js

@@ -0,0 +1,189 @@
+'use strict';
+
+const BOX_WORKFLOW_TEMPLATE = 'pothole_box_ops_v1';
+
+function workflowPriorityFromSeverity(severity) {
+  const normalized = String(severity || '').toLowerCase();
+  if (normalized === 'critical') return 'urgent';
+  if (normalized === 'high' || normalized === 'large') return 'high';
+  if (normalized === 'medium') return 'medium';
+  return 'normal';
+}
+
+function buildInitialWorkflow(report = {}, boxConfig = {}) {
+  const aiStatus = String(report.aiReviewStatus || '').toLowerCase();
+  const aiResult = String(report.aiResult || report.aiPrediction || '').toLowerCase();
+  const needsManualReview = aiStatus.includes('manual') || aiStatus.includes('face');
+  const needsAttention = aiStatus === 'invalid_image';
+
+  return {
+    template: BOX_WORKFLOW_TEMPLATE,
+    currentStage: 'incoming_detection',
+    currentStageLabel: 'Incoming Detection',
+    status: needsManualReview || needsAttention ? 'Under Review' : 'Submitted',
+    queue: needsManualReview || needsAttention ? 'Manual Review' : 'Ops Intake',
+    nextAction: needsAttention
+      ? 'Supervisor must validate the upload before enrichment'
+      : needsManualReview
+        ? 'Supervisor must verify the image before enrichment'
+        : 'Run enrichment and create the case folder',
+    priority: workflowPriorityFromSeverity(aiResult),
+    needsManualReview,
+    triggerFolderId: boxConfig.folderId || '',
+    triggerFolderName: boxConfig.folderName || 'Incoming Detections',
+    submittedAt: report.submittedAt || new Date().toISOString(),
+    lastUpdatedAt: report.submittedAt || new Date().toISOString(),
+  };
+}
+
+function buildEnrichedWorkflow(report = {}, enrichment = {}, context = {}) {
+  const severityLevel = String(enrichment.severityLevel || '').trim() || 'Pending';
+  const duplicateCount = enrichment.duplicate?.duplicateCount || 0;
+  const linkedCases = Array.isArray(enrichment.duplicate?.linkedCaseIds)
+    ? enrichment.duplicate.linkedCaseIds
+    : [];
+  const urgent = severityLevel.toLowerCase() === 'critical';
+
+  return {
+    template: BOX_WORKFLOW_TEMPLATE,
+    currentStage: 'supervisor_review',
+    currentStageLabel: 'Supervisor Review',
+    status: 'Under Review',
+    queue: urgent ? 'Emergency Dispatch' : 'Supervisor Review',
+    nextAction: urgent
+      ? 'Assign an emergency crew and dispatch immediately'
+      : duplicateCount > 0
+        ? 'Review duplicate cluster and confirm routing'
+        : 'Supervisor approve the case and send it to crew routing',
+    priority: workflowPriorityFromSeverity(severityLevel),
+    needsManualReview: String(report.aiReviewStatus || '').toLowerCase().includes('manual'),
+    severityLevel,
+    severityScore: enrichment.severityScore ?? '',
+    duplicateCount,
+    linkedCases: linkedCases.join(', '),
+    district: enrichment.district?.district || report.district || '',
+    ward: enrichment.district?.ward || report.ward || '',
+    maintenanceZone: enrichment.district?.maintenanceZone || report.maintenanceZone || '',
+    boxPath: context.folderPath || '',
+    rootFolderId: context.rootFolderId || '',
+    lastUpdatedAt: enrichment.enrichedAt || new Date().toISOString(),
+  };
+}
+
+function flattenWorkflowForBox(workflow = {}) {
+  return {
+    workflowTemplate: workflow.template || BOX_WORKFLOW_TEMPLATE,
+    workflowStage: workflow.currentStage || '',
+    workflowStageLabel: workflow.currentStageLabel || '',
+    workflowStatus: workflow.status || '',
+    workflowQueue: workflow.queue || '',
+    workflowNextAction: workflow.nextAction || '',
+    workflowPriority: workflow.priority || '',
+    workflowNeedsManualReview: workflow.needsManualReview ? 'true' : 'false',
+    workflowSeverityLevel: workflow.severityLevel || '',
+    workflowSeverityScore: workflow.severityScore ?? '',
+    workflowDuplicateCount: workflow.duplicateCount ?? '',
+    workflowLinkedCases: workflow.linkedCases || '',
+    workflowWard: workflow.ward || '',
+    workflowDistrict: workflow.district || '',
+    workflowMaintenanceZone: workflow.maintenanceZone || '',
+    workflowBoxPath: workflow.boxPath || '',
+    workflowLastUpdatedAt: workflow.lastUpdatedAt || '',
+    workflowTriggerFolderId: workflow.triggerFolderId || workflow.rootFolderId || '',
+    workflowTriggerFolderName: workflow.triggerFolderName || '',
+  };
+}
+
+function getWorkflowInputFields() {
+  return [
+    { key: 'caseId', source: 'Citizen upload', purpose: 'Primary record key used across Box, ops review, and tracking.' },
+    { key: 'submittedAt', source: 'Citizen upload', purpose: 'Timestamp for intake SLAs and queue sorting.' },
+    { key: 'photoFileId', source: 'Box upload', purpose: 'Original pothole photo file to preview or move into the case folder.' },
+    { key: 'sidecarFileId', source: 'Box upload', purpose: 'Original JSON sidecar used as the workflow payload.' },
+    { key: 'address', source: 'Citizen upload', purpose: 'Road location shown to reviewers and crew dispatch.' },
+    { key: 'areaLabel', source: 'Reverse geocode', purpose: 'Human-friendly locality label shown before official ward matching succeeds.' },
+    { key: 'ward', source: 'GIS or reverse geocode', purpose: 'Routes the case into the correct Box subfolder and maintenance area.' },
+    { key: 'district', source: 'GIS mapping', purpose: 'Maps the case to the review or engineering district.' },
+    { key: 'maintenanceZone', source: 'GIS mapping', purpose: 'Directs dispatch to the correct crew zone.' },
+    { key: 'duplicateStatus', source: 'Ops enrichment', purpose: 'Simple duplicate/new label used by external workflow decisions.' },
+    { key: 'weatherStatus', source: 'Ops enrichment', purpose: 'Weather risk status stored with the case for triage and reporting.' },
+    { key: 'potholeSize', source: 'Citizen upload AI', purpose: 'Human-readable pothole size used before and after enrichment.' },
+    { key: 'aiReviewStatus', source: 'Citizen upload AI', purpose: 'Determines whether the case should enter manual review first.' },
+    { key: 'aiResult', source: 'Citizen upload AI', purpose: 'Initial pothole size signal before enrichment recalculates severity.' },
+    { key: 'severityScore', source: 'Ops enrichment', purpose: 'Numeric urgency score for routing, triage, and reporting.' },
+    { key: 'severityLevel', source: 'Ops enrichment', purpose: 'Human-readable priority label for Box tasks and dashboards.' },
+    { key: 'isDuplicate', source: 'Ops enrichment', purpose: 'Flags repeat reports so teams can merge or escalate clusters.' },
+    { key: 'workflowStage', source: 'Workflow metadata', purpose: 'Stable machine field for the current lifecycle stage.' },
+    { key: 'workflowNextAction', source: 'Workflow metadata', purpose: 'Plain-language instruction shown to the next owner.' },
+  ];
+}
+
+function getWorkflowStages() {
+  return [
+    {
+      id: 'incoming_detection',
+      title: '1. Citizen intake and Box file storage',
+      use: 'The portal uploads the photo and JSON sidecar to Box, then upserts the same case into the backend queue.',
+      input: 'Folder ID from Settings, caseId, submittedAt, address, location, aiReviewStatus, potholeSize',
+    },
+    {
+      id: 'supervisor_review',
+      title: '2. Database-owned enrichment and review',
+      use: 'Ops Review and backend services calculate GIS, duplicates, weather, and severity, then save enriched artifacts back into Box.',
+      input: 'photoFileId, sidecarFileId, ward, district, maintenanceZone, duplicateStatus, weatherStatus, severityScore',
+    },
+    {
+      id: 'crew_dispatch',
+      title: '3. Database dispatch with Box-backed artifacts',
+      use: 'The backend records supervisor approval, authority routing, and crew dispatch while Box stores the generated notices and assignment files.',
+      input: 'severityLevel, duplicateStatus, workflowPriority, workflowStatus, maintenanceZone, assignedCrew',
+    },
+    {
+      id: 'resolved',
+      title: '4. Database closeout with Box proof storage',
+      use: 'Crew forms, after photos, reports, and audit outputs are saved by the backend and written back into Box for shared recordkeeping.',
+      input: 'resolvedAt, resolutionNotes, afterPhotoFileId, laborHours, materialsUsed, workflowStatus',
+    },
+  ];
+}
+
+function buildWorkflowBlueprint(boxConfig = {}) {
+  return {
+    template: BOX_WORKFLOW_TEMPLATE,
+    triggerFolderId: boxConfig.folderId || '',
+    triggerFolderName: boxConfig.folderName || 'Incoming Detections',
+    automationUses: [
+      'Box as the content repository for intake, case folders, proof files, and reports',
+      'JSON sidecar payload uploaded by the citizen portal',
+      'Enriched metadata and readable summaries written back after backend processing',
+      'Backend and app screens own approvals, dispatch, authority notifications, and closeout',
+    ],
+    inputFields: getWorkflowInputFields(),
+    stages: getWorkflowStages(),
+    metadataKeys: Object.keys(flattenWorkflowForBox({})),
+  };
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    BOX_WORKFLOW_TEMPLATE,
+    buildInitialWorkflow,
+    buildEnrichedWorkflow,
+    flattenWorkflowForBox,
+    getWorkflowInputFields,
+    getWorkflowStages,
+    buildWorkflowBlueprint,
+  };
+}
+
+if (typeof window !== 'undefined') {
+  window.BoxWorkflow = {
+    BOX_WORKFLOW_TEMPLATE,
+    buildInitialWorkflow,
+    buildEnrichedWorkflow,
+    flattenWorkflowForBox,
+    getWorkflowInputFields,
+    getWorkflowStages,
+    buildWorkflowBlueprint,
+  };
+}

case-report.html

@@ -0,0 +1,303 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Before / After Report — PotholeIQ</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&display=swap" rel="stylesheet" />
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    :root {
+      --ink-950:#0c1626; --ink-700:#344256; --ink-500:#64748b; --ink-400:#8a97a8;
+      --border:#e2e8f0; --brand:#0061d5; --mint:#0e9f6e; --amber:#b45309; --red:#dc2626;
+    }
+    body { font-family:'Inter',system-ui,sans-serif; background:#eef2f7; color:var(--ink-950); -webkit-font-smoothing:antialiased; }
+
+    /* Toolbar (not printed) */
+    .toolbar {
+      position:sticky; top:0; z-index:10;
+      display:flex; align-items:center; justify-content:space-between; gap:16px;
+      padding:14px 24px; background:rgba(12,22,38,0.96); color:#fff;
+      backdrop-filter:blur(10px);
+    }
+    .toolbar__brand { display:flex; align-items:center; gap:10px; font-weight:800; font-size:14px; }
+    .toolbar__brand-icon { width:30px; height:30px; border-radius:8px; background:linear-gradient(135deg,#0b66d6,#083f8c); display:flex; align-items:center; justify-content:center; font-weight:900; }
+    .toolbar__actions { display:flex; gap:10px; }
+    .tbtn { padding:9px 16px; border-radius:9px; font:inherit; font-size:13px; font-weight:700; cursor:pointer; border:1px solid rgba(255,255,255,0.18); background:rgba(255,255,255,0.08); color:#fff; text-decoration:none; transition:background .15s ease; }
+    .tbtn:hover { background:rgba(255,255,255,0.16); }
+    .tbtn.primary { background:linear-gradient(135deg,#1273e6,#0a55b4); border-color:transparent; }
+
+    .page { max-width:920px; margin:24px auto 60px; padding:0 20px; }
+    .sheet { background:#fff; border:1px solid var(--border); border-radius:16px; box-shadow:0 20px 50px rgba(15,23,42,0.10); overflow:hidden; }
+
+    .rhead { padding:28px 32px; border-bottom:1px solid var(--border); background:linear-gradient(135deg,#f8fbff,#eef4fb); }
+    .rhead__eyebrow { font-size:11px; font-weight:800; letter-spacing:0.12em; text-transform:uppercase; color:var(--brand); margin-bottom:6px; }
+    .rhead__title { font-size:26px; font-weight:900; letter-spacing:-0.03em; line-height:1.1; }
+    .rhead__meta { margin-top:8px; font-size:13px; color:var(--ink-500); display:flex; flex-wrap:wrap; gap:14px; }
+    .rhead__meta strong { color:var(--ink-700); }
+    .status-pill { display:inline-flex; align-items:center; gap:6px; padding:5px 12px; border-radius:999px; font-size:12px; font-weight:800; }
+
+    .summary { display:grid; grid-template-columns:repeat(4,1fr); gap:1px; background:var(--border); border-bottom:1px solid var(--border); }
+    .summary__cell { background:#fff; padding:16px 20px; }
+    .summary__label { font-size:10px; font-weight:800; text-transform:uppercase; letter-spacing:0.08em; color:var(--ink-400); margin-bottom:5px; }
+    .summary__value { font-size:20px; font-weight:800; letter-spacing:-0.02em; }
+
+    .section { padding:24px 32px; border-bottom:1px solid var(--border); }
+    .section__label { font-size:11px; font-weight:800; text-transform:uppercase; letter-spacing:0.1em; color:var(--ink-400); margin-bottom:14px; display:flex; align-items:center; gap:10px; }
+    .section__label::after { content:''; flex:1; height:1px; background:var(--border); }
+
+    .ba-grid { display:grid; grid-template-columns:1fr 1fr; gap:18px; }
+    .ba-col__tag { font-size:11px; font-weight:800; text-transform:uppercase; letter-spacing:0.08em; margin-bottom:8px; }
+    .ba-col__tag.before { color:var(--amber); }
+    .ba-col__tag.after { color:var(--mint); }
+    .ba-photo { width:100%; height:230px; border-radius:12px; object-fit:cover; border:1px solid var(--border); background:#f1f5f9; display:block; }
+    .ba-photo__ph { width:100%; height:230px; border-radius:12px; border:1.5px dashed var(--border); background:linear-gradient(135deg,#f8fafc,#eef2f7); display:flex; align-items:center; justify-content:center; text-align:center; color:var(--ink-400); font-size:12px; font-weight:600; padding:16px; }
+
+    .kv { display:grid; grid-template-columns:1fr 1fr; gap:10px; }
+    .kv__item { border:1px solid var(--border); border-radius:11px; padding:11px 13px; background:#fbfdff; }
+    .kv__label { font-size:10px; font-weight:800; text-transform:uppercase; letter-spacing:0.07em; color:var(--ink-400); margin-bottom:4px; }
+    .kv__value { font-size:13px; font-weight:700; color:var(--ink-950); line-height:1.4; word-break:break-word; }
+
+    .cost-table { width:100%; border-collapse:collapse; font-size:13px; }
+    .cost-table td { padding:11px 14px; border-bottom:1px solid var(--border); }
+    .cost-table td:last-child { text-align:right; font-variant-numeric:tabular-nums; font-weight:700; white-space:nowrap; }
+    .cost-table tr.total td { border-top:2px solid var(--ink-950); border-bottom:none; font-weight:900; font-size:15px; }
+    .cost-table tr.total td:last-child { color:var(--amber); }
+    .cost-table .muted { color:var(--ink-500); font-weight:600; }
+    .variance-pos { color:var(--red); } .variance-neg { color:var(--mint); }
+
+    .notes { font-size:13.5px; line-height:1.7; color:var(--ink-700); background:#f8fafc; border:1px solid var(--border); border-radius:12px; padding:16px 18px; white-space:pre-wrap; }
+
+    .sign { display:grid; grid-template-columns:1fr 1fr; gap:24px; padding:24px 32px; }
+    .sign__line { border-top:1.5px solid var(--ink-700); padding-top:8px; font-size:12px; color:var(--ink-500); }
+    .sign__line strong { display:block; color:var(--ink-950); font-size:13px; }
+
+    .rfoot { padding:16px 32px; font-size:11px; color:var(--ink-400); text-align:center; }
+    .loading { padding:80px 20px; text-align:center; color:var(--ink-500); font-weight:600; }
+
+    @media (max-width:680px){ .summary{grid-template-columns:1fr 1fr;} .ba-grid,.kv,.sign{grid-template-columns:1fr;} }
+
+    @media print {
+      body { background:#fff; }
+      .toolbar { display:none; }
+      .page { margin:0; max-width:none; padding:0; }
+      .sheet { border:none; border-radius:0; box-shadow:none; }
+      .section, .summary, .rhead { break-inside:avoid; }
+    }
+  </style>
+</head>
+<body>
+  <div class="toolbar">
+    <div class="toolbar__brand"><div class="toolbar__brand-icon">P</div> PotholeIQ</div>
+    <div class="toolbar__actions">
+      <a class="tbtn" href="ops-review.html">← Ops Review</a>
+      <button class="tbtn primary" onclick="window.print()">Print / Save PDF</button>
+    </div>
+  </div>
+
+  <div class="page">
+    <div id="report-root" class="sheet">
+      <div class="loading" id="loading">Loading case report…</div>
+    </div>
+  </div>
+
+  <script src="backend-api.js?v=20260604b"></script>
+  <script>
+    'use strict';
+    const CASES_KEY = 'submitted_cases';
+    const params = new URLSearchParams(location.search);
+    const caseId = (params.get('case') || '').trim();
+
+    const num = (v) => { const n = Number(v); return Number.isFinite(n) ? n : 0; };
+    const money = (v) => `$${num(v).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+    const esc = (s) => String(s == null ? '' : s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+    const dash = (v) => (v === 0 || v) ? v : '—';
+
+    function estimateRepairCost(size, severityScore, address) {
+      const base = { Small: 140, Medium: 260, Large: 480 }[size] || 0;
+      if (!base) return { base: 0, severity: 0, traffic: 0, total: 0 };
+      const score = Math.max(0, Math.min(100, num(severityScore) || 50));
+      const severity = Math.round((score / 100) * 80);
+      const traffic = /(broad st|market st|chestnut st|ridge ave|main road|ring road|highway|expressway)/i.test(String(address || '')) ? Math.round(base * 0.12) : 0;
+      return { base, severity, traffic, total: Math.round((base + severity + traffic) / 5) * 5 };
+    }
+    function priorityFromScore(score) {
+      const s = num(score);
+      if (s >= 80) return { label:'Critical', desc:'Immediate (<12h)', color:'#dc2626', bg:'#fef2f2' };
+      if (s >= 60) return { label:'High', desc:'Next 24h', color:'#b45309', bg:'#fff8e6' };
+      if (s >= 40) return { label:'Medium', desc:'Next 72h', color:'#0061d5', bg:'#eff4ff' };
+      return { label:'Low', desc:'Scheduled (<7d)', color:'#0e9f6e', bg:'#e7f8f1' };
+    }
+    const STATUS_TONE = {
+      Resolved:{c:'#0e9f6e',bg:'#e7f8f1'}, 'In Progress':{c:'#b45309',bg:'#fff3e6'},
+      Assigned:{c:'#6d28d9',bg:'#f1edfc'}, 'Under Review':{c:'#b45309',bg:'#fff8e6'},
+      Submitted:{c:'#0061d5',bg:'#eaf1fb'}, Rejected:{c:'#9b1c1c',bg:'#fdf0ef'}
+    };
+
+    async function loadCase() {
+      if (window.PotholeBackend?.getCase) {
+        try { const c = await window.PotholeBackend.getCase(caseId); if (c) return c; } catch (e) { /* fall through */ }
+      }
+      try {
+        const local = JSON.parse(localStorage.getItem(CASES_KEY) || '[]');
+        return local.find((x) => x && x.caseId === caseId) || null;
+      } catch { return null; }
+    }
+
+    function photoCell(fileId, fileName, fallbackLabel) {
+      const id = `ph-${Math.random().toString(36).slice(2)}`;
+      if (fileId) {
+        // Try to load from Box; fall back to placeholder on error.
+        setTimeout(() => {
+          fetch(`/api/box/files/${encodeURIComponent(fileId)}/content`)
+            .then((r) => { if (!r.ok) throw new Error(); return r.blob(); })
+            .then((b) => { const el = document.getElementById(id); if (el) el.outerHTML = `<img class="ba-photo" src="${URL.createObjectURL(b)}" alt="${esc(fileName||'')}" />`; })
+            .catch(() => {});
+        }, 0);
+        return `<div class="ba-photo__ph" id="${id}">Loading image…<br>${esc(fileName || fileId)}</div>`;
+      }
+      return `<div class="ba-photo__ph">${esc(fallbackLabel)}${fileName ? `<br>${esc(fileName)}` : ''}</div>`;
+    }
+
+    function kv(label, value) {
+      return `<div class="kv__item"><div class="kv__label">${esc(label)}</div><div class="kv__value">${esc(dash(value))}</div></div>`;
+    }
+
+    function render(rec) {
+      const r = rec.report || {};
+      const sup = r.supervisor || {};
+      const enr = r.enrichment || {};
+      const bd = enr.severityBreakdown || {};
+      const loc = r.location || {};
+
+      const size = sup.size || r.potholeSize || r.aiResult || r.aiPrediction || 'Unknown';
+      const sevScore = enr.severityScore ?? r.workflowSeverityScore ?? '';
+      const sevLevel = enr.severityLevel || r.workflowSeverityLevel || 'Pending';
+      const pr = priorityFromScore(sevScore);
+
+      const laborHours = num(r.laborHours), laborRate = num(r.laborRate), materialsCost = num(r.materialsCost);
+      const laborCost = laborHours * laborRate;
+      const actualTotal = num(r.totalCost) || (laborCost + materialsCost);
+      const est = estimateRepairCost(size, sevScore, r.address);
+      const variance = est.total ? actualTotal - est.total : 0;
+      const variancePct = est.total ? ((variance / est.total) * 100).toFixed(1) + '%' : 'N/A';
+
+      const st = STATUS_TONE[rec.status] || STATUS_TONE.Submitted;
+      const roadScore = typeof r.aiRoadScore === 'number' ? (r.aiRoadScore * 100).toFixed(1) + '%' : '—';
+      const dup = enr.duplicate?.isDuplicate ? `Duplicate (${enr.duplicate.duplicateCount || 0} linked)` : 'New case';
+      const supDecision = sup.verified ? (sup.isPothole ? 'Approved' : 'Rejected') : 'Pending';
+
+      document.getElementById('report-root').innerHTML = `
+        <div class="rhead">
+          <div class="rhead__eyebrow">Pothole Repair · Before / After Report</div>
+          <div class="rhead__title">${esc(rec.caseId)}</div>
+          <div class="rhead__meta">
+            <span><strong>Status:</strong> <span class="status-pill" style="background:${st.bg};color:${st.c};">${esc(rec.status || 'Resolved')}</span></span>
+            <span><strong>Address:</strong> ${esc(r.address || 'Unknown')}</span>
+            <span><strong>Generated:</strong> ${new Date().toLocaleString()}</span>
+          </div>
+        </div>
+
+        <div class="summary">
+          <div class="summary__cell"><div class="summary__label">AI Size</div><div class="summary__value">${esc(size)}</div></div>
+          <div class="summary__cell"><div class="summary__label">Severity</div><div class="summary__value">${dash(sevScore)}${sevScore!=='' ? '/100' : ''}</div></div>
+          <div class="summary__cell"><div class="summary__label">Priority</div><div class="summary__value" style="color:${pr.color}">${pr.label}</div></div>
+          <div class="summary__cell"><div class="summary__label">Total Spend</div><div class="summary__value" style="color:var(--amber)">${money(actualTotal)}</div></div>
+        </div>
+
+        <div class="section">
+          <div class="section__label">Before &amp; After</div>
+          <div class="ba-grid">
+            <div>
+              <div class="ba-col__tag before">● Before — Reported Condition</div>
+              ${photoCell(r.photoFileId, r.photoFileName, 'Reported photo not archived')}
+            </div>
+            <div>
+              <div class="ba-col__tag after">● After — Completed Repair</div>
+              ${photoCell(r.afterPhotoFileId, r.afterPhotoFileName, 'After-photo not uploaded')}
+            </div>
+          </div>
+        </div>
+
+        <div class="section">
+          <div class="section__label">Report &amp; Location</div>
+          <div class="kv">
+            ${kv('Submitted', r.submittedAt ? new Date(r.submittedAt).toLocaleString() : (rec.ts ? new Date(rec.ts).toLocaleString() : '—'))}
+            ${kv('Reporter', r.anonymous ? 'Anonymous' : (r.reporterName || '—'))}
+            ${kv('Ward / District', `${r.ward || 'Pending'} / ${r.district || 'Pending'}`)}
+            ${kv('Maintenance Zone', r.maintenanceZone || 'Pending')}
+            ${kv('Coordinates', (loc.lat != null && loc.lng != null) ? `${Number(loc.lat).toFixed(5)}, ${Number(loc.lng).toFixed(5)}` : '—')}
+            ${kv('Reporter Contact', r.anonymous ? '—' : (r.reporterContact || '—'))}
+          </div>
+        </div>
+
+        <div class="section">
+          <div class="section__label">AI Assessment &amp; Severity (Before)</div>
+          <div class="kv">
+            ${kv('AI Classification', r.aiResult || r.aiPrediction || 'Unknown')}
+            ${kv('Road-likeness', roadScore)}
+            ${kv('Severity Level', `${sevLevel}${sevScore!=='' ? ` (${sevScore}/100)` : ''}`)}
+            ${kv('Resolution Priority', `${pr.label} — ${pr.desc}`)}
+            ${kv('311 Prior Notice', `${dash(bd.priorNotice?.score)} / ${bd.priorNotice?.max ?? 30}`)}
+            ${kv('Traffic & Road Class', `${dash(bd.traffic?.score)} / ${bd.traffic?.max ?? 25}`)}
+            ${kv('Damage Type', `${dash(bd.damage?.score)} / ${bd.damage?.max ?? 25}`)}
+            ${kv('Weather Risk', `${dash(bd.weather?.score)} / ${bd.weather?.max ?? 10}`)}
+            ${kv('Duplicate Status', dup)}
+            ${kv('Supervisor Decision', `${supDecision} · ${sup.by || '—'}`)}
+          </div>
+        </div>
+
+        <div class="section">
+          <div class="section__label">Repair Completion (After)</div>
+          <div class="kv">
+            ${kv('Resolved At', r.resolvedAt ? new Date(r.resolvedAt).toLocaleString() : 'Pending')}
+            ${kv('Crew', r.crewName || r.dispatchPlan?.crewName || r.assignedTo || 'Pending')}
+            ${kv('Repair Method', r.repairMethod || 'Not specified')}
+            ${kv('Materials Used', r.materialsUsed || 'Not specified')}
+            ${kv('Labor Hours', r.laborHours ? `${r.laborHours} h` : 'Not specified')}
+            ${kv('Crew Signature', r.crewSignature || 'Not provided')}
+          </div>
+        </div>
+
+        <div class="section">
+          <div class="section__label">Cost — Estimated vs. Actual</div>
+          <table class="cost-table">
+            <tr><td>Estimated repair cost <span class="muted">(base ${money(est.base)} + severity ${money(est.severity)} + traffic ${money(est.traffic)})</span></td><td>${money(est.total)}</td></tr>
+            <tr><td>Actual labor <span class="muted">(${laborHours} h × ${money(laborRate)}/hr)</span></td><td>${money(laborCost)}</td></tr>
+            <tr><td>Actual materials</td><td>${money(materialsCost)}</td></tr>
+            <tr class="total"><td>Actual total spend</td><td>${money(actualTotal)}</td></tr>
+            <tr><td>Variance vs. estimate</td><td class="${variance > 0 ? 'variance-pos' : 'variance-neg'}">${variance >= 0 ? '+' : ''}${money(variance)} (${variancePct})</td></tr>
+          </table>
+        </div>
+
+        <div class="section">
+          <div class="section__label">Field Notes</div>
+          <div class="notes">${esc(r.resolutionNotes || 'No field notes provided.')}</div>
+        </div>
+
+        <div class="sign">
+          <div class="sign__line"><strong>${esc(r.crewSignature || '________________')}</strong>Crew Lead — Repair Completed</div>
+          <div class="sign__line"><strong>${esc(sup.by || '________________')}</strong>Supervisor — Verified &amp; Closed</div>
+        </div>
+
+        <div class="rfoot">PotholeIQ · Department of Streets — Road Maintenance Division · Case ${esc(rec.caseId)}</div>
+      `;
+    }
+
+    (async function init() {
+      if (!caseId) {
+        document.getElementById('report-root').innerHTML = '<div class="loading">No case specified. Open this report from a case (e.g. case-report.html?case=POT-…).</div>';
+        return;
+      }
+      const rec = await loadCase();
+      if (!rec) {
+        document.getElementById('report-root').innerHTML = `<div class="loading">Case “${esc(caseId)}” was not found.</div>`;
+        return;
+      }
+      render(rec);
+    })();
+  </script>
+</body>
+</html>

command-center.html

@@ -0,0 +1,391 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>PotholeIQ — Command Center</title>
+<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
+<style>
+  :root{
+    /* Box palette — white + blue only */
+    --bg:#f4f8fd; --panel:#ffffff; --panel2:#eef4fc; --line:#dbe6f5; --ink:#0b2545; --muted:#5b6b85;
+    --blue:#0061d5; --blue-deep:#003a85; --blue-mid:#3b86e6; --blue-soft:#8fbef0; --blue-pale:#c9e0f8;
+    /* severity = blue intensity scale (deep=critical … pale=low) */
+    --crit:#003a85; --high:#0061d5; --med:#4a93f0; --low:#a9cdf6;
+  }
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{font-family:'Segoe UI',Inter,system-ui,Arial,sans-serif;background:var(--bg);color:var(--ink);padding:22px 26px 60px}
+  .top{display:flex;align-items:center;justify-content:space-between;flex-wrap:wrap;gap:12px;margin-bottom:20px}
+  .brand{display:flex;align-items:center;gap:12px}
+  .logo{width:40px;height:40px;border-radius:11px;background:var(--blue);display:flex;align-items:center;justify-content:center;font-size:20px;color:#fff}
+  h1{font-size:21px;font-weight:800;letter-spacing:.2px;color:var(--blue-deep)}
+  .sub{font-size:12.5px;color:var(--muted)}
+  .live{display:inline-flex;align-items:center;gap:7px;font-size:12px;color:var(--blue-deep);background:var(--panel2);border:1px solid var(--line);padding:5px 11px;border-radius:20px}
+  .live i{width:8px;height:8px;border-radius:50%;background:var(--blue);animation:p 1.6s infinite}
+  @keyframes p{0%{box-shadow:0 0 0 0 rgba(0,97,213,.5)}70%{box-shadow:0 0 0 7px rgba(0,97,213,0)}100%{box-shadow:0 0 0 0 rgba(0,97,213,0)}}
+  button{font:inherit;cursor:pointer;border:1px solid var(--line);background:var(--panel);color:var(--blue);padding:7px 14px;border-radius:9px;font-weight:600}
+  button:hover{border-color:var(--blue);background:var(--panel2)}
+
+  .kpis{display:grid;grid-template-columns:repeat(5,1fr);gap:14px;margin-bottom:18px}
+  .kpi{background:var(--panel);border:1px solid var(--line);border-radius:14px;padding:15px 16px;position:relative;overflow:hidden;box-shadow:0 1px 3px rgba(11,37,69,.04)}
+  .kpi .v{font-size:30px;font-weight:800;line-height:1;color:var(--blue-deep)}
+  .kpi .l{font-size:12px;color:var(--muted);margin-top:6px}
+  .kpi .bar{position:absolute;left:0;top:0;bottom:0;width:4px;background:var(--blue)}
+
+  .grid2{display:grid;grid-template-columns:1.55fr 1fr;gap:16px;margin-bottom:18px}
+  .grid3{display:grid;grid-template-columns:repeat(3,1fr);gap:14px;margin-bottom:18px}
+  .grid3 canvas{max-height:210px}
+  .panel{background:var(--panel);border:1px solid var(--line);border-radius:16px;padding:16px;box-shadow:0 1px 3px rgba(11,37,69,.04)}
+  .panel h2{font-size:13px;text-transform:uppercase;letter-spacing:.08em;color:var(--muted);margin-bottom:12px}
+  #map{height:380px;border-radius:12px;overflow:hidden;border:1px solid var(--line)}
+  .leaflet-popup-content{font-family:inherit}
+
+  .donut-wrap{display:flex;align-items:center;gap:18px}
+  .donut{width:150px;height:150px;border-radius:50%;flex:none}
+  .legend{display:flex;flex-direction:column;gap:8px;font-size:13px}
+  .legend .row{display:flex;align-items:center;gap:9px}
+  .legend .sw{width:12px;height:12px;border-radius:3px}
+  .pipe{margin-top:18px;display:flex;flex-direction:column;gap:9px}
+  .pipe .seg{display:flex;align-items:center;gap:10px;font-size:12.5px}
+  .pipe .track{flex:1;height:9px;background:var(--panel2);border-radius:6px;overflow:hidden}
+  .pipe .fill{height:100%;border-radius:6px;background:var(--blue)}
+  .pipe .n{width:26px;text-align:right;color:var(--muted)}
+
+  /* filter bar */
+  .cards-h{display:flex;align-items:center;justify-content:space-between;margin:8px 2px 12px;flex-wrap:wrap;gap:10px}
+  .cards-h h2{color:var(--muted);font-size:13px;text-transform:uppercase;letter-spacing:.08em}
+  .filters{display:flex;flex-wrap:wrap;gap:8px;align-items:center;background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:10px 12px;margin-bottom:14px}
+  .fgroup{display:flex;align-items:center;gap:6px;flex-wrap:wrap}
+  .fgroup .glab{font-size:11px;color:var(--muted);text-transform:uppercase;letter-spacing:.06em;margin-right:2px}
+  .chip{font-size:12px;padding:5px 11px;border-radius:20px;border:1px solid var(--line);background:var(--panel);color:var(--ink);cursor:pointer}
+  .chip:hover{border-color:var(--blue-soft)}
+  .chip.active{background:var(--blue);color:#fff;border-color:var(--blue)}
+  select,input[type=search]{font:inherit;font-size:12.5px;padding:6px 10px;border:1px solid var(--line);border-radius:9px;background:var(--panel);color:var(--ink)}
+  input[type=search]{min-width:180px}
+  .fsep{width:1px;align-self:stretch;background:var(--line);margin:0 2px}
+
+  .cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(340px,1fr));gap:16px}
+  .card{background:var(--panel);border:1px solid var(--line);border-radius:16px;overflow:hidden;display:flex;flex-direction:column;box-shadow:0 1px 3px rgba(11,37,69,.05)}
+  .card .photo{height:160px;background:var(--panel2);position:relative;display:flex;align-items:center;justify-content:center;color:var(--muted);font-size:13px}
+  .card .photo img{width:100%;height:100%;object-fit:cover;display:block}
+  .sev-badge{position:absolute;top:10px;left:10px;font-size:11px;font-weight:800;padding:4px 10px;border-radius:20px;color:#fff;text-transform:uppercase;letter-spacing:.04em}
+  .score-chip{position:absolute;top:10px;right:10px;font-size:13px;font-weight:800;background:rgba(0,58,133,.82);padding:4px 10px;border-radius:20px;color:#fff}
+  .card .photo[onclick]{cursor:pointer}
+  .open-box{position:absolute;bottom:10px;right:10px;background:rgba(11,37,69,.85);color:#fff;font-size:10.5px;font-weight:700;padding:4px 9px;border-radius:7px;opacity:0;transition:opacity .15s;pointer-events:none}
+  .card .photo:hover .open-box{opacity:1}
+  .card .body{padding:14px 15px;display:flex;flex-direction:column;gap:10px}
+  .card .cid{font-weight:800;font-size:15px;display:flex;align-items:center;gap:8px;flex-wrap:wrap;color:var(--blue-deep)}
+  .card .addr{font-size:12.5px;color:var(--muted)}
+  .tag{font-size:10.5px;padding:2px 8px;border-radius:6px;border:1px solid var(--line);color:var(--muted);background:var(--panel2)}
+  .tag.dup{color:var(--blue-deep);border-color:var(--blue-soft);background:var(--blue-pale)}
+  .tag.res{color:#fff;border-color:var(--blue);background:var(--blue)}
+
+  .bd{display:flex;flex-direction:column;gap:7px;margin-top:2px}
+  .bd .f{display:grid;grid-template-columns:78px 1fr 38px;align-items:center;gap:8px;font-size:11.5px}
+  .bd .f .lab{color:var(--muted)}
+  .bd .f .track{height:8px;background:var(--panel2);border-radius:5px;overflow:hidden}
+  .bd .f .fill{height:100%;border-radius:5px}
+  .bd .f .val{text-align:right;font-variant-numeric:tabular-nums;color:var(--ink)}
+  /* breakdown factors in blue shades */
+  .bd .f .fill.pn{background:var(--blue-deep)}.bd .f .fill.tr{background:var(--blue)}.bd .f .fill.dm{background:var(--blue-mid)}.bd .f .fill.we{background:var(--blue-soft)}
+  .summary{font-size:12px;color:var(--muted);border-top:1px solid var(--line);padding-top:9px;line-height:1.5}
+  .bd .f2{display:grid;grid-template-columns:92px 1fr;gap:10px;font-size:11.5px;align-items:baseline}
+  .bd .f2 .lab{color:var(--muted);font-weight:600}
+  .bd .f2 .dv{color:var(--ink);line-height:1.45}
+  .acts{display:flex;gap:6px;margin-top:11px;padding-top:11px;border-top:1px solid var(--line)}
+  .acts .act{flex:1;padding:8px 6px;border:none;border-radius:8px;font-size:11.5px;font-weight:700;cursor:pointer;transition:filter .15s}
+  .acts .act:hover{filter:brightness(.93)}
+  .acts .act:disabled{opacity:.55;cursor:default}
+  .acts .approve{background:var(--blue);color:#fff}
+  .acts .resolve{background:#16a366;color:#fff}
+  .acts .reject{background:#fff;color:#9b1c1c;border:1px solid #f0c5c5}
+  .acts .ghost{background:var(--panel2);color:var(--muted)}
+  .disp{display:flex;gap:6px;margin-top:8px}
+  .disp .crew-in{flex:1;min-width:0;padding:7px 9px;border:1px solid var(--line);border-radius:7px;font-size:11.5px;background:var(--bg);color:var(--ink)}
+  .disp .dbtn{padding:7px 11px;border:none;border-radius:7px;background:#0b3d91;color:#fff;font-size:11.5px;font-weight:700;cursor:pointer;white-space:nowrap}
+  .disp .dbtn:hover{filter:brightness(.92)}
+  .disp .dbtn:disabled{opacity:.55;cursor:default}
+  .nb-btn{margin-top:8px;padding:6px 10px;border:1px solid var(--line);background:var(--panel2);color:var(--blue-deep);font-size:11.5px;font-weight:700;border-radius:7px;cursor:pointer;width:100%}
+  .nb-btn:hover{border-color:var(--blue);background:#fff}
+  .modal{display:none;position:fixed;inset:0;background:rgba(11,37,69,.45);z-index:1000;align-items:center;justify-content:center;padding:20px}
+  .modal-box{background:var(--panel);border-radius:14px;max-width:540px;width:100%;max-height:80vh;display:flex;flex-direction:column;box-shadow:0 20px 60px rgba(0,0,0,.3)}
+  .modal-head{display:flex;justify-content:space-between;align-items:center;padding:15px 18px;border-bottom:1px solid var(--line);font-weight:800;color:var(--ink);font-size:13.5px}
+  .modal-x{border:none;background:var(--panel2);width:30px;height:30px;border-radius:8px;cursor:pointer;color:var(--muted);font-size:14px}
+  .nb-list{padding:6px 14px 12px;overflow:auto}
+  .nb-row{display:flex;align-items:center;gap:12px;padding:10px 4px;border-bottom:1px solid var(--line)}
+  .nb-row:last-child{border-bottom:none}
+  .nb-dist{min-width:70px;font-weight:800;font-variant-numeric:tabular-nums;color:var(--ink);font-size:13px}
+  .nb-sev{font-size:10px;font-weight:800;color:#fff;padding:3px 8px;border-radius:12px;text-transform:uppercase;white-space:nowrap}
+  .nb-info{font-size:12px;color:var(--ink);line-height:1.4}
+  .nb-info .muted{color:var(--muted)}
+  .nb-dup{color:#9b1c1c;font-weight:800;font-size:10.5px}
+  .empty{text-align:center;color:var(--muted);padding:40px;border:1px dashed var(--line);border-radius:14px;grid-column:1/-1;background:var(--panel)}
+  @media(max-width:1000px){.kpis{grid-template-columns:repeat(2,1fr)}.grid2{grid-template-columns:1fr}}
+</style>
+</head>
+<body>
+  <div class="top">
+    <div class="brand">
+      <div class="logo">🛣️</div>
+      <div>
+        <h1>PotholeIQ — Command Center</h1>
+        <div class="sub">Operations view · Philadelphia</div>
+      </div>
+    </div>
+    <div style="display:flex;gap:10px;align-items:center">
+      <span class="sub" id="who"></span>
+      <button onclick="load()">⟳ Refresh</button>
+      <button onclick="logout()">Sign out</button>
+    </div>
+  </div>
+
+  <div class="kpis" id="kpis"></div>
+
+  <div class="grid2">
+    <div class="panel">
+      <h2>Pothole Map — severity by location</h2>
+      <div id="map"></div>
+    </div>
+    <div class="panel">
+      <h2>Severity Distribution</h2>
+      <div class="donut-wrap"><div class="donut" id="donut"></div><div class="legend" id="legend"></div></div>
+      <div style="margin-top:18px"><h2>Status Pipeline</h2><div class="pipe" id="pipe"></div></div>
+    </div>
+  </div>
+
+  <div class="grid3">
+    <div class="panel"><h2>Cases by Ward</h2><canvas id="chWard"></canvas></div>
+    <div class="panel"><h2>Pothole Size</h2><canvas id="chSize"></canvas></div>
+    <div class="panel"><h2>Submissions Over Time</h2><canvas id="chTrend"></canvas></div>
+  </div>
+
+  <div class="cards-h">
+    <h2>Active Cases — severity breakdown</h2>
+    <span class="sub" id="count"></span>
+  </div>
+
+  <div class="filters" id="filters">
+    <div class="fgroup"><span class="glab">Severity</span><span id="sevChips"></span></div>
+    <div class="fsep"></div>
+    <div class="fgroup"><span class="glab">Status</span><span id="statChips"></span></div>
+    <div class="fsep"></div>
+    <div class="fgroup"><span class="glab">Ward</span><select id="wardSel"><option value="all">All</option></select></div>
+    <div class="fsep"></div>
+    <div class="fgroup"><input type="search" id="search" placeholder="Search case ID or address…" /></div>
+  </div>
+
+  <div class="cards" id="cards"></div>
+
+<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
+<div id="nearby-modal" class="modal" onclick="if(event.target===this)closeNearby()">
+  <div class="modal-box">
+    <div class="modal-head"><span id="nearby-title">Nearby potholes</span><button class="modal-x" onclick="closeNearby()">✕</button></div>
+    <div id="nearby-list" class="nb-list"></div>
+  </div>
+</div>
+
+
+<script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
+<script>
+// ── Supervisor auth gate ──────────────────────────────────────────────────
+const SUPABASE_URL = 'https://knvoctdesiwogofcyced.supabase.co';
+const SUPABASE_PUBLISHABLE = 'sb_publishable_pCMhOVA6YYg2948wi6ValQ_hhhC-xfK';
+const sbAuth = supabase.createClient(SUPABASE_URL, SUPABASE_PUBLISHABLE);
+let ACCESS_TOKEN = '';
+const REQUIRE_LOGIN = true;    // supervisor login required (set false to open the dashboard)
+async function logout(){ await sbAuth.auth.signOut(); location.href = 'login.html'; }
+async function requireSupervisor(){
+  const { data } = await sbAuth.auth.getSession();
+  const s = data.session;
+  if (s && s.user?.app_metadata?.role === 'supervisor') {
+    ACCESS_TOKEN = s.access_token;
+    const who = document.getElementById('who'); if (who) who.textContent = s.user.email;
+    return true;
+  }
+  if (!REQUIRE_LOGIN) return true;            // login disabled — load anyway
+  location.href = 'login.html'; return false; // login required — bounce to login
+}
+const authHeaders = () => ({ Authorization: `Bearer ${ACCESS_TOKEN}` });
+</script>
+<script>
+const SEV = { critical:'#003a85', high:'#0061d5', medium:'#4a93f0', low:'#a9cdf6' };
+const sevColor = s => SEV[(s||'').toLowerCase()] || '#8fbef0';
+let map, caseLayer, allCases=[];
+const filt = { sev:'all', status:'all', ward:'all', q:'' };
+
+function kpi(v,l){return `<div class="kpi"><div class="bar"></div><div class="v">${v}</div><div class="l">${l}</div></div>`;}
+function renderKpis(cs){
+  const open=cs.filter(c=>!['resolved','rejected'].includes((c.status||'').toLowerCase())).length;
+  const crit=cs.filter(c=>(c.severityLevel||'').toLowerCase()==='critical').length;
+  const res=cs.filter(c=>(c.status||'').toLowerCase()==='resolved').length;
+  const avg=cs.length?Math.round(cs.reduce((a,c)=>a+(c.severityScore||0),0)/cs.length):0;
+  document.getElementById('kpis').innerHTML=kpi(cs.length,'Total Cases')+kpi(open,'Open')+kpi(crit,'Critical')+kpi(res,'Resolved')+kpi(avg,'Avg Severity');
+}
+function renderDonut(cs){
+  const order=['critical','high','medium','low'];
+  const counts=order.map(k=>cs.filter(c=>(c.severityLevel||'').toLowerCase()===k).length);
+  const total=counts.reduce((a,b)=>a+b,0)||1; let acc=0,stops=[];
+  order.forEach((k,i)=>{const fr=counts[i]/total,a=acc*360,b=(acc+fr)*360;if(counts[i])stops.push(`${SEV[k]} ${a}deg ${b}deg`);acc+=fr;});
+  const dn=document.getElementById('donut');
+  dn.style.background=`conic-gradient(${stops.join(',')||'#dbe6f5 0 360deg'})`; dn.style.position='relative';
+  dn.innerHTML=`<div style="position:absolute;inset:26px;background:#fff;border-radius:50%;display:flex;flex-direction:column;align-items:center;justify-content:center"><div style="font-size:26px;font-weight:800;color:var(--blue-deep)">${total}</div><div style="font-size:10px;color:var(--muted)">cases</div></div>`;
+  document.getElementById('legend').innerHTML=order.map((k,i)=>`<div class="row"><span class="sw" style="background:${SEV[k]}"></span><span style="text-transform:capitalize">${k}</span><b style="margin-left:auto">${counts[i]}</b></div>`).join('');
+}
+function renderPipe(cs){
+  const stages=[['under review','Under Review'],['assigned','Assigned'],['In progress','In Progress'],['resolved','Resolved']];
+  const max=cs.length||1;
+  document.getElementById('pipe').innerHTML=stages.map(([k,lab])=>{const n=cs.filter(c=>(c.status||'').toLowerCase()===k.toLowerCase()).length;return `<div class="seg"><span style="width:92px;color:var(--muted)">${lab}</span><div class="track"><div class="fill" style="width:${n/max*100}%"></div></div><span class="n">${n}</span></div>`;}).join('');
+}
+function bar(lab,cls,o){const s=o.score??0,m=o.max||1;return `<div class="f"><span class="lab">${lab}</span><div class="track"><div class="fill ${cls}" style="width:${Math.min(100,s/m*100)}%"></div></div><span class="val">${s}/${m}</span></div>`;}
+// Estimated municipal repair cost by pothole size (US 2026: cold patch ~$90–180, hot-mix ~$250–550, full-depth up to ~$800).
+function estCost(size){const s=(size||'').toLowerCase();
+  if(s.includes('large')) return '$450–$800 · hot-mix, full-depth';
+  if(s.includes('medium')) return '$250–$450 · hot-mix patch';
+  if(s.includes('small')) return '$90–$180 · cold patch';
+  return '—';}
+// Approve / Resolve / Reject / Reopen — writes the status to Box, then re-renders.
+async function setStatus(caseId,status,btn){
+  const lbl=btn?btn.textContent:''; if(btn){btn.disabled=true;btn.textContent='…';}
+  try{
+    const r=await fetch('/api/box/set-status',{method:'POST',headers:Object.assign({'Content-Type':'application/json'},authHeaders()),body:JSON.stringify({caseId,status})}).then(x=>x.json());
+    if(!r.ok) throw new Error(r.error||r.reason||'update failed');
+    load();
+  }catch(e){ alert('Could not update '+caseId+': '+e.message); if(btn){btn.disabled=false;btn.textContent=lbl;} }
+}
+function card(c){
+  const sev=(c.severityLevel||'—'),col=sevColor(sev);
+  const img=c.photoFileId?`<img src="/api/box/files/${c.photoFileId}/content?access_token=${encodeURIComponent(ACCESS_TOKEN)}" onerror="this.style.display='none';this.parentElement.insertAdjacentHTML('beforeend','<span>📷 photo in Box</span>')"/>`:'<span>📷 no photo</span>';
+  const dup=(c.duplicateStatus||'').trim()==='duplicate'?`<span class="tag dup">⚠ duplicate ×${c.duplicateCount}</span>`:'';
+  const res=(c.status||'').toLowerCase()==='resolved'?`<span class="tag res">✓ resolved</span>`:`<span class="tag">${c.status||'—'}</span>`;
+  const b=c.breakdown||{};
+  return `<div class="card"><div class="photo" ${c.folderId?`onclick="openBox('${c.folderId}')" title="Open case folder in Box"`:''}><span class="sev-badge" style="background:${col}">${sev}</span><span class="score-chip">${c.severityScore??'—'}/100</span>${img}${c.folderId?'<span class="open-box">Open in Box ↗</span>':''}</div>
+    <div class="body"><div class="cid">${c.caseId} ${dup} ${res}</div><div class="addr">📍 Ward ${c.ward} · ${c.address||'—'}</div>
+    <div class="addr" style="margin-top:3px">🗓 Reported ${c.submittedAt?new Date(c.submittedAt).toLocaleDateString():'—'}</div>
+    <button class="nb-btn" onclick="showNearby('${c.caseId}')">📍 See nearby potholes</button>
+    <div class="bd">
+      <div class="f2"><span class="lab">Prior detection</span><span class="dv">${(b.priorNotice&&b.priorNotice.detail)||'—'}</span></div>
+      <div class="f2"><span class="lab">Traffic / road</span><span class="dv">${(b.traffic&&b.traffic.detail)||'—'}</span></div>
+      <div class="f2"><span class="lab">Weather risk</span><span class="dv">${(b.weather&&b.weather.detail)||'—'}</span></div>
+      <div class="f2"><span class="lab">Pothole size</span><span class="dv">${c.potholeSize||'—'}</span></div>
+      <div class="f2"><span class="lab">Est. repair cost</span><span class="dv">${estCost(c.potholeSize)}</span></div>
+    </div>
+    <div class="acts">${['resolved','rejected'].includes((c.status||'').toLowerCase())
+      ? `<button class="act ghost" onclick="setStatus('${c.caseId}','under review',this)">↺ Reopen</button>`
+      : `<button class="act approve" onclick="setStatus('${c.caseId}','assigned',this)">✓ Approve</button><button class="act resolve" onclick="setStatus('${c.caseId}','resolved',this)">✓ Resolve</button><button class="act reject" onclick="setStatus('${c.caseId}','rejected',this)">✕ Reject</button>`}</div>
+    <div class="disp"><input type="email" class="crew-in" id="crew-${c.caseId}" placeholder="crew@email.com" /><button class="dbtn" onclick="dispatchCrew('${c.caseId}',this)">Send to crew</button></div>
+    <a class="nb-btn" style="margin-top:8px;display:block;text-align:center;text-decoration:none" href="crew-closeout.html?case=${encodeURIComponent(c.caseId)}" target="_blank">Open Crew Closeout Form</a>
+    </div></div>`;
+}
+function renderMap(cs,boundaries){
+  if(!map){
+    map=L.map('map',{zoomControl:true}).setView([39.99,-75.13],11);
+    L.tileLayer('https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png',{attribution:'© OpenStreetMap © CARTO',maxZoom:19}).addTo(map);
+    if(boundaries&&boundaries.features){L.geoJSON(boundaries,{style:{color:'#0061d5',weight:1,opacity:.4,fillOpacity:.04}}).addTo(map);}
+  }
+  if(caseLayer)caseLayer.remove(); caseLayer=L.layerGroup().addTo(map);
+  cs.forEach(c=>{if(c.latitude&&c.longitude){L.circleMarker([c.latitude,c.longitude],{radius:9,color:'#fff',weight:2,fillColor:sevColor(c.severityLevel),fillOpacity:.95}).bindPopup(`<b>${c.caseId}</b><br>${c.severityLevel} · ${c.severityScore}/100<br>Ward ${c.ward}`).addTo(caseLayer);}});
+}
+
+// ---------- filtering ----------
+function applyFilters(){
+  const f=allCases.filter(c=>{
+    if(filt.sev!=='all' && (c.severityLevel||'').toLowerCase()!==filt.sev) return false;
+    if(filt.status!=='all' && (c.status||'').toLowerCase()!==filt.status.toLowerCase()) return false;
+    if(filt.ward!=='all' && String(c.ward)!==filt.ward) return false;
+    if(filt.q){const q=filt.q.toLowerCase();if(!(`${c.caseId} ${c.address}`.toLowerCase().includes(q)))return false;}
+    return true;
+  });
+  document.getElementById('count').textContent=`${f.length} of ${allCases.length} cases`;
+  document.getElementById('cards').innerHTML=f.length?f.sort((a,b)=>(b.severityScore||0)-(a.severityScore||0)).map(card).join(''):'<div class="empty">No cases match these filters.</div>';
+  renderMap(f);
+}
+function buildChips(){
+  const sevs=[['all','All'],['critical','Critical'],['high','High'],['medium','Medium'],['low','Low']];
+  document.getElementById('sevChips').innerHTML=sevs.map(([v,l])=>`<span class="chip ${filt.sev===v?'active':''}" data-k="sev" data-v="${v}">${l}</span>`).join('');
+  const stats=[['all','All'],['under review','Review'],['assigned','Assigned'],['In progress','In Progress'],['resolved','Resolved'],['rejected','Rejected']];
+  document.getElementById('statChips').innerHTML=stats.map(([v,l])=>`<span class="chip ${filt.status===v?'active':''}" data-k="status" data-v="${v}">${l}</span>`).join('');
+  document.querySelectorAll('.chip').forEach(ch=>ch.onclick=()=>{filt[ch.dataset.k]=ch.dataset.v;buildChips();applyFilters();});
+  const wards=[...new Set(allCases.map(c=>String(c.ward)))].sort((a,b)=>(parseInt(a)||999)-(parseInt(b)||999));
+  document.getElementById('wardSel').innerHTML='<option value="all">All</option>'+wards.map(w=>`<option value="${w}" ${filt.ward===w?'selected':''}>Ward ${w}</option>`).join('');
+  document.getElementById('wardSel').onchange=e=>{filt.ward=e.target.value;applyFilters();};
+  document.getElementById('search').oninput=e=>{filt.q=e.target.value;applyFilters();};
+}
+
+// Click a case photo -> open that case's folder in Box.
+function openBox(folderId){ if(folderId) window.open('https://sednademo.app.box.com/folder/'+folderId,'_blank','noopener'); }
+
+// Nearby potholes: closest cases by GPS distance (flags any within the 80 m duplicate range).
+function haversineM(la1,lo1,la2,lo2){const R=6371000,r=x=>x*Math.PI/180;const dla=r(la2-la1),dlo=r(lo2-lo1);const a=Math.sin(dla/2)**2+Math.cos(r(la1))*Math.cos(r(la2))*Math.sin(dlo/2)**2;return 2*R*Math.asin(Math.sqrt(a));}
+function showNearby(caseId){
+  const c=allCases.find(x=>x.caseId===caseId);
+  if(!c||c.latitude==null||c.longitude==null){alert('No GPS location recorded for '+caseId+'.');return;}
+  const fmt=m=>m>=1000?(m/1000).toFixed(2)+' km':m+' m';
+  const near=allCases.filter(x=>x.caseId!==caseId&&x.latitude!=null&&x.longitude!=null)
+    .map(x=>({c:x,dist:Math.round(haversineM(c.latitude,c.longitude,x.latitude,x.longitude))}))
+    .sort((a,b)=>a.dist-b.dist).slice(0,12);
+  document.getElementById('nearby-title').textContent='Potholes near '+caseId+' — '+near.length+' closest';
+  document.getElementById('nearby-list').innerHTML = near.length
+    ? near.map(n=>`<div class="nb-row"><span class="nb-dist">${fmt(n.dist)}${n.dist<=80?'<br><span class="nb-dup">⚠ duplicate</span>':''}</span><span class="nb-sev" style="background:${sevColor(n.c.severityLevel)}">${n.c.severityLevel||'—'}</span><div class="nb-info"><b>${n.c.caseId}</b> · ${n.c.status||'—'} · ${n.c.potholeSize||'—'}<br><span class="muted">📍 Ward ${n.c.ward} · ${n.c.address||'—'}</span></div></div>`).join('')
+    : '<div class="nb-info muted" style="padding:14px">No other potholes with a location on record.</div>';
+  document.getElementById('nearby-modal').style.display='flex';
+}
+function closeNearby(){document.getElementById('nearby-modal').style.display='none';}
+
+// The Box Form (closeout) the crew fills after repair -> filling it triggers WF2.
+const CLOSEOUT_FORM_LINK='https://sednademo.app.box.com/f/bb3c86290ee94d7b8263bb9a33718e20';
+// Enter a crew email -> generate the Work Order, then draft an email to the crew + supervisor
+// with the Work Order link AND the closeout form link.
+async function dispatchCrew(caseId,btn){
+  const inp=document.getElementById('crew-'+caseId);
+  const email=inp?inp.value.trim():'';
+  if(!email||email.indexOf('@')<1){ alert('Enter a valid crew email.'); if(inp)inp.focus(); return; }
+  const c=allCases.find(x=>x.caseId===caseId)||{caseId:caseId};
+  const meta={caseId:c.caseId,address:c.address,ward:c.ward,district:c.district,maintenanceZone:c.maintenanceZone,
+    latitude:c.latitude,longitude:c.longitude,severityScore:c.severityScore,severityScore0100:c.severityScore,
+    severityLevel:c.severityLevel,potholeSize:c.potholeSize,weatherRisk:c.weatherRisk,aiReviewStatus:c.aiReviewStatus,
+    reporterContact:c.reporterContact,photoFileId:c.photoFileId,submittedAt:c.submittedAt,assignedCrew:email};
+  const lbl=btn?btn.textContent:''; if(btn){btn.disabled=true;btn.textContent='Sending…';}
+  try{
+    // Box Sign: backend (service account) emails the crew a "review & sign" work order — no mailto, no personal info
+    const r=await fetch('/api/box/dispatch-crew',{method:'POST',headers:Object.assign({'Content-Type':'application/json'},authHeaders()),body:JSON.stringify({caseId,crewEmail:email,metadata:meta})}).then(x=>x.json());
+    if(!r.ok) throw new Error(r.error||r.reason||'dispatch failed');
+    if(btn){btn.textContent='✓ Sent via Box Sign';}
+    if(inp){inp.value='';inp.placeholder='Sent to '+email;}
+  }catch(e){ alert('Could not send to crew ('+caseId+'): '+e.message); if(btn){btn.disabled=false;btn.textContent=lbl;} }
+}
+
+let _charts={};
+function renderCharts(cs){
+  if(typeof Chart==='undefined') return;
+  const BLUE='#0061d5';
+  const ward={}; cs.forEach(c=>{const w='Ward '+(c.ward||'?'); ward[w]=(ward[w]||0)+1;});
+  const we=Object.entries(ward).sort((a,b)=>b[1]-a[1]).slice(0,8);
+  const size={small:0,medium:0,large:0}; cs.forEach(c=>{const s=(c.potholeSize||'').toLowerCase(); if(s in size) size[s]++;});
+  const day={}; cs.forEach(c=>{if(c.submittedAt){const d=new Date(c.submittedAt); if(!isNaN(d)){const k=d.toISOString().slice(0,10); day[k]=(day[k]||0)+1;}}});
+  const days=Object.keys(day).sort();
+  const mk=(id,cfg)=>{ if(_charts[id])_charts[id].destroy(); const el=document.getElementById(id); if(el)_charts[id]=new Chart(el,cfg); };
+  const barOpts={responsive:true,maintainAspectRatio:false,plugins:{legend:{display:false}},scales:{y:{beginAtZero:true,ticks:{precision:0}}}};
+  mk('chWard',{type:'bar',data:{labels:we.map(e=>e[0]),datasets:[{data:we.map(e=>e[1]),backgroundColor:BLUE,borderRadius:5}]},options:barOpts});
+  mk('chSize',{type:'doughnut',data:{labels:['Small','Medium','Large'],datasets:[{data:[size.small,size.medium,size.large],backgroundColor:['#8bb8f0','#3b86e8','#0b3d91']}]},options:{responsive:true,maintainAspectRatio:false,plugins:{legend:{position:'bottom'}}}});
+  mk('chTrend',{type:'line',data:{labels:days,datasets:[{data:days.map(d=>day[d]),borderColor:BLUE,backgroundColor:'rgba(0,97,213,.12)',fill:true,tension:.3,pointRadius:2}]},options:barOpts});
+}
+
+async function load(){
+  // keep the supervisor session token fresh so the auto-refresh fetch doesn't 401 (and flicker to 0)
+  try { const { data } = await sbAuth.auth.getSession(); if (data && data.session) ACCESS_TOKEN = data.session.access_token; } catch(_){}
+  const [casesRes,bRes]=await Promise.all([
+    fetch('/api/box/cases',{headers:authHeaders()}).then(r=>r.ok?r.json():null).catch(()=>null),
+    fetch('/api/gis/boundaries').then(r=>r.json()).catch(()=>null),
+  ]);
+  const cases = casesRes && Array.isArray(casesRes.cases) ? casesRes.cases : null;
+  // update on a good fetch; on a failed/empty refresh keep what we already have (don't blank the dashboard)
+  if (cases && (cases.length || !allCases.length)) allCases = cases;
+  renderKpis(allCases); renderDonut(allCases); renderPipe(allCases); renderMap(allCases,bRes);
+  renderCharts(allCases);
+  buildChips(); applyFilters();
+}
+(async()=>{ if (await requireSupervisor()){ load(); setInterval(load, 30000); } })();  // auto-refresh every 30s
+</script>
+</body>
+</html>

config-store.js

@@ -0,0 +1,223 @@
+'use strict';
+
+const fs = require('fs/promises');
+const path = require('path');
+
+const CONFIG_FILE_NAME = 'config.json';
+
+const DEFAULT_BOX_CONFIG = {
+  authMode: 'oauth_refresh',
+  accessToken: '',
+  accessTokenExpiresAt: '',
+  refreshToken: '',
+  clientId: '',
+  clientSecret: '',
+  subjectType: 'enterprise',
+  subjectId: '',
+  intakeFolderId: '',
+  caseRootFolderId: '',
+  metadataScope: '',
+  metadataTemplateKey: '',
+  updatedAt: '',
+};
+
+const DEFAULT_APP_CONFIG = {
+  box: { ...DEFAULT_BOX_CONFIG },
+};
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function cloneDefaults() {
+  return JSON.parse(JSON.stringify(DEFAULT_APP_CONFIG));
+}
+
+function normalizeString(value) {
+  return String(value ?? '').trim();
+}
+
+function maskSecret(secret) {
+  const normalized = normalizeString(secret);
+  if (!normalized) return '';
+  if (normalized.length <= 8) return `${normalized.slice(0, 2)}...${normalized.slice(-2)}`;
+  return `${normalized.slice(0, 4)}...${normalized.slice(-4)}`;
+}
+
+function sanitizeAuthMode(value, fallback = DEFAULT_BOX_CONFIG.authMode) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (['access_token', 'oauth_refresh', 'client_credentials'].includes(normalized)) {
+    return normalized;
+  }
+  return fallback;
+}
+
+function sanitizeSubjectType(value, fallback = DEFAULT_BOX_CONFIG.subjectType) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (normalized === 'user' || normalized === 'enterprise') {
+    return normalized;
+  }
+  return fallback;
+}
+
+function mergeBoxConfig(existing = {}, incoming = {}, options = {}) {
+  const next = {
+    ...DEFAULT_BOX_CONFIG,
+    ...(existing || {}),
+  };
+
+  if (options.reset) {
+    return {
+      ...DEFAULT_BOX_CONFIG,
+      updatedAt: nowIso(),
+    };
+  }
+
+  if (Object.prototype.hasOwnProperty.call(incoming, 'authMode')) {
+    next.authMode = sanitizeAuthMode(incoming.authMode, next.authMode);
+  }
+
+  if (Object.prototype.hasOwnProperty.call(incoming, 'subjectType')) {
+    next.subjectType = sanitizeSubjectType(incoming.subjectType, next.subjectType);
+  }
+
+  const copyFields = [
+    'clientId',
+    'subjectId',
+    'intakeFolderId',
+    'caseRootFolderId',
+    'metadataScope',
+    'metadataTemplateKey',
+  ];
+
+  for (const field of copyFields) {
+    if (Object.prototype.hasOwnProperty.call(incoming, field)) {
+      next[field] = normalizeString(incoming[field]);
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(incoming, 'accessTokenExpiresAt')) {
+    next.accessTokenExpiresAt = normalizeString(incoming.accessTokenExpiresAt);
+  }
+
+  const secretFieldMap = [
+    ['accessToken', 'clearAccessToken'],
+    ['refreshToken', 'clearRefreshToken'],
+    ['clientSecret', 'clearClientSecret'],
+  ];
+
+  for (const [field, clearField] of secretFieldMap) {
+    if (incoming[clearField]) {
+      next[field] = '';
+      if (field === 'accessToken') next.accessTokenExpiresAt = '';
+      continue;
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(incoming, field)) continue;
+    const normalized = normalizeString(incoming[field]);
+    if (normalized) {
+      next[field] = normalized;
+      if (field === 'accessToken' && !incoming.accessTokenExpiresAt) {
+        next.accessTokenExpiresAt = '';
+      }
+    }
+  }
+
+  next.updatedAt = nowIso();
+  return next;
+}
+
+function sanitizeBoxConfigForClient(box = {}) {
+  const merged = { ...DEFAULT_BOX_CONFIG, ...(box || {}) };
+  return {
+    authMode: sanitizeAuthMode(merged.authMode),
+    clientId: normalizeString(merged.clientId),
+    subjectType: sanitizeSubjectType(merged.subjectType),
+    subjectId: normalizeString(merged.subjectId),
+    intakeFolderId: normalizeString(merged.intakeFolderId),
+    caseRootFolderId: normalizeString(merged.caseRootFolderId),
+    metadataScope: normalizeString(merged.metadataScope),
+    metadataTemplateKey: normalizeString(merged.metadataTemplateKey),
+    accessTokenPreview: maskSecret(merged.accessToken),
+    refreshTokenPreview: maskSecret(merged.refreshToken),
+    clientSecretPreview: maskSecret(merged.clientSecret),
+    hasAccessToken: !!normalizeString(merged.accessToken),
+    hasRefreshToken: !!normalizeString(merged.refreshToken),
+    hasClientSecret: !!normalizeString(merged.clientSecret),
+    accessTokenExpiresAt: normalizeString(merged.accessTokenExpiresAt),
+    updatedAt: normalizeString(merged.updatedAt),
+  };
+}
+
+function createConfigStore({ dataDir }) {
+  const configPath = path.join(dataDir, CONFIG_FILE_NAME);
+  let writeQueue = Promise.resolve();
+
+  async function ensureConfigFile() {
+    await fs.mkdir(dataDir, { recursive: true });
+    try {
+      await fs.access(configPath);
+    } catch {
+      await fs.writeFile(configPath, JSON.stringify(cloneDefaults(), null, 2), 'utf8');
+    }
+  }
+
+  async function readConfig() {
+    await ensureConfigFile();
+    const raw = await fs.readFile(configPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+      ...cloneDefaults(),
+      ...(parsed || {}),
+      box: {
+        ...DEFAULT_BOX_CONFIG,
+        ...((parsed && parsed.box) || {}),
+      },
+    };
+  }
+
+  async function writeConfig(nextConfig) {
+    const normalized = {
+      ...cloneDefaults(),
+      ...(nextConfig || {}),
+      box: {
+        ...DEFAULT_BOX_CONFIG,
+        ...((nextConfig && nextConfig.box) || {}),
+      },
+    };
+    const tmpPath = `${configPath}.tmp`;
+    await fs.writeFile(tmpPath, JSON.stringify(normalized, null, 2), 'utf8');
+    await fs.rename(tmpPath, configPath);
+    return normalized;
+  }
+
+  async function queueMutation(mutator) {
+    const task = writeQueue.then(async () => {
+      const current = await readConfig();
+      const next = await mutator(current);
+      const written = await writeConfig(next || current);
+      return written;
+    });
+    writeQueue = task.catch(() => undefined);
+    return task;
+  }
+
+  return {
+    configPath,
+    readConfig,
+    writeConfig,
+    queueMutation,
+    mergeBoxConfig,
+    sanitizeBoxConfigForClient,
+    defaults: {
+      box: { ...DEFAULT_BOX_CONFIG },
+    },
+  };
+}
+
+module.exports = {
+  createConfigStore,
+  mergeBoxConfig,
+  sanitizeBoxConfigForClient,
+  DEFAULT_BOX_CONFIG,
+};

crew-closeout.html

@@ -0,0 +1,602 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Crew Closeout — PotholeIQ</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet" />
+  <link rel="stylesheet" href="styles.css?v=20260604a" />
+  <style>
+    body { padding-top: 64px; }
+    .closeout-shell {
+      min-height: calc(100vh - 64px);
+      background: linear-gradient(180deg, #F7F9FC 0%, #ECF2FB 100%);
+      padding: 36px 20px 72px;
+    }
+    .closeout-wrap {
+      max-width: 1100px;
+      margin: 0 auto;
+      display: grid;
+      grid-template-columns: 320px minmax(0, 1fr);
+      gap: 24px;
+      align-items: start;
+    }
+    .closeout-panel {
+      background: #fff;
+      border: 1px solid #E4E9F0;
+      border-radius: 18px;
+      box-shadow: 0 20px 48px rgba(15, 23, 42, 0.08);
+    }
+    .closeout-panel__head {
+      padding: 22px 24px 18px;
+      border-bottom: 1px solid #E8EDF5;
+    }
+    .closeout-panel__title {
+      font-size: 20px;
+      font-weight: 800;
+      color: #162038;
+      margin-bottom: 6px;
+    }
+    .closeout-panel__sub {
+      font-size: 13px;
+      color: #6B7280;
+      line-height: 1.6;
+    }
+    .closeout-panel__body {
+      padding: 22px 24px 24px;
+    }
+    .detail-stack {
+      display: grid;
+      gap: 12px;
+    }
+    .detail-card {
+      border: 1px solid #E7ECF4;
+      border-radius: 14px;
+      padding: 14px 16px;
+      background: #FAFCFF;
+    }
+    .detail-card__label {
+      font-size: 11px;
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.06em;
+      color: #7A8396;
+      margin-bottom: 4px;
+    }
+    .detail-card__value {
+      font-size: 14px;
+      font-weight: 600;
+      color: #1A2340;
+      line-height: 1.5;
+      word-break: break-word;
+    }
+    .closeout-form {
+      display: grid;
+      gap: 18px;
+    }
+    .form-grid {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+      gap: 16px;
+    }
+    .field-group {
+      display: grid;
+      gap: 8px;
+    }
+    .field-group label {
+      font-size: 12px;
+      font-weight: 700;
+      color: #46506A;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+    }
+    .field-input,
+    .field-textarea,
+    .field-select {
+      width: 100%;
+      border: 1.5px solid #D8E0ED;
+      border-radius: 12px;
+      background: #fff;
+      color: #122033;
+      font: inherit;
+      padding: 12px 14px;
+      transition: border-color 0.15s ease, box-shadow 0.15s ease;
+    }
+    .field-textarea { min-height: 130px; resize: vertical; }
+    .field-input:focus,
+    .field-textarea:focus,
+    .field-select:focus {
+      outline: none;
+      border-color: #0061D5;
+      box-shadow: 0 0 0 3px rgba(0, 97, 213, 0.12);
+    }
+    .field-hint {
+      font-size: 12px;
+      color: #768195;
+      line-height: 1.5;
+    }
+    .cost-total-box {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 16px;
+      padding: 16px 18px;
+      border-radius: 14px;
+      border: 1.5px solid #FDE2A7;
+      background: linear-gradient(135deg, #FFFBF0, #FFF6E0);
+    }
+    .cost-total-box__label {
+      font-size: 12px;
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      color: #9A6608;
+    }
+    .cost-total-box__hint {
+      font-size: 12px;
+      color: #B07B2A;
+      margin-top: 3px;
+    }
+    .cost-total-box__amount {
+      font-size: 26px;
+      font-weight: 800;
+      letter-spacing: -0.02em;
+      color: #92500C;
+      font-variant-numeric: tabular-nums;
+      white-space: nowrap;
+    }
+    .status-banner {
+      display: none;
+      margin-top: 18px;
+      padding: 14px 16px;
+      border-radius: 14px;
+      font-size: 14px;
+      font-weight: 600;
+      line-height: 1.6;
+    }
+    .status-banner.ok {
+      display: block;
+      background: #EAFAF2;
+      border: 1px solid #BFE8D1;
+      color: #166C43;
+    }
+    .status-banner.err {
+      display: block;
+      background: #FEF2F2;
+      border: 1px solid #F6C5C5;
+      color: #A12828;
+    }
+    .action-row {
+      display: flex;
+      gap: 12px;
+      flex-wrap: wrap;
+      align-items: center;
+    }
+    .btn-solid {
+      border: none;
+      border-radius: 12px;
+      padding: 12px 18px;
+      font-size: 14px;
+      font-weight: 700;
+      cursor: pointer;
+      transition: transform 0.15s ease, box-shadow 0.15s ease, background 0.15s ease;
+    }
+    .btn-solid.primary {
+      background: #0061D5;
+      color: #fff;
+      box-shadow: 0 10px 24px rgba(0, 97, 213, 0.2);
+    }
+    .btn-solid.secondary {
+      background: #EEF3FB;
+      color: #24436B;
+    }
+    .btn-solid:hover { transform: translateY(-1px); }
+    @media (max-width: 900px) {
+      .closeout-wrap { grid-template-columns: 1fr; }
+      .form-grid { grid-template-columns: 1fr; }
+    }
+  </style>
+</head>
+<body>
+  <nav class="nav-header">
+    <div class="nav-header__inner">
+      <div class="nav-header__logo">
+        <div class="nav-header__logo-icon">P</div>
+        <span>PotholeIQ — Crew Closeout</span>
+      </div>
+    </div>
+  </nav>
+
+  <main class="closeout-shell">
+    <div class="closeout-wrap">
+      <section class="closeout-panel">
+        <div class="closeout-panel__head">
+          <div class="closeout-panel__title">Assigned Case Snapshot</div>
+          <div class="closeout-panel__sub">Select an assigned case, verify the location and severity context, then submit the field proof and closeout details.</div>
+        </div>
+        <div class="closeout-panel__body">
+          <div class="field-group" style="margin-bottom:18px;">
+            <label for="closeout-case">Case</label>
+            <select id="closeout-case" class="field-select"></select>
+          </div>
+          <div class="detail-stack" id="case-detail-stack">
+            <div class="detail-card">
+              <div class="detail-card__label">Status</div>
+              <div class="detail-card__value">No case selected yet.</div>
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <section class="closeout-panel">
+        <div class="closeout-panel__head">
+          <div class="closeout-panel__title">Crew Completion Form</div>
+          <div class="closeout-panel__sub">This records the repair proof outside Box, then saves the after-photo, before/after report, and audit artifacts back into the case folder in Box.</div>
+        </div>
+        <div class="closeout-panel__body">
+          <form class="closeout-form" id="closeout-form">
+            <div class="form-grid">
+              <div class="field-group">
+                <label for="crew-name">Crew Name</label>
+                <input id="crew-name" class="field-input" type="text" placeholder="Crew Alpha / Crew 2" />
+              </div>
+              <div class="field-group">
+                <label for="repair-method">Repair Method</label>
+                <select id="repair-method" class="field-select">
+                  <option value="Cold Patch">Cold Patch</option>
+                  <option value="Hot Mix">Hot Mix</option>
+                  <option value="Full Depth Repair">Full Depth Repair</option>
+                  <option value="Temporary Safety Patch">Temporary Safety Patch</option>
+                </select>
+              </div>
+            </div>
+
+            <div class="form-grid">
+              <div class="field-group">
+                <label for="materials-used">Materials Used</label>
+                <input id="materials-used" class="field-input" type="text" placeholder="2 cold-mix bags, 1 sealant can" />
+              </div>
+              <div class="field-group">
+                <label for="labor-hours">Labor Hours</label>
+                <input id="labor-hours" class="field-input" type="number" min="0" step="0.25" placeholder="2.5" />
+              </div>
+            </div>
+
+            <div class="form-grid">
+              <div class="field-group">
+                <label for="labor-rate">Labor Rate ($/hr)</label>
+                <input id="labor-rate" class="field-input" type="number" min="0" step="0.01" placeholder="45.00" value="45" />
+              </div>
+              <div class="field-group">
+                <label for="materials-cost">Materials Cost ($)</label>
+                <input id="materials-cost" class="field-input" type="number" min="0" step="0.01" placeholder="120.00" />
+              </div>
+            </div>
+
+            <div class="cost-total-box">
+              <div>
+                <div class="cost-total-box__label">Total Spend (labor + materials)</div>
+                <div class="cost-total-box__hint" id="cost-breakdown-hint">Enter labor hours, rate, and materials cost.</div>
+              </div>
+              <div class="cost-total-box__amount" id="total-spend-display">$0.00</div>
+            </div>
+
+            <div class="field-group">
+              <label for="resolution-notes">Resolution Notes</label>
+              <textarea id="resolution-notes" class="field-textarea" placeholder="Describe the repair, safety observations, and anything the supervisor should know."></textarea>
+            </div>
+
+            <div class="form-grid">
+              <div class="field-group">
+                <label for="crew-signature">Crew Signature</label>
+                <input id="crew-signature" class="field-input" type="text" placeholder="Crew lead full name / badge" />
+              </div>
+              <div class="field-group">
+                <label for="after-photo">After Photo</label>
+                <input id="after-photo" class="field-input" type="file" accept="image/*" />
+                <div class="field-hint">This uploads directly into the case folder in Box before the closeout record is saved.</div>
+              </div>
+            </div>
+
+            <div class="field-group">
+              <label for="notify-email">Also Email Report To <span style="font-weight:500;text-transform:none;color:#768195;">— optional, comma-separated</span></label>
+              <input id="notify-email" class="field-input" type="text" placeholder="extra.person@city.gov, another@city.gov" autocomplete="off" />
+              <div class="field-hint">Every closeout already shares the report with the <strong>default recipients</strong> configured for the team (via Box). Add any extra one-off recipients here, separated by commas. <strong>One-time invite:</strong> each person is invited once to the Box <strong>“Closeout Reports”</strong> folder, then keeps standing access — turn on that folder’s notifications in Box to get one clean email per closeout. Requires Box to be connected.</div>
+            </div>
+
+            <div class="action-row">
+              <button type="submit" class="btn-solid primary" id="submit-closeout">Submit Closeout & Resolve Case</button>
+            </div>
+          </form>
+
+          <div id="closeout-status" class="status-banner"></div>
+        </div>
+      </section>
+    </div>
+  </main>
+
+  <script src="backend-api.js?v=20260604a"></script>
+  <script>
+    'use strict';
+
+    const CASES_KEY = 'submitted_cases';
+
+    function $(id) {
+      return document.getElementById(id);
+    }
+
+    function readLocalCases() {
+      try {
+        return JSON.parse(localStorage.getItem(CASES_KEY) || '[]');
+      } catch {
+        return [];
+      }
+    }
+
+    function writeLocalCases(cases) {
+      localStorage.setItem(CASES_KEY, JSON.stringify(Array.isArray(cases) ? cases : []));
+    }
+
+    function caseDetailField(label, value) {
+      return `
+        <div class="detail-card">
+          <div class="detail-card__label">${label}</div>
+          <div class="detail-card__value">${value || '—'}</div>
+        </div>`;
+    }
+
+    function eligibleCloseoutCases(cases) {
+      return (Array.isArray(cases) ? cases : [])
+        .filter((item) => item && item.caseId)
+        .filter((item) => !['Resolved', 'Rejected'].includes(String(item.status || '')))
+        .filter((item) => item.report?.supervisor?.isPothole !== false);
+    }
+
+    function renderCaseOptions(cases, selectedCaseId = '') {
+      const options = ['<option value="">Select an assigned case</option>'];
+      cases.forEach((item) => {
+        const selected = item.caseId === selectedCaseId ? ' selected' : '';
+        options.push(`<option value="${item.caseId}"${selected}>${item.caseId} — ${item.report?.address || item.report?.areaLabel || 'Unknown address'}</option>`);
+      });
+      $('closeout-case').innerHTML = options.join('');
+    }
+
+    function updateCaseSummary(caseRecord) {
+      if (!caseRecord) {
+        $('case-detail-stack').innerHTML = caseDetailField('Status', 'No case selected yet.');
+        return;
+      }
+
+      const report = caseRecord.report || {};
+      $('case-detail-stack').innerHTML = [
+        caseDetailField('Status', caseRecord.status || 'Unknown'),
+        caseDetailField('Address', report.address || 'Unknown'),
+        caseDetailField('Ward / District', `${report.ward || 'Pending'} / ${report.district || 'Pending'}`),
+        caseDetailField('Maintenance Zone', report.maintenanceZone || 'Pending'),
+        caseDetailField('Severity', `${report.enrichment?.severityLevel || report.workflowSeverityLevel || 'Pending'} (${report.enrichment?.severityScore ?? report.workflowSeverityScore ?? 'N/A'})`),
+        caseDetailField('Assigned Crew', report.dispatchPlan?.crewName || report.crewName || report.assignedTo || 'Pending'),
+      ].join('');
+
+      $('crew-name').value = report.dispatchPlan?.crewName || report.crewName || report.assignedTo || '';
+      $('repair-method').value = report.repairMethod || 'Cold Patch';
+      $('materials-used').value = report.materialsUsed || '';
+      $('labor-hours').value = report.laborHours || '';
+      $('labor-rate').value = report.laborRate || '45';
+      $('materials-cost').value = report.materialsCost || '';
+      $('resolution-notes').value = report.resolutionNotes || '';
+      $('crew-signature').value = report.crewSignature || '';
+      recomputeSpend();
+    }
+
+    function setStatus(message, tone = 'ok') {
+      const el = $('closeout-status');
+      el.className = `status-banner ${tone}`;
+      el.textContent = message;
+    }
+
+    function computeSpend() {
+      const hours = parseFloat($('labor-hours').value) || 0;
+      const rate = parseFloat($('labor-rate').value) || 0;
+      const materials = parseFloat($('materials-cost').value) || 0;
+      const labor = hours * rate;
+      return { hours, rate, materials, labor, total: labor + materials };
+    }
+
+    function recomputeSpend() {
+      const s = computeSpend();
+      $('total-spend-display').textContent = `$${s.total.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+      $('cost-breakdown-hint').textContent = s.total > 0
+        ? `Labor ${s.hours}h × $${s.rate.toFixed(2)} = $${s.labor.toFixed(2)} · Materials $${s.materials.toFixed(2)}`
+        : 'Enter labor hours, rate, and materials cost.';
+    }
+
+    // Map a Box case (flat, from /api/box/cases) to the { caseId, status, report } shape.
+    function boxCaseToRecord(c) {
+      return {
+        caseId: c.caseId,
+        status: c.status || 'Assigned',
+        ts: c.submittedAt || Date.now(),
+        report: {
+          address: c.address || '', ward: c.ward || '', district: c.district || '',
+          maintenanceZone: c.maintenanceZone || '',
+          location: (c.latitude != null && c.longitude != null) ? { lat: c.latitude, lng: c.longitude } : null,
+          photoFileId: c.photoFileId || '', aiResult: c.potholeSize || '', potholeSize: c.potholeSize || '',
+          reporterContact: c.reporterContact || '', submittedAt: c.submittedAt || '',
+          enrichment: { severityScore: c.severityScore, severityLevel: c.severityLevel, severityBreakdown: c.breakdown || {} },
+        },
+      };
+    }
+
+    async function fetchBoxCases() {
+      try {
+        const r = await fetch('/api/box/cases').then((x) => x.json());
+        return Array.isArray(r.cases) ? r.cases.map(boxCaseToRecord) : [];
+      } catch (_) { return []; }
+    }
+
+    // Load every case (local/DB + Box) so the form can open to any case via ?case=.
+    let CASES_BY_ID = {};
+    async function loadCases() {
+      let remoteCases = [];
+      try {
+        remoteCases = await window.PotholeBackend.getCases();
+      } catch (error) {
+        console.warn('[CrewCloseout] remote case load failed:', error);
+      }
+      const merged = window.PotholeBackend.mergeCaseLists(readLocalCases(), remoteCases);
+      const have = new Set(merged.map((c) => c.caseId));
+      (await fetchBoxCases()).forEach((bc) => { if (!have.has(bc.caseId)) merged.push(bc); });
+      CASES_BY_ID = Object.fromEntries(merged.map((c) => [c.caseId, c]));
+      return merged;
+    }
+
+    async function handleSubmit(event) {
+      event.preventDefault();
+      const caseId = $('closeout-case').value;
+      if (!caseId) {
+        setStatus('Select an assigned case before submitting closeout.', 'err');
+        return;
+      }
+
+      const crewName = $('crew-name').value.trim();
+      const resolutionNotes = $('resolution-notes').value.trim();
+      const crewSignature = $('crew-signature').value.trim();
+      if (!crewName || !resolutionNotes || !crewSignature) {
+        setStatus('Crew name, resolution notes, and crew signature are required.', 'err');
+        return;
+      }
+
+      const submitBtn = $('submit-closeout');
+      submitBtn.disabled = true;
+      submitBtn.textContent = 'Submitting closeout…';
+
+      try {
+        // Ensure the case exists in the backend store (Box-only cases aren't there yet),
+        // so the after-photo upload + closeout can find it. The server backfills the rest.
+        const selected = CASES_BY_ID[caseId];
+        if (selected) {
+          await window.PotholeBackend.upsertCase({
+            caseId,
+            status: selected.status || 'Assigned',
+            report: selected.report || {},
+          }).catch(() => {});
+        }
+
+        let afterPhotoUpload = null;
+        const photoFile = $('after-photo').files && $('after-photo').files[0];
+        if (photoFile) {
+          const ext = (photoFile.name.split('.').pop() || 'jpg').toLowerCase();
+          const safeName = `${caseId}_after_photo.${ext}`;
+          afterPhotoUpload = await window.PotholeBackend.uploadCaseFile(caseId, safeName, photoFile, photoFile.type || 'image/jpeg');
+        }
+
+        const spend = computeSpend();
+        const notifyEmail = $('notify-email').value.trim();
+        if (notifyEmail) localStorage.setItem('closeout_notify_email', notifyEmail);
+        const response = await window.PotholeBackend.submitCrewCloseout(caseId, {
+          crewName,
+          repairMethod: $('repair-method').value,
+          materialsUsed: $('materials-used').value.trim(),
+          laborHours: $('labor-hours').value.trim(),
+          laborRate: $('labor-rate').value.trim(),
+          materialsCost: $('materials-cost').value.trim(),
+          totalCost: spend.total.toFixed(2),
+          notifyEmail,
+          resolutionNotes,
+          crewSignature,
+          afterPhotoFileId: afterPhotoUpload?.fileId || '',
+          afterPhotoFileName: afterPhotoUpload?.fileName || '',
+        });
+
+        const updatedCase = response?.case;
+        if (!updatedCase) {
+          throw new Error('Closeout did not return an updated case.');
+        }
+
+        const allCases = window.PotholeBackend.mergeCaseLists(readLocalCases(), [updatedCase]);
+        writeLocalCases(allCases);
+        renderCaseOptions(eligibleCloseoutCases(allCases));
+        updateCaseSummary(updatedCase);
+        $('closeout-form').reset();
+        $('closeout-case').value = '';
+
+        // Summarize the Box notification outcome (one line per recipient).
+        const notifications = response?.notifications || [];
+        const sharedLink = response?.sharedLink || '';
+        const boxLink = sharedLink
+          ? `<div style="margin-top:6px;"><a href="${sharedLink}" target="_blank" style="color:#0061D5;font-weight:700;">Open report in Box →</a></div>`
+          : '';
+        let notifyLine = '';
+        if (notifications.length) {
+          const items = notifications.map((n) => {
+            if (n.firstTime) return `📧 <strong>${n.to}</strong> — invited to the Box reports workspace (one-time)`;
+            if (n.emailed) return `📧 <strong>${n.to}</strong> — report emailed`;
+            if (n.alreadyHasAccess) return `📁 <strong>${n.to}</strong> — already has access (no new invite)`;
+            if (n.reason === 'box_not_configured') return `⚠️ <strong>${n.to}</strong> — Box not connected, not sent`;
+            if (n.error) return `⚠️ <strong>${n.to}</strong> — ${n.error}`;
+            return `• <strong>${n.to}</strong>`;
+          });
+          notifyLine = `<div style="margin-top:10px;font-weight:700;">Report shared via Box with ${notifications.length} recipient${notifications.length === 1 ? '' : 's'}:</div>
+            <ul style="margin:4px 0 0 18px;padding:0;font-weight:500;">${items.map((i) => `<li style="margin:2px 0;">${i}</li>`).join('')}</ul>${boxLink}`;
+        }
+
+        const statusEl = $('closeout-status');
+        statusEl.className = 'status-banner ok';
+        statusEl.innerHTML = `Closeout submitted for <strong>${caseId}</strong>. The before/after report and audit artifacts have been generated${afterPhotoUpload?.fileId ? ' and the after-photo is stored in Box' : ''}.${notifyLine}
+          <a href="case-report.html?case=${encodeURIComponent(caseId)}" target="_blank" style="display:inline-block;margin-top:10px;padding:9px 16px;border-radius:10px;background:#0061D5;color:#fff;text-decoration:none;font-weight:700;">View Before / After Report →</a>`;
+      } catch (error) {
+        console.error('[CrewCloseout] submit failed:', error);
+        setStatus(`Could not submit closeout: ${error.message}`, 'err');
+      } finally {
+        submitBtn.disabled = false;
+        submitBtn.textContent = 'Submit Closeout & Resolve Case';
+      }
+    }
+
+    async function init() {
+      const allCases = await loadCases();
+      const requestedCaseId = new URLSearchParams(window.location.search).get('case') || '';
+
+      if (requestedCaseId) {
+        // Locked mode: this form is for exactly the pothole that was sent to the crew.
+        // Show only that case — no picker, no defaulting to some other case.
+        const theCase = CASES_BY_ID[requestedCaseId];
+        if (!theCase) {
+          renderCaseOptions([], '');
+          $('closeout-case').disabled = true;
+          $('case-detail-stack').innerHTML = caseDetailField('Status', `Case "${requestedCaseId}" was not found.`);
+          $('submit-closeout').disabled = true;
+        } else {
+          renderCaseOptions([theCase], requestedCaseId);
+          $('closeout-case').value = requestedCaseId;
+          $('closeout-case').disabled = true; // crew can't switch to another case
+          updateCaseSummary(theCase);
+        }
+      } else {
+        // No case in the link: don't auto-pick one. Prompt to open from a specific case.
+        const eligible = eligibleCloseoutCases(allCases);
+        renderCaseOptions(eligible, '');
+        updateCaseSummary(null);
+        $('closeout-case').addEventListener('change', (event) => {
+          updateCaseSummary(CASES_BY_ID[event.target.value] || null);
+        });
+      }
+
+      ['labor-hours', 'labor-rate', 'materials-cost'].forEach((id) => {
+        $(id).addEventListener('input', recomputeSpend);
+      });
+      recomputeSpend();
+      $('notify-email').value = localStorage.getItem('closeout_notify_email') || '';
+
+      $('closeout-form').addEventListener('submit', handleSubmit);
+    }
+
+    init().catch((error) => {
+      console.error('[CrewCloseout] init failed:', error);
+      setStatus(`Could not initialize crew closeout: ${error.message}`, 'err');
+    });
+  </script>
+</body>
+</html>

dashcam-demo.html

@@ -0,0 +1,931 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
+  <title>Dashcam Capture Mode - City Road Reporting</title>
+  <meta name="description" content="Real-time pothole detection while driving. Windshield mount your device for hands-free scanning." />
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@500;700&display=swap" rel="stylesheet" />
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/leaflet.min.css" />
+
+  <style>
+    /* ── Reset & Variables ────────────────────────────────────────────────── */
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    
+    :root {
+      --bg-dark: #07090e;
+      --card-glass: rgba(13, 18, 30, 0.72);
+      --card-border: rgba(255, 255, 255, 0.08);
+      --accent-glow: rgba(0, 97, 213, 0.3);
+      --text-main: #f3f4f6;
+      --text-muted: #9ca3af;
+      --primary: #0061d5;
+      
+      --color-small: #10b981;
+      --color-medium: #f59e0b;
+      --color-large: #ef4444;
+      --color-not-pothole: #6b7280;
+    }
+
+    body {
+      font-family: 'Inter', sans-serif;
+      background-color: var(--bg-dark);
+      color: var(--text-main);
+      overflow: hidden;
+      height: 100vh;
+      width: 100vw;
+      user-select: none;
+      -webkit-user-select: none;
+    }
+
+    /* ── Fullscreen Camera ────────────────────────────────────────────────── */
+    .camera-container {
+      position: absolute;
+      inset: 0;
+      z-index: 1;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: #000;
+    }
+
+    #webcam-feed {
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+      transform: scaleX(1); /* Keep natural camera orientation */
+    }
+
+    /* ── Live Bounding-Box Detection Overlay ──────────────────────────────── */
+    #detection-overlay {
+      position: absolute;
+      inset: 0;
+      z-index: 3;            /* above camera + flash, below HUD panels */
+      width: 100%;
+      height: 100%;
+      pointer-events: none;
+    }
+
+    /* ── Flash & Warning Vignette Overlay ─────────────────────────────────── */
+    .alert-overlay {
+      position: absolute;
+      inset: 0;
+      z-index: 2;
+      pointer-events: none;
+      box-shadow: inset 0 0 0px 0px rgba(239, 68, 68, 0);
+      transition: box-shadow 0.15s ease-out;
+    }
+
+    .alert-overlay.flash {
+      box-shadow: inset 0 0 80px 30px rgba(239, 68, 68, 0.65);
+      animation: alert-pulse 0.4s ease-out;
+    }
+
+    @keyframes alert-pulse {
+      0% { box-shadow: inset 0 0 80px 40px rgba(239, 68, 68, 0.85); }
+      100% { box-shadow: inset 0 0 0px 0px rgba(239, 68, 68, 0); }
+    }
+
+    /* ── HUD Dashboard (Overlays) ────────────────────────────────────────── */
+    .hud-layer {
+      position: absolute;
+      inset: 0;
+      z-index: 10;
+      pointer-events: none;
+      display: flex;
+      flex-direction: column;
+      justify-content: space-between;
+      padding: 16px;
+    }
+
+    /* Make items inside HUD layer clickable */
+    .hud-layer * {
+      pointer-events: auto;
+    }
+
+    /* Glassmorphism utility */
+    .glass-panel {
+      background: var(--card-glass);
+      backdrop-filter: blur(12px);
+      -webkit-backdrop-filter: blur(12px);
+      border: 1px solid var(--card-border);
+      border-radius: 12px;
+      box-shadow: 0 8px 32px rgba(0, 0, 0, 0.5);
+    }
+
+    /* ── Header HUD ───────────────────────────────────────────────────────── */
+    .hud-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      width: 100%;
+      margin-bottom: 8px;
+    }
+
+    .header-left {
+      display: flex;
+      align-items: center;
+      gap: 12px;
+    }
+
+    .btn-back {
+      width: 40px;
+      height: 40px;
+      border-radius: 50%;
+      border: 1px solid var(--card-border);
+      background: rgba(13, 18, 30, 0.6);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      cursor: pointer;
+      color: var(--text-main);
+      transition: background 0.2s;
+    }
+    
+    .btn-back:hover {
+      background: var(--primary);
+    }
+
+    .hud-title-wrap {
+      display: flex;
+      flex-direction: column;
+    }
+
+    .hud-title {
+      font-size: 15px;
+      font-weight: 800;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      color: var(--text-main);
+      text-shadow: 0 2px 4px rgba(0,0,0,0.5);
+    }
+
+    .hud-subtitle {
+      font-size: 11px;
+      color: var(--text-muted);
+      font-weight: 500;
+    }
+
+    .header-right {
+      display: flex;
+      gap: 8px;
+    }
+
+    .hud-btn {
+      padding: 10px 14px;
+      border-radius: 8px;
+      border: 1px solid var(--card-border);
+      background: rgba(13, 18, 30, 0.6);
+      color: var(--text-main);
+      font-size: 13px;
+      font-weight: 600;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      transition: all 0.2s;
+    }
+
+    .hud-btn:hover {
+      background: rgba(255,255,255,0.08);
+      border-color: rgba(255,255,255,0.15);
+    }
+
+    /* ── Middle HUD Info Blocks ───────────────────────────────────────────── */
+    .hud-middle {
+      display: flex;
+      flex: 1;
+      justify-content: space-between;
+      align-items: flex-start;
+      margin: 12px 0;
+      gap: 16px;
+      width: 100%;
+    }
+
+    /* Left Stats Box */
+    .hud-stats-panel {
+      padding: 16px;
+      min-width: 140px;
+      display: flex;
+      flex-direction: column;
+      gap: 12px;
+    }
+
+    .stat-item {
+      display: flex;
+      flex-direction: column;
+    }
+
+    .stat-label {
+      font-size: 10px;
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      color: var(--text-muted);
+    }
+
+    .stat-value {
+      font-size: 20px;
+      font-weight: 800;
+      color: var(--text-main);
+      font-family: 'JetBrains Mono', monospace;
+    }
+
+    .stat-unit {
+      font-size: 11px;
+      font-weight: 500;
+      color: var(--text-muted);
+      margin-left: 2px;
+    }
+
+    /* Live Target Overlay Box */
+    .ai-detection-hud {
+      flex: 1;
+      max-width: 320px;
+      padding: 16px;
+      text-align: center;
+      align-self: center;
+      margin: 0 auto;
+      border: 2.5px dashed rgba(255,255,255,0.1);
+      transition: all 0.2s;
+    }
+
+    .ai-detection-hud.scanning {
+      border-color: rgba(0, 97, 213, 0.4);
+      box-shadow: 0 0 16px rgba(0, 97, 213, 0.1);
+    }
+
+    .ai-detection-hud.detected {
+      border-style: solid;
+      animation: border-glow-pulse 1.5s infinite;
+    }
+
+    @keyframes border-glow-pulse {
+      0% { transform: scale(1); }
+      50% { transform: scale(1.03); }
+      100% { transform: scale(1); }
+    }
+
+    .ai-hud-label {
+      font-size: 11px;
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+      color: var(--text-muted);
+      margin-bottom: 4px;
+    }
+
+    .ai-hud-result {
+      font-size: 22px;
+      font-weight: 800;
+      margin: 6px 0;
+      transition: color 0.15s;
+    }
+
+    /* Mini Progress Bar */
+    .ai-hud-bar-wrap {
+      height: 6px;
+      background: rgba(255,255,255,0.1);
+      border-radius: 4px;
+      overflow: hidden;
+      margin: 8px 0;
+    }
+
+    .ai-hud-bar {
+      height: 100%;
+      width: 0%;
+      border-radius: 4px;
+      transition: width 0.1s ease-out, background-color 0.15s;
+    }
+
+    .ai-hud-meta {
+      font-size: 11px;
+      color: var(--text-muted);
+      font-family: 'JetBrains Mono', monospace;
+    }
+
+    /* Right Location Box */
+    .hud-location-panel {
+      padding: 16px;
+      max-width: 200px;
+      display: flex;
+      flex-direction: column;
+      gap: 10px;
+    }
+
+    .loc-row {
+      display: flex;
+      flex-direction: column;
+    }
+
+    .loc-val {
+      font-size: 12px;
+      font-weight: 600;
+      font-family: 'JetBrains Mono', monospace;
+      color: var(--text-main);
+      word-break: break-all;
+    }
+
+    .badge-status {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      padding: 4px 8px;
+      border-radius: 6px;
+      font-size: 11px;
+      font-weight: 700;
+      margin-top: 4px;
+    }
+
+    .badge-status.active {
+      background: rgba(16, 185, 129, 0.15);
+      color: var(--color-small);
+      border: 1px solid rgba(16, 185, 129, 0.3);
+    }
+    
+    .badge-status.inactive {
+      background: rgba(239, 68, 68, 0.15);
+      color: var(--color-large);
+      border: 1px solid rgba(239, 68, 68, 0.3);
+    }
+
+    /* ── Bottom HUD controls ──────────────────────────────────────────────── */
+    .hud-footer {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      width: 100%;
+      gap: 16px;
+      z-index: 11;
+    }
+
+    .footer-left {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .btn-sound-toggle {
+      width: 44px;
+      height: 44px;
+      border-radius: 10px;
+      border: 1px solid var(--card-border);
+      background: var(--card-glass);
+      color: var(--text-main);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      cursor: pointer;
+      font-size: 18px;
+      transition: background 0.2s;
+    }
+
+    .btn-sound-toggle.muted {
+      color: var(--color-large);
+    }
+
+    .btn-sound-toggle:not(.muted) {
+      color: var(--color-small);
+      box-shadow: 0 0 10px rgba(16, 185, 129, 0.2);
+    }
+
+    /* Drawer Toggle handle */
+    .btn-gallery-toggle {
+      flex: 1;
+      max-width: 220px;
+      padding: 12px;
+      border-radius: 12px;
+      border: 1px solid var(--card-border);
+      background: var(--card-glass);
+      color: var(--text-main);
+      font-size: 13px;
+      font-weight: 700;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      gap: 8px;
+      margin: 0 auto;
+      box-shadow: 0 4px 15px rgba(0,0,0,0.3);
+    }
+
+    .btn-gallery-toggle svg {
+      transition: transform 0.3s;
+    }
+
+    .btn-gallery-toggle.active svg {
+      transform: rotate(180deg);
+    }
+
+    /* ── Settings Panel Overlay ───────────────────────────────────────────── */
+    .settings-overlay {
+      position: absolute;
+      inset: 0;
+      z-index: 100;
+      background: rgba(7, 9, 14, 0.85);
+      backdrop-filter: blur(16px);
+      -webkit-backdrop-filter: blur(16px);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 20px;
+      opacity: 0;
+      pointer-events: none;
+      transition: opacity 0.25s ease;
+    }
+
+    .settings-overlay.visible {
+      opacity: 1;
+      pointer-events: auto;
+    }
+
+    .settings-card {
+      width: 100%;
+      max-width: 400px;
+      border: 1px solid var(--card-border);
+      border-radius: 16px;
+      background: var(--bg-dark);
+      padding: 24px;
+      box-shadow: 0 20px 50px rgba(0,0,0,0.6);
+    }
+
+    .settings-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      margin-bottom: 20px;
+      padding-bottom: 12px;
+      border-bottom: 1px solid rgba(255,255,255,0.06);
+    }
+
+    .settings-title {
+      font-size: 18px;
+      font-weight: 700;
+    }
+
+    .settings-close {
+      background: transparent;
+      border: none;
+      color: var(--text-muted);
+      cursor: pointer;
+      font-size: 20px;
+    }
+
+    .setting-group {
+      margin-bottom: 20px;
+    }
+
+    .setting-label-row {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      margin-bottom: 8px;
+    }
+
+    .setting-label {
+      font-size: 13px;
+      font-weight: 600;
+      color: var(--text-main);
+    }
+
+    .setting-value {
+      font-size: 12px;
+      font-weight: 700;
+      color: var(--primary);
+      font-family: 'JetBrains Mono', monospace;
+    }
+
+    .slider-input {
+      width: 100%;
+      height: 6px;
+      background: rgba(255,255,255,0.1);
+      border-radius: 4px;
+      outline: none;
+      -webkit-appearance: none;
+    }
+
+    .slider-input::-webkit-slider-thumb {
+      -webkit-appearance: none;
+      width: 18px;
+      height: 18px;
+      border-radius: 50%;
+      background: var(--primary);
+      cursor: pointer;
+      box-shadow: 0 0 8px rgba(0,97,213,0.5);
+    }
+
+    .setting-desc {
+      font-size: 11px;
+      color: var(--text-muted);
+      margin-top: 4px;
+      line-height: 1.4;
+    }
+
+    .btn-apply-settings {
+      width: 100%;
+      padding: 12px;
+      border-radius: 8px;
+      background: var(--primary);
+      color: #fff;
+      border: none;
+      font-size: 14px;
+      font-weight: 700;
+      cursor: pointer;
+      transition: background 0.2s;
+    }
+
+    .btn-apply-settings:hover {
+      background: #0052b3;
+    }
+
+    /* ── Sliding Session Log Drawer ───────────────────────────────────────── */
+    .gallery-drawer {
+      position: absolute;
+      left: 0;
+      right: 0;
+      bottom: 0;
+      height: 380px;
+      z-index: 50;
+      background: #0c121e;
+      border-top: 1px solid var(--card-border);
+      border-top-left-radius: 20px;
+      border-top-right-radius: 20px;
+      box-shadow: 0 -10px 40px rgba(0, 0, 0, 0.8);
+      transform: translateY(100%);
+      transition: transform 0.35s cubic-bezier(0.19, 1, 0.22, 1);
+      display: flex;
+      flex-direction: column;
+      overflow: hidden;
+    }
+
+    .gallery-drawer.open {
+      transform: translateY(0);
+    }
+
+    .drawer-header {
+      padding: 16px 20px;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      border-bottom: 1px solid rgba(255,255,255,0.06);
+    }
+
+    .drawer-title {
+      font-size: 15px;
+      font-weight: 700;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .drawer-count-badge {
+      background: rgba(255,255,255,0.1);
+      color: var(--text-main);
+      padding: 2px 8px;
+      border-radius: 12px;
+      font-size: 11px;
+      font-weight: 700;
+    }
+
+    .btn-clear-session {
+      font-size: 12px;
+      color: var(--color-large);
+      background: transparent;
+      border: none;
+      cursor: pointer;
+      font-weight: 600;
+    }
+
+    .drawer-body {
+      flex: 1;
+      overflow-y: auto;
+      padding: 16px;
+      -webkit-overflow-scrolling: touch;
+    }
+
+    /* Empty State */
+    .drawer-empty-state {
+      height: 100%;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      color: var(--text-muted);
+      font-size: 13px;
+      text-align: center;
+      padding: 40px;
+    }
+    
+    .empty-icon {
+      font-size: 32px;
+      margin-bottom: 12px;
+      opacity: 0.6;
+    }
+
+    /* Gallery List Grid */
+    .gallery-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(130px, 1fr));
+      gap: 12px;
+    }
+
+    .gallery-card {
+      background: rgba(255,255,255,0.03);
+      border: 1px solid rgba(255,255,255,0.06);
+      border-radius: 10px;
+      overflow: hidden;
+      display: flex;
+      flex-direction: column;
+    }
+
+    .gallery-thumb-container {
+      position: relative;
+      height: 90px;
+      background: #000;
+    }
+
+    .gallery-thumb {
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+    }
+
+    .gallery-size-tag {
+      position: absolute;
+      top: 6px;
+      left: 6px;
+      padding: 2px 6px;
+      border-radius: 4px;
+      font-size: 9px;
+      font-weight: 700;
+      color: #fff;
+    }
+
+    .gallery-info {
+      padding: 8px;
+      display: flex;
+      flex-direction: column;
+      gap: 4px;
+    }
+
+    .gallery-time {
+      font-size: 10px;
+      color: var(--text-muted);
+      font-weight: 500;
+    }
+
+    .gallery-coords {
+      font-size: 9px;
+      font-family: 'JetBrains Mono', monospace;
+      color: var(--primary);
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+
+    /* ── Hide canvas for frames ───────────────────────────────────────────── */
+    #frame-canvas {
+      display: none;
+    }
+
+    /* ── Screen layout support for desktop landscape testing ─────────────── */
+    @media (min-width: 768px) {
+      .hud-layer {
+        padding: 24px;
+      }
+      .hud-stats-panel {
+        min-width: 180px;
+      }
+      .hud-location-panel {
+        max-width: 280px;
+      }
+    }
+  </style>
+</head>
+<body>
+
+  <!-- Hidden canvas for grabbing frames -->
+  <canvas id="frame-canvas" width="400" height="300"></canvas>
+
+  <!-- Fullscreen Camera Preview -->
+  <div class="camera-container">
+    <video id="webcam-feed" autoplay playsinline muted></video>
+  </div>
+
+  <!-- Live bounding-box overlay (drawn by Roboflow detection engine) -->
+  <canvas id="detection-overlay"></canvas>
+
+  <!-- Screen Red Warning Vignette Flash on Detection -->
+  <div class="alert-overlay" id="alert-overlay"></div>
+
+  <!-- HUD Dashboard UI Overlays -->
+  <div class="hud-layer">
+    
+    <!-- HEADER BAR -->
+    <header class="hud-header">
+      <div class="header-left">
+        <button class="btn-back" id="btn-exit" title="Back to submission portal">
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+            <line x1="19" y1="12" x2="5" y2="12"></line>
+            <polyline points="12 19 5 12 12 5"></polyline>
+          </svg>
+        </button>
+        <div class="hud-title-wrap">
+          <h1 class="hud-title" id="hud-title-text">Dashcam Mode</h1>
+          <span class="hud-subtitle">Automatic Moving Vehicle Capture</span>
+        </div>
+      </div>
+      <div class="header-right">
+        <button class="hud-btn" id="btn-settings-open">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <circle cx="12" cy="12" r="3"></circle>
+            <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"></path>
+          </svg>
+          Settings
+        </button>
+      </div>
+    </header>
+
+    <!-- MIDDLE STATS & LIVE AI HUD overlay -->
+    <div class="hud-middle">
+      
+      <!-- Left Panel: Session Stats -->
+      <div class="glass-panel hud-stats-panel">
+        <div class="stat-item">
+          <span class="stat-label">Captured</span>
+          <span class="stat-value" id="stats-total-potholes">0</span>
+        </div>
+        <div class="stat-item">
+          <span class="stat-label">GPS Speed</span>
+          <span class="stat-value" id="stats-speed">0<span class="stat-unit">mph</span></span>
+        </div>
+        <div class="stat-item">
+          <span class="stat-label">Latency</span>
+          <span class="stat-value" id="stats-ai-latency">--<span class="stat-unit">ms</span></span>
+        </div>
+      </div>
+
+      <!-- Center Overlay: AI Live Bounding Target Box -->
+      <div class="glass-panel ai-detection-hud scanning" id="ai-detection-box">
+        <div class="ai-hud-label" id="ai-hud-status-text">Continuous Scanning</div>
+        <div class="ai-hud-result" id="ai-hud-result-label" style="color:var(--text-muted)">Searching...</div>
+        <div class="ai-hud-bar-wrap">
+          <div class="ai-hud-bar" id="ai-confidence-bar"></div>
+        </div>
+        <div class="ai-hud-meta" id="ai-hud-meta-text">Sample Rate: 1.0s</div>
+      </div>
+
+      <!-- Right Panel: GPS Live Location -->
+      <div class="glass-panel hud-location-panel">
+        <div class="loc-row">
+          <span class="stat-label">GPS Lock</span>
+          <div class="badge-status inactive" id="gps-lock-badge">
+            <span style="width: 6px; height: 6px; background: currentColor; border-radius: 50%;"></span>
+            No Signal
+          </div>
+        </div>
+        <div class="loc-row">
+          <span class="stat-label">Coordinates</span>
+          <span class="loc-val" id="hud-gps-coordinates">Waiting...</span>
+        </div>
+        <div class="loc-row">
+          <span class="stat-label">Precision</span>
+          <span class="loc-val" id="hud-gps-precision">--</span>
+        </div>
+        <div class="loc-row">
+          <span class="stat-label">Detected Ward</span>
+          <span class="loc-val" id="hud-detected-ward">--</span>
+        </div>
+      </div>
+
+    </div>
+
+    <!-- FOOTER HUD BAR -->
+    <footer class="hud-footer">
+      <div class="footer-left">
+        <!-- Audio trigger -->
+        <button class="btn-sound-toggle" id="btn-sound-toggle" title="Toggle audio feedback beeps">
+          🔊
+        </button>
+      </div>
+
+      <!-- Drawer Slide Handle -->
+      <button class="btn-gallery-toggle" id="btn-gallery-toggle">
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+          <polyline points="18 15 12 9 6 15"></polyline>
+        </svg>
+        Session Log
+        <span class="drawer-count-badge" id="stats-drawer-count">0</span>
+      </button>
+
+      <!-- Balanced spacing spacer -->
+      <div style="width:44px;"></div>
+    </footer>
+
+  </div>
+
+  <!-- Sliding Session Log Drawer Gallery -->
+  <div class="gallery-drawer" id="gallery-drawer">
+    <div class="drawer-header">
+      <div class="drawer-title">
+        Captured Session Log
+        <span class="drawer-count-badge" id="drawer-count-badge-total">0 items</span>
+      </div>
+      <button class="btn-clear-session" id="btn-clear-session-action">Clear Log</button>
+    </div>
+    
+    <div class="drawer-body">
+      <!-- Empty state initially -->
+      <div class="drawer-empty-state" id="drawer-empty-state">
+        <div class="empty-icon">🎥</div>
+        <p>No potholes auto-captured yet.</p>
+        <p style="font-size: 11px; margin-top: 4px; color: var(--text-muted)">Mount your phone on the dash and start driving. Detections will appear here in real time.</p>
+      </div>
+
+      <!-- Gallery Grid -->
+      <div class="gallery-grid" id="gallery-grid" style="display:none;"></div>
+    </div>
+  </div>
+
+  <!-- Settings Panel Modal -->
+  <div class="settings-overlay" id="settings-overlay">
+    <div class="settings-card">
+      <div class="settings-header">
+        <h3 class="settings-title">Dashcam Setup</h3>
+        <button class="settings-close" id="btn-settings-close">&times;</button>
+      </div>
+
+      <!-- Sample Interval -->
+      <div class="setting-group">
+        <div class="setting-label-row">
+          <span class="setting-label">AI Scanning Rate</span>
+          <span class="setting-value" id="settings-label-rate">1.0s</span>
+        </div>
+        <input type="range" class="slider-input" id="settings-rate" min="0.5" max="5.0" step="0.5" value="1.0" />
+        <p class="setting-desc">How often the camera feeds a frame to the AI. Lower means more frequent checks, consuming more battery.</p>
+      </div>
+
+      <!-- Confidence Threshold -->
+      <div class="setting-group">
+        <div class="setting-label-row">
+          <span class="setting-label">Capture Threshold</span>
+          <span class="setting-value" id="settings-label-threshold">72%</span>
+        </div>
+        <input type="range" class="slider-input" id="settings-threshold" min="30" max="95" step="5" value="72" />
+        <p class="setting-desc">Minimum confidence percentage required to auto-record a pothole detection.</p>
+      </div>
+
+      <!-- Detection engine selector -->
+      <div class="setting-group">
+        <label class="setting-label" style="display:block; margin-bottom: 8px;" for="settings-engine">Detection Engine</label>
+        <select id="settings-engine" style="width:100%; padding:10px; border-radius:6px; background:rgba(255,255,255,0.05); border:1px solid rgba(255,255,255,0.1); color:#fff; font-size:12px; outline:none;">
+          <option value="roboflow">Roboflow — Object Detection (boxes)</option>
+          <option value="teachable">Teachable Machine — Classification</option>
+        </select>
+        <p class="setting-desc">Roboflow draws real bounding boxes around each pothole. Teachable Machine classifies the whole frame.</p>
+      </div>
+
+      <!-- Roboflow config (shown when engine = roboflow) -->
+      <div class="setting-group" id="settings-roboflow-group">
+        <label class="setting-label" style="display:block; margin-bottom: 8px;" for="settings-rf-key">Roboflow Publishable Key</label>
+        <input type="text" id="settings-rf-key" placeholder="rf_xxx (publishable key, not the secret API key)" autocomplete="off" style="width:100%; padding:10px; border-radius:6px; background:rgba(255,255,255,0.05); border:1px solid rgba(255,255,255,0.1); color:#fff; font-size:12px; outline:none; margin-bottom:10px;" />
+        <div style="display:flex; gap:8px;">
+          <input type="text" id="settings-rf-model" placeholder="model id (e.g. pothole-detection-yolov8-ehkp9)" autocomplete="off" style="flex:1; min-width:0; padding:10px; border-radius:6px; background:rgba(255,255,255,0.05); border:1px solid rgba(255,255,255,0.1); color:#fff; font-size:12px; outline:none;" />
+          <input type="number" id="settings-rf-version" min="1" step="1" placeholder="ver" style="width:64px; padding:10px; border-radius:6px; background:rgba(255,255,255,0.05); border:1px solid rgba(255,255,255,0.1); color:#fff; font-size:12px; outline:none;" />
+        </div>
+        <p class="setting-desc">Get a free publishable key at roboflow.com (Settings → API Keys). Find a model id + version on any Roboflow Universe pothole project, or train your own. Runs fully in-browser.</p>
+      </div>
+
+      <!-- Teachable Machine config (shown when engine = teachable) -->
+      <div class="setting-group" id="settings-teachable-group">
+        <label class="setting-label" style="display:block; margin-bottom: 8px;" for="settings-model-url">Teachable Machine URL</label>
+        <input type="text" id="settings-model-url" style="width:100%; padding:10px; border-radius:6px; background:rgba(255,255,255,0.05); border:1px solid rgba(255,255,255,0.1); color:#fff; font-size:12px; outline:none;" />
+        <p class="setting-desc">Load custom Google Teachable Machine image classification models.</p>
+      </div>
+
+      <button class="btn-apply-settings" id="btn-settings-apply">Apply Configurations</button>
+    </div>
+  </div>
+
+  <!-- ── EXTERNAL LIBRARIES ────────────────────────────────────────────────── -->
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet/1.9.4/leaflet.min.js"></script>
+  <!--
+    Computer-vision engines are loaded lazily by dashcam-demo.js, on demand,
+    so only the selected engine's libraries are downloaded:
+      • Roboflow detection → https://cdn.roboflow.com/0.2.26/roboflow.js (bundles its own TFJS)
+      • Teachable Machine  → @tensorflow/tfjs + @teachablemachine/image
+    Loading both statically pulls two TensorFlow.js copies that clash, so we don't.
+  -->
+
+  <!-- ── DOMAIN HELPER SCRIPTS ──────────────────────────────────────────────── -->
+  <script src="gis.js"></script>
+  <script src="backend-api.js"></script>
+  <script src="box-upload.js"></script>
+
+  <!-- ── CORE APPLICATION CONTROLLER ───────────────────────────────────────── -->
+  <script src="dashcam-demo.js"></script>
+
+</body>
+</html>

dashcam-demo.js

@@ -0,0 +1,989 @@
+/**
+ * dashcam-demo.js — Real-Time Mobile Capture Controller
+ * Performs edge-inference AI classification on continuous video feed,
+ * tracks live coordinates, and handles spatial deduplication.
+ */
+
+'use strict';
+
+(function () {
+  // ─── CONFIGURATION & LOCAL STORAGE ───────────────────────────────────────
+  const CONFIG = {
+    engine: localStorage.getItem('dashcam_engine') || 'roboflow', // 'roboflow' | 'teachable'
+    modelUrl: localStorage.getItem('tm_model_url') || 'https://teachablemachine.withgoogle.com/models/3HQTi9DMo/',
+    rfKey: localStorage.getItem('roboflow_publishable_key') || '',
+    rfModel: localStorage.getItem('roboflow_model_id') || 'pothole-detection-yolov8-ehkp9',
+    rfVersion: parseInt(localStorage.getItem('roboflow_model_version') || '1', 10),
+    sampleRate: parseFloat(localStorage.getItem('dashcam_sample_rate') || '1.0'),
+    threshold: parseFloat(localStorage.getItem('dashcam_threshold') || '72'),
+    soundEnabled: localStorage.getItem('dashcam_sound_enabled') !== 'false'
+  };
+
+  // ─── APPLICATION STATE ───────────────────────────────────────────────────
+  const state = {
+    stream: null,
+    tmModel: null,
+    rfModel: null,        // Loaded Roboflow detection model
+    gpsWatcherId: null,
+    currentGPS: null,
+    lastDetections: [], // Cache for spatial deduplication { lat, lng, timestamp }
+    sessionCount: 0,
+    aiTimer: null,
+    isProcessing: false,
+    audioCtx: null
+  };
+
+  // ─── DOM REFERENCES ──────────────────────────────────────────────────────
+  const DOM = {
+    video: document.getElementById('webcam-feed'),
+    canvas: document.getElementById('frame-canvas'),
+    overlay: document.getElementById('alert-overlay'),
+    boxOverlay: document.getElementById('detection-overlay'),
+    
+    // Stats HUD
+    statsTotal: document.getElementById('stats-total-potholes'),
+    statsSpeed: document.getElementById('stats-speed'),
+    statsLatency: document.getElementById('stats-ai-latency'),
+    
+    // Detection Box HUD
+    aiBox: document.getElementById('ai-detection-box'),
+    aiStatusText: document.getElementById('ai-hud-status-text'),
+    aiResultLabel: document.getElementById('ai-hud-result-label'),
+    aiBar: document.getElementById('ai-confidence-bar'),
+    aiMetaText: document.getElementById('ai-hud-meta-text'),
+    
+    // Location HUD
+    gpsBadge: document.getElementById('gps-lock-badge'),
+    gpsCoords: document.getElementById('hud-gps-coordinates'),
+    gpsPrecision: document.getElementById('hud-gps-precision'),
+    detectedWard: document.getElementById('hud-detected-ward'),
+    
+    // Footer Controls
+    btnSound: document.getElementById('btn-sound-toggle'),
+    btnGallery: document.getElementById('btn-gallery-toggle'),
+    drawerCount: document.getElementById('stats-drawer-count'),
+    
+    // Drawer Gallery
+    drawer: document.getElementById('gallery-drawer'),
+    drawerCountTotal: document.getElementById('drawer-count-badge-total'),
+    drawerEmpty: document.getElementById('drawer-empty-state'),
+    galleryGrid: document.getElementById('gallery-grid'),
+    btnClearSession: document.getElementById('btn-clear-session-action'),
+    
+    // Settings Panel
+    settingsOverlay: document.getElementById('settings-overlay'),
+    btnSettingsOpen: document.getElementById('btn-settings-open'),
+    btnSettingsClose: document.getElementById('btn-settings-close'),
+    btnSettingsApply: document.getElementById('btn-settings-apply'),
+    
+    sliderRate: document.getElementById('settings-rate'),
+    sliderThreshold: document.getElementById('settings-threshold'),
+    inputModelUrl: document.getElementById('settings-model-url'),
+    selectEngine: document.getElementById('settings-engine'),
+    inputRfKey: document.getElementById('settings-rf-key'),
+    inputRfModel: document.getElementById('settings-rf-model'),
+    inputRfVersion: document.getElementById('settings-rf-version'),
+    groupRoboflow: document.getElementById('settings-roboflow-group'),
+    groupTeachable: document.getElementById('settings-teachable-group'),
+
+    labelRate: document.getElementById('settings-label-rate'),
+    labelThreshold: document.getElementById('settings-label-threshold'),
+    
+    btnExit: document.getElementById('btn-exit')
+  };
+
+  // ─── INIT SOUND (WEB AUDIO API) ──────────────────────────────────────────
+  function initAudioContext() {
+    if (!state.audioCtx) {
+      state.audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+    }
+    if (state.audioCtx.state === 'suspended') {
+      state.audioCtx.resume();
+    }
+  }
+
+  function playAlertBeep() {
+    if (!CONFIG.soundEnabled) return;
+    try {
+      initAudioContext();
+      const ctx = state.audioCtx;
+      
+      // Dual-tone high-frequency notification beep
+      const osc1 = ctx.createOscillator();
+      const osc2 = ctx.createOscillator();
+      const gainNode = ctx.createGain();
+
+      osc1.type = 'sine';
+      osc1.frequency.setValueAtTime(880, ctx.currentTime); // A5 note
+      osc1.frequency.exponentialRampToValueAtTime(1200, ctx.currentTime + 0.15);
+
+      osc2.type = 'triangle';
+      osc2.frequency.setValueAtTime(440, ctx.currentTime); // A4 note harmony
+      
+      gainNode.gain.setValueAtTime(0.25, ctx.currentTime);
+      gainNode.gain.exponentialRampToValueAtTime(0.01, ctx.currentTime + 0.2);
+
+      osc1.connect(gainNode);
+      osc2.connect(gainNode);
+      gainNode.connect(ctx.destination);
+
+      osc1.start();
+      osc2.start();
+      
+      osc1.stop(ctx.currentTime + 0.2);
+      osc2.stop(ctx.currentTime + 0.2);
+    } catch (e) {
+      console.warn('[Sound] Web Audio play failed:', e);
+    }
+  }
+
+  // ─── DYNAMIC SETTINGS SYNC ───────────────────────────────────────────────
+  function syncSettingsUI() {
+    DOM.sliderRate.value = CONFIG.sampleRate;
+    DOM.sliderThreshold.value = CONFIG.threshold;
+    DOM.inputModelUrl.value = CONFIG.modelUrl;
+
+    if (DOM.selectEngine) DOM.selectEngine.value = CONFIG.engine;
+    if (DOM.inputRfKey) DOM.inputRfKey.value = CONFIG.rfKey;
+    if (DOM.inputRfModel) DOM.inputRfModel.value = CONFIG.rfModel;
+    if (DOM.inputRfVersion) DOM.inputRfVersion.value = CONFIG.rfVersion;
+    toggleEngineSettingGroups();
+
+    DOM.labelRate.textContent = CONFIG.sampleRate + 's';
+    DOM.labelThreshold.textContent = CONFIG.threshold + '%';
+
+    DOM.aiMetaText.textContent = `Sample Rate: ${CONFIG.sampleRate}s`;
+
+    if (CONFIG.soundEnabled) {
+      DOM.btnSound.classList.remove('muted');
+      DOM.btnSound.textContent = '🔊';
+    } else {
+      DOM.btnSound.classList.add('muted');
+      DOM.btnSound.textContent = '🔇';
+    }
+  }
+
+  function toggleEngineSettingGroups() {
+    const engine = DOM.selectEngine ? DOM.selectEngine.value : CONFIG.engine;
+    if (DOM.groupRoboflow) DOM.groupRoboflow.style.display = engine === 'roboflow' ? 'block' : 'none';
+    if (DOM.groupTeachable) DOM.groupTeachable.style.display = engine === 'teachable' ? 'block' : 'none';
+  }
+
+  // ─── CAMERA ACCESS ───────────────────────────────────────────────────────
+  async function startCamera() {
+    if (state.stream) {
+      state.stream.getTracks().forEach(track => track.stop());
+    }
+
+    const constraints = {
+      audio: false,
+      video: {
+        facingMode: { ideal: 'environment' }, // Request back camera primarily
+        width: { ideal: 1280 },
+        height: { ideal: 720 }
+      }
+    };
+
+    try {
+      state.stream = await navigator.mediaDevices.getUserMedia(constraints);
+      DOM.video.srcObject = state.stream;
+      console.info('[Camera] Rear-facing environment camera stream loaded.');
+    } catch (err) {
+      console.warn('[Camera] Exact environment mode failed, falling back to basic camera constraints.', err);
+      try {
+        state.stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: false });
+        DOM.video.srcObject = state.stream;
+      } catch (fallbackErr) {
+        console.error('[Camera] WebRTC access denied or unavailable.', fallbackErr);
+        alert('Could not access device camera. Please verify camera permissions in settings.');
+      }
+    }
+  }
+
+  // ─── AI INFERENCE LOOP ───────────────────────────────────────────────────
+  // Lazily inject a <script> once and resolve when it has loaded. Used to pull
+  // each CV engine's libraries on demand so we never load two TFJS copies at once.
+  const loadedScripts = {};
+  function loadScriptOnce(src) {
+    if (loadedScripts[src]) return loadedScripts[src];
+    loadedScripts[src] = new Promise((resolve, reject) => {
+      const el = document.createElement('script');
+      el.src = src;
+      el.async = true;
+      el.onload = () => resolve();
+      el.onerror = () => { delete loadedScripts[src]; reject(new Error(`Failed to load ${src}`)); };
+      document.head.appendChild(el);
+    });
+    return loadedScripts[src];
+  }
+
+  const TFJS_SRC = 'https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@latest/dist/tf.min.js';
+  const TEACHABLE_SRC = 'https://cdn.jsdelivr.net/npm/@teachablemachine/image@latest/dist/teachablemachine-image.min.js';
+  const ROBOFLOW_SRC = 'https://cdn.roboflow.com/0.2.26/roboflow.js';
+
+  async function loadAIModel() {
+    // Reset any previously-loaded models so a fresh engine starts clean
+    state.tmModel = null;
+    state.rfModel = null;
+    clearDetectionOverlay();
+
+    if (CONFIG.engine === 'roboflow') {
+      await loadRoboflowModel();
+    } else {
+      await loadTeachableModel();
+    }
+  }
+
+  function setAiStatus(status, result, resultColor) {
+    DOM.aiStatusText.textContent = status;
+    DOM.aiResultLabel.textContent = result;
+    DOM.aiResultLabel.style.color = resultColor || 'var(--text-muted)';
+  }
+
+  async function loadTeachableModel() {
+    setAiStatus('Loading AI Model...', 'Initialising...');
+
+    const url = CONFIG.modelUrl.replace(/\/?$/, '/');
+    const modelURL = url + 'model.json';
+    const metadataURL = url + 'metadata.json';
+
+    try {
+      // Pull TFJS + Teachable Machine on demand (tfjs must load first)
+      await loadScriptOnce(TFJS_SRC);
+      await loadScriptOnce(TEACHABLE_SRC);
+      if (typeof tmImage === 'undefined') {
+        throw new Error('Teachable Machine CDN scripts did not load successfully.');
+      }
+      state.tmModel = await tmImage.load(modelURL, metadataURL);
+      console.info('[AI Model] Teachable Machine model loaded successfully from URL:', url);
+
+      setAiStatus('Continuous Scanning', 'Searching...');
+      DOM.aiBox.classList.remove('scanning');
+      DOM.aiBox.classList.add('scanning');
+    } catch (err) {
+      console.error('[AI Model] Teachable Machine loading failed:', err);
+      setAiStatus('AI Unavailable', 'Error Loading Model', 'var(--color-large)');
+    }
+  }
+
+  async function loadRoboflowModel() {
+    if (!CONFIG.rfKey) {
+      setAiStatus('Setup Required', 'Add Roboflow Key', 'var(--color-medium)');
+      DOM.aiMetaText.textContent = 'Open Settings → paste publishable key';
+      DOM.aiBox.classList.remove('scanning');
+      return;
+    }
+
+    setAiStatus('Loading AI Model...', `${CONFIG.rfModel} v${CONFIG.rfVersion}`);
+
+    try {
+      // Pull the Roboflow SDK on demand (bundles its own TFJS)
+      await loadScriptOnce(ROBOFLOW_SRC);
+      if (typeof roboflow === 'undefined') {
+        throw new Error('roboflow.js SDK did not initialise.');
+      }
+      const publishable = CONFIG.rfKey;
+      const model = await roboflow
+        .auth({ publishable_key: publishable })
+        .load({ model: CONFIG.rfModel, version: CONFIG.rfVersion });
+
+      // Map the capture threshold (e.g. 72%) into the model's confidence filter
+      if (typeof model.configure === 'function') {
+        model.configure({ threshold: Math.max(0.05, CONFIG.threshold / 100), overlap: 0.5, max_objects: 20 });
+      }
+
+      state.rfModel = model;
+      console.info('[AI Model] Roboflow model loaded:', CONFIG.rfModel, 'v' + CONFIG.rfVersion);
+
+      setAiStatus('Continuous Scanning', 'Searching...');
+      DOM.aiBox.classList.remove('scanning');
+      DOM.aiBox.classList.add('scanning');
+    } catch (err) {
+      console.error('[AI Model] Roboflow loading failed:', err);
+      setAiStatus('AI Unavailable', 'Model Load Failed', 'var(--color-large)');
+      DOM.aiMetaText.textContent = 'Check key, model id, and version in Settings';
+    }
+  }
+
+  function startPredictionTimer() {
+    if (state.aiTimer) clearInterval(state.aiTimer);
+
+    state.aiTimer = setInterval(async () => {
+      const ready = CONFIG.engine === 'roboflow' ? state.rfModel : state.tmModel;
+      if (!ready || state.isProcessing || DOM.video.paused || DOM.video.ended) return;
+
+      state.isProcessing = true;
+      try {
+        if (CONFIG.engine === 'roboflow') {
+          await runRoboflowPrediction();
+        } else {
+          await runTeachablePrediction();
+        }
+      } catch (err) {
+        console.warn('[Inference] Prediction loop encountered an error:', err);
+      } finally {
+        state.isProcessing = false;
+      }
+    }, CONFIG.sampleRate * 1000);
+  }
+
+  async function runTeachablePrediction() {
+    const t0 = performance.now();
+
+    // Draw video frame to hidden canvas
+    const ctx = DOM.canvas.getContext('2d');
+    ctx.drawImage(DOM.video, 0, 0, DOM.canvas.width, DOM.canvas.height);
+
+    // Run model prediction
+    const predictions = await state.tmModel.predict(DOM.canvas);
+    DOM.statsLatency.innerHTML = `${Math.round(performance.now() - t0)}<span class="stat-unit">ms</span>`;
+
+    const sorted = [...predictions].sort((a, b) => b.probability - a.probability);
+    const best = sorted[0];
+    const confPct = Math.round(best.probability * 100);
+
+    updateHUDClassification(best.className, confPct);
+
+    if (confPct >= CONFIG.threshold && ['Small', 'Medium', 'Large'].includes(best.className)) {
+      triggerPotholeDetection(best.className, best.probability);
+    }
+  }
+
+  async function runRoboflowPrediction() {
+    const t0 = performance.now();
+
+    // Roboflow detects directly on the live <video> element
+    const predictions = await state.rfModel.detect(DOM.video);
+    DOM.statsLatency.innerHTML = `${Math.round(performance.now() - t0)}<span class="stat-unit">ms</span>`;
+
+    // Keep only confident pothole boxes
+    const boxes = (Array.isArray(predictions) ? predictions : [])
+      .filter(p => p && p.bbox && Number.isFinite(p.confidence))
+      .sort((a, b) => b.confidence - a.confidence);
+
+    // Draw every box on the live overlay
+    drawDetectionBoxes(boxes);
+
+    if (!boxes.length) {
+      updateHUDClassification('Searching...', 0, true);
+      return;
+    }
+
+    const best = boxes[0];
+    const confPct = Math.round(best.confidence * 100);
+    const size = sizeFromBoundingBox(best.bbox);
+
+    updateHUDClassification(`${size} pothole`, confPct);
+
+    // Capture the strongest detection once it clears the threshold
+    if (confPct >= CONFIG.threshold) {
+      triggerPotholeDetection(size, best.confidence);
+    }
+  }
+
+  // Derive a Small/Medium/Large label from how much of the frame the box covers,
+  // so Roboflow detections flow through the same pipeline as Teachable Machine.
+  function sizeFromBoundingBox(bbox) {
+    const frameW = DOM.video.videoWidth || DOM.video.clientWidth || 1;
+    const frameH = DOM.video.videoHeight || DOM.video.clientHeight || 1;
+    const areaFraction = (bbox.width * bbox.height) / (frameW * frameH);
+    if (areaFraction >= 0.06) return 'Large';
+    if (areaFraction >= 0.02) return 'Medium';
+    return 'Small';
+  }
+
+  // ─── LIVE BOUNDING-BOX OVERLAY ────────────────────────────────────────────
+  const SIZE_BOX_COLORS = { Small: '#10b981', Medium: '#f59e0b', Large: '#ef4444' };
+
+  function clearDetectionOverlay() {
+    if (!DOM.boxOverlay) return;
+    const ctx = DOM.boxOverlay.getContext('2d');
+    ctx.clearRect(0, 0, DOM.boxOverlay.width, DOM.boxOverlay.height);
+  }
+
+  function drawDetectionBoxes(boxes) {
+    if (!DOM.boxOverlay) return;
+    const canvas = DOM.boxOverlay;
+    const ctx = canvas.getContext('2d');
+
+    // Match the canvas backing store to the displayed video size
+    const dispW = DOM.video.clientWidth || canvas.width;
+    const dispH = DOM.video.clientHeight || canvas.height;
+    if (canvas.width !== dispW || canvas.height !== dispH) {
+      canvas.width = dispW;
+      canvas.height = dispH;
+    }
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    if (!boxes || !boxes.length) return;
+
+    // The video uses object-fit: cover — replicate that mapping so boxes line up
+    const vidW = DOM.video.videoWidth || dispW;
+    const vidH = DOM.video.videoHeight || dispH;
+    const scale = Math.max(dispW / vidW, dispH / vidH);
+    const offsetX = (dispW - vidW * scale) / 2;
+    const offsetY = (dispH - vidH * scale) / 2;
+
+    ctx.font = '700 13px Inter, sans-serif';
+    ctx.textBaseline = 'bottom';
+
+    boxes.forEach(p => {
+      const size = sizeFromBoundingBox(p.bbox);
+      const color = SIZE_BOX_COLORS[size] || '#0061d5';
+      // bbox x/y is the box CENTER in source-video pixels
+      const w = p.bbox.width * scale;
+      const h = p.bbox.height * scale;
+      const x = offsetX + (p.bbox.x * scale) - w / 2;
+      const y = offsetY + (p.bbox.y * scale) - h / 2;
+
+      ctx.strokeStyle = color;
+      ctx.lineWidth = 3;
+      ctx.strokeRect(x, y, w, h);
+
+      const label = `${size} ${Math.round((p.confidence || 0) * 100)}%`;
+      ctx.font = '700 13px Inter, sans-serif';
+      const padX = 6;
+      const tw = ctx.measureText(label).width + padX * 2;
+      const labelY = y > 20 ? y : y + h + 20;
+      ctx.fillStyle = color;
+      ctx.fillRect(x, labelY - 18, tw, 18);
+      ctx.fillStyle = '#fff';
+      ctx.fillText(label, x + padX, labelY - 3);
+    });
+  }
+
+  function updateHUDClassification(label, confidence, idle = false) {
+    if (idle) {
+      DOM.aiResultLabel.textContent = label;
+      DOM.aiResultLabel.style.color = 'var(--text-muted)';
+      DOM.aiBar.style.width = '0%';
+      DOM.aiBar.style.backgroundColor = 'var(--color-not-pothole)';
+      DOM.aiBox.classList.remove('detected');
+      return;
+    }
+
+    DOM.aiResultLabel.textContent = `${label} (${confidence}%)`;
+    DOM.aiBar.style.width = `${confidence}%`;
+
+    // Color by detected size (works for both 'Large' and 'Large pothole' labels)
+    let sizeColor = null;
+    if (/small/i.test(label)) sizeColor = 'var(--color-small)';
+    else if (/medium/i.test(label)) sizeColor = 'var(--color-medium)';
+    else if (/large/i.test(label)) sizeColor = 'var(--color-large)';
+
+    if (confidence < CONFIG.threshold || !sizeColor) {
+      DOM.aiResultLabel.style.color = 'var(--text-muted)';
+      DOM.aiBar.style.backgroundColor = 'var(--color-not-pothole)';
+      DOM.aiBox.classList.remove('detected');
+    } else {
+      DOM.aiResultLabel.style.color = sizeColor;
+      DOM.aiBar.style.backgroundColor = sizeColor;
+      DOM.aiBox.classList.add('detected');
+    }
+  }
+
+  // ─── GEOLOCATION WATCHER ────────────────────────────────────────────────
+  function startGPSWatcher() {
+    if (!navigator.geolocation) {
+      console.warn('[GPS] Geolocation API not supported by browser.');
+      updateGPSHUDStatus(false);
+      return;
+    }
+
+    updateGPSHUDStatus(false);
+    DOM.gpsCoords.textContent = 'Locking...';
+
+    state.gpsWatcherId = navigator.geolocation.watchPosition(
+      async (position) => {
+        const lat = position.coords.latitude;
+        const lng = position.coords.longitude;
+        const accuracy = position.coords.accuracy || 0;
+        const speedMps = position.coords.speed || 0; // Speed in meters per second
+
+        state.currentGPS = { lat, lng, accuracy, speedMps };
+
+        updateGPSHUDStatus(true);
+        DOM.gpsCoords.textContent = `${lat.toFixed(6)}, ${lng.toFixed(6)}`;
+        DOM.gpsPrecision.textContent = `± ${accuracy.toFixed(1)} m`;
+
+        // Calculate speed in MPH
+        const speedMph = Math.round(speedMps * 2.23694);
+        DOM.statsSpeed.innerHTML = `${speedMph}<span class="stat-unit">mph</span>`;
+
+        // Retrieve regional boundary ward info if GIS config exists
+        try {
+          if (typeof window.resolveGISMapping === 'function') {
+            const gisMapping = await window.resolveGISMapping(lat, lng, { fallbackArea: '' });
+            const detectedWard = gisMapping.ward || gisMapping.district || gisMapping.zone || 'Global Domain';
+            DOM.detectedWard.textContent = detectedWard;
+          } else {
+            // Local simple Philly ward bounds detection
+            const localWard = detectPhillyWardLocal(lat, lng);
+            DOM.detectedWard.textContent = localWard || 'Metro Area';
+          }
+        } catch (e) {
+          DOM.detectedWard.textContent = 'Metro Region';
+        }
+      },
+      (err) => {
+        console.warn('[GPS] Error locked or denied:', err);
+        updateGPSHUDStatus(false);
+        DOM.gpsCoords.textContent = 'No GPS Signal';
+        DOM.gpsPrecision.textContent = '--';
+        DOM.statsSpeed.innerHTML = `0<span class="stat-unit">mph</span>`;
+      },
+      { enableHighAccuracy: true, timeout: 8000, maximumAge: 0 }
+    );
+  }
+
+  function updateGPSHUDStatus(isLocked) {
+    if (isLocked) {
+      DOM.gpsBadge.className = 'badge-status active';
+      DOM.gpsBadge.innerHTML = `<span style="width:6px;height:6px;background:currentColor;border-radius:50%;"></span>GPS Locked`;
+    } else {
+      DOM.gpsBadge.className = 'badge-status inactive';
+      DOM.gpsBadge.innerHTML = `<span style="width:6px;height:6px;background:currentColor;border-radius:50%;"></span>No Signal`;
+    }
+  }
+
+  function detectPhillyWardLocal(lat, lng) {
+    if (lat > 40.04 && lng > -75.07) return 'Northeast';
+    if (lat > 40.02 && lng < -75.17) return 'Northwest';
+    if (lat > 40.02 && lng >= -75.17 && lng <= -75.07) return 'North';
+    if (lat >= 39.97 && lat <= 40.02 && lng >= -75.20 && lng <= -75.14) return 'Lower North';
+    if (lat >= 39.94 && lat <= 40.04 && lng < -75.18) return 'West';
+    if (lat >= 39.95 && lat <= 40.02 && lng > -75.09) return 'River Wards';
+    if (lat >= 39.94 && lat <= 40.02 && lng >= -75.18 && lng <= -75.09) return 'Central';
+    if (lat >= 39.90 && lat <= 39.95 && lng >= -75.20 && lng <= -75.10) return 'South';
+    if (lat < 39.94 && lng < -75.15) return 'Southwest';
+    return null;
+  }
+
+  // ─── SPATIAL DEDUPLICATION & DETECTIONS ───────────────────────────────────
+  function haversineDistance(lat1, lon1, lat2, lon2) {
+    const R = 6371000; // Earth radius in meters
+    const phi1 = lat1 * Math.PI / 180;
+    const phi2 = lat2 * Math.PI / 180;
+    const deltaPhi = (lat2 - lat1) * Math.PI / 180;
+    const deltaLambda = (lon2 - lon1) * Math.PI / 180;
+    
+    const a = Math.sin(deltaPhi / 2) ** 2 + Math.cos(phi1) * Math.cos(phi2) * Math.sin(deltaLambda / 2) ** 2;
+    return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+  }
+
+  function checkDeduplication(newLat, newLng) {
+    const now = Date.now();
+    const COOL_DOWN_RADIUS = 15; // meters
+    const COOL_DOWN_TIME = 4000; // milliseconds
+    
+    // Clean expired cooldown entries
+    state.lastDetections = state.lastDetections.filter(d => now - d.timestamp < COOL_DOWN_TIME);
+
+    // Scan for collisions
+    for (const d of state.lastDetections) {
+      const dist = haversineDistance(d.lat, d.lng, newLat, newLng);
+      if (dist <= COOL_DOWN_RADIUS) {
+        return false; // Suppressed: duplicate found in close proximity and timeframe
+      }
+    }
+    return true; // Approved: new unique detection
+  }
+
+  // Helper: Convert base64 data to Blob object for box-upload
+  function dataURLtoBlob(dataurl) {
+    const arr = dataurl.split(',');
+    const mime = arr[0].match(/:(.*?);/)[1];
+    const bstr = atob(arr[1]);
+    let n = bstr.length;
+    const u8arr = new Uint8Array(n);
+    while (n--) {
+      u8arr[n] = bstr.charCodeAt(n);
+    }
+    return new Blob([u8arr], { type: mime });
+  }
+
+  function generateCaseId() {
+    const city = localStorage.getItem('city_name') || '';
+    const prefix = (city.replace(/[^A-Za-z]/g, '').slice(0, 3) || 'POT').toUpperCase();
+    const datePart = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+    const randomPart = Math.random().toString(36).substring(2, 8).toUpperCase();
+    return `${prefix}-${datePart}-${randomPart}`;
+  }
+
+  // ─── OFFLINE PERSISTENT UPLOAD QUEUE ─────────────────────────────────────
+  let isQueueRunning = false;
+
+  function getPendingUploads() {
+    try {
+      return JSON.parse(localStorage.getItem('dashcam_pending_uploads') || '[]');
+    } catch (e) {
+      return [];
+    }
+  }
+
+  function savePendingUploads(queue) {
+    localStorage.setItem('dashcam_pending_uploads', JSON.stringify(queue));
+  }
+
+  function saveToHistory(record) {
+    try {
+      const history = JSON.parse(localStorage.getItem('submitted_cases') || '[]');
+      const idx = history.findIndex(x => x.caseId === record.caseId);
+      if (idx >= 0) {
+        history[idx] = record;
+      } else {
+        history.push(record);
+      }
+      localStorage.setItem('submitted_cases', JSON.stringify(history));
+    } catch (e) {
+      console.warn('[Queue] Failed saving to history:', e);
+    }
+  }
+
+  async function processUploadQueue() {
+    if (isQueueRunning) return;
+    const queue = getPendingUploads();
+    if (queue.length === 0) return;
+
+    isQueueRunning = true;
+    console.log(`[Queue] Processing ${queue.length} pending dashcam uploads...`);
+
+    for (const item of queue) {
+      updateGalleryCardStatus(item.caseId, 'syncing');
+      try {
+        const blob = dataURLtoBlob(item.photoDataUrl);
+        
+        // 1. Submit to Box (uploads photo and metadata sidecar)
+        let uploadResult = null;
+        if (window.BoxUpload) {
+          uploadResult = await window.BoxUpload.submitToBox(blob, item.metadata);
+        }
+
+        const success = uploadResult ? uploadResult.success : false;
+        
+        if (success) {
+          console.log(`[Queue] Box upload success for case: ${item.caseId}`);
+          
+          // 2. Build full case record for backend database
+          const caseRecord = {
+            caseId: item.caseId,
+            status: 'Submitted',
+            ts: item.timestampMs,
+            timestamp: item.timestampIso,
+            report: {
+              ...item.metadata,
+              photoFileId: uploadResult.photoFileId || '',
+              sidecarFileId: uploadResult.sidecarFileId || ''
+            }
+          };
+
+          // 3. Upsert to backend database so app stays fast
+          if (window.PotholeBackend) {
+            await window.PotholeBackend.upsertCase(caseRecord);
+            console.log(`[Queue] Backend database sync success for case: ${item.caseId}`);
+          }
+
+          // 4. Update local submission history
+          saveToHistory(caseRecord);
+
+          // Remove from pending queue
+          const currentQueue = getPendingUploads().filter(x => x.caseId !== item.caseId);
+          savePendingUploads(currentQueue);
+          
+          updateGalleryCardStatus(item.caseId, 'uploaded');
+        } else {
+          // If Box config is disabled/broken, we fallback to uploading directly to Node database!
+          const errorMsg = uploadResult?.error || '';
+          if (errorMsg.includes('Box is not configured') || errorMsg.includes('Box authentication')) {
+            console.log(`[Queue] Box config unavailable. Saving directly to backend database for: ${item.caseId}`);
+            
+            const caseRecord = {
+              caseId: item.caseId,
+              status: 'Submitted',
+              ts: item.timestampMs,
+              timestamp: item.timestampIso,
+              report: item.metadata
+            };
+
+            if (window.PotholeBackend) {
+              await window.PotholeBackend.upsertCase(caseRecord);
+              console.log(`[Queue] Saved directly to database successfully: ${item.caseId}`);
+            }
+
+            saveToHistory(caseRecord);
+
+            const currentQueue = getPendingUploads().filter(x => x.caseId !== item.caseId);
+            savePendingUploads(currentQueue);
+            
+            updateGalleryCardStatus(item.caseId, 'uploaded');
+          } else {
+            throw new Error(errorMsg || 'Box upload failed.');
+          }
+        }
+      } catch (err) {
+        console.warn(`[Queue] Upload failed for case ${item.caseId}. Retrying later.`, err);
+        updateGalleryCardStatus(item.caseId, 'failed');
+        // Stop queue runner immediately on failure (network is likely offline or weak)
+        break;
+      }
+    }
+    isQueueRunning = false;
+  }
+
+  function triggerPotholeDetection(size, confidence) {
+    const lat = state.currentGPS ? state.currentGPS.lat : 39.9526; // Default to Philly center if offline
+    const lng = state.currentGPS ? state.currentGPS.lng : -75.1652;
+    
+    // Evaluate spatial deduplication
+    const isNewUnique = checkDeduplication(lat, lng);
+    if (!isNewUnique) {
+      console.log(`[Deduplication] Pothole capture suppressed inside 15m radius cooldown at (${lat.toFixed(5)}, ${lng.toFixed(5)}).`);
+      return;
+    }
+
+    // Capture success — register coordinates in spatial index
+    state.lastDetections.push({ lat, lng, timestamp: Date.now() });
+
+    // Snap a fresh frame from the live video into the hidden canvas, then export.
+    // (The Roboflow engine detects on the <video> directly and never touches this
+    // canvas, so we must draw the current frame here for an accurate snapshot.)
+    try {
+      const snapCtx = DOM.canvas.getContext('2d');
+      snapCtx.drawImage(DOM.video, 0, 0, DOM.canvas.width, DOM.canvas.height);
+    } catch (e) {
+      console.warn('[Capture] could not draw video frame to snapshot canvas:', e);
+    }
+    const imageBase64 = DOM.canvas.toDataURL('image/jpeg', 0.82);
+
+    // Audio & Screen Flash visual alert
+    playAlertBeep();
+    DOM.overlay.classList.remove('flash');
+    void DOM.overlay.offsetWidth; // Force CSS reflow
+    DOM.overlay.classList.add('flash');
+
+    state.sessionCount++;
+    DOM.statsTotal.textContent = state.sessionCount;
+    DOM.drawerCount.textContent = state.sessionCount;
+    DOM.drawerCountTotal.textContent = `${state.sessionCount} items`;
+
+    const caseId = generateCaseId();
+    const timestampIso = new Date().toISOString();
+    const timestampMs = Date.now();
+
+    // Build Case Metadata
+    const metadata = {
+      caseId,
+      timestamp: timestampIso,
+      city: localStorage.getItem('city_name') || 'Philadelphia',
+      department: localStorage.getItem('dept_name') || 'Department of Streets',
+      description: 'Auto-captured from moving vehicle.',
+      anonymous: true,
+      location: { lat, lng, source: 'device' },
+      locationSource: 'device',
+      address: DOM.gpsCoords.textContent !== 'Waiting...' ? (state.address || DOM.gpsCoords.textContent) : 'Windshield Capture',
+      ward: DOM.detectedWard.textContent !== '--' ? DOM.detectedWard.textContent : 'Metro Area',
+      aiResult: size,
+      aiConfidence: parseFloat(confidence.toFixed(4))
+    };
+
+    // Add entry to persistent upload queue
+    const queue = getPendingUploads();
+    queue.push({
+      caseId,
+      metadata,
+      photoDataUrl: imageBase64,
+      timestampIso,
+      timestampMs
+    });
+    savePendingUploads(queue);
+
+    // Add entry to UI gallery (starts as queued)
+    addPotholeToGallery(caseId, size, confidence, lat, lng, imageBase64, 'queued');
+
+    // Trigger queue runner immediately
+    processUploadQueue();
+  }
+
+  function addPotholeToGallery(caseId, size, confidence, lat, lng, imageData, status = 'queued') {
+    // Hide empty state
+    DOM.drawerEmpty.style.display = 'none';
+    DOM.galleryGrid.style.display = 'grid';
+
+    const timestamp = new Date().toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+    const sizeColors = { Small: '#10b981', Medium: '#f59e0b', Large: '#ef4444' };
+    const color = sizeColors[size] || '#6b7280';
+    const confPct = Math.round(confidence * 100);
+
+    const card = document.createElement('div');
+    card.className = 'gallery-card';
+    card.id = `card-${caseId}`;
+
+    const statusText = status === 'uploaded' ? '☁️ Sync Complete' : status === 'syncing' ? '🔄 Syncing' : status === 'failed' ? '❌ Weak Signal' : '⏳ Queued';
+    const statusBg = status === 'uploaded' ? 'rgba(16, 185, 129, 0.15)' : status === 'syncing' ? 'rgba(245, 158, 11, 0.15)' : status === 'failed' ? 'rgba(239, 68, 68, 0.15)' : 'rgba(255, 255, 255, 0.08)';
+    const statusColor = status === 'uploaded' ? '#10b981' : status === 'syncing' ? '#f59e0b' : status === 'failed' ? '#ef4444' : '#9ca3af';
+
+    card.innerHTML = `
+      <div class="gallery-thumb-container">
+        <img src="${imageData}" class="gallery-thumb" alt="Captured Pothole" />
+        <span class="gallery-size-tag" style="background:${color}">${size} (${confPct}%)</span>
+      </div>
+      <div class="gallery-info">
+        <span class="gallery-time">🕒 ${timestamp}</span>
+        <span class="gallery-coords">${lat.toFixed(5)}, ${lng.toFixed(5)}</span>
+        <span id="sync-tag-${caseId}" style="display:inline-block; font-size:10px; font-weight:700; padding:2px 6px; border-radius:4px; margin-top:6px; background:${statusBg}; color:${statusColor}; text-transform:uppercase; text-align:center;">
+          ${statusText}
+        </span>
+      </div>
+    `;
+
+    // Prepend to display latest first
+    DOM.galleryGrid.insertBefore(card, DOM.galleryGrid.firstChild);
+  }
+
+  function updateGalleryCardStatus(caseId, status) {
+    const el = document.getElementById(`sync-tag-${caseId}`);
+    if (!el) return;
+    
+    const statusText = status === 'uploaded' ? '☁️ Sync Complete' : status === 'syncing' ? '🔄 Syncing' : status === 'failed' ? '❌ Weak Signal' : '⏳ Queued';
+    const statusBg = status === 'uploaded' ? 'rgba(16, 185, 129, 0.15)' : status === 'syncing' ? 'rgba(245, 158, 11, 0.15)' : status === 'failed' ? 'rgba(239, 68, 68, 0.15)' : 'rgba(255, 255, 255, 0.08)';
+    const statusColor = status === 'uploaded' ? '#10b981' : status === 'syncing' ? '#f59e0b' : status === 'failed' ? '#ef4444' : '#9ca3af';
+
+    el.textContent = statusText;
+    el.style.background = statusBg;
+    el.style.color = statusColor;
+  }
+
+  // ─── USER INTERFACE CONTROLS & EVENTS ───────────────────────────────────
+  function wireEvents() {
+    // Exit button
+    DOM.btnExit.addEventListener('click', () => {
+      // Clear interval and GPS watchers
+      if (state.aiTimer) clearInterval(state.aiTimer);
+      if (state.gpsWatcherId) navigator.geolocation.clearWatch(state.gpsWatcherId);
+      
+      // Stop camera tracks
+      if (state.stream) {
+        state.stream.getTracks().forEach(track => track.stop());
+      }
+      
+      // Navigate back
+      window.location.href = 'index.html';
+    });
+
+    // Sound toggle button
+    DOM.btnSound.addEventListener('click', () => {
+      CONFIG.soundEnabled = !CONFIG.soundEnabled;
+      localStorage.setItem('dashcam_sound_enabled', CONFIG.soundEnabled);
+      initAudioContext();
+      syncSettingsUI();
+    });
+
+    // Drawer gallery slide toggle
+    DOM.btnGallery.addEventListener('click', () => {
+      DOM.drawer.classList.toggle('open');
+      DOM.btnGallery.classList.toggle('active');
+    });
+
+    // Settings overlay toggle
+    DOM.btnSettingsOpen.addEventListener('click', () => {
+      DOM.settingsOverlay.classList.add('visible');
+    });
+
+    DOM.btnSettingsClose.addEventListener('click', () => {
+      DOM.settingsOverlay.classList.remove('visible');
+    });
+
+    // Engine selector toggles which config block is visible
+    if (DOM.selectEngine) {
+      DOM.selectEngine.addEventListener('change', toggleEngineSettingGroups);
+    }
+
+    // Apply Settings
+    DOM.btnSettingsApply.addEventListener('click', () => {
+      const newRate = parseFloat(DOM.sliderRate.value);
+      const newThreshold = parseFloat(DOM.sliderThreshold.value);
+      const newUrl = DOM.inputModelUrl.value.trim();
+      const newEngine = DOM.selectEngine ? DOM.selectEngine.value : CONFIG.engine;
+      const newRfKey = DOM.inputRfKey ? DOM.inputRfKey.value.trim() : CONFIG.rfKey;
+      const newRfModel = DOM.inputRfModel ? DOM.inputRfModel.value.trim() : CONFIG.rfModel;
+      const newRfVersion = DOM.inputRfVersion ? (parseInt(DOM.inputRfVersion.value, 10) || 1) : CONFIG.rfVersion;
+
+      let modelChanged = false;
+      if (newEngine !== CONFIG.engine) { CONFIG.engine = newEngine; localStorage.setItem('dashcam_engine', newEngine); modelChanged = true; }
+      if (newUrl !== CONFIG.modelUrl) { CONFIG.modelUrl = newUrl; localStorage.setItem('tm_model_url', newUrl); modelChanged = true; }
+      if (newRfKey !== CONFIG.rfKey) { CONFIG.rfKey = newRfKey; localStorage.setItem('roboflow_publishable_key', newRfKey); modelChanged = true; }
+      if (newRfModel !== CONFIG.rfModel) { CONFIG.rfModel = newRfModel; localStorage.setItem('roboflow_model_id', newRfModel); modelChanged = true; }
+      if (newRfVersion !== CONFIG.rfVersion) { CONFIG.rfVersion = newRfVersion; localStorage.setItem('roboflow_model_version', String(newRfVersion)); modelChanged = true; }
+
+      const thresholdChanged = newThreshold !== CONFIG.threshold;
+      CONFIG.sampleRate = newRate;
+      CONFIG.threshold = newThreshold;
+      localStorage.setItem('dashcam_sample_rate', newRate);
+      localStorage.setItem('dashcam_threshold', newThreshold);
+
+      syncSettingsUI();
+      DOM.settingsOverlay.classList.remove('visible');
+
+      if (modelChanged) {
+        loadAIModel();
+      } else if (thresholdChanged && CONFIG.engine === 'roboflow' && state.rfModel && typeof state.rfModel.configure === 'function') {
+        // Re-apply confidence filter without re-downloading the model
+        state.rfModel.configure({ threshold: Math.max(0.05, CONFIG.threshold / 100), overlap: 0.5, max_objects: 20 });
+      }
+      startPredictionTimer();
+    });
+
+    // Live slider values display
+    DOM.sliderRate.addEventListener('input', () => {
+      DOM.labelRate.textContent = DOM.sliderRate.value + 's';
+    });
+
+    DOM.sliderThreshold.addEventListener('input', () => {
+      DOM.labelThreshold.textContent = DOM.sliderThreshold.value + '%';
+    });
+
+    // Clear session log
+    DOM.btnClearSession.addEventListener('click', () => {
+      if (confirm('Are you sure you want to clear the captured session log?')) {
+        DOM.galleryGrid.innerHTML = '';
+        DOM.galleryGrid.style.display = 'none';
+        DOM.drawerEmpty.style.display = 'flex';
+        state.sessionCount = 0;
+        
+        DOM.statsTotal.textContent = '0';
+        DOM.drawerCount.textContent = '0';
+        DOM.drawerCountTotal.textContent = '0 items';
+
+        // Also clear any unsent uploads
+        savePendingUploads([]);
+      }
+    });
+
+    // Tap target on video to trigger audio permission initialization
+    DOM.video.addEventListener('click', () => {
+      initAudioContext();
+    });
+  }
+
+  // ─── STARTUP ─────────────────────────────────────────────────────────────
+  async function init() {
+    syncSettingsUI();
+    wireEvents();
+    
+    await startCamera();
+    await loadAIModel();
+    
+    startPredictionTimer();
+    startGPSWatcher();
+
+    // Start background queue processing runner loop (every 12 seconds)
+    setInterval(processUploadQueue, 12000);
+    // Process anything remaining from prior session on boot
+    processUploadQueue();
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();