docs: Smart Pinging, DEFER on the third-party API, Settings Reference rebuilt

docs/admins.md

@@ -187,6 +187,8 @@ The Settings tab is organised into collapsible blocks. The ageing and cleanup co
   - **Enforce Hybrid Mode**: Disables Active mode for wardrivers in your region.  If your regions mesh has an issue with dropped packets due to high mesh traffic or many wardrivers, consider enabling this option.  *(Mobile app functionality will be available with v1.1.0)*
   - **Consider Failed DISC as DROP**: When disabled, Discovery pings that do not receive a reply will not appear on the map.  When enabled, Discovery pings that do not will receive a reply will display as DROP (red) on the map.
   - **Minimum Active/Hybrid Mode Interval**: Optionally set the number of seconds between mesh pings for wardrivers in your region.  If your regions mesh has an issue with dropped packets due to high mesh traffic or many wardrivers, consider setting a higher minimum interval.  *(Mobile app functionality will be available with v1.1.0)*
+  - **Enforce Smart Pinging**: Locks the app's Smart Pinging on for wardrivers in your region, so auto pings are deferred in squares that already have a recent two-way or discovery result and the held ping goes out at the next square without one. Users cannot turn it off while connected to your zone, and your window replaces their own. Wardrivers still earn 1.5 points per verified deferred square. Requires app v1.4.0 or newer; older apps ignore the setting.
+  - **Smart Pinging Window (Days)**: How recent a result must be for a square to count as covered: 1, 3, 7, 14 or 30 days. Only applies while Enforce Smart Pinging is on. Otherwise each user's own window (default 14 days) applies.
   - **Region Message**: Optionally add a message here that will display to map visitors when they click the "Region Info" option.  Direct guests to your Discord server, website, etc.  Field is plain-text and will automatically convert URLs to clickable links.
   - **Social Media Links**: Optionally add any number of social media or website links that will display on the "Region Info" window on your regions map.
   - **MQTT Observers**: Configure the list of letsmesh observers to ingest from.

docs/app_connection_guide.md

@@ -150,11 +150,11 @@ If you don't have internet, or the MeshMapper API is in maintenance mode, use **
 - Zone validation is skipped (zone chip shows a grey dash)
 - All ping data (TX, RX, DISC) is saved to local session files
 - Session files are named by date (e.g., "2026-03-20.json")
-- Manage sessions in **Settings > Offline Sessions**
+- Manage sessions in **Settings > Data > Offline Sessions**
 
 **When you are back online:**
 
-1. Open **Settings > Offline Sessions**
+1. Open **Settings > Data > Offline Sessions**
 2. Tap upload button next to each session to send to MeshMapper
 3. Or download session files for backup
 

docs/app_getting_started.md

@@ -48,7 +48,7 @@ It also discloses that your location data is uploaded to the MeshMapper API and
 After tapping **Continue**, your phone will ask for location permission. Grant "While Using the App" at minimum.
 
 !!! warning "iOS Background Location"
-    If you want to run MeshMapper in the background on iOS (e.g., wardriving with the screen off), you need to manually enable "Background Location" in the MeshMapper Settings tab. Apple restricts apps from requesting background location directly, so the user must enable it themselves. Without this, iOS will throttle or stop GPS updates when the app is not in the foreground.
+    If you want to run MeshMapper in the background on iOS (e.g., wardriving with the screen off), you need to manually enable "Background Location" under Settings > General in MeshMapper. Apple restricts apps from requesting background location directly, so the user must enable it themselves. Without this, iOS will throttle or stop GPS updates when the app is not in the foreground.
 
 ---
 
@@ -104,7 +104,7 @@ Once both are set, tap **Send Ping**:
 
 - The app sends a channel message to #wardriving
 - This message **floods the entire mesh network**, with every repeater relaying it onward
-- **Your GPS position is not in the on-air message.** By default the message carries a short anonymous token — your coordinates are sent only to the MeshMapper server over the internet. (You can opt in to broadcasting coordinates on the air via Settings > Ping Settings > Broadcast My Coordinates.)
+- **Your GPS position is not in the on-air message.** By default the message carries a short anonymous token, and your coordinates are sent only to the MeshMapper server over the internet. (You can opt in to broadcasting coordinates on the air via Settings > Wardriving > Broadcast My Coordinates.)
 - If your regional admin has configured a **scope**, the message stays within that region instead
 - The app listens for **5 seconds** to see which repeaters echoed your message back
 - On the backend, MeshMapper uses **MQTT observers** that also listen to the #wardriving channel. If an observer receives your message, the backend marks that ping as **bidirectional (bidir)**

docs/app_how_it_works.md

@@ -108,6 +108,21 @@ Trace pings target a specific repeater by hex ID:
 
 ---
 
+## How Smart Pinging Works
+
+Smart Pinging is the app's way of not repeating work the map already shows. It is on by default and applies to Hybrid, Passive and Active modes.
+
+1. **Coverage lookup**: While connected, the app keeps MeshMapper's recent coverage for roughly 500m around you loaded. It uses the same vector tiles the map draws, filtered to two-way (green) and discovery (cyan) results inside your Smart Pinging window. The lookup re-checks after every 100m of movement and refreshes tiles older than 5 minutes at the next 100m. Squares you cover yourself during the session (a heard TX, an answered discovery) are marked covered immediately.
+2. **The check**: When an auto ping (TX or discovery) is due, the app looks up the square under your current GPS fix. The square is the cell of your Grid Mode setting (300m, or 100m in Detailed). A recent green or cyan result there means the ping is deferred, and the countdown reads "Deferred". The check runs before the minimum distance rule, so a covered square reads "Deferred" rather than "Skipped".
+3. **The hold**: A deferred ping is banked in a single slot. On every GPS fix the app asks whether you have reached a square with no recent coverage and moved at least your minimum ping distance since the last ping of that kind. If so, the banked ping goes out and the interval timer restarts. A later deferral replaces an earlier one, so at most one ping is ever waiting. The regular interval keeps running underneath, so a phone that never reaches a fresh square still tries at its normal cadence.
+4. **Fail open**: If the coverage data is not loaded yet, a fetch failed, you are outside a zone, or you are in Offline Mode, the lookup answers "unknown" and the ping is sent as normal. Smart Pinging only ever holds a ping it knows to be redundant.
+5. **Credit**: A deferred ping posts no coverage row, so on its own it would cost you the point that ping would have earned. Instead the app reports a small `DEFER` item for each square where it held a ping (one per 300m square per session, whatever your Grid Mode) in the normal upload batch. MeshMapper verifies the square really was covered in its own data, drops any it cannot confirm, and credits the accepted ones at 1.5 points each. Accepted squares also drive the Airtime awards and the Top Airtime Savers leaderboard.
+
+!!! note
+    Manual pings, Trace Mode and passive RX listening are never deferred. RX is free coverage, and the other two are you asking for a specific measurement.
+
+---
+
 ## Packet Filtering and Validation
 
 Every packet goes through a strict validation pipeline before being accepted. If a packet fails any step, it is dropped immediately.
@@ -206,7 +221,7 @@ A "carpeater" (car + repeater) is a repeater mounted in/on your vehicle. It will
 **Two filter methods:**
 
 1. **RSSI threshold**: RSSI equal to or stronger (closer to 0) than -30 dBm → automatically dropped (device is right next to you)
-2. **User-configured repeater ID**: Specify your repeater's hex ID in Settings > Filtering > CARpeater Filter. Echoes from that repeater are stripped before upload.
+2. **User-configured repeater ID**: Set your repeater's full public key in Settings > Wardriving > CARpeater Filter. Echoes from that repeater are stripped before upload.
 
 Both can be adjusted or disabled in Settings for testing.
 
@@ -222,7 +237,7 @@ Each packet carries a "path" showing which repeaters it traveled through, with e
 
 **Key details:**
 
-- Configurable in Settings > Radio > TX Bytes (firmware 1.14+ required)
+- Configurable in Settings > Wardriving > Radio > TX Bytes (firmware 1.14+ required)
 - RX auto-detects path size regardless of your TX setting
 - Regional administrators can require a specific TX path setting in the admin panel