diff --git a/apps/field/package-lock.json b/apps/field/package-lock.json
index b0c5757..3875eb5 100644
--- a/apps/field/package-lock.json
+++ b/apps/field/package-lock.json
@@ -10,7 +10,6 @@
       "dependencies": {
         "@quasar/cli": "^3.0.0",
         "@quasar/extras": "^1.16.12",
-        "html5-qrcode": "^2.3.8",
         "idb-keyval": "^6.2.1",
         "pinia": "^2.1.7",
         "quasar": "^2.16.10",
@@ -6580,12 +6579,6 @@
         "node": "^14.13.1 || >=16.0.0"
       }
     },
-    "node_modules/html5-qrcode": {
-      "version": "2.3.8",
-      "resolved": "https://registry.npmjs.org/html5-qrcode/-/html5-qrcode-2.3.8.tgz",
-      "integrity": "sha512-jsr4vafJhwoLVEDW3n1KvPnCCXWaQfRng0/EEYk1vNcQGcG/htAdhJX0be8YyqMoSz7+hZvOZSTAepsabiuhiQ==",
-      "license": "Apache-2.0"
-    },
     "node_modules/http-errors": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
diff --git a/apps/field/package.json b/apps/field/package.json
index 10b73e6..e210bbe 100644
--- a/apps/field/package.json
+++ b/apps/field/package.json
@@ -12,7 +12,6 @@
   "dependencies": {
     "@quasar/cli": "^3.0.0",
     "@quasar/extras": "^1.16.12",
-    "html5-qrcode": "^2.3.8",
     "idb-keyval": "^6.2.1",
     "pinia": "^2.1.7",
     "quasar": "^2.16.10",
diff --git a/apps/field/src/composables/useScanner.js b/apps/field/src/composables/useScanner.js
index 5f79bf9..d2c1ab8 100644
--- a/apps/field/src/composables/useScanner.js
+++ b/apps/field/src/composables/useScanner.js
@@ -2,61 +2,43 @@ import { ref, watch } from 'vue'
 import { scanBarcodes } from 'src/api/ocr'
 import { useOfflineStore } from 'src/stores/offline'
 
-const GEMINI_TIMEOUT_MS = 8000
-const MAX_CODES = 3
+const SCAN_TIMEOUT_MS = 8000
 
 /**
- * Hybrid barcode scanner for field techs.
+ * Barcode scanner using device camera photo capture + Gemini Vision AI.
  *
- * Three modes, all writing into the same `barcodes` array (max 3):
+ * Strategy: Use <input type="file" capture="environment"> which triggers
+ * the native camera app — this gives proper autofocus, tap-to-focus,
+ * and high-res photos. Then send to Gemini Vision for barcode extraction.
  *
- *   1. `startLive(elId)` — continuous camera stream via html5-qrcode.
- *      Instant, offline-capable, works for standard QR / Code128 / EAN.
- *      This is the DEFAULT and fastest path.
- *
- *   2. `processPhoto(file)` — take a picture, scan it for codes.
- *      Tries html5-qrcode locally first (full image + 3 horizontal strips,
- *      catches up to 3 barcodes per photo, offline). If nothing is found
- *      AND we're online, falls back to Gemini Vision which can read weird
- *      stuff html5-qrcode misses: damaged stickers, multi-line serials
- *      printed as text, unusual barcode symbologies.
- *      If Gemini times out on weak LTE, the photo is queued in IndexedDB
- *      and retried when signal returns — late results come back through
- *      `onNewCode` via the watcher on offline.scanResults.
- *
- *   3. Manual entry — handled by the caller, just appends via addCode().
- *
- * This was rewritten in 2026-04-22 after an earlier refactor replaced all
- * local scanning with Gemini-only. Live camera matters for field techs:
- * point-and-scan is 10× faster than take-photo-wait-for-AI on a normal QR.
- * Gemini is kept as a second chance for the hard cases.
+ * Resilience: if Gemini doesn't answer within SCAN_TIMEOUT_MS (weak LTE),
+ * the photo is queued in IndexedDB via the offline store and retried when
+ * the signal comes back. The tech gets a "scan en attente" indicator and
+ * can keep working; late results are delivered via onNewCode().
  *
  * @param {object} options
- * @param {(code: string) => void} [options.onNewCode] — fires for each
- *   newly added code whether it came from live, photo, queue, or manual.
- *   Typically used to trigger lookup + toast.
+ * @param {(code: string) => void} [options.onNewCode] — called for each
+ *   newly detected code, whether the scan was synchronous or delivered
+ *   later from the offline queue. Typically used to trigger lookup + notify.
  */
 export function useScanner (options = {}) {
   const onNewCode = options.onNewCode || (() => {})
-  const barcodes = ref([])        // [{ value, region }], max MAX_CODES
-  const scanning = ref(false)     // true while a photo/AI call is in-flight
-  const live = ref(false)         // true while the live camera is running
+  const barcodes = ref([])        // Array of { value, region } — max 3
+  const scanning = ref(false)     // true while Gemini is processing
   const error = ref(null)
-  const lastPhoto = ref(null)     // thumbnail data URI
-  const photos = ref([])          // [{ url, ts, codes, queued }]
+  const lastPhoto = ref(null)     // data URI of last captured photo (thumbnail)
+  const photos = ref([])          // all captured photo thumbnails
 
   const offline = useOfflineStore()
-  let _html5 = null               // Html5Qrcode instance for live mode
 
-  // Pick up any Gemini scans that completed while the page was unmounted
-  // (tech queued a photo, locked phone, walked out of the basement, signal
-  // returned, hub replied, we stored the result in IndexedDB).
+  // Pick up any scans that completed while the page was unmounted (e.g. tech
+  // queued a photo, locked phone, walked out of the basement, signal returns).
   for (const result of offline.scanResults) {
     mergeCodes(result.barcodes || [], 'queued')
     offline.consumeScanResult(result.id)
   }
 
-  // Watch for sync completions during this scanner's lifetime.
+  // Watch for sync completions during the lifetime of this scanner.
   // Vue auto-disposes the watcher when the host component unmounts.
   watch(
     () => offline.scanResults.length,
@@ -69,12 +51,10 @@ export function useScanner (options = {}) {
   )
 
   function addCode (code, region) {
-    const trimmed = String(code || '').trim()
-    if (!trimmed) return false
-    if (barcodes.value.length >= MAX_CODES) return false
-    if (barcodes.value.find(b => b.value === trimmed)) return false
-    barcodes.value.push({ value: trimmed, region })
-    onNewCode(trimmed)
+    if (barcodes.value.length >= 3) return false
+    if (barcodes.value.find(b => b.value === code)) return false
+    barcodes.value.push({ value: code, region })
+    onNewCode(code)
     return true
   }
 
@@ -86,109 +66,44 @@ export function useScanner (options = {}) {
     return added
   }
 
-  // -------------------------------------------------------------------------
-  // 1. Live camera — html5-qrcode continuous stream
-  // -------------------------------------------------------------------------
-
-  /**
-   * Start the live scanner in the given DOM element.
-   * Safe to call again after stopLive() — recreates the instance.
-   *
-   * @param {string} elementId — id of a div to mount the camera view into.
-   *                             Must already be in the DOM when this is called.
-   */
-  async function startLive (elementId) {
-    if (live.value) return
-    error.value = null
-    try {
-      const { Html5Qrcode } = await import('html5-qrcode')
-      _html5 = new Html5Qrcode(elementId, { verbose: false })
-      await _html5.start(
-        { facingMode: 'environment' },
-        {
-          fps: 10,
-          // Wider aimbox so tech doesn't have to line up perfectly.
-          qrbox: (w, h) => {
-            const side = Math.floor(Math.min(w, h) * 0.7)
-            return { width: side, height: Math.floor(side * 0.6) }
-          },
-        },
-        (decoded) => addCode(decoded, 'caméra'),
-        () => { /* per-frame decode miss — ignore, this is noisy by design */ },
-      )
-      live.value = true
-    } catch (e) {
-      error.value = e?.message || 'Caméra non disponible'
-      live.value = false
-      _html5 = null
-    }
-  }
-
-  async function stopLive () {
-    try {
-      if (_html5?.isScanning) await _html5.stop()
-      _html5?.clear()
-    } catch { /* ignore — teardown races are fine */ }
-    _html5 = null
-    live.value = false
-  }
-
-  // -------------------------------------------------------------------------
-  // 2. Photo scan — html5-qrcode multi-strip, Gemini fallback
-  // -------------------------------------------------------------------------
-
   /**
    * Process a photo file from camera input.
-   *
-   * Pass 1: html5-qrcode on the full image (cheap, offline).
-   * Pass 2: split into 3 horizontal strips, scan each — catches stickers
-   *          that contain multiple barcodes stacked vertically (common on
-   *          modems: SN, MAC, GPON SN each on their own line).
-   * Pass 3: if still empty AND online, send to Gemini for OCR-based read.
-   *          If Gemini times out (weak signal), queue for background retry.
+   * Resizes for AI, keeps thumbnail, sends to Gemini with an 8s timeout.
+   * On timeout/failure, the photo is queued for background retry.
    */
   async function processPhoto (file) {
     if (!file) return []
     error.value = null
     scanning.value = true
 
-    const found = []
-    const photoIdx = photos.value.length
     let aiImage = null
+    const photoIdx = photos.value.length
+    let found = []
 
     try {
-      // Thumbnail for the UI
+      // Create thumbnail for display (small)
       const thumbUrl = await resizeImage(file, 400)
       lastPhoto.value = thumbUrl
       photos.value.push({ url: thumbUrl, ts: Date.now(), codes: [], queued: false })
 
-      // --- Pass 1 + 2: local html5-qrcode on full image + strips ---
-      const localCodes = await scanPhotoLocally(file)
-      found.push(...mergeCodes(localCodes, 'photo'))
+      // Create optimized image for AI — keep high res for text readability
+      aiImage = await resizeImage(file, 1600, 0.92)
+
+      const result = await scanBarcodesWithTimeout(aiImage, SCAN_TIMEOUT_MS)
+      found = mergeCodes(result.barcodes || [], 'photo')
+      photos.value[photoIdx].codes = found
 
-      // --- Pass 3: Gemini fallback if local scan came up empty ---
       if (found.length === 0) {
-        aiImage = await resizeImage(file, 1600, 0.92)
-        try {
-          const result = await scanBarcodesWithTimeout(aiImage, GEMINI_TIMEOUT_MS)
-          found.push(...mergeCodes(result.barcodes || [], 'IA'))
-        } catch (e) {
-          if (isRetryable(e)) {
-            await offline.enqueueVisionScan({ image: aiImage })
-            if (photos.value[photoIdx]) photos.value[photoIdx].queued = true
-            error.value = 'Réseau faible — scan en attente. Reprise automatique au retour du signal.'
-          } else {
-            throw e
-          }
-        }
-      }
-
-      if (photos.value[photoIdx]) photos.value[photoIdx].codes = found
-      if (found.length === 0 && !error.value) {
         error.value = 'Aucun code détecté — rapprochez-vous ou améliorez la mise au point'
       }
     } catch (e) {
-      error.value = e?.message || 'Erreur'
+      if (aiImage && isRetryable(e)) {
+        await offline.enqueueVisionScan({ image: aiImage })
+        if (photos.value[photoIdx]) photos.value[photoIdx].queued = true
+        error.value = 'Réseau faible — scan en attente. Reprise automatique au retour du signal.'
+      } else {
+        error.value = e.message || 'Erreur'
+      }
     } finally {
       scanning.value = false
     }
@@ -196,69 +111,6 @@ export function useScanner (options = {}) {
     return found
   }
 
-  /**
-   * Local pass: html5-qrcode on full image + 3 horizontal strips.
-   * Returns an array of unique decoded strings. Always safe to call —
-   * errors at any stage are swallowed and produce an empty result.
-   */
-  async function scanPhotoLocally (file) {
-    const found = new Set()
-    let scratch = document.getElementById('scanner-scratch')
-    if (!scratch) {
-      scratch = document.createElement('div')
-      scratch.id = 'scanner-scratch'
-      scratch.style.display = 'none'
-      document.body.appendChild(scratch)
-    }
-
-    let scanner
-    try {
-      const { Html5Qrcode } = await import('html5-qrcode')
-      scanner = new Html5Qrcode('scanner-scratch', { verbose: false })
-
-      // Full image first
-      try {
-        const r = await scanner.scanFileV2(file, false)
-        if (r?.decodedText) found.add(r.decodedText)
-      } catch { /* no code on full image — try strips */ }
-
-      // Split into 3 strips and scan each — only if we still have room
-      if (found.size < MAX_CODES) {
-        const img = await createImageBitmap(file)
-        try {
-          const { width, height } = img
-          const strips = [
-            { y: 0, h: Math.floor(height / 3), label: 'haut' },
-            { y: Math.floor(height / 3), h: Math.floor(height / 3), label: 'milieu' },
-            { y: Math.floor(height * 2 / 3), h: height - Math.floor(height * 2 / 3), label: 'bas' },
-          ]
-          const canvas = document.createElement('canvas')
-          const ctx = canvas.getContext('2d')
-
-          for (const strip of strips) {
-            if (found.size >= MAX_CODES) break
-            canvas.width = width
-            canvas.height = strip.h
-            ctx.drawImage(img, 0, strip.y, width, strip.h, 0, 0, width, strip.h)
-            try {
-              const blob = await new Promise(r => canvas.toBlob(r, 'image/jpeg', 0.9))
-              const stripFile = new File([blob], 'strip.jpg', { type: 'image/jpeg' })
-              const r = await scanner.scanFileV2(stripFile, false)
-              if (r?.decodedText) found.add(r.decodedText)
-            } catch { /* strip miss — continue */ }
-          }
-        } finally {
-          img.close()
-        }
-      }
-    } catch { /* library load / instantiation failure — caller falls back to Gemini */ }
-    finally {
-      try { scanner?.clear() } catch { /* ignore */ }
-    }
-
-    return Array.from(found)
-  }
-
   async function scanBarcodesWithTimeout (image, ms) {
     return await Promise.race([
       scanBarcodes(image),
@@ -278,11 +130,9 @@ export function useScanner (options = {}) {
       || e?.name === 'TypeError'  // fetch throws TypeError on network error
   }
 
-  // -------------------------------------------------------------------------
-  // Utilities
-  // -------------------------------------------------------------------------
-
-  /** Resize an image file to a max dimension, return as base64 data URI. */
+  /**
+   * Resize an image file to a max dimension, return as base64 data URI.
+   */
   function resizeImage (file, maxDim, quality = 0.85) {
     return new Promise((resolve, reject) => {
       const img = new Image()
@@ -316,15 +166,7 @@ export function useScanner (options = {}) {
   }
 
   return {
-    // state
-    barcodes, scanning, live, error, lastPhoto, photos,
-    // live camera
-    startLive, stopLive,
-    // photo scan
-    processPhoto,
-    // shared
-    addCode, removeBarcode, clearBarcodes,
-    // constants
-    MAX_CODES,
+    barcodes, scanning, error, lastPhoto, photos,
+    processPhoto, removeBarcode, clearBarcodes,
   }
 }
diff --git a/apps/field/src/pages/ScanPage.vue b/apps/field/src/pages/ScanPage.vue
index 1092b0c..107ba65 100644
--- a/apps/field/src/pages/ScanPage.vue
+++ b/apps/field/src/pages/ScanPage.vue
@@ -17,99 +17,55 @@
       </q-card-section>
     </q-card>
 
-    <!-- Mode tabs: Caméra / Photo IA / Manuel -->
-    <q-tabs v-model="mode" dense no-caps active-color="primary" indicator-color="primary" align="justify"
-      class="q-mb-md" @update:model-value="onModeChange">
-      <q-tab name="live" icon="videocam" label="Caméra" />
-      <q-tab name="photo" icon="photo_camera" label="Photo" />
-      <q-tab name="manual" icon="keyboard" label="Manuel" />
-    </q-tabs>
-
-    <!-- ==== Live camera mode (default, fastest) ==== -->
-    <div v-show="mode === 'live'" class="live-wrap">
-      <div id="live-reader" class="live-reader" />
-      <div class="text-center q-mt-sm">
-        <q-btn v-if="!scanner.live.value" color="primary" icon="play_arrow"
-          label="Démarrer la caméra" @click="startLive" unelevated />
-        <q-btn v-else color="negative" icon="stop" label="Arrêter" @click="scanner.stopLive()" outline />
-      </div>
-      <div v-if="scanner.live.value" class="text-caption text-center text-grey q-mt-xs">
-        Cadrez un code-barres — détection automatique
-      </div>
-    </div>
-
-    <!-- ==== Photo mode (native camera + local scan + Gemini fallback) ==== -->
-    <div v-show="mode === 'photo'" class="text-center">
+    <!-- Camera capture button -->
+    <div class="text-center">
       <q-btn
-        color="primary" icon="photo_camera" label="Prendre une photo"
+        color="primary" icon="photo_camera" label="Scanner"
         size="lg" rounded unelevated
         @click="takePhoto"
         :loading="scanner.scanning.value"
         class="q-px-xl"
       />
       <input ref="cameraInput" type="file" accept="image/*" capture="environment" class="hidden" @change="onPhoto" />
-      <div class="text-caption text-grey q-mt-sm">
-        Jusqu'à 3 codes par photo · IA activée si la lecture locale échoue
-      </div>
+    </div>
 
-      <!-- Pending scan indicator (signal faible) -->
-      <div v-if="offline.pendingVisionCount > 0" class="text-center q-mt-sm">
-        <q-chip icon="wifi_tethering_off" color="orange" text-color="white" dense clickable
-          @click="offline.syncVisionQueue()">
-          {{ offline.pendingVisionCount }} scan{{ offline.pendingVisionCount > 1 ? 's' : '' }}
-          en attente · toucher pour réessayer
-        </q-chip>
-      </div>
+    <!-- Pending scan indicator (signal faible) -->
+    <div v-if="offline.pendingVisionCount > 0" class="text-center q-mt-sm">
+      <q-chip icon="wifi_tethering_off" color="orange" text-color="white" dense clickable @click="offline.syncVisionQueue()">
+        {{ offline.pendingVisionCount }} scan{{ offline.pendingVisionCount > 1 ? 's' : '' }} en attente · toucher pour réessayer
+      </q-chip>
+    </div>
 
-      <!-- Last captured photo (thumbnail) -->
-      <div v-if="scanner.lastPhoto.value" class="photo-preview q-mt-md">
-        <img :src="scanner.lastPhoto.value" class="preview-img" @click="showFullPhoto = true" />
-        <div v-if="scanner.scanning.value" class="preview-overlay">
-          <q-spinner-dots size="32px" color="white" />
-          <div class="text-white text-caption q-mt-xs">Analyse...</div>
-        </div>
-      </div>
-
-      <!-- Photo history (small thumbnails) -->
-      <div v-if="scanner.photos.value.length > 1" class="q-mt-md">
-        <div class="text-caption text-grey q-mb-xs">Photos capturées</div>
-        <div class="row q-gutter-xs">
-          <div v-for="(p, i) in scanner.photos.value" :key="i" class="photo-thumb" @click="viewPhoto(p)">
-            <img :src="p.url" />
-            <q-badge v-if="p.codes.length" color="green" floating :label="p.codes.length" />
-          </div>
-        </div>
+    <!-- Last captured photo (thumbnail) -->
+    <div v-if="scanner.lastPhoto.value" class="photo-preview q-mt-md">
+      <img :src="scanner.lastPhoto.value" class="preview-img" @click="showFullPhoto = true" />
+      <div v-if="scanner.scanning.value" class="preview-overlay">
+        <q-spinner-dots size="32px" color="white" />
+        <div class="text-white text-caption q-mt-xs">Analyse Gemini...</div>
       </div>
     </div>
 
-    <!-- ==== Manual entry ==== -->
-    <div v-show="mode === 'manual'">
-      <q-input v-model="manualCode" label="Saisie manuelle SN / MAC / code-barres"
-        outlined dense autofocus @keyup.enter="addManual">
-        <template v-slot:prepend><q-icon name="keyboard" /></template>
-        <template v-slot:append>
-          <q-btn flat dense icon="add" :disable="!manualCode.trim()" @click="addManual" />
-        </template>
-      </q-input>
-    </div>
-
-    <!-- ==== Error / status (all modes) ==== -->
+    <!-- Error / status -->
     <div v-if="scanner.error.value" class="text-caption text-center q-mt-sm text-negative">
       {{ scanner.error.value }}
     </div>
 
-    <!-- ==== Scanned barcodes (shared across all modes) ==== -->
+    <!-- Manual entry -->
+    <q-input v-model="manualCode" label="Saisie manuelle SN / MAC" outlined dense class="q-mt-md"
+      @keyup.enter="addManual">
+      <template v-slot:append>
+        <q-btn flat dense icon="add" @click="addManual" :disable="!manualCode.trim()" />
+      </template>
+    </q-input>
+
+    <!-- Scanned barcodes -->
     <div v-if="scanner.barcodes.value.length > 0" class="q-mt-md">
-      <div class="row items-center q-mb-xs">
-        <div class="text-subtitle2 col">Codes détectés ({{ scanner.barcodes.value.length }}/{{ scanner.MAX_CODES }})</div>
-        <q-btn flat dense size="sm" icon="clear_all" label="Effacer" @click="scanner.clearBarcodes()" />
-      </div>
+      <div class="text-subtitle2 q-mb-xs">Codes détectés ({{ scanner.barcodes.value.length }}/3)</div>
       <q-card v-for="bc in scanner.barcodes.value" :key="bc.value" class="q-mb-sm">
         <q-card-section class="q-py-sm row items-center no-wrap">
           <q-icon name="qr_code" class="q-mr-sm" color="primary" />
           <div class="col">
             <div class="text-subtitle2 mono">{{ bc.value }}</div>
-            <div class="text-caption text-grey">{{ bc.region }}</div>
           </div>
           <q-btn flat dense icon="search" @click="lookupDevice(bc.value)" :loading="lookingUp === bc.value" />
           <q-btn flat dense icon="close" color="negative" @click="scanner.removeBarcode(bc.value)" />
@@ -130,7 +86,7 @@
               <q-btn flat dense size="sm" color="orange" label="Lier à un service" icon="link"
                 @click="openLinkDialog(bc.value, lookupResults[bc.value].equipment)" />
             </div>
-            <div v-else-if="lookupResults[bc.value].equipment.service_location" class="text-caption text-green q-mt-xs">
+            <div v-else class="text-caption text-green q-mt-xs">
               <q-icon name="check_circle" size="xs" class="q-mr-xs" />
               {{ lookupResults[bc.value].equipment.service_location }}
             </div>
@@ -146,6 +102,17 @@
       </q-card>
     </div>
 
+    <!-- Photo history (small thumbnails) -->
+    <div v-if="scanner.photos.value.length > 1" class="q-mt-md">
+      <div class="text-caption text-grey q-mb-xs">Photos capturées</div>
+      <div class="row q-gutter-xs">
+        <div v-for="(p, i) in scanner.photos.value" :key="i" class="photo-thumb" @click="viewPhoto(p)">
+          <img :src="p.url" />
+          <q-badge v-if="p.codes.length" color="green" floating :label="p.codes.length" />
+        </div>
+      </div>
+    </div>
+
     <!-- Link all to account (manual, when no job context) -->
     <div v-if="scanner.barcodes.value.length > 0 && !jobContext && hasUnlinked" class="q-mt-sm">
       <q-btn color="orange" icon="link" label="Lier les équipements à un service"
@@ -235,7 +202,7 @@
 </template>
 
 <script setup>
-import { ref, computed, onBeforeUnmount, nextTick } from 'vue'
+import { ref, computed } from 'vue'
 import { useRoute } from 'vue-router'
 import { useScanner } from 'src/composables/useScanner'
 import { listDocs, createDoc, updateDoc } from 'src/api/erp'
@@ -251,8 +218,6 @@ const scanner = useScanner({
   },
 })
 
-// Default to live camera — that's what techs use 90% of the time.
-const mode = ref('live')
 const cameraInput = ref(null)
 const manualCode = ref('')
 const lookingUp = ref(null)
@@ -293,30 +258,10 @@ const hasUnlinked = computed(() =>
   })
 )
 
-// --- Mode switch: stop the camera when leaving Live, pause auto-restart ---
-
-function onModeChange (newMode) {
-  if (newMode !== 'live' && scanner.live.value) scanner.stopLive()
-}
-
-// Make sure we don't leak the camera when the page unmounts.
-onBeforeUnmount(() => {
-  if (scanner.live.value) scanner.stopLive()
-})
-
-// --- Live camera ---
-
-async function startLive () {
-  // The reader element is inside v-show — it's in the DOM from first render.
-  // nextTick just in case something upstream hid it.
-  await nextTick()
-  await scanner.startLive('live-reader')
-}
-
-// --- Photo camera ---
+// --- Camera ---
 
 function takePhoto () {
-  // Reset the input so the same file triggers change
+  // Reset the input so same file triggers change
   if (cameraInput.value) cameraInput.value.value = ''
   cameraInput.value?.click()
 }
@@ -340,16 +285,15 @@ function viewPhoto (photo) {
 function addManual () {
   const code = manualCode.value.trim()
   if (!code) return
-  if (scanner.barcodes.value.length >= scanner.MAX_CODES) {
-    Notify.create({ type: 'warning', message: `Maximum ${scanner.MAX_CODES} codes` })
+  if (scanner.barcodes.value.length >= 3) {
+    Notify.create({ type: 'warning', message: 'Maximum 3 codes' })
     return
   }
-  if (scanner.addCode(code, 'manuel')) {
-    manualCode.value = ''
-  } else {
-    Notify.create({ type: 'info', message: 'Code déjà ajouté' })
-    manualCode.value = ''
+  if (!scanner.barcodes.value.find(b => b.value === code)) {
+    scanner.barcodes.value.push({ value: code, region: 'manuel' })
+    lookupDevice(code)
   }
+  manualCode.value = ''
 }
 
 // --- Device lookup ---
@@ -552,25 +496,6 @@ async function linkDeviceToService () {
   padding-bottom: 16px !important;
 }
 
-.live-wrap {
-  max-width: 420px;
-  margin: 0 auto;
-}
-
-.live-reader {
-  width: 100%;
-  min-height: 280px;
-  border-radius: 12px;
-  overflow: hidden;
-  background: #000;
-  // html5-qrcode injects a <video> — make it fill the container
-  :deep(video) {
-    width: 100% !important;
-    height: auto !important;
-    display: block;
-  }
-}
-
 .photo-preview {
   position: relative;
   text-align: center;
@@ -607,8 +532,4 @@ async function linkDeviceToService () {
     object-fit: cover;
   }
 }
-
-.mono {
-  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
-}
 </style>
diff --git a/apps/ops/package-lock.json b/apps/ops/package-lock.json
index 243c622..0827aa2 100644
--- a/apps/ops/package-lock.json
+++ b/apps/ops/package-lock.json
@@ -12,7 +12,6 @@
         "@twilio/voice-sdk": "^2.18.1",
         "chart.js": "^4.5.1",
         "cytoscape": "^3.33.2",
-        "html5-qrcode": "^2.3.8",
         "idb-keyval": "^6.2.1",
         "lucide-vue-next": "^1.0.0",
         "pinia": "^2.1.7",
@@ -5894,12 +5893,6 @@
         "node": "^14.13.1 || >=16.0.0"
       }
     },
-    "node_modules/html5-qrcode": {
-      "version": "2.3.8",
-      "resolved": "https://registry.npmjs.org/html5-qrcode/-/html5-qrcode-2.3.8.tgz",
-      "integrity": "sha512-jsr4vafJhwoLVEDW3n1KvPnCCXWaQfRng0/EEYk1vNcQGcG/htAdhJX0be8YyqMoSz7+hZvOZSTAepsabiuhiQ==",
-      "license": "Apache-2.0"
-    },
     "node_modules/http-errors": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz",
diff --git a/apps/ops/package.json b/apps/ops/package.json
index 47fa35f..a246eb1 100644
--- a/apps/ops/package.json
+++ b/apps/ops/package.json
@@ -14,7 +14,6 @@
     "@twilio/voice-sdk": "^2.18.1",
     "chart.js": "^4.5.1",
     "cytoscape": "^3.33.2",
-    "html5-qrcode": "^2.3.8",
     "idb-keyval": "^6.2.1",
     "lucide-vue-next": "^1.0.0",
     "pinia": "^2.1.7",
diff --git a/apps/ops/src/composables/useScanner.js b/apps/ops/src/composables/useScanner.js
index f4831a6..e1beb6b 100644
--- a/apps/ops/src/composables/useScanner.js
+++ b/apps/ops/src/composables/useScanner.js
@@ -1,45 +1,37 @@
 /**
- * useScanner — hybrid camera + barcode composable for field techs.
+ * useScanner — camera-capture + Gemini Vision composable.
  *
- * Three capture modes, one shared `barcodes` array:
+ * Two capture modes, one pipeline:
+ *   - processPhoto(file)         → barcode/serial extraction    (ScanPage, /j)
+ *   - scanEquipmentLabel(file)   → structured ONT/ONU label     (equipment
+ *                                    linking, ClientDetailPage photos)
  *
- *   1. Live camera (startLive / stopLive)
- *      html5-qrcode continuous stream. INSTANT, OFFLINE, and the fastest
- *      path for normal QR codes on modem stickers. This is the default on
- *      the /j/scan page — techs point, scan, done.
+ * Both resize the photo twice:
+ *   - 400px  for the on-screen thumbnail
+ *   - 1600px @ q=0.92 for Gemini (text readability > filesize)
  *
- *   2. Photo scan (processPhoto)
- *      Take a picture with the native camera, then:
- *        Pass 1 — html5-qrcode on the full image (cheap, offline)
- *        Pass 2 — split into 3 horizontal strips, scan each — catches up
- *                 to 3 stacked barcodes on a single sticker (SN + MAC +
- *                 GPON SN is a common layout)
- *        Pass 3 — if still empty AND online, fall back to Gemini Vision
- *                 which can read damaged stickers, multi-line text-only
- *                 serials, and unusual symbologies
- *        If Gemini times out on weak LTE, photo is queued in IndexedDB
- *        via the offline store. Late results come back through
- *        `onNewCode` via the watcher on offline.scanResults.
+ * Resilience (barcode mode only):
+ *   If Gemini doesn't answer within SCAN_TIMEOUT_MS (weak LTE, basement,
+ *   service cold-start), the photo is queued in IndexedDB via the offline
+ *   store and retried in the background. The tech sees a "scan en attente"
+ *   chip, keeps scanning the next equipment, and the late result is pushed
+ *   back into `barcodes` via a reactive watcher on `offline.scanResults`.
  *
- *   3. Equipment label scan (scanEquipmentLabel)
- *      Dedicated Gemini-only path for structured ONT/ONU label OCR.
- *      Used from ClientDetailPage/equipment-linking flows where the caller
- *      wants a sync answer ({brand, model, serial, mac, gpon_sn, ...}) —
- *      not resilient, no queue, desktop/wifi only.
+ * Equipment-label mode does NOT queue — it's typically invoked on a desktop
+ * or strong wifi (indoor install, office) where the extra complexity of
+ * background retry isn't worth it, and callers want a synchronous answer
+ * (to pre-fill an equipment form).
  *
- * History: this file originally lived in apps/field. In 2026-04-22 the
- * field scanner was briefly replaced with Gemini-only capture, losing
- * the live camera. This version restores live + multi-strip as the fast
- * primary path and keeps Gemini as a second-chance fallback.
- *
- * See docs/architecture/overview.md §"Legacy Retirement Plan" — apps/field
- * is being folded into apps/ops at /j and must not lose offline capability
- * or live scanning in the process.
+ * Merged from apps/ops/src/composables/useScanner.js (which had the
+ * equipment-label branch) and apps/field/src/composables/useScanner.js
+ * (which had the resilient timeout + offline queue). See
+ * docs/ARCHITECTURE.md §"Legacy Retirement Plan" — field is being folded
+ * into ops at /j and must not lose offline capability in the process.
  *
  * @param {object} options
  * @param {(code: string) => void} [options.onNewCode] — fires for each
- *   newly added code. Fires for live scans, photo scans, queued retries,
- *   and equipment-label scans. Typical use: trigger an ERPNext lookup
+ *   newly detected code, whether the scan was synchronous OR delivered
+ *   later from the offline queue. Typical use: trigger an ERPNext lookup
  *   and Quasar notify.
  */
 
@@ -47,25 +39,27 @@ import { ref, watch } from 'vue'
 import { scanBarcodes, scanEquipmentLabel as apiScanEquipmentLabel } from 'src/api/ocr'
 import { useOfflineStore } from 'src/stores/offline'
 
-const GEMINI_TIMEOUT_MS = 8000
-const MAX_BARCODES = 5  // equipment labels have more identifiers than field cap of 3
+const SCAN_TIMEOUT_MS = 8000
 
 export function useScanner (options = {}) {
   const onNewCode = options.onNewCode || (() => {})
 
   const barcodes = ref([])       // { value, region }[] — max MAX_BARCODES
-  const scanning = ref(false)    // true while a photo/AI call is in flight
-  const live = ref(false)        // true while the live camera is running
+  const scanning = ref(false)    // true while a Gemini call is in flight
   const error = ref(null)
   const lastPhoto = ref(null)    // data URI of last thumbnail (400px)
   const photos = ref([])         // { url, ts, codes, queued }[] — full history
 
-  const offline = useOfflineStore()
-  let _html5 = null              // Html5Qrcode live instance
+  // Field's default cap was 3 (phone screen estate); ops historically
+  // allowed 5 (equipment labels have more identifiers). Keep 5 here
+  // since equipment-label mode is an ops-only feature.
+  const MAX_BARCODES = 5
 
-  // Pick up any Gemini scans that completed while the composable was unmounted
-  // (tech queued a photo in the basement, phone locked, signal returned while
-  // the page was gone, now they reopen ScanPage).
+  const offline = useOfflineStore()
+
+  // Pick up any scans that completed while the composable was unmounted
+  // (e.g. tech queued a photo in the basement, phone locked, signal
+  // returned while the page was gone, now they reopen ScanPage).
   for (const result of offline.scanResults) {
     mergeCodes(result.barcodes || [], 'queued')
     offline.consumeScanResult(result.id)
@@ -84,12 +78,10 @@ export function useScanner (options = {}) {
   )
 
   function addCode (code, region) {
-    const trimmed = String(code || '').trim()
-    if (!trimmed) return false
     if (barcodes.value.length >= MAX_BARCODES) return false
-    if (barcodes.value.find(b => b.value === trimmed)) return false
-    barcodes.value.push({ value: trimmed, region })
-    onNewCode(trimmed)
+    if (barcodes.value.find(b => b.value === code)) return false
+    barcodes.value.push({ value: code, region })
+    onNewCode(code)
     return true
   }
 
@@ -101,105 +93,42 @@ export function useScanner (options = {}) {
     return added
   }
 
-  // -------------------------------------------------------------------------
-  // 1. Live camera
-  // -------------------------------------------------------------------------
-
-  /**
-   * Start the live scanner in the given DOM element.
-   * Safe to call again after stopLive(). Element must exist in the DOM.
-   */
-  async function startLive (elementId) {
-    if (live.value) return
-    error.value = null
-    try {
-      const { Html5Qrcode } = await import('html5-qrcode')
-      _html5 = new Html5Qrcode(elementId, { verbose: false })
-      await _html5.start(
-        { facingMode: 'environment' },
-        {
-          fps: 10,
-          // Wider aimbox so tech doesn't have to line up perfectly.
-          qrbox: (w, h) => {
-            const side = Math.floor(Math.min(w, h) * 0.7)
-            return { width: side, height: Math.floor(side * 0.6) }
-          },
-        },
-        (decoded) => addCode(decoded, 'caméra'),
-        () => { /* per-frame decode miss — ignore, this is noisy by design */ },
-      )
-      live.value = true
-    } catch (e) {
-      error.value = e?.message || 'Caméra non disponible'
-      live.value = false
-      _html5 = null
-    }
-  }
-
-  async function stopLive () {
-    try {
-      if (_html5?.isScanning) await _html5.stop()
-      _html5?.clear()
-    } catch { /* ignore — teardown races are fine */ }
-    _html5 = null
-    live.value = false
-  }
-
-  // -------------------------------------------------------------------------
-  // 2. Photo scan — html5-qrcode local, Gemini fallback, offline queue
-  // -------------------------------------------------------------------------
-
   /**
    * Process a photo for generic barcode/serial extraction.
-   *
-   * Three-pass strategy:
-   *   1. html5-qrcode on full image (offline, fast)
-   *   2. html5-qrcode on 3 horizontal strips (multi-barcode)
-   *   3. Gemini Vision fallback if local found nothing AND we're online
-   *
-   * Resilient: if Gemini times out the photo is queued for retry.
+   * Resilient: on timeout/network error the photo is queued for retry.
    */
   async function processPhoto (file) {
     if (!file) return []
     error.value = null
     scanning.value = true
 
-    const found = []
-    const photoIdx = photos.value.length
     let aiImage = null
+    const photoIdx = photos.value.length
+    let found = []
 
     try {
       const thumbUrl = await resizeImage(file, 400)
       lastPhoto.value = thumbUrl
       photos.value.push({ url: thumbUrl, ts: Date.now(), codes: [], queued: false })
 
-      // --- Pass 1 + 2: local html5-qrcode on full image + strips ---
-      const localCodes = await scanPhotoLocally(file)
-      found.push(...mergeCodes(localCodes, 'photo'))
+      // Keep high-res for text readability (small serial fonts).
+      aiImage = await resizeImage(file, 1600, 0.92)
+
+      const result = await scanBarcodesWithTimeout(aiImage, SCAN_TIMEOUT_MS)
+      found = mergeCodes(result.barcodes || [], 'photo')
+      photos.value[photoIdx].codes = found
 
-      // --- Pass 3: Gemini fallback if local scan came up empty ---
       if (found.length === 0) {
-        aiImage = await resizeImage(file, 1600, 0.92)
-        try {
-          const result = await scanBarcodesWithTimeout(aiImage, GEMINI_TIMEOUT_MS)
-          found.push(...mergeCodes(result.barcodes || [], 'IA'))
-        } catch (e) {
-          if (isRetryable(e)) {
-            await offline.enqueueVisionScan({ image: aiImage })
-            if (photos.value[photoIdx]) photos.value[photoIdx].queued = true
-            error.value = 'Réseau faible — scan en attente. Reprise automatique au retour du signal.'
-          } else {
-            throw e
-          }
-        }
-      }
-
-      if (photos.value[photoIdx]) photos.value[photoIdx].codes = found
-      if (found.length === 0 && !error.value) {
         error.value = 'Aucun code détecté — rapprochez-vous ou améliorez la mise au point'
       }
     } catch (e) {
-      error.value = e?.message || 'Erreur'
+      if (aiImage && isRetryable(e)) {
+        await offline.enqueueVisionScan({ image: aiImage })
+        if (photos.value[photoIdx]) photos.value[photoIdx].queued = true
+        error.value = 'Réseau faible — scan en attente. Reprise automatique au retour du signal.'
+      } else {
+        error.value = e.message || 'Erreur'
+      }
     } finally {
       scanning.value = false
     }
@@ -207,72 +136,6 @@ export function useScanner (options = {}) {
     return found
   }
 
-  /**
-   * Local pass: html5-qrcode on full image + 3 horizontal strips.
-   * Returns unique decoded strings. All failures swallowed → empty array.
-   */
-  async function scanPhotoLocally (file) {
-    const found = new Set()
-    let scratch = document.getElementById('scanner-scratch')
-    if (!scratch) {
-      scratch = document.createElement('div')
-      scratch.id = 'scanner-scratch'
-      scratch.style.display = 'none'
-      document.body.appendChild(scratch)
-    }
-
-    let scanner
-    try {
-      const { Html5Qrcode } = await import('html5-qrcode')
-      scanner = new Html5Qrcode('scanner-scratch', { verbose: false })
-
-      // Full image first
-      try {
-        const r = await scanner.scanFileV2(file, false)
-        if (r?.decodedText) found.add(r.decodedText)
-      } catch { /* no code on full image — try strips */ }
-
-      // Split into 3 horizontal strips — catches stacked barcodes
-      if (found.size < MAX_BARCODES) {
-        const img = await createImageBitmap(file)
-        try {
-          const { width, height } = img
-          const strips = [
-            { y: 0, h: Math.floor(height / 3), label: 'haut' },
-            { y: Math.floor(height / 3), h: Math.floor(height / 3), label: 'milieu' },
-            { y: Math.floor(height * 2 / 3), h: height - Math.floor(height * 2 / 3), label: 'bas' },
-          ]
-          const canvas = document.createElement('canvas')
-          const ctx = canvas.getContext('2d')
-
-          for (const strip of strips) {
-            if (found.size >= MAX_BARCODES) break
-            canvas.width = width
-            canvas.height = strip.h
-            ctx.drawImage(img, 0, strip.y, width, strip.h, 0, 0, width, strip.h)
-            try {
-              const blob = await new Promise(r => canvas.toBlob(r, 'image/jpeg', 0.9))
-              const stripFile = new File([blob], 'strip.jpg', { type: 'image/jpeg' })
-              const r = await scanner.scanFileV2(stripFile, false)
-              if (r?.decodedText) found.add(r.decodedText)
-            } catch { /* strip miss — continue */ }
-          }
-        } finally {
-          img.close()
-        }
-      }
-    } catch { /* lib load / instantiation failure — caller falls back to Gemini */ }
-    finally {
-      try { scanner?.clear() } catch { /* ignore */ }
-    }
-
-    return Array.from(found)
-  }
-
-  // -------------------------------------------------------------------------
-  // 3. Equipment label scan (ops-only, desktop/wifi, structured Gemini output)
-  // -------------------------------------------------------------------------
-
   /**
    * Process a photo for structured equipment-label extraction.
    *
@@ -312,10 +175,7 @@ export function useScanner (options = {}) {
     }
   }
 
-  // -------------------------------------------------------------------------
-  // Utilities
-  // -------------------------------------------------------------------------
-
+  /** Race scanBarcodes against a timeout. Used only for barcode mode. */
   async function scanBarcodesWithTimeout (image, ms) {
     return await Promise.race([
       scanBarcodes(image),
@@ -326,6 +186,7 @@ export function useScanner (options = {}) {
     ])
   }
 
+  /** Retryable = worth queueing in IndexedDB for later. */
   function isRetryable (e) {
     const msg = (e?.message || '').toLowerCase()
     return msg.includes('scantimeout')
@@ -335,6 +196,7 @@ export function useScanner (options = {}) {
       || e?.name === 'TypeError'  // fetch throws TypeError on network error
   }
 
+  /** Resize a File to a max dimension, return as base64 data URI. */
   function resizeImage (file, maxDim, quality = 0.85) {
     return new Promise((resolve, reject) => {
       const img = new Image()
@@ -368,15 +230,7 @@ export function useScanner (options = {}) {
   }
 
   return {
-    // state
-    barcodes, scanning, live, error, lastPhoto, photos,
-    // live camera
-    startLive, stopLive,
-    // photo scans
-    processPhoto, scanEquipmentLabel,
-    // shared
-    addCode, removeBarcode, clearBarcodes,
-    // constants
-    MAX_BARCODES,
+    barcodes, scanning, error, lastPhoto, photos,
+    processPhoto, scanEquipmentLabel, removeBarcode, clearBarcodes,
   }
 }
diff --git a/apps/ops/src/modules/tech/pages/TechJobDetailPage.vue b/apps/ops/src/modules/tech/pages/TechJobDetailPage.vue
index 22ce8ad..b86f4eb 100644
--- a/apps/ops/src/modules/tech/pages/TechJobDetailPage.vue
+++ b/apps/ops/src/modules/tech/pages/TechJobDetailPage.vue
@@ -37,16 +37,31 @@
 
       <!-- Content -->
       <div class="job-content q-pa-md">
-        <!-- Info -->
+
+        <!-- Info card -->
         <q-card flat bordered class="q-mb-md">
           <q-card-section class="q-pb-none"><div class="text-overline text-grey-6">INFORMATIONS</div></q-card-section>
           <q-card-section>
-            <q-input v-model="job.subject" label="Sujet" outlined dense class="q-mb-sm" @blur="saveField('subject', job.subject)" />
+            <q-input v-model="job.subject" label="Sujet" outlined dense class="q-mb-sm"
+              @blur="saveField('subject', job.subject)" />
+
             <div class="row q-gutter-sm q-mb-sm">
-              <q-input v-model="job.scheduled_time" label="Heure" type="time" outlined dense class="col" @blur="saveField('scheduled_time', job.scheduled_time)" />
-              <q-input v-model="job.duration_h" label="Duree (h)" type="number" step="0.5" min="0.5" outlined dense class="col" @blur="saveField('duration_h', parseFloat(job.duration_h) || 1)" />
+              <q-select v-model="job.job_type" :options="jobTypes" label="Type" outlined dense
+                class="col" emit-value map-options @update:model-value="saveField('job_type', $event)" />
+              <q-select v-model="job.priority" :options="priorities" label="Priorité" outlined dense
+                class="col" emit-value map-options @update:model-value="saveField('priority', $event)" />
             </div>
-            <q-input v-model="job.description" label="Notes / Description" type="textarea" outlined dense autogrow rows="2" @blur="saveField('description', job.description)" />
+
+            <div class="row q-gutter-sm q-mb-sm">
+              <q-input v-model="job.scheduled_time" label="Heure" type="time" outlined dense class="col"
+                @blur="saveField('scheduled_time', job.scheduled_time)" />
+              <q-input v-model="displayDuration" label="Durée (h)" type="number" step="0.5" min="0.5" max="12"
+                outlined dense class="col"
+                @blur="saveField('duration_h', parseFloat(displayDuration) || 1)" />
+            </div>
+
+            <q-input v-model="job.description" label="Notes / Description" type="textarea" outlined dense
+              autogrow rows="2" @blur="saveField('description', job.description)" />
           </q-card-section>
         </q-card>
 
@@ -58,11 +73,15 @@
               <q-icon name="person" color="grey" class="q-mr-sm" />
               <span class="text-body2">{{ job.customer_name }}</span>
             </div>
-            <div v-if="job.service_location_name" class="row items-center q-mb-sm">
+            <div v-if="locationAddress" class="row items-center q-mb-sm">
               <q-icon name="place" color="grey" class="q-mr-sm" />
-              <span class="text-body2">{{ job.service_location_name }}</span>
+              <span class="text-body2">{{ locationAddress }}</span>
               <q-space />
-              <q-btn flat dense round icon="navigation" color="primary" @click="openGps" />
+              <q-btn flat dense round icon="navigation" color="primary" @click="openGps" title="Naviguer" />
+            </div>
+            <div v-if="locationDetail?.contact_name" class="text-caption text-grey">
+              Contact: {{ locationDetail.contact_name }}
+              <span v-if="locationDetail.contact_phone"> — {{ locationDetail.contact_phone }}</span>
             </div>
           </q-card-section>
         </q-card>
@@ -70,22 +89,111 @@
         <!-- Equipment -->
         <q-card flat bordered class="q-mb-md">
           <q-card-section class="q-pb-none row items-center">
-            <div class="text-overline text-grey-6 col">EQUIPEMENTS ({{ equipment.length }})</div>
-            <q-btn flat dense size="sm" icon="qr_code_scanner" color="primary" label="Scanner" @click="goScan" />
+            <div class="text-overline text-grey-6 col">ÉQUIPEMENTS ({{ equipment.length }})</div>
+            <q-btn flat dense size="sm" icon="add" color="primary" label="Ajouter" @click="addEquipmentMenu = true" />
           </q-card-section>
-          <q-list v-if="equipment.length" separator>
-            <q-item v-for="eq in equipment" :key="eq.name">
+          <q-card-section v-if="loadingEquip" class="text-center">
+            <q-spinner size="sm" />
+          </q-card-section>
+          <q-list v-else-if="equipment.length" separator>
+            <q-item v-for="eq in equipment" :key="eq.name" clickable
+              @click="$router.push({ name: 'tech-device', params: { serial: eq.serial_number } })">
               <q-item-section avatar>
-                <q-icon :name="eq.equipment_type === 'ONT' ? 'settings_input_hdmi' : eq.equipment_type === 'Routeur' ? 'wifi' : 'memory'" :color="eq.status === 'Actif' ? 'green' : 'grey'" />
+                <q-icon :name="eqIcon(eq.equipment_type)" :color="eqStatusColor(eq.status)" />
               </q-item-section>
               <q-item-section>
                 <q-item-label>{{ eq.equipment_type }} — {{ eq.brand }} {{ eq.model }}</q-item-label>
-                <q-item-label caption style="font-family:monospace">{{ eq.serial_number }}</q-item-label>
+                <q-item-label caption class="mono">{{ eq.serial_number }}</q-item-label>
+              </q-item-section>
+              <q-item-section side>
+                <q-badge :color="eqStatusColor(eq.status)" :label="eq.status || '—'" />
               </q-item-section>
             </q-item>
           </q-list>
-          <q-card-section v-else class="text-center text-grey text-caption">Aucun equipement lie</q-card-section>
+          <q-card-section v-else class="text-center text-grey text-caption">
+            Aucun équipement lié
+          </q-card-section>
         </q-card>
+
+        <!-- Add equipment bottom-sheet -->
+        <q-dialog v-model="addEquipmentMenu" position="bottom">
+          <q-card style="width: 100%; max-width: 400px">
+            <q-card-section class="text-h6">Ajouter un équipement</q-card-section>
+            <q-list>
+              <q-item clickable v-close-popup @click="goScan">
+                <q-item-section avatar><q-icon name="qr_code_scanner" color="primary" /></q-item-section>
+                <q-item-section>
+                  <q-item-label>Scanner un code-barres / QR</q-item-label>
+                  <q-item-label caption>Utiliser la caméra pour détecter un SN ou MAC</q-item-label>
+                </q-item-section>
+              </q-item>
+              <q-item clickable v-close-popup @click="searchEquipDialog = true">
+                <q-item-section avatar><q-icon name="search" color="orange" /></q-item-section>
+                <q-item-section>
+                  <q-item-label>Rechercher un équipement existant</q-item-label>
+                  <q-item-label caption>Par numéro de série ou MAC</q-item-label>
+                </q-item-section>
+              </q-item>
+              <q-item clickable v-close-popup @click="createEquipDialog = true">
+                <q-item-section avatar><q-icon name="add_circle" color="green" /></q-item-section>
+                <q-item-section>
+                  <q-item-label>Créer un nouvel équipement</q-item-label>
+                  <q-item-label caption>Saisir manuellement les informations</q-item-label>
+                </q-item-section>
+              </q-item>
+            </q-list>
+          </q-card>
+        </q-dialog>
+
+        <!-- Search existing equipment -->
+        <q-dialog v-model="searchEquipDialog">
+          <q-card style="min-width: 340px">
+            <q-card-section class="text-h6">Rechercher un équipement</q-card-section>
+            <q-card-section>
+              <q-input v-model="eqSearchText" label="Numéro de série ou MAC" outlined dense autofocus
+                @keyup.enter="searchEquipment" debounce="400" @update:model-value="searchEquipment">
+                <template v-slot:append><q-icon name="search" /></template>
+              </q-input>
+              <q-list v-if="eqSearchResults.length" bordered separator class="q-mt-sm" style="max-height: 250px; overflow-y: auto">
+                <q-item v-for="eq in eqSearchResults" :key="eq.name" clickable @click="linkEquipToJob(eq)">
+                  <q-item-section>
+                    <q-item-label>{{ eq.equipment_type }} — {{ eq.brand }} {{ eq.model }}</q-item-label>
+                    <q-item-label caption class="mono">SN: {{ eq.serial_number }}</q-item-label>
+                    <q-item-label caption v-if="eq.customer_name">Client: {{ eq.customer_name }}</q-item-label>
+                  </q-item-section>
+                  <q-item-section side>
+                    <q-icon name="link" color="primary" />
+                  </q-item-section>
+                </q-item>
+              </q-list>
+              <div v-if="eqSearchText && !eqSearchResults.length && !eqSearching" class="text-caption text-grey q-mt-sm text-center">
+                Aucun résultat
+              </div>
+            </q-card-section>
+            <q-card-actions align="right">
+              <q-btn flat label="Fermer" v-close-popup />
+            </q-card-actions>
+          </q-card>
+        </q-dialog>
+
+        <!-- Create new equipment -->
+        <q-dialog v-model="createEquipDialog">
+          <q-card style="min-width: 340px">
+            <q-card-section class="text-h6">Nouvel équipement</q-card-section>
+            <q-card-section>
+              <q-input v-model="newEquip.serial_number" label="Numéro de série" outlined dense class="q-mb-sm" autofocus />
+              <q-select v-model="newEquip.equipment_type" :options="eqTypes" label="Type" outlined dense class="q-mb-sm" />
+              <q-input v-model="newEquip.brand" label="Marque" outlined dense class="q-mb-sm" />
+              <q-input v-model="newEquip.model" label="Modèle" outlined dense class="q-mb-sm" />
+              <q-input v-model="newEquip.mac_address" label="MAC (optionnel)" outlined dense class="q-mb-sm" />
+            </q-card-section>
+            <q-card-actions align="right">
+              <q-btn flat label="Annuler" v-close-popup />
+              <q-btn color="primary" label="Créer & Lier" :loading="creatingEquip" @click="createAndLinkEquip" />
+            </q-card-actions>
+          </q-card>
+        </q-dialog>
+
       </div>
     </template>
   </q-page>
@@ -95,73 +203,226 @@
 import { ref, computed, onMounted } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { Notify } from 'quasar'
+import { getDoc, listDocs, createDoc, updateDoc } from 'src/api/erp'
 import { BASE_URL } from 'src/config/erpnext'
 
 const route = useRoute()
 const router = useRouter()
+
+const jobName = computed(() => route.params.name)
 const loading = ref(true)
 const saving = ref(false)
 const job = ref(null)
+const locationDetail = ref(null)
 const equipment = ref([])
+const loadingEquip = ref(false)
 
-const jobName = computed(() => route.params.name)
+// Add-equipment dialog state
+const addEquipmentMenu = ref(false)
+const searchEquipDialog = ref(false)
+const createEquipDialog = ref(false)
+const eqSearchText = ref('')
+const eqSearchResults = ref([])
+const eqSearching = ref(false)
+const creatingEquip = ref(false)
+const eqTypes = ['ONT', 'Modem', 'Routeur', 'Décodeur TV', 'VoIP', 'Amplificateur', 'Splitter', 'Câble', 'Autre']
+const newEquip = ref({ serial_number: '', equipment_type: 'ONT', brand: '', model: '', mac_address: '' })
+
+const displayDuration = computed({
+  get: () => job.value?.duration_h || 1,
+  set: v => { if (job.value) job.value.duration_h = v },
+})
+
+const jobTypes = [
+  { label: 'Installation', value: 'Installation' },
+  { label: 'Réparation', value: 'Repair' },
+  { label: 'Maintenance', value: 'Maintenance' },
+  { label: 'Inspection', value: 'Inspection' },
+  { label: 'Livraison', value: 'Delivery' },
+  { label: 'Autre', value: 'Other' },
+]
+
+const priorities = [
+  { label: 'Basse', value: 'low' },
+  { label: 'Moyenne', value: 'medium' },
+  { label: 'Haute', value: 'high' },
+  { label: 'Urgente', value: 'urgent' },
+]
 
 const statusColor = computed(() => {
-  const map = { Scheduled: 'blue', assigned: 'blue', 'In Progress': 'orange', in_progress: 'orange', Completed: 'green' }
+  const map = { Scheduled: 'blue', assigned: 'blue', 'In Progress': 'orange', in_progress: 'orange', Completed: 'green', Cancelled: 'grey' }
   return map[job.value?.status] || 'grey'
 })
 const statusLabel = computed(() => {
-  const map = { Scheduled: 'Planifie', assigned: 'Assigne', 'In Progress': 'En cours', in_progress: 'En cours', Completed: 'Termine' }
+  const map = { Scheduled: 'Planifié', assigned: 'Assigné', 'In Progress': 'En cours', in_progress: 'En cours', Completed: 'Terminé', Cancelled: 'Annulé' }
   return map[job.value?.status] || job.value?.status || ''
 })
 
-async function apiFetch (url) {
-  const res = await fetch(BASE_URL + url)
-  if (!res.ok) throw new Error('API ' + res.status)
-  return (await res.json()).data
+const locationAddress = computed(() => {
+  const loc = locationDetail.value
+  if (!loc) return job.value?.service_location_name || ''
+  return [loc.address_line, loc.city, loc.postal_code].filter(Boolean).join(', ')
+})
+
+function eqIcon (type) {
+  const map = { ONT: 'settings_input_hdmi', Modem: 'router', Routeur: 'wifi', 'Décodeur TV': 'tv', VoIP: 'phone' }
+  return map[type] || 'memory'
+}
+function eqStatusColor (s) {
+  if (s === 'Actif') return 'green'
+  if (s === 'Défectueux' || s === 'Perdu') return 'red'
+  return 'grey'
 }
 
-async function apiUpdate (doctype, name, data) {
-  await fetch(BASE_URL + '/api/resource/' + doctype + '/' + encodeURIComponent(name), {
-    method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data),
-  })
-}
+// --- Load job + related data ---
 
 async function loadJob () {
   loading.value = true
   try {
-    job.value = await apiFetch('/api/resource/Dispatch Job/' + encodeURIComponent(jobName.value))
+    job.value = await getDoc('Dispatch Job', jobName.value)
     if (job.value.service_location) {
-      const params = new URLSearchParams({ filters: JSON.stringify({ service_location: job.value.service_location }), fields: JSON.stringify(['name','serial_number','equipment_type','brand','model','status']), limit_page_length: 50 })
-      try { equipment.value = await apiFetch('/api/resource/Service Equipment?' + params) || [] } catch {}
+      getDoc('Service Location', job.value.service_location)
+        .then(loc => { locationDetail.value = loc })
+        .catch(() => {})
     }
+    loadEquipment()
   } catch (e) {
-    Notify.create({ type: 'negative', message: 'Erreur: ' + e.message })
-  } finally { loading.value = false }
+    Notify.create({ type: 'negative', message: 'Erreur chargement job: ' + e.message })
+  } finally {
+    loading.value = false
+  }
 }
 
+async function loadEquipment () {
+  if (!job.value?.service_location && !job.value?.customer) return
+  loadingEquip.value = true
+  try {
+    const filters = job.value.service_location
+      ? { service_location: job.value.service_location }
+      : { customer: job.value.customer }
+    equipment.value = await listDocs('Service Equipment', {
+      filters,
+      fields: ['name', 'serial_number', 'equipment_type', 'brand', 'model', 'mac_address', 'status', 'customer_name'],
+      limit: 50,
+    })
+  } catch { equipment.value = [] }
+  finally { loadingEquip.value = false }
+}
+
+// --- Save / status ---
+
 async function saveField (field, value) {
   if (!job.value?.name) return
-  try { await apiUpdate('Dispatch Job', job.value.name, { [field]: value }) } catch {}
+  try { await updateDoc('Dispatch Job', job.value.name, { [field]: value }) }
+  catch (e) { Notify.create({ type: 'negative', message: 'Erreur sauvegarde: ' + e.message }) }
 }
 
 async function updateStatus (status) {
   saving.value = true
   try {
-    await apiUpdate('Dispatch Job', job.value.name, { status })
+    await updateDoc('Dispatch Job', job.value.name, { status })
     job.value.status = status
-    Notify.create({ type: 'positive', message: status === 'Completed' ? 'Termine' : 'En route !' })
+    const msgs = { 'In Progress': 'En route !', Completed: 'Job terminé', Scheduled: 'Job réouvert' }
+    Notify.create({ type: 'positive', message: msgs[status] || status, icon: status === 'Completed' ? 'check_circle' : 'directions_car' })
   } catch (e) {
     Notify.create({ type: 'negative', message: 'Erreur: ' + e.message })
   } finally { saving.value = false }
 }
 
+// --- GPS & misc ---
+
 function openGps () {
-  window.open(`https://www.google.com/maps/dir/?api=1&destination=${encodeURIComponent(job.value.service_location_name || '')}`, '_blank')
+  const loc = locationDetail.value
+  if (loc?.latitude && loc?.longitude) {
+    window.open(`https://www.google.com/maps/dir/?api=1&destination=${loc.latitude},${loc.longitude}`, '_blank')
+    return
+  }
+  const addr = loc
+    ? [loc.address_line, loc.city, loc.postal_code].filter(Boolean).join(', ')
+    : (job.value?.service_location_name || '')
+  window.open(`https://www.google.com/maps/dir/?api=1&destination=${encodeURIComponent(addr)}`, '_blank')
 }
-function openInErp () { window.open(`${BASE_URL}/app/dispatch-job/${job.value.name}`, '_blank') }
+
+function openInErp () {
+  window.open(`${BASE_URL}/app/dispatch-job/${job.value.name}`, '_blank')
+}
+
 function goScan () {
-  router.push({ path: '/j/scan', query: { job: job.value.name, customer: job.value.customer, customer_name: job.value.customer_name, location: job.value.service_location, location_name: job.value.service_location_name } })
+  router.push({
+    name: 'tech-scan',
+    query: {
+      job: job.value.name,
+      customer: job.value.customer,
+      customer_name: job.value.customer_name,
+      location: job.value.service_location,
+      location_name: job.value.service_location_name,
+    },
+  })
+}
+
+// --- Equipment search / create / link ---
+
+async function searchEquipment () {
+  const text = eqSearchText.value?.trim()
+  if (!text || text.length < 2) { eqSearchResults.value = []; return }
+  eqSearching.value = true
+  try {
+    let results = await listDocs('Service Equipment', {
+      filters: { serial_number: ['like', `%${text}%`] },
+      fields: ['name', 'serial_number', 'equipment_type', 'brand', 'model', 'mac_address', 'customer_name', 'status'],
+      limit: 10,
+    })
+    if (!results.length) {
+      results = await listDocs('Service Equipment', {
+        filters: { mac_address: ['like', `%${text}%`] },
+        fields: ['name', 'serial_number', 'equipment_type', 'brand', 'model', 'mac_address', 'customer_name', 'status'],
+        limit: 10,
+      })
+    }
+    eqSearchResults.value = results
+  } catch { eqSearchResults.value = [] }
+  finally { eqSearching.value = false }
+}
+
+async function linkEquipToJob (eq) {
+  try {
+    const updates = {}
+    if (job.value.customer) updates.customer = job.value.customer
+    if (job.value.service_location) updates.service_location = job.value.service_location
+    await updateDoc('Service Equipment', eq.name, updates)
+    equipment.value.push(eq)
+    searchEquipDialog.value = false
+    eqSearchText.value = ''
+    eqSearchResults.value = []
+    Notify.create({ type: 'positive', message: `${eq.equipment_type} lié au job`, icon: 'link' })
+  } catch (e) {
+    Notify.create({ type: 'negative', message: 'Erreur: ' + e.message })
+  }
+}
+
+async function createAndLinkEquip () {
+  if (!newEquip.value.serial_number?.trim()) {
+    Notify.create({ type: 'warning', message: 'Numéro de série requis' })
+    return
+  }
+  creatingEquip.value = true
+  try {
+    const data = {
+      ...newEquip.value,
+      status: 'Actif',
+      customer: job.value.customer || '',
+      service_location: job.value.service_location || '',
+    }
+    const doc = await createDoc('Service Equipment', data)
+    equipment.value.push(doc)
+    Notify.create({ type: 'positive', message: 'Équipement créé et lié', icon: 'check_circle' })
+    createEquipDialog.value = false
+    newEquip.value = { serial_number: '', equipment_type: 'ONT', brand: '', model: '', mac_address: '' }
+  } catch (e) {
+    Notify.create({ type: 'negative', message: 'Erreur: ' + e.message })
+  } finally {
+    creatingEquip.value = false
+  }
 }
 
 onMounted(loadJob)
@@ -169,18 +430,29 @@ onMounted(loadJob)
 
 <style lang="scss" scoped>
 .job-detail-page { padding: 0 !important; display: flex; flex-direction: column; min-height: 100%; }
+
 .job-topbar {
   display: flex; align-items: center; padding: 8px 8px 8px 4px;
   background: linear-gradient(135deg, #3f3d7a 0%, #5c59a8 100%); color: white;
   position: sticky; top: 0; z-index: 10;
 }
+
 .job-status-hero {
   text-align: center; padding: 20px 16px; background: #f5f7fa;
   border-bottom: 1px solid rgba(0,0,0,0.06);
   &.status-in-progress, &.status-in_progress { background: #fff8e1; }
   &.status-completed { background: #e8f5e9; }
+  &.status-cancelled { background: #fafafa; }
 }
+
 .action-btn { min-width: 140px; font-weight: 600; border-radius: 12px; }
-.job-content { flex: 1; overflow-y: auto; padding-bottom: 80px !important; }
+
+.job-content {
+  flex: 1;
+  overflow-y: auto;
+  padding-bottom: 80px !important; // clear TechLayout bottom tab bar
+}
+
+.mono { font-family: 'SF Mono', 'Fira Code', monospace; font-size: 0.85em; }
 .text-overline { font-size: 0.68rem; letter-spacing: 0.08em; }
 </style>
diff --git a/apps/ops/src/modules/tech/pages/TechScanPage.vue b/apps/ops/src/modules/tech/pages/TechScanPage.vue
index 7cd8aab..a81ac92 100644
--- a/apps/ops/src/modules/tech/pages/TechScanPage.vue
+++ b/apps/ops/src/modules/tech/pages/TechScanPage.vue
@@ -1,19 +1,19 @@
 <!--
   TechScanPage — camera-based equipment scanner for field techs at /j/scan.
 
-  Three capture modes (useScanner docs in src/composables/useScanner.js):
-    • Caméra (live) — default, html5-qrcode continuous stream, instant + offline
-    • Photo        — native camera, local multi-strip + Gemini fallback, offline-queued
-    • Manuel       — plain text input, for bent/unreadable stickers
+  What it does in one sentence: the tech points their phone at an ONT/router
+  label, Gemini reads the serial, and we look it up in ERPNext, optionally
+  auto-linking the equipment to the tech's current Dispatch Job.
 
-  ERPNext relationships touched (see docs/features/vision-ocr.md §10):
+  ERPNext relationships touched (see docs/VISION_AND_OCR.md §10 for the full
+  data-model diagram):
 
     Dispatch Job ─► Customer ─► Service Location  ◄── Service Equipment
                                                        (serial_number, barcode,
                                                         mac_address, status)
 
     The tech arrives via `/j/scan?job=JOB-001&customer=CUST-123&location=LOC-456`
-    — when a scanned serial matches an unlinked Service Equipment row, we
+    — when the scanned serial matches an unlinked Service Equipment row, we
     auto-patch customer + service_location on that row so the device is
     provably tied to that install address before the tech leaves.
 
@@ -21,11 +21,11 @@
     same Customer + Service Location, so the scan result flows through
     naturally for any downstream ticket view.
 
-  History: this page started as apps/field/src/pages/ScanPage.vue (live + multi-
-  strip), was briefly reduced to Gemini-only (Apr 2026), and is now hybrid.
-  Live camera is the default because pointing-and-scanning is 10× faster than
-  take-photo-wait-for-AI on a normal QR code. Photo+Gemini is kept as a
-  second chance for damaged or text-only labels.
+  Ported from apps/field/src/pages/ScanPage.vue during the field→ops
+  unification (see docs/ARCHITECTURE.md §"Legacy Retirement Plan"). Adapted
+  for the ops router:
+    - device-detail route name: 'tech-device' (was 'device' in field)
+    - same query-param contract from TechJobDetailPage.goScan()
 -->
 <template>
   <q-page padding class="scan-page">
@@ -46,99 +46,55 @@
       </q-card-section>
     </q-card>
 
-    <!-- Mode tabs: Caméra / Photo / Manuel -->
-    <q-tabs v-model="mode" dense no-caps active-color="primary" indicator-color="primary" align="justify"
-      class="q-mb-md" @update:model-value="onModeChange">
-      <q-tab name="live" icon="videocam" label="Caméra" />
-      <q-tab name="photo" icon="photo_camera" label="Photo" />
-      <q-tab name="manual" icon="keyboard" label="Manuel" />
-    </q-tabs>
-
-    <!-- ==== Live camera mode (default, fastest) ==== -->
-    <div v-show="mode === 'live'" class="live-wrap">
-      <div id="live-reader" class="live-reader" />
-      <div class="text-center q-mt-sm">
-        <q-btn v-if="!scanner.live.value" color="primary" icon="play_arrow"
-          label="Démarrer la caméra" @click="startLive" unelevated />
-        <q-btn v-else color="negative" icon="stop" label="Arrêter" @click="scanner.stopLive()" outline />
-      </div>
-      <div v-if="scanner.live.value" class="text-caption text-center text-grey q-mt-xs">
-        Cadrez un code-barres — détection automatique
-      </div>
-    </div>
-
-    <!-- ==== Photo mode (native camera + local scan + Gemini fallback) ==== -->
-    <div v-show="mode === 'photo'" class="text-center">
+    <!-- Camera capture button -->
+    <div class="text-center">
       <q-btn
-        color="primary" icon="photo_camera" label="Prendre une photo"
+        color="primary" icon="photo_camera" label="Scanner"
         size="lg" rounded unelevated
         @click="takePhoto"
         :loading="scanner.scanning.value"
         class="q-px-xl"
       />
       <input ref="cameraInput" type="file" accept="image/*" capture="environment" class="hidden" @change="onPhoto" />
-      <div class="text-caption text-grey q-mt-sm">
-        Jusqu'à {{ scanner.MAX_BARCODES }} codes par photo · IA activée si la lecture locale échoue
-      </div>
+    </div>
 
-      <!-- Pending scan indicator (signal faible → queue offline) -->
-      <div v-if="offline.pendingVisionCount > 0" class="text-center q-mt-sm">
-        <q-chip icon="wifi_tethering_off" color="orange" text-color="white" dense clickable
-          @click="offline.syncVisionQueue()">
-          {{ offline.pendingVisionCount }} scan{{ offline.pendingVisionCount > 1 ? 's' : '' }}
-          en attente · toucher pour réessayer
-        </q-chip>
-      </div>
+    <!-- Pending scan indicator (signal faible → queue offline) -->
+    <div v-if="offline.pendingVisionCount > 0" class="text-center q-mt-sm">
+      <q-chip icon="wifi_tethering_off" color="orange" text-color="white" dense clickable @click="offline.syncVisionQueue()">
+        {{ offline.pendingVisionCount }} scan{{ offline.pendingVisionCount > 1 ? 's' : '' }} en attente · toucher pour réessayer
+      </q-chip>
+    </div>
 
-      <!-- Last captured photo (thumbnail) -->
-      <div v-if="scanner.lastPhoto.value" class="photo-preview q-mt-md">
-        <img :src="scanner.lastPhoto.value" class="preview-img" @click="showFullPhoto = true" />
-        <div v-if="scanner.scanning.value" class="preview-overlay">
-          <q-spinner-dots size="32px" color="white" />
-          <div class="text-white text-caption q-mt-xs">Analyse...</div>
-        </div>
-      </div>
-
-      <!-- Photo history (small thumbnails) -->
-      <div v-if="scanner.photos.value.length > 1" class="q-mt-md">
-        <div class="text-caption text-grey q-mb-xs">Photos capturées</div>
-        <div class="row q-gutter-xs justify-center">
-          <div v-for="(p, i) in scanner.photos.value" :key="i" class="photo-thumb" @click="viewPhoto(p)">
-            <img :src="p.url" />
-            <q-badge v-if="p.codes.length" color="green" floating :label="p.codes.length" />
-          </div>
-        </div>
+    <!-- Last captured photo (thumbnail) -->
+    <div v-if="scanner.lastPhoto.value" class="photo-preview q-mt-md">
+      <img :src="scanner.lastPhoto.value" class="preview-img" @click="showFullPhoto = true" />
+      <div v-if="scanner.scanning.value" class="preview-overlay">
+        <q-spinner-dots size="32px" color="white" />
+        <div class="text-white text-caption q-mt-xs">Analyse Gemini...</div>
       </div>
     </div>
 
-    <!-- ==== Manual entry ==== -->
-    <div v-show="mode === 'manual'">
-      <q-input v-model="manualCode" label="Saisie manuelle SN / MAC / code-barres"
-        outlined dense autofocus @keyup.enter="addManual">
-        <template v-slot:prepend><q-icon name="keyboard" /></template>
-        <template v-slot:append>
-          <q-btn flat dense icon="add" :disable="!manualCode.trim()" @click="addManual" />
-        </template>
-      </q-input>
-    </div>
-
-    <!-- ==== Error / status (all modes) ==== -->
+    <!-- Error / status -->
     <div v-if="scanner.error.value" class="text-caption text-center q-mt-sm text-negative">
       {{ scanner.error.value }}
     </div>
 
-    <!-- ==== Scanned barcodes (shared across all modes) ==== -->
+    <!-- Manual entry fallback -->
+    <q-input v-model="manualCode" label="Saisie manuelle SN / MAC" outlined dense class="q-mt-md"
+      @keyup.enter="addManual">
+      <template v-slot:append>
+        <q-btn flat dense icon="add" @click="addManual" :disable="!manualCode.trim()" />
+      </template>
+    </q-input>
+
+    <!-- Scanned barcodes — max 5 (see useScanner.MAX_BARCODES) -->
     <div v-if="scanner.barcodes.value.length > 0" class="q-mt-md">
-      <div class="row items-center q-mb-xs">
-        <div class="text-subtitle2 col">Codes détectés ({{ scanner.barcodes.value.length }}/{{ scanner.MAX_BARCODES }})</div>
-        <q-btn flat dense size="sm" icon="clear_all" label="Effacer" @click="scanner.clearBarcodes()" />
-      </div>
+      <div class="text-subtitle2 q-mb-xs">Codes détectés ({{ scanner.barcodes.value.length }})</div>
       <q-card v-for="bc in scanner.barcodes.value" :key="bc.value" class="q-mb-sm">
         <q-card-section class="q-py-sm row items-center no-wrap">
           <q-icon name="qr_code" class="q-mr-sm" color="primary" />
           <div class="col">
             <div class="text-subtitle2 mono">{{ bc.value }}</div>
-            <div class="text-caption text-grey">{{ bc.region }}</div>
           </div>
           <q-btn flat dense icon="search" @click="lookupDevice(bc.value)" :loading="lookingUp === bc.value" />
           <q-btn flat dense icon="close" color="negative" @click="scanner.removeBarcode(bc.value)" />
@@ -175,6 +131,17 @@
       </q-card>
     </div>
 
+    <!-- Photo history (small thumbnails) -->
+    <div v-if="scanner.photos.value.length > 1" class="q-mt-md">
+      <div class="text-caption text-grey q-mb-xs">Photos capturées</div>
+      <div class="row q-gutter-xs">
+        <div v-for="(p, i) in scanner.photos.value" :key="i" class="photo-thumb" @click="viewPhoto(p)">
+          <img :src="p.url" />
+          <q-badge v-if="p.codes.length" color="green" floating :label="p.codes.length" />
+        </div>
+      </div>
+    </div>
+
     <!-- Link all to account (manual, when no job context) -->
     <div v-if="scanner.barcodes.value.length > 0 && !jobContext && hasUnlinked" class="q-mt-sm">
       <q-btn color="orange" icon="link" label="Lier les équipements à un service"
@@ -264,7 +231,7 @@
 </template>
 
 <script setup>
-import { ref, computed, nextTick, onBeforeUnmount } from 'vue'
+import { ref, computed } from 'vue'
 import { useRoute } from 'vue-router'
 import { useScanner } from 'src/composables/useScanner'
 import { listDocs, createDoc, updateDoc } from 'src/api/erp'
@@ -274,8 +241,8 @@ import { Notify } from 'quasar'
 const route = useRoute()
 const offline = useOfflineStore()
 // Each new code triggers both a toast AND a silent ERPNext lookup. The
-// callback fires for live scans, photo scans, queued retries, and manual
-// entries — the tech gets notified either way.
+// callback fires for synchronous scans AND for scans that complete later
+// from the offline vision queue — the tech gets notified either way.
 const scanner = useScanner({
   onNewCode: (code) => {
     Notify.create({ type: 'positive', message: code, timeout: 2500, icon: 'qr_code', color: 'deep-purple' })
@@ -283,8 +250,6 @@ const scanner = useScanner({
   },
 })
 
-// Default to live camera — that's what techs use 90% of the time.
-const mode = ref('live')
 const cameraInput = ref(null)
 const manualCode = ref('')
 const lookingUp = ref(null)
@@ -330,28 +295,7 @@ const hasUnlinked = computed(() =>
   })
 )
 
-// ─── Mode switch ─────────────────────────────────────────────────────
-
-function onModeChange (newMode) {
-  // Leaving Live → cut the camera so we're not streaming in the background.
-  if (newMode !== 'live' && scanner.live.value) scanner.stopLive()
-}
-
-// Defensive: make sure we don't leak the camera if the page unmounts while live.
-onBeforeUnmount(() => {
-  if (scanner.live.value) scanner.stopLive()
-})
-
-// ─── Live camera ─────────────────────────────────────────────────────
-
-async function startLive () {
-  // #live-reader is inside v-show — it's always in the DOM from first render.
-  // nextTick is defensive in case a parent transition hid it momentarily.
-  await nextTick()
-  await scanner.startLive('live-reader')
-}
-
-// ─── Photo camera ────────────────────────────────────────────────────
+// ─── Camera capture ──────────────────────────────────────────────────
 
 function takePhoto () {
   // Reset so the same file re-triggers change when tech scans, undoes, scans
@@ -377,16 +321,11 @@ function viewPhoto (photo) {
 function addManual () {
   const code = manualCode.value.trim()
   if (!code) return
-  if (scanner.barcodes.value.length >= scanner.MAX_BARCODES) {
-    Notify.create({ type: 'warning', message: `Maximum ${scanner.MAX_BARCODES} codes` })
-    return
-  }
-  if (scanner.addCode(code, 'manuel')) {
-    manualCode.value = ''
-  } else {
-    Notify.create({ type: 'info', message: 'Code déjà ajouté' })
-    manualCode.value = ''
+  if (!scanner.barcodes.value.find(b => b.value === code)) {
+    scanner.barcodes.value.push({ value: code, region: 'manuel' })
+    lookupDevice(code)
   }
+  manualCode.value = ''
 }
 
 // ─── Device lookup: 3-tier fallback ──────────────────────────────────
@@ -598,25 +537,6 @@ async function linkDeviceToService () {
   padding-bottom: 80px !important;  /* TechLayout has a bottom tab bar */
 }
 
-.live-wrap {
-  max-width: 480px;
-  margin: 0 auto;
-}
-
-.live-reader {
-  width: 100%;
-  min-height: 280px;
-  border-radius: 12px;
-  overflow: hidden;
-  background: #000;
-  // html5-qrcode injects a <video> — make it fill the container
-  :deep(video) {
-    width: 100% !important;
-    height: auto !important;
-    display: block;
-  }
-}
-
 .photo-preview {
   position: relative;
   text-align: center;
@@ -655,6 +575,6 @@ async function linkDeviceToService () {
 }
 
 .mono {
-  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-family: monospace;
 }
 </style>
diff --git a/docs/README.md b/docs/README.md
index c730c5f..f96aa63 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,18 +1,26 @@
 # Gigafibre FSM — Documentation
 
-> **Start here.** Everything you need to understand the system is one or two
-> clicks away. Pick the row that matches why you're here.
+> **Start here.** Pick a row by intent, jump to the module index when you
+> need scope, or go straight to the cross-module map when you're chasing a
+> call that hops surfaces.
+
+**Last refreshed:** 2026-04-22 (expanded module index, added dispatch /
+customer portal / tech mobile docs, cross-interaction matrix)
 
 ---
 
-## Quick nav by intent
+## 1. Quick nav by intent
 
 | I want to… | Open |
 |---|---|
 | **See the plan** — what's shipped, what's queued, with clickable links to every live module | [roadmap.md](roadmap.md) |
 | **Understand the system end-to-end** — services, containers, networks, SSO, Traefik routes | [architecture/overview.md](architecture/overview.md) |
+| **See who calls who** — one-page matrix of every module → module interaction | [architecture/module-interactions.md](architecture/module-interactions.md) |
 | **Build a new feature** — UI patterns, folder layout, router conventions, Pinia, feature-sliced design | [architecture/app-design.md](architecture/app-design.md) |
 | **Touch ERPNext data** — doctypes, customer → subscription → equipment → invoice, "Lead to Live" flow | [architecture/data-model.md](architecture/data-model.md) |
+| **Work on dispatch** — drag-and-drop scheduling, tech assignment, travel-time optimization, magic-link SMS | [features/dispatch.md](features/dispatch.md) |
+| **Work on the tech mobile app** — scan-to-identify, equipment install, job status, JWT auth | [features/tech-mobile.md](features/tech-mobile.md) |
+| **Work on the customer portal** — passwordless magic-link, invoice + ticket self-service | [features/customer-portal.md](features/customer-portal.md) |
 | **Work on billing, Stripe, payments** — subscription lifecycle, invoice OCR, payment reconciliation, PPA | [features/billing-payments.md](features/billing-payments.md) |
 | **Touch CPE / modems / ONTs** — GenieACS, Oktopus, TR-069 → TR-369 migration, TP-Link XX230v diagnostics | [features/cpe-management.md](features/cpe-management.md) |
 | **Build or debug the scanner / OCR** — Gemini vision pipeline, barcode/equipment/invoice endpoints, offline queue, AI_API_KEY rotation | [features/vision-ocr.md](features/vision-ocr.md) |
@@ -23,25 +31,194 @@
 
 ---
 
-## Folder map
+## 2. Module index
+
+Every deployed surface, by app. Each row links to its primary doc and
+names the exact code paths so you can `grep` from here.
+
+### 2a. Ops SPA (`apps/ops/`) — `https://erp.gigafibre.ca/ops/`
+
+**Single pane of glass for internal teams.** Quasar PWA (SPA mode in dev,
+PWA mode in prod), Vue 3 + Pinia, hash router. Wrapped by Authentik via
+Traefik `forwardAuth` on `/ops/*`. Bottom of the same app hosts the tech
+mobile module on `/j/*` with magic-link auth.
+
+| Module | URL | Purpose | Primary doc | Primary code |
+|---|---|---|---|---|
+| **Dashboard** | `/ops/#/` | KPIs (MRR, AR, active tickets), dispatch summary, live SSE feed | — | `src/pages/DashboardPage.vue` |
+| **Clients** | `/ops/#/clients` · `/clients/:id` | Customer 360: profile, subscriptions, invoices, equipment, tickets, communication timeline | — | `src/pages/ClientsPage.vue` · `ClientDetailPage.vue` · `src/modules/clients/` |
+| **Dispatch** | `/ops/#/dispatch` | Drag-and-drop tech schedule, job board, travel-time optimization, SMS magic-link issuance | [features/dispatch.md](features/dispatch.md) | `src/pages/DispatchPage.vue` · `src/modules/dispatch/` |
+| **Tickets** | `/ops/#/tickets` | Support ticket board, SLA clock, linked equipment + jobs | — | `src/pages/TicketsPage.vue` · `src/modules/tickets/` |
+| **Équipe** | `/ops/#/equipe` | Technician roster, skills/tags, availability, today's jobs | [features/dispatch.md §6](features/dispatch.md) | `src/pages/EquipePage.vue` · `src/modules/equipe/` |
+| **Rapports** | `/ops/#/rapports` + `/revenus` · `/ventes` · `/taxes` · `/ar` | Revenue, sales, tax, AR reports (renders in-browser; PDF export via hub) | [features/billing-payments.md §9](features/billing-payments.md) | `src/pages/Rapports*.vue` · `src/modules/rapports/` |
+| **OCR** | `/ops/#/ocr` | Upload scanned supplier bills → Gemini parse → pre-fill Purchase Invoice | [features/vision-ocr.md §4](features/vision-ocr.md) | `src/pages/OcrPage.vue` |
+| **Settings** | `/ops/#/settings` | Feature flags, integration keys, user management (mirror of ERPNext) | — | `src/pages/SettingsPage.vue` |
+| **Telephony** | `/ops/#/telephony` | SIP click-to-dial (Twilio Voice SDK + sip.js fallback), call history | [architecture/overview.md §3](architecture/overview.md) | `src/pages/TelephonyPage.vue` |
+| **Agent Flows** | `/ops/#/agent-flows` | Visual editor for Flow Template (automation runtime) | [features/flow-editor.md](features/flow-editor.md) | `src/pages/AgentFlowsPage.vue` |
+| **Network** | `/ops/#/network` | Cytoscape-rendered OLT/ONT topology, live link status from GenieACS | [features/cpe-management.md](features/cpe-management.md) | `src/pages/NetworkPage.vue` |
+
+### 2b. Ops tech module (`apps/ops/src/modules/tech/`) — `https://erp.gigafibre.ca/ops/#/j/*`
+
+**Same SPA, different mount.** Techs hit a magic-link SMS, land on `/j/:token`,
+the token redirects to `/j` with JWT in localStorage. Mobile-first layout
+with bottom tab bar.
+
+| Route | Purpose | Primary doc | Primary code |
+|---|---|---|---|
+| `/j` | Today's jobs, grouped by status | [features/tech-mobile.md §4a](features/tech-mobile.md) | `TechTasksPage.vue` |
+| `/j/job/:name` | Job detail + equipment management (Ajouter/Scanner/Rechercher/Créer) | [features/tech-mobile.md §5](features/tech-mobile.md) | `TechJobDetailPage.vue` |
+| `/j/scan` | Standalone scanner (native camera → Gemini) | [features/tech-mobile.md §3](features/tech-mobile.md) | `TechScanPage.vue` |
+| `/j/device/:serial` | Per-device detail, diagnostic shortcut | — | `TechDevicePage.vue` |
+| `/j/diagnostic` | In-browser speed test + GenieACS probe | [features/cpe-management.md](features/cpe-management.md) | `TechDiagnosticPage.vue` |
+| `/j/more` | Settings, token expiry, logout | — | `TechMorePage.vue` |
+| `/j/:token` | Magic-link handler (last route, accepts any JWT) | [features/tech-mobile.md §2](features/tech-mobile.md) | `TechTasksPage.vue` (same component, different entry) |
+
+### 2c. Field PWA (`apps/field/`) — `https://erp.gigafibre.ca/field/`
+
+**Transitional standalone PWA, retiring.** Authentik-protected; byte-for-byte
+closer to the legacy workflow techs had before the Ops tech module
+existed. No magic-link — tech logs in via Authentik. Kept alive while the
+SMS link still points at the hub SSR page (see tech-mobile doc §1).
+
+Same page set as §2b (TasksPage, ScanPage, JobDetailPage, DevicePage,
+DiagnosticPage, MorePage), same Gemini-native scanner composable.
+`apps/field/src/pages/JobDetailPage.vue` is the reference implementation
+we port *from* when the Ops tech module drifts.
+
+### 2d. Customer portal (`apps/client/`) — `https://portal.gigafibre.ca/`
+
+**Passwordless self-service.** Standalone Quasar PWA served by a dedicated
+nginx container (`client-portal`) bind-mounted from `/opt/client-app/` on
+the Proxmox VM. No Authentik — customers get a magic-link email (HS256
+JWT, 24h TTL).
+
+| Module | URL | Purpose | Primary doc | Primary code |
+|---|---|---|---|---|
+| **Login** | `/#/login` | Email entry → magic-link email send | [features/customer-portal.md §3](features/customer-portal.md) | `src/pages/LoginPage.vue` |
+| **Dashboard** | `/#/` | Balance, next invoice, active tickets, recent activity | [features/customer-portal.md §4a](features/customer-portal.md) | `DashboardPage.vue` |
+| **Account** | `/#/account` | Profile, saved payment methods (Stripe PM), address book | [features/billing-payments.md §6](features/billing-payments.md) | `AccountPage.vue` |
+| **Catalog / Cart** | `/#/catalog` · `/#/cart` | Shop add-ons (extra mesh, static IP), add to Stripe Checkout | [features/billing-payments.md](features/billing-payments.md) | `CatalogPage.vue` · `CartPage.vue` |
+| **Invoices** | `/#/invoices` · `/#/invoices/:name` | List + PDF of all Sales Invoices, Stripe-linked pay button | [features/billing-payments.md §8](features/billing-payments.md) | `InvoicesPage.vue` · `InvoiceDetailPage.vue` |
+| **Tickets** | `/#/tickets` · `/#/tickets/:name` | Create support ticket, reply thread, attach photos | — | `TicketsPage.vue` · `TicketDetailPage.vue` |
+| **Messages** | `/#/messages` | Unified comm thread (SMS + email) with support | — | `MessagesPage.vue` |
+| **Payment flows** | `/#/payment-success` · `/payment-cancel` · `/payment-card-added` · `/order-success` | Stripe return URL landings | [features/billing-payments.md §7](features/billing-payments.md) | `Payment*.vue` · `OrderSuccessPage.vue` |
+
+### 2e. Legacy portal (`apps/portal/`) — **retired 2026-04-22**
+
+Old ERPNext-embedded customer portal. Host `client.gigafibre.ca` now 307s
+to `portal.gigafibre.ca/*` via Traefik; see
+`apps/portal/traefik-client-portal.yml`. Codebase retained as historical
+reference only. Do not build.
+
+### 2f. Marketing site (`apps/website/`) — `https://www.gigafibre.ca/`
+
+React + Vite marketing site. Self-contained, no ERPNext dependency,
+no docs beyond its own README.
+
+---
+
+## 3. Services (backends)
+
+Everything in `services/*` is backend infrastructure. Usually you don't
+edit these unless you're adding a new endpoint.
+
+| Service | Port | Role | Primary docs |
+|---|---|---|---|
+| `services/targo-hub/` | `msg.gigafibre.ca:3300` | **API gateway.** Vision (Gemini), magic-link JWT, Twilio SMS, SSE fanout, Stripe webhooks, ACS proxy, Legacy-DB read proxy, tech-mobile SSR | [overview.md §3](architecture/overview.md) · [vision-ocr.md](features/vision-ocr.md) · [customer-portal.md](features/customer-portal.md) · [tech-mobile.md](features/tech-mobile.md) · [billing-payments.md](features/billing-payments.md) |
+| `services/modem-bridge/` | `:3301` (internal) | Playwright + Chromium wrapper that logs into TP-Link XX230v modems and reads encrypted TR-181 data | [cpe-management.md](features/cpe-management.md) |
+| `services/docuseal/` | `docs.gigafibre.ca:3000` | Contract signing for commercial quotes + residential service agreements | [flow-editor.md §5](features/flow-editor.md) (briefly) |
+| `services/legacy-db/` | `:3305` (internal) | Read-only proxy over the retired MariaDB for lookups that haven't migrated | [architecture/overview.md](architecture/overview.md) |
+
+**ERPNext** (`erp.gigafibre.ca`) is not under `services/` — it's a standard
+Frappe-Bench install on the VM. See
+[architecture/data-model.md](architecture/data-model.md) for the doctype
+catalog.
+
+---
+
+## 4. Cross-module interactions (one-page map)
+
+> Full matrix + sequence diagrams in
+> [architecture/module-interactions.md](architecture/module-interactions.md).
+> The summary below is just the high-traffic edges.
+
+```text
+                    ┌───────────────────────────────────────┐
+                    │         ERPNext (source of truth)     │
+                    │     Customer · Subscription ·         │
+                    │     Equipment · Dispatch Job ·        │
+                    │     Sales Invoice · Ticket            │
+                    └──┬──────────────┬──────────┬──────────┘
+                       │              │          │
+           REST+token  │      REST+token         │ REST+token
+                       │              │          │
+          ┌────────────▼──┐   ┌───────▼────────┐ │
+          │  targo-hub    │   │   Ops SPA      │ │
+          │  (gateway)    │◄──┤   apps/ops/    │ │
+          │               │   └────┬───────────┘ │
+          │ /vision/*     │        │             │
+          │ /magic-link/* │        │ bundles     │
+          │ /sse          │        │ tech module │
+          │ /sms          │        │ at /j/*     │
+          │ /stripe/*     │        │             │
+          │ /acs/*        │        └─────────────┘
+          │ /t/{token}    │                      │
+          └──┬──────┬─────┘                      │
+             │      │                            │
+       SMS   │      │ email (magic link)         │
+       /SSE  │      │                            │
+             ▼      ▼                            ▼
+     ┌─────────────────┐    ┌────────────────────────┐
+     │ Tech mobile     │    │ Customer portal        │
+     │ (SSR OR Vue)    │    │ apps/client/           │
+     │ /t or /ops/#/j/ │    │ portal.gigafibre.ca    │
+     └─────────────────┘    └────────────────────────┘
+```
+
+**Highest-traffic edges (read these docs first if you're chasing one):**
+
+| From | To | Via | Where it's documented |
+|---|---|---|---|
+| Dispatch (Ops) | Tech mobile | Magic-link SMS → hub/magic-link.js → Twilio | [dispatch.md §5](features/dispatch.md) + [tech-mobile.md §2](features/tech-mobile.md) |
+| Tech mobile scanner | Gemini | POST hub `/vision/barcodes` + `/vision/equipment` | [vision-ocr.md §2](features/vision-ocr.md) + [tech-mobile.md §3](features/tech-mobile.md) |
+| Ops OCR page | Gemini | POST hub `/vision/invoice` | [vision-ocr.md §3](features/vision-ocr.md) |
+| Customer portal | ERPNext | Authenticated via customer JWT → hub proxies `/api/resource/*` | [customer-portal.md §6](features/customer-portal.md) |
+| Stripe | ERPNext | Webhook → hub `/stripe/webhook` → creates Payment Entry | [billing-payments.md §7](features/billing-payments.md) |
+| Ops dispatch | SSE live updates | hub `/sse` (tech status, job flip, ETA) | [dispatch.md §4](features/dispatch.md) |
+| Agent-flows | Any module | Runtime in hub → triggers any ERPNext op via service token | [flow-editor.md §6](features/flow-editor.md) |
+| GenieACS | Modem-bridge | hub `/acs/probe` → modem-bridge for TP-Link deep params | [cpe-management.md §4](features/cpe-management.md) |
+
+---
+
+## 5. Folder map
 
 ```text
 docs/
 ├── README.md                    ← you are here
 ├── roadmap.md                   ← phase tracker + live module URLs
+│
 ├── architecture/                ← the system itself
 │   ├── overview.md              (services, Docker, Traefik, SSO, retirement plan)
 │   ├── data-model.md            (ERPNext doctypes + "Lead to Live")
-│   └── app-design.md            (Vue/Quasar patterns, feature-sliced layout)
+│   ├── app-design.md            (Vue/Quasar patterns, feature-sliced layout)
+│   └── module-interactions.md   (full call graph + sequence diagrams)
+│
 ├── features/                    ← one doc per business capability
+│   ├── README.md                (per-doc index)
+│   ├── dispatch.md              (Ops dispatch board, scheduling, tags, SMS)
+│   ├── tech-mobile.md           (Gemini-native scanner, equipment UX, JWT)
+│   ├── customer-portal.md       (Plan A magic-link, Stripe self-service)
 │   ├── billing-payments.md      (Stripe, invoices, subscriptions, PPA)
-│   ├── cpe-management.md        (GenieACS, Oktopus, XX230v)
+│   ├── cpe-management.md        (GenieACS, Oktopus, XX230v, modem-bridge)
 │   ├── vision-ocr.md            (Gemini, scan pipeline, offline queue, keys)
 │   └── flow-editor.md           (Flow Template, triggers, runtime)
+│
 ├── reference/                   ← lookup material
 │   ├── erpnext-item-diff.md     (new SKUs vs legacy gestionclient)
 │   └── legacy-wizard/           (read-only snapshot of the PHP wizard)
+│
 ├── assets/                      ← PPTX decks, screenshots, generated diagrams
+│
 └── archive/                     ← frozen docs, do not edit
     ├── HANDOFF-2026-04-18.md
     ├── MIGRATION.md
@@ -51,26 +228,52 @@ docs/
 
 ---
 
-## Conventions
+## 6. Conventions
 
 - **Edit in place.** Don't copy-paste a section into a new file — link to it instead.
-- **Dated snapshots go to `archive/status-snapshots/`.** Don't create `STATUS_YYYY-MM-DD.md` at the root anymore.
-- **Code comments that reference a doc** use the full repo-relative path, e.g.
-  `// See docs/features/vision-ocr.md §10` — so `grep docs/` still surfaces them if we reorganize again.
+- **Module index = source of truth for URLs.** If you change a route or a
+  deployed host, update §2 of this file *and* the relevant feature doc.
+  `grep -r "erp.gigafibre.ca" docs/` should not return stale hostnames.
+- **Cross-doc links use repo-relative paths,** e.g.
+  `[features/dispatch.md](features/dispatch.md)` — so `git mv`ing a doc
+  surfaces every incoming link.
+- **Code comments that reference a doc** use the full repo-relative path,
+  e.g. `// See docs/features/vision-ocr.md §10` — so `grep docs/` still
+  surfaces them if we reorganize again.
+- **Dated snapshots go to `archive/status-snapshots/`.** Don't create
+  `STATUS_YYYY-MM-DD.md` at the root anymore.
 - **The root `README.md`** (one level up) is the repo introduction for
-  non-technical readers; `docs/README.md` (this file) is the engineering index.
+  non-technical readers; `docs/README.md` (this file) is the engineering
+  index.
 
 ---
 
-## What changed on 2026-04-22
+## 7. What changed on 2026-04-22
 
-The docs were flattened out of a single folder into `architecture/`,
-`features/`, `reference/`, `archive/`. Every file move used `git mv` so
-`git log --follow` still works. The old paths
-(`docs/ARCHITECTURE.md`, `docs/VISION_AND_OCR.md`, etc.) no longer exist — if
-you land on one of those links from an external bookmark, use the table above
-to find the new location.
+Big reorganization:
 
-The only place old names still appear is inside
-`archive/HANDOFF-2026-04-18.md` and `archive/status-snapshots/*.md`, where the
-links are intentionally preserved as a frozen historical record.
+1. **New feature docs** added: `dispatch.md`, `customer-portal.md`,
+   `tech-mobile.md`. The first was missing entirely despite being the
+   most-used surface in Ops; the second codifies the Plan A magic-link
+   cutover; the third replaces a stale `tech-mobile.md` that incorrectly
+   referenced `html5-qrcode` (never shipped — scanner has always been
+   native camera + Gemini).
+2. **New architecture doc** added: `module-interactions.md` — the
+   one-page call graph with sequence diagrams for the hot paths (dispatch
+   → SMS → tech scan → equipment install).
+3. **Module index** (§2 above) now lists *every* deployed surface, not
+   just the three that had feature docs. Dispatch, Tickets, Équipe,
+   Rapports, Telephony, Network, Agent Flows, OCR, and every customer-portal
+   page now have a named row.
+4. **Customer portal topology clarified.** `portal.gigafibre.ca` is the
+   live SPA; `client.gigafibre.ca` 307s to portal. The legacy
+   `apps/portal/` tree is retained as historical reference only.
+5. **Earlier flattening (still in effect):** docs were flattened out of a
+   single folder into `architecture/`, `features/`, `reference/`,
+   `archive/`. Every file move used `git mv` so `git log --follow` still
+   works. The old paths (`docs/ARCHITECTURE.md`, `docs/VISION_AND_OCR.md`,
+   etc.) no longer exist — if you land on one of those links from an
+   external bookmark, use §1 above to find the new location. Legacy
+   references remain only inside `archive/HANDOFF-2026-04-18.md` and
+   `archive/status-snapshots/*.md`, where they're preserved as a frozen
+   historical record.
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index 5ed4507..78ba9b5 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -1,11 +1,12 @@
 # Architecture
 
-How the pieces fit together. Read [overview.md](overview.md) first unless you
-have a specific reason not to.
+How the pieces fit together. Read [overview.md](overview.md) first unless
+you have a specific reason not to.
 
 | Doc | Read when… |
 |---|---|
 | [overview.md](overview.md) | You need the full service map — ERPNext, Ops PWA, targo-hub, DocuSeal, Authentik, Traefik, Docker networks, the legacy retirement plan |
+| [module-interactions.md](module-interactions.md) | You're chasing a call across modules — one-page matrix + sequence diagrams for the hot paths (dispatch → SMS → tech scan → equipment install, Stripe webhook → ERPNext, customer portal → hub proxy) |
 | [data-model.md](data-model.md) | You're about to touch ERPNext: Customer, Service Location, Service Subscription, Service Equipment, Sales Invoice, Payment Entry. Also covers the "Lead to Live" customer flow |
 | [app-design.md](app-design.md) | You're building frontend. Feature-sliced layout, Vue/Quasar patterns, Pinia, router, theming, Storybook conventions |
 
diff --git a/docs/architecture/module-interactions.md b/docs/architecture/module-interactions.md
new file mode 100644
index 0000000..4b79df5
--- /dev/null
+++ b/docs/architecture/module-interactions.md
@@ -0,0 +1,329 @@
+# Module Interactions
+
+> The cross-cutting "who talks to whom" reference for the Gigafibre FSM
+> codebase. Every feature doc links here for dependency questions instead of
+> duplicating a matrix of its own.
+>
+> Sibling docs: [overview.md](overview.md) (containers, networks, Traefik) ·
+> [data-model.md](data-model.md) (ERPNext doctypes).
+
+---
+
+## 1. Purpose
+
+The codebase is split into a handful of frontends (`apps/`), a Node.js API
+gateway (`services/targo-hub/`), a couple of side-car services, and a long tail
+of external integrations (ERPNext, Stripe, Twilio, GenieACS, etc.). Any given
+feature crosses three or four of these layers, which means the interesting
+question is rarely "what does module X do" but "when module X does its job,
+who does it call, and who reacts to the side-effect?".
+
+This document is the single authoritative answer to that question. Feature
+docs in [../features/](../features/README.md) describe a capability end-to-end
+and link back here for the cross-module picture. If you are adding a new
+module or moving an existing call, update this file first.
+
+---
+
+## 2. Module catalog
+
+### 2.1 Apps (frontends)
+
+| Module | Host / Route | Owns | Feature doc |
+|---|---|---|---|
+| `apps/ops` | `erp.gigafibre.ca/ops/#/*` | Staff PWA — Dispatch, Clients, Tickets, Équipe, Rapports, OCR, Téléphonie, Agent Flows, Réseau, Settings. Also serves the tech mobile tree `/j/*` (same bundle, different layout). Routes registered in [`apps/ops/src/router/index.js`](../../apps/ops/src/router/index.js). | [billing-payments.md](../features/billing-payments.md) · [cpe-management.md](../features/cpe-management.md) · [vision-ocr.md](../features/vision-ocr.md) · [flow-editor.md](../features/flow-editor.md) |
+| `apps/client` | `portal.gigafibre.ca/#/*` | Customer portal PWA — Dashboard, Invoices, Tickets, Messages, Account, Catalog/Cart, payment return landings. Hash router, routes in [`apps/client/src/router/index.js`](../../apps/client/src/router/index.js). Plan A: passwordless magic-link JWT, no Authentik. | [billing-payments.md §4](../features/billing-payments.md) |
+| `apps/field` | `/field/` (legacy) | Original Quasar tech app. Being retired in favour of `apps/ops` `/j/*` + SMS magic-link. See §8. | — |
+| `apps/website` | `www.gigafibre.ca` | React + Vite marketing site. Lead-capture form posts to targo-hub `/api/checkout` / `/api/order`. Built from [`apps/website/`](../../apps/website/). | — |
+| `apps/portal` | (Traefik only) | Not a runtime. Holds [`traefik-client-portal.yml`](../../apps/portal/traefik-client-portal.yml) which permanently redirects the legacy host `client.gigafibre.ca` → `portal.gigafibre.ca`, so stale SMS and bookmarks keep working. | — |
+
+### 2.2 Services (backends we own)
+
+| Module | Host / Port | Owns | Notes |
+|---|---|---|---|
+| `services/targo-hub` | `msg.gigafibre.ca:3300` | API gateway / monolith. Routes registered in [`services/targo-hub/server.js`](../../services/targo-hub/server.js). Every external integration (Twilio, Stripe, Mailjet, Gemini, GenieACS, Oktopus, Traccar) is reached *through* the hub — frontends never hit those directly. | Lib catalog below. |
+| `services/modem-bridge` | `:3301` (internal) | Playwright + headless Chromium driving TP-Link XX230v web UI to read encrypted TR-181 parameters the vendor exposes only via client-side JS. Token auth, internal network only. | [`services/modem-bridge/server.js`](../../services/modem-bridge/server.js) |
+| `services/docuseal` | `sign.gigafibre.ca` | DocuSeal container for commercial-contract e-signature. Residential contracts use a JWT-based acceptance flow (see `lib/acceptance.js` + `lib/contracts.js`) — DocuSeal is the commercial track. | — |
+| `services/legacy-db` | `10.100.80.100:3307` | Read-only MariaDB bridge into the old PHP `gestionclient` database. Used by migration scripts and a handful of lookup queries in `lib/auth.js`. | [`services/legacy-db/docker-compose.yml`](../../services/legacy-db/docker-compose.yml) |
+
+#### targo-hub library map (`services/targo-hub/lib/`)
+
+One file per capability; the router in `server.js` dispatches by path prefix.
+
+| File | Mount point | Responsibility |
+|---|---|---|
+| `acceptance.js` | `/accept*` | Residential contract acceptance tokens — JWT sign + signed-blob storage on Quotation. |
+| `address-search.js` | (lib) | Calls the Supabase `rddrjzptzhypltuzmere` RQA address database for autocomplete. |
+| `agent.js` | `/agent/*` | LLM agent runtime + tool-use dispatch (reads `agent-tools.json`). |
+| `ai.js` | `/ai/*` | Internal AI decision-making powered by Gemini Flash (classification, summaries, suggestions). |
+| `auth.js` | `/auth/*` | Staff auth bridge — reads Authentik headers, optionally checks legacy `gestionclient` MySQL for migration. |
+| `checkout.js` | `/api/catalog`, `/api/checkout`, `/api/accept-for-client`, `/api/order`, `/api/address`, `/api/otp` | Onboarding wizard: catalog → cart → OTP → order. Creates ERPNext Lead/Quotation/Customer. |
+| `config.js` | (lib) | Environment variable accessor with typed defaults. |
+| `contracts.js` | `/contract*` | Signed-contract lifecycle — residential JWT and commercial DocuSeal. |
+| `conversation.js` | `/conversations*` | Threaded inbox: SMS, email, web chat → ERPNext Communication / HD Ticket. |
+| `device-extractors.js` | (lib) | Pure functions to extract WAN/LAN/WiFi/optical facts from GenieACS device JSON. |
+| `device-hosts.js` | (lib) | `Device.Hosts.Host.{n}.*` TR-181 host list parser. |
+| `devices.js` | `/devices`, `/acs/*` | GenieACS NBI proxy — device lookup, presets, tasks, diagnostic summary. |
+| `dispatch.js` | `/dispatch*` | Dispatch Job assignment scoring, tech-to-job matching. |
+| `email-templates.js` | (lib) | HTML templates for OTP, magic-link, invoice email. |
+| `email.js` | (lib) | SMTP transport (Mailjet `in-v3.mailjet.com` per `config.js`). |
+| `flow-api.js` | `/flow/start`, `/flow/advance`, `/flow/complete`, `/flow/event`, `/flow/runs/*` | HTTP endpoints for the flow runtime. |
+| `flow-runtime.js` | (lib) | Execution engine for Flow Templates — `dispatchEvent()` is how modules fire triggers. |
+| `flow-templates.js` | `/flow/templates*` | CRUD for Flow Template doctype. |
+| `helpers.js` | (lib) | HTTP client, ERPNext REST wrapper (`erpFetch`, `erpRequest`), JSON response helper. |
+| `ical.js` | `/dispatch/ical-token/:tech`, `/dispatch/calendar/:tech.ics` | Signed-token iCal feed — lets techs subscribe their jobs in Apple/Google Calendar. |
+| `magic-link.js` | `/magic-link*` | JWT sign/verify + one-time magic-link issuance. |
+| `modem-bridge.js` | `/modem*` | Thin client for the modem-bridge sidecar. |
+| `network-intel.js` | `/network/*` | InfluxDB + Grafana log analysis → Gemini summarization. |
+| `oktopus-mqtt.js` | (worker) | MQTT subscriber to the Oktopus broker — compensates for their broken events-controller hook. |
+| `oktopus.js` | `/oktopus/*` | Oktopus CE REST API — TR-369/USP device preauth and provisioning. |
+| `olt-snmp.js` | `/olt*` | SNMP poller for ONU status / optical power on the OLTs. |
+| `otp.js` | (lib) | One-time-password issuance + email/SMS delivery (used by checkout + portal). |
+| `outage-monitor.js` | `/webhook/kuma` | Uptime-Kuma webhook ingest; cross-references OLT poller to synthesize mass-outage alerts. |
+| `payments.js` | `/payments*`, `/webhook/stripe` | Stripe Checkout session creation, customer portal links, webhook verification, Payment Entry reconciliation, PPA cron. Fires `on_payment_received` flow trigger. |
+| `pbx.js` | `/webhook/3cx/call-event` | 3CX call-event webhook → ERPNext Communication. |
+| `portal-auth.js` | `/portal/*` | Passwordless magic-link endpoint `POST /portal/request-link` — rate-limited, anti-enumeration. |
+| `project-templates.js` | (lib) | Hard-coded job-template catalogue (fibre_install, etc.) for dispatch. |
+| `provision.js` | `/provision/*` | Device provisioning orchestrator — GenieACS preset push + Oktopus preauth. |
+| `referral.js` | `/api/referral/*` | Referral credit validation + application, backing the wizard. |
+| `reports.js` | `/reports*` | GL / revenue / tax / A/R reports, Frappe PostgreSQL queries. |
+| `sse.js` | `/sse`, `/broadcast` | Server-Sent Events fan-out. Topics: `customer:*`, `conversations`, `dispatch`, etc. |
+| `tech-absence-sms.js` | (worker) | Auto-notify customers when their tech is absent. |
+| `tech-mobile.js` | `/t/*` | Lightweight mobile tech page (predecessor of `/j/*`). |
+| `telephony.js` | `/telephony/*` | Routr / identity SIP pool management. |
+| `traccar.js` | `/traccar*` | Traccar REST API proxy (GPS fleet tracker). |
+| `twilio.js` | `/send/sms`, `/webhook/twilio/sms-*`, `/voice/*` | Twilio SMS send + inbound webhook + Voice tokens + TwiML. |
+| `vision.js` | `/vision/barcodes`, `/vision/equipment`, `/vision/invoice` | Gemini 2.5 Flash vision OCR endpoints. |
+| `voice-agent.js` | `/voice/inbound`, `/voice/gather`, `/voice/connect-agent`, `/voice/ws` | Twilio IVR + agent runtime with Media Streams WebSocket. |
+
+### 2.3 External integrations
+
+| Provider | Used from | Channel | Purpose |
+|---|---|---|---|
+| ERPNext v16 / Frappe | hub (`helpers.erpFetch`), ops (nginx proxy), client (via hub) | REST `/api/resource`, `/api/method` | Source of truth for Customer, Subscription, Invoice, Ticket, Dispatch Job, etc. |
+| Authentik SSO | Traefik ForwardAuth middleware | Header injection | Guards staff surfaces (`/ops/`, `n8n.`, `hub.`). |
+| Twilio | `lib/twilio.js`, `lib/voice-agent.js` | SMS / Voice (REST + webhook + Media Streams WS) | SMS magic-links, OTP, IVR, Voice tokens. |
+| Stripe | `lib/payments.js` | REST + webhook (`Stripe-Signature`) | Checkout sessions, Billing Portal, card-on-file, Klarna BNPL. |
+| Mailjet | `lib/email.js` (SMTP `in-v3.mailjet.com`) | SMTP | Transactional email (OTP, invoices, magic-links). |
+| GenieACS | `lib/devices.js`, `helpers.nbiRequest` | NBI REST / TR-069 | Modem provisioning + diagnostics (legacy CPE fleet). |
+| Oktopus CE | `lib/oktopus.js`, `lib/oktopus-mqtt.js` | REST + MQTT (TR-369/USP) | New CPE fleet. |
+| Traccar | `lib/traccar.js` | REST + WebSocket | GPS breadcrumbs for field techs. |
+| Gemini 2.5 Flash | `lib/vision.js`, `lib/ai.js` | REST (`generativelanguage.googleapis.com`) | Vision OCR + internal AI. |
+| n8n | (via Authentik header proxy) | REST | Workflow automation — long-running batch jobs. |
+| DocuSeal | `sign.gigafibre.ca` | REST + webhook | Commercial contract e-signature. |
+
+---
+
+## 3. Interaction matrix
+
+Row = caller, column = callee. Cell = primary channel (`REST`, `SSE`, `WS`,
+`MQTT`, `SMS`, `SMTP`, `TR-069`, `TR-369`, `Webhook`, `JWT`, `ForwardAuth`,
+iCal). Empty = no direct interaction (use the hub as a relay).
+
+| caller ↓ / callee → | ops | client | field | hub | ERPNext | GenieACS | Oktopus | Traccar | Twilio | Stripe | Gemini | Authentik | DocuSeal |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| **ops**     | —   | —   | —   | REST + SSE | REST (nginx proxy w/ token) | — (via hub) | — (via hub) | WS (via hub proxy) | — (via hub) | — (via hub) | — (via hub `/vision`) | ForwardAuth | — |
+| **client**  | —   | —   | —   | REST + SSE | — (via hub) | — | — | — | — (via hub) | — (via hub `checkout-link`) | — (via hub) | JWT (magic-link, not Authentik) | — |
+| **field**   | —   | —   | —   | REST | REST (legacy, token) | — | — | — | — | — | — | — | — |
+| **website** | —   | —   | —   | REST (`/api/checkout`, `/api/order`) | — (via hub) | — | — | — | — | — | — | — | — |
+| **hub**     | SSE | SSE | —   | —   | REST (`erpFetch`, `Authorization: token ...`) | REST (NBI `nbiRequest`) | REST + MQTT | REST + WS | SMS REST + Webhook | REST + Webhook (`Stripe-Signature`) | REST | — | REST + Webhook |
+| **modem-bridge** | — | — | — | — (hub calls it, `:3301`) | — | — | — | — | — | — | — | — | — |
+| **ERPNext** | —   | —   | —   | — (fire-and-forget HTTP to hub `/flow/*` from server scripts) | — | — | — | — | — | — | — | — | — |
+| **Traefik** | Forwards | Forwards | Forwards | Forwards | Forwards | — | — | — | — | — | — | ForwardAuth | — |
+| **Twilio**  | —   | —   | —   | Webhook (`/webhook/twilio/*`) | — | — | — | — | — | — | — | — | — |
+| **Stripe**  | —   | —   | —   | Webhook (`/webhook/stripe`) | — | — | — | — | — | — | — | — | — |
+| **DocuSeal**| —   | —   | —   | Webhook (`/contract/*`) | — | — | — | — | — | — | — | — | — |
+
+---
+
+## 4. Canonical flows
+
+Six flows cover 90 % of the interactions. Each is grounded in the hub lib
+file that drives it.
+
+### 4.1 New customer onboarding
+
+```text
+apps/website (React lead form)
+    │ POST /api/order  (lib/checkout.js)
+    ▼
+targo-hub  ──► address-search.js  ──► Supabase RQA
+           ──► otp.js              ──► Twilio SMS + Mailjet SMTP
+           ──► erpFetch            ──► ERPNext (Lead → Quotation → Customer)
+           ──► payments.js         ──► Stripe Checkout session
+    │
+    │ user pays
+    ▼
+Stripe ──webhook──► hub /webhook/stripe  (lib/payments.js, Stripe-Signature verify)
+                                         ├─► ERPNext Payment Entry
+                                         ├─► flow-runtime.dispatchEvent('on_payment_received')
+                                         │      ├─► contracts.js  (DocuSeal or JWT accept)
+                                         │      └─► dispatch.js    (create Dispatch Job)
+                                         └─► sse.broadcast('customer:<name>', ...)
+```
+
+Feature doc: [billing-payments.md](../features/billing-payments.md).
+
+### 4.2 Tech dispatches a job
+
+```text
+apps/ops /dispatch  (DispatchPage.vue)
+    │ drag-drop assignment, POST /dispatch/assign (lib/dispatch.js)
+    ▼
+hub  ──► ERPNext Dispatch Job (scoring weights in dispatch.js)
+     ──► twilio.sendSms       →  customer cell:  "/j/<JWT>"
+    │
+    ▼
+Tech opens /j/<JWT> on phone   (apps/ops/src/modules/tech/*)
+    │ JWT verified by magic-link.js
+    │ GPS check-in → traccar.js → Traccar REST → WS breadcrumbs back to ops
+    │ Scan device barcode → useScanner → /vision/barcodes → Gemini
+    │ Mark complete → flow-runtime.dispatchEvent('on_job_complete')
+    ▼
+ops SSE topic `dispatch` refreshes the Kanban
+```
+
+Feature docs: [cpe-management.md](../features/cpe-management.md) (device scan) ·
+[vision-ocr.md](../features/vision-ocr.md) (OCR pipeline) ·
+[flow-editor.md](../features/flow-editor.md) (post-job trigger).
+
+### 4.3 Customer pays an invoice from the portal
+
+```text
+apps/client /#/invoices/INV-0000123   (InvoiceDetailPage.vue)
+    │ click "Payer maintenant"
+    │ POST /billing/checkout-link (lib/payments.js)
+    ▼
+hub  ──► Stripe Checkout session (mode=payment, client_reference_id=INV-…)
+    │ browser redirects to Stripe, user pays
+    ▼
+Stripe ──webhook──► hub /webhook/stripe
+                    ├─► ERPNext Payment Entry
+                    ├─► flow-runtime.dispatchEvent('on_payment_received')
+                    └─► sse.broadcast('customer:<name>', 'invoice.paid', …)
+    ▼
+Both apps/ops (cust detail) and apps/client (dashboard) update live over SSE.
+```
+
+### 4.4 Customer requests support
+
+```text
+apps/client /#/messages  (MessagesPage.vue)
+    │ POST /conversations  (lib/conversation.js)
+    ▼
+hub  ──► ERPNext HD Ticket  (erpFetch)
+     ──► sse.broadcast('conversations', …)
+    ▼
+apps/ops /tickets  (TicketsPage.vue)  — live refresh
+    │ staff replies → conversation.handle → ERPNext Communication
+    ▼
+hub ──► twilio.sendSms (if customer channel = SMS) or email.js (if email)
+```
+
+### 4.5 Modem diagnostic from ops
+
+```text
+apps/ops /network  (NetworkPage.vue)
+    │ GET /devices/lookup?serial=…  (lib/devices.js)
+    ▼
+hub  ──► GenieACS NBI  (helpers.nbiRequest)
+    │ if TP-Link XX230v → ask modem-bridge :3301 for encrypted params
+    ▼
+modem-bridge  ──► Playwright headless Chromium  ──► modem web UI (172.17.x.x:443)
+              ──► decrypted TR-181 JSON back to hub
+    ▼
+hub  ──► device-extractors.summarizeDevice  → consolidated JSON
+    ▼
+ops UI renders WAN / LAN / WiFi / Optical; SSE topic `customer:<name>`
+updates any other ops tab watching the same client.
+```
+
+Feature doc: [cpe-management.md](../features/cpe-management.md).
+
+### 4.6 Passwordless login (customer)
+
+```text
+apps/client /#/login  (LoginPage.vue)
+    │ POST /portal/request-link  (lib/portal-auth.js)
+    │   rate-limited, anti-enumeration (constant-time response)
+    ▼
+hub  ──► otp.js / magic-link.js  (JWT HS256, 24h exp)
+     ──► twilio.sendSms    ("Votre lien: https://portal.gigafibre.ca/#/?token=…")
+     ──► email.js (SMTP Mailjet)
+    ▼
+customer clicks link → apps/client router guard hydrates store from token
+                      → store.customerId set → dashboard loads
+```
+
+---
+
+## 5. Authentication matrix
+
+| Surface | Mechanism | Source of trust | Notes |
+|---|---|---|---|
+| Staff apps (ops, n8n, hub UI) | Authentik ForwardAuth via Traefik `authentik-client@file` middleware | `id.gigafibre.ca` session cookie | Headers `X-Authentik-Email`, `X-Authentik-Groups` injected into upstream. |
+| Customer portal (`apps/client`) | 24 h HS256 JWT (magic-link) | `lib/magic-link.js` secret | No Authentik; no password form reachable (Traefik redirects legacy `/login`). |
+| Tech mobile (`/j/*` inside `apps/ops`) | 24 h HS256 JWT sent by SMS | Same secret | Same JWT primitive as portal. |
+| hub → ERPNext | `Authorization: token <key>:<secret>` (Frappe API token) | ERPNext Administrator token — never regenerate ("Generate Keys" in ERPNext UI breaks the hub) | Used by `helpers.erpFetch`. |
+| ops → ERPNext (frontend) | nginx same-origin reverse proxy injects the same token server-side | Token stays server-side; browser never sees it | See `apps/ops/infra/`. |
+| Webhooks | Per-provider signature verification | `Stripe-Signature`, `X-Twilio-Signature`, DocuSeal shared secret | Rejected synchronously before any side-effect. |
+| `modem-bridge` | Shared bearer token | env var on both hub + bridge containers | Internal network only, not exposed via Traefik. |
+| Traccar | Bearer token preferred (fall-back Basic) | env var on hub | See `lib/traccar.js` header note. |
+
+---
+
+## 6. Data ownership
+
+Source of truth per entity. "Hub cache" means the hub keeps a read-through
+copy; the authoritative write goes to the listed owner.
+
+| Entity | Source of truth | Hub role | Frontend read path |
+|---|---|---|---|
+| Customer | ERPNext `Customer` | thin pass-through (`erpFetch`) | ops: direct via nginx proxy · client: via hub |
+| Address (Service Location) | ERPNext `Service Location` | pass-through; `address-search.js` also calls Supabase RQA for autocomplete | — |
+| Subscription | ERPNext `Subscription` | pass-through | — |
+| Invoice | ERPNext `Sales Invoice` | pass-through + `/vision/invoice` OCR | — |
+| Payment | ERPNext `Payment Entry` | written from Stripe webhook in `lib/payments.js` | — |
+| Ticket | ERPNext `HD Ticket` | written from `lib/conversation.js` | — |
+| Dispatch Job | ERPNext `Dispatch Job` (custom doctype) | written from `lib/dispatch.js` | ops SSE topic `dispatch` |
+| Technician | ERPNext `Technician` (custom) | pass-through | — |
+| Service Equipment | ERPNext `Service Equipment` (custom) | pass-through | — |
+| Tag | ERPNext `Tag` | pass-through | — |
+| Flow Template | ERPNext `Flow Template` (custom) | CRUD in `lib/flow-templates.js` | ops `/agent-flows` |
+| Flow Run | ERPNext `Flow Run` (custom) | written from `lib/flow-runtime.js` | ops `/agent-flows` |
+| **Exceptions** |  |  |  |
+| Live modem state (WAN IP, SNR, host list) | GenieACS / Oktopus | hub never persists — always fetched live | — |
+| GPS breadcrumbs | Traccar | hub proxies WS + REST | ops `/dispatch` map |
+| JWT sessions | hub process memory + browser `localStorage` | — | no server-side session store |
+
+---
+
+## 7. Real-time channels
+
+| Channel | Transport | Producer | Consumer | Topic / payload |
+|---|---|---|---|---|
+| Ops / portal live updates | SSE | `lib/sse.js` | `apps/ops`, `apps/client` | `customer:<name>`, `conversations`, `dispatch`, ad-hoc |
+| TR-369 device events | MQTT | Oktopus broker | `lib/oktopus-mqtt.js` worker | device-online, heartbeat |
+| GPS breadcrumbs | WebSocket | Traccar | `lib/traccar.js` proxy → ops dispatch | `deviceId`, `latitude`, `longitude`, `speed` |
+| Twilio Media Streams | WebSocket upgrade on hub `/voice/ws` | Twilio | `lib/voice-agent.js` | raw audio frames for IVR agent |
+| SSE keep-alive | server-pushed `: ping` | `lib/sse.js` 25 s interval | browsers | heartbeat |
+
+---
+
+## 8. Retired / in-retirement
+
+Do not build new features on these. Linked target is where the replacement
+lives.
+
+| Retiring | Replacement | Status | Notes |
+|---|---|---|---|
+| `auth.targo.ca` | `id.gigafibre.ca` (Authentik) | active migration | ForwardAuth middleware already on the new host. |
+| `apps/field` | `apps/ops` `/j/*` tree | in retirement | Same bundle, different layout — removes the separate deploy surface. |
+| `dispatch-app` (legacy standalone) | `apps/ops` `/dispatch` | retired | Feature parity reached; decommission pending DNS cleanup. |
+| `client.gigafibre.ca` | `portal.gigafibre.ca` | retired | Traefik permanent-redirect via [`apps/portal/traefik-client-portal.yml`](../../apps/portal/traefik-client-portal.yml). |
+| Frappe `/login` form for customers | `/portal/request-link` magic-link | retired | Legacy MD5 hashes not migrated — customers forced through the new flow. |
+| Ollama local `llama3.2-vision` | `lib/vision.js` → Gemini 2.5 Flash | retired | Ops VM has no GPU. |
+
+---
+
+Back to [docs/README.md](../README.md).
diff --git a/docs/features/README.md b/docs/features/README.md
index 6804a07..16a0922 100644
--- a/docs/features/README.md
+++ b/docs/features/README.md
@@ -6,9 +6,16 @@ modes. Open the one that matches the feature you're changing.
 
 | Doc | Owns |
 |---|---|
+| [dispatch.md](dispatch.md) | Ops dispatch board: drag-and-drop scheduling, tech assignment with skill tags, travel-time optimization, magic-link SMS issuance, live SSE updates |
+| [tech-mobile.md](tech-mobile.md) | Field tech app (three surfaces: SSR `/t/{jwt}`, transitional `apps/field/`, unified `/ops/#/j/*`). Native camera → Gemini scanner, equipment install/remove, JWT auth, offline queue |
+| [customer-portal.md](customer-portal.md) | Passwordless customer self-service at `portal.gigafibre.ca`: magic-link email (24h JWT), invoice + ticket view, Stripe-linked payment flows |
 | [billing-payments.md](billing-payments.md) | Stripe integration (Checkout, Billing Portal, webhook), subscription lifecycle, invoice generation, payment reconciliation, PPA (Plan de paiement automatique), Klarna BNPL |
-| [cpe-management.md](cpe-management.md) | CPE fleet: GenieACS (TR-069), Oktopus (TR-369), provisioning, diagnostics, TP-Link XX230v / Deco deep probe, migration plan |
+| [cpe-management.md](cpe-management.md) | CPE fleet: GenieACS (TR-069), Oktopus (TR-369), provisioning, diagnostics, TP-Link XX230v / Deco deep probe via modem-bridge, migration plan |
 | [vision-ocr.md](vision-ocr.md) | Camera-based scanning via Gemini 2.5 Flash — barcode, equipment label, invoice OCR. Hub endpoints `/vision/*`, `useScanner` composable, offline queue, AI_API_KEY rotation policy, ERPNext relationships triggered by a scan |
 | [flow-editor.md](flow-editor.md) | Agent-flows module: Flow Template + Flow Run doctypes, trigger catalogue, step types, runtime contract, UI editor at `/ops/#/agent-flows` |
 
+**Cross-module map:** see
+[../architecture/module-interactions.md](../architecture/module-interactions.md)
+for the full call graph + sequence diagrams.
+
 Back to [docs/README.md](../README.md) · [roadmap.md](../roadmap.md)
diff --git a/docs/features/customer-portal.md b/docs/features/customer-portal.md
new file mode 100644
index 0000000..7d48af1
--- /dev/null
+++ b/docs/features/customer-portal.md
@@ -0,0 +1,707 @@
+# Customer Portal — Architecture & Integration Guide
+
+> Authoritative reference for the Gigafibre customer portal: the Vue 3 +
+> Quasar SPA at `portal.gigafibre.ca`, its passwordless magic-link
+> authentication, and the standalone `nginx:alpine` container that serves
+> it. Companion document to [../architecture/overview.md](../architecture/overview.md)
+> and [../architecture/data-model.md](../architecture/data-model.md).
+>
+> Last updated: 2026-04-22. Plan A (magic-link login replacing ERPNext
+> `/login`) shipped today. See commits `2b04e6b` and `7ac9a58` for the
+> deploy-topology cutover.
+
+---
+
+## 1. Goals & Principles
+
+The customer portal is the only front door a residential or commercial
+customer ever sees. It replaces the legacy PHP portal and the ERPNext
+`/login` password form; staff continue to use Authentik (`ops.gigafibre.ca`
+/ `erp.gigafibre.ca`) and never touch the portal host.
+
+Design tenets:
+
+1. **Passwordless by default.** The customer types an email or phone, the
+   hub mails/SMSes a 24 h JWT, the SPA decodes it client-side. No password,
+   no session cookie, no Authentik for customers — rationale documented in
+   `~/.claude/projects/-Users-louispaul-Documents-testap/memory/project_portal_auth.md`
+   (legacy passwords are unsalted MD5 and cannot be trusted).
+2. **Anti-enumeration by contract.** `POST /portal/request-link` *always*
+   returns `HTTP 200 {"ok":true, "sent":[…]}`. An unknown identifier returns
+   `sent: []`. An attacker cannot use the endpoint to probe whether an email
+   or phone is in our customer database.
+3. **Rate limit the send surface.** 3 requests per 15-minute window per
+   identifier (case-insensitive). Survives restart loss gracefully — the
+   Map is in-memory and repopulates on the next abuse attempt.
+4. **Both channels, best effort.** A customer with both email and phone
+   gets the link on both — SMS failure does not block email, and vice versa.
+   The `sent: [...]` array tells the UI which channels actually delivered
+   so it can display redacted destinations.
+5. **Two routes, one SPA.** `portal.gigafibre.ca` is the canonical host.
+   `client.gigafibre.ca` is a 307 redirect at the Traefik layer so stale
+   bookmarks, SMS notifications from before the cutover, and old invoice
+   links still land on the right place.
+6. **Hash router, not path router.** The SPA uses `createWebHashHistory`
+   so the token survives behind the `#` and never reaches nginx. Also lets
+   the single `index.html` serve every route without per-path nginx rules.
+7. **Retire, don't migrate.** ERPNext's `/login` is dead for customers —
+   there is no "staff impersonation" path in the passwordless flow. Staff
+   who need to act as a customer use the Ops "Send magic link" action on
+   the client-detail page (implemented via `POST /portal/request-link`).
+
+---
+
+## 2. Topology & Deployment
+
+### 2.1 Hosts & routing
+
+```
+                            ┌───────────────────────────────────────┐
+                            │  Traefik (erp.gigafibre.ca:443)       │
+                            │  *.gigafibre.ca wildcard → 96.125.196.67│
+                            └───────────────────────────────────────┘
+                                │                 │                │
+                                ▼                 ▼                ▼
+          ┌───────────────────────┐  ┌────────────────────┐  ┌──────────────┐
+          │ portal.gigafibre.ca   │  │ client.gigafibre.ca│  │ erp.*/ops.*  │
+          │   (canonical host)    │  │   (legacy alias)   │  │   (staff)    │
+          ├───────────────────────┤  ├────────────────────┤  ├──────────────┤
+          │ docker container      │  │ Traefik dynamic    │  │ ERPNext      │
+          │   client-portal       │  │ route — 307 to     │  │ frontend +   │
+          │   image nginx:alpine  │  │ portal.gigafibre.ca│  │ Authentik    │
+          │   bind-mounts         │  │ /$1 (preserves     │  │ forwardAuth  │
+          │   /opt/client-app/    │  │  path)             │  │              │
+          │     ─ index.html      │  │                    │  │ NO customer  │
+          │     ─ assets/*        │  │ (traefik-client-   │  │ /login form  │
+          │     ─ nginx.conf      │  │  portal.yml)       │  │ — endpoint is│
+          │     ─ docker-compose  │  │                    │  │ blocked by   │
+          └───────────────────────┘  └────────────────────┘  │ redirect     │
+                                                             └──────────────┘
+
+                                              ▲
+                                              │ magic-link JWT + REST
+                                              │   (msg.gigafibre.ca)
+                                              │
+                                     ┌──────────────────┐
+                                     │   targo-hub      │
+                                     │   portal-auth.js │
+                                     │   magic-link.js  │
+                                     └──────────────────┘
+                                              │
+                                              │  resource REST
+                                              ▼
+                                     ┌──────────────────┐
+                                     │ ERPNext backend  │
+                                     │ (Customer, Sales │
+                                     │  Invoice, Issue) │
+                                     └──────────────────┘
+```
+
+### 2.2 Two distinct Vue builds used to coexist — no more
+
+Before 2026-04-22 the same Vue SPA was built twice: once with
+`base=/assets/client-app/` and dropped into the ERPNext public folder so
+ERPNext's frontend would serve it at `client.gigafibre.ca/assets/client-app/`;
+a second build ran for local dev. That's retired — we now build with
+`base=/` and ship to a standalone nginx container.
+
+`apps/client/quasar.config.js` keeps `/assets/client-app/` as the fallback
+so a local `quasar dev` still works, but production always overrides with
+`DEPLOY_BASE=/`:
+
+```js
+// apps/client/quasar.config.js
+extendViteConf (viteConf) {
+  viteConf.base = process.env.DEPLOY_BASE || '/assets/client-app/'
+}
+```
+
+```bash
+# apps/client/deploy.sh (prod build)
+VITE_ERP_TOKEN="…" DEPLOY_BASE=/ npx quasar build -m pwa
+```
+
+### 2.3 `deploy.sh` — atomic swap + the inode gotcha
+
+The deploy does three things remotely:
+
+1. Upload the fresh build into a staging directory (`mktemp -d
+   /opt/client-app.new.XXXXXX`).
+2. `mv` the live `/opt/client-app` aside (`/opt/client-app.bak.<epoch>`),
+   then `mv` the staging dir onto `/opt/client-app`. This is atomic —
+   nginx never sees a half-written `index.html` referencing hashed assets
+   that haven't finished uploading.
+3. Keep the three most recent backups, delete older ones.
+
+Then the non-obvious part:
+
+> **Docker bind mounts follow the inode, not the path.** When `docker run`
+> records a bind mount, it resolves `/opt/client-app` once and pins that
+> inode. After the atomic `mv` swap, the container is still pointed at the
+> *old* directory (now `/opt/client-app.bak.<epoch>`) — so you'd serve
+> stale content from the backup until you recreate the mount.
+>
+> Fix: `docker restart client-portal` at the end of the deploy. The
+> restart re-resolves the bind and the container picks up the new inode.
+
+That `docker restart` line is the entire reason `deploy.sh` needed an
+update today; previously we relied on the bind mount "just reflecting the
+new files" which only works when you edit them in place, not when you
+swap the entire directory.
+
+### 2.4 Local build only
+
+```bash
+./deploy.sh local    # build with DEPLOY_BASE=/ into dist/pwa/, no upload
+```
+
+Handy when you want to test the PWA manifest / service worker path
+behaviour before shipping.
+
+---
+
+## 3. File Inventory
+
+### 3.1 Front-end — `apps/client/`
+
+| Path                                             | Responsibility                                                           |
+|--------------------------------------------------|--------------------------------------------------------------------------|
+| `deploy.sh`                                      | Build + rsync + atomic swap + `docker restart client-portal`             |
+| `quasar.config.js`                               | Vite base override (`DEPLOY_BASE`), hash router, PWA manifest            |
+| `src/App.vue`                                    | Root — calls `store.init()` once on mount                                |
+| `src/router/index.js`                            | Routes + navigation guard (pushes unauthenticated to `/login`)           |
+| `src/layouts/PortalLayout.vue`                   | Drawer + header + cart badge, shows customer name                        |
+| `src/stores/customer.js`                         | Pinia store: `hydrateFromToken`, JWT decode, `stripTokenFromUrl`, `init` |
+| `src/stores/cart.js`                             | Pinia store for the public catalog cart                                  |
+| `src/composables/useMagicToken.js`               | Read-through: `{authenticated, expired, customerId}` for payment pages   |
+| `src/composables/useSSE.js`                      | EventSource wrapper for `msg.gigafibre.ca/sse` (topic-based)             |
+| `src/composables/useFormatters.js`               | `formatDate`, `formatMoney`, `formatShortDate`, `formatPrice`            |
+| `src/composables/useOTP.js`                      | OTP send/verify for catalog checkout existing-customer path              |
+| `src/composables/useAddressSearch.js`            | RQA address autocomplete wrapper                                         |
+| `src/composables/usePolling.js`                  | Generic polling helper                                                   |
+| `src/api/auth-portal.js`                         | `requestPortalLink()` — posts to hub `/portal/request-link`              |
+| `src/api/auth.js`                                | `authFetch()` wraps ERPNext REST with service token (`VITE_ERP_TOKEN`)   |
+| `src/api/portal.js`                              | ERPNext REST client: invoices, tickets, profile, service locations, comms |
+| `src/api/payments.js`                            | Hub client: balance, methods, checkout, setup card, billing portal, PPA  |
+| `src/api/catalog.js`                             | Hub client: catalog, checkout, address search, OTP                       |
+| `src/pages/*.vue`                                | One page per route (see §4)                                              |
+
+### 3.2 Back-end — `services/targo-hub/lib/`
+
+| Path                 | Responsibility                                                                       |
+|----------------------|--------------------------------------------------------------------------------------|
+| `portal-auth.js`     | `POST /portal/request-link` — lookup, mint JWT, dispatch SMS + email, rate limit     |
+| `magic-link.js`      | `generateCustomerToken()` — HS256 JWT with `scope=customer`, 24 h TTL                |
+| `config.js`          | `CLIENT_PORTAL_URL`, `JWT_SECRET` — wired to `portal.gigafibre.ca` by default        |
+| `helpers.js`         | `lookupCustomerByPhone()` — last-10-digit match across `cell_phone`, `tel_home`, `tel_office` |
+| `twilio.js`          | `sendSmsInternal()` — used for the SMS channel                                       |
+| `email.js`           | `sendEmail()` — used for the email channel                                           |
+| `checkout.js` / `payments.js` | Stripe endpoints that the portal hits from `InvoiceDetailPage`              |
+| `conversation.js`    | SSE topic `conversations` + `customer:<id>` for real-time inbox updates              |
+
+### 3.3 Traefik — `apps/portal/`
+
+| Path                         | Responsibility                                                             |
+|------------------------------|----------------------------------------------------------------------------|
+| `traefik-client-portal.yml`  | Dynamic route: `Host(\`client.gigafibre.ca\`)` → 307 to `portal.…/$1`      |
+| `deploy-portal.sh`           | `scp` the YAML to `/opt/traefik/dynamic/client-portal.yml` + smoke-test    |
+
+---
+
+## 4. Routes & Pages
+
+The router uses `createWebHashHistory`, so every URL above the portal
+root looks like `https://portal.gigafibre.ca/#/<path>`. Route paths in
+French match the customer-facing UI vocabulary (`/me`, `/panier`,
+`/paiement/merci`, `/commande/confirmation`).
+
+| Path                          | Name                | Purpose                                                                   | Endpoints                                                                                                                                                   |
+|-------------------------------|---------------------|---------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `/login`                      | `login`             | Passwordless login form — email or phone input, sent state, rate banner   | hub `POST /portal/request-link`                                                                                                                             |
+| `/`                           | `dashboard`         | "Bonjour, {name}" + unpaid count + open tickets + 5 most recent invoices  | ERPNext `Sales Invoice`, `Issue`; hub `POST /payments/checkout`                                                                                             |
+| `/invoices`                   | `invoices`          | Paginated table of Sales Invoices with download PDF action                | ERPNext `Sales Invoice`, `frappe.utils.print_format.download_pdf`                                                                                           |
+| `/invoices/:name`             | `invoice-detail`    | Single invoice: summary, lines, taxes, pay CTA (card + Klarna), PDF       | ERPNext `Sales Invoice/:name`, `printview.get_html_and_style`; hub `POST /payments/checkout-invoice`                                                        |
+| `/tickets`                    | `tickets`           | Support ticket list + create dialog                                       | ERPNext `Issue` (list + create)                                                                                                                             |
+| `/tickets/:name`              | `ticket-detail`     | Conversation thread + reply box                                           | ERPNext `Issue/:name`, `Communication` (list + post)                                                                                                        |
+| `/messages`                   | `messages`          | All communications (SMS / Email / Phone) grouped by ticket or medium      | ERPNext `Communication` (direct + via Issues); hub SSE topic `customer:<id>`                                                                                |
+| `/me`                         | `account`           | Customer info, service locations + monthly total, saved cards, PPA toggle | ERPNext `Customer/:name`, `Service Location`, `Service Subscription`; hub `/payments/balance`, `/payments/methods`, `/payments/setup`, `/payments/portal`, `/payments/toggle-ppa` |
+| `/catalogue`                  | `catalog`           | Public add-on catalog (Internet / Téléphonie / Bundle / Équipement)       | hub `GET /api/catalog`                                                                                                                                      |
+| `/panier`                     | `cart`              | Cart review, install scheduling, OTP flow for existing customers          | hub `POST /api/otp/send`, `POST /api/otp/verify`, `POST /api/address-search`, `POST /api/checkout`                                                          |
+| `/commande/confirmation`      | `order-success`     | Post-checkout confirmation with order number + install notice             | hub `GET /api/order/:id`                                                                                                                                    |
+| `/paiement/merci`             | `payment-success`   | Stripe return (session mode) — "Paiement reçu" + link back to invoice     | — (return landing only)                                                                                                                                     |
+| `/paiement/annule`            | `payment-cancel`    | Stripe return when the user backs out                                     | — (return landing only)                                                                                                                                     |
+| `/paiement/carte-ajoutee`     | `payment-card-added`| Stripe Setup Intent return — confirms the card is saved, nudges PPA       | — (return landing only)                                                                                                                                     |
+
+### 4.1 Public routes (skip the nav guard)
+
+```js
+// apps/client/src/router/index.js
+const PUBLIC_ROUTES = new Set([
+  'login',
+  'catalog', 'cart', 'order-success',
+  'payment-success', 'payment-cancel', 'payment-card-added',
+])
+```
+
+Payment returns stay public so a customer whose JWT has expired still
+sees a human confirmation (plus a re-auth CTA) rather than a bounce.
+The catalog and cart are public so unauthenticated prospects can shop
+add-ons — the OTP flow in the cart escalates to auth only at checkout.
+
+---
+
+## 5. Authentication Flow
+
+### 5.1 Sequence
+
+```
+Customer                Login Page                 targo-hub                ERPNext             Email/SMS
+   │                       │                          │                        │                    │
+   │── types email/phone ──▶                          │                        │                    │
+   │                       │── POST /portal/          │                        │                    │
+   │                       │   request-link ─────────▶│                        │                    │
+   │                       │                          │── lookupCustomer ─────▶│                    │
+   │                       │                          │◀── Customer row ───────│                    │
+   │                       │                          │                                             │
+   │                       │                          │── generateCustomerToken (HS256, 24h) ───────│
+   │                       │                          │── sendSmsInternal ─────────────────────────▶│
+   │                       │                          │── sendEmail ───────────────────────────────▶│
+   │                       │◀── 200 {ok:true,         │                        │                    │
+   │                       │    sent:[sms,email],     │                        │                    │
+   │                       │    redacted:[…]} ────────│                        │                    │
+   │◀── "Lien envoyé!" ────│                          │                        │                    │
+   │                                                                                                │
+   │                       (customer opens SMS / email)                                              │
+   │◀───────────────────── https://portal.gigafibre.ca/#/?token=<JWT> ──────────────────────────────│
+   │                                                                                                │
+   │── click ──▶ SPA loads                                                                          │
+   │            └─ router guard: to.query.token → store.hydrateFromToken()                          │
+   │               └─ JWT parts[1] base64-decoded, exp checked, scope==='customer'                  │
+   │               └─ customerStore.customerId = payload.sub                                        │
+   │               └─ stripTokenFromUrl()  (history.replaceState)                                   │
+   │            └─ dashboard renders                                                                │
+```
+
+### 5.2 JWT shape
+
+Minted by `generateCustomerToken(customerId, customerName, email, ttlHours=24)`
+in `services/targo-hub/lib/magic-link.js`:
+
+```json
+{
+  "alg": "HS256", "typ": "JWT"
+}
+.
+{
+  "sub":   "C-00042",
+  "scope": "customer",
+  "name":  "Jean Tremblay",
+  "email": "jean@example.com",
+  "iat":   1713798000,
+  "exp":   1713884400
+}
+```
+
+Signed HS256 with `cfg.JWT_SECRET` (shared only between the hub processes
+— the portal never holds the secret). The portal trusts the signature
+implicitly because the token arrived over HTTPS via a channel the user
+already controls (their own inbox or SMS). Any tampering breaks
+signature verification the next time the user clicks the link; the
+currently-loaded SPA never re-verifies.
+
+### 5.3 Identifier resolution
+
+`portal-auth.js → lookupCustomer(raw)` handles three forms:
+
+| Input shape            | Lookup order                                                                                  |
+|------------------------|-----------------------------------------------------------------------------------------------|
+| Contains `@`           | `Customer.email_id` → `Customer.email_billing` (both lowercased)                              |
+| Matches `^(C-|CUST-|GI-)/i` or `^\d{4,7}$` | `Customer.legacy_customer_id` → direct `Customer.name` fetch                   |
+| Anything else (phone)  | `helpers.lookupCustomerByPhone()` — last 10 digits matched against `cell_phone`/`tel_home`/`tel_office` |
+
+Returned record always includes `name`, `customer_name`, `cell_phone`,
+`tel_home`, `email_id`, `email_billing` so the sender knows which channels
+are available.
+
+### 5.4 URL hygiene after hydration
+
+`stores/customer.js → stripTokenFromUrl()` uses `history.replaceState` to
+rewrite the URL without `?token=` as soon as the store is hydrated. This
+keeps the token out of:
+
+- Browser history (back button won't show the token).
+- Bookmarks ("add this page to bookmarks" captures the stripped URL).
+- Third-party referer headers (external links on subsequent pages).
+
+The JWT still lives in the Pinia store for the rest of the tab's life;
+a hard refresh reloads the store from…nothing, and the router guard
+bounces back to `/login` unless the URL carries a token or a previous
+hydration put `customerId` into `localStorage` (the store does not
+persist — this is intentional; a refresh is a fresh auth attempt).
+
+### 5.5 Subsequent calls
+
+Two backends, two auth styles:
+
+- **ERPNext REST** (`BASE_URL/api/resource/…`, `/api/method/…`): served
+  through `authFetch()` in `src/api/auth.js`, which attaches
+  `Authorization: token <VITE_ERP_TOKEN>`. The token is a fixed service
+  key baked in at build time; it's not the customer's JWT. The customer's
+  identity is enforced at the query layer by always filtering on
+  `customer = store.customerId` from the store.
+- **Hub** (`msg.gigafibre.ca/payments/*`, `/api/*`, `/sse`): currently
+  called unauthenticated. Endpoints that need customer context receive
+  `customer` as a body/path parameter. The hub trusts the portal origin.
+  Upgrading these endpoints to verify the magic-link JWT is tracked as
+  a hardening follow-up (see §10).
+
+---
+
+## 6. Anti-Enumeration Contract
+
+`POST /portal/request-link` adheres strictly to the following response
+matrix. Callers (portal UI, staff-ops tools, any future integration)
+must treat `200 OK` as the *only* success signal and must *not* branch
+on the identity of sent channels to decide whether the account exists.
+
+| Situation                         | HTTP | Body                                                                            |
+|-----------------------------------|------|---------------------------------------------------------------------------------|
+| Unknown identifier                | 200  | `{"ok":true, "sent":[]}`                                                        |
+| Known, only email on file         | 200  | `{"ok":true, "sent":["email"], "redacted":["j***n@example.com"]}`               |
+| Known, only phone on file         | 200  | `{"ok":true, "sent":["sms"], "redacted":["***-***-1234"]}`                      |
+| Known, both channels              | 200  | `{"ok":true, "sent":["sms","email"], "redacted":["***-***-1234","j***n@…"]}`    |
+| Known, both channels, both failed | 200  | `{"ok":true, "sent":[]}` (logged internally as delivery failure)                |
+| Empty body                        | 400  | `{"error":"identifier_required"}`                                               |
+| Rate limit hit                    | 429  | `{"error":"rate_limit", "message":"Trop de tentatives. Réessayez dans N min.", "retry_after_sec":N}` |
+
+Two downstream rules follow:
+
+1. **The login page shows "Lien envoyé"** even on `sent: []`. The copy
+   says "Si votre compte existe, un lien vous a été envoyé" — the timing
+   and the UI are identical to the happy path. A typo'd email looks
+   indistinguishable from a genuine send.
+2. **The internal log still records the miss** (`log('Portal
+   request-link: no match for "…"')`) so ops can spot fat-finger traffic
+   vs. probing. The log is not served publicly.
+
+Redaction rules (`redactEmail`, `redactPhone`):
+
+- Email: keep first + last char of local part, mask the middle, keep
+  the domain (`j***n@example.com`).
+- Phone: `***-***-XXXX` where `XXXX` is the last 4 digits of the raw
+  `cell_phone`/`tel_home` field (not the E.164-normalized one).
+
+---
+
+## 7. Rate Limiting
+
+A single `Map<identifier, {count, windowStart}>` in the hub process
+enforces 3 requests per 15 minutes (`RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_MS`
+in `portal-auth.js`). The key is `rawIdentifier.trim().toLowerCase()` so
+`jean@example.com` and `JEAN@Example.com` share a bucket.
+
+Lifecycle:
+
+```js
+// portal-auth.js
+function checkRateLimit (key) {
+  const now = Date.now()
+  const entry = rateLimits.get(key)
+  if (!entry || now - entry.windowStart > RATE_LIMIT_WINDOW_MS) {
+    rateLimits.set(key, { count: 1, windowStart: now })
+    return { ok: true }
+  }
+  if (entry.count >= RATE_LIMIT_MAX) {
+    return { ok: false, retryAfterMs: RATE_LIMIT_WINDOW_MS - (now - entry.windowStart) }
+  }
+  entry.count++
+  return { ok: true }
+}
+
+// Cull every 15 min so the Map stays small
+setInterval(() => { /* drop entries older than window */ }, RATE_LIMIT_WINDOW_MS).unref()
+```
+
+### 7.1 Failure modes we accept
+
+- **Process restart** wipes the Map. Worst case a throttled attacker gets
+  their window reset — still bounded by Twilio + Mailjet rate limits, and
+  the internal `Portal request-link` log surfaces the abuse for ops.
+- **Hub horizontal scale** would duplicate the Map per replica. Today the
+  hub is a single container so the Map is authoritative; if we scale out,
+  move to Redis (tracked under the hub hardening line in
+  [../roadmap.md](../roadmap.md)).
+- **Identifier rotation** (attacker types slightly different strings):
+  mitigated by Twilio/Mailjet per-destination throttles that kick in
+  downstream — the attacker can't out-run our carrier tier.
+
+### 7.2 Error surfacing to the UI
+
+`requestPortalLink()` rethrows the 429 as a typed error:
+
+```js
+// src/api/auth-portal.js
+if (r.status === 429) {
+  const err = new Error(data.message || 'Trop de tentatives. Réessayez plus tard.')
+  err.code = 'rate_limit'
+  err.retryAfterSec = data.retry_after_sec || 900
+  throw err
+}
+```
+
+`LoginPage.vue` displays the message in an orange banner (`q-banner
+bg-orange-1`) without clearing the input — the user can read the message
+and adjust their identifier.
+
+---
+
+## 8. Cross-Module References
+
+### 8.1 Billing — Stripe Checkout + Klarna
+
+`InvoiceDetailPage.vue` exposes both payment rails:
+
+```js
+payInvoice('card')   → hub POST /payments/checkout-invoice { payment_method: 'card'   }
+payInvoice('klarna') → hub POST /payments/checkout-invoice { payment_method: 'klarna' }
+```
+
+The hub returns a hosted Checkout URL; the SPA does
+`window.location.href = url`. Stripe's return URLs come back to
+`/#/paiement/merci?invoice=…`, `/#/paiement/annule?invoice=…`, and
+`/#/paiement/carte-ajoutee` (Setup Intent flow). All three live under
+`PUBLIC_ROUTES` so an expired token still gets a civilized landing.
+
+Full lifecycle: [billing-payments.md](billing-payments.md) — especially
+§4 "Flux de paiement public" and §7 "Configuration & secrets" for Stripe
+keys and webhook wiring.
+
+### 8.2 Messaging — Server-Sent Events
+
+`MessagesPage.vue` subscribes to `msg.gigafibre.ca/sse?topics=customer:<id>`
+via `useSSE`. The hub broadcasts `conversations` and per-customer topics
+from `lib/conversation.js` (see lines 68–70 of that file); every inbound
+SMS or email handled by the hub fires a broadcast, and the portal
+reloads `fetchAllCommunications` on receipt and shows a toast for
+inbound-direction messages.
+
+The SPA's SSE connection is resilient: `useSSE` implements exponential
+backoff (1 s → 30 s) on disconnect. Read path details in
+`apps/client/src/composables/useSSE.js`.
+
+### 8.3 Tickets — read-only window into ERPNext HD Ticket
+
+`TicketsPage` and `TicketDetailPage` hit the stock ERPNext `Issue`
+doctype. Creation goes through `POST /api/resource/Issue` with
+`customer`, `subject`, `description`, `issue_type='Support'`,
+`priority='Medium'`. Replies from the portal create a `Communication`
+tied to the Issue; staff see them in the Ops CRM pane. Cross-ref
+`docs/architecture/data-model.md` for the full `Issue` field list.
+
+### 8.4 Catalog — shared SKUs with the quote wizard
+
+`CatalogPage` lists the same Items the sales wizard exposes — Internet
+plans, phone service, bundles, equipment. Prices and `requires_visit`
+flags come from ERPNext Items via the hub's `/api/catalog` endpoint.
+Add-on purchases placed through `/panier` become `Sales Order` drafts
+that the dispatch queue picks up. See `billing-payments.md` §2
+"App Frappe custom — `gigafibre_utils`" for the shared SKU catalog
+source of truth.
+
+### 8.5 Contract acceptance
+
+Two separate tracks, both documented elsewhere:
+
+- **Residential JWT** (promotion framing, 24 h link, same style as this
+  portal's auth) — `services/targo-hub/lib/contracts.js`. See
+  `billing-payments.md` and memory `project_contract_acceptance.md`.
+- **Commercial DocuSeal** — `services/targo-hub/lib/acceptance.js`,
+  documented in the same memory file.
+
+Neither track reuses the portal's magic-link JWT today; the
+`scope=customer` token is strictly for browsing. A signed contract
+produces its own short-lived acceptance JWT minted by `contracts.js`.
+
+### 8.6 Tech mobile app
+
+The field tech interface lives at `msg.gigafibre.ca/t/<tech-token>`
+— a separate HS256 token scope (`scope='all'` or per-job) minted by
+`magic-link.js`. It shares the hub's HS256 primitive (`signJwt`) with
+the customer portal but not the token itself. There is no customer-facing
+touchpoint on the tech app; cross-ref is kept here only so future
+refactors remember the two scopes sign with the same secret.
+
+---
+
+## 9. Deploy & Operations
+
+### 9.1 Ship a portal change
+
+```bash
+cd apps/client
+./deploy.sh                      # build PWA + rsync + flip + docker restart
+```
+
+What the script prints on success:
+
+```
+  Deployed. Backup: /opt/client-app.bak.1713798123
+Done! Customer Portal: https://portal.gigafibre.ca/
+Legacy alias (302):    https://client.gigafibre.ca/
+```
+
+### 9.2 Ship a Traefik redirect change (`client.gigafibre.ca`)
+
+```bash
+cd apps/portal
+./deploy-portal.sh               # scp YAML to /opt/traefik/dynamic/ + smoke test
+```
+
+Traefik auto-reloads anything under `/opt/traefik/dynamic/` — no restart.
+The script also curls `https://client.gigafibre.ca/login` and prints the
+HTTP code so you know whether Let's Encrypt has provisioned the cert yet
+(first request may return 000 while the cert is being issued).
+
+### 9.3 Roll back
+
+```bash
+ssh root@96.125.196.67
+ls -dt /opt/client-app.bak.*     # pick the timestamp you want
+mv /opt/client-app /opt/client-app.broken
+mv /opt/client-app.bak.<epoch> /opt/client-app
+docker restart client-portal      # same inode trap as deploy
+```
+
+`deploy.sh` keeps the three most recent backups (`ls -dt … | tail -n +4
+| xargs -r rm -rf`), which is usually enough to roll back a same-day mistake.
+
+### 9.4 Smoke tests
+
+```bash
+# SPA shell reachable
+curl -sI https://portal.gigafibre.ca/ | head -5
+
+# Legacy redirect preserves path
+curl -sI https://client.gigafibre.ca/invoices | grep -iE 'location|http/'
+#   expect:  HTTP/2 307
+#   expect:  location: https://portal.gigafibre.ca/invoices
+
+# Magic-link endpoint: anti-enumeration contract
+curl -s -X POST https://msg.gigafibre.ca/portal/request-link \
+  -H 'Content-Type: application/json' \
+  -d '{"identifier":"does-not-exist@example.com"}'
+#   expect:  {"ok":true,"sent":[]}
+
+# Rate limit (send the same identifier 4 times quickly)
+for i in 1 2 3 4; do
+  curl -s -X POST https://msg.gigafibre.ca/portal/request-link \
+    -H 'Content-Type: application/json' \
+    -d '{"identifier":"rl-test@example.com"}' ; echo
+done
+#   expect 4th call:  429 + rate_limit body
+```
+
+### 9.5 Cache bust
+
+The Quasar PWA service worker is configured with `skipWaiting: true` +
+`clientsClaim: true` + `cleanupOutdatedCaches: true`. A user who's been
+sitting on a stale tab usually picks up the new build on next nav. For
+a hard bust, append `?v=<epoch>` to the URL or instruct the user to
+do a reload; the hash router handles the query string transparently.
+
+---
+
+## 10. Failure Modes
+
+| Symptom                                             | Likely cause                                                  | Remedy                                                                                                         |
+|-----------------------------------------------------|---------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| User clicks magic link, lands on `/login`            | JWT expired (>24 h)                                          | Re-request a link. Payment-return pages show a banner with a one-click re-auth button                          |
+| User clicks magic link, lands on dashboard briefly, then bounces to `/login` on refresh | Store not persisted; token already stripped from URL         | Expected — refresh is a fresh auth. Re-request or click from the original email again                          |
+| "Lien envoyé" but no SMS arrives                     | Twilio rejected the number (no `cell_phone`/`tel_home` on file, or number invalid) | Check `docker logs targo-hub | grep 'Portal link'` — the log reports `sent via email` vs `NONE`                |
+| "Lien envoyé" but no email arrives                   | Mailjet rate limit / bounce                                   | Same log line. Investigate Mailjet dashboard for the destination                                               |
+| Dashboard renders blank after click                  | `VITE_ERP_TOKEN` broken; ERPNext returns 401                  | Browser console shows `[portal] ERPNext returned 401 — check VITE_ERP_TOKEN`. Rebuild with the right token     |
+| `client.gigafibre.ca` serves the old portal         | Traefik dynamic config not reloaded / not placed in `/opt/traefik/dynamic/` | `scp` via `deploy-portal.sh`, then `docker logs --tail 50 traefik`                                             |
+| Deploy succeeds, but users still see old UI          | Docker bind mount still pinned to backup inode                | `ssh … docker restart client-portal` (deploy.sh does this; if you copied files manually, restart manually)     |
+| SSE never connects in `/messages`                   | CSP or mixed-content block on `msg.gigafibre.ca`              | Check browser console — the nginx `Content-Security-Policy` must allow `connect-src https://msg.gigafibre.ca`  |
+| Hash router breaks behind corporate proxy           | Proxy strips the `#` fragment                                 | Issue a plain `/login` link (no token) — users self-request magic link from there                              |
+| 429 loop for a well-meaning user                    | Same identifier typed 4 times inside 15 min                   | Wait the window out, or restart the hub container to flush the Map                                             |
+
+### 10.1 CSP for the hash router
+
+The nginx container's config (`/opt/client-app/nginx.conf`, preserved
+across deploys by the `cp docker-compose.yml nginx.conf` lines in
+`deploy.sh`) must include at minimum:
+
+```
+connect-src 'self' https://msg.gigafibre.ca https://erp.gigafibre.ca;
+```
+
+The first permits hub SSE and REST; the second permits ERPNext REST via
+`authFetch`. If either is missing, the SPA loads but every data call fails.
+
+---
+
+## 11. Retirement Notes
+
+### 11.1 ERPNext `/login` — retired for customers
+
+- The form is still reachable at `erp.gigafibre.ca/login` but is gated
+  behind Authentik forwardAuth — non-staff accounts cannot authenticate.
+- `client.gigafibre.ca/login` (the old direct ERPNext frontend) no
+  longer serves the form because the whole host is 307-redirected to
+  `portal.gigafibre.ca/login`.
+- No migration of legacy MD5 password hashes is required. Ever. See
+  memory `project_portal_auth.md` for rationale.
+
+### 11.2 `client.gigafibre.ca` — legacy alias, not canonical
+
+- All outbound communications (email templates, SMS, invoice footers,
+  QR codes on PDFs) now use `https://portal.gigafibre.ca/#/…`. See
+  `project_invoice_qr.md` memory for the QR wiring.
+- The redirect in `traefik-client-portal.yml` is currently a `302`
+  (`permanent: false`) while the cutover is still warm — we can flip
+  to `301` once we're confident nothing else points at the old host.
+  Tracking this in [../roadmap.md](../roadmap.md).
+- DNS: `*.gigafibre.ca` wildcard already resolves to `96.125.196.67`.
+  Let's Encrypt auto-provisions the cert for both hosts.
+
+### 11.3 Authentik — not a factor for customers
+
+Staff continue to use Authentik forwardAuth for Ops (`ops.gigafibre.ca`)
+and ERPNext (`erp.gigafibre.ca`). The portal host has no Authentik
+middleware; the JWT is the sole credential. Memory files
+`reference_authentik.md` and `reference_authentik_client.md` cover
+the staff side.
+
+---
+
+## 12. Glossary
+
+- **Magic link** — `https://portal.gigafibre.ca/#/?token=<JWT>`. The only
+  authenticated entry point for customers. Minted by the hub, delivered
+  via SMS + email.
+- **Customer JWT** — HS256 token with `scope=customer`, 24 h TTL,
+  `sub=<Customer.name>`. Decoded client-side; never re-verified.
+- **Anti-enumeration** — The contract that every `POST /portal/request-link`
+  returns 200 regardless of whether the identifier matched.
+- **Hash router** — Vue Router's `createWebHashHistory` mode. URL paths
+  live after `#`, so the server always serves the same `index.html`.
+- **Inode trap** — The Docker bind-mount behaviour where `mv`-swapping a
+  directory leaves the container pointed at the old inode. Solved by
+  `docker restart client-portal`.
+- **Legacy alias** — `client.gigafibre.ca`. Still resolves, still has a
+  cert, but 307-redirects every request to the canonical host.
+- **Service token** — `VITE_ERP_TOKEN`: a fixed ERPNext API key baked
+  into the SPA bundle. Identifies the *portal* to ERPNext; not the
+  customer. Customer identity is enforced at the query layer.
+
+---
+
+*Last updated: 2026-04-22. Owners: Targo Platform team
+(<louis@targo.ca>). Related roadmap items: hub JWT verification on
+`/payments/*`, flip `client.gigafibre.ca` redirect to 301, Redis-backed
+rate limit for multi-replica hub. See [../roadmap.md](../roadmap.md).*
+
+---
+
+Back to [docs/README.md](../README.md) · [roadmap.md](../roadmap.md)
diff --git a/docs/features/dispatch.md b/docs/features/dispatch.md
new file mode 100644
index 0000000..8c266ac
--- /dev/null
+++ b/docs/features/dispatch.md
@@ -0,0 +1,332 @@
+# Dispatch
+
+> Real-time technician scheduling, work-order creation, and field publishing for the Ops PWA. Largest module in `apps/ops/` — the single page where CSRs turn incoming service requests into scheduled work on a technician's calendar.
+
+## 1. Goals & Principles
+
+Dispatch is the live control surface for every field intervention. It replaces the legacy PHP `dispatch-app` (slated for retirement per [../architecture/overview.md](../architecture/overview.md)) with a Vue 3 / Pinia timeline bound directly to ERPNext Dispatch Job and Dispatch Technician DocTypes.
+
+Principles enforced in the code:
+
+- **Single source of truth is ERPNext.** Every drag, resize, tag toggle issues a `PUT /api/resource/Dispatch Job/{name}` through `src/api/dispatch.js`. The Pinia store (`src/stores/dispatch.js`) only holds a mapped view; on reload it rehydrates from Frappe.
+- **Optimistic UI + undo stack.** `useUndo` snapshots mutations so keyboard `Cmd+Z` can roll back a mistake before ERPNext ever replies.
+- **Match skill, not cost.** Per `feedback_dispatch_tags.md` convention, tags carry a level 1-5 and auto-dispatch picks the lowest adequate match — experts are preserved for jobs that require them.
+- **Push, don't poll.** Timeline stays in sync via SSE topics `dispatch` and `network` from `targo-hub` — tech-absence SMS, outage alerts, OLT up/down events all land as toasts without a refresh.
+- **Human and material resources share one grid.** A `Dispatch Technician` row is either a human (with a phone / user) or a material asset (Véhicule, Nacelle, OTDR, Fusionneuse…) — the same drag-drop logic applies.
+- **Work is not visible to techs until it is published.** The `published` flag on a Dispatch Job gates both the mobile page (`/t/{token}`) and the iCal feed.
+
+## 2. File Inventory
+
+### Front-end (Ops PWA)
+
+| Path | Responsibility |
+| --- | --- |
+| `apps/ops/src/pages/DispatchPage.vue` | Top-level page, composes all composables, owns SSE connection, renders timeline / week / month switcher plus inline map panel. |
+| `apps/ops/src/modules/dispatch/components/TimelineRow.vue` | One row per resource — renders shift, absence, travel, assist, ghost and job segments; emits drag / drop / resize events. |
+| `apps/ops/src/modules/dispatch/components/WeekCalendar.vue` | 7-day grid view with absence chips, ghost recurrences and day-load bars; handles planning mode shifts and on-call bands. |
+| `apps/ops/src/modules/dispatch/components/MonthCalendar.vue` | Month overview with per-day tech-count badges; shows selected tech's availability when in planning mode. |
+| `apps/ops/src/modules/dispatch/components/BottomPanel.vue` | Unassigned jobs tray with lasso selection, batch assign and auto-distribute buttons. |
+| `apps/ops/src/modules/dispatch/components/RightPanel.vue` | Details side-panel for a selected job — edit, move, geofix, unassign, set end date, remove assistant, assign pending, update tags. |
+| `apps/ops/src/modules/dispatch/components/JobEditModal.vue` | Inline edit of title, address, note, duration, priority and tags. |
+| `apps/ops/src/modules/dispatch/components/WoCreateModal.vue` | "Nouveau work order" modal — runs `rankTechs` + `refineWithDrivingTimes` on the top 3 candidates. |
+| `apps/ops/src/modules/dispatch/components/CreateOfferModal.vue` | Creates a job offer in broadcast / targeted / pool mode with a pricing preset. |
+| `apps/ops/src/modules/dispatch/components/OfferPoolPanel.vue` | Live offer feed with status chips (open, pending, accepted, expired, cancelled). |
+| `apps/ops/src/modules/dispatch/components/PublishScheduleModal.vue` | "Publier & envoyer l'horaire par SMS" — publishes jobs, builds per-tech magic link + webcal iCal URL, sends via Twilio. |
+| `apps/ops/src/modules/dispatch/components/SbModal.vue` | Generic overlay modal with header / body / footer slots. |
+| `apps/ops/src/modules/dispatch/components/SbContextMenu.vue` | Positioned context-menu wrapper used for right-click menus on techs and jobs. |
+| `apps/ops/src/modules/dispatch/components/MapPanel.vue` | Standalone map panel component — present but **not imported** by `DispatchPage.vue`, which uses an inline Mapbox block instead. |
+| `apps/ops/src/modules/dispatch/components/SuggestSlotsDialog.vue` | Client for `/dispatch/suggest-slots` (hub endpoint). Present but **not imported** by `DispatchPage.vue` — kept for future "Find me a time" entry point. |
+| `apps/ops/src/stores/dispatch.js` | Pinia store — maps ERPNext rows to UI-friendly shape, rebuilds tech queues, triggers GPS polling. |
+| `apps/ops/src/config/dispatch.js` | Row height constant, resource icon map (Véhicule, Nacelle, Fusionneuse…), re-exports `HUB_SSE_URL`. |
+| `apps/ops/src/api/dispatch.js` | All Frappe REST calls — `fetchTechnicians`, `fetchJobsFast`, `updateJob`, `publishJobs`, `createJob`, `createTech`. |
+| `apps/ops/src/composables/useScheduler.js` | Drives period navigation, busy lanes, ghost materialization. |
+| `apps/ops/src/composables/useDragDrop.js` | Drag sources / drop targets for jobs, techs and assistants. |
+| `apps/ops/src/composables/useAutoDispatch.js` | Client-side candidate ranking mirroring the hub algorithm. |
+| `apps/ops/src/composables/useJobOffers.js` | Offer-pool state + `PRICING_PRESETS`. |
+| `apps/ops/src/composables/useAbsenceResize.js` | Drag-to-resize absence bands. |
+| `apps/ops/src/composables/useTechManagement.js` | Create / delete / reassign technicians. |
+| `apps/ops/src/composables/useTagManagement.js` | Tag editor bindings for techs and jobs. |
+| `apps/ops/src/composables/useContextMenus.js` | Tech and job right-click menus. |
+| `apps/ops/src/composables/useSelection.js` | Lasso selection in the bottom panel. |
+| `apps/ops/src/composables/useBottomPanel.js` | Collapsed / pinned state of the unassigned tray. |
+| `apps/ops/src/composables/usePeriodNavigation.js` | 3-period buffer and infinite horizontal scroll. |
+| `apps/ops/src/composables/useResourceFilter.js` | Human / material / group filtering. |
+| `apps/ops/src/composables/useMap.js` | Mapbox GL layer and marker lifecycle. |
+| `apps/ops/src/composables/useUndo.js` | Per-mutation snapshots for `Cmd+Z`. |
+| `apps/ops/src/composables/useAddressSearch.js` | Mapbox geocoder wrapper used by Wo and Job modals. |
+| `apps/ops/src/components/dispatch/NlpInput.vue` | Natural-language "type-to-dispatch" shortcut. |
+
+### Back-end (targo-hub)
+
+| Path | Responsibility |
+| --- | --- |
+| `services/targo-hub/server.js` | Routes `/dispatch/*` to `dispatch.js`, `/dispatch/ical-token/:id` and `/dispatch/calendar/:id.ics` to `ical.js`, `/t/*` to `tech-mobile.js`, `/traccar/*` to `traccar.js`, `/magic-link/*` to `magic-link.js`. |
+| `services/targo-hub/lib/dispatch.js` | `POST /dispatch/best-tech`, `POST /dispatch/suggest-slots`, `POST /dispatch/create-job`. Implements `rankTechs`, `getTechsWithLoad`, `enrichWithGps`, `suggestSlots`. |
+| `services/targo-hub/lib/ical.js` | HMAC-SHA256 token signing, VCALENDAR builder with `America/Toronto` VTIMEZONE, status + priority mapping, RRULE passthrough. |
+| `services/targo-hub/lib/traccar.js` | Bearer-auth proxy to the Traccar GPS server with a 60s device cache. |
+| `services/targo-hub/lib/magic-link.js` | `POST /magic-link/generate`, `POST /magic-link/verify`, `POST /magic-link/refresh` — JWT tokens, default 72h TTL, job-level and all-jobs-for-tech variants. |
+| `services/targo-hub/lib/tech-mobile.js` | Server-rendered mobile page at `/t/{token}` with status update, scan, vision, equipment and catalog endpoints. |
+| `services/targo-hub/lib/tech-absence-sms.js` | Inbound Twilio SMS → Gemini Flash NLU (regex fallback) → `setTechAbsence` / `clearTechAbsence` → SSE `tech-absence` broadcast. |
+| `services/targo-hub/lib/sse.js` | Topic fan-out used by the `dispatch` and `network` channels. |
+
+### ERPNext (Frappe custom DocTypes)
+
+| Path | Responsibility |
+| --- | --- |
+| `erpnext/setup_fsm_doctypes.py` | Creates / patches custom fields on Dispatch Job and Dispatch Technician. |
+
+## 3. Data Model
+
+### Dispatch Job
+
+Core Frappe fields plus these custom fields (from `erpnext/setup_fsm_doctypes.py`):
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `customer` | Link → Customer | Billing-side link. |
+| `service_location` | Link → Service Location | Physical address + geocoded coordinates. |
+| `job_type` | Select | Installation / Réparation / Maintenance / Retrait / Dépannage / Autre. |
+| `source_issue` | Link → Issue | Origin ticket, when the job came from Support. |
+| `depends_on` | Link → Dispatch Job | Blocks scheduling until the dependency is done. |
+| `parent_job` | Link → Dispatch Job | Multi-step workflow (with `step_order`). |
+| `on_open_webhook`, `on_close_webhook` | Data | Flow-editor callbacks — see [flow-editor.md](flow-editor.md). |
+| `equipment_items`, `materials_used`, `checklist`, `photos` | Table | Child tables fed by the mobile tech page. |
+| `actual_start`, `actual_end`, `travel_time_min` | Datetime / Int | Field-recorded metrics. |
+| `completion_notes`, `customer_signature` | Text / Attach | End-of-job capture. |
+| `published` | Check | Gates visibility on the mobile page and iCal feed. |
+| `is_recurring`, `recurrence_rule`, `recurrence_end`, `pause_periods`, `template_id` | Mixed | RRULE-based repeating jobs (materialized on demand). |
+| `continuous` | Check | Emergency jobs that may span weekends / off-days. |
+| `assistants` (child table) | Table | `tech_id`, `tech_name`, `duration_h`, `note`, `pinned`. |
+| `tags` (child table) | Table | `tag`, `level`, `required`. |
+
+### Dispatch Technician
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `resource_type` | Select | `human` or `material`. |
+| `resource_category` | Select | Véhicule / Outil / Salle / Équipement / Nacelle / Grue / Fusionneuse / OTDR. |
+| `weekly_schedule` | Text / JSON | Parsed by `parseWeeklySchedule`. |
+| `extra_shifts` | JSON (hidden) | Per-date overrides. |
+| `absence_reason`, `absence_from`, `absence_until`, `absence_start_time`, `absence_end_time` | Mixed | Current absence band. |
+| `traccar_device_id` | Data | Links to a Traccar GPS device. |
+| `tags` (child table) | Table | `tag`, `level`. |
+
+Full field definitions live in [../architecture/data-model.md](../architecture/data-model.md).
+
+## 4. UI Surfaces
+
+All French strings below are pulled directly from `DispatchPage.vue`.
+
+### Top bar
+
+"Ressources" (resource filter), "Filtres" (tag filter), "Aujourd'hui" (jump-to-today), "Jour / Semaine / Mois" view toggle, "Planning" mode for availability editing, "Carte" for the inline map, "Publier" for the publish modal, "+ WO" for the work-order creator, "ERP" status pill.
+
+### Timeline view (`TimelineRow.vue`)
+
+One row per resource. Each row renders stacked segments:
+
+| Segment type | Source | Notes |
+| --- | --- | --- |
+| `shift` | `weeklySchedule` + `extraShifts` | Active working window; drop targets enabled. |
+| `absence` | `absence_from..absence_until` or weekly "off" days | Resizable via `useAbsenceResize`. |
+| `travel` | Computed between consecutive jobs | Mapbox Directions API; non-draggable. |
+| `assist` | `assistants[]` on another tech's job | Pinned assists cannot be dragged away. |
+| `ghost` | Unmaterialized recurrence | Click → materialize concrete Dispatch Job. |
+| `job` | Assigned, scheduled Dispatch Job | Primary drag source. |
+
+Drag sources: tech avatar (to split shifts), job blocks (to move / reassign), pinned assist blocks (to nudge helper). Emits `select-tech`, `ctx-tech`, `job-dragstart`, `timeline-drop`, `block-move`, `block-resize`, `absence-resize`, `ghost-click`, `ghost-materialize`.
+
+### Week view (`WeekCalendar.vue`)
+
+Seven-day grid per resource. Distinguishes `isExplicitAbsent` (a typed absence record) from `isScheduleOff` (non-working weekday). In planning mode it draws availability bands and on-call shift overlays on top.
+
+### Month view (`MonthCalendar.vue`)
+
+Month grid with per-day badges showing how many techs are available. In planning mode a sidebar surfaces the selected tech's weekly schedule and extra shifts.
+
+### Bottom panel (`BottomPanel.vue`)
+
+Unassigned jobs tray. Supports:
+
+- Lasso selection (click-drag to select multiple)
+- Batch assign to a tech
+- Auto-distribute across available techs using `useAutoDispatch`
+- Collapse / pin state via `useBottomPanel`
+
+### Right panel (`RightPanel.vue`)
+
+Details + pending-request slide-in. Emits `edit`, `move`, `geofix`, `unassign`, `set-end-date`, `remove-assistant`, `assign-pending`, `update-tags`.
+
+### Inline map
+
+DispatchPage renders its own Mapbox panel using `useMap` and `MAPBOX_TOKEN` from `config/erpnext.js`. `MapPanel.vue` exists in the module but is not currently imported — kept for a possible future extraction.
+
+### Offer pool (`OfferPoolPanel.vue`, `CreateOfferModal.vue`)
+
+Three offer modes surface as icon toggles in `CreateOfferModal`:
+
+| Mode | Behaviour |
+| --- | --- |
+| `broadcast` | Blast to every matching tech; first accepter wins. |
+| `targeted` | Single named recipient. |
+| `pool` | A named candidate list; first to accept wins. |
+
+Pricing is composed from `PRICING_PRESETS` (in `useJobOffers`) as `displacement$ + hourlyRate$/h × duration`. Offer status chips: `open`, `pending`, `accepted`, `expired`, `cancelled`.
+
+### Context menu (`SbContextMenu.vue`)
+
+Right-click on a tech row or job block opens a context menu wired through `useContextMenus` — quick reassign, cancel, open in ERP, copy magic link, copy iCal URL.
+
+### Drag-drop rules (enforced in `useDragDrop`)
+
+- Drop on an active shift / within absence band = allowed (toggle absence).
+- Drop on a non-working weekday = blocked unless `continuous=1`.
+- Drop on a tech whose tags don't meet `tags.required` levels = warning toast but still allowed (CSR override).
+- `Escape` cancels any in-flight drag.
+- `Delete` while a job is selected opens the unassign confirmation.
+- `Cmd+Z` walks back the `useUndo` snapshot stack.
+
+## 5. Key Flows
+
+### 5.1 Create a work order
+
+1. CSR clicks `+ WO` → `WoCreateModal.vue` opens.
+2. Address input auto-geocodes via `useAddressSearch` (Mapbox geocoder).
+3. On submit, `WoCreateModal` calls `findBestTech()` which locally runs the ranking, then refines the top 3 with live driving times.
+4. `createJob` (in `src/api/dispatch.js`) POSTs to ERPNext.
+5. The store prepends the new job; SSE fan-out notifies other open Ops tabs.
+
+### 5.2 Suggest the best tech (server side)
+
+`POST /dispatch/best-tech` on `targo-hub` (`lib/dispatch.js`):
+
+- `rankTechs` computes a score per candidate using SCORE_WEIGHTS — `proximityMultiplier=4`, `proximityMax=100` km, `loadMultiplier=30`, `overloadPenalty=500`, `gpsFreshnessBonus=20`.
+- Proximity uses a Euclidean km approximation at Montreal latitude (fast enough for ranking).
+- `getTechsWithLoad` tallies today's scheduled hours; anything above the configured cap triggers the overload penalty.
+- `enrichWithGps` adds a freshness bonus when a recent Traccar fix exists.
+
+### 5.3 Suggest time slots
+
+`POST /dispatch/suggest-slots` (`lib/dispatch.js`) returns up to N best windows across all techs:
+
+- 7-day horizon, capped at 2 slots per tech to diversify suggestions.
+- Default shift 08:00-17:00 (overridable per tech).
+- 15-minute travel buffer inserted before/after existing jobs.
+- `SuggestSlotsDialog.vue` is the front-end client — present in the repo but not yet wired into `DispatchPage.vue`; the current path is tech selection via `WoCreateModal` or manual drag.
+
+### 5.4 Offer pool
+
+1. CSR opens `CreateOfferModal`, picks mode + pricing preset.
+2. Offer is persisted through `useJobOffers`.
+3. `OfferPoolPanel` subscribes to offer events and updates chip status.
+4. Accepting techs fire a state transition that converts the offer into an assigned Dispatch Job.
+
+### 5.5 Publish & SMS schedule
+
+`PublishScheduleModal.vue` — title "Publier & envoyer l'horaire par SMS":
+
+1. Operator selects a tech + date range.
+2. `publishJobs(jobNames)` from `src/api/dispatch.js` PUTs `published: 1` on each job in parallel.
+3. For each tech, the modal fetches:
+   - A magic link via `POST /magic-link/generate` (targo-hub, default 72h TTL) → produces the `/t/{token}` URL that opens the mobile tech page.
+   - An iCal token via `GET /dispatch/ical-token/{techId}` → builds a `webcal://` URL pointing at `/dispatch/calendar/{techId}.ics?token=...`.
+4. Twilio sends two SMS:
+   - "Mes tâches: {link}" — the magic link.
+   - "Ajouter à mon calendrier: {webcal url}" — the iCal subscription URL.
+5. `sendTestSms` is invoked with `reference_doctype = Dispatch Technician` so every send is logged against the tech in ERPNext.
+
+### 5.6 Absence via SMS (inbound)
+
+`services/targo-hub/lib/tech-absence-sms.js`:
+
+1. Twilio inbound webhook hits `handleAbsenceSms`.
+2. `lookupTechByPhone` matches the last 10 digits of the sender against Dispatch Technicians.
+3. Gemini 2.5 Flash (OpenAI-compatible endpoint) parses intent + dates; a regex fallback catches "absent / malade / sick / formation / vacances" with simple date ranges if the LLM is down.
+4. `setTechAbsence` or `clearTechAbsence` PUTs to Dispatch Technician and broadcasts SSE `tech-absence` on the `dispatch` topic.
+5. Ops timelines update in-place; the operator sees a toast. A French confirmation SMS is returned to the tech.
+
+### 5.7 Recurring jobs (ghosts → materialized)
+
+- A template job carries `is_recurring=1` and an RFC 5545 `recurrence_rule` (e.g. `FREQ=WEEKLY;BYDAY=SA,SU`).
+- `WeekCalendar` and `TimelineRow` render upcoming occurrences as ghost segments computed client-side.
+- Clicking a ghost fires `ghost-materialize`, creating a concrete Dispatch Job with `template_id` set — subsequent edits diverge from the template.
+- `pause_periods` carves out vacation windows without deleting the template.
+
+## 6. External Integrations
+
+### Traccar (GPS)
+
+`services/targo-hub/lib/traccar.js` proxies `/traccar/devices`, `/traccar/positions` and a generic GET fallback with Traccar bearer-token auth preferred over Basic. Device metadata is cached for 60 seconds. The store (`useGpsTracking`) polls positions and feeds live `gpsCoords`, `gpsSpeed`, `gpsOnline` into each tech row — these in turn power the freshness bonus in the server-side ranker. Traccar limitation noted in [../architecture/overview.md](../architecture/overview.md) #6.4: only one `deviceId` per request — poll in parallel.
+
+### Twilio
+
+- **Outbound** — `PublishScheduleModal` calls `sendTestSms` to deliver the magic link and webcal URL per tech.
+- **Inbound** — `tech-absence-sms.js` owns Twilio's incoming SMS webhook and drives the absence flow above.
+- Number `+14382313838` per `reference_twilio.md`.
+
+### iCal / webcal
+
+`services/targo-hub/lib/ical.js`:
+
+- Token is HMAC-SHA256 over `{techId}` with `ICAL_SECRET`, truncated to 16 hex chars.
+- Fetches jobs from past 7 days to future 60 days for the tech.
+- Emits RFC 5545 with a full `America/Toronto` VTIMEZONE (DST rules included).
+- Status: `open → TENTATIVE`, `cancelled` / `completed → CANCELLED`.
+- Priority: `urgent → 1`, `medium → 5`, everything else → `9`.
+- Honors `recurrence_rule` — passes the RRULE through untouched.
+
+Subscription URL handed to techs is `webcal://msg.gigafibre.ca/dispatch/calendar/{techId}.ics?token=...` — Apple Calendar and Google Calendar both handle this.
+
+### Mobile tech page (`/t/{token}`)
+
+`services/targo-hub/lib/tech-mobile.js` is a lightweight server-rendered page — **not** the Ops PWA. It authenticates the tech with a JWT magic link (`verifyJwt`), lists their published jobs for the day, and offers POST endpoints:
+
+| Route | Purpose |
+| --- | --- |
+| `GET /t/{token}` | Day view for the tech. |
+| `POST /t/{token}/status` | Flip status (In Progress, Completed). |
+| `POST /t/{token}/scan` | Record a barcode scan. |
+| `POST /t/{token}/vision` | Send a photo to `/vision/barcodes` for OCR. |
+| `POST /t/{token}/equip` | Install a Service Equipment row. |
+| `POST /t/{token}/equip-remove` | Decommission equipment. |
+| `GET /t/{token}/catalog` | Fetch the equipment catalog. |
+| `GET /t/{token}/equip-list` | Fetch equipment already on site. |
+
+The Ops PWA never opens this page — it lives alongside Dispatch to replace the retiring `apps/field` app. See [../architecture/overview.md](../architecture/overview.md) §1.
+
+## 7. Cross-module References
+
+- [../architecture/overview.md](../architecture/overview.md) — ecosystem map, retirement plan for the legacy dispatch-app and field app.
+- [../architecture/data-model.md](../architecture/data-model.md) — canonical Dispatch Job / Dispatch Technician field list.
+- [flow-editor.md](flow-editor.md) — wires `on_open_webhook` / `on_close_webhook` on Dispatch Job into workflow runs.
+- [vision-ocr.md](vision-ocr.md) — barcode / equipment recognition consumed by the tech mobile page during a dispatch.
+- [cpe-management.md](cpe-management.md) — "Diagnostiquer" deep-dives started from a customer card flow into the same tech assignment surface.
+- [billing-payments.md](billing-payments.md) — Sales Orders that trigger installation Dispatch Jobs (`order_source`, `sales_order` fields on the job).
+
+## 8. Failure Modes
+
+| Symptom | Likely cause | Where to look |
+| --- | --- | --- |
+| Timeline loads but all rows are empty | ERPNext token revoked or Administrator "Generate Keys" clicked | `src/api/auth.js` + note in [../architecture/overview.md](../architecture/overview.md) §6.3 |
+| Drops appear to work then revert on refresh | ERPNext `exc` swallowed — check console for `[API] PUT Dispatch Job/... failed` | `apps/ops/src/api/dispatch.js` |
+| iCal subscription returns 401 | Wrong token or `ICAL_SECRET` changed — ask operator to re-copy the webcal URL | `services/targo-hub/lib/ical.js` |
+| Tech never receives magic link SMS | Twilio rejected the number or `published=0` on the selected jobs | `PublishScheduleModal.vue` + Twilio console |
+| Absence SMS ignored | Phone number not matched in Dispatch Technician (last-10-digits LIKE) | `services/targo-hub/lib/tech-absence-sms.js` → `lookupTechByPhone` |
+| GPS dot stale / missing | Traccar token expired, cache 60s, or no `traccar_device_id` on the tech | `services/targo-hub/lib/traccar.js` |
+| Suggestion always picks same tech | Overload penalty not firing — check `getTechsWithLoad` result for load cap | `services/targo-hub/lib/dispatch.js` |
+| SSE toasts stop arriving | ForwardAuth dropped the session; reload to re-auth with Authentik | `apps/ops/src/pages/DispatchPage.vue` SSE setup |
+| Ghost occurrences missing | RRULE parse failed client-side — malformed `recurrence_rule` | `apps/ops/src/stores/dispatch.js` `_mapJob` |
+| Tech mobile page shows "not found" | JWT expired (default 72h) — operator must re-publish to regenerate | `services/targo-hub/lib/magic-link.js` |
+
+## 9. Retirement Note
+
+The legacy `dispatch-app` (PHP) and `apps/field` (mobile technician SPA) are slated for retirement in April-May 2026, per [../architecture/overview.md](../architecture/overview.md) §1. The replacement pairing is:
+
+- **Ops PWA Dispatch module** — this document — for all scheduling, ranking, publishing.
+- **Lightweight tech mobile page** at `/t/{token}` (see §6) for the field-side experience.
+
+Do not add new features to `dispatch-app` or `apps/field`. Any feature request should land in `apps/ops/src/modules/dispatch/` or the tech-mobile handler in `services/targo-hub/lib/tech-mobile.js`.
+
+---
+
+Back to [docs/README.md](../README.md) · [roadmap.md](../roadmap.md)
diff --git a/docs/features/tech-mobile.md b/docs/features/tech-mobile.md
new file mode 100644
index 0000000..9b3f5c6
--- /dev/null
+++ b/docs/features/tech-mobile.md
@@ -0,0 +1,462 @@
+# Tech Mobile — Field Technician App
+
+> **One feature, three delivery surfaces.** The tech-facing UI (today's jobs,
+> scan-to-identify, equipment install/remove, diagnostic probes) has been
+> rewritten twice and the codebase currently carries all three copies. Know
+> which one a bug is actually in before you start editing.
+
+**Last refreshed:** 2026-04-22
+
+---
+
+## 1. The three surfaces (read this first)
+
+| Surface | URL in the SMS today | Hosted at | Status |
+|---|---|---|---|
+| **Legacy SSR** | `https://msg.gigafibre.ca/t/{jwt}` | `services/targo-hub/lib/tech-mobile.js` — single-file server-rendered HTML+inline JS | **Live.** This is what techs actually open today. |
+| **Transitional PWA** | — (self-navigated) | `apps/field/` — standalone Quasar PWA at `https://erp.gigafibre.ca/field/` behind Authentik | **Live but retiring.** Used by techs who bookmark it; no SMS points here. |
+| **Unified Ops tech module** | — (target) | `apps/ops/src/modules/tech/` mounted at `https://erp.gigafibre.ca/ops/#/j/` | **Live, on deck.** Same auth path as Ops; magic-link handler at `/j/:token` is wired but SMS generator still points at the SSR page. |
+
+**The migration plan** is to flip `FIELD_APP_URL` in `services/targo-hub/lib/config.js`
+from `https://msg.gigafibre.ca` to `https://erp.gigafibre.ca/ops/#/j` (or
+update `generateLink()` to emit that URL directly), at which point the Vue
+SPA becomes the primary surface and the SSR page becomes a fallback for
+browsers too old to parse the SPA. Both the legacy SSR page and the Vue
+pages talk to the same hub endpoints, so cutover is a one-line change plus a
+regression pass.
+
+```text
+                      ┌────────────────────────────────────────┐
+                      │  Dispatch Job created / reassigned     │
+                      │  (Ops staff in /ops/#/dispatch)        │
+                      └──────────────────┬─────────────────────┘
+                                         │  POST /magic-link/refresh
+                                         │  (nightly cron + on-demand)
+                                         ▼
+                    ┌───────────────────────────────────┐
+                    │  targo-hub / magic-link.js        │
+                    │  mint JWT (HS256, 72h)            │
+                    │  + Twilio SMS to tech.phone       │
+                    └──────────────────┬────────────────┘
+                                       │ link:
+                                       │ https://msg.gigafibre.ca/t/{jwt}
+                                       ▼
+            ┌──────────────────────────────────────────┐
+            │ TECH TAPS LINK ON PHONE                  │
+            └──────────────────┬───────────────────────┘
+                               │  (today)            │  (target)
+                               ▼                     ▼
+              ┌──────────────────────────┐  ┌─────────────────────────────┐
+              │ hub/lib/tech-mobile.js   │  │ apps/ops/src/modules/tech/  │
+              │ server-renders HTML,     │  │ Vue SPA; magic-link route   │
+              │ inline JS, <15KB         │  │ /j/:token persists JWT in   │
+              │ Same /vision/* calls     │  │ localStorage then redirects │
+              └──────────────────────────┘  └─────────────────────────────┘
+                               │                     │
+                               └──────┬──────────────┘
+                                      │  all surfaces call:
+                                      ▼
+                   POST https://msg.gigafibre.ca/vision/barcodes
+                   POST https://msg.gigafibre.ca/vision/equipment
+                   POST /api/resource/Dispatch Job/{name}
+                   POST /api/resource/Service Equipment
+```
+
+---
+
+## 2. Auth: magic-link JWT (shared by all three surfaces)
+
+**Implemented in:** `services/targo-hub/lib/magic-link.js`
+
+Two token shapes:
+
+```js
+// Job-scoped: gives access to a single Dispatch Job
+{ sub: techId, job: jobId, iat, exp }
+
+// Tech-scoped: gives access to every job assigned to that tech
+{ sub: techId, scope: 'all', iat, exp }
+```
+
+**TTL:** 72 hours (hard-coded in `generateLink()` / `generateTechLink()`).
+The customer portal uses 24h; techs get longer so a Monday SMS covers a
+full ticket lookahead.
+
+**Signing:** HS256 using `JWT_SIGNING_KEY` from the hub env. Same secret
+signs the customer-portal tokens — rotating it logs everyone out, so it's
+only rotated on incident.
+
+**SMS sender flow (`magic-link.js` → `twilio.js`):**
+
+```text
+POST /magic-link/refresh { tech_id }
+  ↓ ERPNext: lookup Dispatch Technician → phone
+  ↓ generate tech-level JWT (scope=all, 72h)
+  ↓ Twilio: SMS "Voici votre nouveau lien pour accéder à vos tâches: <url>"
+  ↓ log to targo-hub stdout (tech_id + phone number, no token)
+  200 { ok: true, sent_to: "+15145551234" }
+```
+
+**Token verification:**
+
+```text
+GET /magic-link/verify?token=<jwt>
+  200 { ok, tech_id, job_id?, scope, exp }
+  401 { error: 'invalid_or_expired',
+        message: 'Ce lien a expiré. Un nouveau lien vous sera envoyé par SMS.' }
+```
+
+**On the Vue SPA side** (`apps/ops/src/modules/tech/pages/TechTasksPage.vue`,
+route `/j/:token`): the component reads `route.params.token`, calls
+`/magic-link/verify`, stores `{tech_id, exp}` in localStorage, then
+`router.replace({ name: 'tech-tasks' })` so the URL no longer contains the
+raw JWT. Any subsequent 401 re-triggers the expired flow.
+
+---
+
+## 3. Scanner — native camera + Gemini (no JS library)
+
+> **This is the whole point of the feature.** No `html5-qrcode`, no
+> `html5core`, no `ZXing`, no `BarcodeDetector` polyfill. Just the browser's
+> file picker in "camera" mode and a POST to the hub.
+
+**Implementation:** `apps/ops/src/composables/useScanner.js` (Vue SPA) and
+`apps/field/src/composables/useScanner.js` (transitional PWA). The two
+files are byte-identical minus imports — kept in sync by the revert
+bookmark at commit `e50ea88`. The SSR page
+(`services/targo-hub/lib/tech-mobile.js`) inlines an equivalent ~40 lines.
+
+### 3a. The markup
+
+```html
+<input
+  ref="cameraInput"
+  type="file"
+  accept="image/*"
+  capture="environment"
+  class="hidden"
+  @change="onPhoto" />
+```
+
+`capture="environment"` tells iOS Safari / Android Chrome to open the rear
+camera directly with autofocus engaged. We do **not** stream `getUserMedia`
+ourselves — a JS camera has worse focus on close-up serial labels than the
+OS camera does, and burns battery. The user frames one photo, taps the
+shutter, the `<input>`'s `change` event fires with a `File` object, and we
+hand it off.
+
+### 3b. The pipeline
+
+```text
+File (1–4 MB JPEG)
+  ↓ createImageBitmap → 400px thumbnail (for instant UI preview)
+  ↓ createImageBitmap → 1600px long-edge JPEG @ quality 0.92
+  ↓ base64 encode (~500 KB over the wire)
+  ↓ POST https://msg.gigafibre.ca/vision/barcodes
+  ↓           body: { image: "data:image/jpeg;base64,…" }
+  ↓ 200 { barcodes: ["1608K44D9E79FAFF5", "0418D6A1B2C3", "TPLG-A1…"] }
+  ↓ onNewCode(code) callback fires per string, up to MAX_BARCODES = 5
+```
+
+**Timeout:** `SCAN_TIMEOUT_MS = 8000`. Beyond that we give up and either
+(a) offer a retry, or (b) enqueue the image to the offline queue if
+offline.
+
+**Why 3 codes max:** the hub's `responseSchema` caps `barcodes` at 3 items
+(see `services/targo-hub/lib/vision.js`). A single label often has 3–5
+barcodes (EAN, S/N, MAC) stacked — we take the first 3 Gemini ranks as
+most-confident and let the user tap the one that matches. The SPA keeps a
+rolling window of 5 so a tech can re-scan without losing the prior match.
+
+### 3c. Equipment-label mode (structured, not just strings)
+
+When the user opens the scanner **from the "Scanner un code-barres" option
+inside the equipment bottom-sheet** (not the top-level `/j/scan` page), we
+hit `/vision/equipment` instead. That endpoint returns structured fields
+ready to pre-fill the "Create equipment" dialog:
+
+```json
+{
+  "equipment": [
+    {
+      "serial":  "1608K44D9E79FAFF5",
+      "mac":     "04:18:D6:A1:B2:C3",
+      "brand":   "Nokia",
+      "model":   "G-140W-C",
+      "type":    "ONT"
+    }
+  ]
+}
+```
+
+`maxItems: 5`. Same 1600px JPEG. Same 8s timeout. Same offline queue.
+
+### 3d. Offline queue
+
+**Implemented in:** `apps/ops/src/stores/offline.js` (Pinia) via
+`idb-keyval` at key `tech-vision-queue`.
+
+```js
+// When fetch() rejects or navigator.onLine === false:
+enqueueVisionScan({ id, endpoint, imageDataUri, ts, consumer })
+  → persist to IndexedDB
+
+// On navigator.online event:
+watch(isOnline, async now => {
+  if (now) flushQueue()  // replays each scan, fires original consumer
+})
+```
+
+The consumer identifier (`'tech-scan' | 'tech-equip-scan' | …`) lets the
+UI route the late result to the right dialog once the user is back online.
+Scans older than 7 days are dropped on boot.
+
+---
+
+## 4. The Vue SPA surface (`apps/ops/src/modules/tech/`)
+
+Routes, defined in `apps/ops/src/router/index.js`:
+
+```js
+path: '/j',
+component: TechLayout,
+children: [
+  { path: '',               name: 'tech-tasks',  component: TechTasksPage },
+  { path: 'job/:name',      name: 'tech-job',    component: TechJobDetailPage, props: true },
+  { path: 'scan',           name: 'tech-scan',   component: TechScanPage },
+  { path: 'device/:serial', name: 'tech-device', component: TechDevicePage, props: true },
+  { path: 'diagnostic',     name: 'tech-diag',   component: TechDiagnosticPage },
+  { path: 'more',           name: 'tech-more',   component: TechMorePage },
+  { path: ':token',         name: 'tech-magic',  component: TechTasksPage, props: true }, // must be LAST
+],
+```
+
+The magic-link route is deliberately the last child — Vue Router's pattern
+matcher would otherwise swallow `/j/scan` as `token=scan`. If you add a
+new static child, put it **above** the `:token` entry.
+
+### 4a. `TechTasksPage.vue` — today's schedule
+
+Fetches `Dispatch Job` rows filtered by `assigned_tech == sub` and
+`scheduled_date == today` (UTC-Toronto). Groups them by status
+("À venir", "En cours", "Terminée"). Each row navigates to
+`/j/job/:name`.
+
+### 4b. `TechJobDetailPage.vue` — the main tech surface
+
+**458 lines. This is where the ported equipment UX lives — see §5.**
+
+Three cards:
+
+| Card | Fields | Writes? |
+|---|---|---|
+| **Info** | Type (Installation / Dépannage / …), Priority, Duration, Status chip, Description textarea | Yes — `saveField()` debounced 500ms PUTs to `Dispatch Job` |
+| **Location** | Address (click → Google Maps GPS), contact name, contact phone (expandable, lazy-loads `Service Location`) | No — read-only |
+| **Equipment** | List of `Service Equipment` linked to the job; "Ajouter un équipement" bottom-sheet | Yes — see §5 |
+
+Bottom-of-page action buttons:
+- Status `Scheduled` → "Démarrer" → PUT status `In Progress`
+- Status `In Progress` → "Terminer" → PUT status `Completed`
+- Status `Completed` → no button (dispatch has to reopen)
+
+Both status values have legacy aliases (`assigned`, `in_progress`) because
+the SSR page uses ERPNext's Title Case and older Python scripts emit
+lowercase. The computed `statusLabel` handles both.
+
+### 4c. `TechScanPage.vue` — standalone scanner
+
+The top-level scanner route. Accepts any barcode, looks up by serial in
+ERPNext, routes to `/j/device/:serial` on a hit or offers "Create
+equipment" on a miss. Useful for techs auditing a van inventory or
+confirming a serial before scheduled install time.
+
+### 4d. `TechDevicePage.vue` — per-device detail
+
+GET `Service Equipment/:serial` → shows brand, model, MAC, install date,
+linked customer, linked address, recent diagnostic runs (via
+`useSpeedTest` composable). "Retirer" button unlinks from current job
+(PUT `linked_job: null`) but preserves the doc for audit.
+
+### 4e. `TechDiagnosticPage.vue` — speed test + GenieACS probe
+
+Runs an in-browser speed test via `useSpeedTest` and, if the device is
+ACS-managed, fires a `GetParameterValues` against GenieACS through
+`targo-hub /acs/probe`. Results render as a one-page PDF the tech can
+SMS to the customer.
+
+### 4f. `TechMorePage.vue` — settings, logout, version
+
+Shows tech name, token expiry countdown, link to "Request new magic
+link" (POSTs `/magic-link/refresh`), and a hard logout that wipes
+localStorage.
+
+---
+
+## 5. Equipment management (the UX that was re-ported 2026-04-22)
+
+This section drove today's port from `apps/field/src/pages/JobDetailPage.vue`
+→ `apps/ops/src/modules/tech/pages/TechJobDetailPage.vue`. The Ops SPA
+stub had dropped it. It's back.
+
+### 5a. The bottom-sheet trigger
+
+```vue
+<q-btn flat dense label="Ajouter" icon="add" @click="addEquipmentMenu = true" />
+
+<q-dialog v-model="addEquipmentMenu" position="bottom">
+  <q-list>
+    <q-item clickable v-close-popup @click="goToScanner">
+      <q-item-section avatar><q-icon name="qr_code_scanner" /></q-item-section>
+      <q-item-section>Scanner un code-barres / QR</q-item-section>
+    </q-item>
+    <q-item clickable v-close-popup @click="searchEquipDialog = true">
+      <q-item-section avatar><q-icon name="search" /></q-item-section>
+      <q-item-section>Rechercher un équipement existant</q-item-section>
+    </q-item>
+    <q-item clickable v-close-popup @click="createEquipDialog = true">
+      <q-item-section avatar><q-icon name="add_circle" /></q-item-section>
+      <q-item-section>Créer un nouvel équipement</q-item-section>
+    </q-item>
+  </q-list>
+</q-dialog>
+```
+
+### 5b. Scan → link
+
+`goToScanner()` `router.push({ name: 'tech-scan' })`, passing the current
+`jobName` in query string. `TechScanPage` on a barcode hit calls
+`linkEquipToJob(equipment)` which PUTs `linked_job: jobName` on the
+`Service Equipment` row.
+
+### 5c. Search → link
+
+Debounced 400ms on `eqSearchText`. First query is by `serial_number`;
+if that returns empty and the string looks like a MAC
+(hex+separators), falls through to `mac_address`. Results render as
+selectable rows; tap → `linkEquipToJob()`.
+
+### 5d. Create → link (pre-filled from scan or blank)
+
+```js
+const newEquip = ref({
+  serial_number:  '',             // autofocus
+  equipment_type: 'ONT',          // select
+  brand:          '',             // Marque
+  model:          '',             // Modèle
+  mac_address:    '',             // MAC optionnel
+})
+
+const eqTypes = ['ONT', 'Modem', 'Routeur', 'Décodeur TV',
+                 'VoIP', 'Amplificateur', 'Splitter', 'Câble', 'Autre']
+```
+
+`createAndLinkEquip()` POSTs a `Service Equipment` doc with these fields
+plus `status: 'In Service'`, `linked_job: jobName`,
+`service_location: job.service_location`. The doc name is auto-generated
+(ERPNext auto-series `EQ-.####`).
+
+### 5e. "Retirer" (unlink from job, preserve doc)
+
+Button on each equipment row. PUT `linked_job: null` + optional
+`status: 'Returned'`. The doc itself is never deleted — audit trail
+matters.
+
+---
+
+## 6. Hub API endpoints (all three surfaces call these)
+
+Direct ERPNext calls via the tech's JWT (the Vue SPA wraps these in
+`src/api/erp.js`):
+
+```
+GET  /api/resource/Dispatch%20Job?filters=…          → list today's jobs
+GET  /api/resource/Dispatch%20Job/:name              → job detail
+PUT  /api/resource/Dispatch%20Job/:name              → status, priority, etc.
+GET  /api/resource/Service%20Equipment?filters=…    → list linked
+GET  /api/resource/Service%20Equipment/:serial       → detail
+POST /api/resource/Service%20Equipment               → create
+PUT  /api/resource/Service%20Equipment/:serial      → link/unlink
+GET  /api/resource/Service%20Location/:name          → expand location
+```
+
+Hub-mediated calls (all `https://msg.gigafibre.ca/…`):
+
+```
+POST /vision/barcodes          → Gemini vision, {image}  → {barcodes: []}
+POST /vision/equipment         → Gemini vision, {image}  → {equipment: []}
+POST /magic-link/refresh       → reissue + SMS            → {sent_to: "+1…"}
+GET  /magic-link/verify?token  → check expiry             → {tech_id, exp}
+POST /acs/probe                → GenieACS GetParamValues  → {params: {}}
+```
+
+The legacy SSR surface at `/t/{token}/…` replicates a subset of these
+(`/scan`, `/vision`, `/equip`, `/equip-remove`, `/status`, `/catalog`,
+`/equip-list`) but as token-scoped paths rather than REST + JWT header.
+When the SSR page is retired those paths will 410 Gone.
+
+---
+
+## 7. File inventory
+
+```text
+apps/ops/src/modules/tech/pages/
+├── TechTasksPage.vue         (today's jobs, grouped by status)
+├── TechJobDetailPage.vue     ← ported 2026-04-22 (equipment UX)
+├── TechScanPage.vue          (standalone scanner)
+├── TechDevicePage.vue        (per-device detail)
+├── TechDiagnosticPage.vue    (speed test + ACS probe)
+└── TechMorePage.vue          (settings, logout, token expiry)
+
+apps/ops/src/layouts/
+└── TechLayout.vue            (bottom tab bar, mobile-optimized viewport)
+
+apps/ops/src/composables/
+└── useScanner.js             (native <input> + Gemini, offline queue)
+
+apps/ops/src/stores/
+└── offline.js                (IndexedDB queue, online-event flush)
+
+apps/ops/src/api/
+└── erp.js                    (getDoc, listDocs, createDoc, updateDoc wrappers)
+
+apps/field/                   ← transitional PWA, same layout, retiring
+└── src/pages/JobDetailPage.vue    (the 526-line reference for the port)
+
+services/targo-hub/lib/
+├── tech-mobile.js            ← legacy SSR surface at /t/{token}
+├── magic-link.js             ← JWT mint/verify/refresh, shared w/ portal
+└── vision.js                 ← /vision/barcodes + /vision/equipment
+```
+
+---
+
+## 8. Open questions / known gaps
+
+- [ ] **Cutover**: flip `FIELD_APP_URL` (or `generateLink()`) to point at
+      `https://erp.gigafibre.ca/ops/#/j` and retire the SSR page. Needs a
+      regression sweep of the equipment bottom-sheet on iOS Safari 16 and
+      Android Chrome 120.
+- [ ] **Offline create-equipment**: `createDoc` is not queued yet. If a
+      tech creates a device while offline the operation silently
+      `catch()`es. Needs a write queue analogous to `enqueueVisionScan`.
+- [ ] **Dual-language strings**: UI is French-only. Roadmap item to
+      extract to `src/i18n/` once Ops desktop i18n lands.
+- [ ] **Equipment type normalization**: `eqTypes` array is hard-coded.
+      ERPNext has an "Equipment Type" doctype — wire the dropdown to it
+      so new types don't require a frontend deploy.
+- [ ] **GenieACS auto-probe**: currently the tech has to navigate to
+      `/j/diagnostic` manually. Could fire a background probe the moment
+      a device is scanned.
+
+---
+
+## 9. Related docs
+
+- [features/vision-ocr.md](vision-ocr.md) — the Gemini pipeline backing the scanner
+- [features/dispatch.md](dispatch.md) — where `Dispatch Job` rows are created + assigned
+- [features/customer-portal.md](customer-portal.md) — same magic-link pattern, 24h TTL, different token schema
+- [features/cpe-management.md](cpe-management.md) — GenieACS probe called by `TechDiagnosticPage`
+- [architecture/overview.md](../architecture/overview.md) — Traefik routes, Authentik wrapping, hub placement
+- [architecture/module-interactions.md](../architecture/module-interactions.md) — cross-module read/write matrix
+
+Back to [docs/features/README.md](README.md) · [docs/README.md](../README.md)