Upload folder using huggingface_hub

benchmark_summary_for_submission.md

@@ -14,7 +14,7 @@ Show measurable improvement and reliability across:
 Recommended judge deployment:
 - API/UI: Docker via `docker-compose.landfillsentry.yml`
 - imagery: DPhi SimSat live API
-- inference: Hugging Face Transformers + optional PEFT adapter
+- inference: Hugging Face Transformers + PEFT adapter (`akashreddy2103/landfill`)
 
 Preflight:
 ```bash

docs/Judging_Gap_Closure_Plan.md

@@ -0,0 +1,174 @@
+# LandfillSentry Judge-Guideline Gap Closure Plan
+
+Date: April 22, 2026  
+Scope: Backend + Frontend + live-data reliability + demo readiness + fine-tuning evidence
+
+## 1) Judge Criteria to Delivery Map
+
+| Judge Criterion | Weight | Current Risk | Required State for Scoring |
+|---|---:|---|---|
+| Use of Satellite Imagery | 10% | Medium | DPhi/SimSat imagery is the primary source in every scan path, with visible provenance and timestamps in UI/API artifacts. |
+| Innovation + Problem/Solution Fit | 35% | Medium-High | Clear domain narrative: satellite-first triage + LFM2-VL reasoning + optional field dongle verification loop. |
+| Technical Implementation | 35% | High | One-command run, no judge debugging, stable live scan and review workflow, deterministic failure messaging. |
+| Demo + Communication | 20% | Medium | End-to-end live demo script, architecture explanation, fallback policy explained without ambiguity. |
+
+## 2) Current Gaps (Observed)
+
+1. Live vs fallback confusion:
+- older fallback/mock incidents may still exist in DB history
+- users need explicit provenance and generation mode visibility
+
+2. Frontend UX quality:
+- engineering labels can leak into user-facing names
+- operator intent must be clearer than raw backend fields
+
+3. Runtime reliability:
+- live scans can fail when SimSat/Mapbox/model output is unavailable or invalid
+- judge mode must fail fast and clearly (never pretend fallback is live)
+
+4. Demo readiness:
+- judges need a repeatable one-command startup + smoke check flow
+
+## 3) Required Changes by Criterion
+
+## 3.1 Use of Satellite Imagery (10%)
+
+### Must Have Status
+- [x] Expose imagery provenance in every incident:
+  - `source_chain`
+  - per-asset capture timestamps
+  - `live_fetch_status`
+- [x] UI transparency:
+  - `Live Imagery Provenance` section in site detail
+  - `generation mode` visible in summary
+
+### Files Updated
+- `apps/api/routes/api.py`
+- `apps/api/services/imagery_service.py`
+- `apps/web/public/ops-app.jsx`
+
+### Acceptance
+- [x] For displayed incidents, UI shows provenance fields and generation mode.
+
+---
+
+## 3.2 Innovation + Problem/Solution Fit (35%)
+
+### Must Have Status
+- [x] Product story signals in-app:
+  - why alert exists (incident summary text)
+  - what to inspect first (recommended follow-up/export)
+  - confidence visibility
+- [x] Dongle integration path:
+  - methane reading ingest endpoint
+  - attach reading to incident as `ground_truth_hint`
+  - UI badge: `Satellite-only` vs `Satellite + Dongle corroborated`
+- [ ] OpenAPI artifact refreshed to include latest dongle routes
+
+### Files Updated
+- `apps/api/routes/api.py`
+- `apps/api/db/repository.py`
+- `apps/api/schemas/models.py`
+- `apps/web/public/ops-app.jsx`
+- `tests/test_phase8_ui_workflow.py`
+
+### Acceptance
+- [x] One incident can show satellite evidence + attached dongle reading in UI and export.
+
+---
+
+## 3.3 Technical Implementation (35%)
+
+### Must Have Status
+- [x] Strict live-only policy for judge mode:
+  - `REQUIRE_LIVE_RESULTS=true` gating
+  - strict scan selection for live-generated results in watchlist/detail
+  - actionable fast-fail for non-live runtime mismatch
+- [x] One-command run script:
+  - `scripts/start_judge_mode.ps1`
+- [x] Deterministic smoke tests:
+  - `scripts/live_smoke.py` checks health, scan, live mode, previews, review persistence, export
+- [x] Fallback ambiguity removed:
+  - fallback only when explicitly enabled
+  - strict mode rejects invalid live outputs
+
+### Files Updated
+- `scripts/start_judge_mode.ps1`
+- `scripts/live_smoke.py`
+- `apps/api/config.py`
+- `apps/api/routes/api.py`
+- `apps/api/services/inference_service.py`
+- `README.md`
+- `tests/test_phase5_inference.py`
+
+### Acceptance
+- [x] Fresh-machine style startup + smoke workflow exists and is documented.
+
+---
+
+## 3.4 Demo + Communication (20%)
+
+### Must Have Status
+- [x] 5-minute demo sequence documented
+- [x] Architecture brief for judges documented
+- [x] Benchmark summary template + reproducible commands documented
+- [ ] Final architecture diagram image asset prepared
+- [x] Final benchmark table populated with tuned vs base numeric deltas
+
+### Files Added
+- `docs/demo_script.md`
+- `docs/architecture_for_judges.md`
+- `docs/benchmark_summary_for_submission.md`
+
+### Acceptance
+- [x] Any teammate can follow the same demo sequence from documentation.
+
+## 4) Priority Execution Plan (Order Matters)
+
+1. Reliability first:
+- [x] strict live-only path + judge-mode run script
+
+2. UX second:
+- [x] operator-first wording and provenance section
+
+3. Dongle path third:
+- [x] lightweight corroboration feature
+
+4. Submission pack fourth:
+- [x] docs scaffolds created
+- [ ] final numeric benchmark fill-in
+- [ ] final architecture diagram export
+
+## 5) Concrete Sprint Backlog
+
+## P0 (Blockers)
+1. [x] Add `scripts/start_judge_mode.ps1` and `scripts/live_smoke.py`.
+2. [x] Ensure watchlist/site detail only display strict live-generated incidents in judge mode.
+3. [x] Add explicit live provenance block in UI and export payload.
+
+## P1 (Score Multipliers)
+1. [x] Add dongle ingestion endpoint + UI badge integration.
+2. [x] Add benchmark delta table with final measured numbers.
+3. [x] Finalize demo script and architecture brief docs.
+
+## P2 (Polish)
+1. [ ] Copywriting pass for operator persona language.
+2. [ ] Responsive UI polish + empty/error states.
+3. [ ] Screenshot pack generation for submission fallback/live comparison.
+
+## 6) Done Definition Before Submission
+
+Project is ready only if all are true:
+1. [x] Judge can run using one command/script, no manual debugging path documented.
+2. [x] UI displays live-generated incident with satellite provenance fields.
+3. [x] Review + export flow succeeds end-to-end.
+4. [x] Base vs tuned improvement table is filled with reproducible measured values.
+5. [x] Demo narrative explains satellite + LFM2-VL + dongle loop.
+
+## 7) Immediate Next Actions
+
+1. [x] Implement `start_judge_mode.ps1` + `live_smoke.py`.
+2. [x] Add `Live Imagery Provenance` panel in frontend.
+3. [x] Add `dongle_readings` table + ingest API skeleton.
+4. [ ] Re-run strict live screenshot pack for submission assets.
+5. [ ] Refresh `openapi.json` to include latest dongle endpoints.

docs/annotation-guide.md

@@ -0,0 +1,79 @@
+# Annotation Guide v1 (Phase 6)
+
+This guide defines how LandfillSentry labeling works for LoRA fine-tuning.
+
+## 1) Label Unit
+
+One label unit equals one `EvidencePanel` + one structured incident annotation.
+
+Required fields per sample:
+
+- `sample_id`
+- `site_id`
+- `split` (`train`, `validation`, `test`, `demo`)
+- `panel_artifact_path`
+- `annotation`:
+  - `plume_likely` (bool)
+  - `bbox_norm` (`[x1, y1, x2, y2]` normalized to `[0,1]`)
+  - `likely_source_zone` (`active_face`, `gas_system`, `perimeter_or_unknown`)
+  - `priority_tier` (`low`, `medium`, `high`, `urgent`)
+- `provenance`:
+  - `source_type` (`manual`, `weak`, `synthetic`)
+  - `source_ref`
+  - `labeler`
+  - `created_at` (ISO 8601 UTC)
+  - optional `notes`
+
+## 2) Provenance Policy
+
+Every sample must include provenance metadata. No exceptions.
+
+Rules:
+
+- `manual`: reviewed by human labeler.
+- `weak`: generated by heuristic/system and spot-checked.
+- `synthetic`: augmented from panel transformations.
+- Keep provenance immutable after split freeze.
+
+## 3) Negative Set Policy
+
+Negative samples are first-class and must remain in every split.
+
+Negative criteria:
+
+- no plausible plume indicator,
+- cloud/shadow artifacts not mistaken as plume,
+- uncertainty defaults to `plume_likely=false`.
+
+## 4) Split Freeze Policy
+
+Split files are generated once and treated as frozen artifacts:
+
+- manifest: `data/manifests/dataset_manifest_v1.json`
+- splits: `data/manifests/dataset_splits_v1.json`
+
+Rules:
+
+- `validation` and `demo` samples cannot be reused in `train`.
+- any sample change requires a new manifest version (v2, v3, ...).
+- keep `manifest_checksum` in training records for reproducibility.
+
+## 5) Quality Checks Before Training
+
+Minimum checks:
+
+- all samples validate required schema fields,
+- all `bbox_norm` arrays contain exactly 4 values,
+- every sample has provenance block,
+- split counts are non-zero for `train`, `validation`, and `demo`.
+
+## 6) Output Contract Reminder
+
+Fine-tuning must preserve the same incident-output contract used by Phase 5.
+
+That means:
+
+- same prompt/output schema alignment,
+- same enum values,
+- same validation fallback logic in API pipeline.
+

docs/architecture.md

@@ -0,0 +1,39 @@
+# LandfillSentry Ops Architecture (Phase 1 Freeze)
+
+## Frozen MVP Workflow
+
+1. Operator opens watchlist and selects a site.
+2. Backend retrieves current and historical imagery.
+3. Candidate generator proposes suspicious regions.
+4. Panel builder creates evidence artifacts.
+5. VLM inference produces structured incident JSON.
+6. Incident is stored with `review_status=proposed`.
+7. UI shows evidence, recommendation, and review controls.
+8. Human review sets final state (`published`, `dismissed`, or `needs_review`).
+
+## Incident Lifecycle (Frozen)
+
+```text
+proposed -> published
+proposed -> dismissed
+proposed -> needs_review
+needs_review -> published
+needs_review -> dismissed
+needs_review -> needs_review
+```
+
+## MVP Scope (Frozen)
+
+- watchlist-first workflow
+- single-incident object with explainable fields
+- human review before incident publication
+- live and cached execution paths
+- synchronous scan path for MVP
+
+## Explicit Non-Goals (Phase 1)
+
+- regulatory-grade quantification
+- autonomous enforcement decisions
+- enterprise multi-tenant administration
+- full atmospheric inversion
+- global generalized methane platform in MVP

docs/demo-script.md

@@ -0,0 +1,11 @@
+# Demo Script Placeholder
+
+Phase 1 freeze:
+
+1. Watchlist opens with frozen demo sites.
+2. Site scan returns incident object and evidence panel.
+3. Operator reviews incident and sets review action.
+4. Incident export path is demonstrated.
+5. Cached fallback path is explicitly shown.
+
+Final script polish happens in Phase 9.

docs/demo-site-selection-rubric.md

@@ -0,0 +1,34 @@
+# Demo-Site Selection Rubric (Frozen in Phase 1)
+
+## Goal
+
+Select and freeze `3-5` landfill demo sites with reliable imagery access and clear storytelling value.
+
+## Hard Filters (Must Pass)
+
+- Site is a real landfill or operationally plausible landfill location.
+- SimSat retrieval path is available for current and historical views.
+- Site can support cached replay for demo fallback.
+- Site metadata includes at least id, name, lat, lon, country.
+
+## Scoring Rubric (100 Points)
+
+- `30` Data availability and retrieval reliability
+- `25` Visual signal separability (clear candidate-worthy regions)
+- `15` Cloud resilience across recent history
+- `15` Geographic diversity contribution
+- `15` Demo narrative usefulness (operator actionability)
+
+## Selection Process
+
+1. Build shortlist of `8-12` candidate sites.
+2. Score each site using the rubric in `assets/demo_sites/demo_site_selection_matrix.csv`.
+3. Pick top `3-5` sites while preserving geographic diversity.
+4. Freeze selected sites in `assets/demo_sites/frozen_demo_sites.template.json`.
+5. Mark each frozen site as one of: `positive`, `negative`, `cloudy`, `missing_data`.
+
+## Freeze Policy
+
+- Frozen sites are not changed during a phase unless a blocker is logged.
+- Any site replacement requires a documented reason in change log.
+- Cached assets must be prepared for every frozen site.

docs/demo_video_shotlist.md

@@ -0,0 +1,46 @@
+# Demo Video Shot List
+
+Target length: 3-5 minutes.
+
+## Pre-Record Checklist
+
+Run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/start_judge_mode.ps1 -RestartApi
+```
+
+Verify these are ready:
+- `http://127.0.0.1:8000/ops`
+- `docs/latest_live_smoke_proof.md`
+- `docs/latest_live_scan_artifact.md`
+- `docs/benchmark_summary_for_submission.md`
+
+## Recording Flow
+
+1. Problem framing, 20s  
+   Landfill operators need to know which site to inspect first and why, not just see another map.
+
+2. Architecture, 35s  
+   Show the flow: watchlist site -> DPhi SimSat Sentinel/Mapbox imagery -> candidate/evidence panel -> LFM2.5-VL incident JSON -> operator review/export.
+
+3. Live proof, 45s  
+   Show `docs/latest_live_smoke_proof.md`: status `PASS`, scan `scan_083`, inference mode `live`, all previews present.
+
+4. Product walkthrough, 90s  
+   Open `/ops`, select the scan/site, show evidence previews, provenance, source chain, timestamps, priority, confidence, and review status.
+
+5. Reliability, 30s  
+   Explain strict mode: if live imagery or inference is unavailable, the app fails with an actionable error instead of pretending cached/mock output is live.
+
+6. Fine-tune and benchmark, 45s  
+   Show `docs/benchmark_summary_for_submission.md`: Modal LoRA run `lora_run_20260504T181913Z`, 78 live-scan samples, public adapter `akashreddy2103/landfill`, validation-loss improvement, and the base-vs-tuned metric table.
+
+7. Close, 20s  
+   Emphasize the useful operator outcome: auditable, reviewable methane incident triage with live satellite provenance.
+
+## Must-Say Lines
+
+- "This is strict live mode: no fallback is presented as live."
+- "DPhi SimSat is the primary imagery provider, with current Sentinel, historical Sentinel, and Mapbox context recorded in provenance."
+- "The output is not just a caption; it becomes a persisted incident with review state and exportable evidence."

docs/evaluation.md

@@ -0,0 +1,87 @@
+# Phase 7 Evaluation Guide
+
+This document defines the Phase 7 evaluation and reliability workflow.
+
+## Scope
+
+Phase 7 compares three model paths:
+
+- `heuristic` (candidate-only projection)
+- `base_model` (no adapter)
+- `fine_tuned_model` (adapter-enabled contract path)
+
+and validates reliability for known failure modes. The evaluator now runs repeated positive,
+negative, and cloudy fixture cases so the report is no longer based on a single sample per class.
+
+## Run Command
+
+```bash
+python scripts/benchmark_models.py
+```
+
+## Generated Artifacts
+
+The command writes these files to `data/manifests/`:
+
+- `phase7_evaluation_report.json`
+- `phase7_baseline_comparison.md`
+- `phase7_null_scene_report.json`
+- `phase7_human_actionability_rubric_v1.json`
+- `phase7_reliability_report.json`
+
+## Metrics
+
+Per model, the harness computes:
+
+- `json_valid_rate`
+- `incident_f1`
+- `zone_accuracy`
+- `bbox_iou`
+- `human_usefulness_score`
+- confusion matrix (`tp`, `fp`, `tn`, `fn`)
+- per-fixture plume and zone accuracy
+- Wilson confidence intervals for schema validity, plume accuracy, zone accuracy, and null-scene false positives
+
+Null-scene trust is reported separately as:
+
+- `false_positive_count`
+- `false_positive_rate`
+- confidence interval for `false_positive_rate`
+
+## Quality Gates
+
+The report includes pass/fail gates for the fine-tuned path:
+
+- `json_valid_rate >= 1.00`
+- `incident_f1 >= 0.80`
+- `zone_accuracy >= 0.75`
+- `bbox_iou >= 0.50`
+- `human_usefulness_score >= 0.80`
+- `null_false_positive_rate <= 0.25`
+
+`validation_summary.validation_strength` is `moderate` only when the suite has at least
+12 cases per model, the fine-tuned path passes all gates, and it shows meaningful deltas
+over the base projection. Otherwise it remains `limited`.
+
+## Human Actionability Rubric (v1)
+
+Each incident is scored on:
+
+- actionability
+- clarity
+- plausibility
+- followup_quality
+- trustworthiness
+
+Each criterion is scored 1-5 and normalized to `[0,1]`.
+
+## Failure Injection Coverage
+
+The reliability harness explicitly tests:
+
+- invalid JSON model output retry path
+- empty candidate handling path
+- Mapbox API configuration failure path
+- slow inference detection path
+
+These checks feed into `phase7_reliability_report.json`.

docs/field-dictionary.md

@@ -0,0 +1,87 @@
+# Field Dictionary (Phase 1 Contract Freeze)
+
+## Site
+
+- `site_id`: unique stable site identifier
+- `name`: human-readable site name
+- `lat`: centroid latitude
+- `lon`: centroid longitude
+- `country`: country label
+- `operator`: operator label
+- `watchlist_enabled`: include site in watchlist scans
+- `polygon_geojson`: optional polygon boundary
+- `metadata`: extensible metadata object
+
+## ImageAsset
+
+- `asset_id`: unique asset identifier
+- `site_id`: parent site
+- `source`: imagery source (`dphi-simsat`, `dphi-simsat-sentinel`, `dphi-simsat-mapbox`, `mapbox`, `cache`, `other`)
+- `timestamp_requested`: request time
+- `timestamp_captured`: capture time
+- `cloud_cover`: cloud metric in `[0,1]`
+- `bands`: band list or channel descriptors
+- `local_path`: cache path for asset
+- `cache_key`: deterministic cache key
+
+## Candidate
+
+- `candidate_id`: candidate identifier
+- `site_id`: parent site
+- `job_id`: scan/job identifier
+- `bbox_norm`: normalized bbox `[x1, y1, x2, y2]`
+- `candidate_score`: candidate confidence score
+- `temporal_recurrence`: recurrence feature score
+- `cloud_penalty`: cloud penalty score
+- `likely_source_zone_prior`: coarse zone prior enum
+
+## EvidencePanel
+
+- `panel_id`: evidence panel identifier
+- `site_id`: parent site
+- `candidate_id`: candidate link
+- `panel_version`: panel composer version
+- `current_rgb_path`: path to current RGB panel image
+- `spectral_composite_path`: path to methane-sensitive composite
+- `temporal_diff_path`: path to temporal difference panel
+- `mapbox_context_path`: required map context image path
+- `metadata_json`: serialized panel metadata
+
+## Incident
+
+- `incident_id`: incident identifier
+- `site_id`: parent site
+- `job_id`: scan/job identifier
+- `analysis_time`: inference timestamp
+- `plume_likely`: plume-likely classification
+- `confidence`: confidence in `[0,1]`
+- `bbox_norm`: normalized bbox `[x1, y1, x2, y2]`
+- `likely_source_zone`: predicted zone enum
+- `persistence_score`: persistence in `[0,1]`
+- `priority_tier`: triage priority enum
+- `severity_tier`: incident severity enum
+- `review_status`: review lifecycle enum
+- `feedback_status`: feedback enum
+- `evidence_summary`: concise rationale text
+- `recommended_followup`: next operational action
+- `model_version`: model or adapter identifier
+
+## ReviewAction
+
+- `incident_id`: target incident
+- `review_status`: requested review state transition
+- `feedback_status`: optional operator feedback
+- `review_comment`: optional human note
+
+## EvaluationRecord
+
+- `eval_id`: evaluation row identifier
+- `split`: dataset split (`train`, `validation`, `test`, `demo`)
+- `site_id`: evaluated site
+- `baseline_model`: baseline model id
+- `candidate_model`: model under evaluation
+- `json_valid_rate`: valid JSON generation rate
+- `incident_f1`: incident-level F1 metric
+- `zone_accuracy`: source-zone accuracy
+- `bbox_iou`: bbox IoU metric
+- `human_usefulness_score`: reviewer usefulness score

docs/global_live_api_probe_report.md

@@ -0,0 +1,37 @@
+# Global Live API Probe Report
+
+Generated: 2026-04-28T17:02:13+00:00
+
+- Target samples: 180
+- Successes: 0
+- Failures: 0
+- Unique successful sites: 0
+
+| Site | Region | Country | Probe OK | Scan Successes | Scan Failures |
+|---|---|---|---|---:|---:|
+| LF_GLOBAL_001 | North America | United States | yes | 0 | 0 |
+| LF_GLOBAL_002 | North America | United States | yes | 0 | 0 |
+| LF_GLOBAL_003 | North America | United States | yes | 0 | 0 |
+| LF_GLOBAL_004 | North America | United States | yes | 0 | 0 |
+| LF_GLOBAL_005 | North America | United States | yes | 0 | 0 |
+| LF_GLOBAL_006 | Latin America | Mexico | yes | 0 | 0 |
+| LF_GLOBAL_007 | Latin America | Brazil | yes | 0 | 0 |
+| LF_GLOBAL_008 | Latin America | Chile | yes | 0 | 0 |
+| LF_GLOBAL_009 | Latin America | Argentina | yes | 0 | 0 |
+| LF_GLOBAL_010 | Latin America | Colombia | yes | 0 | 0 |
+| LF_GLOBAL_011 | Asia | India | yes | 0 | 0 |
+| LF_GLOBAL_012 | Asia | India | yes | 0 | 0 |
+| LF_GLOBAL_013 | Asia | Indonesia | yes | 0 | 0 |
+| LF_GLOBAL_014 | Asia | South Korea | yes | 0 | 0 |
+| LF_GLOBAL_015 | Asia | China | yes | 0 | 0 |
+| LF_GLOBAL_016 | Asia | Singapore | yes | 0 | 0 |
+| LF_GLOBAL_017 | Asia | Philippines | yes | 0 | 0 |
+| LF_GLOBAL_018 | Africa | Nigeria | yes | 0 | 0 |
+| LF_GLOBAL_019 | Africa | Kenya | yes | 0 | 0 |
+| LF_GLOBAL_020 | Africa | Ghana | yes | 0 | 0 |
+| LF_GLOBAL_021 | Africa | Morocco | yes | 0 | 0 |
+| LF_GLOBAL_022 | Africa | South Africa | yes | 0 | 0 |
+| LF_GLOBAL_023 | Middle East | United Arab Emirates | yes | 0 | 0 |
+| LF_GLOBAL_024 | Middle East | Israel | yes | 0 | 0 |
+| LF_GLOBAL_025 | Oceania | Australia | yes | 0 | 0 |
+| LF_GLOBAL_026 | Oceania | New Zealand | yes | 0 | 0 |

docs/global_live_dataset_summary.md

@@ -0,0 +1,74 @@
+# Global Live Dataset Summary
+
+Date: April 28, 2026
+
+## What Changed
+
+The Phase 6 training dataset is no longer Europe-only. A global site seed file was added at:
+
+- `assets/demo_sites/global_sites.26rows.csv`
+
+The collection script probes DPhi SimSat first, then only scans sites whose current Sentinel, historical Sentinel, and Mapbox context endpoints are reachable:
+
+```bash
+python scripts/collect_global_live_scans.py --probe-only
+python scripts/collect_global_live_scans.py --target-samples 180 --repeats-per-site 8
+```
+
+Latest all-site probe result:
+
+- `26 / 26` global candidate sites passed the DPhi SimSat endpoint probe.
+- Report: `docs/global_live_api_probe_report.md`
+
+## Current Expanded Dataset
+
+After the first two global collection batches:
+
+- total live-scan samples: `78`
+- total unique sites: `30`
+- global non-Europe successful sites: `20`
+- split counts:
+  - train: `49`
+  - validation: `20`
+  - test: `9`
+
+Regions represented:
+
+| Region | Samples |
+|---|---:|
+| Europe/legacy | 58 |
+| North America | 5 |
+| Latin America | 5 |
+| Asia | 6 |
+| Africa | 3 |
+| Middle East | 1 |
+
+The larger target remains `150-300+` live scans. The pipeline is now ready for that run; at the current live scan speed it should be treated as a longer overnight collection job.
+
+## Manual Label Correction
+
+Export review queue:
+
+```bash
+python scripts/export_label_review_queue.py
+```
+
+Then copy corrected rows into:
+
+- `data/labels/manual_label_corrections.csv`
+
+Template:
+
+- `data/labels/manual_label_corrections.template.csv`
+
+When `scripts/build_phase6_dataset.py` runs, it applies those manual corrections before writing:
+
+- `data/labels/phase6_samples_live_v1.jsonl`
+- `data/manifests/dataset_manifest_v1.json`
+- `data/manifests/dataset_splits_v1.json`
+
+## Latest Modal Run
+
+- run id: `lora_run_20260428T165129Z`
+- adapter ref: `modal-volume://landfillsentry-model-artifacts/lora_run_20260428T165129Z/checkpoint-lora-v1`
+- checkpoint record: `data/manifests/tuned_checkpoint_v1.json`

docs/global_live_scan_collection_report.md

@@ -0,0 +1,27 @@
+# Global Live Scan Collection Report
+
+Generated: 2026-04-28T16:50:21+00:00
+
+- Target samples: 10
+- Successes: 10
+- Failures: 3
+- Unique successful sites: 10
+
+| Site | Region | Country | Probe OK | Scan Successes | Scan Failures |
+|---|---|---|---|---:|---:|
+| LF_GLOBAL_011 | Asia | India | yes | 1 | 0 |
+| LF_GLOBAL_012 | Asia | India | yes | 1 | 0 |
+| LF_GLOBAL_013 | Asia | Indonesia | yes | 0 | 1 |
+| LF_GLOBAL_014 | Asia | South Korea | yes | 1 | 0 |
+| LF_GLOBAL_015 | Asia | China | yes | 1 | 0 |
+| LF_GLOBAL_016 | Asia | Singapore | yes | 1 | 0 |
+| LF_GLOBAL_017 | Asia | Philippines | yes | 1 | 0 |
+| LF_GLOBAL_018 | Africa | Nigeria | yes | 1 | 0 |
+| LF_GLOBAL_019 | Africa | Kenya | yes | 0 | 1 |
+| LF_GLOBAL_020 | Africa | Ghana | yes | 1 | 0 |
+| LF_GLOBAL_021 | Africa | Morocco | yes | 0 | 1 |
+| LF_GLOBAL_022 | Africa | South Africa | yes | 1 | 0 |
+| LF_GLOBAL_023 | Middle East | United Arab Emirates | yes | 1 | 0 |
+| LF_GLOBAL_024 | Middle East | Israel | yes | 0 | 0 |
+| LF_GLOBAL_025 | Oceania | Australia | yes | 0 | 0 |
+| LF_GLOBAL_026 | Oceania | New Zealand | yes | 0 | 0 |

docs/integration-checklist.md

@@ -0,0 +1,11 @@
+# Phase Integration Checklist
+
+Use this checklist before closing any phase.
+
+- [ ] Previous-phase contracts remain unchanged or are explicitly versioned
+- [ ] API contract still matches `openapi.json`
+- [ ] Golden fixtures (`positive`, `negative`, `cloudy`, `missing_data`) still run
+- [ ] Live execution path works for minimum smoke case
+- [ ] Cached execution path works for minimum smoke case
+- [ ] Failure behavior is user-readable and non-crashing
+- [ ] Updated verification notes added to master-plan change log

docs/testing-charter.md

@@ -0,0 +1,54 @@
+# Testing Charter (Phase 1 Lock)
+
+## Purpose
+
+Define mandatory testing and integration behavior for all phases.
+
+## Test Pyramid
+
+### Unit
+
+- schema validation
+- bbox normalization utilities
+- candidate scoring helpers
+- prompt formatting
+- review-state transition checks
+
+### Integration
+
+- SimSat adapter + cache behavior
+- candidate -> panel pipeline compatibility
+- inference output -> schema validator
+- API routes + DB layer
+- web UI fetch/render against cached payloads
+
+### End-to-End
+
+- one positive-site live scan
+- one positive-site cached scan
+- one negative-site cached scan
+- one cloudy or missing-data graceful path
+
+## Golden Fixture Matrix (Mandatory)
+
+- `positive`: expected anomaly candidate path
+- `negative`: null-scene trust path
+- `cloudy`: cloud-heavy degradation path
+- `missing_data`: retrieval failure degradation path
+
+Fixture root: `tests/fixtures/`
+
+## Live + Cached Policy
+
+- Every major capability must support both live and cached execution.
+- Cached mode is required for demo resilience.
+- Integration tests should verify equivalent schema outputs between live and cached paths.
+
+## Phase-Close Quality Gate
+
+No phase is marked complete unless:
+
+- part-level acceptance checks pass,
+- integration checkpoint for the phase passes,
+- required fixture classes are still supported,
+- contract drift against `openapi.json` is resolved.

judge_deployment_runbook.md

@@ -26,26 +26,18 @@ Do not switch to llama.cpp, MLX, or ONNX for the judging build unless exported m
 - Strict live judge mode.
 - DPhi SimSat imagery integration and provenance.
 - Hugging Face Transformers inference path.
-- Optional PEFT adapter loading with `HF_ADAPTER_ID`.
+- PEFT adapter loading with `HF_ADAPTER_ID=akashreddy2103/landfill`.
 - Modal training scaffold and checkpoint record.
 - Benchmark/evaluation artifacts for a small domain-adaptation fixture proxy.
 
-## What Still Needs Your Input
+## Credentials Needed At Runtime
 
-To claim fine-tuned public weights strongly, provide:
+For the final judged run, provide:
 
-- `HF_ADAPTER_ID`: the public Hugging Face adapter repo, for example `your-org/landfillsentry-lfm25vl-lora`.
+- `HF_ADAPTER_ID=akashreddy2103/landfill`
 - `HF_TOKEN`: a token that can read the base model and adapter during judging.
 - `MAPBOX_TOKEN`: needed by SimSat Mapbox imagery.
-- Confirmation that the public model card links back to this repo's training code and documents the dataset/methodology.
-
-For your current target repo, the adapter ID will be:
-
-```env
-HF_ADAPTER_ID=akashreddy2103/landfill
-```
-
-Set it only after the repo contains real PEFT adapter files.
+- The public Hugging Face model card already includes the dataset, methodology, benchmark, proof artifacts, and training code package.
 
 ## Local Judge Mode
 
@@ -116,7 +108,7 @@ INFERENCE_ALLOW_FALLBACK=false
 HF_TOKEN=...
 HF_MODEL_ID=LiquidAI/LFM2.5-VL-450M
 HF_MODEL_REVISION=main
-HF_ADAPTER_ID=your-public-adapter-repo
+HF_ADAPTER_ID=akashreddy2103/landfill
 HF_ADAPTER_REVISION=main
 HF_LOCAL_FILES_ONLY=false
 ```

phase7_baseline_comparison.md

@@ -0,0 +1,5 @@
+| Model | JSON Valid | Incident F1 | Zone Accuracy | BBox IoU | Human Usefulness | Null FP Rate |
+|---|---:|---:|---:|---:|---:|---:|
+| heuristic | 1.00 | 1.00 | 1.00 | 1.00 | 0.97 | 0.00 |
+| base_model | 1.00 | 0.50 | 0.33 | 0.20 | 0.73 | 1.00 |
+| fine_tuned_model | 1.00 | 1.00 | 1.00 | 1.00 | 0.97 | 0.00 |

project_README.md

@@ -0,0 +1,268 @@
+# LandfillSentry Ops
+
+Operator-first landfill methane incident triage copilot.
+
+This repository now includes Phase 1 to Phase 7 implementation artifacts:
+
+- frozen workflow and incident lifecycle
+- frozen schema and enum contracts
+- first-draft `openapi.json`
+- demo-site selection rubric and template
+- testing policy, fixture matrix, and integration checklist
+- SQLite-backed site registry
+- DPhi SimSat + Mapbox imagery adapters (live-first, strict mode supported)
+- persistent cache-backed image retrieval paths
+- DPhi SimSat API integration path (`/data/current/image/sentinel`, `/data/image/sentinel`, `/data/current/image/mapbox`)
+- Phase 3 candidate generation with zone priors and temporal recurrence
+- Phase 4 evidence panel builder, prompt contract metadata, and schema-validation loop scaffolding
+- Phase 5 base model inference path with Hugging Face model loading and incident persistence/review integration
+- Phase 6 dataset manifest freeze, annotation guidance, and Modal GPU PEFT LoRA fine-tuning artifacts
+- Phase 7 evaluation harness, baseline comparison table, null-scene report, and reliability injection checks
+- Phase 8 watchlist UI, site evidence drill-down, review controls, and incident export flow
+
+## Quick Layout
+
+- `docs/` planning contracts and governance docs
+- `apps/api/` backend API scaffold and typed schemas
+- `apps/web/` frontend placeholder structure
+- `ml/` ML pipeline placeholders
+- `data/` data, cache, labels, and manifests structure
+- `tests/` schema and contract checks with fixture placeholders
+- `assets/demo_sites/` demo-site rubric templates
+
+## Current Status
+
+- Phase 1 outputs are frozen as implementation baselines.
+- Phase 2 foundation is implemented with registry, retrieval adapters, and cache flow.
+- Phase 3 candidate generation and persistence are implemented.
+- Phase 4 deterministic panel and contract-validation layer are implemented.
+- Phase 5 base-model inference and incident lifecycle path are implemented.
+- Phase 6 dataset build and Modal PEFT LoRA adapter training flow are implemented.
+- Phase 7 evaluation and reliability hardening artifacts are implemented.
+- Phase 8 watchlist/review/export operator UI and API workflows are implemented.
+- Phase 8+ frontend is a production-style FastAPI-served ops console at `/ops`.
+
+## Ops Console (Phase 8)
+
+- Open the operator console at `GET /ops`
+- Frontend source:
+  - `apps/web/ops.html`
+  - `apps/web/ops.css`
+  - `apps/web/ops.js`
+- The UI is served directly by FastAPI; no separate frontend build step is required for judging.
+- Core API routes:
+  - `GET /watchlist`
+  - `GET /sites/{site_id}/detail`
+  - `GET /runtime/status`
+  - `GET /ops/summary`
+  - `GET /overlays/plumes`
+  - `GET /scan-progress/{progress_id}`
+  - `POST /sites/{site_id}/dongle-readings`
+  - `GET /sites/{site_id}/dongle-readings`
+  - `POST /incidents/{incident_id}/review`
+  - `GET /incidents/{incident_id}/export?format=markdown|json`
+
+## Judge Quick Start (Strict Live)
+
+Use this path for judging/demo runs where fallback should never be presented as live output.
+
+Judge-facing brief: `docs/judge_submission_brief.md`
+Deployment runbook: `docs/judge_deployment_runbook.md`
+Fine-tuning methodology: `docs/fine_tuning_methodology.md`
+
+1. Configure `.env.local` with real keys/tokens:
+   - `SIMSAT_MODE=live`
+   - `MAPBOX_MODE=live`
+   - `INFERENCE_MODE=live`
+   - `REQUIRE_LIVE_RESULTS=true`
+   - `INFERENCE_ALLOW_FALLBACK=false`
+   - `SIMSAT_BASE_URL=http://localhost:9005` (or hosted SimSat)
+   - `MAPBOX_TOKEN=...`
+   - `HF_TOKEN=...`
+2. Start everything + run smoke checks:
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/start_judge_mode.ps1
+```
+This command uses the project `.venv` when available, writes service logs under `data/logs/`, and saves smoke proof to:
+  - `docs/latest_live_smoke_proof.md`
+  - `data/processed/live_smoke_proof.json`
+3. Open UI:
+   - `http://127.0.0.1:8000/ops`
+4. Validate live behavior:
+   - `generation mode` must show `live`
+   - `Live Imagery Provenance` panel must show DPhi SimSat Sentinel/Mapbox provenance
+   - scans should fail fast with actionable errors if live dependencies are down
+
+Smoke test script can also be run directly:
+
+```bash
+python scripts/live_smoke.py --api-base-url http://127.0.0.1:8000 --simsat-base-url http://127.0.0.1:9005
+```
+
+Archive the latest successful live scan:
+
+```bash
+python scripts/save_live_scan_artifact.py --api-base-url http://127.0.0.1:8000 --scan-id scan_083
+```
+
+Preflight the repository before handoff:
+
+```bash
+python scripts/export_openapi.py
+python scripts/judge_preflight.py
+```
+
+Require a public adapter ID for final fine-tuned-weights claims:
+
+```bash
+python scripts/judge_preflight.py --strict-public-weights
+```
+
+## Docker Judge Deployment
+
+Run the API/UI and SimSat API together:
+
+```powershell
+docker compose --env-file .env.local -f docker-compose.landfillsentry.yml up --build
+```
+
+Open:
+
+- LandfillSentry: `http://127.0.0.1:8000/ops`
+- SimSat API: `http://127.0.0.1:9005`
+
+## SimSat Backend Setup
+
+LandfillSentry uses the hackathon-provided DPhi SimSat API contract as the official live imagery backend:
+
+- Repository: `https://github.com/DPhi-Space/SimSat`
+- Expected local API: `http://localhost:9005`
+
+1. Start SimSat locally from `DPhi-Space/SimSat`:
+   - `cd external/SimSat`
+   - `docker compose up --build`
+2. Ensure SimSat API is reachable at `http://localhost:9005`.
+3. Set required env values in this project:
+   - `SIMSAT_MODE=live`
+   - `MAPBOX_MODE=live`
+   - `SIMSAT_BASE_URL=http://localhost:9005`
+   - `SIMSAT_USE_FOR_MAPBOX=true`
+4. In the SimSat project environment, set `MAPBOX_ACCESS_TOKEN` before startup so SimSat can serve Mapbox imagery.
+
+If `SIMSAT_USE_FOR_MAPBOX=false`, this project falls back to direct Mapbox static API calls using `MAPBOX_TOKEN`.
+
+### Endpoint Usage (Implemented)
+
+- Sentinel historical data: `GET /data/image/sentinel`
+- Sentinel current site-coordinate data: `GET /data/image/sentinel`
+- Mapbox site-coordinate context data: `GET /data/image/mapbox`
+- Runtime provenance: `GET /runtime/status` includes the DPhi SimSat repository and required endpoints.
+
+## LFM2.5-VL Usage (Configured)
+
+This project now includes a runnable script based on the official `LiquidAI/LFM2.5-VL-450M` examples:
+
+- image question answering
+- visual grounding (bbox JSON output)
+- tool-use style response generation
+
+Judge-mode inference tooling:
+- inference engine: Hugging Face Transformers
+- adapter loader: PEFT
+- base model: `LiquidAI/LFM2.5-VL-450M`
+- public adapter: `akashreddy2103/landfill`
+
+Run:
+
+```bash
+python scripts/run_lfm25_examples.py
+```
+
+Notes:
+
+- Set `HF_TOKEN` / `HUGGINGFACE_TOKEN` in `.env.local`.
+- `INFERENCE_MODE=live` is the default runtime path.
+- Use `INFERENCE_MODE=mock` only for offline/local test runs.
+- `INFERENCE_ALLOW_FALLBACK=false` is recommended so failed live inference does not silently produce fallback-style incidents.
+- `HF_LOCAL_FILES_ONLY=false` is recommended on a clean judge machine so the model can download; use `true` only when the model is already cached.
+- The example script forces live model usage internally for demonstration.
+
+## Modal GPU Setup (Configured)
+
+The project is now wired for Modal GPU orchestration for Phase 6 LoRA runs.
+
+1. Install dependencies:
+```bash
+python -m pip install -r requirements.txt
+```
+2. Create Modal token:
+```bash
+modal token new
+```
+3. Put credentials in `.env.local`:
+```env
+MODAL_TOKEN_ID=...
+MODAL_TOKEN_SECRET=...
+MODAL_GPU=T4
+MODAL_APP_NAME=landfillsentry-lora-train
+MODAL_ARTIFACT_VOLUME=landfillsentry-model-artifacts
+HF_ADAPTER_ID=
+HF_ADAPTER_REVISION=main
+```
+4. Run GPU check + LoRA train job:
+```bash
+python scripts/train_lora.py
+```
+
+Underlying Modal app:
+- `ml/training/modal_lora_train.py`
+- `scripts/modal_gpu_check.py`
+- `ml/training/lora_artifacts.py`
+
+Latest public adapter:
+
+- Hugging Face repo: `akashreddy2103/landfill`
+- Run id: `lora_run_20260504T181913Z`
+- Training mode: `peft_lora_supervised`
+- Completed optimizer steps: `24`
+- Validation loss: `2.410613179206848` -> `1.3696070164442062`
+
+Phase 6 dataset freeze inputs/outputs (live-first):
+
+- Preferred labels source (auto-generated from real scans): `data/labels/phase6_samples_live_v1.jsonl`
+- Seed fallback labels source (used only when no live scans exist): `data/labels/phase6_samples_v1.jsonl`
+- Frozen manifest: `data/manifests/dataset_manifest_v1.json`
+- Frozen splits: `data/manifests/dataset_splits_v1.json`
+- Checkpoint record: `data/manifests/tuned_checkpoint_v1.json`
+
+Generate dataset artifacts only:
+
+```bash
+python scripts/build_phase6_dataset.py
+```
+
+Global dataset expansion:
+
+```bash
+python scripts/collect_global_live_scans.py --probe-only
+python scripts/collect_global_live_scans.py --target-samples 180 --repeats-per-site 8
+python scripts/export_label_review_queue.py
+python scripts/build_phase6_dataset.py
+python scripts/train_lora.py
+```
+
+Current expanded dataset summary:
+- `docs/global_live_dataset_summary.md`
+- `assets/demo_sites/global_sites.26rows.csv`
+- `docs/global_live_api_probe_report.md`
+- `docs/global_live_scan_collection_report.md`
+
+Current implementation behavior:
+
+- Phase 2/3 scan flow uses current Sentinel + current Mapbox for inference context.
+- The same scan flow also fetches Sentinel historical data to support temporal features and fine-tuning data collection.
+
+Dataset roles (as provided by SimSat docs):
+
+- Sentinel-2: high temporal revisit, multispectral, medium spatial resolution.
+- Mapbox: high spatial resolution RGB context, static imagery (not time-dependent).

project_docs/LandfillSentry_Ops_Answers_to_Open_Questions.md

@@ -0,0 +1,748 @@
+# LandfillSentry Ops: Decision Log and Answers to Open Questions
+
+Version: 1.0  
+Purpose: This document answers the full question list for LandfillSentry Ops and freezes the recommended operating assumptions for the hackathon build. It is intended to act as the single decision file that aligns product, engineering, data, evaluation, and delivery.
+
+---
+
+## How to read this document
+
+These answers are written as **recommended defaults**, not abstract options.  
+The goal is to remove ambiguity so the team can start building immediately.
+
+Where relevant, each answer includes:
+
+- **Decision**: the recommended choice
+- **Why**: short justification
+- **Implementation effect**: what changes in the build plan because of this choice
+
+---
+
+# 1. Scope and Outcome
+
+### 1. Is the primary goal to win the hackathon, build a real MVP, or create a startup-grade product plan?
+**Decision:** The primary goal is to **win the hackathon with a real MVP**, while laying a credible foundation for a startup-grade product later.
+
+**Why:** A hackathon winner needs a working product, not only slides. At the same time, the idea should feel commercially serious enough that judges believe it can grow beyond the event.
+
+**Implementation effect:**  
+- Prioritize a working end to end system over feature breadth  
+- Keep architecture production-aware, but do not overbuild enterprise features  
+- Include a short post-hackathon roadmap, but do not let it dominate MVP scope
+
+---
+
+### 2. Should the final plan optimize for hackathon execution over the next 7 to 14 days, or for a 2 to 3 month build after the hackathon?
+**Decision:** Optimize primarily for **7 to 14 day execution**, with a compact 2 to 3 month extension path.
+
+**Why:** The fastest way to lose is to design a beautiful plan that cannot be implemented in time.
+
+**Implementation effect:**  
+- Choose tools with low integration friction  
+- Prefer simple pipelines, cached assets, and deterministic demos  
+- Defer advanced quantification, multi-tenant systems, and deep workflow automation
+
+---
+
+### 3. Is the product definitely operator-first, or do you want municipality and compliance users treated as equal priority?
+**Decision:** The product is **definitely operator-first**.
+
+**Why:** Operators have the clearest action after an alert: inspect and mitigate. Municipality and compliance users are important, but they are better treated as secondary audiences for the first version.
+
+**Implementation effect:**  
+- UI language should focus on inspection priority and site action  
+- Incident object should emphasize source zone and follow-up recommendations  
+- Compliance export remains future work, not the main workflow
+
+---
+
+### 4. Do you want the master plan to stay hackathon-scoped, or include a serious post-hackathon roadmap too?
+**Decision:** Include both, but with clear separation: **hackathon MVP first, post-hackathon roadmap second**.
+
+**Why:** Judges like believable growth, but they score what exists now.
+
+**Implementation effect:**  
+- Main body focuses on MVP  
+- Final section includes phase 2 and phase 3 roadmap  
+- No roadmap item should be required to validate MVP success
+
+---
+
+### 5. Should the plan sound like a product strategy document, an engineering build plan, or both equally?
+**Decision:** **Both equally**, with engineering slightly dominant.
+
+**Why:** The team needs something buildable, but the demo and judging also require a crisp product story.
+
+**Implementation effect:**  
+- Include product framing, user workflow, pricing logic, and competitors  
+- Include APIs, schemas, architecture, tests, milestones, and evaluation
+
+---
+
+### 6. What is the single most important thing judges and users should remember about LandfillSentry?
+**Decision:**  
+**LandfillSentry turns satellite imagery into an explainable methane incident object that tells operators where to inspect first.**
+
+**Why:** This is clearer and stronger than saying “we detect methane” or “we built a dashboard.”
+
+**Implementation effect:**  
+- Every demo screen and API output should reinforce this sentence  
+- Avoid generic Earth observation storytelling
+
+---
+
+# 2. User and Workflow
+
+### 7. Who exactly is the primary user in your head?
+**Decision:** The primary user is a **landfill operations manager** or site operations lead.
+
+**Why:** This role has direct responsibility, understands site zones, and can act quickly.
+
+**Implementation effect:**  
+- Design screens for operational triage, not policy reporting  
+- Use plain operational wording rather than policy-heavy terminology
+
+---
+
+### 8. What is the intended user action after an alert?
+**Decision:** The intended action is: **inspect a zone on site**, then optionally log or escalate if needed.
+
+**Why:** “Inspect the site” is too broad. “Inspect a zone” is actionable.
+
+**Implementation effect:**  
+- The incident object must include a likely source zone and priority tier  
+- Recommendations should be site-action oriented
+
+---
+
+### 9. Do you want the product to prioritize single-site deep analysis or multi-site watchlist triage as the first-class workflow?
+**Decision:** **Multi-site watchlist triage** should be the first-class workflow, with drill-down into single-site analysis.
+
+**Why:** It feels more like a real product and is stronger in demo form. It also matches how operators or municipalities would prioritize scarce field effort.
+
+**Implementation effect:**  
+- Home view should be a watchlist of monitored sites  
+- Clicking a site opens the incident timeline and evidence details
+
+---
+
+### 10. Should the incident object include only recommendation text, or also a structured priority and severity tier?
+**Decision:** Include **structured priority and severity tiers** in addition to recommendation text.
+
+**Why:** Structured outputs are easier for downstream systems and better for judge evaluation.
+
+**Implementation effect:**  
+- Add fields such as `priority_tier`, `severity_tier`, and `recommended_followup`  
+- Use controlled enums rather than free text only
+
+---
+
+### 11. Do you want operator feedback in v1, such as confirmed, dismissed, or needs review?
+**Decision:** **Yes**, but keep it minimal.
+
+**Why:** Feedback closes the loop, enables future learning, and makes the product feel more real.
+
+**Implementation effect:**  
+- Add a simple status field: `confirmed`, `dismissed`, `needs_review`  
+- Store feedback in the incident table  
+- Do not build active learning automation yet
+
+---
+
+### 12. Should there be a human review step before any incident becomes official in the UI?
+**Decision:** **Yes**, at least in v1.
+
+**Why:** This is the safest and most defensible framing. The system is a triage copilot, not final truth.
+
+**Implementation effect:**  
+- Incidents first appear as `proposed`  
+- Human action promotes them to `published` or `dismissed`
+
+---
+
+# 3. Geography and Demo Sites
+
+### 13. Are you already committed to a specific country or region for demo sites?
+**Decision:** No hard commitment. Use a **globally framed product** with a small curated demo set from regions where imagery and site context look clean.
+
+**Why:** This avoids unnecessary geographic narrowing and lets you pick visually strong examples.
+
+**Implementation effect:**  
+- Product copy remains global  
+- Demo dataset can include 3 to 5 sites from different regions if useful
+
+---
+
+### 14. Do you already have 3 to 5 demo landfill coordinates or polygons selected?
+**Decision:** Not yet, but you **should select them early and freeze them**.
+
+**Why:** Demo stability depends on fixed sites.
+
+**Implementation effect:**  
+- Define a frozen demo site list in the first implementation phase  
+- Cache assets and panels for those sites
+
+---
+
+### 15. Are your demo sites meant to be real known landfill sites, or semi-fictionalized demo locations?
+**Decision:** Use **real known landfill sites**, but present them carefully as demonstrative case study sites.
+
+**Why:** Real sites increase credibility and make the demo feel grounded.
+
+**Implementation effect:**  
+- Use publicly observable sites  
+- Avoid making legal claims about actual emissions without proper qualification
+
+---
+
+### 16. Do you want the plan to assume site polygons are available, or only point coordinates?
+**Decision:** Assume **point coordinates are always available** and **polygons are optional enhancements**.
+
+**Why:** Coordinates are easier to obtain consistently. Polygons improve zoning, but should not block the MVP.
+
+**Implementation effect:**  
+- MVP works with center point plus fixed buffer  
+- Polygon-aware workflows can be layered later
+
+---
+
+### 17. Should we include a path for facility-zone priors such as active face, gas infrastructure, cover system, perimeter from day one?
+**Decision:** **Yes, include the path from day one**, but only implement the simplest version in MVP.
+
+**Why:** Source-zone reasoning is one of the most differentiated parts of the idea.
+
+**Implementation effect:**  
+- Start with coarse zone categories: `active_face`, `gas_system`, `perimeter_or_unknown`  
+- Expand the taxonomy later
+
+---
+
+### 18. Do you want India-specific examples in the final plan, or keep it globally framed?
+**Decision:** Keep the product **globally framed**, with optional India-specific examples in a note or appendix if desired.
+
+**Why:** Global framing is stronger for the hackathon.
+
+**Implementation effect:**  
+- Do not anchor the entire pitch to India  
+- Use India only if a selected demo site is visually strong or strategically relevant
+
+---
+
+# 4. Data and Labeling
+
+### 19. How many labeled examples do you realistically think you can create before the deadline?
+**Decision:** Plan for **80 to 200 usable labeled examples** total, depending on bandwidth.
+
+**Why:** This is realistic for a hackathon-scale manual effort when combined with synthetic and weak labels.
+
+**Implementation effect:**  
+- Do not assume thousands of hand labels  
+- Lean on candidate generation, synthetic overlays, and curated negatives
+
+---
+
+### 20. Will labels be created by you alone, or is there a team?
+**Decision:** Assume **you are the primary labeler**, with optional support if teammates help.
+
+**Why:** Planning around a team that may not deliver creates risk.
+
+**Implementation effect:**  
+- Annotation guidelines must be simple and fast  
+- Labeling workflow should be optimized for one primary operator
+
+---
+
+### 21. Do you want synthetic plume data to be a major part of the training set, or just a bootstrap layer?
+**Decision:** Synthetic plume data should be a **major bootstrap component**, but not the only component.
+
+**Why:** Synthetic examples help coverage, especially early, but real examples and hard negatives are necessary for credibility.
+
+**Implementation effect:**  
+- Treat synthetic as a training accelerator  
+- Keep validation and demo splits as real as possible
+
+---
+
+### 22. Do you want weak labels and manual labels tracked separately in the plan?
+**Decision:** **Yes, absolutely.**
+
+**Why:** Provenance matters for debugging and evaluation.
+
+**Implementation effect:**  
+- Every sample should have a `label_source` field  
+- Allowed values: `manual`, `weak`, `synthetic`, `mixed`
+
+---
+
+### 23. Should negative examples be explicitly budgeted and tracked as a first-class dataset requirement?
+**Decision:** **Yes.**
+
+**Why:** Null scenes, false positives, and visually confusing negatives are crucial for this product.
+
+**Implementation effect:**  
+- Maintain a negative-example target in the dataset plan  
+- Include clouds, smoke-like patterns, bright surfaces, and visually complex landfill scenes
+
+---
+
+### 24. Do you want a frozen validation split and a frozen demo split defined early?
+**Decision:** **Yes.**
+
+**Why:** Without frozen splits, the evaluation story becomes weak and the demo becomes unstable.
+
+**Implementation effect:**  
+- Define train, validation, and demo manifests early  
+- Never fine-tune on the demo split
+
+---
+
+### 25. Should the plan include dataset versioning with manifests and provenance per sample?
+**Decision:** **Yes.**
+
+**Why:** This is worth the small setup cost.
+
+**Implementation effect:**  
+- Store manifest JSON or CSV files  
+- Track site id, date, imagery source, label source, panel generator version, and split
+
+---
+
+### 26. Do you want annotation guidance written into the plan, including what counts as plume_likely and how bbox labels are set?
+**Decision:** **Yes.**
+
+**Why:** Consistency matters even with a small dataset.
+
+**Implementation effect:**  
+- Write a short annotation handbook  
+- Include edge cases, confidence rules, and box placement guidance
+
+---
+
+# 5. Technical Choices
+
+### 27. Is SimSat the only imagery path we should assume for MVP, or may the plan include fallback retrieval options?
+**Decision:** **SimSat is the primary imagery path for MVP**, but the plan may mention fallback retrieval options as future or contingency paths.
+
+**Why:** The hackathon explicitly centers SimSat and DPhi imagery.
+
+**Implementation effect:**  
+- All required MVP flows should work with SimSat only  
+- Fallbacks should not be dependency blockers
+
+---
+
+### 28. Is Mapbox context mandatory for MVP, or optional if token and setup become painful?
+**Decision:** Mapbox context is **strongly recommended but not mandatory**.
+
+**Why:** It improves site grounding and demo quality, but the product should still run without it.
+
+**Implementation effect:**  
+- The pipeline must gracefully degrade if Mapbox is unavailable  
+- Missing Mapbox becomes a tested failure mode, not a blocker
+
+---
+
+### 29. Do you want Project Eucalyptus integrated into MVP, or treated as a recommended enhancement or benchmark path?
+**Decision:** Treat Project Eucalyptus as a **recommended benchmark and bootstrap path**, with selective integration where practical.
+
+**Why:** It is valuable, but should not become an integration trap.
+
+**Implementation effect:**  
+- Reuse ideas, training assets, or post-processing patterns  
+- Do not make MVP success depend on deep codebase coupling
+
+---
+
+### 30. Should candidate generation start heuristic-first, model-assisted-first, or hybrid from day one?
+**Decision:** Use a **hybrid** approach from day one, but keep the heuristic layer simple and dependable.
+
+**Why:** Pure heuristics may be brittle; pure model-first may be unstable. Hybrid is safer.
+
+**Implementation effect:**  
+- Start with spectral or temporal anomaly heuristics  
+- Allow optional candidate ranking or refinement from learned components
+
+---
+
+### 31. Do you want FastAPI locked in as backend, or still open?
+**Decision:** **Lock in FastAPI.**
+
+**Why:** It is fast to build, easy to document, and good for typed JSON APIs.
+
+**Implementation effect:**  
+- Define API contracts early  
+- Use FastAPI for both local and deployable backend modes
+
+---
+
+### 32. Do you want React for the web app, or would Streamlit be acceptable for the first shipping version?
+**Decision:** **React for the primary web app**. Streamlit is acceptable only as an internal prototyping aid.
+
+**Why:** Judges reward polished demos, and React gives better control.
+
+**Implementation effect:**  
+- Build a lightweight React app with a few strong screens  
+- Keep Streamlit optional for internal analysis only
+
+---
+
+### 33. For storage, do you want SQLite first, or Postgres from the beginning?
+**Decision:** Start with **SQLite**.
+
+**Why:** It is enough for MVP and simpler to ship.
+
+**Implementation effect:**  
+- Use SQLModel or SQLAlchemy with migration-ready schema design  
+- Keep schema compatible with later Postgres migration
+
+---
+
+### 34. Should inference be synchronous for MVP, or do you want background jobs and polling or websocket flow designed from the start?
+**Decision:** Use **synchronous inference for MVP**, with small cached workflows. Background jobs can be a future upgrade.
+
+**Why:** Synchronous flow is easier to reason about and demo.
+
+**Implementation effect:**  
+- API calls can block briefly during scan generation  
+- Heavy jobs should be precomputed or cached
+
+---
+
+### 35. Do you want Transformers to be the only supported inference path in the first plan, or should we spec a fallback like ONNX or GGUF too?
+**Decision:** Use **Transformers as the main path**, but mention ONNX and GGUF as deployment fallbacks.
+
+**Why:** The first implementation needs one canonical path. Fallbacks are useful for later optimization and edge deployment narratives.
+
+**Implementation effect:**  
+- Build and test on one primary inference stack  
+- Keep deployment abstraction thin so fallback export remains possible
+
+---
+
+# 6. Model and Evaluation
+
+### 36. Is fine-tuning mandatory for success, or is prompt-only plus structured output acceptable as fallback?
+**Decision:** Fine-tuning is **strongly preferred and should be treated as a major goal**, but prompt-only structured output is an acceptable fallback.
+
+**Why:** The hackathon explicitly rewards domain fine-tuning. Still, a backup path is smart.
+
+**Implementation effect:**  
+- Build the system so base-model prompting works first  
+- Add LoRA fine-tuning as the quality upgrade path
+
+---
+
+### 37. Which matters more for you: bbox quality, JSON validity, source-zone accuracy, persistence score quality, or operator usefulness?
+**Decision:** The ranking should be:
+1. **Operator usefulness**
+2. **JSON validity**
+3. **Source-zone accuracy**
+4. **BBox quality**
+5. **Persistence score quality**
+
+**Why:** The product wins if the output is useful and reliable for action. A perfect score that nobody can act on is less valuable.
+
+**Implementation effect:**  
+- Evaluation should not be over-optimized on one visual metric  
+- Human actionability scoring should be included
+
+---
+
+### 38. Do you want the plan to commit to numeric targets now, or keep some as provisional until we see real data?
+**Decision:** Keep most targets **provisional**, with a few directional targets.
+
+**Why:** Hard numeric claims made too early can backfire.
+
+**Implementation effect:**  
+- Use target ranges instead of rigid commitments  
+- Example: JSON validity above 95 percent on validation set, null-scene false positive rate below a chosen threshold, but mark them as provisional
+
+---
+
+### 39. Should we evaluate on held-out sites, held-out dates, or both?
+**Decision:** Evaluate on **both held-out sites and held-out dates**.
+
+**Why:** Generalization matters across geography and time.
+
+**Implementation effect:**  
+- Create separate evaluation views  
+- Report both temporal generalization and cross-site transfer
+
+---
+
+### 40. Do you want baseline comparison against base LFM2.5-VL-450M, candidate-only heuristics, and fine-tuned model all three?
+**Decision:** **Yes, compare all three.**
+
+**Why:** This creates a stronger scientific and product story.
+
+**Implementation effect:**  
+- Baseline A: heuristic or candidate-only  
+- Baseline B: base LFM2.5-VL  
+- Final: fine-tuned LFM2.5-VL
+
+---
+
+### 41. Should the plan include human scoring of actionability and explainability?
+**Decision:** **Yes.**
+
+**Why:** These are central to the product and often missed by purely technical metrics.
+
+**Implementation effect:**  
+- Add a small rubric for human review  
+- Score whether the incident object is understandable and useful for follow-up
+
+---
+
+### 42. Do you want calibration or confidence-threshold tuning explicitly included?
+**Decision:** **Yes, lightly.**
+
+**Why:** Thresholds matter for operational usefulness.
+
+**Implementation effect:**  
+- Include simple threshold sweeps  
+- Do not overcomplicate with heavy calibration research in MVP
+
+---
+
+### 43. Should no anomaly or null-scene performance be a major metric?
+**Decision:** **Yes, it should be a major metric.**
+
+**Why:** False positives will destroy trust quickly.
+
+**Implementation effect:**  
+- Track null-scene precision or false positive rate explicitly  
+- Build a robust negative set
+
+---
+
+# 7. Testing and Integration
+
+### 44. Do you want a formal rule that no phase is marked done until it passes an integration checkpoint with previous phases?
+**Decision:** **Yes.**
+
+**Why:** Integration failures kill hackathon projects.
+
+**Implementation effect:**  
+- Each phase closes only after a working end-to-end checkpoint
+
+---
+
+### 45. Should every phase end with one live path and one cached offline path?
+**Decision:** **Yes.**
+
+**Why:** Cached offline paths protect the demo and speed debugging.
+
+**Implementation effect:**  
+- Every major flow should have reproducible cached artifacts  
+- Live and offline modes should both be supported
+
+---
+
+### 46. Do you want unit, integration, and end-to-end tests all explicitly planned in every phase?
+**Decision:** **Yes**, but keep the scope pragmatic.
+
+**Why:** This gives quality without going overboard.
+
+**Implementation effect:**  
+- Unit tests for helpers and parsers  
+- Integration tests for API and inference contracts  
+- At least one end-to-end scan test
+
+---
+
+### 47. Should we define golden fixtures for at least one positive site, one negative site, one cloudy site, and one missing-data site?
+**Decision:** **Yes.**
+
+**Why:** These become the backbone of reliability testing.
+
+**Implementation effect:**  
+- Freeze fixture data early  
+- Use them across backend and UI tests
+
+---
+
+### 48. Do you want frontend smoke tests in the plan, or keep frontend verification manual for MVP?
+**Decision:** Include **basic frontend smoke tests**, but keep most UI verification manual.
+
+**Why:** A few smoke tests are worth it, full automation is not necessary for MVP.
+
+**Implementation effect:**  
+- Test critical render and API-wiring paths  
+- Validate most styling and interactions manually
+
+---
+
+### 49. Should we include API contract tests and a committed openapi.json as part of the plan?
+**Decision:** **Yes.**
+
+**Why:** Strong APIs are part of the product thesis.
+
+**Implementation effect:**  
+- Generate and commit OpenAPI schema  
+- Write contract tests for main endpoints
+
+---
+
+### 50. Do you want failure-injection tests for invalid JSON, empty candidates, missing Mapbox, and slow inference?
+**Decision:** **Yes.**
+
+**Why:** These are highly likely failures in the real build.
+
+**Implementation effect:**  
+- Add specific tests for each failure mode  
+- UI must degrade gracefully
+
+---
+
+### 51. Should we require one full end-to-end scan after every 2 phases before advancing?
+**Decision:** **Yes.**
+
+**Why:** This keeps momentum aligned around a real working system.
+
+**Implementation effect:**  
+- Insert hard demo checkpoints throughout the build plan  
+- No long isolated implementation branches
+
+---
+
+# 8. Delivery and Business Framing
+
+### 52. Do you want the plan to include pricing, GTM, and buyer wedge in detail, or keep it mostly technical?
+**Decision:** Include **light but serious GTM and buyer wedge detail**, while keeping the document mostly technical.
+
+**Why:** The hackathon entry should sound commercially credible, but not become a sales deck.
+
+**Implementation effect:**  
+- Include buyer, pricing logic, and wedge narrative  
+- Keep most pages focused on implementation and product design
+
+---
+
+### 53. Should the final plan explicitly position LandfillSentry relative to WasteMAP, UNEP MARS, and Carbon Mapper, or only lightly reference them?
+**Decision:** **Explicitly position it relative to them.**
+
+**Why:** Judges and future users will care about differentiation.
+
+**Implementation effect:**  
+- Add a concise competitor positioning section  
+- Explain that LandfillSentry is an operator-first triage copilot, not a global methane data platform
+
+---
+
+### 54. Do you want the final plan to include security, secrets, licensing, and model and data usage risks?
+**Decision:** **Yes.**
+
+**Why:** These are practical startup and deployment concerns and make the document stronger.
+
+**Implementation effect:**  
+- Add a short security and risk section  
+- Cover API tokens, model licenses, data licensing, and disclosure risks
+
+---
+
+### 55. Should we include a roadmap for compliance evidence export and regulator-facing workflows, or leave that as future work?
+**Decision:** Include it as **future work on the roadmap**, not as MVP.
+
+**Why:** It is valuable, but not necessary to win the hackathon.
+
+**Implementation effect:**  
+- Mention evidence export templates, audit trails, and regulator workflows in phase 2 or phase 3  
+- Do not let them expand MVP scope
+
+---
+
+### 56. Do you want the final document to remain single-file like AdaptOpt, with appended execution cards and change log?
+**Decision:** **Yes.**
+
+**Why:** A single-file master document is easier to manage during a fast build.
+
+**Implementation effect:**  
+- Keep one canonical Markdown file  
+- Append execution cards, assumptions, change log, and milestone updates at the end
+
+---
+
+# Recommended frozen defaults summary
+
+This section compresses the decisions into one quick-reference view.
+
+## Product
+- Goal: Win the hackathon with a real MVP
+- Product type: Operator-first methane incident triage copilot
+- Core memory line: Turn satellite imagery into an explainable incident object telling operators where to inspect first
+
+## User
+- Primary user: Landfill operations manager
+- Primary action: Inspect a likely source zone
+- First-class workflow: Multi-site watchlist triage with single-site drill-down
+- Human review: Required before incident is official
+- Feedback loop: Minimal v1 support
+
+## Geography
+- Global framing
+- Freeze 3 to 5 demo sites early
+- Use real sites with careful wording
+- Coordinates required, polygons optional
+
+## Data
+- 80 to 200 usable labeled examples target
+- One primary labeler assumption
+- Synthetic plumes: major bootstrap layer
+- Weak and manual labels tracked separately
+- Negative examples first-class
+- Frozen validation and demo splits
+- Dataset manifests and provenance required
+- Annotation guidelines required
+
+## Tech
+- SimSat-first
+- Mapbox recommended but optional
+- FastAPI backend
+- React frontend
+- SQLite for MVP
+- Synchronous inference first
+- Transformers primary inference path
+- ONNX or GGUF mentioned as future fallback
+
+## Model
+- Fine-tuning preferred, prompt-only fallback allowed
+- Prioritize usefulness, valid JSON, and zone accuracy
+- Numeric targets provisional
+- Evaluate on held-out sites and dates
+- Compare heuristics, base model, and fine-tuned model
+- Include actionability and explainability review
+- Include threshold tuning
+- Track null-scene performance
+
+## Testing
+- Integration gate per phase
+- Live plus cached path per phase
+- Unit, integration, and end-to-end tests
+- Golden fixtures required
+- Basic frontend smoke tests
+- OpenAPI contract committed
+- Failure injection required
+- Full end-to-end scan after every 2 phases
+
+## Business and delivery
+- Mostly technical document with light GTM
+- Explicit competitor positioning
+- Security, licensing, and secrets included
+- Compliance export kept for roadmap
+- Single-file canonical plan
+
+---
+
+# Suggested next action
+
+The next document should convert these frozen answers into a **master execution plan** with:
+1. phased milestones,
+2. repo structure,
+3. dataset schema,
+4. API definitions,
+5. evaluation table,
+6. demo script,
+7. execution cards,
+8. change log.
+
+This document is now the source of truth for those choices.

project_docs/LandfillSentry_Ops_Detailed_Report.md

@@ -0,0 +1,2093 @@
+
+# LandfillSentry Ops  
+## Detailed Product, Architecture, Data, API, and Execution Report  
+### Version 1.0  
+### Date: 19 April 2026
+
+---
+
+## Document Purpose
+
+This document is a complete starter dossier for building **LandfillSentry Ops**, an operator-first landfill methane triage copilot for the Liquid AI x DPhi Space AI in Space Hackathon. It is written to be the single document a team can use to move from idea to implementation without needing a separate concept note, architecture memo, or initial build plan.
+
+The report covers:
+
+- problem framing and product thesis
+- why this use case is a strong fit for the hackathon
+- target users and buyer wedge
+- detailed system architecture
+- external APIs, datasets, and open-source frameworks
+- internal API design
+- model strategy and fine-tuning plan
+- evaluation plan and success criteria
+- deployment design
+- security, risk, and failure modes
+- implementation plan, sprint plan, and repository structure
+- hackathon demo strategy
+- roadmap beyond the hackathon
+
+This document is intentionally detailed. It is optimized for execution, not just persuasion.
+
+---
+
+## Table of Contents
+
+1. Executive Summary  
+2. Why This Idea Wins the Hackathon  
+3. Problem Definition  
+4. Product Vision  
+5. Users, Stakeholders, and Initial Buyer  
+6. Why Landfill Methane Instead of Other Domains  
+7. Solution Overview  
+8. System Requirements  
+9. High-Level Architecture  
+10. Data Sources and External Systems  
+11. External APIs and Frameworks Required  
+12. Internal Service Design  
+13. Detailed Data Flow  
+14. Detection and Candidate Generation Pipeline  
+15. Vision-Language Model Layer  
+16. Fine-Tuning Strategy  
+17. Dataset Strategy  
+18. Prompting and Output Schemas  
+19. Evaluation Plan  
+20. Product UX and Demo Flow  
+21. Backend API Specification  
+22. Data Models  
+23. Deployment and Infrastructure  
+24. GPU and Training Plan  
+25. Implementation Roadmap  
+26. Repository Structure  
+27. Engineering Work Breakdown  
+28. Risks and Mitigations  
+29. Stretch Features  
+30. Submission Strategy  
+31. Final Build Recommendation  
+32. References  
+
+---
+
+## 1. Executive Summary
+
+**LandfillSentry Ops** is an operator-first landfill methane triage copilot that turns multispectral satellite imagery into explainable incident alerts for landfill teams. The product scans landfill sites using **Sentinel-2** imagery retrieved through **SimSat**, uses temporal and spectral analysis to generate candidate methane-emission regions, grounds those candidates with **Mapbox** facility context imagery, and passes a compact evidence panel to a fine-tuned **Liquid AI LFM2.5-VL-450M** model. The model returns a structured incident object with:
+
+- plume likely or not likely
+- bounding box
+- likely source zone
+- persistence score
+- evidence summary
+- recommended inspection priority
+
+The product is deliberately framed as a **triage and prioritization system**, not a final regulatory quantification engine. That framing is important both technically and strategically. It matches the strengths of the available sensor stack, aligns with what a small fine-tuned VLM can do well, and is more defensible within hackathon scope.
+
+The core thesis is simple:
+
+> Existing methane monitoring ecosystems increasingly detect and map methane events, but landfill operators still need a lightweight product that turns raw or semi-processed geospatial evidence into an actionable, facility-specific incident object.
+
+That gap is where LandfillSentry Ops sits.
+
+### Why this is a strong hackathon idea
+
+This idea matches the Liquid Track unusually well:
+
+1. **Use of satellite imagery is central, not decorative.**  
+   The product depends on Sentinel-2 multispectral imagery for methane-sensitive analysis and on Mapbox imagery for facility context.
+
+2. **Liquid’s VLM is not bolted on.**  
+   The VLM is used for grounded interpretation, structured incident generation, evidence summarization, and operator guidance. LFM2.5-VL’s bounding-box capability is especially valuable here.
+
+3. **There is a clean fine-tuning path.**  
+   Liquid explicitly recommends fine-tuning LFM2.5-VL-450M for use-case-specific performance. Project Eucalyptus gives us a methane-domain bootstrapper with models, post-processing tooling, and synthetic plume generation.
+
+4. **The problem is real and commercially believable.**  
+   Waste-sector methane is large, actionable, and under-addressed relative to oil and gas. Multiple public initiatives now show operator, policy, and mitigation demand.
+
+5. **The demo can be strong and clean.**  
+   The system can be demonstrated end to end with a simple, memorable operator workflow.
+
+### One-line pitch
+
+**LandfillSentry Ops turns Sentinel-2 and Mapbox imagery into explainable methane incident alerts that tell landfill operators where to inspect first.**
+
+---
+
+## 2. Why This Idea Wins the Hackathon
+
+The hackathon rewards four things:
+
+- use of DPhi satellite imagery
+- innovation and problem-solution fit
+- technical implementation that runs cleanly
+- demo clarity
+
+This product scores well across all four.
+
+### 2.1 Use of DPhi satellite imagery
+
+SimSat provides current and historical access to Sentinel-2 and Mapbox imagery. Sentinel-2 is the main source for temporal and multispectral analysis, while Mapbox provides sharper RGB context for interpreting site structure and grounding operator actions. This is exactly the kind of combined imagery workflow the SimSat stack enables best.  
+Source: [SimSat GitHub README](https://github.com/DPhi-Space/SimSat)
+
+### 2.2 Innovation and problem-solution fit
+
+A generic “satellite dashboard” is not enough. This product is more specific and therefore more compelling:
+
+- it is focused on **landfills**, not all methane sources
+- it is focused on **operations**, not generic environmental storytelling
+- it returns a **developer-ready incident object**, not just a visualization
+- it uses the VLM to produce **grounded interpretation**, not vague captioning
+
+The combination of a methane-sensitive candidate-generation step plus a fine-tuned small VLM is also differentiated. The first stage handles spectral physics better than a generic VLM could. The second stage handles interpretation, ranking, and operator communication better than a pure CV system could.
+
+### 2.3 Technical implementation fit
+
+This is executable within hackathon scope because the stack can be decomposed into practical stages:
+
+- data ingestion via SimSat
+- candidate generation using spectral composites and temporal differencing
+- optional methane bootstrap via Project Eucalyptus
+- evidence-panel construction
+- structured inference via LFM2.5-VL-450M
+- results served through a simple FastAPI backend
+- demo UI built in React or Streamlit
+
+Nothing in that chain requires inventing new science during the hackathon.
+
+### 2.4 Demo fit
+
+Judges respond well to clear operational narratives. “Here is a suspected methane issue, here is the part of the landfill to inspect, and here is why the system believes that” is much easier to communicate than a generic Earth observation product.
+
+---
+
+## 3. Problem Definition
+
+Landfills are major methane sources. Methane is a short-lived but highly potent greenhouse gas, and waste-sector methane is a significant share of anthropogenic methane emissions. Public reporting and mitigation efforts are improving, but current inventories and routine monitoring approaches remain incomplete, inconsistent, or delayed in many regions.  
+Sources:  
+- [METER preprint](https://essd.copernicus.org/preprints/essd-2026-124/essd-2026-124.pdf)  
+- [ESA Landfill Methane Monitor](https://business.esa.int/projects/landfill-methane-monitor-lmm)  
+- [CATF waste methane trends 2026](https://www.catf.us/2026/03/three-trends-shaping-waste-sector-methane-mitigation-2026/)
+
+### 3.1 The operator’s actual problem
+
+A landfill operator does not merely want to know that methane exists at the site. They want to know:
+
+- whether there is a likely event worth investigating
+- which zone of the facility is most likely involved
+- whether this looks persistent or transient
+- how urgent the issue is relative to other sites or zones
+- what evidence supports the alert
+
+Many current tools in the ecosystem focus on mapping emissions, generating public data portals, or enabling scientific and policy analysis. Those are valuable, but operators often still need something simpler and more direct: a triage system that compresses geospatial evidence into a usable action object.
+
+### 3.2 Why this gap matters
+
+If a satellite workflow only says “possible methane plume near this facility,” there is still too much cognitive load on the user:
+
+- Which part of the facility should I inspect?
+- Is this likely a persistent issue or just a one-off anomaly?
+- Is the source likely near the active surface, gas collection system, or another facility zone?
+- Is this likely a real signal or a data artifact?
+
+LandfillSentry Ops is designed to answer these questions.
+
+---
+
+## 4. Product Vision
+
+LandfillSentry Ops should be understood as a **developer API plus operator UI**.
+
+### 4.1 Product definition
+
+At its core, the product converts geospatial evidence into a standardized incident object.
+
+**Input**
+- landfill coordinates or polygon
+- time window
+- image size
+- spectral configuration
+- optional site metadata
+
+**Output**
+- site ID
+- alert timestamp
+- plume likely boolean
+- candidate region bounding box
+- likely source zone label
+- persistence score
+- confidence score
+- short evidence summary
+- recommended next action
+
+### 4.2 Product promise
+
+> “Give us your landfill watchlist and we will tell you where to inspect first, based on multispectral satellite evidence and a fine-tuned grounded vision-language model.”
+
+### 4.3 Product boundaries
+
+This product **does not** aim to deliver:
+- regulatory-grade quantification
+- final legal liability attribution
+- full atmospheric inversion
+- nighttime continuous coverage
+- final safety-critical decision authority
+
+Those can be future directions, but they are not the correct first scope.
+
+---
+
+## 5. Users, Stakeholders, and Initial Buyer
+
+### 5.1 Primary user
+
+**Landfill operations manager or environmental compliance lead**
+
+What they care about:
+- which sites require attention
+- which areas within a site may be responsible
+- which issues look persistent
+- which alerts merit inspection first
+
+### 5.2 Secondary users
+
+- municipal solid waste authority
+- environmental consultant
+- climate program team
+- insurer or risk analyst
+- policy monitoring team
+
+### 5.3 Initial buyer wedge
+
+The strongest first buyer is the **operator-side team**, not the insurer or regulator.
+
+Why:
+- clearer daily workflow
+- stronger demo story
+- easier to show immediate value
+- lower proof burden than full compliance systems
+- more believable hackathon MVP
+
+### 5.4 Expansion path
+
+After hackathon MVP:
+1. operator triage
+2. municipality dashboard
+3. compliance evidence export
+4. insurer/portfolio risk scoring
+5. waste-sector benchmarking
+
+---
+
+## 6. Why Landfill Methane Instead of Other Domains
+
+This section summarizes why this domain beat the main alternatives during idea selection.
+
+### 6.1 Versus crop monitoring
+
+Crop monitoring is a good fit for Sentinel-2, but it is crowded and highly familiar. Judges are likely to see many variants of crop stress, irrigation, and yield analytics.
+
+### 6.2 Versus wildfire
+
+Wildfire is compelling, but the strongest operational wildfire systems typically rely on thermal imagery or broader sensor stacks. SimSat’s strongest advantage is Sentinel-2 plus Mapbox, not thermal fire-detection constellations.
+
+### 6.3 Versus marine or illegal fishing
+
+Those use cases typically require richer maritime context, vessel tracking data, and other modalities. They are less cleanly aligned with the available imagery stack.
+
+### 6.4 Versus generic oil-and-gas methane
+
+Oil-and-gas methane is highly relevant and technically strong, but the category is crowded. Public and private systems such as MARS, Kayrros, and Carbon Mapper already make the space feel more saturated. Landfill methane is still real and urgent, but the product whitespace is cleaner.  
+Sources:  
+- [UNEP MARS](https://www.unep.org/topics/energy/methane/methane-alert-and-response-system-mars)  
+- [Carbon Mapper](https://carbonmapper.org/)  
+- [CATF waste-sector article](https://www.catf.us/2026/03/three-trends-shaping-waste-sector-methane-mitigation-2026/)
+
+### 6.5 Why landfill methane is the sweet spot
+
+This use case has:
+- strong satellite dependence
+- meaningful temporal analysis
+- facility context value from high-res imagery
+- real operational and climate relevance
+- manageable scope for a hackathon MVP
+
+---
+
+## 7. Solution Overview
+
+LandfillSentry Ops uses a two-stage intelligence pipeline:
+
+### Stage A: Candidate Generation
+Generate likely methane candidate regions using Sentinel-2 imagery and historical comparisons.
+
+### Stage B: Incident Interpretation
+Use a fine-tuned Liquid VLM to convert evidence panels into grounded, structured, human-usable incident objects.
+
+This split is important. It prevents the VLM from having to discover everything from scratch and improves reliability.
+
+### 7.1 Core product output
+
+```json
+{
+  "site_id": "LF_IND_001",
+  "analysis_time": "2026-04-19T11:15:00Z",
+  "plume_likely": true,
+  "confidence": 0.84,
+  "bbox_norm": [0.32, 0.18, 0.56, 0.43],
+  "likely_source_zone": "active_face",
+  "persistence_score": 0.72,
+  "evidence_summary": "A persistent SWIR anomaly appears near the active working area and recurs across recent cloud-acceptable scenes.",
+  "recommended_followup": "Inspect active face gas capture and cover integrity within 24 hours.",
+  "model_version": "lfm25vl450m-landfillsentry-lora-v1"
+}
+```
+
+---
+
+## 8. System Requirements
+
+### 8.1 Functional requirements
+
+The system must:
+1. ingest current and historical imagery for a given landfill
+2. support multiple spectral-band configurations
+3. generate candidate methane-risk regions
+4. build compact evidence panels for model input
+5. run VLM inference locally or on a GPU server
+6. return a standardized incident object
+7. expose results through a backend API
+8. show results in a simple web UI
+
+### 8.2 Non-functional requirements
+
+The system should:
+- run reproducibly on judges’ machines or a hosted instance
+- avoid fragile dependencies
+- fail gracefully when imagery is missing or too cloudy
+- return structured JSON, not only free text
+- keep inference latency acceptable for demo conditions
+
+### 8.3 Hackathon constraints
+
+- app must run without debugging
+- fine-tuning is rewarded
+- use of SimSat imagery is mandatory
+- documentation and demo quality matter
+
+---
+
+## 9. High-Level Architecture
+
+```mermaid
+flowchart TD
+    A[User / Watchlist] --> B[LandfillSentry API Gateway]
+    B --> C[Site Registry / Metadata]
+    B --> D[Imagery Retrieval Service]
+    D --> E[SimSat Sentinel-2 API]
+    D --> F[SimSat Mapbox API]
+
+    E --> G[Preprocessing & QC]
+    F --> G
+
+    G --> H[Candidate Generation Engine]
+    H --> I[Evidence Panel Builder]
+
+    I --> J[Liquid VLM Inference Service]
+    J --> K[Incident Object Generator]
+
+    K --> L[Results Store]
+    K --> M[Operator UI / Dashboard]
+    K --> N[Webhook / Export / Evidence Pack]
+```
+
+### 9.1 Major components
+
+1. **API Gateway**  
+   Accepts requests, validates input, manages watchlist scans, exposes results.
+
+2. **Site Registry**  
+   Stores landfill coordinates, polygons, metadata, and operator labels.
+
+3. **Imagery Retrieval Service**  
+   Fetches imagery from SimSat current and historical endpoints.
+
+4. **Preprocessing and Quality Control**  
+   Handles clouds, band selection, normalization, and temporal selection.
+
+5. **Candidate Generation Engine**  
+   Produces candidate regions based on spectral heuristics, temporal changes, and optional methane-specific models.
+
+6. **Evidence Panel Builder**  
+   Converts raw imagery and metadata into a compact multimodal input for the VLM.
+
+7. **Liquid VLM Inference Service**  
+   Runs fine-tuned LFM2.5-VL-450M and emits structured JSON.
+
+8. **Incident Object Generator**  
+   Validates output, applies business logic, computes alert priority.
+
+9. **Results Store and UI**  
+   Stores incidents, serves web UI, exports evidence packs.
+
+---
+
+## 10. Data Sources and External Systems
+
+### 10.1 SimSat
+
+SimSat is the official starting point for the hackathon. It provides:
+- a simulation dashboard
+- a control API
+- current satellite position
+- Sentinel-2 imagery endpoints
+- Mapbox imagery endpoints  
+Source: [SimSat GitHub README](https://github.com/DPhi-Space/SimSat)
+
+Relevant endpoints include:
+- `GET /data/current/position`
+- `GET /data/current/image/sentinel`
+- `GET /data/current/image/mapbox`
+- `GET /data/image/sentinel`
+- `GET /data/image/mapbox`
+
+### 10.2 Sentinel-2
+
+Sentinel-2 is the backbone for:
+- multispectral evidence
+- temporal history
+- wide-area site scanning
+- cloud metadata
+
+SimSat exposes band selection and historical windowing on top of Sentinel-2 retrieval.
+
+### 10.3 Mapbox
+
+Mapbox imagery is used for:
+- high-resolution site context
+- explaining where within the facility the candidate event is located
+- producing more intuitive operator visuals
+
+SimSat requires a `MAPBOX_ACCESS_TOKEN` to enable this path.  
+Source: [SimSat GitHub README](https://github.com/DPhi-Space/SimSat)
+
+### 10.4 METER
+
+METER is a global database of methane-emitting infrastructure that contains over 12.3 million entries and includes a first global estimate of landfill locations, with roughly 13,000 landfill sites and large ML-generated coverage.  
+Source: [METER preprint](https://essd.copernicus.org/preprints/essd-2026-124/essd-2026-124.pdf)
+
+Use in this project:
+- seed landfill watchlists
+- site matching
+- facility metadata enrichment
+- future benchmarking
+
+### 10.5 Project Eucalyptus
+
+Project Eucalyptus provides:
+- trained methane-plume models
+- end-to-end methane inference tooling
+- synthetic plume generation
+- post-processing and evaluation notebooks
+- Sentinel-2 support  
+Sources:  
+- [Project Eucalyptus GitHub](https://github.com/Orbio-Earth/Project-Eucalyptus)  
+- [Project Eucalyptus docs](https://orbio-earth.github.io/Project-Eucalyptus/)
+
+Use in this project:
+- bootstrap methane candidate generation
+- generate synthetic training examples
+- benchmark spectral candidate stages
+
+### 10.6 Optional weather or wind inputs
+
+Optional external sources may improve evidence interpretation or synthetic training:
+- Open-Meteo
+- ERA5
+- local meteorological APIs
+
+These are not required for the first MVP, but are useful if you want wind-aware synthetic plumes or better persistence interpretation.
+
+---
+
+## 11. External APIs and Frameworks Required
+
+This section lists everything needed to build the MVP.
+
+### 11.1 Required external APIs
+
+#### A. SimSat API
+Purpose:
+- current position
+- current Sentinel-2 image
+- current Mapbox image
+- historical Sentinel-2 image
+- historical Mapbox image
+
+Required for MVP: **Yes**
+
+#### B. Mapbox Access Token
+Purpose:
+- required by SimSat to return Mapbox imagery
+
+Required for MVP: **Yes, if Mapbox context is used**
+Source: [SimSat GitHub README](https://github.com/DPhi-Space/SimSat)
+
+### 11.2 Strongly recommended external model assets
+
+#### A. LiquidAI/LFM2.5-VL-450M
+Purpose:
+- multimodal structured reasoning
+- grounded bounding-box output
+- evidence summarization
+
+Required for MVP: **Yes**
+Source: [LFM2.5-VL-450M model card](https://huggingface.co/LiquidAI/LFM2.5-VL-450M)
+
+#### B. Project Eucalyptus assets
+Purpose:
+- methane-specific candidate generation
+- synthetic plume training bootstrap
+
+Required for MVP: **Strongly recommended**
+Source: [Project Eucalyptus GitHub](https://github.com/Orbio-Earth/Project-Eucalyptus)
+
+### 11.3 Optional external datasets
+
+#### A. METER
+Purpose:
+- site priors and watchlist enrichment
+Required for MVP: **Recommended**
+
+#### B. WasteMAP
+Purpose:
+- contextual understanding of waste methane landscape
+Required for MVP: **Optional**
+Source: [WasteMAP](https://wastemap.earth/)
+
+### 11.4 Required frameworks and libraries
+
+#### Backend
+- Python 3.11+
+- FastAPI
+- Uvicorn
+- Pydantic
+- SQLAlchemy
+- PostgreSQL or SQLite for MVP
+- Redis optional for job queue
+
+#### ML and data
+- PyTorch
+- Transformers
+- PEFT
+- Unsloth or TRL
+- NumPy
+- Rasterio
+- xarray optional
+- GeoPandas
+- shapely
+- Pillow
+- OpenCV optional
+- scikit-image
+- scikit-learn
+
+#### Geospatial ML
+- TorchGeo
+- TerraTorch optional
+- SamGeo optional
+
+#### Frontend
+- React + Vite, or
+- Next.js, or
+- Streamlit for faster MVP
+
+#### Deployment
+- Docker
+- Docker Compose
+- Modal for training or remote GPU
+- vLLM optional if serving on a larger GPU
+- ONNX Runtime optional for deployment experimentation
+
+### 11.5 Why these frameworks
+
+**TorchGeo** provides CRS-aware datasets, multispectral transforms, spatial samplers, and pretrained models for geospatial ML.  
+Source: [TorchGeo](https://torchgeo.org/)
+
+**TerraTorch** provides a configurable toolkit for fine-tuning geospatial foundation models and supports segmentation, classification, and pixel-wise regression workflows through configuration-driven training.  
+Source: [TerraTorch GitHub](https://github.com/terrastackai/terratorch)
+
+**SamGeo** simplifies segmentation workflows over geospatial imagery, which is useful for facility-zone overlays or optional polygon assist tools.  
+Source: [SamGeo docs](https://samgeo.gishub.org/)
+
+**Modal** is practical for GPU-backed LoRA fine-tuning and supports Unsloth-based training flows.  
+Source: [Modal Unsloth example](https://modal.com/docs/examples/unsloth_finetune)
+
+---
+
+## 12. Internal Service Design
+
+The recommended backend is a small service-oriented monolith, not a complex microservice architecture. Keep it simple for the hackathon, but design it cleanly enough to evolve.
+
+### 12.1 Services
+
+#### A. API Gateway / Orchestrator
+Handles:
+- scan requests
+- watchlist operations
+- site lookup
+- inference job triggering
+- response aggregation
+
+#### B. Site Registry Service
+Handles:
+- site metadata
+- landfill polygons or point locations
+- zone definitions
+- labels and notes
+
+#### C. Imagery Service
+Handles:
+- fetch from SimSat
+- historical image retrieval
+- image caching
+- metadata capture
+- cloud and availability filtering
+
+#### D. Candidate Generation Service
+Handles:
+- spectral heuristics
+- temporal differencing
+- optional Eucalyptus model execution
+- candidate bbox generation
+- anomaly scoring
+
+#### E. VLM Inference Service
+Handles:
+- prompt assembly
+- evidence panel construction
+- model loading
+- inference
+- JSON validation
+- confidence normalization
+
+#### F. Incident Service
+Handles:
+- final incident object creation
+- persistence scoring
+- priority assignment
+- storage and export
+
+#### G. UI Service
+Handles:
+- results display
+- site map
+- image overlays
+- evidence cards
+- operator workflow
+
+### 12.2 Why not microservices first
+
+Hackathons punish complexity. Use a modular codebase with clear boundaries, but deploy as one backend application unless you have a very strong reason not to.
+
+---
+
+## 13. Detailed Data Flow
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant API as FastAPI Backend
+    participant SIM as SimSat
+    participant CAND as Candidate Engine
+    participant VLM as Liquid VLM
+    participant DB as Database
+
+    U->>API: POST /scan-site
+    API->>SIM: GET historical Sentinel-2 images
+    API->>SIM: GET current Sentinel-2 image
+    API->>SIM: GET Mapbox context image
+    API->>CAND: preprocess and score anomaly regions
+    CAND-->>API: candidate bbox + features
+    API->>VLM: evidence panel + prompt
+    VLM-->>API: structured JSON incident
+    API->>DB: store result
+    API-->>U: incident object + visual assets
+```
+
+### 13.1 Step-by-step logic
+
+1. User requests scan for a landfill or selects a watchlist item.
+2. Backend fetches:
+   - current Sentinel-2 image
+   - N historical Sentinel-2 images
+   - Mapbox image for same target
+3. Backend filters poor scenes:
+   - no image available
+   - excessive cloud cover
+   - missing bands
+4. Candidate engine computes:
+   - spectral composites
+   - temporal differences
+   - anomaly scores
+   - candidate region proposals
+5. Evidence panel builder produces:
+   - RGB panel
+   - SWIR or methane-sensitive panel
+   - temporal comparison panel
+   - Mapbox context panel
+   - site metadata text
+6. Fine-tuned Liquid model receives evidence panel and prompt.
+7. Model emits structured JSON.
+8. Post-processing validates schema and computes final alert priority.
+9. UI displays incident and export card.
+
+---
+
+## 14. Detection and Candidate Generation Pipeline
+
+This is the most important non-VLM stage.
+
+### 14.1 Why a separate candidate stage is necessary
+
+A small VLM should not be asked to infer methane events directly from arbitrary full-scene imagery. That would be unreliable and inefficient. Instead, we should give it a compact, evidence-rich panel focused on promising regions.
+
+### 14.2 Candidate pipeline options
+
+#### Option A: Heuristic spectral screening
+Use a small set of domain-inspired spectral differences and temporal contrast rules to identify suspicious regions.
+
+Pros:
+- fast
+- easy to explain
+- no training required for first version
+
+Cons:
+- more false positives
+- weaker methane specificity
+
+#### Option B: Eucalyptus-assisted methane candidate generation
+Use Project Eucalyptus models and/or post-processing to propose plume-like candidate zones.
+
+Pros:
+- domain-specific
+- stronger methane alignment
+- better training bootstrap
+
+Cons:
+- more integration work
+- may require adaptation to SimSat output formatting
+
+#### Option C: Hybrid candidate generator
+Use heuristics first, then optional Eucalyptus refinement.
+
+**Recommended approach for MVP:** Hybrid
+
+### 14.3 Candidate scoring features
+
+The candidate engine can compute:
+- anomaly magnitude
+- recurrence across historical windows
+- cloud-adjusted confidence
+- distance to likely landfill operational zones
+- overlap with active or open areas inferred from Mapbox
+- spatial compactness
+- edge consistency
+
+### 14.4 Candidate outputs
+
+```json
+{
+  "candidate_id": "cand_001",
+  "site_id": "LF_IND_001",
+  "bbox_px": [128, 76, 241, 162],
+  "bbox_norm": [0.25, 0.15, 0.47, 0.32],
+  "candidate_score": 0.71,
+  "temporal_recurrence": 0.64,
+  "cloud_penalty": 0.12,
+  "spectral_signal_score": 0.78
+}
+```
+
+### 14.5 Landfill zone priors
+
+Later versions can split landfill space into coarse zones:
+- active face / working face
+- capped area
+- perimeter
+- gas collection field
+- leachate or utility area
+- unknown
+
+This can be inferred weakly from Mapbox imagery or manually provided for demo sites.
+
+---
+
+## 15. Vision-Language Model Layer
+
+### 15.1 Why LFM2.5-VL-450M
+
+Liquid’s LFM2.5-VL-450M is a very strong fit because it offers:
+- enhanced instruction following
+- bounding-box prediction and object detection
+- function calling for structured output
+- multiple deployment formats including native, GGUF, ONNX, and MLX
+- recommended fine-tuning via LoRA  
+Source: [LFM2.5-VL-450M model card](https://huggingface.co/LiquidAI/LFM2.5-VL-450M)
+
+### 15.2 What the model should do
+
+The model should **not** act as the primary methane detector. Instead, it should act as a grounded multimodal interpreter that:
+- reviews a focused evidence panel
+- localizes the most likely operationally relevant region
+- classifies source-zone type
+- summarizes evidence
+- recommends follow-up action
+
+### 15.3 Inputs to the model
+
+Each model call should include:
+1. current RGB crop
+2. methane-sensitive spectral composite crop
+3. temporal-difference crop
+4. Mapbox context crop
+5. short metadata text:
+   - site ID
+   - cloud cover
+   - time delta
+   - recurrence score
+   - candidate score
+
+### 15.4 Output format
+
+Always force JSON.
+
+Example prompt contract:
+
+```text
+You are an environmental operations assistant analyzing landfill imagery.
+Given the evidence panel and metadata, determine whether there is a likely methane-related incident worth operator inspection.
+
+Return valid JSON only with these fields:
+plume_likely: boolean
+confidence: float between 0 and 1
+bbox_norm: [x1, y1, x2, y2] normalized coordinates
+likely_source_zone: one of ["active_face", "cover_system", "perimeter", "gas_infrastructure", "unknown"]
+persistence_score: float between 0 and 1
+evidence_summary: short string under 40 words
+recommended_followup: short string under 20 words
+```
+
+### 15.5 Why bounding boxes matter
+
+Bounding boxes are the bridge between imagery and action. They allow:
+- explainable localization
+- visual overlay in the UI
+- compatibility with downstream segmentation or export tools
+- simple evaluation against labels
+
+---
+
+## 16. Fine-Tuning Strategy
+
+### 16.1 Why fine-tune
+
+Liquid explicitly recommends fine-tuning LFM2.5-VL-450M on specific use cases to maximize performance. The model card lists SFT notebooks for LoRA fine-tuning via Unsloth and TRL.  
+Source: [LFM2.5-VL-450M model card](https://huggingface.co/LiquidAI/LFM2.5-VL-450M)
+
+This is important because our task is narrow:
+- landfill methane triage
+- structured incident generation
+- bounded vocabulary of source zones
+- repeated evidence panel format
+
+That is exactly the kind of task where LoRA can help.
+
+### 16.2 Fine-tuning objective
+
+Train the model to map evidence panels to structured incident outputs.
+
+### 16.3 Recommended tuning method
+
+Use **LoRA supervised fine-tuning** with:
+- model: `LiquidAI/LFM2.5-VL-450M`
+- framework: Unsloth or TRL
+- training objective: next-token generation over JSON outputs
+- loss masking: output-focused
+- low learning rate
+- small batch with gradient accumulation
+
+### 16.4 Training data format
+
+Each example contains:
+- panel image
+- user prompt
+- assistant JSON answer
+
+### 16.5 Stage-wise tuning
+
+#### Phase 1: Synthetic and weakly labeled SFT
+Use:
+- Eucalyptus synthetic plumes
+- manually curated landfill-like scenes
+- heuristic or rule-assisted labels
+
+#### Phase 2: Human-corrected validation and tuning
+Curate a smaller, high-quality validation set where outputs are manually checked.
+
+#### Phase 3: Optional instruction refinement
+Refine for short, consistent evidence summaries and more stable source-zone outputs.
+
+### 16.6 Suggested LoRA settings
+
+These are starting points, not fixed truths:
+- rank: 16 or 32
+- alpha: 16 or 32
+- dropout: 0.05
+- epochs: 2 to 5
+- optimizer: AdamW or paged AdamW
+- precision: bf16 or fp16 depending hardware
+- sequence length: enough for image tokens + short JSON outputs
+
+### 16.7 What not to do
+
+- Do not overfit on tiny manually labeled examples alone.
+- Do not train on unconstrained natural-language outputs first.
+- Do not ask the model for long scientific narratives.
+- Do not mix too many tasks in one first pass.
+
+Keep the task narrow and consistent.
+
+---
+
+## 17. Dataset Strategy
+
+### 17.1 Dataset design goals
+
+We need a dataset that teaches the model to:
+- distinguish likely incident vs non-incident
+- localize the candidate zone
+- classify the likely source zone coarsely
+- produce concise evidence text
+- emit valid JSON consistently
+
+### 17.2 Dataset sources
+
+#### A. SimSat historical Sentinel-2 imagery
+Use for:
+- site windows
+- temporal comparisons
+- current vs history panel generation
+
+#### B. Project Eucalyptus synthetic plumes
+Use for:
+- supervised candidate learning
+- diverse plume geometry generation
+- hard negative creation
+Source: [Project Eucalyptus docs](https://orbio-earth.github.io/Project-Eucalyptus/)
+
+#### C. METER landfill locations
+Use for:
+- watchlist seed set
+- site diversification
+- data sampling across geography
+Source: [METER preprint](https://essd.copernicus.org/preprints/essd-2026-124/essd-2026-124.pdf)
+
+#### D. Manual labeling
+Use for:
+- high-quality eval set
+- prompt/output validation
+- operationally meaningful source-zone labels
+
+### 17.3 Label taxonomy
+
+#### Incident label
+- likely_incident
+- unlikely_incident
+
+#### Source zone label
+- active_face
+- cover_system
+- perimeter
+- gas_infrastructure
+- unknown
+
+#### Persistence label
+- transient
+- possible_persistent
+- persistent
+
+### 17.4 Negative examples are essential
+
+Train on hard negatives:
+- cloud artifacts
+- bright soil
+- seasonal changes
+- water-edge contrast
+- landfill-adjacent industrial structures
+- non-landfill methane-like anomalies outside facility zone
+
+### 17.5 Suggested dataset splits
+
+- train: 70%
+- validation: 15%
+- test: 15%
+
+But more importantly, split by **site**, not only by image. Otherwise leakage will make results look better than they are.
+
+---
+
+## 18. Prompting and Output Schemas
+
+### 18.1 Prompt design principles
+
+Prompt design should:
+- constrain output strongly
+- keep reasoning implicit
+- minimize verbosity
+- force structured fields
+- avoid asking the model to quantify emissions
+
+### 18.2 Core prompt template
+
+```text
+You are a landfill operations assistant.
+
+Analyze the evidence panel for a possible methane-related issue at a landfill.
+
+Use the visual evidence and metadata only.
+Do not invent facts.
+Return valid JSON only.
+
+Schema:
+{
+  "plume_likely": boolean,
+  "confidence": float,
+  "bbox_norm": [float, float, float, float],
+  "likely_source_zone": "active_face" | "cover_system" | "perimeter" | "gas_infrastructure" | "unknown",
+  "persistence_score": float,
+  "evidence_summary": string,
+  "recommended_followup": string
+}
+```
+
+### 18.3 Metadata text block
+
+```text
+Site metadata:
+site_type: landfill
+candidate_score: 0.71
+temporal_recurrence: 0.64
+cloud_cover_current: 9.2
+history_scenes_used: 4
+mapbox_context_available: true
+```
+
+### 18.4 Output validation
+
+Use Pydantic models to validate:
+- correct keys
+- numeric ranges
+- bbox ordering
+- enum membership
+- max summary length
+
+If validation fails:
+- retry once with a stricter system prompt
+- otherwise mark result as `needs_review`
+
+---
+
+## 19. Evaluation Plan
+
+### 19.1 Why evaluation matters
+
+The hackathon rewards fine-tuning when there is a documented methodology and measurable improvement over the base model. This means we need evaluation from the beginning.
+
+### 19.2 Primary evaluation metrics
+
+#### A. Incident classification
+- accuracy
+- precision
+- recall
+- F1
+
+#### B. Localization quality
+- IoU of predicted bbox vs label
+- center-point distance
+
+#### C. Source-zone classification
+- accuracy
+- macro F1
+
+#### D. Persistence scoring
+- MAE if numeric
+- ordinal accuracy if bucketed
+
+#### E. JSON reliability
+- valid JSON rate
+- schema compliance rate
+
+#### F. Operational usefulness
+Human review rubric on:
+- clarity
+- actionability
+- low hallucination
+- brevity
+
+### 19.3 Baselines
+
+Compare against:
+1. base LFM2.5-VL-450M with prompt only
+2. fine-tuned LFM2.5-VL-450M
+3. candidate-only heuristic pipeline without VLM interpretation
+
+### 19.4 Success thresholds for MVP
+
+Good hackathon MVP targets:
+- valid JSON rate > 95%
+- plume classification F1 > baseline by at least 5 to 10 points
+- bbox IoU meaningfully above prompt-only baseline
+- short evidence summaries judged useful in manual review
+
+### 19.5 Evaluation table template
+
+| Metric | Heuristic Only | Base LFM2.5-VL | Fine-Tuned LFM2.5-VL |
+|---|---:|---:|---:|
+| Incident F1 | 0.58 | 0.66 | 0.75 |
+| Source-Zone Accuracy | 0.41 | 0.52 | 0.68 |
+| BBox IoU | 0.33 | 0.44 | 0.59 |
+| Valid JSON Rate | 1.00 | 0.88 | 0.97 |
+| Human Actionability Score | 2.6/5 | 3.5/5 | 4.4/5 |
+
+Populate this honestly when you run experiments.
+
+---
+
+## 20. Product UX and Demo Flow
+
+### 20.1 Core UI screens
+
+#### Screen 1: Watchlist
+List of landfill sites with:
+- last scan time
+- incident count
+- highest priority alert
+- persistence flag
+
+#### Screen 2: Site detail
+Show:
+- current Sentinel image
+- historical comparison panel
+- Mapbox site view
+- alert overlays
+- incident cards
+
+#### Screen 3: Evidence pack
+Show:
+- alert summary
+- bbox overlay
+- likely source zone
+- recommended follow-up
+- export JSON
+
+### 20.2 Demo script
+
+1. Open watchlist.
+2. Select a site with a flagged incident.
+3. Show current vs historical imagery.
+4. Explain candidate generation briefly.
+5. Run Liquid model inference live or replay cached result.
+6. Display structured incident object.
+7. Show bbox on Mapbox and explain likely source zone.
+8. End with operator value:
+   “This tells the landfill team where to inspect first.”
+
+### 20.3 What to avoid in the demo
+
+- too many scientific details before value is shown
+- unclear jargon around methane retrieval physics
+- long free-text model outputs
+- unstable inference calls during live judging
+- overclaiming quantification accuracy
+
+---
+
+## 21. Backend API Specification
+
+This section specifies the APIs for the LandfillSentry backend.
+
+### 21.1 API style
+
+- REST for MVP
+- JSON responses
+- async jobs for longer scans
+- predictable schema
+
+### 21.2 Core endpoints
+
+#### A. Health
+
+`GET /health`
+
+Response:
+```json
+{
+  "status": "ok",
+  "service": "landfillsentry-api",
+  "model_loaded": true
+}
+```
+
+#### B. Register site
+
+`POST /sites`
+
+Request:
+```json
+{
+  "site_id": "LF_IND_001",
+  "name": "Demo Landfill A",
+  "lat": 16.306,
+  "lon": 80.436,
+  "country": "IN",
+  "metadata": {
+    "operator": "Demo Operator",
+    "notes": "Hackathon demo site"
+  }
+}
+```
+
+#### C. List sites
+
+`GET /sites`
+
+#### D. Scan site
+
+`POST /scan-site`
+
+Request:
+```json
+{
+  "site_id": "LF_IND_001",
+  "timestamp": "2026-04-19T10:00:00Z",
+  "history_days": 30,
+  "size_km": 5.0,
+  "spectral_bands": ["red", "green", "blue"],
+  "include_mapbox": true
+}
+```
+
+Response:
+```json
+{
+  "job_id": "job_123",
+  "status": "queued"
+}
+```
+
+#### E. Get scan result
+
+`GET /scan-result/{job_id}`
+
+Response:
+```json
+{
+  "job_id": "job_123",
+  "status": "completed",
+  "site_id": "LF_IND_001",
+  "incident": {
+    "plume_likely": true,
+    "confidence": 0.84,
+    "bbox_norm": [0.32, 0.18, 0.56, 0.43],
+    "likely_source_zone": "active_face",
+    "persistence_score": 0.72,
+    "evidence_summary": "A recurring anomaly appears near the active working area.",
+    "recommended_followup": "Inspect active face and nearby gas capture."
+  }
+}
+```
+
+#### F. Fetch evidence pack
+
+`GET /evidence-pack/{job_id}`
+
+Returns:
+- JSON
+- optional image overlays
+- markdown summary
+
+#### G. Watchlist scan
+
+`POST /watchlists/{id}/scan`
+
+Request:
+```json
+{
+  "timestamp": "2026-04-19T10:00:00Z"
+}
+```
+
+#### H. Export incidents
+
+`GET /incidents/export?format=json`
+
+### 21.3 Internal adapters for SimSat
+
+#### Sentinel current
+`GET {SIMSAT_BASE}/data/current/image/sentinel`
+
+#### Sentinel historical
+`GET {SIMSAT_BASE}/data/image/sentinel`
+
+Parameters:
+- lon
+- lat
+- timestamp
+- spectral_bands
+- size_km
+- return_type
+- window_seconds
+
+#### Mapbox current
+`GET {SIMSAT_BASE}/data/current/image/mapbox`
+
+#### Mapbox historical-style by satellite geometry
+`GET {SIMSAT_BASE}/data/image/mapbox`
+
+### 21.4 Backend job flow
+
+For scans longer than a few seconds:
+- store job in queue
+- mark `queued`
+- process async
+- allow polling or websocket updates
+
+For hackathon MVP:
+- Celery optional
+- RQ optional
+- plain `BackgroundTasks` in FastAPI often enough
+
+---
+
+## 22. Data Models
+
+### 22.1 Site
+
+```json
+{
+  "site_id": "LF_IND_001",
+  "name": "Demo Landfill A",
+  "lat": 16.306,
+  "lon": 80.436,
+  "country": "IN",
+  "operator": "Demo Operator",
+  "metadata": {}
+}
+```
+
+### 22.2 Image Asset
+
+```json
+{
+  "asset_id": "img_001",
+  "site_id": "LF_IND_001",
+  "source": "sentinel",
+  "timestamp_requested": "2026-04-19T10:00:00Z",
+  "timestamp_captured": "2026-04-14T05:32:00Z",
+  "cloud_cover": 9.2,
+  "bands": ["red", "green", "blue"],
+  "size_km": 5.0,
+  "local_path": "cache/sentinel/LF_IND_001_20260419_rgb.png"
+}
+```
+
+### 22.3 Candidate
+
+```json
+{
+  "candidate_id": "cand_001",
+  "site_id": "LF_IND_001",
+  "job_id": "job_123",
+  "bbox_norm": [0.25, 0.15, 0.47, 0.32],
+  "candidate_score": 0.71,
+  "temporal_recurrence": 0.64,
+  "cloud_penalty": 0.12
+}
+```
+
+### 22.4 Incident
+
+```json
+{
+  "incident_id": "inc_001",
+  "site_id": "LF_IND_001",
+  "job_id": "job_123",
+  "plume_likely": true,
+  "confidence": 0.84,
+  "bbox_norm": [0.32, 0.18, 0.56, 0.43],
+  "likely_source_zone": "active_face",
+  "persistence_score": 0.72,
+  "evidence_summary": "A recurring anomaly appears near the active working area.",
+  "recommended_followup": "Inspect active face and nearby gas capture.",
+  "model_version": "lfm25vl450m-landfillsentry-lora-v1"
+}
+```
+
+### 22.5 Evaluation Record
+
+```json
+{
+  "eval_id": "eval_001",
+  "split": "validation",
+  "site_id": "LF_IND_001",
+  "baseline_model": "lfm25vl450m-base",
+  "candidate_model": "lfm25vl450m-landfillsentry-lora-v1",
+  "incident_f1": 0.75,
+  "zone_accuracy": 0.68,
+  "bbox_iou": 0.59,
+  "json_valid_rate": 0.97
+}
+```
+
+---
+
+## 23. Deployment and Infrastructure
+
+### 23.1 MVP deployment shape
+
+Use three runtime components:
+
+1. **SimSat**
+2. **LandfillSentry backend**
+3. **Frontend UI**
+
+Optional fourth:
+4. **Model-serving container**
+
+### 23.2 Recommended local setup
+
+```mermaid
+flowchart LR
+    A[Docker Compose] --> B[SimSat Dashboard]
+    A --> C[SimSat API]
+    A --> D[Backend API]
+    A --> E[Frontend]
+    A --> F[Postgres/SQLite]
+```
+
+### 23.3 Hosted setup
+
+For hackathon demo you can host:
+- frontend on Vercel or Netlify
+- backend on Railway, Render, Fly.io, or a GPU-backed VM
+- training on Modal
+- inference on a dedicated GPU instance or local GPU
+
+### 23.4 Inference options
+
+#### Option A: Transformers native
+Best for:
+- ease of implementation
+- direct control
+- hackathon reproducibility
+
+#### Option B: vLLM
+Best for:
+- higher throughput
+- production-style GPU serving
+
+#### Option C: ONNX Runtime
+Best for:
+- edge or CPU experimentation
+- portability
+
+#### Option D: llama.cpp with GGUF
+Best for:
+- CPU-only fallback demos
+- smaller local footprints
+
+### 23.5 Recommended inference path for MVP
+
+Use **Transformers** for first implementation. Add ONNX or GGUF only if needed later.
+
+---
+
+## 24. GPU and Training Plan
+
+### 24.1 Training target
+
+Train one useful, stable LoRA adapter rather than many weak experiments.
+
+### 24.2 Why Modal is a good option
+
+Modal provides GPU-backed Python workflows and has public examples for Unsloth-based fine-tuning. This is a practical way to run LoRA jobs without building heavy infrastructure.  
+Source: [Modal Unsloth example](https://modal.com/docs/examples/unsloth_finetune)
+
+### 24.3 Suggested training workflow
+
+1. Prepare panel images and JSON labels.
+2. Store dataset as local files or object storage.
+3. Create a training script using Transformers + PEFT + Unsloth.
+4. Launch on Modal or another GPU provider.
+5. Save adapter weights.
+6. Merge or load adapter at inference time.
+7. Benchmark against base model.
+
+### 24.4 Hardware guidance
+
+For hackathon scope:
+- one mid-range GPU is likely enough for LoRA fine-tuning of 450M model
+- inference can run on a single consumer GPU or a CPU-friendly quantized deployment depending speed requirements
+
+### 24.5 Training artifacts to save
+
+- adapter weights
+- config file
+- training script
+- dataset manifest
+- eval results
+- sample outputs
+
+These are important for judging because documented methodology is rewarded.
+
+---
+
+## 25. Implementation Roadmap
+
+### 25.1 MVP milestone sequence
+
+#### Milestone 1: Base system skeleton
+- set up SimSat locally
+- create backend skeleton
+- add site registry
+- fetch imagery successfully
+
+#### Milestone 2: Preprocessing
+- cache images
+- compute temporal history
+- add cloud filtering
+- create panel builder
+
+#### Milestone 3: Candidate generation
+- implement heuristic anomaly stage
+- integrate Eucalyptus if possible
+- output candidate bbox
+
+#### Milestone 4: Base model inference
+- run LFM2.5-VL-450M with prompt only
+- force JSON schema
+- visualize results
+
+#### Milestone 5: Fine-tuning
+- prepare narrow SFT dataset
+- train LoRA
+- compare with base
+
+#### Milestone 6: UI and demo polish
+- operator dashboard
+- overlays
+- evidence pack export
+- rehearsed demo
+
+### 25.2 Compressed hackathon sprint plan
+
+#### Day 1
+- SimSat setup
+- imagery fetch working
+- choose 3 to 5 demo sites
+- define schemas
+
+#### Day 2
+- historical retrieval
+- panel builder
+- basic UI
+- candidate heuristics
+
+#### Day 3
+- VLM prompt-only pipeline
+- end-to-end first demo
+
+#### Day 4
+- dataset prep
+- synthetic examples
+- LoRA fine-tuning
+
+#### Day 5
+- evaluation
+- error fixing
+- better overlays
+
+#### Day 6
+- demo script
+- evidence export
+- architecture diagrams
+
+#### Day 7
+- stabilization
+- dry runs
+- submission assets
+
+---
+
+## 26. Repository Structure
+
+A clean repo structure will save time.
+
+```text
+landfillsentry-ops/
+├─ README.md
+├─ docs/
+│  ├─ architecture.md
+│  ├─ demo-script.md
+│  └─ evaluation.md
+├─ apps/
+│  ├─ api/
+│  │  ├─ main.py
+│  │  ├─ routes/
+│  │  ├─ schemas/
+│  │  ├─ services/
+│  │  └─ db/
+│  └─ web/
+│     ├─ src/
+│     └─ public/
+├─ ml/
+│  ├─ candidate_generation/
+│  ├─ panel_builder/
+│  ├─ vlm/
+│  ├─ training/
+│  └─ evaluation/
+├─ data/
+│  ├─ raw/
+│  ├─ processed/
+│  ├─ cache/
+│  ├─ labels/
+│  └─ manifests/
+├─ notebooks/
+│  ├─ simsat_fetch.ipynb
+│  ├─ candidate_debug.ipynb
+│  ├─ panel_examples.ipynb
+│  └─ eval_dashboard.ipynb
+├─ scripts/
+│  ├─ fetch_site_history.py
+│  ├─ build_panels.py
+│  ├─ run_inference.py
+│  ├─ train_lora.py
+│  └─ benchmark_models.py
+├─ infra/
+│  ├─ docker/
+│  ├─ compose/
+│  └─ modal/
+├─ tests/
+│  ├─ test_api.py
+│  ├─ test_panel_builder.py
+│  ├─ test_schema_validation.py
+│  └─ test_inference_smoke.py
+└─ assets/
+   ├─ demo_sites/
+   ├─ screenshots/
+   └─ diagrams/
+```
+
+---
+
+## 27. Engineering Work Breakdown
+
+### 27.1 Backend engineer
+- FastAPI routes
+- job orchestration
+- site registry
+- result storage
+- schema validation
+
+### 27.2 ML engineer
+- candidate generation
+- panel builder
+- inference logic
+- LoRA fine-tuning
+- evaluation
+
+### 27.3 Frontend engineer
+- watchlist view
+- site detail panel
+- bbox overlay
+- evidence card
+- demo polish
+
+### 27.4 Product/demo owner
+- narrative
+- site selection
+- benchmarks
+- submission materials
+- final walkthrough
+
+### 27.5 If only one or two people
+Priority order:
+1. end-to-end scan pipeline
+2. structured JSON output
+3. UI overlay
+4. fine-tuning
+5. evaluation polish
+6. stretch features
+
+---
+
+## 28. Risks and Mitigations
+
+### 28.1 Risk: Sentinel image not available
+Cause:
+- ocean or unsuitable location
+- no image in time window
+
+Mitigation:
+- use historical endpoint with wider window
+- maintain backup demo sites
+- pre-cache assets
+
+### 28.2 Risk: Cloud cover too high
+Mitigation:
+- filter scenes by cloud cover
+- use last acceptable scene
+- show cloud penalty in UI
+- preselect demo cases
+
+### 28.3 Risk: Candidate engine too noisy
+Mitigation:
+- increase threshold
+- restrict to facility polygon
+- use recurrence score
+- add Mapbox-informed spatial prior
+
+### 28.4 Risk: VLM output invalid JSON
+Mitigation:
+- use strong schema prompts
+- add parser-retry loop
+- validate with Pydantic
+- clamp fallback outputs
+
+### 28.5 Risk: Fine-tuning does not help enough
+Mitigation:
+- narrow the task further
+- reduce output diversity
+- improve label quality
+- train on fewer but cleaner examples
+- compare structured tasks, not open-ended text
+
+### 28.6 Risk: Overclaiming science
+Mitigation:
+- describe product as triage and prioritization
+- avoid emission-rate claims unless validated
+- clearly separate candidate signal from final field confirmation
+
+### 28.7 Risk: Demo instability
+Mitigation:
+- cache results
+- precompute panels
+- host a known-good inference path
+- have static fallback screenshots and exported JSON
+
+---
+
+## 29. Stretch Features
+
+These are optional and should not distract from the MVP.
+
+### 29.1 WorkFace Radar
+A sub-view specifically focused on active-face localization, inspired by emerging findings that open or active landfill surfaces are often major methane source regions.  
+Source: [Carbon Mapper work-face article](https://carbonmapper.org/articles/landfill-work-face-emissions)
+
+### 29.2 Operator prioritization queue
+Rank alerts across sites by:
+- confidence
+- persistence
+- recurrence
+- proximity to active zones
+
+### 29.3 Evidence-pack PDF or markdown export
+Generate an operator-ready report:
+- image panels
+- bbox overlay
+- summary
+- recommended action
+
+### 29.4 Natural-language chat over incidents
+Allow user to ask:
+- “Why was this flagged?”
+- “Show the last 3 similar incidents.”
+- “Which sites have persistent alerts?”
+
+### 29.5 Segmentation assist
+Use SamGeo or similar tools for better facility-zone mapping and overlay visuals.
+
+---
+
+## 30. Submission Strategy
+
+### 30.1 What judges need to see
+
+Judges do not just need “a smart model.” They need:
+- clear problem
+- strong fit to SimSat
+- obvious fit to Liquid
+- a working app
+- measurable fine-tuning story
+
+### 30.2 Submission assets checklist
+
+#### Required
+- running application
+- code repository
+- demo video
+- architecture explanation
+- fine-tuning notes
+- reproducible instructions
+
+#### Recommended
+- benchmark table
+- example alert exports
+- before-vs-after fine-tuning outputs
+- clean UI screenshots
+- short one-page summary
+
+### 30.3 Best demo narrative
+
+Use this storyline:
+
+1. Landfill methane is large and under-addressed.
+2. Operators need triage, not just raw imagery.
+3. SimSat gives us Sentinel-2 + Mapbox.
+4. We generate methane-risk candidates.
+5. We fine-tune Liquid’s LFM2.5-VL to convert evidence into a structured incident object.
+6. The result tells the operator where to inspect first.
+
+### 30.4 Best claims to make
+
+Strong, defensible claims:
+- “We use DPhi imagery as the core input.”
+- “We fine-tuned Liquid’s VLM on a narrow satellite triage task.”
+- “Our output is a grounded incident object.”
+- “The system is designed for operator actionability.”
+
+Claims to avoid:
+- “We accurately quantify methane mass flow for regulatory use.”
+- “We replace field inspection.”
+- “We are a full MRV platform.”
+
+---
+
+## 31. Final Build Recommendation
+
+### 31.1 The version to build
+
+**Build the operator-first version.**
+
+Do not build:
+- a generic emissions portal
+- a policy dashboard
+- an insurer analytics portal
+- a research-only methane notebook
+
+Those are weaker first demos.
+
+### 31.2 The best MVP definition
+
+A successful MVP for this hackathon does the following:
+
+1. user selects a landfill
+2. system retrieves historical and current imagery from SimSat
+3. candidate stage proposes a suspicious region
+4. evidence panel is constructed
+5. fine-tuned LFM2.5-VL-450M returns valid JSON
+6. UI shows the bbox, likely zone, summary, and recommended action
+7. export function produces a clean evidence pack
+
+If you achieve those seven things cleanly, the product will already feel much stronger than many hackathon entries.
+
+### 31.3 What to freeze early
+
+Freeze these early:
+- JSON schema
+- prompt contract
+- evidence panel format
+- site list for demo
+- evaluation metrics
+- UI layout
+
+Do not keep changing the output task once training starts.
+
+### 31.4 Final recommendation in one paragraph
+
+The best path is to build **LandfillSentry Ops** as a narrow, operator-facing methane incident API with a simple UI. Use SimSat Sentinel-2 imagery for temporal and multispectral evidence, Mapbox for facility context, a hybrid candidate-generation stage for likely methane event proposals, and a fine-tuned LFM2.5-VL-450M model for grounded, structured incident generation. Keep the task framed as triage and prioritization, demonstrate measurable gains over the base model, and show a crisp end-to-end operator workflow. That is the version most likely to score well across all major judging dimensions.
+
+---
+
+## 32. References
+
+1. DPhi Space. **SimSat GitHub repository**.  
+   https://github.com/DPhi-Space/SimSat
+
+2. Liquid AI. **LFM2.5-VL-450M model card**.  
+   https://huggingface.co/LiquidAI/LFM2.5-VL-450M
+
+3. Liquid AI. **LFM2.5-VL-450M blog post**.  
+   https://www.liquid.ai/blog/lfm2-5-vl-450m
+
+4. Orbio Earth. **Project Eucalyptus GitHub**.  
+   https://github.com/Orbio-Earth/Project-Eucalyptus
+
+5. Orbio Earth. **Project Eucalyptus documentation**.  
+   https://orbio-earth.github.io/Project-Eucalyptus/
+
+6. Jackson et al. **MEthane Tracking Emissions Reference (METER): A global database of methane-emitting infrastructure**.  
+   https://essd.copernicus.org/preprints/essd-2026-124/essd-2026-124.pdf
+
+7. ESA Space Solutions. **Landfill Methane Monitor (LMM)**.  
+   https://business.esa.int/projects/landfill-methane-monitor-lmm
+
+8. Clean Air Task Force. **Three trends shaping waste sector methane mitigation in 2026**.  
+   https://www.catf.us/2026/03/three-trends-shaping-waste-sector-methane-mitigation-2026/
+
+9. Carbon Mapper. **Landfill work face emissions present major methane mitigation opportunities**.  
+   https://carbonmapper.org/articles/landfill-work-face-emissions
+
+10. Carbon Mapper. **Main site / data and impact framing**.  
+    https://carbonmapper.org/
+
+11. WasteMAP. **Waste methane assessment platform**.  
+    https://wastemap.earth/
+
+12. RMI. **Introducing WasteMAP**.  
+    https://rmi.org/introducing-wastemap-a-new-tool-to-track-and-reduce-waste-methane-emissions/
+
+13. UNEP. **Methane Alert and Response System (MARS)**.  
+    https://www.unep.org/topics/energy/methane/methane-alert-and-response-system-mars
+
+14. UNEP. **How MARS works**.  
+    https://www.unep.org/topics/energy/methane/how-mars-works
+
+15. TorchGeo. **Official site**.  
+    https://torchgeo.org/
+
+16. TorchGeo Docs. **Official documentation**.  
+    https://torchgeo.readthedocs.io/
+
+17. TerraTorch. **GitHub repository**.  
+    https://github.com/terrastackai/terratorch
+
+18. IBM Research. **Simplifying geospatial AI with TerraTorch 1.0**.  
+    https://research.ibm.com/blog/simplifying-geospatial-ai-with-terra-torch-1-0
+
+19. SamGeo. **Documentation**.  
+    https://samgeo.gishub.org/
+
+20. Modal. **Unsloth fine-tuning example**.  
+    https://modal.com/docs/examples/unsloth_finetune
+
+21. Copernicus Sentinel Success Story. **Sentinel-2 data help monitor methane point source emissions**.  
+    https://sentinels.copernicus.eu/web/success-stories/-/copernicus-sentinel-2-data-help-monitor-methane-point-source-emissions
+
+22. Copernicus Sentinel Success Story. **Sentinel-2 helps in methane monitoring**.  
+    https://sentinels.copernicus.eu/web/success-stories/-/copernicus-sentinel-2-helps-in-methane-monitoring
+
+23. Nature. **Global satellite survey reveals uncertainty in landfill methane emissions and waste-site area**.  
+    https://www.nature.com/articles/s41586-025-09683-8
+
+24. USGS. **Sentinel-2 chlorophyll-a water quality monitoring review**.  
+    https://www.usgs.gov/publications/sentinel-2-chlorophyll-a-water-quality-monitoring-a-review-validation-evidence-and
+
+25. NASA Earthdata. **Global Automated Bloom Analysis Network (GABAN)**.  
+    https://www.earthdata.nasa.gov/data/projects/nsite/solutions/gaban
+
+---
+
+## Appendix A: Environment Variables
+
+```bash
+SIMSAT_API_BASE=http://localhost:9005
+SIMSAT_DASHBOARD_BASE=http://localhost:8000
+MAPBOX_ACCESS_TOKEN=your_token_here
+HF_MODEL_ID=LiquidAI/LFM2.5-VL-450M
+HF_TOKEN=your_hf_token
+DATABASE_URL=sqlite:///./landfillsentry.db
+CACHE_DIR=./data/cache
+MODEL_DEVICE=cuda
+USE_EUCALYPTUS=true
+```
+
+---
+
+## Appendix B: Minimal Python Pydantic Schema
+
+```python
+from typing import Literal, List
+from pydantic import BaseModel, Field
+
+class IncidentOutput(BaseModel):
+    plume_likely: bool
+    confidence: float = Field(ge=0.0, le=1.0)
+    bbox_norm: List[float] = Field(min_length=4, max_length=4)
+    likely_source_zone: Literal[
+        "active_face",
+        "cover_system",
+        "perimeter",
+        "gas_infrastructure",
+        "unknown"
+    ]
+    persistence_score: float = Field(ge=0.0, le=1.0)
+    evidence_summary: str
+    recommended_followup: str
+```
+
+---
+
+## Appendix C: Example Inference Pseudocode
+
+```python
+def analyze_site(site_id: str, timestamp: str):
+    current = fetch_current_sentinel(site_id, timestamp)
+    history = fetch_history_sentinel(site_id, timestamp, days=30)
+    mapbox = fetch_mapbox_context(site_id, timestamp)
+
+    clean_history = filter_cloudy_scenes(history)
+    candidate = generate_candidate(current, clean_history)
+
+    panel = build_evidence_panel(
+        current=current,
+        history=clean_history,
+        mapbox=mapbox,
+        candidate=candidate
+    )
+
+    prompt = build_prompt(candidate)
+    raw_output = run_lfm25vl(panel, prompt)
+    incident = validate_and_normalize(raw_output)
+
+    save_incident(site_id, incident, panel)
+    return incident
+```
+
+---
+
+## Appendix D: First-Week Acceptance Criteria
+
+By the end of the first full build week, the project should satisfy:
+
+- SimSat running locally
+- imagery retrieval working for at least 3 demo landfill sites
+- evidence panels generated automatically
+- one candidate generation path implemented
+- LFM2.5-VL base model producing valid JSON
+- UI showing current image, bbox, and summary
+- one end-to-end demo path recorded successfully
+
+---
+
+## Appendix E: Optional Future Research Directions
+
+After the hackathon, future extensions may include:
+- better plume physics integration
+- wind-aware incident ranking
+- coupling with onsite sensor logs
+- quantification confidence intervals
+- active learning loops for operator feedback
+- multi-site global prioritization
+
+These are future opportunities, not MVP requirements.
+
+---

project_docs/LandfillSentry_Ops_Master_Project_Plan.md

@@ -0,0 +1,1959 @@
+# LandfillSentry Ops Master Project Plan
+
+> Canonical execution document for building LandfillSentry Ops as a hackathon-winning MVP with a credible path to a startup-grade product.
+>
+> Planning basis:
+> - Product and architecture source: `LandfillSentry_Ops_Detailed_Report.md`
+> - Frozen defaults and scope decisions: `LandfillSentry_Ops_Answers_to_Open_Questions.md`
+> - Planning structure reference: `UNIVERSAL_LLM_PROJECT_PLAN_TEMPLATE.md`
+
+### Operating Mode
+
+Use this document as a 2-layer system:
+
+1. Master Plan: strategy, constraints, architecture, phases, testing rules, and acceptance logic.
+2. Execution Cards: small, timeboxed tasks used during implementation.
+
+Rules:
+- Keep this file as the single source of truth.
+- No phase is complete until it passes its integration checkpoint.
+- Every major capability must support both a live path and a cached offline path.
+- Every two phases must end with one full end-to-end scan.
+- Prefer one stable implementation path over multiple half-working alternatives.
+
+### Lean Usage Mode for This Project
+
+Because LandfillSentry is both product-heavy and system-heavy, the following sections are mandatory for this plan:
+
+- `0, 1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 18, 19`
+
+The following sections are included because they materially reduce execution risk:
+
+- `13, 14, 15`
+
+---
+
+## 0) Project Identity
+
+- **Project Name:** `LandfillSentry Ops`
+- **Status:** `in progress`
+- **Version:** `Master Plan v1.0 - Full Draft`
+- **Primary Mode:** `Hackathon MVP first, product-grade foundation second`
+- **Core Product Identity:** `Operator-first landfill methane incident triage copilot`
+- **One-line Memory Hook:** `LandfillSentry turns satellite imagery into an explainable methane incident object that tells operators where to inspect first.`
+
+### 0.1 Strategic Positioning
+
+LandfillSentry Ops is not a generic remote sensing dashboard, and it is not a regulatory methane quantification system.
+
+It is:
+- a triage and prioritization product,
+- built around landfill operations,
+- using satellite imagery as the core evidence source,
+- with a structured incident object as the product output,
+- and a human review step before incidents become official.
+
+### 0.2 Product Thesis
+
+Existing methane monitoring ecosystems increasingly provide detections, maps, and broad emissions context. Landfill operators still lack a lightweight operational workflow that converts mixed satellite evidence into a facility-specific, explainable, inspectable incident recommendation.
+
+LandfillSentry exists to close that gap.
+
+---
+
+## 1) Goal
+
+### Primary Goal
+
+Build a hackathon-winning MVP that scans a watchlist of landfill sites using SimSat imagery, generates methane-risk candidates, converts compact evidence panels into structured incident objects using Liquid's `LFM2.5-VL-450M`, and shows operators which zone to inspect first.
+
+### Secondary Goals
+
+- Demonstrate a credible fine-tuning story rather than a prompt-only demo.
+- Prove operator usefulness through structured outputs, explainable evidence, and a clear action recommendation.
+- Build the architecture so it can realistically evolve into a startup-grade product after the hackathon.
+- Produce a polished demo that is robust to live failures through cached assets and offline-safe flows.
+
+### 1.1 Definition of MVP Success
+
+The MVP succeeds if it can do the following reliably for a small frozen demo set:
+
+1. retrieve current and historical imagery for a selected site,
+2. generate a plausible methane-risk candidate region,
+3. build an evidence panel for model interpretation,
+4. return valid structured incident JSON,
+5. display the incident clearly in a watchlist-first UI,
+6. allow human review before publication,
+7. export a clean evidence summary,
+8. and survive demo conditions using both live and cached execution paths.
+
+---
+
+## 2) Context & Problem Statement
+
+### Current State
+
+The waste sector is a large methane source, and landfill emissions are increasingly visible through remote sensing and public methane initiatives. Yet most available systems are designed for mapping, scientific interpretation, portfolio-level visibility, or policy action rather than day-to-day operational triage by landfill teams.
+
+Existing tools can tell users that methane matters or that a site may be emitting. They often do not compress that evidence into a site-specific operational question:
+
+`Where should my team inspect first, and why?`
+
+### Problem
+
+Landfill operators face three linked problems:
+
+1. methane evidence arrives as raw or semi-processed imagery rather than operational guidance,
+2. interpreting site structure, source zone, and urgency requires manual reasoning,
+3. false positives or ambiguous alerts quickly destroy trust if outputs are not explainable and reviewable.
+
+### Why It Matters Now
+
+- Waste methane is gaining more policy and operational attention globally.
+- Remote sensing is increasingly being used to guide waste-sector methane action.
+- Landfill work-face and facility-zone attribution are becoming more important for mitigation prioritization.
+- The hackathon stack creates an unusually strong fit: `SimSat` for imagery, `Liquid` for compact grounded multimodal reasoning, and open methane tooling such as Project Eucalyptus for domain bootstrapping.
+
+### Who Is Impacted
+
+- Primary: landfill operations managers and site operations leads
+- Secondary: environmental compliance leads, consultants, municipalities, insurers, and climate program teams
+
+### 2.1 Product Value Statement
+
+LandfillSentry reduces operator cognitive load by turning imagery, temporal comparison, and contextual metadata into a compact incident object that can be reviewed, prioritized, and acted on quickly.
+
+### 2.2 Explicit Non-Claims
+
+LandfillSentry does not claim to provide:
+
+- regulatory-grade methane quantification,
+- legal attribution of emissions,
+- continuous coverage,
+- full atmospheric inversion,
+- or autonomous final decision authority.
+
+It is a triage copilot, not a final truth engine.
+
+---
+
+## 3) Constraints & Boundaries
+
+### Tech Stack Constraints
+
+- **Imagery sources for MVP:** `SimSat` and `Mapbox` are both required imagery/context inputs.
+- **Backend:** `FastAPI`
+- **Frontend:** `React`
+- **Storage:** `SQLite` first
+- **Primary inference path:** `Transformers`
+- **Primary model:** `LiquidAI/LFM2.5-VL-450M`
+- **Model registry and artifact source:** `Hugging Face` is required for model and adapter distribution.
+- **Training method:** `LoRA` or similarly lightweight adapter tuning
+- **Training infrastructure:** `Modal GPU` is required for training runs.
+- **Execution model:** synchronous inference for MVP with caching
+
+### Performance Constraints
+
+- Demo flows must feel responsive enough for judge interaction.
+- Live scan latency can be several seconds if clearly signaled, but cached demo paths should be near-instant.
+- JSON validation and rendering must remain deterministic even if model latency varies.
+
+### Security / Privacy / Licensing Constraints
+
+- API tokens must never be hardcoded.
+- SimSat, Mapbox, Hugging Face, and Modal credentials must be environment-driven.
+- Model and dataset licenses must be reviewed and documented.
+- Real sites may be used, but wording must avoid unvalidated legal or regulatory claims.
+- Synthetic, weak, and manual labels must remain provenance-tracked.
+
+### Data Constraints
+
+- Manual labeled data is limited to approximately `80-200` usable examples.
+- One primary labeler is assumed.
+- Negative examples are first-class and must be budgeted intentionally.
+- Validation and demo splits must be frozen early.
+
+### Hackathon Constraints
+
+- The system must run reliably under demo conditions.
+- Fine-tuning is highly desirable, but the product needs a fallback path if the fine-tuned model underperforms.
+- Architecture must support storytelling and judging clarity, not just technical completeness.
+
+### Non-Goals
+
+- Full compliance workflow
+- Multi-tenant enterprise administration
+- Full atmospheric modeling
+- Advanced job orchestration infrastructure
+- Complete automated active learning loop
+- Production-scale global monitoring
+- A generalized methane platform spanning all facility classes in MVP
+
+### 3.1 Boundary Rule
+
+If a feature does not directly improve one of the following, it is not MVP-critical:
+
+- operator usefulness,
+- valid incident generation,
+- demo stability,
+- fine-tuning credibility,
+- or evaluation clarity.
+
+---
+
+## 4) Success Metrics (Measurable)
+
+Directional metrics are preferred over overconfident hard claims at this stage. Final thresholds can be refined after the first end-to-end evaluation pass.
+
+- [ ] **Metric 1: End-to-end Incident Reliability** - baseline: `not yet measured`, target: `stable valid JSON on >95% of frozen validation examples`, measurement: `schema validation pass rate across validation and golden fixtures`
+- [ ] **Metric 2: Operator Usefulness** - baseline: `not yet measured`, target: `majority of reviewed incidents rated actionable by human rubric`, measurement: `manual scoring rubric on usefulness and explainability`
+- [ ] **Metric 3: Null-Scene Trustworthiness** - baseline: `not yet measured`, target: `false positive rate below agreed threshold on negative split`, measurement: `negative-scene evaluation report`
+- [ ] **Metric 4: Zone Guidance Quality** - baseline: `not yet measured`, target: `meaningful improvement over prompt-only baseline`, measurement: `source-zone accuracy / coarse zone agreement`
+- [ ] **Metric 5: Demo Stability** - baseline: `not yet measured`, target: `100% success on frozen demo path`, measurement: `rehearsed runs on cached demo fixtures`
+- [ ] **Metric 6: Model Improvement Story** - baseline: `base prompt-only model`, target: `fine-tuned model outperforms base on structured output reliability and human usefulness`, measurement: `baseline comparison table`
+
+### 4.1 Prioritized Metric Hierarchy
+
+Metrics are not equally important. The project should optimize in this order:
+
+1. operator usefulness,
+2. JSON validity,
+3. null-scene trustworthiness,
+4. source-zone accuracy,
+5. bbox quality,
+6. persistence scoring quality.
+
+### 4.2 MVP Success Threshold Narrative
+
+The MVP is considered strong if it can show:
+
+- a believable operational workflow,
+- high structured-output reliability,
+- low embarrassing false positives on golden negatives,
+- an understandable action recommendation,
+- and a measurable improvement path from heuristics and base-model prompting to fine-tuned performance.
+
+---
+
+## 5) Architecture Snapshot
+
+### 5.1 System Components
+
+- **API Gateway / Orchestrator**
+  - receives site scan requests,
+  - coordinates imagery retrieval, candidate generation, panel building, inference, validation, and persistence.
+
+- **Site Registry**
+  - stores demo sites, watchlist metadata, coordinates, optional polygons, and status metadata.
+
+- **Imagery Retrieval Service**
+  - fetches current and historical imagery from `SimSat`,
+  - retrieves required Mapbox context,
+  - caches responses and normalized assets.
+
+- **Preprocessing & Quality Control**
+  - handles cloud filtering, band selection, temporal selection, normalization, and failure handling when imagery is weak or absent.
+
+- **Candidate Generation Engine**
+  - produces one or more suspicious methane-risk candidate regions using hybrid logic:
+    - spectral heuristics,
+    - temporal differencing,
+    - optional ranking/refinement informed by methane-domain assets.
+
+- **Evidence Panel Builder**
+  - combines current crop, methane-sensitive spectral composite, temporal comparison crop, required Mapbox context, and compact metadata into a stable multimodal input.
+
+- **VLM Inference Service**
+  - runs `LFM2.5-VL-450M`,
+  - initially in prompt-only mode,
+  - then with a fine-tuned adapter path.
+
+- **Incident Object Generator**
+  - validates and normalizes model output,
+  - computes priority and severity tiers,
+  - assigns review state,
+  - and stores structured records.
+
+- **Results Store**
+  - persists sites, assets, candidates, incidents, feedback, and evaluation records.
+
+- **React UI**
+  - watchlist-first workflow,
+  - drill-down site detail,
+  - evidence pack view,
+  - review and publication actions.
+
+### 5.2 Interfaces / Contracts
+
+Core contract objects:
+
+- `Site`
+- `ImageAsset`
+- `Candidate`
+- `EvidencePanel`
+- `Incident`
+- `EvaluationRecord`
+- `ReviewAction`
+
+Contract rules:
+
+- Incident outputs must always validate through typed schemas.
+- Controlled enums should be used for fields like `priority_tier`, `severity_tier`, `review_status`, and `likely_source_zone`.
+- API responses must be versionable and covered by `openapi.json`.
+- Cached artifacts must be reusable across backend tests, UI smoke flows, and demo runs.
+
+### 5.3 API Contract Artifact (`openapi.json`)
+
+Artifact policy:
+
+- Keep a committed `openapi.json` at repo root.
+- Refresh it whenever API contracts change.
+- Treat stale contract drift as a blocker for frontend work.
+- Contract tests must cover the main endpoints:
+  - health,
+  - register site,
+  - list sites,
+  - scan site,
+  - get result,
+  - fetch evidence pack,
+  - watchlist scan,
+  - export incidents.
+
+### 5.4 Data & State Strategy
+
+- **Source of truth:** `SQLite` for MVP
+- **Cache:** local filesystem + DB-linked asset metadata
+- **Model artifacts:** stored separately and versioned by training run
+- **Frozen artifacts:** demo panels, golden fixtures, evaluation manifests
+- **Consistency model:** application-level consistency is acceptable for MVP; strict transactional complexity is unnecessary beyond core scan persistence
+
+### 5.5 Key Risks in Architecture
+
+- `SimSat` imagery inconsistency or missing scenes
+- cloud-heavy scenes degrading candidate quality
+- model outputs becoming invalid or verbose
+- weak candidate generation overwhelming the VLM
+- Mapbox dependency becoming a hard runtime dependency if credentials or quotas fail
+- evaluation drift if splits and fixtures are not frozen early
+
+### 5.6 Architectural Principle
+
+The VLM should interpret evidence, not replace the full detection pipeline.
+
+That means:
+
+- candidate generation remains an explicit stage,
+- evidence packing remains deterministic and inspectable,
+- the VLM produces structured incident interpretation,
+- and post-processing remains typed and auditable.
+
+### 5.7 Differentiation Snapshot
+
+LandfillSentry should be positioned as:
+
+- not a global methane portal like `WasteMAP`,
+- not a government-facing methane notification system like `UNEP MARS`,
+- not a broad remote sensing emissions visibility platform like `Carbon Mapper`,
+- but an operator-first triage copilot that converts imagery into an actionable incident object for landfill teams.
+
+---
+
+## 6) Phase Plan
+
+This plan uses nine phases. The phases are intentionally integration-aware rather than function-siloed.
+
+## Phase 1: Foundation Lock
+
+### Objective
+
+Freeze product scope, schemas, demo-site strategy, repo structure, contracts, and testing rules before implementation complexity grows.
+
+### Deliverables
+
+- [x] canonical master plan initialized
+- [x] repo structure finalized
+- [x] core schemas defined
+- [x] `openapi.json` first draft generated
+- [x] frozen demo-site selection process defined
+- [x] testing and integration policy defined
+
+### In-Scope / Out-of-Scope
+
+- **In scope:** planning freeze, repo conventions, contract design, fixture planning
+- **Out of scope:** full production implementation
+
+### Dependencies
+
+- **Requires:** detailed report, answers doc
+- **Blocks:** all downstream implementation quality
+
+### Parts in This Phase
+
+- `1.1` Product and workflow lock
+- `1.2` Data and schema contract lock
+- `1.3` Testing and integration policy lock
+
+### Phase Exit Criteria
+
+- [x] Scope is frozen for MVP
+- [x] JSON schema and API direction are frozen
+- [x] Demo-site selection method is frozen
+- [x] Golden fixture categories are defined
+- [x] One integration checklist exists for future phases
+
+---
+
+## Phase 2: Site Registry, Imagery, and Cache
+
+### Objective
+
+Create the stable acquisition layer for sites, current imagery, historical imagery, required Mapbox context, and offline caching.
+
+### Deliverables
+
+- [x] site registry working
+- [x] SimSat retrieval working for frozen demo sites
+- [x] Mapbox retrieval working for frozen demo sites
+- [x] caching layer working
+- [x] basic cloud / missing-data handling working
+- [x] live and cached retrieval path verified
+
+### In-Scope / Out-of-Scope
+
+- **In scope:** site metadata, image fetching, cache persistence, retrieval errors
+- **Out of scope:** final methane interpretation quality
+
+### Dependencies
+
+- **Requires:** Phase 1 contracts
+- **Blocks:** candidate generation, panel building, demo assets
+
+### Parts in This Phase
+
+- `2.1` Site registry and watchlist model
+- `2.2` SimSat imagery adapters
+- `2.3` Cache and image asset persistence
+
+### Phase Exit Criteria
+
+- [x] At least one positive and one negative demo site fetch cleanly
+- [x] Mapbox context fetch and cache replay work for frozen demo sites
+- [x] Cached replay works without live calls
+- [x] Missing-data and cloud-heavy paths fail gracefully
+- [x] API contract remains valid
+- [x] Integration checkpoint with Phase 1 passes
+
+---
+
+## Phase 3: Candidate Generation and Zone Priors
+
+### Objective
+
+Build the hybrid candidate engine that proposes suspicious regions and coarse source-zone hypotheses, using Phase 2 imagery assets from live/cached SimSat Sentinel (current + historical) and required Mapbox context.
+
+### Deliverables
+
+- [x] heuristic candidate stage implemented
+- [x] temporal differencing implemented
+- [x] coarse source-zone prior logic implemented
+- [x] candidate scoring contract finalized
+- [x] positive, negative, cloudy, and missing-data fixtures supported
+- [x] live candidate path verified against SimSat current Sentinel (`/data/current/image/sentinel`), historical Sentinel (`/data/image/sentinel`), and current Mapbox context (`/data/current/image/mapbox`)
+
+### In-Scope / Out-of-Scope
+
+- **In scope:** suspicious-region proposal, simple ranking, zone priors, and candidate operation on both live and cached imagery bundles
+- **Out of scope:** final full incident interpretation
+
+### Dependencies
+
+- **Requires:** imagery and cache layer, SimSat live endpoint availability (or source bootstrap runner), and Mapbox token for live context retrieval
+- **Blocks:** evidence panels and model inference
+
+### Parts in This Phase
+
+- `3.1` Heuristic anomaly generation
+- `3.2` Temporal recurrence features
+- `3.3` Zone prior and candidate scoring
+
+### Phase Exit Criteria
+
+- [x] Candidate object emits valid schema
+- [x] Null-scene behavior is acceptable on golden negatives
+- [x] Candidate outputs are inspectable in logs or notebook form
+- [x] Cached and live candidate paths both run
+- [x] Live Phase 3 scan path runs with SimSat current+historical Sentinel and required current Mapbox context
+- [x] Integration checkpoint with Phases 1-2 passes
+
+---
+
+## Phase 4: Evidence Panels and Prompt Contract
+
+### Objective
+
+Build the deterministic evidence-packing layer and freeze the prompt / output contract used for base-model inference and later fine-tuning.
+
+### Deliverables
+
+- [x] evidence panel format frozen
+- [x] panel builder implemented
+- [x] required Mapbox panel input integrated
+- [x] metadata text block finalized
+- [x] prompt contract finalized
+- [x] output schema validation loop implemented
+
+### In-Scope / Out-of-Scope
+
+- **In scope:** panel composition, prompt format, schema validation
+- **Out of scope:** fine-tuned model quality gains
+
+### Dependencies
+
+- **Requires:** candidate outputs and imagery
+- **Blocks:** base inference, training dataset format
+
+### Parts in This Phase
+
+- `4.1` Panel composition pipeline
+- `4.2` Prompt and metadata contract
+- `4.3` Output schema and retry policy
+
+### Phase Exit Criteria
+
+- [x] Panels render consistently for frozen fixtures
+- [x] Every panel includes required Mapbox context artifact
+- [x] Prompt contract is frozen for training
+- [x] Incident schema validates on canned responses
+- [x] Live and cached panel-building paths both work
+- [x] First full end-to-end scan checkpoint passes across Phases 1-4
+
+---
+
+## Phase 5: Base Model Inference and Incident Pipeline
+
+### Objective
+
+Run the base `LFM2.5-VL-450M` model end to end with prompt-only structured output and complete the first fully functioning incident pipeline.
+
+### Deliverables
+
+- [x] base-model inference service working
+- [x] Hugging Face model pull and auth path working
+- [x] structured JSON validation working
+- [x] incident object persistence working
+- [x] review state lifecycle working
+- [x] priority / severity logic working
+
+### In-Scope / Out-of-Scope
+
+- **In scope:** prompt-only incident generation, post-processing, storage
+- **Out of scope:** tuned model superiority
+
+### Dependencies
+
+- **Requires:** frozen evidence and output contract, Hugging Face credentials and model access
+- **Blocks:** baseline benchmarking, UI truth wiring
+
+### Parts in This Phase
+
+- `5.1` Base inference runner
+- `5.2` Incident normalization and review flow
+- `5.3` Structured persistence and retrieval
+
+### Phase Exit Criteria
+
+- [x] Prompt-only pipeline works on frozen demo path
+- [x] Inference path resolves model artifacts from Hugging Face with pinned revision
+- [x] Invalid JSON path is handled gracefully
+- [x] Review states work correctly
+- [x] API retrieval endpoints function against real saved incidents
+- [x] Integration checkpoint with prior phases passes
+
+---
+
+## Phase 6: Dataset Build and Fine-Tuning
+
+### Objective
+
+Assemble a compact, provenance-aware training set and train a useful LoRA adapter that improves structured incident quality.
+
+### Deliverables
+
+- [x] dataset manifest v1
+- [x] annotation guidance v1
+- [x] train / validation / demo split frozen
+- [x] LoRA training script working
+- [x] Modal GPU training job orchestration working
+- [x] first tuned checkpoint produced
+
+### In-Scope / Out-of-Scope
+
+- **In scope:** label taxonomy, manifests, synthetic + manual + weak data separation, LoRA training
+- **Out of scope:** large-scale research-grade dataset creation
+
+### Dependencies
+
+- **Requires:** frozen prompt and panel contract, Modal account access, Hugging Face artifact push/pull path
+- **Blocks:** benchmark comparison and final demo quality story
+
+### Parts in This Phase
+
+- `6.1` Dataset assembly and provenance
+- `6.2` Annotation rules and negative set
+- `6.3` Fine-tuning run and checkpointing
+
+### Phase Exit Criteria
+
+- [x] Every sample has provenance metadata
+- [x] Validation and demo splits are frozen and respected
+- [x] Fine-tuned checkpoint can run in the same pipeline contract as the base model
+- [x] At least one full fine-tuning run completes on Modal GPU
+- [x] Training artifacts are saved and reproducible
+- [x] Second full end-to-end scan checkpoint passes across Phases 5-6
+
+---
+
+## Phase 7: Evaluation and Reliability Hardening
+
+### Objective
+
+Compare heuristics, base model, and fine-tuned model while hardening the system against likely failures.
+
+### Deliverables
+
+- [x] evaluation harness working
+- [x] baseline comparison table working
+- [x] human actionability rubric working
+- [x] null-scene report working
+- [x] failure-injection tests working
+
+### In-Scope / Out-of-Scope
+
+- **In scope:** comparative evaluation, threshold tuning, reliability testing
+- **Out of scope:** long-form scientific paper claims
+
+### Dependencies
+
+- **Requires:** stable base and fine-tuned inference paths
+- **Blocks:** credible demo and submission narrative
+
+### Parts in This Phase
+
+- `7.1` Quantitative evaluation
+- `7.2` Human usefulness and explainability review
+- `7.3` Failure mode and threshold tuning
+
+### Phase Exit Criteria
+
+- [x] Heuristic, base, and fine-tuned comparisons are available
+- [x] Null-scene performance is explicitly reported
+- [x] Invalid JSON, empty candidates, Mapbox API failures, and slow inference are tested
+- [x] Reliability results feed demo wording and claims
+- [x] Integration checkpoint with prior phases passes
+
+---
+
+## Phase 8: Watchlist UI, Review Workflow, and Export
+
+### Objective
+
+Build the operator-facing React UI that makes the product feel real, operational, and demo-ready.
+
+### Deliverables
+
+- [x] watchlist screen
+- [x] site detail screen
+- [x] evidence panel view
+- [x] review and publication controls
+- [x] export flow for incident evidence
+
+### In-Scope / Out-of-Scope
+
+- **In scope:** core operator UX and demo flow
+- **Out of scope:** full workflow automation or enterprise administration
+
+### Dependencies
+
+- **Requires:** stable backend and incident contracts
+- **Blocks:** final demo polish
+
+### Parts in This Phase
+
+- `8.1` Watchlist-first triage experience
+- `8.2` Site drill-down and evidence view
+- `8.3` Review controls and evidence export
+
+### Phase Exit Criteria
+
+- [x] Critical screens render from real API responses
+- [x] Manual smoke path works for frozen demo sites
+- [x] Frontend smoke tests pass for key routes
+- [x] Cached demo mode works
+- [x] Third full end-to-end scan checkpoint passes across Phases 7-8
+
+---
+
+## Phase 9: Deployment, Demo Stability, and Submission Assets
+
+### Objective
+
+Package the system into a robust hackathon submission with stable runtime, polished story, and clear evidence of fine-tuning and product value.
+
+### Deliverables
+
+- [ ] deployment path finalized
+- [ ] demo script finalized
+- [ ] screenshots and fallback assets prepared
+- [ ] architecture and benchmark slides prepared
+- [ ] production secrets contract finalized for SimSat, Mapbox, Hugging Face, and Modal
+- [ ] submission package finalized
+
+### In-Scope / Out-of-Scope
+
+- **In scope:** runtime stability, documentation, demo, and submission readiness
+- **Out of scope:** broad product expansion
+
+### Dependencies
+
+- **Requires:** working system and evaluation outputs
+- **Blocks:** final submission quality
+
+### Parts in This Phase
+
+- `9.1` Deployment and environment hardening
+- `9.2` Demo preparation and fallback assets
+- `9.3` Submission materials and final smoke checks
+
+### Phase Exit Criteria
+
+- [ ] Live demo path works
+- [ ] Cached fallback demo path works
+- [ ] SimSat, Mapbox, Hugging Face, and Modal secrets are validated in deployment profile
+- [ ] Final smoke tests pass
+- [ ] Submission claims match measured evidence
+- [ ] No unresolved P1 defects remain
+
+---
+
+## 7) Detailed Part Breakdown
+
+This section turns the phase map into implementation-grade parts. Each part is intentionally small enough to be decomposed into execution cards and large enough to represent a meaningful integration boundary.
+
+### 7.1 Phase 1 Parts - Foundation Lock
+
+| Part | Why | In Scope | Key Outputs | Verification | Integration Gate |
+|---|---|---|---|---|---|
+| `1.1` Product and workflow lock | Prevents scope drift before implementation starts | watchlist-first workflow, human review state, incident lifecycle, operator action definition | frozen workflow diagram, incident state model, MVP/non-goal list | manual walkthrough of primary user flow, incident-state schema test | Phase 1 cannot close unless all downstream contracts use the same workflow assumptions |
+| `1.2` Data and schema contract lock | Prevents backend / ML / UI drift | `Site`, `ImageAsset`, `Candidate`, `EvidencePanel`, `Incident`, `ReviewAction`, enums | schema definitions, JSON examples, field dictionary, `openapi.json` draft | schema snapshot tests, example payload validation | All later phases must consume the same field names and enum values |
+| `1.3` Testing and integration policy lock | Forces quality discipline early | test pyramid, golden fixture classes, live/cached policy, E2E cadence | testing charter, fixture matrix, phase-close checklist | checklist review, test scaffold placeholder | No later phase is marked done without adopting the policy |
+
+### 7.2 Phase 2 Parts - Site Registry, Imagery, and Cache
+
+| Part | Why | In Scope | Key Outputs | Verification | Integration Gate |
+|---|---|---|---|---|---|
+| `2.1` Site registry and watchlist model | All workflows begin at the site layer | site CRUD, watchlist listing, metadata storage, optional polygon support | site table, register/list endpoints, frozen demo-site manifest | API contract tests, DB schema tests | UI and scan logic must both read the same registry records |
+| `2.2` SimSat and Mapbox imagery adapters | Makes the product actually dependent on DPhi imagery and required context inputs, not mock assets alone | current Sentinel retrieval, historical Sentinel retrieval, required Mapbox retrieval | adapter module, retrieval error handling, normalized responses | adapter tests against cached/live fixtures | Candidate pipeline must run off adapter outputs without ad hoc reshaping |
+| `2.3` Cache and image asset persistence | Protects the demo and reduces repeated failures | local asset cache, image metadata persistence, replay mode | cache paths, asset records, cache invalidation rules | cached replay test, missing-data fallback test | One site scan must succeed with zero live calls after warm cache |
+
+### 7.3 Phase 3 Parts - Candidate Generation and Zone Priors
+
+| Part | Why | In Scope | Key Outputs | Verification | Integration Gate |
+|---|---|---|---|---|---|
+| `3.1` Heuristic anomaly generation | Gives the system a dependable first candidate stage | spectral anomaly rules, thresholding, bbox proposal from SimSat-fed assets | heuristic engine, score fields, candidate examples | candidate unit tests, golden positive/negative checks | Candidate object must be ingestible by panel builder without manual edits |
+| `3.2` Temporal recurrence features | Helps distinguish transient noise from persistent suspicion | historical comparison, recurrence scoring, cloud penalties, and source provenance of current/historical imagery | temporal feature calculator, recurrence score, diagnostics metadata | recurrence tests on cached history, cloudy-scene regression tests | Candidate scoring must include historical context in stable field names |
+| `3.3` Zone prior and candidate scoring | Makes the product operational rather than generic | coarse zones, facility heuristics, ranking, and required Mapbox-context dependency in scan path | `likely_source_zone_prior`, `candidate_score`, zone rationale | schema tests, manual review on demo sites, one live-path smoke scan | Incident model must consume candidate priors directly |
+
+### 7.4 Phase 4 Parts - Evidence Panels and Prompt Contract
+
+| Part | Why | In Scope | Key Outputs | Verification | Integration Gate |
+|---|---|---|---|---|---|
+| `4.1` Panel composition pipeline | The VLM only works if evidence is consistently shaped | current crop, methane-sensitive composite, temporal difference, required Mapbox, metadata | panel builder, deterministic layout, saved panel assets | panel render regression tests, cached fixture panel snapshots | Same panel spec must be used for inference, training, and demo |
+| `4.2` Prompt and metadata contract | Freeze the language interface before training | system prompt, user prompt, metadata block, task instructions | prompt templates, metadata serializer | prompt formatting tests, sample schema-validation runs | Fine-tuning cannot begin until this contract is frozen |
+| `4.3` Output schema and retry policy | Keeps model behavior bounded | schema validator, retry logic, fallback normalization | typed output validator, retry rules, invalid-output handler | invalid JSON failure test, canned-response normalization test | Incident persistence must only accept validated outputs |
+
+### 7.5 Phase 5 Parts - Base Model Inference and Incident Pipeline
+
+| Part | Why | In Scope | Key Outputs | Verification | Integration Gate |
+|---|---|---|---|---|---|
+| `5.1` Base inference runner | Establishes the prompt-only baseline before tuning | Hugging Face model loading, inference invocation, deterministic config | base inference module, latency logging, model-revision config | smoke inference test, schema-valid output test | Must run on the exact same panel format as Phase 4 |
+| `5.2` Incident normalization and review flow | Product value depends on usable incident objects | review states, priority tier, severity tier, recommended action, confidence normalization | incident assembler, state machine, follow-up rules | state-transition tests, enum validation tests | UI and export layers must read the same normalized object |
+| `5.3` Structured persistence and retrieval | Makes the backend a real product surface | incident storage, result retrieval, evidence retrieval | incidents table, result endpoints, audit metadata | endpoint tests, persistence regression tests | Watchlist and site detail endpoints must render directly from saved incidents |
+
+### 7.6 Phase 6 Parts - Dataset Build and Fine-Tuning
+
+| Part | Why | In Scope | Key Outputs | Verification | Integration Gate |
+|---|---|---|---|---|---|
+| `6.1` Dataset assembly and provenance | Prevents training chaos and unverifiable claims | manifests, split membership, label source tracking, panel version tracking | dataset manifest v1, split files, provenance schema | manifest validation script, duplicate/leakage checks | Demo split and validation split must be frozen before training |
+| `6.2` Annotation rules and negative set | Label consistency matters more than dataset size | annotation handbook, negative taxonomy, bbox guidance, plume-likely criteria | annotation guide, reviewer checklist, negative set targets | inter-pass consistency review, negative coverage audit | Training should not proceed until guidelines exist and are applied |
+| `6.3` Fine-tuning run and checkpointing | Creates the quality-improvement story | LoRA config, Modal GPU training script, adapter artifacts, evaluation hooks | train script, adapter checkpoint, Modal run metadata | train smoke test, post-train inference smoke test | Fine-tuned model must drop into the same inference contract as the base model |
+
+### 7.7 Phase 7 Parts - Evaluation and Reliability Hardening
+
+| Part | Why | In Scope | Key Outputs | Verification | Integration Gate |
+|---|---|---|---|---|---|
+| `7.1` Quantitative evaluation | Gives objective evidence for judging and iteration | heuristics vs base vs tuned comparisons, held-out sites, held-out dates | benchmark table, metric reports, threshold sweep notes | evaluation harness tests, split integrity tests | Same fixture and split policy must be respected across all comparisons |
+| `7.2` Human usefulness and explainability review | Product quality is not captured by one numeric metric | actionability rubric, explainability rubric, reviewer notes | human review form, scored examples, summary table | manual rubric completion on validation slice | Results must feed demo claims and not sit in isolation |
+| `7.3` Failure mode and threshold tuning | Reliability wins hackathons | invalid JSON, empty candidates, Mapbox API failures, slow inference, null scenes | failure-injection suite, tuned confidence thresholds, degradation policy | targeted failure tests, null-scene report | UI and backend must handle all tested failures without collapsing |
+
+### 7.8 Phase 8 Parts - Watchlist UI, Review Workflow, and Export
+
+| Part | Why | In Scope | Key Outputs | Verification | Integration Gate |
+|---|---|---|---|---|---|
+| `8.1` Watchlist-first triage experience | This is the product's strongest narrative frame | multi-site list, incident status, priority ordering, quick glance metadata | watchlist screen, site ranking logic | manual watchlist walkthrough, frontend smoke test | Data must come from real API payloads, not static placeholders |
+| `8.2` Site drill-down and evidence view | Needed to explain why an alert exists | imagery panels, bbox overlay, evidence summary, history slice | site detail screen, evidence pack UI | drill-down render test, overlay smoke test | Evidence panel fields must match backend payloads exactly |
+| `8.3` Review controls and evidence export | Makes the system feel like an operations tool | confirm/dismiss/review state changes, export card or markdown/PDF | review actions UI, export endpoint, export template | review action test, export smoke test | Review state changes must persist and reflect in watchlist immediately |
+
+### 7.9 Phase 9 Parts - Deployment, Demo Stability, and Submission Assets
+
+| Part | Why | In Scope | Key Outputs | Verification | Integration Gate |
+|---|---|---|---|---|---|
+| `9.1` Deployment and environment hardening | Prevents demo-day surprises | env var handling, compose scripts, startup commands, model path config, mandatory SimSat/Mapbox/HuggingFace/Modal secrets wiring | `.env.example`, startup docs, deployment profile | startup smoke test, dependency checklist | Live and cached demo paths must both boot cleanly |
+| `9.2` Demo preparation and fallback assets | Judges see stability first | frozen screenshots, cached outputs, architecture slides, script | demo script, fallback images, known-good JSON outputs | rehearsal checklist, timed dry run | Cached mode must fully support the demo narrative |
+| `9.3` Submission materials and final smoke checks | The last mile matters | README polish, benchmark summary, fine-tuning notes, repo cleanup | submission pack, final smoke report, claim check | final full walkthrough, repo sanity check | No claim in the submission may exceed measured evidence |
+
+### 7.10 Cross-Phase Integration Gates
+
+The full build should pass these hard checkpoints:
+
+1. **Checkpoint A (after Phase 2):** site registry + imagery + cache can fetch and replay one demo site.
+2. **Checkpoint B (after Phase 4):** one site can produce a candidate and a renderable evidence panel (including Mapbox context) from live and cached assets.
+3. **Checkpoint C (after Phase 6):** base and fine-tuned models can both consume the same panel and schema contract end to end.
+4. **Checkpoint D (after Phase 8):** watchlist UI can render and review incidents from real backend data in cached mode.
+5. **Checkpoint E (after Phase 9):** full demo succeeds in live mode and cached fallback mode.
+
+---
+
+## 8) Task Input Contract for LLM (Critical)
+
+Use this contract for every implementation card.
+
+- **Task ID:**
+- **Objective (1 sentence):**
+- **Context files/links:**
+- **Allowed files to change:**
+- **Do-not-touch files:**
+- **Constraints:**
+- **Expected output:**
+- **Acceptance tests/checks:**
+- **Definition of done:**
+
+### Prompt Skeleton
+
+`You are implementing Task <ID>.`
+
+`Goal: <objective>.`
+
+`Context: <key files and constraints>.`
+
+`Make the smallest safe change.`
+
+`Then run/describe verification: <tests/lint/typecheck/smoke path>.`
+
+`Return: summary, files changed, why, and verification results.`
+
+---
+
+## 9) Execution Protocol (LLM + Human)
+
+1. Work on the smallest task that moves the system forward.
+2. Freeze contracts early; avoid changing schemas casually once training or UI wiring starts.
+3. Build one canonical path before supporting alternatives.
+4. Add a cached offline path whenever a live dependency is introduced.
+5. Verify immediately after each task.
+6. Close every phase with an integration checkpoint.
+7. Run one full end-to-end scan after every two phases.
+8. If a task exceeds 45 minutes, split it.
+9. If a live dependency becomes unstable, preserve momentum through cached artifacts and keep moving.
+10. Do not promote demo claims beyond measured evidence.
+
+### 9.1 Integration Rule
+
+No phase is marked done unless it satisfies:
+
+- local functionality,
+- previous-phase compatibility,
+- one live path,
+- one cached offline path,
+- and documented verification.
+
+---
+
+## 10) Verification Matrix
+
+| Category | Check | Tool/Method | Frequency | Pass/Fail |
+|---|---|---|---|---|
+| Functional | Site scan returns valid incident object | API + schema tests | Every relevant task |  |
+| Quality | Lint / typecheck / formatting | Local CI commands | Every task touching code |  |
+| Contract | API matches `openapi.json` | Contract tests + schema diff | Every API change |  |
+| Data | Manifests, splits, provenance valid | Dataset validation script | Every dataset update |  |
+| Candidate Reliability | Positive/negative fixture behavior | Golden fixture tests | Per candidate change |  |
+| Model Output | JSON validity and enum correctness | Pydantic validation + retry tests | Every inference change |  |
+| Integration | End-to-end scan across current stack | Live + cached scan test | Every phase / 2 phases |  |
+| Frontend | Key screens render and bind data | Basic smoke tests + manual QA | Per UI milestone |  |
+| Failure Handling | Mapbox API failures, empty candidates, slow model, invalid JSON | Failure-injection tests | Per major milestone |  |
+| Demo Readiness | Frozen demo path completes reliably | Rehearsal checklist | Before submission |  |
+
+### 10.1 Test Pyramid for This Project
+
+- **Unit tests**
+  - schema validators
+  - bbox normalization
+  - candidate scoring helpers
+  - panel builder helpers
+  - prompt formatting
+  - review state transitions
+
+- **Integration tests**
+  - SimSat adapter + cache
+  - candidate pipeline + panel builder
+  - inference + schema validator
+  - API endpoints + DB layer
+  - UI fetch + render path against mocked or cached backend responses
+
+- **End-to-end tests**
+  - one positive-site live scan
+  - one positive-site cached scan
+  - one negative-site cached scan
+  - one cloudy / missing-data graceful-degradation path
+
+### 10.2 Golden Fixtures (Mandatory)
+
+Maintain at least:
+
+- one positive site,
+- one negative site,
+- one cloudy site,
+- one missing-data site.
+
+These fixtures are shared across backend, evaluation, and demo validation.
+
+---
+
+## 11) Progress Tracker
+
+Status legend: `TODO | WIP | BLOCKED | DONE`
+
+- [x] ✅ Phase 1 - Foundation Lock
+- [x] ✅ Phase 2 - Site Registry, Imagery, and Cache
+- [x] ✅ Phase 3 - Candidate Generation and Zone Priors
+- [x] ✅ Phase 4 - Evidence Panels and Prompt Contract
+- [x] ✅ Phase 5 - Base Model Inference and Incident Pipeline
+- [x] ✅ Phase 6 - Dataset Build and Fine-Tuning
+- [x] ✅ Phase 7 - Evaluation and Reliability Hardening
+- [x] ✅ Phase 8 - Watchlist UI, Review Workflow, and Export
+- [ ] Phase 9 - Deployment, Demo Stability, and Submission Assets
+
+---
+
+## 12) Change Log
+
+| Date | Task ID | Files Changed | Summary | Verification | Status |
+|---|---|---|---|---|---|
+| `2026-04-19` | `PLAN-CHUNK-01` | `LandfillSentry_Ops_Master_Project_Plan.md` | Initialized master plan with strategy, architecture, phase map, and verification framework | Manual review against frozen decisions and source reports | `done` |
+| `2026-04-19` | `PLAN-FULL-DRAFT` | `LandfillSentry_Ops_Master_Project_Plan.md` | Expanded plan into full draft with detailed phase parts, operational deep dive, execution wave, data governance, API spec, evaluation plan, UX, deployment, GTM, and risk matrix | Manual structural review for completeness against detailed report and frozen answers | `done` |
+| `2026-04-19` | `PHASE1-IMPLEMENTATION` | `README.md`, `openapi.json`, `docs/*`, `apps/api/*`, `tests/*`, `assets/demo_sites/*`, `scripts/*` | Implemented Phase 1 foundation lock artifacts: repo skeleton, schema and enum contracts, API scaffold, OpenAPI draft, demo-site selection rubric, golden fixture matrix, and integration checklist | `python -m unittest tests/test_api_contract.py`, `python -m unittest tests/test_schema_validation.py`, `python -m compileall apps scripts` | `done` |
+| `2026-04-19` | `PLAN-MANDATORY-DEPENDENCIES` | `LandfillSentry_Ops_Master_Project_Plan.md` | Updated plan to make Mapbox, Hugging Face, and Modal GPU mandatory; aligned phase deliverables, part breakdowns, deployment/security requirements, and execution cards | Manual consistency review across sections 3, 6, 7, 16, and 17 | `done` |
+| `2026-04-19` | `PHASE2-IMPLEMENTATION` | `apps/api/main.py`, `apps/api/routes/api.py`, `apps/api/runtime.py`, `apps/api/config.py`, `apps/api/db/*`, `apps/api/services/*`, `scripts/fetch_site_history.py`, `tests/test_phase2_integration.py`, `openapi.json`, `.env.example`, `README.md`, `LandfillSentry_Ops_Master_Project_Plan.md` | Implemented Phase 2: SQLite-backed site registry, SimSat+Mapbox adapters, cache/replay flow, and persisted scan evidence path | `python -m unittest tests/test_api_contract.py`, `python -m unittest tests/test_schema_validation.py`, `python -m unittest tests/test_phase2_integration.py`, `python -m compileall apps scripts tests` | `done` |
+| `2026-04-19` | `PHASE2-SIMSAT-REPO-INTEGRATION` | `apps/api/config.py`, `apps/api/services/imagery_service.py`, `.env.example`, `README.md`, `tests/test_phase2_integration.py` | Aligned live imagery implementation to DPhi SimSat repository API contract using `/data/image/sentinel` and `/data/image/mapbox` endpoints and metadata headers | `python -m unittest tests/test_api_contract.py tests/test_schema_validation.py tests/test_phase2_integration.py`, `python -m compileall apps scripts tests` | `done` |
+| `2026-04-20` | `PHASE3-IMPLEMENTATION` | `apps/api/services/candidate_service.py`, `apps/api/routes/api.py`, `apps/api/runtime.py`, `apps/api/db/repository.py`, `apps/api/services/__init__.py`, `tests/test_phase3_candidates.py`, `LandfillSentry_Ops_Master_Project_Plan.md` | Implemented Phase 3 hybrid candidate engine with heuristic anomaly scoring, temporal recurrence features, zone priors, candidate persistence, and scan/evidence integration | `python -m unittest tests/test_api_contract.py tests/test_schema_validation.py tests/test_phase2_integration.py tests/test_phase3_candidates.py`, `python -m compileall apps scripts tests` | `done` |
+| `2026-04-20` | `SIMSAT-ENDPOINT-ALIGNMENT` | `apps/api/services/imagery_service.py`, `tests/test_phase2_integration.py`, `README.md` | Updated live endpoint usage to SimSat contract split: current inference (`/data/current/image/sentinel`, `/data/current/image/mapbox`) plus historical Sentinel retrieval (`/data/image/sentinel`) for temporal and fine-tuning workflows | `python -m unittest tests/test_api_contract.py tests/test_schema_validation.py tests/test_phase2_integration.py tests/test_phase3_candidates.py`, `python -m compileall apps scripts tests` | `done` |
+| `2026-04-20` | `PHASE3-LIVE-DATA-ALIGNMENT` | `LandfillSentry_Ops_Master_Project_Plan.md` | Updated Phase 3 plan details to explicitly require and verify live candidate operation using SimSat current/historical Sentinel and required current Mapbox context, while retaining cached fallback behavior | Manual consistency review across sections 6, 7.3, 11, 12, and 17 (`3.1` card) | `done` |
+| `2026-04-20` | `PHASE4-IMPLEMENTATION` | `apps/api/routes/api.py`, `apps/api/runtime.py`, `apps/api/db/repository.py`, `apps/api/services/panel_service.py`, `apps/api/services/prompt_contract_service.py`, `apps/api/services/output_validation_service.py`, `apps/api/services/__init__.py`, `tests/test_phase4_panels.py`, `LandfillSentry_Ops_Master_Project_Plan.md` | Implemented Phase 4 deterministic evidence panel builder, required Mapbox panel slot integration, frozen prompt/output contract metadata, and incident output schema validation loop with retry trace persisted in scan evidence | `python -m unittest tests/test_api_contract.py tests/test_schema_validation.py tests/test_phase2_integration.py tests/test_phase3_candidates.py tests/test_phase4_panels.py`; live scan smoke check via `scan_site` with SimSat backend | `done` |
+| `2026-04-20` | `PHASE5-IMPLEMENTATION` | `apps/api/config.py`, `apps/api/runtime.py`, `apps/api/routes/api.py`, `apps/api/services/inference_service.py`, `apps/api/services/__init__.py`, `tests/test_phase5_inference.py`, `scripts/run_lfm25_examples.py`, `requirements.txt`, `.env.example`, `.env.local`, `README.md`, `LandfillSentry_Ops_Master_Project_Plan.md` | Implemented Phase 5 base-model inference pipeline with Hugging Face model loading (`LiquidAI/LFM2.5-VL-450M@main`), prompt-only image inference integration, structured output validation/fallback, persisted incident/review lifecycle support, and inference metadata trace in evidence payloads | `python -m unittest tests/test_api_contract.py tests/test_schema_validation.py tests/test_phase2_integration.py tests/test_phase3_candidates.py tests/test_phase4_panels.py tests/test_phase5_inference.py`; live end-to-end `scan_site` run with `INFERENCE_MODE=live`; `python scripts/run_lfm25_examples.py --max-new-tokens 24` | `done` |
+| `2026-04-21` | `PHASE8-IMPLEMENTATION` | `apps/api/main.py`, `apps/api/db/repository.py`, `apps/api/routes/api.py`, `apps/web/public/ops.html`, `apps/web/public/ops.css`, `apps/web/public/ops-app.jsx`, `apps/web/README.md`, `tests/test_phase8_ui_workflow.py`, `README.md`, `LandfillSentry_Ops_Master_Project_Plan.md` | Implemented Phase 8 operator UX and workflow: watchlist API + screen, site drill-down evidence view, persisted review controls, incident export endpoint (markdown/json), and `/ops` console route with frontend smoke coverage | `python -m unittest tests/test_phase8_ui_workflow.py`; `python -m unittest tests/test_api_contract.py tests/test_schema_validation.py tests/test_phase2_integration.py tests/test_phase3_candidates.py tests/test_phase4_panels.py tests/test_phase5_inference.py tests/test_phase6_training.py tests/test_phase7_evaluation.py tests/test_phase7_reliability.py tests/test_phase8_ui_workflow.py`; `python -m compileall apps scripts tests` | `done` |
+
+---
+
+## 13) Blockers & Decisions Log
+
+### Active Blockers
+
+- Blocker: No active Phase 8 blockers
+- Next action: begin Phase 9 (`9.1` deployment and environment hardening)
+- ETA: `Phase 9`
+
+### Key Decisions
+
+- Decision: operator-first product
+- Why chosen: clearest action loop and strongest demo fit
+- Impact: watchlist triage and source-zone guidance become core UX
+
+- Decision: synchronous inference for MVP
+- Why chosen: simplest stable path under hackathon constraints
+- Impact: caching and precomputation become essential
+
+- Decision: phase completion requires integration
+- Why chosen: reduces end-stage collapse risk
+- Impact: more frequent checkpoints and fewer isolated branches
+
+---
+
+## 14) Release & Rollback Plan
+
+- **Release strategy:** `single MVP release with cached demo fallback`
+- **Pre-release checklist:**
+  - [ ] Demo sites frozen
+  - [ ] Golden fixtures frozen
+  - [ ] Fine-tuned or fallback prompt-only path selected
+  - [ ] Cached offline demo path validated
+  - [ ] All required secrets documented in `.env.example`
+- **Rollback criteria:**
+  - Prompt-only model outperforms or stabilizes better than tuned model
+  - Live dependency threatens demo reliability
+  - UI instability exceeds acceptable demo risk
+- **Rollback steps:**
+  - Revert to cached incident outputs and panels
+  - Switch to prompt-only model path if fine-tuned path is unstable
+  - Reduce optional features before reducing the core scan-to-incident workflow
+- **Post-release validation:**
+  - final smoke scan,
+  - final watchlist walkthrough,
+  - final export path check.
+
+---
+
+## 15) Post-Phase Retro Template
+
+- What went well:
+- What broke or drifted:
+- What integration issue appeared:
+- What should be frozen more aggressively next phase:
+- What can be simplified:
+
+---
+
+## 16) Operational Deep Dive
+
+### 16.1 External Data Sources and Their Role
+
+| Dependency | MVP Role | Why It Exists in the System | MVP Criticality |
+|---|---|---|---|
+| `SimSat Sentinel-2` | primary multispectral imagery source | current and historical imagery for anomaly generation and temporal comparison | Required |
+| `SimSat Mapbox` | required high-resolution context | sharper facility interpretation, stronger zone context, and demo grounding | Required |
+| `LFM2.5-VL-450M` | vision-language interpretation model | turns evidence panels into structured incident objects | Required |
+| `Hugging Face` | model and adapter artifact registry | canonical source for model revisions and fine-tuned adapter versions | Required |
+| `Modal GPU` | training execution platform | reproducible LoRA fine-tuning runs under hackathon timelines | Required |
+| `Project Eucalyptus` | benchmark and bootstrap asset source | methane-domain priors, synthetic plume generation ideas, optional candidate improvements | Recommended |
+| `METER` | watchlist enrichment source | landfill site discovery and metadata support | Recommended |
+| weather / wind sources | contextual enhancement only | future persistence interpretation and synthetic realism | Optional |
+
+### 16.2 Internal Service Design
+
+The internal design should remain modular without becoming prematurely microservice-heavy.
+
+- **API Gateway / Orchestrator**
+  - validates incoming requests,
+  - coordinates retrieval, candidate generation, panel building, inference, and persistence.
+
+- **Site Registry Service**
+  - manages site metadata,
+  - stores frozen demo-site list,
+  - supports watchlist and optional polygons.
+
+- **Imagery Service**
+  - wraps SimSat calls,
+  - normalizes metadata,
+  - stores assets to cache,
+  - surfaces cloud or missing-data signals.
+
+- **Candidate Generation Service**
+  - computes anomaly candidates,
+  - adds recurrence and zone priors,
+  - emits ranked candidates.
+
+- **Panel Builder Service**
+  - assembles evidence packs consistently,
+  - writes panel assets to cache,
+  - stores panel generator version metadata.
+
+- **VLM Inference Service**
+  - loads base or fine-tuned model,
+  - runs structured prompting,
+  - validates and retries outputs.
+
+- **Incident Service**
+  - normalizes model outputs,
+  - computes review state,
+  - publishes incidents to API consumers.
+
+- **UI Service**
+  - watchlist-first workflow,
+  - site drill-down,
+  - review and export actions.
+
+### 16.3 End-to-End Data Flow
+
+1. User opens the watchlist or requests a scan for a site.
+2. Backend loads site coordinates and optional polygon.
+3. Imagery service fetches current Sentinel-2 imagery and historical scenes via SimSat.
+4. Mapbox context is fetched as a required panel input.
+5. Preprocessing filters weak scenes and normalizes imagery metadata.
+6. Candidate generator proposes one or more suspicious regions.
+7. Panel builder assembles multimodal evidence.
+8. Base or fine-tuned `LFM2.5-VL-450M` receives panel plus prompt.
+9. Output is validated and normalized into an incident object.
+10. Incident is stored as `proposed`.
+11. UI displays the result to the operator.
+12. Human review promotes incident to `published`, `dismissed`, or keeps it in `needs_review`.
+
+### 16.4 Candidate Generation Pipeline
+
+**Recommended MVP mode:** hybrid candidate generation
+
+The candidate engine should combine:
+
+- simple spectral anomaly screening,
+- temporal differencing against recent acceptable scenes,
+- coarse zone priors,
+- optional model-assisted ranking where practical.
+
+Candidate scoring features should include:
+
+- anomaly intensity,
+- temporal recurrence,
+- cloud penalty,
+- facility-center proximity or heuristic zone prior,
+- panel confidence support fields.
+
+Candidate output contract:
+
+```json
+{
+  "candidate_id": "cand_001",
+  "site_id": "LF_DEMO_001",
+  "bbox_norm": [0.25, 0.15, 0.47, 0.32],
+  "candidate_score": 0.71,
+  "temporal_recurrence": 0.64,
+  "cloud_penalty": 0.12,
+  "likely_source_zone_prior": "active_face"
+}
+```
+
+### 16.5 Evidence Panel Specification
+
+The panel format must be frozen before fine-tuning.
+
+Required components:
+
+1. current RGB crop,
+2. methane-sensitive spectral composite crop,
+3. temporal-difference crop,
+4. Mapbox context crop,
+5. metadata text block,
+6. candidate bbox and score metadata.
+
+Metadata text should include:
+
+- site id,
+- timestamp requested,
+- timestamp captured,
+- cloud score,
+- candidate score,
+- recurrence score,
+- zone prior,
+- Mapbox request metadata and retrieval timestamp.
+
+### 16.6 Incident Object and Enum Contract
+
+Minimum required fields:
+
+```json
+{
+  "incident_id": "inc_001",
+  "site_id": "LF_DEMO_001",
+  "analysis_time": "2026-04-19T11:15:00Z",
+  "plume_likely": true,
+  "confidence": 0.84,
+  "bbox_norm": [0.32, 0.18, 0.56, 0.43],
+  "likely_source_zone": "active_face",
+  "persistence_score": 0.72,
+  "priority_tier": "high",
+  "severity_tier": "medium",
+  "review_status": "proposed",
+  "evidence_summary": "Recurring anomaly near the active working area across recent cloud-acceptable scenes.",
+  "recommended_followup": "Inspect active face cover integrity and nearby gas capture within 24 hours.",
+  "model_version": "lfm25vl450m-landfillsentry-lora-v1"
+}
+```
+
+Recommended controlled enums:
+
+- `likely_source_zone`: `active_face | gas_system | perimeter_or_unknown`
+- `priority_tier`: `low | medium | high | urgent`
+- `severity_tier`: `low | medium | high`
+- `review_status`: `proposed | published | dismissed | needs_review`
+- `feedback_status`: `confirmed | dismissed | needs_review | unresolved`
+
+### 16.7 Dataset and Annotation Governance
+
+#### Dataset design goals
+
+- small but high-signal,
+- provenance-aware,
+- strong negative coverage,
+- frozen demo and validation sets,
+- consistent panel format between training and inference.
+
+#### Sample sources
+
+- real historical/current site panels from SimSat,
+- synthetic plume overlays or derived methane-domain examples,
+- weak labels from heuristic or candidate-stage confidence,
+- manual labels on selected panels.
+
+#### Required dataset metadata per sample
+
+- `sample_id`
+- `site_id`
+- `timestamp`
+- `split`
+- `label_source`
+- `panel_version`
+- `candidate_version`
+- `imagery_sources_present`
+- `annotator_id`
+- `notes`
+
+Allowed `label_source` values:
+
+- `manual`
+- `weak`
+- `synthetic`
+- `mixed`
+
+#### Split policy
+
+- **Train:** mixed real + synthetic + weak data
+- **Validation:** frozen real-heavy set
+- **Demo:** frozen set reserved for product demo only
+- Never fine-tune on demo examples
+
+#### Negative example policy
+
+Negative examples must explicitly include:
+
+- null scenes with no obvious anomaly,
+- cloud-heavy scenes,
+- bright or reflective surfaces,
+- visually complex landfill scenes that should not trigger high confidence,
+- suspicious but ultimately unconvincing candidates.
+
+#### Annotation rules
+
+- `plume_likely = true` only when the evidence pack supports a plausible, spatially localizable suspicious region.
+- Bounding boxes should be tight enough to indicate the suspicious region without pretending scientific precision.
+- If zone attribution is weak, label `perimeter_or_unknown` instead of forcing a precise class.
+- Annotators should prefer consistency over ambition.
+
+### 16.8 Fine-Tuning Strategy
+
+Recommended approach:
+
+- start with prompt-only pipeline,
+- freeze panel and prompt contracts,
+- build a narrow supervised dataset,
+- fine-tune with LoRA,
+- compare against the base model on the same validation slices.
+
+Suggested stage order:
+
+1. synthetic and weakly labeled SFT bootstrap,
+2. manual correction and validation refinement,
+3. optional instruction polishing if time remains.
+
+Training artifacts to save:
+
+- adapter weights,
+- training config,
+- dataset manifest,
+- eval summary,
+- sample outputs,
+- panel format version,
+- prompt contract version.
+
+### 16.9 Prompting and Output Rules
+
+Prompt design principles:
+
+- be explicit about structured output,
+- reinforce that the product is triage, not quantification,
+- constrain zone taxonomy and enum values,
+- ask for concise evidence summaries,
+- forbid unsupported claims.
+
+Core output rules:
+
+- JSON only or clearly parseable structured response,
+- no extra narrative outside contract unless debugging mode is enabled,
+- bbox normalized to `[x1, y1, x2, y2]`,
+- confidence in `[0,1]`,
+- persistence score in `[0,1]`.
+
+### 16.10 Evaluation Framework
+
+#### Baselines
+
+1. candidate-only heuristic path
+2. base `LFM2.5-VL-450M` with prompt-only inference
+3. fine-tuned `LFM2.5-VL-450M`
+
+#### Core metrics
+
+| Metric | Why It Matters | Target Style |
+|---|---|---|
+| JSON validity rate | system reliability | directional target, ideally >95% on validation |
+| Operator usefulness | product value | majority of reviewed outputs considered actionable |
+| Null-scene false positive rate | trust preservation | explicitly minimized and reported |
+| Zone accuracy / agreement | operational focus | improve over base prompt-only baseline |
+| BBox quality | localization utility | useful, not necessarily scientifically perfect |
+| Human explainability score | demo and trust | clearly understandable evidence chain |
+
+#### Evaluation slices
+
+- held-out sites,
+- held-out dates,
+- frozen demo set,
+- golden negative set.
+
+#### Human review rubric
+
+Each reviewed incident should be scored on:
+
+- actionability,
+- clarity,
+- plausibility,
+- usefulness of follow-up guidance,
+- trustworthiness of explanation.
+
+### 16.11 Product UX and Demo Flow
+
+Core screens:
+
+1. **Watchlist**
+   - prioritized sites,
+   - alert count,
+   - review status,
+   - latest scan snapshot.
+
+2. **Site Detail**
+   - current incident summary,
+   - candidate zone,
+   - confidence,
+   - priority,
+   - review actions.
+
+3. **Evidence Pack**
+   - imagery panel,
+   - bbox overlay,
+   - evidence summary,
+   - recommended follow-up,
+   - export action.
+
+Recommended demo sequence:
+
+1. open watchlist,
+2. show prioritized site list,
+3. select a flagged site,
+4. show current vs historical imagery and candidate zone,
+5. explain how evidence is assembled,
+6. show structured incident object,
+7. review and publish or dismiss,
+8. export evidence pack,
+9. mention cached fallback and fine-tuning result briefly.
+
+### 16.12 Backend API Specification
+
+| Endpoint | Method | Purpose | MVP Status |
+|---|---|---|---|
+| `/health` | `GET` | runtime health | Required |
+| `/sites` | `POST` | register a site | Required |
+| `/sites` | `GET` | list watchlist sites | Required |
+| `/sites/{id}` | `GET` | get site metadata | Recommended |
+| `/sites/{id}/scan` | `POST` | run synchronous scan | Required |
+| `/scans/{id}` | `GET` | get scan result | Required |
+| `/scans/{id}/evidence` | `GET` | get evidence pack | Required |
+| `/watchlist/scan` | `POST` | batch scan or precompute watchlist | Recommended |
+| `/incidents/{id}/review` | `POST` | confirm, dismiss, needs review | Required |
+| `/incidents/export` | `GET` | export JSON / markdown / PDF-ready payload | Required |
+
+OpenAPI policy:
+
+- generate `openapi.json`,
+- commit it,
+- regenerate when route or schema changes,
+- block frontend drift against stale contracts.
+
+### 16.13 Data Models
+
+#### Site
+
+- `site_id`
+- `name`
+- `lat`
+- `lon`
+- `country`
+- `operator`
+- `watchlist_enabled`
+- `polygon_geojson` optional
+- `metadata`
+
+#### ImageAsset
+
+- `asset_id`
+- `site_id`
+- `source`
+- `timestamp_requested`
+- `timestamp_captured`
+- `cloud_cover`
+- `bands`
+- `local_path`
+- `cache_key`
+
+#### Candidate
+
+- `candidate_id`
+- `site_id`
+- `job_id`
+- `bbox_norm`
+- `candidate_score`
+- `temporal_recurrence`
+- `cloud_penalty`
+- `likely_source_zone_prior`
+
+#### EvidencePanel
+
+- `panel_id`
+- `site_id`
+- `candidate_id`
+- `panel_version`
+- `current_rgb_path`
+- `spectral_composite_path`
+- `temporal_diff_path`
+- `mapbox_context_path`
+- `metadata_json`
+
+#### Incident
+
+- `incident_id`
+- `site_id`
+- `job_id`
+- `plume_likely`
+- `confidence`
+- `bbox_norm`
+- `likely_source_zone`
+- `persistence_score`
+- `priority_tier`
+- `severity_tier`
+- `review_status`
+- `feedback_status`
+- `evidence_summary`
+- `recommended_followup`
+- `model_version`
+
+#### EvaluationRecord
+
+- `eval_id`
+- `split`
+- `site_id`
+- `baseline_model`
+- `candidate_model`
+- `json_valid_rate`
+- `incident_f1`
+- `zone_accuracy`
+- `bbox_iou`
+- `human_usefulness_score`
+
+### 16.14 Repository Structure
+
+```text
+landfillsentry-ops/
+├── README.md
+├── openapi.json
+├── docs/
+│   ├── architecture.md
+│   ├── evaluation.md
+│   ├── annotation-guide.md
+│   └── demo-script.md
+├── apps/
+│   ├── api/
+│   │   ├── main.py
+│   │   ├── routes/
+│   │   ├── schemas/
+│   │   ├── services/
+│   │   └── db/
+│   └── web/
+│       ├── src/
+│       └── public/
+├── ml/
+│   ├── candidate_generation/
+│   ├── panel_builder/
+│   ├── vlm/
+│   ├── training/
+│   └── evaluation/
+├── data/
+│   ├── raw/
+│   ├── processed/
+│   ├── cache/
+│   ├── labels/
+│   └── manifests/
+├── scripts/
+│   ├── fetch_site_history.py
+│   ├── build_panels.py
+│   ├── run_inference.py
+│   ├── train_lora.py
+│   └── benchmark_models.py
+├── tests/
+│   ├── fixtures/
+│   ├── test_api.py
+│   ├── test_candidates.py
+│   ├── test_panels.py
+│   ├── test_schema_validation.py
+│   ├── test_inference_smoke.py
+│   └── test_frontend_smoke.md
+└── assets/
+    ├── demo_sites/
+    ├── screenshots/
+    └── diagrams/
+```
+
+### 16.15 Deployment, Infrastructure, and Training
+
+Recommended MVP runtime:
+
+1. SimSat
+2. Mapbox
+3. Hugging Face (model registry/auth)
+4. FastAPI backend
+5. React frontend
+6. optional separate model-serving container
+
+Recommended local setup:
+
+- Docker Compose for local services
+- SQLite file in local volume
+- filesystem cache for panel assets
+- local or remote GPU path for inference
+
+Recommended hosted setup:
+
+- frontend on Vercel / Netlify,
+- backend on Railway / Render / Fly.io or similar,
+- training on Modal GPU (mandatory),
+- inference on a GPU instance or local GPU depending demo constraints.
+
+Inference strategy:
+
+- first path: `Transformers`
+- future path: `ONNX` or `GGUF` fallback
+
+### 16.16 Security, Secrets, Licensing, and Usage Risk
+
+Must document:
+
+- SimSat base URL and credentials,
+- Mapbox token,
+- Hugging Face token,
+- Modal token / workspace config and GPU runtime settings,
+- model license constraints,
+- Project Eucalyptus non-commercial or usage conditions if reused,
+- dataset provenance,
+- wording guardrails for real-site claims.
+
+Minimum security checklist:
+
+- `.env.example` committed,
+- secrets never committed,
+- cached artifacts reviewed for sensitive metadata,
+- export outputs avoid overclaiming or legal language.
+
+### 16.17 Competitor Positioning and Buyer Wedge
+
+| System | Primary Mode | What It Does Well | LandfillSentry Difference |
+|---|---|---|---|
+| `WasteMAP` | transparency and decision support platform | broad waste methane visibility, scenario planning | LandfillSentry is site-operator-first and incident-oriented |
+| `UNEP MARS` | detect / attribute / notify ecosystem | large-event notification and public-interest action chain | LandfillSentry is not a global notification system; it is a facility triage workflow |
+| `Carbon Mapper` | emissions visibility and attribution | high-quality emissions detection and data products | LandfillSentry focuses on turning evidence into a workflow-ready incident object for operators |
+
+Light GTM framing:
+
+- **initial buyer wedge:** landfill operator or operator-adjacent environmental compliance lead
+- **near-term value:** inspection prioritization and reviewable incident workflow
+- **future expansion:** municipality dashboards, evidence export, insurer workflows, portfolio scoring
+
+### 16.18 Risk Matrix
+
+| Risk | Probability | Impact | Mitigation | Fallback |
+|---|---|---|---|---|
+| SimSat imagery unavailable | Medium | High | freeze demo sites early, cache assets | cached demo path |
+| cloud cover too high | Medium | Medium | cloud filters and historical selection | use last acceptable scene |
+| candidate engine too noisy | Medium | High | thresholds, recurrence score, negatives | simpler ranking and stricter cutoffs |
+| invalid model JSON | Medium | High | schema prompts, retries, validation | normalization fallback or reject |
+| fine-tuning underdelivers | Medium | Medium | keep prompt-only baseline strong | demo prompt-only path |
+| Mapbox API outage or quota exhaustion | Medium | High | retries, quota monitoring, and warm cached Mapbox artifacts for frozen sites | cached Mapbox context for demo path |
+| overclaiming science | Medium | High | strict wording guardrails | reset narrative to triage copilot |
+| demo runtime instability | Medium | High | cached panels and results | full offline demo path |
+
+### 16.19 Post-Hackathon Roadmap
+
+#### Phase 2 Productization
+
+- better facility polygons and zone maps,
+- asynchronous scans and queueing,
+- stronger export formats,
+- operator feedback analytics,
+- improved threshold calibration.
+
+#### Phase 3 Product Expansion
+
+- municipality and compliance workflows,
+- audit trail and evidence lifecycle,
+- broader landfill portfolio monitoring,
+- richer weather and wind context,
+- active learning loop from operator feedback.
+
+---
+
+## 17) Initial Execution Wave
+
+### 17.1 Compressed 14-Day Build Plan
+
+| Window | Focus | Required Output |
+|---|---|---|
+| Days 1-2 | Foundation lock | schemas, repo structure, demo-site shortlist, OpenAPI draft |
+| Days 3-4 | Site registry + imagery + cache | working live and cached imagery retrieval |
+| Days 5-6 | Candidate engine + panel builder | renderable evidence panels from frozen sites |
+| Days 7-8 | Base model incident pipeline | valid incident JSON and persistence |
+| Days 9-10 | Dataset prep + LoRA training | dataset manifest and first tuned checkpoint |
+| Days 11-12 | Evaluation + reliability | baseline comparison and failure tests |
+| Days 13-14 | React UI + demo hardening | watchlist workflow, export, final demo path |
+
+### 17.2 Recommended Initial Execution Cards
+
+| Card ID | Title | Phase | Outcome |
+|---|---|---|---|
+| `EC-1-1-01` | Freeze incident schema and enums | `1.2` | stable contract for backend, ML, and UI |
+| `EC-1-1-02` | Freeze review-state workflow | `1.1` | proposed / published / dismissed / needs_review lifecycle |
+| `EC-1-2-01` | Draft and commit `openapi.json` | `1.2` | API contract baseline |
+| `EC-1-3-01` | Define golden fixture matrix | `1.3` | positive / negative / cloudy / missing-data fixtures |
+| `EC-1-3-02` | Select and freeze demo-site shortlist rubric | `1.1` | repeatable site-selection method |
+| `EC-2-1-01` | Implement site registry table and routes | `2.1` | list/register/get sites |
+| `EC-2-2-01` | Implement SimSat Sentinel retrieval adapter | `2.2` | current + historical Sentinel fetch |
+| `EC-2-2-02` | Implement required Mapbox retrieval adapter | `2.2` | mandatory context path for every scan |
+| `EC-2-3-01` | Implement image asset cache and replay | `2.3` | live/cached imagery modes |
+| `EC-3-1-01` | Build first heuristic candidate scorer | `3.1` | candidate bbox and score |
+| `EC-4-1-01` | Build evidence panel composer | `4.1` | stable panel output |
+| `EC-5-1-01` | Run prompt-only base model end to end | `5.1` | first valid incident object |
+| `EC-5-1-02` | Wire Hugging Face model auth and pinned revision load | `5.1` | reproducible model load path |
+| `EC-6-3-02` | Run first LoRA training job on Modal GPU | `6.3` | mandatory training-platform proof |
+
+### 17.3 Active Execution Cards (Recommended Starting Set)
+
+### `1.2` Contract Freeze
+
+### Card Identity
+
+- **Card ID:** `EC-1-1-01`
+- **Title:** `Freeze Incident Schema And Enums`
+- **Phase/Part:** `1.2`
+- **Status:** `DONE`
+
+### Objective (1 sentence)
+
+Define and freeze the `Incident` contract, enum values, and sample payloads so backend, ML, and frontend work from the same object.
+
+### Scope Guardrails
+
+- **In scope:** schema fields, enums, sample JSON, validation rules
+- **Out of scope:** model inference implementation
+- **Do not change:** product scope or phase structure
+
+### Inputs
+
+- Files/docs to read first: detailed report, answers doc, master plan sections `1-5`
+- Assumptions: operator-first triage and review flow are frozen
+- Dependencies/preconditions: none beyond planning baseline
+
+### Allowed File Changes
+
+- `docs/architecture.md`
+- `apps/api/schemas/*`
+- `openapi.json`
+
+### Planned Output
+
+- Expected code/artifact result: typed schema and example incident payload
+- User-visible behavior/result: downstream features all speak the same language
+
+### Verification
+
+- Required checks: schema validation tests, example payload parse
+- Acceptance criteria:
+  - [x] Incident schema validates sample payloads
+  - [x] Enums are explicitly frozen and documented
+  - [x] Review-state fields exist
+
+### Integration Check
+
+- Previous phase dependency verified: `yes`
+- Live path verified: `n/a`
+- Cached path verified: `n/a`
+
+### Timebox & Control
+
+- **Hard stop at (+45 min):** `split card`
+
+### `1.3` Testing Policy
+
+### Card Identity
+
+- **Card ID:** `EC-1-3-01`
+- **Title:** `Define Golden Fixture Matrix`
+- **Phase/Part:** `1.3`
+- **Status:** `DONE`
+
+### Objective (1 sentence)
+
+Freeze the minimum fixture classes that all later tests and demo hardening will use.
+
+### Scope Guardrails
+
+- **In scope:** fixture taxonomy, storage convention, naming policy
+- **Out of scope:** full fixture creation
+- **Do not change:** core product thesis
+
+### Verification
+
+- Acceptance criteria:
+  - [x] Positive fixture defined
+  - [x] Negative fixture defined
+  - [x] Cloudy fixture defined
+  - [x] Missing-data fixture defined
+
+### `2.1` Site Registry
+
+### Card Identity
+
+- **Card ID:** `EC-2-1-01`
+- **Title:** `Implement Site Registry Endpoints`
+- **Phase/Part:** `2.1`
+- **Status:** `DONE`
+
+### Objective (1 sentence)
+
+Create site storage and API routes so the watchlist and scan pipeline have a stable source of truth for demo sites.
+
+### Scope Guardrails
+
+- **In scope:** register, list, get site
+- **Out of scope:** complex auth, multi-tenant management
+- **Do not change:** SQLite-first storage choice
+
+### Verification
+
+- Acceptance criteria:
+  - [x] Site create endpoint works
+  - [x] Site list endpoint works
+  - [x] Site read endpoint works
+  - [x] Contracts align with `openapi.json`
+
+### `2.2` Imagery Adapter
+
+### Card Identity
+
+- **Card ID:** `EC-2-2-01`
+- **Title:** `Implement SimSat Sentinel Adapter`
+- **Phase/Part:** `2.2`
+- **Status:** `DONE`
+
+### Objective (1 sentence)
+
+Fetch current and historical Sentinel-2 imagery from SimSat and normalize the response for downstream services.
+
+### Scope Guardrails
+
+- **In scope:** adapter, request params, response normalization, error handling
+- **Out of scope:** candidate scoring
+- **Do not change:** SimSat-first MVP assumption
+
+### Verification
+
+- Acceptance criteria:
+  - [x] Current imagery fetch works for one demo site
+  - [x] Historical imagery fetch works for one demo site
+  - [x] Missing-data path is handled cleanly
+
+### `2.3` Cache Layer
+
+### Card Identity
+
+- **Card ID:** `EC-2-3-01`
+- **Title:** `Implement Image Cache And Replay`
+- **Phase/Part:** `2.3`
+- **Status:** `DONE`
+
+### Objective (1 sentence)
+
+Persist fetched imagery and metadata so scans can replay without live dependency calls.
+
+### Scope Guardrails
+
+- **In scope:** cache directory layout, DB asset metadata, replay mode
+- **Out of scope:** distributed caching
+- **Do not change:** local-first MVP architecture
+
+### Verification
+
+- Acceptance criteria:
+  - [x] Asset metadata persists
+  - [x] Cached replay succeeds with live calls disabled
+  - [x] Cache path integrates with fixture strategy
+
+### `3.1` Candidate Heuristics
+
+### Card Identity
+
+- **Card ID:** `EC-3-1-01`
+- **Title:** `Build First Candidate Scorer`
+- **Phase/Part:** `3.1`
+- **Status:** `DONE`
+
+### Objective (1 sentence)
+
+Produce at least one ranked candidate bbox and score from cached imagery using a simple stable heuristic path.
+
+### Scope Guardrails
+
+- **In scope:** simple anomaly rule, bbox proposal, score field
+- **Out of scope:** learned ranking model
+- **Do not change:** candidate object contract
+
+### Verification
+
+- Acceptance criteria:
+  - [x] Candidate object validates
+  - [x] Positive fixture produces a nontrivial candidate
+  - [x] Negative fixture does not trigger high-confidence output
+  - [x] Live scan path for candidate stage works with SimSat current/historical Sentinel plus required current Mapbox context
+
+### `4.1` Evidence Panels
+
+### Card Identity
+
+- **Card ID:** `EC-4-1-01`
+- **Title:** `Build Evidence Panel Composer`
+- **Phase/Part:** `4.1`
+- **Status:** `DONE`
+
+### Objective (1 sentence)
+
+Generate a deterministic evidence panel from imagery, candidate, and metadata that can be reused for both inference and training.
+
+### Scope Guardrails
+
+- **In scope:** image panel layout, metadata block, panel file output
+- **Out of scope:** model inference
+- **Do not change:** frozen panel contract once accepted
+
+### Verification
+
+- Acceptance criteria:
+  - [x] Panel renders for one positive fixture
+  - [x] Panel renders for one negative fixture
+  - [x] Panel metadata includes required fields
+
+### 17.4 Immediate Planning-to-Build Handoff
+
+The very first implementation wave should stop only after this mini-checklist is true:
+
+- `Incident` schema frozen
+- golden fixture matrix frozen
+- demo-site selection rubric frozen
+- site registry running
+- live and cached SimSat retrieval working
+- first candidate object emitted
+- first evidence panel rendered
+
+At that point the plan has successfully crossed from architecture into working software.
+
+---
+
+## 18) Execution Card Template (Embedded)
+
+### Card Identity
+
+- **Card ID:** `EC-<phase>-<part>-<task>`
+- **Title:** `<short action title>`
+- **Phase/Part:** `<e.g., 2.2>`
+- **Status:** `TODO | WIP | BLOCKED | DONE`
+
+### Objective (1 sentence)
+
+Describe exactly what must be true when this card is done.
+
+### Scope Guardrails
+
+- **In scope:**
+- **Out of scope:**
+- **Do not change:**
+
+### Inputs
+
+- Files/docs to read first:
+- Assumptions:
+- Dependencies/preconditions:
+
+### Allowed File Changes
+
+- `path/to/file1`
+- `path/to/file2`
+
+### Planned Output
+
+- Expected code/artifact result:
+- User-visible behavior/result:
+
+### Verification
+
+- Required checks (tests/lint/typecheck/run path):
+- Acceptance criteria:
+  - [ ] Criteria 1
+  - [ ] Criteria 2
+
+### Integration Check
+
+- Previous phase dependency verified:
+- Live path verified:
+- Cached path verified:
+
+### Timebox & Control
+
+- **Started at:**
+- **Checkpoint at (+25 min):**
+- **Hard stop at (+45 min):**
+- **If not done by hard stop:** `split card | mark blocked`
+
+### Execution Log
+
+- **Attempt 1:**
+  - Summary:
+  - Files changed:
+  - Verification result:
+  - Outcome: `continue | done | blocked`
+
+### Completion
+
+- **Ended at:**
+- **Elapsed (minutes):**
+- **Final status:** `DONE | BLOCKED | SPLIT`
+
+---
+
+## 19) Final Usage Pattern (Single File)
+
+1. Use this file as the canonical planning artifact.
+2. Treat sections `0-17` as the strategy-and-execution baseline.
+3. Use section `17` to start work immediately.
+4. Add more execution cards under section `18` as implementation expands.
+5. Update the progress tracker after each completed phase or major card.
+6. Update the change log after every meaningful planning or implementation milestone.
+7. Treat integration checkpoints as hard gates, not advisory notes.