From 15b65b59a3326e3577c1f0f1b17187b80cfc3bd7 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Wed, 23 Sep 2026 14:01:13 +0800
Subject: [PATCH 01/24] Add telematics data retention settings and prune sweep

Telematics polling writes a device event, a position and a delivery envelope per
reporting device per poll, and nothing bounded device_events or positions. Add a
per-company retention policy (Fleet-Ops > Settings > Telematics Data, with admin
system defaults) enforced by fleetops:prune-telematics-data every fifteen minutes
in bounded hard-delete batches, with raw payload compaction, inbox tables resolved
through connections, an orphan sweep, dry-run/filter/lock options, supporting
indexes, a storage usage endpoint and an on-demand cleanup job.

Ingestion fixes: device_events.meta no longer duplicates the raw provider unit,
and telemetry-driven saves skip the activity log unless the company opts in. The
drain command now only recovers deliveries and finishes interrupted runs.
---
 RELEASE.md                                    |  23 +-
 .../components/admin/telematics-settings.hbs  |  44 +++
 addon/components/admin/telematics-settings.js |  76 +++++
 addon/components/layout/fleet-ops-sidebar.js  |   6 +-
 addon/controllers/settings/index.js           |   8 +
 addon/controllers/settings/telematics.js      | 171 ++++++++++
 addon/extension.js                            |   6 +
 addon/routes.js                               |   1 +
 addon/routes/settings/telematics.js           |  16 +
 addon/templates/settings/telematics.hbs       | 128 +++++++
 app/components/admin/telematics-settings.js   |   1 +
 app/controllers/settings/telematics.js        |   1 +
 app/routes/settings/telematics.js             |   1 +
 app/templates/settings/telematics.js          |   1 +
 composer.json                                 |   2 +-
 docs/AFAQY.md                                 |   2 +-
 docs/TELEMATICS_QUEUES.md                     |   2 +-
 docs/TELEMETRY_ARCHITECTURE.md                |  49 ++-
 extension.json                                |   2 +-
 package.json                                  |   2 +-
 server/config/telemetry.php                   |   9 +
 ...1_add_retention_index_to_device_events.php |  40 +++
 ...00002_add_retention_index_to_positions.php |  40 +++
 ...retention_index_to_telematic_sync_runs.php |  40 +++
 server/src/Auth/Schemas/FleetOps.php          |  20 ++
 .../Console/Commands/DrainTelematicInbox.php  |  16 +-
 .../Console/Commands/PruneTelematicsData.php  | 304 +++++++++++++++++
 .../Internal/v1/SettingController.php         | 199 +++++++++++
 server/src/Jobs/PruneTelematicsDataJob.php    |  63 ++++
 .../src/Providers/FleetOpsServiceProvider.php |   3 +
 server/src/Support/Database/TableIndexes.php  |  66 ++++
 .../Telematics/Retention/RetentionPolicy.php  | 232 +++++++++++++
 .../Retention/TelemetryActivity.php           |  40 +++
 .../Support/Telematics/TelematicService.php   |  14 +-
 .../Support/Telematics/Telemetry/Ingestor.php |   6 +-
 server/src/routes.php                         |   6 +
 .../Http/AfaqyRealtimeIngestionTest.php       |  17 +-
 .../TelematicsRetentionIndexMigrationTest.php | 115 +++++++
 server/tests/ProviderContractsTest.php        |  10 +
 .../tests/SettingControllerContractsTest.php  | 240 +++++++++++++
 .../Support/PruneTelematicsDataProbe.php      |  55 +++
 .../PruneTelematicsDataCommandTest.php        | 314 ++++++++++++++++++
 .../Unit/Jobs/PruneTelematicsDataJobTest.php  |  48 +++
 .../Retention/RetentionPolicyTest.php         | 130 ++++++++
 .../Retention/TelemetryActivityTest.php       |  60 ++++
 .../admin/telematics-settings-test.js         |  54 +++
 .../controllers/settings/telematics-test.js   | 117 +++++++
 tests/unit/routes/settings/telematics-test.js |  58 ++++
 translations/en-us.yaml                       |  43 +++
 49 files changed, 2866 insertions(+), 35 deletions(-)
 create mode 100644 addon/components/admin/telematics-settings.hbs
 create mode 100644 addon/components/admin/telematics-settings.js
 create mode 100644 addon/controllers/settings/telematics.js
 create mode 100644 addon/routes/settings/telematics.js
 create mode 100644 addon/templates/settings/telematics.hbs
 create mode 100644 app/components/admin/telematics-settings.js
 create mode 100644 app/controllers/settings/telematics.js
 create mode 100644 app/routes/settings/telematics.js
 create mode 100644 app/templates/settings/telematics.js
 create mode 100644 server/migrations/2026_09_23_000001_add_retention_index_to_device_events.php
 create mode 100644 server/migrations/2026_09_23_000002_add_retention_index_to_positions.php
 create mode 100644 server/migrations/2026_09_23_000003_add_retention_index_to_telematic_sync_runs.php
 create mode 100644 server/src/Console/Commands/PruneTelematicsData.php
 create mode 100644 server/src/Jobs/PruneTelematicsDataJob.php
 create mode 100644 server/src/Support/Database/TableIndexes.php
 create mode 100644 server/src/Support/Telematics/Retention/RetentionPolicy.php
 create mode 100644 server/src/Support/Telematics/Retention/TelemetryActivity.php
 create mode 100644 server/tests/Feature/Http/Api/TelematicsRetentionIndexMigrationTest.php
 create mode 100644 server/tests/Support/PruneTelematicsDataProbe.php
 create mode 100644 server/tests/Unit/Console/PruneTelematicsDataCommandTest.php
 create mode 100644 server/tests/Unit/Jobs/PruneTelematicsDataJobTest.php
 create mode 100644 server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php
 create mode 100644 server/tests/Unit/Support/Telematics/Retention/TelemetryActivityTest.php
 create mode 100644 tests/integration/components/admin/telematics-settings-test.js
 create mode 100644 tests/unit/controllers/settings/telematics-test.js
 create mode 100644 tests/unit/routes/settings/telematics-test.js

diff --git a/RELEASE.md b/RELEASE.md
index 32ebd138d..56b6d7d34 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,23 +1,28 @@
-> v0.6.69 ~ "Fleet-Ops tools for Fleetbase AI"
+> v0.6.70 ~ "Telematics data retention"
 
 ---
 ## What's New
-- **Fleet-Ops works with Fleetbase AI tool calling.** Creating orders from the AI prompt works again with the tool-calling assistant, and the assistant can also propose an optimized waypoint sequence for an order and explain what an order or resource import needs. Every change is a preview card the user confirms.
-- **Fleet-Ops console actions.** The assistant can offer to open Fleet-Ops pages and dialogs, such as **Operations › Orders** and **New Order**, as confirmation cards.
-- **Resource search for the assistant.** A `fleetops_search` tool finds orders, vehicles, drivers, work orders, maintenances, devices, sensors and telematics records by id, name, plate, VIN, email or phone.
+- **Telematics Data settings.** A new Fleet-Ops → Settings → Telematics Data page lets each organization decide how long telemetry is kept: device events, raw event payloads, positions, processed and quarantined delivery envelopes, and sync run diagnostics. Administrators set system-wide defaults from the admin console (Fleet-Ops Config → Telematics Data). A value of 0 keeps rows forever.
+- **Scheduled retention sweep.** `fleetops:prune-telematics-data` runs every fifteen minutes and applies each organization's policy in bounded batches, so a large backlog is drained gradually without stalling ingestion. Defaults: events 30 days, raw payloads stripped after 7 days, positions 90 days, processed deliveries 24 hours, quarantined deliveries 7 days, sync runs 7 days.
+- **Storage usage and on-demand cleanup.** The settings page shows rows, oldest row and estimated size per table for your organization, and "Run cleanup now" queues an immediate retention run.
 
 ---
 ## Fixes
-- AI resource search no longer fails on every call with `Unknown column 'sensor_type'`, and database errors are no longer passed to the model.
+- Device events no longer store the raw provider unit twice. `payload` keeps the raw unit; `meta` holds only the normalized block (speed, heading, odometer, ignition, fuel level, timing). New event rows are roughly half the size.
+- Telemetry-driven saves (device, event, position, vehicle, sensors) no longer write to the activity log on every poll. Organizations that want them can enable "Log telemetry activity" in Telematics Data settings. Manual edits are logged as before.
+- Delivery inbox and sync run retention moved from the drain command into the retention sweep; `fleetops:drain-telematic-inbox` now only recovers deliveries and finishes interrupted runs.
 
 ---
-## Dependencies
-- `@fleetbase/fleetops-data` upgraded to `^0.2.2`, which adds the read-only login state (`is_staff_linked`, `login_status`) to the driver and contact models.
-- `@fleetbase/ember-ui` upgraded to `^0.4.3`, which provides the `btn-auth` style the Track Order button on the login page uses.
+## Upgrade notes
+- New indexes on `device_events (company_uuid, created_at)`, `positions (company_uuid, created_at)` and `telematic_sync_runs (telematic_uuid, updated_at)`; on very large tables run `php artisan migrate` in a maintenance window.
+- Retention is enabled by default. Existing rows older than the defaults are removed over successive runs after upgrading; set the values to 0 before upgrading if you need to keep history indefinitely.
+- Deleting rows frees space inside the database files, not on disk. Run `OPTIMIZE TABLE` off-peak to return space to the operating system.
+- Run `php artisan fleetbase:create-permissions` to register the `telematics-settings` permission and the Telematics Settings Manager policy and role.
 
 ---
 ## Testing
-- Unit tests cover the new AI tools and console commands, and the AI capability registration.
+- Backend tests cover the retention policy layering and clamping, the prune command (per-company policies, compaction, inbox tables via connections, orphans, batch caps, dry runs, filters, locking), the settings and storage usage endpoints, the index migrations, the on-demand job, and the meta and activity-log changes to ingestion.
+- Ember tests cover the settings route guard, the settings controller, and the admin defaults component.
 
 ---
 ## Need help?
diff --git a/addon/components/admin/telematics-settings.hbs b/addon/components/admin/telematics-settings.hbs
new file mode 100644
index 000000000..6c225c74b
--- /dev/null
+++ b/addon/components/admin/telematics-settings.hbs
@@ -0,0 +1,44 @@
+<div class="space-y-6">
+    {{#unless @embedded}}
+        <InfoBlock @type="info" @icon="circle-info" class="mb-4">
+            Configure system-wide telematics data retention defaults here. Organizations can override these values from Fleet-Ops &rsaquo; Settings &rsaquo; Telematics Data. A value of 0 keeps rows forever.
+        </InfoBlock>
+    {{/unless}}
+
+    <ContentPanel @title="Retention Defaults" @open={{true}} @wrapperClass="bordered-classic">
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <InputGroup @name="Device Event Retention (days)" @helpText="Delete telemetry events older than this. 0 keeps them forever.">
+                <Input @type="number" @value={{this.eventRetentionDays}} min="0" max="3650" class="form-input w-full" />
+            </InputGroup>
+            <InputGroup @name="Strip Raw Payloads After (days)" @helpText="Remove the raw provider payload from kept events after this many days. 0 disables compaction.">
+                <Input @type="number" @value={{this.eventCompactAfterDays}} min="0" max="3650" class="form-input w-full" />
+            </InputGroup>
+            <InputGroup @name="Position Retention (days)" @helpText="Delete vehicle and trailer positions older than this. 0 keeps them forever.">
+                <Input @type="number" @value={{this.positionRetentionDays}} min="0" max="3650" class="form-input w-full" />
+            </InputGroup>
+            <InputGroup @name="Processed Deliveries (hours)" @helpText="Delete processed delivery envelopes older than this.">
+                <Input @type="number" @value={{this.processedRetentionHours}} min="0" max="720" class="form-input w-full" />
+            </InputGroup>
+            <InputGroup @name="Quarantined Deliveries (days)" @helpText="Delete quarantined delivery envelopes older than this.">
+                <Input @type="number" @value={{this.quarantineRetentionDays}} min="0" max="365" class="form-input w-full" />
+            </InputGroup>
+            <InputGroup @name="Sync Runs (days)" @helpText="Delete finished sync run diagnostics older than this.">
+                <Input @type="number" @value={{this.syncRunRetentionDays}} min="0" max="365" class="form-input w-full" />
+            </InputGroup>
+        </div>
+        <InputGroup @name="Log Telemetry Activity" @helpText="Write telemetry-driven device, event and vehicle saves to the activity log. Off by default; every poll otherwise adds several activity rows per device.">
+            <Toggle @isToggled={{this.logTelemetryActivity}} @onToggle={{fn (mut this.logTelemetryActivity)}} />
+        </InputGroup>
+        <div class="flex justify-end mt-4">
+            <Button
+                @type="primary"
+                @size="sm"
+                @icon="save"
+                @text="Save Defaults"
+                @onClick={{perform this.saveSettings}}
+                @disabled={{this.saveSettings.isRunning}}
+                @isLoading={{or this.saveSettings.isRunning this.loadSettings.isRunning}}
+            />
+        </div>
+    </ContentPanel>
+</div>
diff --git a/addon/components/admin/telematics-settings.js b/addon/components/admin/telematics-settings.js
new file mode 100644
index 000000000..c030990f9
--- /dev/null
+++ b/addon/components/admin/telematics-settings.js
@@ -0,0 +1,76 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { task } from 'ember-concurrency';
+
+/**
+ * System-wide telematics retention defaults, applied to every company that
+ * has not set its own values from Fleet-Ops > Settings > Telematics Data.
+ */
+export default class AdminTelematicsSettingsComponent extends Component {
+    @service fetch;
+    @service notifications;
+    @tracked eventRetentionDays = 30;
+    @tracked eventCompactAfterDays = 7;
+    @tracked positionRetentionDays = 90;
+    @tracked processedRetentionHours = 24;
+    @tracked quarantineRetentionDays = 7;
+    @tracked syncRunRetentionDays = 7;
+    @tracked logTelemetryActivity = false;
+
+    constructor() {
+        super(...arguments);
+        this.loadSettings.perform();
+    }
+
+    @task *loadSettings() {
+        try {
+            const settings = yield this.fetch.get('fleet-ops/settings/admin-telematics-settings');
+            this.applySettings(settings);
+        } catch (error) {
+            this.notifications.serverError(error);
+        }
+    }
+
+    @task *saveSettings() {
+        try {
+            const settings = yield this.fetch.post('fleet-ops/settings/admin-telematics-settings', this.settingsPayload);
+            this.applySettings(settings);
+            this.notifications.success('Telematics retention defaults saved.');
+        } catch (error) {
+            this.notifications.serverError(error);
+        }
+    }
+
+    get settingsPayload() {
+        return {
+            event_retention_days: this.toInteger(this.eventRetentionDays),
+            event_compact_after_days: this.toInteger(this.eventCompactAfterDays),
+            position_retention_days: this.toInteger(this.positionRetentionDays),
+            processed_retention_hours: this.toInteger(this.processedRetentionHours),
+            quarantine_retention_days: this.toInteger(this.quarantineRetentionDays),
+            sync_run_retention_days: this.toInteger(this.syncRunRetentionDays),
+            log_telemetry_activity: Boolean(this.logTelemetryActivity),
+        };
+    }
+
+    applySettings(settings = {}) {
+        if (!settings) {
+            return;
+        }
+
+        this.eventRetentionDays = settings.event_retention_days ?? this.eventRetentionDays;
+        this.eventCompactAfterDays = settings.event_compact_after_days ?? this.eventCompactAfterDays;
+        this.positionRetentionDays = settings.position_retention_days ?? this.positionRetentionDays;
+        this.processedRetentionHours = settings.processed_retention_hours ?? this.processedRetentionHours;
+        this.quarantineRetentionDays = settings.quarantine_retention_days ?? this.quarantineRetentionDays;
+        this.syncRunRetentionDays = settings.sync_run_retention_days ?? this.syncRunRetentionDays;
+        this.logTelemetryActivity = settings.log_telemetry_activity ?? this.logTelemetryActivity;
+    }
+
+    toInteger(value) {
+        const number = parseInt(value, 10);
+
+        return Number.isFinite(number) && number > 0 ? number : 0;
+    }
+}
diff --git a/addon/components/layout/fleet-ops-sidebar.js b/addon/components/layout/fleet-ops-sidebar.js
index 0abf9056f..c7394f079 100644
--- a/addon/components/layout/fleet-ops-sidebar.js
+++ b/addon/components/layout/fleet-ops-sidebar.js
@@ -210,6 +210,7 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
             this.createItem('menu.routing', 'route', 'settings.routing', 'fleet-ops view routing-settings', 'fleet-ops see routing-settings'),
             this.createItem('menu.orchestrator', 'circle-nodes', 'settings.orchestrator', 'fleet-ops view routing-settings', 'fleet-ops see routing-settings'),
             this.createItem('menu.scheduling', 'calendar-days', 'settings.scheduling', 'fleet-ops view scheduling-settings', 'fleet-ops see scheduling-settings'),
+            this.createItem('menu.telematics-settings', 'database', 'settings.telematics', 'fleet-ops view telematics-settings', 'fleet-ops see telematics-settings'),
             this.createItem('menu.custom-fields', 'pen-to-square', 'settings.custom-fields', 'fleet-ops view custom-field', 'fleet-ops see custom-field'),
             this.createItem('menu.avatars', 'icons', 'settings.avatars', 'fleet-ops view avatar', 'fleet-ops see avatar'),
         ]);
@@ -387,8 +388,9 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
             'settings.routing': 5,
             'settings.orchestrator': 6,
             'settings.scheduling': 7,
-            'settings.custom-fields': 8,
-            'settings.avatars': 9,
+            'settings.telematics': 8,
+            'settings.custom-fields': 9,
+            'settings.avatars': 10,
         };
 
         return priorities[route] ?? 0;
diff --git a/addon/controllers/settings/index.js b/addon/controllers/settings/index.js
index 9ec9284b8..771f45f0c 100644
--- a/addon/controllers/settings/index.js
+++ b/addon/controllers/settings/index.js
@@ -28,6 +28,7 @@ export default class SettingsIndexController extends Controller {
             description: 'Keep commerce, metadata, and visual conventions aligned.',
             links: [
                 { label: 'Payments', route: 'settings.payments', icon: 'cash-register', description: 'Payment setup for operational commerce workflows.' },
+                { label: 'Telematics Data', route: 'settings.telematics', icon: 'database', description: 'Retention and storage for telemetry events, positions, and delivery history.' },
                 { label: 'Custom Fields', route: 'settings.custom-fields', icon: 'pen-to-square', description: 'Operational metadata fields for Fleet-Ops records.' },
                 { label: 'Avatars', route: 'settings.avatars', icon: 'icons', description: 'Visual assets for driver, vehicle, and map displays.' },
             ],
@@ -113,6 +114,13 @@ export default class SettingsIndexController extends Controller {
             title: 'Scheduling settings',
             description: 'Manage schedule templates and timing rules for planned work.',
         },
+        {
+            label: 'Telematics Data',
+            icon: 'database',
+            slug: 'fleet-ops/settings/telematics',
+            title: 'Telematics data settings',
+            description: 'Control how long telemetry events, positions, and delivery history are kept.',
+        },
         {
             label: 'Custom Fields',
             icon: 'pen-to-square',
diff --git a/addon/controllers/settings/telematics.js b/addon/controllers/settings/telematics.js
new file mode 100644
index 000000000..712f9c6ba
--- /dev/null
+++ b/addon/controllers/settings/telematics.js
@@ -0,0 +1,171 @@
+import Controller from '@ember/controller';
+import { tracked } from '@glimmer/tracking';
+import { inject as service } from '@ember/service';
+import { action } from '@ember/object';
+import { task, timeout } from 'ember-concurrency';
+
+/**
+ * Settings::TelematicsController
+ *
+ * Company-level data retention for telematics ingestion:
+ *   - How long device events are kept, and when their raw provider payloads are stripped
+ *   - How long positions are kept
+ *   - How long processed and quarantined delivery envelopes and sync runs are kept
+ *   - Whether telemetry-driven saves are written to the activity log
+ * plus a read-only view of the rows each table holds and an on-demand cleanup run.
+ */
+export default class SettingsTelematicsController extends Controller {
+    @service fetch;
+    @service notifications;
+    @service intl;
+    @service currentUser;
+    @service modalsManager;
+
+    /** Days to keep device events; 0 keeps them forever. */
+    @tracked eventRetentionDays = 30;
+
+    /** Days after which raw payload/meta blobs are stripped from kept events; 0 disables compaction. */
+    @tracked eventCompactAfterDays = 7;
+
+    /** Days to keep positions; 0 keeps them forever. */
+    @tracked positionRetentionDays = 90;
+
+    /** Hours to keep processed delivery envelopes. */
+    @tracked processedRetentionHours = 24;
+
+    /** Days to keep quarantined delivery envelopes. */
+    @tracked quarantineRetentionDays = 7;
+
+    /** Days to keep sync run diagnostics. */
+    @tracked syncRunRetentionDays = 7;
+
+    /** Whether telemetry-driven saves are written to the activity log. */
+    @tracked logTelemetryActivity = false;
+
+    /** System defaults and clamp limits reported by the API. */
+    @tracked defaults = {};
+    @tracked limits = {};
+
+    /** Per-table storage usage reported by the API. */
+    @tracked usage = null;
+
+    get isAdmin() {
+        return this.currentUser.isAdmin === true;
+    }
+
+    /** Compaction is pointless once events are deleted at the same age or sooner. */
+    get compactionIneffective() {
+        const retention = Number(this.eventRetentionDays);
+        const compactAfter = Number(this.eventCompactAfterDays);
+
+        return retention > 0 && compactAfter > 0 && compactAfter >= retention;
+    }
+
+    get usageRows() {
+        const tables = this.usage?.tables ?? {};
+
+        return ['device_events', 'positions', 'telematic_deliveries', 'telematic_sync_runs']
+            .filter((table) => tables[table])
+            .map((table) => ({ table, label: this.intl.t(`settings.telematics.tables.${table}`), ...tables[table] }));
+    }
+
+    get settingsPayload() {
+        return {
+            event_retention_days: this.toInteger(this.eventRetentionDays),
+            event_compact_after_days: this.toInteger(this.eventCompactAfterDays),
+            position_retention_days: this.toInteger(this.positionRetentionDays),
+            processed_retention_hours: this.toInteger(this.processedRetentionHours),
+            quarantine_retention_days: this.toInteger(this.quarantineRetentionDays),
+            sync_run_retention_days: this.toInteger(this.syncRunRetentionDays),
+            log_telemetry_activity: Boolean(this.logTelemetryActivity),
+        };
+    }
+
+    constructor() {
+        super(...arguments);
+        this.getSettings.perform();
+        this.loadUsage.perform();
+    }
+
+    /**
+     * Load retention settings from the backend.
+     */
+    @task *getSettings() {
+        try {
+            const settings = yield this.fetch.get('fleet-ops/settings/telematics-settings');
+            this.applySettings(settings);
+        } catch {
+            // Settings may not exist yet — use defaults silently
+        }
+    }
+
+    /**
+     * Save retention settings to the backend.
+     */
+    @task *saveSettings() {
+        try {
+            const settings = yield this.fetch.post('fleet-ops/settings/telematics-settings', this.settingsPayload);
+            this.applySettings(settings);
+            this.notifications.success(this.intl.t('settings.telematics.settings-saved'));
+        } catch (error) {
+            this.notifications.serverError(error);
+        }
+    }
+
+    /**
+     * Load per-table storage usage for the current company.
+     */
+    @task *loadUsage() {
+        try {
+            this.usage = yield this.fetch.get('fleet-ops/settings/telematics-storage-usage');
+        } catch {
+            this.usage = null;
+        }
+    }
+
+    /**
+     * Queue an immediate retention run for the current company, then refresh usage.
+     */
+    @task *runCleanup() {
+        try {
+            yield this.fetch.post('fleet-ops/settings/telematics-retention/run');
+            this.notifications.success(this.intl.t('settings.telematics.cleanup-queued'));
+            yield timeout(5000);
+            yield this.loadUsage.perform();
+        } catch (error) {
+            this.notifications.serverError(error);
+        }
+    }
+
+    @action confirmRunCleanup() {
+        return this.modalsManager.confirm({
+            title: this.intl.t('settings.telematics.run-cleanup'),
+            body: this.intl.t('settings.telematics.run-cleanup-confirm'),
+            acceptButtonText: this.intl.t('settings.telematics.run-cleanup'),
+            acceptButtonIcon: 'broom',
+            onConfirm: () => this.runCleanup.perform(),
+        });
+    }
+
+    applySettings(settings = {}) {
+        if (!settings) {
+            return;
+        }
+
+        this.eventRetentionDays = settings.event_retention_days ?? this.eventRetentionDays;
+        this.eventCompactAfterDays = settings.event_compact_after_days ?? this.eventCompactAfterDays;
+        this.positionRetentionDays = settings.position_retention_days ?? this.positionRetentionDays;
+        this.processedRetentionHours = settings.processed_retention_hours ?? this.processedRetentionHours;
+        this.quarantineRetentionDays = settings.quarantine_retention_days ?? this.quarantineRetentionDays;
+        this.syncRunRetentionDays = settings.sync_run_retention_days ?? this.syncRunRetentionDays;
+        this.logTelemetryActivity = settings.log_telemetry_activity ?? this.logTelemetryActivity;
+        this.defaults = settings.defaults ?? this.defaults;
+        this.limits = settings.limits ?? this.limits;
+    }
+
+    toInteger(value) {
+        const number = parseInt(value, 10);
+
+        return Number.isFinite(number) && number > 0 ? number : 0;
+    }
+}
diff --git a/addon/extension.js b/addon/extension.js
index bcf5b4602..b69ee334a 100644
--- a/addon/extension.js
+++ b/addon/extension.js
@@ -101,6 +101,11 @@ export default {
                     icon: 'location-arrow',
                     component: new ExtensionComponent('@fleetbase/fleetops-engine', 'admin/navigator-app'),
                 }),
+                new MenuItem({
+                    title: 'Telematics Data',
+                    icon: 'database',
+                    component: new ExtensionComponent('@fleetbase/fleetops-engine', 'admin/telematics-settings'),
+                }),
             ],
             {
                 slug: 'fleet-ops',
@@ -456,6 +461,7 @@ export default {
             'fleet-ops:template:settings:routing',
             'fleet-ops:template:settings:orchestrator',
             'fleet-ops:component:admin:routing-settings',
+            'fleet-ops:component:admin:telematics-settings',
         ]);
     },
 };
diff --git a/addon/routes.js b/addon/routes.js
index 3454717b5..9596e2885 100644
--- a/addon/routes.js
+++ b/addon/routes.js
@@ -323,6 +323,7 @@ export default buildRoutes(function () {
         this.route('map');
         this.route('orchestrator');
         this.route('scheduling');
+        this.route('telematics');
         this.route('payments', function () {
             this.route('index', { path: '/' });
             this.route('onboard');
diff --git a/addon/routes/settings/telematics.js b/addon/routes/settings/telematics.js
new file mode 100644
index 000000000..73e817fd3
--- /dev/null
+++ b/addon/routes/settings/telematics.js
@@ -0,0 +1,16 @@
+import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
+
+export default class SettingsTelematicsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view telematics-settings')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/templates/settings/telematics.hbs b/addon/templates/settings/telematics.hbs
new file mode 100644
index 000000000..f8595f9f4
--- /dev/null
+++ b/addon/templates/settings/telematics.hbs
@@ -0,0 +1,128 @@
+<Layout::Section::Header @title={{t "settings.telematics.telematics-settings"}}>
+    <Button
+        @type="primary"
+        @size="sm"
+        @icon="save"
+        @text={{t "common.save-changes"}}
+        @onClick={{perform this.saveSettings}}
+        @disabled={{this.saveSettings.isRunning}}
+        @isLoading={{or this.saveSettings.isRunning this.getSettings.isRunning}}
+    />
+</Layout::Section::Header>
+<Layout::Section::Body class="overflow-y-scroll-i h-full">
+    <div class="container mx-auto h-screen">
+        <div class="max-w-3xl my-10 mx-auto space-y-6">
+
+            <InfoBlock @type="info" @icon="circle-info">
+                {{t "settings.telematics.intro"}}
+            </InfoBlock>
+
+            {{! ── Device events ────────────────────────────────────────────── }}
+            <ContentPanel @title={{t "settings.telematics.device-events"}} @open={{true}} @wrapperClass="bordered-classic">
+                <InputGroup @name={{t "settings.telematics.event-retention-days"}} @helpText={{t "settings.telematics.event-retention-days-help"}}>
+                    <Input @type="number" @value={{this.eventRetentionDays}} min="0" max="3650" class="w-full form-input" />
+                </InputGroup>
+                <InputGroup @name={{t "settings.telematics.event-compact-after-days"}} @helpText={{t "settings.telematics.event-compact-after-days-help"}}>
+                    <Input @type="number" @value={{this.eventCompactAfterDays}} min="0" max="3650" class="w-full form-input" />
+                </InputGroup>
+                {{#if this.compactionIneffective}}
+                    <InfoBlock @type="warning" @icon="triangle-exclamation">
+                        {{t "settings.telematics.compaction-warning"}}
+                    </InfoBlock>
+                {{/if}}
+            </ContentPanel>
+
+            {{! ── Positions ────────────────────────────────────────────────── }}
+            <ContentPanel @title={{t "settings.telematics.positions"}} @open={{true}} @wrapperClass="bordered-classic">
+                <InputGroup @name={{t "settings.telematics.position-retention-days"}} @helpText={{t "settings.telematics.position-retention-days-help"}}>
+                    <Input @type="number" @value={{this.positionRetentionDays}} min="0" max="3650" class="w-full form-input" />
+                </InputGroup>
+            </ContentPanel>
+
+            {{! ── Delivery inbox & sync runs ───────────────────────────────── }}
+            <ContentPanel @title={{t "settings.telematics.inbox"}} @open={{true}} @wrapperClass="bordered-classic">
+                <InputGroup @name={{t "settings.telematics.processed-retention-hours"}} @helpText={{t "settings.telematics.processed-retention-hours-help"}}>
+                    <Input @type="number" @value={{this.processedRetentionHours}} min="0" max="720" class="w-full form-input" />
+                </InputGroup>
+                <InputGroup @name={{t "settings.telematics.quarantine-retention-days"}} @helpText={{t "settings.telematics.quarantine-retention-days-help"}}>
+                    <Input @type="number" @value={{this.quarantineRetentionDays}} min="0" max="365" class="w-full form-input" />
+                </InputGroup>
+                <InputGroup @name={{t "settings.telematics.sync-run-retention-days"}} @helpText={{t "settings.telematics.sync-run-retention-days-help"}}>
+                    <Input @type="number" @value={{this.syncRunRetentionDays}} min="0" max="365" class="w-full form-input" />
+                </InputGroup>
+            </ContentPanel>
+
+            {{! ── Activity logging ─────────────────────────────────────────── }}
+            <ContentPanel @title={{t "settings.telematics.activity-logging"}} @open={{true}} @wrapperClass="bordered-classic">
+                <InputGroup @name={{t "settings.telematics.log-telemetry-activity"}} @helpText={{t "settings.telematics.log-telemetry-activity-help"}}>
+                    <Toggle @isToggled={{this.logTelemetryActivity}} @onToggle={{fn (mut this.logTelemetryActivity)}} />
+                </InputGroup>
+            </ContentPanel>
+
+            {{! ── Storage usage ────────────────────────────────────────────── }}
+            <ContentPanel @title={{t "settings.telematics.storage-usage"}} @open={{true}} @wrapperClass="bordered-classic">
+                <div class="flex items-center justify-end gap-2 mb-3">
+                    <Button @size="xs" @icon="rotate" @text={{t "settings.telematics.refresh"}} @onClick={{perform this.loadUsage}} @isLoading={{this.loadUsage.isRunning}} />
+                    <Button
+                        @type="danger"
+                        @size="xs"
+                        @icon="broom"
+                        @text={{t "settings.telematics.run-cleanup"}}
+                        @onClick={{this.confirmRunCleanup}}
+                        @disabled={{this.runCleanup.isRunning}}
+                        @isLoading={{this.runCleanup.isRunning}}
+                    />
+                </div>
+                {{#if this.usageRows.length}}
+                    <div class="overflow-x-auto">
+                        <table class="w-full text-sm">
+                            <thead>
+                                <tr class="text-left text-xs uppercase text-gray-500 dark:text-gray-400">
+                                    <th class="py-2 pr-3">{{t "settings.telematics.table"}}</th>
+                                    <th class="py-2 pr-3 text-right">{{t "settings.telematics.rows"}}</th>
+                                    <th class="py-2 pr-3 text-right">{{t "settings.telematics.estimated-size"}}</th>
+                                    <th class="py-2">{{t "settings.telematics.oldest"}}</th>
+                                </tr>
+                            </thead>
+                            <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+                                {{#each this.usageRows as |row|}}
+                                    <tr class="text-gray-800 dark:text-gray-100">
+                                        <td class="py-2 pr-3">
+                                            <div class="font-medium">{{row.label}}</div>
+                                            {{#if row.raw_payload_rows}}
+                                                <div class="text-xs text-gray-500 dark:text-gray-400">
+                                                    {{t "settings.telematics.raw-payload-rows" count=(format-number row.raw_payload_rows) compactable=(format-number row.compactable_rows)}}
+                                                </div>
+                                            {{/if}}
+                                        </td>
+                                        <td class="py-2 pr-3 text-right">{{format-number row.rows}}</td>
+                                        <td class="py-2 pr-3 text-right">{{#if row.estimated_bytes}}{{format-bytes row.estimated_bytes}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
+                                        <td class="py-2 text-xs">{{#if row.oldest}}{{row.oldest}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
+                                    </tr>
+                                {{/each}}
+                            </tbody>
+                        </table>
+                    </div>
+                    <p class="mt-3 text-xs text-gray-500 dark:text-gray-400">{{t "settings.telematics.space-reclaim-note"}}</p>
+                {{else if this.loadUsage.isRunning}}
+                    <div class="flex items-center justify-center py-8">
+                        <Spinner />
+                    </div>
+                {{else}}
+                    <div class="text-center py-8 text-sm text-gray-400 dark:text-gray-500">
+                        {{t "settings.telematics.usage-unavailable"}}
+                    </div>
+                {{/if}}
+            </ContentPanel>
+
+            {{! ── System defaults (administrators) ────────────────────────── }}
+            {{#if this.isAdmin}}
+                <ContentPanel @title={{t "settings.telematics.admin-defaults"}} @open={{false}} @wrapperClass="bordered-classic">
+                    <Admin::TelematicsSettings @embedded={{true}} />
+                </ContentPanel>
+            {{/if}}
+
+        </div>
+    </div>
+    <Spacer @height="600px" />
+</Layout::Section::Body>
diff --git a/app/components/admin/telematics-settings.js b/app/components/admin/telematics-settings.js
new file mode 100644
index 000000000..2ed694547
--- /dev/null
+++ b/app/components/admin/telematics-settings.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/admin/telematics-settings';
diff --git a/app/controllers/settings/telematics.js b/app/controllers/settings/telematics.js
new file mode 100644
index 000000000..2a8328922
--- /dev/null
+++ b/app/controllers/settings/telematics.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/controllers/settings/telematics';
diff --git a/app/routes/settings/telematics.js b/app/routes/settings/telematics.js
new file mode 100644
index 000000000..2c34721cc
--- /dev/null
+++ b/app/routes/settings/telematics.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/routes/settings/telematics';
diff --git a/app/templates/settings/telematics.js b/app/templates/settings/telematics.js
new file mode 100644
index 000000000..1e3bbaee3
--- /dev/null
+++ b/app/templates/settings/telematics.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/templates/settings/telematics';
diff --git a/composer.json b/composer.json
index 3907b8527..15f9fc15e 100644
--- a/composer.json
+++ b/composer.json
@@ -1,6 +1,6 @@
 {
     "name": "fleetbase/fleetops-api",
-    "version": "0.6.69",
+    "version": "0.6.70",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "keywords": [
         "fleetbase-extension",
diff --git a/docs/AFAQY.md b/docs/AFAQY.md
index dc68293b7..5b515efd3 100644
--- a/docs/AFAQY.md
+++ b/docs/AFAQY.md
@@ -57,7 +57,7 @@ Existing provider interfaces and vehicle/trailer event names remain compatible.
 
 The public receiver remains `POST webhooks/telematics/afaqy?telematic=...&key=...` under the application's API prefix. A new `device.telemetry_updated` broadcast identifies the device; an open device panel reloads its authorized resource and refetches after socket reconnection. Company broadcast identity comes from the persisted asset, not a worker session. Map movement uses the existing vehicle/trailer events, rejects older source timestamps, and reloads visible telemetry assets after socket reconnection with at most five concurrent requests.
 
-Configure shared queues, retention, limits, and freshness under `telematics.telemetry` using `server/config/telemetry.php`. `TELEMATICS_BATCH_SIZE` controls units per ingestion delivery (default 100); `TELEMATICS_REQUEST_TIMEOUT_SECONDS` controls the bounded polling request timeout (default 45 seconds). AFAQY's adapter switches and optional queue overrides remain under `telematics.afaqy` in `server/config/afaqy.php`. Defaults: two MiB per webhook, 10,000 pending deliveries per connection, processed payload retention 24 hours, quarantine retention seven days, stale-position thresholds 120 seconds with ignition on and 600 seconds with ignition off/unknown. Each device's metadata records the effective threshold. Connection status categories remain unchanged.
+Configure shared queues, retention, limits, and freshness under `telematics.telemetry` using `server/config/telemetry.php`. `TELEMATICS_BATCH_SIZE` controls units per ingestion delivery (default 100); `TELEMATICS_REQUEST_TIMEOUT_SECONDS` controls the bounded polling request timeout (default 45 seconds). AFAQY's adapter switches and optional queue overrides remain under `telematics.afaqy` in `server/config/afaqy.php`. Defaults: two MiB per webhook, 10,000 pending deliveries per connection, stale-position thresholds 120 seconds with ignition on and 600 seconds with ignition off/unknown. Retention (processed payloads 24 hours, quarantined deliveries seven days, device events 30 days, positions 90 days) is applied by `fleetops:prune-telematics-data` and is configured per company in Fleet-Ops → Settings → Telematics Data, with system defaults in the admin console; the config values are only the fallback. See `docs/TELEMETRY_ARCHITECTURE.md` § Retention. Each device's metadata records the effective threshold. Connection status categories remain unchanged.
 
 ## Incident verification
 
diff --git a/docs/TELEMATICS_QUEUES.md b/docs/TELEMATICS_QUEUES.md
index 0f9829c1f..d1d9239f4 100644
--- a/docs/TELEMATICS_QUEUES.md
+++ b/docs/TELEMATICS_QUEUES.md
@@ -14,7 +14,7 @@ nothing changes: every job and broadcast stays on the same queue as before.
 | Setting | Default | Work routed |
 | --- | --- | --- |
 | `TELEMATICS_POLL_QUEUE` | `default` | Scheduled and manual polls (`PollTelematicTelemetry`), legacy device discovery (`SyncTelematicDevicesJob`), and queued connection tests (`TestTelematicConnectionJob`). |
-| `TELEMATICS_INGESTION_QUEUE` | `default` | Applying polled or pushed positions (`ProcessTelematicDelivery`), including jobs re-queued by `fleetops:drain-telematic-inbox` and manual replays. |
+| `TELEMATICS_INGESTION_QUEUE` | `default` | Applying polled or pushed positions (`ProcessTelematicDelivery`), including jobs re-queued by `fleetops:drain-telematic-inbox` and manual replays, and on-demand retention runs (`PruneTelematicsDataJob`, queued by "Run cleanup now" in Settings → Telematics Data). |
 | `TELEMATICS_BROADCAST_QUEUE` | unset | Live-map broadcasts created by telematics ingestion: `DeviceTelemetryUpdated`, and `VehicleLocationChanged` / `TrailerLocationChanged` when a device is attached. When unset, broadcasts use the queue connection's default queue. |
 
 `TELEMATICS_BROADCAST_QUEUE` affects only broadcasts that telematics ingestion
diff --git a/docs/TELEMETRY_ARCHITECTURE.md b/docs/TELEMETRY_ARCHITECTURE.md
index e10b064cb..fcc570da6 100644
--- a/docs/TELEMETRY_ARCHITECTURE.md
+++ b/docs/TELEMETRY_ARCHITECTURE.md
@@ -48,11 +48,58 @@ persistence. The performance requirement did not justify those dependencies.
 ## Tradeoffs
 
 Three shared tables separate run-level diagnostics, high-volume delivery retention,
-and connection-level secrets with different lifetimes. Provider-specific protocol
+and connection-level secrets with different lifetimes (see Retention below). Provider-specific protocol
 classes remain appropriate. Capability opt-in avoids silently changing every
 existing integration's ingestion or webhook behavior. Production throughput and
 real AFAQY payload verification remain separate deployment gates.
 
+## Retention
+
+Every poll writes one `device_events` row, one `positions` row and a delivery
+envelope per batch for each reporting device. Without a ceiling those tables grow
+until the disk fills, so retention is enforced by `fleetops:prune-telematics-data`
+(scheduled every fifteen minutes, `withoutOverlapping(14)`) using a per-company
+policy resolved by `Support\Telematics\Retention\RetentionPolicy`:
+
+| Layer | Source | Where it is edited |
+|---|---|---|
+| Package config | `server/config/telemetry.php` | deployment |
+| System defaults | setting `fleet-ops.telematics-settings` | Admin console → Fleet-Ops Config → Telematics Data |
+| Company policy | `company.<uuid>.fleet-ops.telematics-settings` | Fleet-Ops → Settings → Telematics Data |
+
+Defaults: device events 30 days, raw payload/meta stripped ("compacted") after
+7 days, positions 90 days, processed deliveries 24 hours, quarantined deliveries
+7 days, sync runs 7 days. `0` keeps rows forever. Values are clamped to
+`RetentionPolicy::LIMITS`.
+
+Rules the sweep follows:
+
+- Hard deletes only. The models soft-delete, so `delete()` would grow the table;
+  rows already soft-deleted are purged regardless of age.
+- Bounded work: at most `--max-batches` (default 50) statements of `--batch-size`
+  (default 1000) rows per table per company per run. A capped run is normal; the
+  next tick continues. Operators can catch up faster off-peak with
+  `php artisan fleetops:prune-telematics-data --max-batches=500 --no-lock`.
+- Compaction keeps the event (type, severity, location, normalized `data`) and
+  nulls `payload` and `meta`, which hold the bulk of each row.
+- `telematic_deliveries` and `telematic_sync_runs` carry no company; they are
+  resolved through the company's connections (including trashed ones). In-flight
+  sync runs (`fetching`, `ingesting`) are recovered by the drain, never expired.
+- Rows whose company or connection no longer exists are swept with the system
+  defaults.
+- Migrations add `(company_uuid, created_at)` on `device_events` and `positions`
+  and `(telematic_uuid, updated_at)` on `telematic_sync_runs`; on multi-GB tables
+  run them in a maintenance window.
+- Deleting rows frees space inside InnoDB files, not on disk. Run
+  `OPTIMIZE TABLE device_events` (requires `innodb_file_per_table`) off-peak to
+  return it to the operating system.
+
+Two write-amplification fixes accompany the sweep: `device_events.meta` stores only
+the normalized block (the raw unit lives once, in `payload`), and telemetry-driven
+saves run inside `activity()->withoutLogs()` unless the company enables
+"Log telemetry activity". `DrainTelematicInbox` now only recovers deliveries and
+finishes interrupted runs.
+
 ## Adding an adapter
 
 Implement `TelemetryProviderInterface` alongside the existing provider contract.
diff --git a/extension.json b/extension.json
index 49ca67ca9..f08a7afde 100644
--- a/extension.json
+++ b/extension.json
@@ -1,6 +1,6 @@
 {
     "name": "Fleet-Ops",
-    "version": "0.6.69",
+    "version": "0.6.70",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "repository": "https://github.com/fleetbase/fleetops",
     "license": "AGPL-3.0-or-later",
diff --git a/package.json b/package.json
index 680462f58..81928af77 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@fleetbase/fleetops-engine",
-    "version": "0.6.69",
+    "version": "0.6.70",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "fleetbase": {
         "route": "fleet-ops"
diff --git a/server/config/telemetry.php b/server/config/telemetry.php
index 2997fec25..2dd3ead6a 100644
--- a/server/config/telemetry.php
+++ b/server/config/telemetry.php
@@ -13,8 +13,17 @@
     'batch_size'                => env('TELEMATICS_BATCH_SIZE', 100),
     'max_payload_bytes'         => 2097152,
     'max_pending_deliveries'    => 10000,
+    // Retention defaults. Companies override these from Fleet-Ops > Settings > Telematics;
+    // administrators override the system defaults from the admin console. 0 keeps rows forever.
     'processed_retention_hours' => 24,
     'quarantine_retention_days' => 7,
+    'sync_run_retention_days'   => 7,
+    'event_retention_days'      => 30,
+    'event_compact_after_days'  => 7,
+    'position_retention_days'   => 90,
+    'log_telemetry_activity'    => false,
+    'prune_batch_size'          => 1000,
+    'prune_max_batches'         => 50,
     'stale_engine_on_seconds'   => 120,
     'stale_engine_off_seconds'  => 600,
 ];
diff --git a/server/migrations/2026_09_23_000001_add_retention_index_to_device_events.php b/server/migrations/2026_09_23_000001_add_retention_index_to_device_events.php
new file mode 100644
index 000000000..c79dc41ed
--- /dev/null
+++ b/server/migrations/2026_09_23_000001_add_retention_index_to_device_events.php
@@ -0,0 +1,40 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Database\TableIndexes;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Supports the bounded retention sweep in fleetops:prune-telematics-data,
+ * which ranges over these columns for every company on every run.
+ */
+return new class extends Migration {
+    private const TABLE   = 'device_events';
+    private const INDEX   = 'device_events_company_created_at_index';
+    private const COLUMNS = ['company_uuid', 'created_at'];
+
+    public function up(): void
+    {
+        if (!Schema::hasTable(self::TABLE) || !Schema::hasColumns(self::TABLE, self::COLUMNS)) {
+            return;
+        }
+
+        if (TableIndexes::covers(self::TABLE, self::COLUMNS)) {
+            return;
+        }
+
+        Schema::table(self::TABLE, fn (Blueprint $table) => $table->index(self::COLUMNS, self::INDEX));
+    }
+
+    public function down(): void
+    {
+        if (!Schema::hasTable(self::TABLE)) {
+            return;
+        }
+
+        if ((TableIndexes::for(self::TABLE)[self::INDEX] ?? null) === self::COLUMNS) {
+            Schema::table(self::TABLE, fn (Blueprint $table) => $table->dropIndex(self::INDEX));
+        }
+    }
+};
diff --git a/server/migrations/2026_09_23_000002_add_retention_index_to_positions.php b/server/migrations/2026_09_23_000002_add_retention_index_to_positions.php
new file mode 100644
index 000000000..6cc4564d7
--- /dev/null
+++ b/server/migrations/2026_09_23_000002_add_retention_index_to_positions.php
@@ -0,0 +1,40 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Database\TableIndexes;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Supports the bounded retention sweep in fleetops:prune-telematics-data,
+ * which ranges over these columns for every company on every run.
+ */
+return new class extends Migration {
+    private const TABLE   = 'positions';
+    private const INDEX   = 'positions_company_created_at_index';
+    private const COLUMNS = ['company_uuid', 'created_at'];
+
+    public function up(): void
+    {
+        if (!Schema::hasTable(self::TABLE) || !Schema::hasColumns(self::TABLE, self::COLUMNS)) {
+            return;
+        }
+
+        if (TableIndexes::covers(self::TABLE, self::COLUMNS)) {
+            return;
+        }
+
+        Schema::table(self::TABLE, fn (Blueprint $table) => $table->index(self::COLUMNS, self::INDEX));
+    }
+
+    public function down(): void
+    {
+        if (!Schema::hasTable(self::TABLE)) {
+            return;
+        }
+
+        if ((TableIndexes::for(self::TABLE)[self::INDEX] ?? null) === self::COLUMNS) {
+            Schema::table(self::TABLE, fn (Blueprint $table) => $table->dropIndex(self::INDEX));
+        }
+    }
+};
diff --git a/server/migrations/2026_09_23_000003_add_retention_index_to_telematic_sync_runs.php b/server/migrations/2026_09_23_000003_add_retention_index_to_telematic_sync_runs.php
new file mode 100644
index 000000000..18ebc7fec
--- /dev/null
+++ b/server/migrations/2026_09_23_000003_add_retention_index_to_telematic_sync_runs.php
@@ -0,0 +1,40 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Database\TableIndexes;
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Supports the bounded retention sweep in fleetops:prune-telematics-data,
+ * which ranges over these columns for every company on every run.
+ */
+return new class extends Migration {
+    private const TABLE   = 'telematic_sync_runs';
+    private const INDEX   = 'telematic_sync_runs_telematic_updated_at_index';
+    private const COLUMNS = ['telematic_uuid', 'updated_at'];
+
+    public function up(): void
+    {
+        if (!Schema::hasTable(self::TABLE) || !Schema::hasColumns(self::TABLE, self::COLUMNS)) {
+            return;
+        }
+
+        if (TableIndexes::covers(self::TABLE, self::COLUMNS)) {
+            return;
+        }
+
+        Schema::table(self::TABLE, fn (Blueprint $table) => $table->index(self::COLUMNS, self::INDEX));
+    }
+
+    public function down(): void
+    {
+        if (!Schema::hasTable(self::TABLE)) {
+            return;
+        }
+
+        if ((TableIndexes::for(self::TABLE)[self::INDEX] ?? null) === self::COLUMNS) {
+            Schema::table(self::TABLE, fn (Blueprint $table) => $table->dropIndex(self::INDEX));
+        }
+    }
+};
diff --git a/server/src/Auth/Schemas/FleetOps.php b/server/src/Auth/Schemas/FleetOps.php
index 74bf863ae..ac2cdda86 100644
--- a/server/src/Auth/Schemas/FleetOps.php
+++ b/server/src/Auth/Schemas/FleetOps.php
@@ -174,6 +174,11 @@ class FleetOps
             'action'         => [],
             'remove_actions' => ['export', 'create'],
         ],
+        [
+            'name'           => 'telematics-settings', // data retention and storage for telematics ingestion
+            'action'         => [],
+            'remove_actions' => ['export', 'create'],
+        ],
     ];
 
     /**
@@ -353,6 +358,14 @@ class FleetOps
                 'list vehicle',
             ],
         ],
+        [
+            'name'        => 'TelematicsSettingsManager',
+            'description' => 'Policy for managing telematics data retention and storage settings.',
+            'permissions' => [
+                'see extension',
+                '* telematics-settings',
+            ],
+        ],
         [
             'name'        => 'DriverOperations',
             'description' => 'Policy for drivers to manage their assigned tasks and access necessary information.',
@@ -453,6 +466,13 @@ class FleetOps
                 'NavigatorSettingsManager',
             ],
         ],
+        [
+            'name'        => 'Telematics Settings Manager',
+            'description' => 'Role responsible for managing telematics data retention and storage settings.',
+            'policies'    => [
+                'TelematicsSettingsManager',
+            ],
+        ],
         [
             'name'        => 'Driver',
             'description' => 'Role for drivers with the necessary access to manage their daily tasks, including order management, and vehicle assignment.',
diff --git a/server/src/Console/Commands/DrainTelematicInbox.php b/server/src/Console/Commands/DrainTelematicInbox.php
index 023a8e6aa..3ff998c36 100644
--- a/server/src/Console/Commands/DrainTelematicInbox.php
+++ b/server/src/Console/Commands/DrainTelematicInbox.php
@@ -16,7 +16,7 @@
 class DrainTelematicInbox extends Command
 {
     protected $signature   = 'fleetops:drain-telematic-inbox';
-    protected $description = 'Recover pending telematic deliveries and expire retained payloads.';
+    protected $description = 'Recover pending telematic deliveries and finish interrupted sync runs.';
 
     public function handle(): int
     {
@@ -58,24 +58,14 @@ public function handle(): int
             try {
                 Queue::dispatch((new ProcessTelematicDelivery($row->uuid))->onQueue($optionsByConnection[$row->telematic_uuid]['ingestion_queue'] ?? 'default'));
             } catch (\Throwable) {
-                // A broker outage must not prevent retention cleanup; retry the next minute.
+                // A broker outage must not prevent run recovery; retry the next minute.
                 break;
             }
         }
-        // Bound deletes so retention cleanup cannot monopolize the inbox table.
-        foreach (['processed' => now()->subHours(config('telematics.telemetry.processed_retention_hours', 24)), 'quarantined' => now()->subDays(config('telematics.telemetry.quarantine_retention_days', 7))] as $status => $cutoff) {
-            for ($batch = 0; $batch < 20; $batch++) {
-                $ids = DB::table('telematic_deliveries')->where('status', $status)->where('updated_at', '<', $cutoff)->limit(1000)->pluck('uuid');
-                if ($ids->isEmpty()) {
-                    break;
-                }
-                DB::table('telematic_deliveries')->whereIn('uuid', $ids)->delete();
-            }
-        }
+        // Retention for deliveries and sync runs is applied by fleetops:prune-telematics-data.
         DB::table('telematic_sync_runs')->where('status', 'fetching')->where('updated_at', '<', now()->subMinutes(5))
             ->update(['status' => 'incomplete', 'error' => 'Worker interrupted; next scheduled sweep will recover.']);
         DB::table('telematic_sync_runs')->where('status', 'ingesting')->get(['uuid'])->each(fn ($run) => Inbox::finishRun($run->uuid));
-        DB::table('telematic_sync_runs')->where('updated_at', '<', now()->subDays(7))->delete();
 
         return self::SUCCESS;
     }
diff --git a/server/src/Console/Commands/PruneTelematicsData.php b/server/src/Console/Commands/PruneTelematicsData.php
new file mode 100644
index 000000000..98a6de4e6
--- /dev/null
+++ b/server/src/Console/Commands/PruneTelematicsData.php
@@ -0,0 +1,304 @@
+<?php
+
+namespace Fleetbase\FleetOps\Console\Commands;
+
+use Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy;
+use Illuminate\Console\Command;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Applies each company's telematics retention policy.
+ *
+ * Deletes are hard deletes issued in bounded batches so a large backlog never
+ * monopolizes the tables ingestion is writing to; a capped run picks up where
+ * it left off on the next schedule tick.
+ */
+class PruneTelematicsData extends Command
+{
+    public const TABLES = ['device_events', 'positions', 'telematic_deliveries', 'telematic_sync_runs'];
+
+    public const LOCK = 'fleetops:prune-telematics-data';
+
+    protected $signature = 'fleetops:prune-telematics-data
+        {--company= : Only prune data for this company (uuid or public id)}
+        {--table=* : Only prune these tables (device_events, positions, telematic_deliveries, telematic_sync_runs)}
+        {--batch-size=1000 : Rows per delete or update statement}
+        {--max-batches=50 : Maximum batches per table per company per run}
+        {--dry-run : Report matching rows without deleting or compacting}
+        {--no-lock : Skip process locking}';
+
+    protected $description = 'Prune telematics device events, positions, deliveries and sync runs according to each company\'s retention policy.';
+
+    protected int $batchSize  = 1000;
+    protected int $maxBatches = 50;
+    protected bool $dryRun    = false;
+
+    public function handle(): int
+    {
+        $tables = $this->requestedTables();
+        if ($tables === null) {
+            $this->error('Unknown table. Valid tables: ' . implode(', ', self::TABLES) . '.');
+
+            return self::FAILURE;
+        }
+
+        $lock = null;
+        if (!$this->option('no-lock')) {
+            $lock = Cache::lock(self::LOCK, 840);
+            if (!$lock->get()) {
+                $this->warn('Another telematics prune run appears to be in progress.');
+
+                return self::SUCCESS;
+            }
+        }
+
+        try {
+            $this->batchSize  = max(100, min(5000, (int) $this->option('batch-size') ?: 1000));
+            $this->maxBatches = max(1, (int) $this->option('max-batches') ?: 50);
+            $this->dryRun     = (bool) $this->option('dry-run');
+
+            $only      = ((string) $this->option('company')) ?: null;
+            $companies = $this->companies($only);
+            if ($only && $companies->isEmpty()) {
+                $this->error(sprintf('Company [%s] was not found.', $only));
+
+                return self::FAILURE;
+            }
+
+            $totals = $this->emptyStats();
+            foreach ($companies as $company) {
+                $stats  = $this->pruneCompany($company->uuid, $this->policyFor($company->uuid), $tables);
+                $totals = $this->mergeStats($totals, $stats);
+                $this->report($company->public_id ?: $company->uuid, $stats);
+            }
+            if (!$only) {
+                $stats  = $this->pruneOrphans($this->policyFor(null), $tables);
+                $totals = $this->mergeStats($totals, $stats);
+                $this->report('orphaned', $stats);
+            }
+
+            $this->info(sprintf(
+                '%s: deleted=%d compacted=%d batches=%d%s',
+                $this->dryRun ? 'Telematics prune dry run' : 'Telematics prune complete',
+                $totals['deleted'],
+                $totals['compacted'],
+                $totals['batches'],
+                $totals['capped'] ? ' (capped; more rows remain for the next run)' : ''
+            ));
+
+            return self::SUCCESS;
+        } finally {
+            $lock?->release();
+        }
+    }
+
+    /**
+     * @return string[]|null null when an unknown table was requested
+     */
+    protected function requestedTables(): ?array
+    {
+        $requested = array_values(array_filter((array) $this->option('table')));
+        if ($requested === []) {
+            return self::TABLES;
+        }
+
+        return array_diff($requested, self::TABLES) === [] ? array_values(array_unique($requested)) : null;
+    }
+
+    protected function companies(?string $only): Collection
+    {
+        $query = DB::table('companies')->select(['id', 'uuid', 'public_id'])->orderBy('id');
+        if ($only) {
+            $query->where(fn ($where) => $where->where('uuid', $only)->orWhere('public_id', $only));
+        }
+
+        return $query->get();
+    }
+
+    protected function policyFor(?string $companyUuid): RetentionPolicy
+    {
+        return RetentionPolicy::forCompany($companyUuid);
+    }
+
+    protected function pruneCompany(string $companyUuid, RetentionPolicy $policy, array $tables): array
+    {
+        $rows = fn ($query) => $query->where('company_uuid', $companyUuid);
+
+        $telematics = null;
+        if (array_intersect(['telematic_deliveries', 'telematic_sync_runs'], $tables) !== []) {
+            // Inbox tables carry no company; trashed connections still prune under their company's policy.
+            $telematics = DB::table('telematics')->where('company_uuid', $companyUuid)->pluck('uuid')->all();
+        }
+        $inbox = $telematics ? fn ($query) => $query->whereIn('telematic_uuid', $telematics) : null;
+
+        return $this->prune($rows, $inbox, $policy, $tables);
+    }
+
+    /**
+     * Rows whose company or connection no longer exists fall back to the system defaults.
+     */
+    protected function pruneOrphans(RetentionPolicy $policy, array $tables): array
+    {
+        $rows = fn ($query) => $query->where(function ($where) {
+            $where->whereNull('company_uuid')->orWhereNotIn('company_uuid', DB::table('companies')->select('uuid'));
+        });
+        $inbox = fn ($query) => $query->whereNotIn('telematic_uuid', DB::table('telematics')->select('uuid'));
+
+        return $this->prune($rows, $inbox, $policy, $tables);
+    }
+
+    protected function prune(\Closure $rows, ?\Closure $inbox, RetentionPolicy $policy, array $tables): array
+    {
+        $stats = $this->emptyStats();
+        if (in_array('device_events', $tables, true)) {
+            $stats['tables']['device_events'] = $this->pruneDeviceEvents($rows, $policy);
+        }
+        if (in_array('positions', $tables, true)) {
+            $stats['tables']['positions'] = $this->prunePositions($rows, $policy);
+        }
+        if ($inbox && in_array('telematic_deliveries', $tables, true)) {
+            $stats['tables']['telematic_deliveries'] = $this->pruneDeliveries($inbox, $policy);
+        }
+        if ($inbox && in_array('telematic_sync_runs', $tables, true)) {
+            $stats['tables']['telematic_sync_runs'] = $this->pruneSyncRuns($inbox, $policy);
+        }
+        foreach ($stats['tables'] as $table) {
+            $stats['deleted'] += $table['deleted'];
+            $stats['compacted'] += $table['compacted'];
+            $stats['batches'] += $table['batches'];
+            $stats['capped']     = $stats['capped'] || $table['capped'];
+        }
+
+        return $stats;
+    }
+
+    protected function pruneDeviceEvents(\Closure $rows, RetentionPolicy $policy): array
+    {
+        $stats  = $this->emptyTableStats();
+        $cutoff = $policy->cutoff('event_retention_days');
+        // Soft-deleted events only grow the table; purge them regardless of age.
+        $this->deleteInBatches('device_events', 'id', fn ($query) => $rows($query)->whereNotNull('deleted_at'), $stats);
+        if ($cutoff) {
+            $this->deleteInBatches('device_events', 'id', fn ($query) => $rows($query)->where('created_at', '<', $cutoff->toDateTimeString()), $stats);
+        }
+        if ($policy->compactsEvents() && ($compactAt = $policy->cutoff('event_compact_after_days'))) {
+            // Keep the event (type, severity, location, normalized data) but drop the raw provider blobs.
+            // Rows past the delete cutoff are left to the delete sweep rather than rewritten first.
+            $this->updateInBatches(
+                'device_events',
+                'id',
+                function ($query) use ($rows, $cutoff, $compactAt) {
+                    $query = $rows($query)->where('created_at', '<', $compactAt->toDateTimeString())->where(fn ($where) => $where->whereNotNull('payload')->orWhereNotNull('meta'));
+
+                    return $cutoff ? $query->where('created_at', '>=', $cutoff->toDateTimeString()) : $query;
+                },
+                ['payload' => null, 'meta' => null],
+                $stats
+            );
+        }
+
+        return $stats;
+    }
+
+    protected function prunePositions(\Closure $rows, RetentionPolicy $policy): array
+    {
+        $stats = $this->emptyTableStats();
+        $this->deleteInBatches('positions', 'id', fn ($query) => $rows($query)->whereNotNull('deleted_at'), $stats);
+        if ($cutoff = $policy->cutoff('position_retention_days')) {
+            $this->deleteInBatches('positions', 'id', fn ($query) => $rows($query)->where('created_at', '<', $cutoff->toDateTimeString()), $stats);
+        }
+
+        return $stats;
+    }
+
+    protected function pruneDeliveries(\Closure $inbox, RetentionPolicy $policy): array
+    {
+        $stats = $this->emptyTableStats();
+        foreach (['processed' => 'processed_retention_hours', 'quarantined' => 'quarantine_retention_days'] as $status => $key) {
+            if ($cutoff = $policy->cutoff($key)) {
+                $this->deleteInBatches('telematic_deliveries', 'uuid', fn ($query) => $inbox($query)->where('status', $status)->where('updated_at', '<', $cutoff->toDateTimeString()), $stats);
+            }
+        }
+
+        return $stats;
+    }
+
+    protected function pruneSyncRuns(\Closure $inbox, RetentionPolicy $policy): array
+    {
+        $stats = $this->emptyTableStats();
+        if ($cutoff = $policy->cutoff('sync_run_retention_days')) {
+            // In-flight runs are recovered by the drain command, never expired here.
+            $this->deleteInBatches('telematic_sync_runs', 'uuid', fn ($query) => $inbox($query)->whereNotIn('status', ['fetching', 'ingesting'])->where('updated_at', '<', $cutoff->toDateTimeString()), $stats);
+        }
+
+        return $stats;
+    }
+
+    protected function deleteInBatches(string $table, string $key, \Closure $scope, array &$stats): void
+    {
+        if ($this->dryRun) {
+            $stats['deleted'] += $scope(DB::table($table))->count();
+
+            return;
+        }
+        for ($batch = 0; $batch < $this->maxBatches; $batch++) {
+            $ids = $scope(DB::table($table))->orderBy($key)->limit($this->batchSize)->pluck($key);
+            if ($ids->isEmpty()) {
+                return;
+            }
+            $stats['batches']++;
+            $stats['deleted'] += DB::table($table)->whereIn($key, $ids->all())->delete();
+        }
+        $stats['capped'] = true;
+    }
+
+    protected function updateInBatches(string $table, string $key, \Closure $scope, array $values, array &$stats): void
+    {
+        if ($this->dryRun) {
+            $stats['compacted'] += $scope(DB::table($table))->count();
+
+            return;
+        }
+        for ($batch = 0; $batch < $this->maxBatches; $batch++) {
+            $ids = $scope(DB::table($table))->orderBy($key)->limit($this->batchSize)->pluck($key);
+            if ($ids->isEmpty()) {
+                return;
+            }
+            $stats['batches']++;
+            $stats['compacted'] += DB::table($table)->whereIn($key, $ids->all())->update($values);
+        }
+        $stats['capped'] = true;
+    }
+
+    protected function report(string $label, array $stats): void
+    {
+        foreach ($stats['tables'] as $table => $counts) {
+            if (!$counts['deleted'] && !$counts['compacted'] && !$counts['capped']) {
+                continue;
+            }
+            $this->info(sprintf('%s %s: deleted=%d compacted=%d batches=%d%s', $label, $table, $counts['deleted'], $counts['compacted'], $counts['batches'], $counts['capped'] ? ' capped' : ''));
+        }
+    }
+
+    protected function emptyTableStats(): array
+    {
+        return ['deleted' => 0, 'compacted' => 0, 'batches' => 0, 'capped' => false];
+    }
+
+    protected function emptyStats(): array
+    {
+        return ['deleted' => 0, 'compacted' => 0, 'batches' => 0, 'capped' => false, 'tables' => []];
+    }
+
+    protected function mergeStats(array $totals, array $stats): array
+    {
+        $totals['deleted'] += $stats['deleted'];
+        $totals['compacted'] += $stats['compacted'];
+        $totals['batches'] += $stats['batches'];
+        $totals['capped']     = $totals['capped'] || $stats['capped'];
+
+        return $totals;
+    }
+}
diff --git a/server/src/Http/Controllers/Internal/v1/SettingController.php b/server/src/Http/Controllers/Internal/v1/SettingController.php
index 3a1c568e5..50d8050c5 100644
--- a/server/src/Http/Controllers/Internal/v1/SettingController.php
+++ b/server/src/Http/Controllers/Internal/v1/SettingController.php
@@ -2,12 +2,15 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\FleetOps\Jobs\PruneTelematicsDataJob;
+use Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy;
 use Fleetbase\FleetOps\Tracking\TrackingProviderRegistry;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Models\Setting;
 use Fleetbase\Support\Auth;
 use Fleetbase\Support\NotificationRegistry;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
 
 /**
  * Class SettingController.
@@ -628,6 +631,202 @@ protected function trackingProviderOptions(): array
         })->values()->all();
     }
 
+    /**
+     * Retrieve telematics data retention settings for the current company.
+     *
+     * Company values fall back to the system defaults (admin setting over
+     * package config); the response carries both so the UI can show them.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function getTelematicsSettings()
+    {
+        $defaults = $this->telematicsDefaults();
+        $settings = RetentionPolicy::normalize((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, []), $defaults);
+
+        return response()->json(array_merge($settings, [
+            'defaults' => $defaults,
+            'limits'   => RetentionPolicy::LIMITS,
+        ]));
+    }
+
+    /**
+     * Save telematics data retention settings for the current company.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function saveTelematicsSettings(Request $request)
+    {
+        $settings = RetentionPolicy::normalize($request->only(RetentionPolicy::keys()), $this->telematicsDefaults());
+        $this->configureCompanySetting(RetentionPolicy::SETTING_KEY, $settings);
+        RetentionPolicy::flush($this->currentCompany()?->uuid);
+
+        return response()->json(array_merge($settings, [
+            'status'  => 'ok',
+            'message' => 'Telematics settings successfully saved.',
+        ]));
+    }
+
+    /**
+     * Retrieve the system-wide telematics retention defaults.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function getAdminTelematicsSettings()
+    {
+        return response()->json(array_merge($this->telematicsDefaults(), [
+            'limits' => RetentionPolicy::LIMITS,
+        ]));
+    }
+
+    /**
+     * Save the system-wide telematics retention defaults.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function saveAdminTelematicsSettings(Request $request)
+    {
+        $config   = array_intersect_key((array) config('telematics.telemetry', []), RetentionPolicy::FALLBACKS);
+        $settings = RetentionPolicy::normalize($request->only(RetentionPolicy::keys()), RetentionPolicy::normalize($config, RetentionPolicy::FALLBACKS));
+        $this->configureSetting(RetentionPolicy::SETTING_KEY, $settings);
+        RetentionPolicy::flush();
+
+        return response()->json($this->getAdminTelematicsSettings()->getData(true));
+    }
+
+    /**
+     * Report how much telematics data the current company holds per table.
+     *
+     * Row counts are exact; sizes are estimates from the table's average row
+     * length because InnoDB does not account space per tenant.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function getTelematicsStorageUsage()
+    {
+        $company = $this->currentCompany();
+        if (!$company) {
+            return response()->error('No company session.', 401);
+        }
+
+        $companyUuid = $company->uuid;
+        $policy      = RetentionPolicy::normalize((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, []), $this->telematicsDefaults());
+        $telematics  = $this->companyTelematicUuids($companyUuid);
+        $byCompany   = fn ($query) => $query->where('company_uuid', $companyUuid);
+        $byInbox     = fn ($query) => $query->whereIn('telematic_uuid', $telematics);
+
+        $tables = [
+            'device_events'        => $this->tableUsage('device_events', $byCompany, 'created_at'),
+            'positions'            => $this->tableUsage('positions', $byCompany, 'created_at'),
+            'telematic_deliveries' => $telematics ? $this->tableUsage('telematic_deliveries', $byInbox, 'received_at') : ['rows' => 0, 'oldest' => null],
+            'telematic_sync_runs'  => $telematics ? $this->tableUsage('telematic_sync_runs', $byInbox, 'created_at') : ['rows' => 0, 'oldest' => null],
+        ];
+
+        // Events still carrying raw provider payloads, and how many of them compaction would strip now.
+        $tables['device_events']['raw_payload_rows'] = $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload'));
+        $compactAfter                                = (int) $policy['event_compact_after_days'];
+        $tables['device_events']['compactable_rows'] = $compactAfter > 0
+            ? $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload')->where('created_at', '<', now()->subDays($compactAfter)->toDateTimeString()))
+            : 0;
+
+        foreach ($this->averageRowLengths(array_keys($tables)) as $table => $length) {
+            $tables[$table]['avg_row_bytes']   = $length;
+            $tables[$table]['estimated_bytes'] = (int) ($tables[$table]['rows'] * $length);
+        }
+
+        return response()->json([
+            'tables'       => $tables,
+            'generated_at' => now()->toISOString(),
+        ]);
+    }
+
+    /**
+     * Queue an immediate retention run for the current company.
+     *
+     * @return \Illuminate\Http\JsonResponse
+     */
+    public function runTelematicsRetention()
+    {
+        $company = $this->currentCompany();
+        if (!$company) {
+            return response()->error('No company session.', 401);
+        }
+
+        $this->dispatchTelematicsPrune($company->uuid);
+
+        return response()->json([
+            'status'  => 'queued',
+            'message' => 'Telematics cleanup has been queued.',
+        ], 202);
+    }
+
+    /**
+     * System-wide retention defaults: package config overridden by the admin setting.
+     */
+    protected function telematicsDefaults(): array
+    {
+        $config = array_intersect_key((array) config('telematics.telemetry', []), RetentionPolicy::FALLBACKS);
+
+        return RetentionPolicy::normalize((array) $this->lookupSetting(RetentionPolicy::SETTING_KEY, []), RetentionPolicy::normalize($config, RetentionPolicy::FALLBACKS));
+    }
+
+    protected function tableUsage(string $table, \Closure $scope, string $ageColumn): array
+    {
+        return [
+            'rows'   => $this->tableCount($table, $scope),
+            'oldest' => $this->tableOldest($table, $scope, $ageColumn),
+        ];
+    }
+
+    protected function companyTelematicUuids(string $companyUuid): array
+    {
+        return DB::table('telematics')->where('company_uuid', $companyUuid)->pluck('uuid')->all();
+    }
+
+    protected function tableCount(string $table, \Closure $scope): int
+    {
+        return (int) $scope(DB::table($table))->count();
+    }
+
+    protected function tableOldest(string $table, \Closure $scope, string $column): ?string
+    {
+        $oldest = $scope(DB::table($table))->min($column);
+
+        return $oldest ? (string) $oldest : null;
+    }
+
+    /**
+     * Average row length per table from InnoDB statistics. Empty on other drivers.
+     *
+     * @return array<string, int>
+     */
+    protected function averageRowLengths(array $tables): array
+    {
+        $connection = DB::connection();
+        if ($connection->getDriverName() !== 'mysql') {
+            return [];
+        }
+
+        $prefix       = $connection->getTablePrefix();
+        $placeholders = implode(', ', array_fill(0, count($tables), '?'));
+        $rows         = $connection->select(
+            'SELECT TABLE_NAME AS name, AVG_ROW_LENGTH AS length FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (' . $placeholders . ')',
+            array_map(fn ($table) => $prefix . $table, $tables)
+        );
+
+        $lengths = [];
+        foreach ($rows as $row) {
+            $lengths[substr($row->name, strlen($prefix))] = (int) $row->length;
+        }
+
+        return $lengths;
+    }
+
+    protected function dispatchTelematicsPrune(string $companyUuid): void
+    {
+        PruneTelematicsDataJob::dispatch($companyUuid);
+    }
+
     protected function configureSetting(string $key, mixed $value): mixed
     {
         return Setting::configure($key, $value);
diff --git a/server/src/Jobs/PruneTelematicsDataJob.php b/server/src/Jobs/PruneTelematicsDataJob.php
new file mode 100644
index 000000000..0df14789d
--- /dev/null
+++ b/server/src/Jobs/PruneTelematicsDataJob.php
@@ -0,0 +1,63 @@
+<?php
+
+namespace Fleetbase\FleetOps\Jobs;
+
+use Fleetbase\FleetOps\Console\Commands\PruneTelematicsData;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Symfony\Component\Console\Input\ArrayInput;
+use Symfony\Component\Console\Output\BufferedOutput;
+
+/**
+ * Runs the telematics prune for one company on demand ("Run cleanup now").
+ *
+ * The command is executed directly rather than through the console kernel so a
+ * worker started before this package version can still run it.
+ */
+class PruneTelematicsDataJob implements ShouldQueue, ShouldBeUnique
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+
+    public int $uniqueFor = 900;
+    public int $tries     = 1;
+    public int $timeout   = 600;
+
+    public function __construct(public ?string $companyUuid = null, public int $maxBatches = 200)
+    {
+    }
+
+    public function uniqueId(): string
+    {
+        return $this->companyUuid ?? 'all';
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function parameters(): array
+    {
+        $parameters = ['--no-lock' => true, '--max-batches' => $this->maxBatches];
+        if ($this->companyUuid) {
+            $parameters['--company'] = $this->companyUuid;
+        }
+
+        return $parameters;
+    }
+
+    public function handle(): void
+    {
+        $command = $this->command();
+        $command->setLaravel(app());
+        $command->run(new ArrayInput($this->parameters()), new BufferedOutput());
+    }
+
+    protected function command(): PruneTelematicsData
+    {
+        return app(PruneTelematicsData::class);
+    }
+}
diff --git a/server/src/Providers/FleetOpsServiceProvider.php b/server/src/Providers/FleetOpsServiceProvider.php
index 93b8394a9..bb91d464a 100644
--- a/server/src/Providers/FleetOpsServiceProvider.php
+++ b/server/src/Providers/FleetOpsServiceProvider.php
@@ -77,6 +77,7 @@ class FleetOpsServiceProvider extends CoreServiceProvider
         \Fleetbase\FleetOps\Console\Commands\ProcessOperationalAlerts::class,
         \Fleetbase\FleetOps\Console\Commands\SyncTelematics::class,
         \Fleetbase\FleetOps\Console\Commands\DrainTelematicInbox::class,
+        \Fleetbase\FleetOps\Console\Commands\PruneTelematicsData::class,
     ];
 
     /**
@@ -153,6 +154,8 @@ public function boot()
             // leave the default 24-hour overlap lease blocking telemetry recovery.
             $schedule->command('fleetops:sync-telematics')->everyMinute()->withoutOverlapping(2)->storeOutputInDb();
             $schedule->command('fleetops:drain-telematic-inbox')->everyMinute()->withoutOverlapping(2);
+            // Bounded batches per company and table; a capped run simply continues on the next tick.
+            $schedule->command('fleetops:prune-telematics-data')->everyFifteenMinutes()->withoutOverlapping(14)->storeOutputInDb();
         });
         $this->registerNotifications();
         $this->registerAiCapabilities();
diff --git a/server/src/Support/Database/TableIndexes.php b/server/src/Support/Database/TableIndexes.php
new file mode 100644
index 000000000..fc5e5daf0
--- /dev/null
+++ b/server/src/Support/Database/TableIndexes.php
@@ -0,0 +1,66 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Database;
+
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Inspect table indexes without Schema::getIndexes, which is absent in the
+ * Laravel versions this package supports. Fleet-Ops deploys on MySQL and runs
+ * its migration tests on SQLite.
+ */
+final class TableIndexes
+{
+    /**
+     * @return array<string, string[]> index name => ordered column names
+     */
+    public static function for(string $table): array
+    {
+        $connection = Schema::getConnection();
+        $prefixed   = $connection->getTablePrefix() . $table;
+        $indexes    = [];
+
+        if ($connection instanceof \Illuminate\Database\SQLiteConnection || $connection->getDriverName() === 'sqlite') {
+            $quoted = str_replace('"', '""', $prefixed);
+            foreach ($connection->select('PRAGMA index_list("' . $quoted . '")') as $index) {
+                $name    = str_replace('"', '""', $index->name);
+                $columns = $connection->select('PRAGMA index_info("' . $name . '")');
+                usort($columns, fn ($a, $b) => $a->seqno <=> $b->seqno);
+                $indexes[$index->name] = array_column($columns, 'name');
+            }
+
+            return $indexes;
+        }
+
+        // @codeCoverageIgnoreStart
+        if ($connection->getDriverName() !== 'mysql') {
+            throw new \RuntimeException('Index inspection requires MySQL or SQLite.');
+        }
+
+        $quoted = str_replace('`', '``', $prefixed);
+        foreach ($connection->select('SHOW INDEX FROM `' . $quoted . '`') as $index) {
+            $indexes[$index->Key_name][(int) $index->Seq_in_index - 1] = $index->Column_name;
+        }
+        foreach ($indexes as &$columns) {
+            ksort($columns);
+            $columns = array_values($columns);
+        }
+
+        return $indexes;
+        // @codeCoverageIgnoreEnd
+    }
+
+    /**
+     * Whether any index already leads with exactly these columns, in order.
+     */
+    public static function covers(string $table, array $columns): bool
+    {
+        foreach (self::for($table) as $indexed) {
+            if (array_slice($indexed, 0, count($columns)) === $columns) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}
diff --git a/server/src/Support/Telematics/Retention/RetentionPolicy.php b/server/src/Support/Telematics/Retention/RetentionPolicy.php
new file mode 100644
index 000000000..a693112e4
--- /dev/null
+++ b/server/src/Support/Telematics/Retention/RetentionPolicy.php
@@ -0,0 +1,232 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Retention;
+
+use Fleetbase\Models\Setting;
+use Illuminate\Support\Carbon;
+
+/**
+ * Resolves how long a company keeps telematics data.
+ *
+ * Values resolve in three layers: the package config (`telematics.telemetry`),
+ * the system-wide admin setting, then the company setting. Every numeric value
+ * is clamped to its limits; zero always means "keep forever".
+ */
+final class RetentionPolicy
+{
+    public const SETTING_KEY = 'fleet-ops.telematics-settings';
+
+    /** Cached policies are refreshed after this many seconds so saved settings reach long-lived workers. */
+    public const CACHE_TTL_SECONDS = 60;
+
+    /** @var array<string, array{0: int, 1: int}> */
+    public const LIMITS = [
+        'event_retention_days'      => [1, 3650],
+        'event_compact_after_days'  => [1, 3650],
+        'position_retention_days'   => [1, 3650],
+        'processed_retention_hours' => [1, 720],
+        'quarantine_retention_days' => [1, 365],
+        'sync_run_retention_days'   => [1, 365],
+    ];
+
+    public const BOOLEANS = ['log_telemetry_activity'];
+
+    /** Used when neither config nor settings provide a value. */
+    public const FALLBACKS = [
+        'event_retention_days'      => 30,
+        'event_compact_after_days'  => 7,
+        'position_retention_days'   => 90,
+        'processed_retention_hours' => 24,
+        'quarantine_retention_days' => 7,
+        'sync_run_retention_days'   => 7,
+        'log_telemetry_activity'    => false,
+    ];
+
+    /**
+     * Test seam: fn (string $scope, string $key, mixed $default, ?string $companyUuid): mixed
+     * where $scope is `system` or `company`.
+     */
+    public static ?\Closure $settingsResolver = null;
+
+    /** @var array<string, array{policy: self, expires: int}> */
+    private static array $companyCache = [];
+
+    /** @var array{values: array, expires: int}|null */
+    private static ?array $defaultsCache = null;
+
+    private function __construct(private array $values)
+    {
+    }
+
+    /** @return string[] */
+    public static function keys(): array
+    {
+        return array_keys(self::FALLBACKS);
+    }
+
+    /**
+     * System-wide defaults: package config overridden by the admin setting.
+     */
+    public static function defaults(): array
+    {
+        if (self::$defaultsCache && self::$defaultsCache['expires'] > time()) {
+            return self::$defaultsCache['values'];
+        }
+
+        $config = array_intersect_key((array) config('telematics.telemetry', []), self::FALLBACKS);
+        $base   = self::normalize($config, self::FALLBACKS);
+        $values = self::normalize(self::resolve('system', null), $base);
+
+        self::$defaultsCache = ['values' => $values, 'expires' => time() + self::CACHE_TTL_SECONDS];
+
+        return $values;
+    }
+
+    public static function forCompany(?string $companyUuid): self
+    {
+        if (!$companyUuid) {
+            return new self(self::defaults());
+        }
+
+        $cached = self::$companyCache[$companyUuid] ?? null;
+        if ($cached && $cached['expires'] > time()) {
+            return $cached['policy'];
+        }
+
+        $defaults = self::defaults();
+        $policy   = new self(self::normalize(self::resolve('company', $companyUuid), $defaults));
+
+        self::$companyCache[$companyUuid] = ['policy' => $policy, 'expires' => time() + self::CACHE_TTL_SECONDS];
+
+        return $policy;
+    }
+
+    public static function fromArray(array $values, ?array $base = null): self
+    {
+        return new self(self::normalize($values, $base ?? self::FALLBACKS));
+    }
+
+    /**
+     * Clamp and cast user input, filling gaps from `$base`.
+     */
+    public static function normalize(array $input, array $base): array
+    {
+        $values = [];
+        foreach (self::LIMITS as $key => [$min, $max]) {
+            $value        = (int) self::pick($input, $base, $key);
+            $values[$key] = $value === 0 ? 0 : max($min, min($max, $value));
+        }
+        foreach (self::BOOLEANS as $key) {
+            $values[$key] = filter_var(self::pick($input, $base, $key), FILTER_VALIDATE_BOOLEAN);
+        }
+
+        return $values;
+    }
+
+    public static function flush(?string $companyUuid = null): void
+    {
+        if ($companyUuid === null) {
+            self::$companyCache  = [];
+            self::$defaultsCache = null;
+
+            return;
+        }
+
+        unset(self::$companyCache[$companyUuid]);
+    }
+
+    /**
+     * The point in time before which rows governed by `$key` are expired, or null when retention is off.
+     */
+    public function cutoff(string $key): ?Carbon
+    {
+        $value = (int) ($this->values[$key] ?? 0);
+        if ($value <= 0) {
+            return null;
+        }
+
+        return $key === 'processed_retention_hours' ? Carbon::now()->subHours($value) : Carbon::now()->subDays($value);
+    }
+
+    public function deletesEvents(): bool
+    {
+        return $this->values['event_retention_days'] > 0;
+    }
+
+    /**
+     * Compaction strips raw payloads from events that are kept but no longer need the provider blob.
+     * It is pointless when events are deleted before, or at the same age as, they would be compacted.
+     */
+    public function compactsEvents(): bool
+    {
+        $compactAfter = $this->values['event_compact_after_days'];
+        if ($compactAfter <= 0) {
+            return false;
+        }
+
+        return !$this->deletesEvents() || $compactAfter < $this->values['event_retention_days'];
+    }
+
+    public function logsTelemetryActivity(): bool
+    {
+        return (bool) $this->values['log_telemetry_activity'];
+    }
+
+    public function get(string $key): mixed
+    {
+        return $this->values[$key] ?? null;
+    }
+
+    public function toArray(): array
+    {
+        return $this->values;
+    }
+
+    private static function pick(array $input, array $base, string $key): mixed
+    {
+        if (array_key_exists($key, $input) && $input[$key] !== null && $input[$key] !== '') {
+            return $input[$key];
+        }
+
+        return $base[$key] ?? self::FALLBACKS[$key];
+    }
+
+    /**
+     * Read the stored setting for a scope. Any failure (no settings table, no session store)
+     * falls back to the layer below so ingestion never depends on the settings store.
+     */
+    private static function resolve(string $scope, ?string $companyUuid): array
+    {
+        try {
+            if (self::$settingsResolver) {
+                $value = (self::$settingsResolver)($scope, self::SETTING_KEY, [], $companyUuid);
+            } elseif ($scope === 'system') {
+                $value = Setting::lookup(self::SETTING_KEY, []);
+            } else {
+                $value = self::lookupCompanySetting($companyUuid);
+            }
+        } catch (\Throwable) {
+            $value = [];
+        }
+
+        return is_array($value) ? $value : [];
+    }
+
+    /**
+     * `Setting::lookupCompany` reads the company from the session, which queue workers and
+     * console commands do not have; scope it for the lookup and restore whatever was there.
+     */
+    private static function lookupCompanySetting(string $companyUuid): mixed
+    {
+        $session  = app('session');
+        $had      = $session->has('company');
+        $previous = $session->get('company');
+        $session->put('company', $companyUuid);
+
+        try {
+            return Setting::lookupCompany(self::SETTING_KEY, []);
+        } finally {
+            $had ? $session->put('company', $previous) : $session->forget('company');
+        }
+    }
+}
diff --git a/server/src/Support/Telematics/Retention/TelemetryActivity.php b/server/src/Support/Telematics/Retention/TelemetryActivity.php
new file mode 100644
index 000000000..adbaccab1
--- /dev/null
+++ b/server/src/Support/Telematics/Retention/TelemetryActivity.php
@@ -0,0 +1,40 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Retention;
+
+use Spatie\Activitylog\ActivityLogger;
+
+/**
+ * Runs telemetry-driven writes with activity logging suppressed unless the
+ * company opted in. Every poll saves the device, event, position and vehicle,
+ * which otherwise writes several activity rows per device per minute.
+ */
+final class TelemetryActivity
+{
+    public static function run(?string $companyUuid, \Closure $callback): mixed
+    {
+        if (RetentionPolicy::forCompany($companyUuid)->logsTelemetryActivity()) {
+            return $callback();
+        }
+
+        $logger = self::logger();
+        if (!$logger) {
+            return $callback();
+        }
+
+        return $logger->withoutLogs($callback);
+    }
+
+    /**
+     * The logger is optional: an environment without the activity log package
+     * bound (package tests, minimal consoles) must still ingest telemetry.
+     */
+    private static function logger(): ?ActivityLogger
+    {
+        try {
+            return app(ActivityLogger::class);
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+}
diff --git a/server/src/Support/Telematics/TelematicService.php b/server/src/Support/Telematics/TelematicService.php
index 42015bf79..b1541f88d 100644
--- a/server/src/Support/Telematics/TelematicService.php
+++ b/server/src/Support/Telematics/TelematicService.php
@@ -239,6 +239,12 @@ public function ingestDeviceSnapshot(Telematic $telematic, TelematicProviderInte
         if ($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface) {
             return app(Telemetry\Ingestor::class)->ingest($telematic, $provider, $payload, $this);
         }
+
+        return Retention\TelemetryActivity::run($telematic->company_uuid, fn () => $this->ingestLegacySnapshot($telematic, $provider, $payload));
+    }
+
+    protected function ingestLegacySnapshot(Telematic $telematic, TelematicProviderInterface $provider, array $payload): array
+    {
         $device = $this->linkDevice($telematic, $provider->normalizeDevice($payload));
 
         $event  = null;
@@ -299,7 +305,9 @@ public function storeDeviceEvent(Telematic $telematic, array $eventData, ?Device
         ], fn ($value) => $value !== null);
         $event->payload      = $eventData['payload'] ?? $eventData['meta'] ?? $eventData;
         $event->_key         = $eventKey;
-        $event->meta         = array_merge($eventData['meta'] ?? [], [
+        // Providers hand over the raw unit in `meta`; it already lives in `payload`.
+        // Persist only the normalized block so each event is stored once, not twice.
+        $event->meta = array_filter([
             'telematic_uuid'    => $telematic->uuid,
             'telematic_id'      => $telematic->public_id,
             'provider_event_id' => $event->ident,
@@ -310,7 +318,9 @@ public function storeDeviceEvent(Telematic $telematic, array $eventData, ?Device
             'odometer'          => $eventData['odometer'] ?? null,
             'ignition'          => $eventData['ignition'] ?? null,
             'fuel_level'        => $eventData['fuel_level'] ?? null,
-        ]);
+            'telemetry'         => data_get($eventData, 'meta.telemetry'),
+            'provider_status'   => data_get($eventData, 'meta.provider_status'),
+        ], fn ($value) => $value !== null);
 
         $location = $this->normalizeLocation($eventData['location'] ?? null);
         if ($location) {
diff --git a/server/src/Support/Telematics/Telemetry/Ingestor.php b/server/src/Support/Telematics/Telemetry/Ingestor.php
index e09a6c6cd..9b790900d 100644
--- a/server/src/Support/Telematics/Telemetry/Ingestor.php
+++ b/server/src/Support/Telematics/Telemetry/Ingestor.php
@@ -7,6 +7,7 @@
 use Fleetbase\FleetOps\Models\Device;
 use Fleetbase\FleetOps\Models\DeviceEvent;
 use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Telematics\Retention\TelemetryActivity;
 use Fleetbase\FleetOps\Support\Telematics\TelematicService;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Cache;
@@ -32,7 +33,8 @@ public function ingest(Telematic $telematic, TelemetryProviderInterface $provide
         }
         $key = 'telemetry:device:' . hash('sha256', $telematic->uuid . '|' . $id);
 
-        return Cache::lock($key, 60)->block(5, fn () => DB::transaction(function () use ($telematic, $sample, $options, $service, $receivedAt, $source, $normalized, $event, $id) {
+        // Telemetry saves (device, event, position, vehicle, sensors) only reach the activity log when the company opts in.
+        return Cache::lock($key, 60)->block(5, fn () => TelemetryActivity::run($telematic->company_uuid, fn () => DB::transaction(function () use ($telematic, $sample, $options, $service, $receivedAt, $source, $normalized, $event, $id) {
             $device            = Device::withoutGlobalScopes()->where('company_uuid', $telematic->company_uuid)->where('telematic_uuid', $telematic->uuid)->where('device_id', $id)->lockForUpdate()->first();
             $current           = data_get($device?->meta, 'telemetry.position_at') ?? data_get($device?->meta, 'last_update.occurred_at');
             $valid             = Sample::validPosition($event);
@@ -107,6 +109,6 @@ public function ingest(Telematic $telematic, TelemetryProviderInterface $provide
             }
 
             return ['device' => $device, 'event' => $stored, 'events' => $stored ? [$stored] : [], 'sensors' => $sensors, 'duplicate' => $duplicate, 'invalid_position' => !$valid];
-        }, 3));
+        }, 3)));
     }
 }
diff --git a/server/src/routes.php b/server/src/routes.php
index 631bccc92..9789b37f8 100644
--- a/server/src/routes.php
+++ b/server/src/routes.php
@@ -814,6 +814,12 @@ function ($router) {
                                         $router->post('orchestrator-settings', 'SettingController@saveOrchestratorSettings');
                                         $router->get('orchestrator-card-fields', 'SettingController@getOrchestratorCardFields');
                                         $router->post('orchestrator-card-fields', 'SettingController@saveOrchestratorCardFields');
+                                        $router->get('telematics-settings', 'SettingController@getTelematicsSettings');
+                                        $router->post('telematics-settings', 'SettingController@saveTelematicsSettings');
+                                        $router->get('admin-telematics-settings', 'SettingController@getAdminTelematicsSettings');
+                                        $router->post('admin-telematics-settings', 'SettingController@saveAdminTelematicsSettings');
+                                        $router->get('telematics-storage-usage', 'SettingController@getTelematicsStorageUsage');
+                                        $router->post('telematics-retention/run', 'SettingController@runTelematicsRetention');
                                     }
                                 );
                                 $router->group(
diff --git a/server/tests/Feature/Http/AfaqyRealtimeIngestionTest.php b/server/tests/Feature/Http/AfaqyRealtimeIngestionTest.php
index 5a56b5a40..6d7a5ad9e 100644
--- a/server/tests/Feature/Http/AfaqyRealtimeIngestionTest.php
+++ b/server/tests/Feature/Http/AfaqyRealtimeIngestionTest.php
@@ -3,6 +3,7 @@
 require_once __DIR__ . '/../../Support/AfaqyTestCrypto.php';
 require_once __DIR__ . '/../../Support/ExampleTelemetryProvider.php';
 require_once __DIR__ . '/../../Support/TelemetryTestEnvironment.php';
+require_once __DIR__ . '/../../Support/PruneTelematicsDataProbe.php';
 
 use Fleetbase\FleetOps\Http\Controllers\TelematicPositionWebhookController;
 use Fleetbase\FleetOps\Jobs\ProcessTelematicDelivery;
@@ -123,6 +124,12 @@ function afaqyDbUnit(string $time = '2026-09-15 11:59:00', float $lat = 24.0): a
     expect(DeviceEvent::withoutGlobalScopes()->count())->toBe(2);
     expect(count($GLOBALS['afaqy_broadcasts']))->toBe(1);
     expect($device->last_position->getLat())->toBe(24.0);
+    // The raw unit is stored once, in payload; meta carries only the normalized block.
+    $stored = DeviceEvent::withoutGlobalScopes()->orderBy('id')->first();
+    expect(data_get($stored->payload, '_id'))->toBe('unit-1')
+        ->and($stored->meta)->not->toHaveKeys(['_id', 'last_update'])
+        ->and(data_get($stored->meta, 'telemetry.position_at'))->toBe('2026-09-15T11:59:00.000000Z')
+        ->and(data_get($stored->meta, 'telematic_uuid'))->toBe('integration-1');
 });
 
 test('webhook authenticates before durable acceptance and worker quarantines unknown shapes', function () {
@@ -282,7 +289,7 @@ public function storeDeviceEvent(Telematic $telematic, array $eventData, ?Device
     expect($elapsed)->toBeLessThan(60.0);
 })->skip(getenv('AFAQY_RUN_LOAD_TESTS') !== '1', 'Opt-in local processing benchmark; production latency requires deployment testing.');
 
-test('inbox maintenance retains replayable payloads and cleans expired rows during a broker outage', function () {
+test('inbox recovery leaves retention to the prune command, which expires processed deliveries by policy', function () {
     $telematic   = afaqyDbFixture();
     $inbox       = new Inbox();
     $pending     = $inbox->accept($telematic, afaqyDbUnit(), 'poll');
@@ -297,9 +304,17 @@ public function storeDeviceEvent(Telematic $telematic, array $eventData, ?Device
         'metadata' => ['telemetry' => ['durable_ingestion' => true]],
     ]));
     expect((new Fleetbase\FleetOps\Console\Commands\DrainTelematicInbox())->handle())->toBe(0);
+    // The drain only recovers; nothing is expired until the retention sweep runs.
+    expect(DB::table('telematic_deliveries')->count())->toBe(3);
+
+    $prune                     = new PruneTelematicsDataProbe();
+    $prune->options['company'] = 'company-1';
+    $prune->companyRows        = collect([(object) ['id' => 1, 'uuid' => 'company-1', 'public_id' => 'company_1']]);
+    expect($prune->handle())->toBe(0);
     expect(DB::table('telematic_deliveries')->where('uuid', $processed)->exists())->toBeFalse();
     expect(DB::table('telematic_deliveries')->where('uuid', $quarantined)->exists())->toBeTrue();
     expect(DB::table('telematic_deliveries')->where('uuid', $pending)->value('status'))->toBe('pending');
+    expect($prune->messages)->toContain(['info', 'company_1 telematic_deliveries: deleted=1 compacted=0 batches=1']);
 });
 
 test('sensor values use source time and preserve units through partial and older snapshots', function () {
diff --git a/server/tests/Feature/Http/Api/TelematicsRetentionIndexMigrationTest.php b/server/tests/Feature/Http/Api/TelematicsRetentionIndexMigrationTest.php
new file mode 100644
index 000000000..e6027f553
--- /dev/null
+++ b/server/tests/Feature/Http/Api/TelematicsRetentionIndexMigrationTest.php
@@ -0,0 +1,115 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Database\TableIndexes;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * The retention sweep ranges over (company_uuid, created_at) and
+ * (telematic_uuid, updated_at); these migrations add those indexes once,
+ * skip equivalent existing ones, and roll back only what they created.
+ */
+function fleetopsRetentionIndexDatabase(): SQLiteConnection
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'), ':memory:', '', ['driver' => 'sqlite']);
+    Schema::swap($connection->getSchemaBuilder());
+
+    return $connection;
+}
+
+function fleetopsRetentionIndexMigrations(): array
+{
+    $migrations = [];
+    foreach (glob(dirname(__DIR__, 4) . '/migrations/2026_09_23_00000*_add_retention_index_to_*.php') as $path) {
+        $migrations[basename($path)] = fn () => require $path;
+    }
+
+    return $migrations;
+}
+
+test('retention index migrations add composite indexes once and roll them back', function () {
+    fleetopsRetentionIndexDatabase();
+    Schema::create('device_events', function ($table) {
+        $table->increments('id');
+        $table->uuid('company_uuid')->nullable();
+        $table->timestamps();
+    });
+    Schema::create('positions', function ($table) {
+        $table->increments('id');
+        $table->uuid('company_uuid')->nullable();
+        $table->timestamps();
+    });
+    Schema::create('telematic_sync_runs', function ($table) {
+        $table->uuid('uuid')->primary();
+        $table->uuid('telematic_uuid')->index();
+        $table->timestamps();
+    });
+
+    $expected = [
+        'device_events'       => ['device_events_company_created_at_index', ['company_uuid', 'created_at']],
+        'positions'           => ['positions_company_created_at_index', ['company_uuid', 'created_at']],
+        'telematic_sync_runs' => ['telematic_sync_runs_telematic_updated_at_index', ['telematic_uuid', 'updated_at']],
+    ];
+    $migrations = fleetopsRetentionIndexMigrations();
+    expect($migrations)->toHaveCount(3);
+    foreach ($migrations as $load) {
+        $load()->up();
+        $load()->up();
+    }
+    foreach ($expected as $table => [$name, $columns]) {
+        expect(TableIndexes::for($table)[$name] ?? null)->toBe($columns)
+            ->and(TableIndexes::covers($table, $columns))->toBeTrue()
+            ->and(TableIndexes::covers($table, ['created_at']))->toBeFalse();
+    }
+    // The existing single-column index on telematic_uuid does not cover the composite.
+    expect(count(array_filter(TableIndexes::for('telematic_sync_runs'), fn ($columns) => $columns === ['telematic_uuid'])))->toBe(1);
+
+    foreach ($migrations as $load) {
+        $load()->down();
+    }
+    foreach ($expected as $table => [$name]) {
+        expect(TableIndexes::for($table))->not->toHaveKey($name);
+    }
+});
+
+test('retention index migrations skip missing tables, missing columns and equivalent indexes', function () {
+    fleetopsRetentionIndexDatabase();
+    $migrations = fleetopsRetentionIndexMigrations();
+
+    // No tables at all: nothing to do either way.
+    foreach ($migrations as $load) {
+        $load()->up();
+        $load()->down();
+    }
+
+    Schema::create('device_events', fn ($table) => $table->increments('id'));
+    Schema::create('positions', function ($table) {
+        $table->increments('id');
+        $table->uuid('company_uuid')->nullable();
+        $table->timestamps();
+        $table->index(['company_uuid', 'created_at', 'id'], 'positions_existing_company_created');
+    });
+    Schema::create('telematic_sync_runs', function ($table) {
+        $table->uuid('uuid')->primary();
+        $table->uuid('telematic_uuid');
+        $table->timestamps();
+        $table->index(['telematic_uuid', 'updated_at'], 'telematic_sync_runs_telematic_updated_at_index');
+    });
+    Schema::table('telematic_sync_runs', fn ($table) => $table->index('updated_at', 'unrelated_updated_at'));
+
+    foreach ($migrations as $load) {
+        $load()->up();
+    }
+    expect(TableIndexes::for('device_events'))->toBe([])
+        ->and(array_keys(TableIndexes::for('positions')))->toBe(['positions_existing_company_created'])
+        ->and(TableIndexes::for('telematic_sync_runs'))->toHaveKeys(['telematic_sync_runs_telematic_updated_at_index', 'unrelated_updated_at']);
+
+    // Rolling back never drops an index the migration did not create, even under the reserved name when its shape differs.
+    Schema::table('telematic_sync_runs', fn ($table) => $table->dropIndex('telematic_sync_runs_telematic_updated_at_index'));
+    Schema::table('telematic_sync_runs', fn ($table) => $table->index('updated_at', 'telematic_sync_runs_telematic_updated_at_index'));
+    foreach ($migrations as $load) {
+        $load()->down();
+    }
+    expect(array_keys(TableIndexes::for('positions')))->toBe(['positions_existing_company_created'])
+        ->and(TableIndexes::for('telematic_sync_runs')['telematic_sync_runs_telematic_updated_at_index'])->toBe(['updated_at']);
+});
diff --git a/server/tests/ProviderContractsTest.php b/server/tests/ProviderContractsTest.php
index 50857aa01..e181e93f5 100644
--- a/server/tests/ProviderContractsTest.php
+++ b/server/tests/ProviderContractsTest.php
@@ -115,6 +115,13 @@ public function everyTenMinutes(): self
         return $this;
     }
 
+    public function everyFifteenMinutes(): self
+    {
+        $this->methods[] = ['everyFifteenMinutes'];
+
+        return $this;
+    }
+
     public function daily(): self
     {
         $this->methods[] = ['daily'];
@@ -277,11 +284,14 @@ protected function mergeConfigFrom($path, $key)
                 'fleetops:process-operational-alerts',
                 'fleetops:sync-telematics',
                 'fleetops:drain-telematic-inbox',
+                'fleetops:prune-telematics-data',
             ])
             ->and($provider->schedule?->commands['fleetops:dispatch-orders']->methods)->toContain(['everyMinute'], ['withoutOverlapping'], ['storeOutputInDb'])
             ->and($provider->schedule?->commands['fleetops:update-estimations']->methods)->toContain(['everyTenMinutes'], ['withoutOverlapping'])
             ->and($provider->schedule?->commands['fleetops:sync-telematics']->expiresAt)->toBe(2)
             ->and($provider->schedule?->commands['fleetops:drain-telematic-inbox']->expiresAt)->toBe(2)
+            ->and($provider->schedule?->commands['fleetops:prune-telematics-data']->methods)->toContain(['everyFifteenMinutes'], ['withoutOverlapping'], ['storeOutputInDb'])
+            ->and($provider->schedule?->commands['fleetops:prune-telematics-data']->expiresAt)->toBe(14)
             ->and($orchestrationRegistry->has('vroom'))->toBeTrue()
             ->and($orchestrationRegistry->has('greedy'))->toBeTrue()
             ->and($orchestrationRegistry->has('capacity'))->toBeTrue()
diff --git a/server/tests/SettingControllerContractsTest.php b/server/tests/SettingControllerContractsTest.php
index 1163a5f36..f1d7e7770 100644
--- a/server/tests/SettingControllerContractsTest.php
+++ b/server/tests/SettingControllerContractsTest.php
@@ -78,6 +78,40 @@ protected function googleMapsApiKey(): string
     {
         return $this->googleMapsApiKey;
     }
+
+    public array $telematicUuids = [];
+    public array $counts         = [];
+    public array $oldest         = [];
+    public array $rowLengths     = [];
+    public array $countScopes    = [];
+    public array $pruned         = [];
+
+    protected function companyTelematicUuids(string $companyUuid): array
+    {
+        return $this->telematicUuids[$companyUuid] ?? [];
+    }
+
+    protected function tableCount(string $table, Closure $scope): int
+    {
+        $this->countScopes[] = $table;
+
+        return $this->counts[$table] ?? 0;
+    }
+
+    protected function tableOldest(string $table, Closure $scope, string $column): ?string
+    {
+        return $this->oldest[$table] ?? null;
+    }
+
+    protected function averageRowLengths(array $tables): array
+    {
+        return $this->rowLengths;
+    }
+
+    protected function dispatchTelematicsPrune(string $companyUuid): void
+    {
+        $this->pruned[] = $companyUuid;
+    }
 }
 
 class FleetOpsTrackingProviderOptionFake
@@ -441,3 +475,209 @@ function fleetopsJsonPayload(mixed $response): array
     expect($defaults['leafletTileUrl'])->toBe('')
         ->and($defaults['leafletDarkTileUrl'])->toBe('');
 });
+
+test('telematics settings layer package config, admin defaults and company overrides with clamping', function () {
+    config(['telematics.telemetry' => ['event_retention_days' => 45, 'processed_retention_hours' => 48, 'log_telemetry_activity' => false, 'poll_queue' => 'default']]);
+    $controller                                                    = new FleetOpsSettingControllerProbe();
+    $controller->settings['fleet-ops.telematics-settings']         = ['position_retention_days' => 120, 'event_retention_days' => 99999];
+    $controller->companySettings['fleet-ops.telematics-settings']  = ['event_compact_after_days' => 3, 'log_telemetry_activity' => '1'];
+
+    $settings = fleetopsJsonPayload($controller->getTelematicsSettings());
+    expect($settings['event_retention_days'])->toBe(3650)
+        ->and($settings['position_retention_days'])->toBe(120)
+        ->and($settings['event_compact_after_days'])->toBe(3)
+        ->and($settings['processed_retention_hours'])->toBe(48)
+        ->and($settings['log_telemetry_activity'])->toBeTrue()
+        ->and($settings['defaults']['event_compact_after_days'])->toBe(7)
+        ->and($settings['defaults']['log_telemetry_activity'])->toBeFalse()
+        ->and($settings['limits'])->toBe(Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy::LIMITS);
+
+    $saved = fleetopsJsonPayload($controller->saveTelematicsSettings(new Request([
+        'event_retention_days'      => '0',
+        'event_compact_after_days'  => -3,
+        'processed_retention_hours' => 5000,
+        'log_telemetry_activity'    => 'false',
+        'unexpected'                => 'ignored',
+    ])));
+    expect($saved['status'])->toBe('ok')
+        ->and($saved['event_retention_days'])->toBe(0)
+        ->and($saved['event_compact_after_days'])->toBe(1)
+        ->and($saved['processed_retention_hours'])->toBe(720)
+        ->and($saved['position_retention_days'])->toBe(120)
+        ->and($saved['log_telemetry_activity'])->toBeFalse()
+        ->and($controller->configuredCompany['fleet-ops.telematics-settings'])->not->toHaveKey('unexpected')
+        ->and($controller->configuredCompany['fleet-ops.telematics-settings']['quarantine_retention_days'])->toBe(7);
+
+    $admin = fleetopsJsonPayload($controller->getAdminTelematicsSettings());
+    expect($admin['event_retention_days'])->toBe(3650)->and($admin['limits'])->toHaveKey('sync_run_retention_days');
+
+    $savedAdmin = fleetopsJsonPayload($controller->saveAdminTelematicsSettings(new Request(['event_retention_days' => 60, 'sync_run_retention_days' => 0])));
+    expect($savedAdmin['event_retention_days'])->toBe(60)
+        ->and($savedAdmin['sync_run_retention_days'])->toBe(0)
+        ->and($savedAdmin['processed_retention_hours'])->toBe(48)
+        ->and($controller->configured['fleet-ops.telematics-settings']['position_retention_days'])->toBe(90);
+    config(['telematics.telemetry' => []]);
+});
+
+test('telematics storage usage and cleanup require a company session', function () {
+    $controller = new FleetOpsSettingControllerProbe();
+    expect($controller->getTelematicsStorageUsage()->getStatusCode())->toBe(401)
+        ->and($controller->runTelematicsRetention()->getStatusCode())->toBe(401)
+        ->and($controller->pruned)->toBe([]);
+});
+
+test('telematics storage usage reports rows, age, compaction backlog and estimated size per table', function () {
+    Illuminate\Support\Carbon::setTestNow('2026-09-23 12:00:00 UTC');
+    try {
+        $controller                 = new FleetOpsSettingControllerProbe();
+        $controller->company        = (object) ['uuid' => 'company-1'];
+        $controller->telematicUuids = ['company-1' => ['tm-1']];
+        $controller->counts         = ['device_events' => 500, 'positions' => 40, 'telematic_deliveries' => 6, 'telematic_sync_runs' => 3];
+        $controller->oldest         = ['device_events' => '2026-08-01 00:00:00'];
+        $controller->rowLengths     = ['device_events' => 32000, 'positions' => 700];
+
+        $usage = fleetopsJsonPayload($controller->getTelematicsStorageUsage());
+        expect($usage['tables']['device_events'])->toBe([
+            'rows'             => 500,
+            'oldest'           => '2026-08-01 00:00:00',
+            'raw_payload_rows' => 500,
+            'compactable_rows' => 500,
+            'avg_row_bytes'    => 32000,
+            'estimated_bytes'  => 16000000,
+        ])
+            ->and($usage['tables']['positions'])->toBe(['rows' => 40, 'oldest' => null, 'avg_row_bytes' => 700, 'estimated_bytes' => 28000])
+            ->and($usage['tables']['telematic_deliveries'])->toBe(['rows' => 6, 'oldest' => null])
+            ->and($usage['tables']['telematic_sync_runs']['rows'])->toBe(3)
+            ->and($usage['generated_at'])->toBe('2026-09-23T12:00:00.000000Z')
+            ->and($controller->countScopes)->toBe(['device_events', 'positions', 'telematic_deliveries', 'telematic_sync_runs', 'device_events', 'device_events']);
+
+        // Without connections the inbox tables are reported empty; compaction disabled skips the backlog count.
+        $controller->telematicUuids                                    = [];
+        $controller->companySettings['fleet-ops.telematics-settings']  = ['event_compact_after_days' => 0];
+        $controller->countScopes                                       = [];
+        $usage                                                         = fleetopsJsonPayload($controller->getTelematicsStorageUsage());
+        expect($usage['tables']['telematic_deliveries'])->toBe(['rows' => 0, 'oldest' => null])
+            ->and($usage['tables']['telematic_sync_runs'])->toBe(['rows' => 0, 'oldest' => null])
+            ->and($usage['tables']['device_events']['compactable_rows'])->toBe(0)
+            ->and($controller->countScopes)->toBe(['device_events', 'positions', 'device_events']);
+
+        $queued = $controller->runTelematicsRetention();
+        expect($queued->getStatusCode())->toBe(202)
+            ->and(fleetopsJsonPayload($queued)['status'])->toBe('queued')
+            ->and($controller->pruned)->toBe(['company-1']);
+    } finally {
+        Illuminate\Support\Carbon::setTestNow();
+    }
+});
+
+test('telematics storage helpers query the database and size rows from InnoDB statistics on MySQL', function () {
+    $connection = new class(new PDO('sqlite::memory:')) extends Illuminate\Database\SQLiteConnection {
+        public string $driver = 'sqlite';
+        public array $selects = [];
+
+        public function getDriverName()
+        {
+            return $this->driver;
+        }
+
+        public function select($query, $bindings = [], $useReadPdo = true)
+        {
+            if (str_contains($query, 'information_schema')) {
+                $this->selects[] = [$query, $bindings];
+
+                // information_schema reports prefixed table names.
+                return [(object) ['name' => $bindings[0], 'length' => '32000'], (object) ['name' => $bindings[1], 'length' => 700]];
+            }
+
+            return parent::select($query, $bindings, $useReadPdo);
+        }
+    };
+    $connection->setTablePrefix('');
+    $originalDb = app()->bound('db') ? app('db') : null;
+    app()->instance('db', new class($connection) {
+        public function __construct(public $connection)
+        {
+        }
+
+        public function connection($name = null)
+        {
+            return $this->connection;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->connection->{$method}(...$arguments);
+        }
+    });
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+    try {
+        $schema = $connection->getSchemaBuilder();
+        $schema->create('telematics', function ($table) {
+            $table->increments('id');
+            $table->string('uuid');
+            $table->string('company_uuid');
+        });
+        $schema->create('device_events', function ($table) {
+            $table->increments('id');
+            $table->string('company_uuid')->nullable();
+            $table->timestamp('created_at')->nullable();
+        });
+        $connection->table('telematics')->insert([['uuid' => 'tm-1', 'company_uuid' => 'company-1'], ['uuid' => 'tm-2', 'company_uuid' => 'company-2']]);
+        $connection->table('device_events')->insert([
+            ['company_uuid' => 'company-1', 'created_at' => '2026-08-01 00:00:00'],
+            ['company_uuid' => 'company-1', 'created_at' => '2026-09-01 00:00:00'],
+            ['company_uuid' => 'company-2', 'created_at' => '2026-07-01 00:00:00'],
+        ]);
+
+        $controller = new class extends SettingController {
+            public function telematics(string $company): array
+            {
+                return $this->companyTelematicUuids($company);
+            }
+
+            public function usage(string $table, Closure $scope, string $column): array
+            {
+                return $this->tableUsage($table, $scope, $column);
+            }
+
+            public function lengths(array $tables): array
+            {
+                return $this->averageRowLengths($tables);
+            }
+        };
+        $byCompany = fn ($query) => $query->where('company_uuid', 'company-1');
+        expect($controller->telematics('company-1'))->toBe(['tm-1'])
+            ->and($controller->usage('device_events', $byCompany, 'created_at'))->toBe(['rows' => 2, 'oldest' => '2026-08-01 00:00:00'])
+            ->and($controller->usage('device_events', fn ($query) => $query->where('company_uuid', 'none'), 'created_at'))->toBe(['rows' => 0, 'oldest' => null])
+            ->and($controller->lengths(['device_events', 'positions']))->toBe([]);
+
+        $connection->driver = 'mysql';
+        $connection->setTablePrefix('fb_');
+        expect($controller->lengths(['device_events', 'positions']))->toBe(['device_events' => 32000, 'positions' => 700])
+            ->and($connection->selects[0][1])->toBe(['fb_device_events', 'fb_positions'])
+            ->and($connection->selects[0][0])->toContain('TABLE_NAME IN (?, ?)');
+    } finally {
+        if ($originalDb) {
+            app()->instance('db', $originalDb);
+        } else {
+            app()->forgetInstance('db');
+        }
+        Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+    }
+});
+
+test('telematics cleanup dispatches the unique prune job for the company', function () {
+    Fleetbase\TestSupport\DispatchRecorder::$dispatched = [];
+    $controller                                         = new class extends SettingController {
+        public function prune(string $company): void
+        {
+            $this->dispatchTelematicsPrune($company);
+        }
+    };
+    $controller->prune('company-1');
+
+    expect(Fleetbase\TestSupport\DispatchRecorder::$dispatched)->toBe([
+        ['job' => Fleetbase\FleetOps\Jobs\PruneTelematicsDataJob::class, 'arguments' => ['company-1']],
+    ]);
+    Fleetbase\TestSupport\DispatchRecorder::$dispatched = [];
+});
diff --git a/server/tests/Support/PruneTelematicsDataProbe.php b/server/tests/Support/PruneTelematicsDataProbe.php
new file mode 100644
index 000000000..0e1b05d4d
--- /dev/null
+++ b/server/tests/Support/PruneTelematicsDataProbe.php
@@ -0,0 +1,55 @@
+<?php
+
+use Fleetbase\FleetOps\Console\Commands\PruneTelematicsData;
+use Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy;
+use Illuminate\Support\Collection;
+
+/**
+ * Drives fleetops:prune-telematics-data without the console kernel: options,
+ * output and the settings-backed policy are all supplied by the test.
+ */
+class PruneTelematicsDataProbe extends PruneTelematicsData
+{
+    public array $messages = [];
+    public array $options  = ['company' => null, 'table' => [], 'batch-size' => 1000, 'max-batches' => 50, 'dry-run' => false, 'no-lock' => true];
+
+    /** company uuid ('' for the system defaults) => policy values passed to RetentionPolicy::fromArray */
+    public array $policies = [];
+
+    /** When set, replaces the companies table lookup. */
+    public ?Collection $companyRows = null;
+
+    public function option($key = null, $default = null)
+    {
+        return $this->options[$key] ?? $default;
+    }
+
+    public function info($string, $verbosity = null)
+    {
+        $this->messages[] = ['info', $string];
+    }
+
+    public function warn($string, $verbosity = null)
+    {
+        $this->messages[] = ['warn', $string];
+    }
+
+    public function error($string, $verbosity = null)
+    {
+        $this->messages[] = ['error', $string];
+    }
+
+    protected function policyFor(?string $companyUuid): RetentionPolicy
+    {
+        return RetentionPolicy::fromArray($this->policies[$companyUuid ?? ''] ?? $this->policies[''] ?? []);
+    }
+
+    protected function companies(?string $only): Collection
+    {
+        if ($this->companyRows === null) {
+            return parent::companies($only);
+        }
+
+        return $this->companyRows->filter(fn ($company) => !$only || $company->uuid === $only || $company->public_id === $only)->values();
+    }
+}
diff --git a/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php b/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php
new file mode 100644
index 000000000..bcd228f80
--- /dev/null
+++ b/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php
@@ -0,0 +1,314 @@
+<?php
+
+use Fleetbase\FleetOps\Console\Commands\PruneTelematicsData;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+require_once __DIR__ . '/../../Support/PruneTelematicsDataProbe.php';
+
+/**
+ * fleetops:prune-telematics-data against an in-memory SQLite fixture: per-company
+ * policies, compaction, inbox tables resolved through connections, orphans,
+ * bounded batches, dry runs, filters and locking.
+ */
+function fleetopsPruneBoot(): SQLiteConnection
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'), '', '', ['name' => 'mysql', 'driver' => 'sqlite']);
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+    app()->instance('db', new class($connection) {
+        public function __construct(public SQLiteConnection $c)
+        {
+        }
+
+        public function connection($name = null): SQLiteConnection
+        {
+            return $this->c;
+        }
+
+        public function __call($method, $arguments)
+        {
+            return $this->c->{$method}(...$arguments);
+        }
+    });
+    app()->instance('db.schema', $connection->getSchemaBuilder());
+    DB::clearResolvedInstance('db');
+    Schema::clearResolvedInstance('db.schema');
+
+    foreach ([
+        'companies'     => ['uuid', 'public_id', 'name'],
+        'telematics'    => ['uuid', 'public_id', 'company_uuid', 'provider', 'status'],
+        'devices'       => ['uuid', 'company_uuid', 'telematic_uuid', 'device_id'],
+        'device_events' => ['uuid', 'company_uuid', 'device_uuid', 'event_type', 'payload', 'meta', 'data'],
+        'positions'     => ['uuid', 'company_uuid', 'subject_uuid', 'subject_type'],
+    ] as $table => $columns) {
+        Schema::create($table, function ($blueprint) use ($columns) {
+            $blueprint->increments('id');
+            foreach ($columns as $column) {
+                $blueprint->text($column)->nullable();
+            }
+            $blueprint->timestamps();
+            $blueprint->timestamp('deleted_at')->nullable();
+        });
+    }
+    (require __DIR__ . '/../../../migrations/2026_09_15_000001_create_telematic_telemetry_tables.php')->up();
+    foreach (glob(__DIR__ . '/../../../migrations/2026_09_23_00000*_add_retention_index_to_*.php') as $migration) {
+        (require $migration)->up();
+    }
+
+    Carbon::setTestNow('2026-09-23 12:00:00 UTC');
+    DB::table('companies')->insert([
+        ['id' => 1, 'uuid' => 'company-1', 'public_id' => 'company_one'],
+        ['id' => 2, 'uuid' => 'company-2', 'public_id' => 'company_two'],
+    ]);
+    DB::table('telematics')->insert([
+        ['uuid' => 'tm-1', 'company_uuid' => 'company-1', 'provider' => 'afaqy', 'status' => 'active', 'deleted_at' => null],
+        ['uuid' => 'tm-1-trashed', 'company_uuid' => 'company-1', 'provider' => 'afaqy', 'status' => 'disabled', 'deleted_at' => '2026-09-01 00:00:00'],
+        ['uuid' => 'tm-2', 'company_uuid' => 'company-2', 'provider' => 'safee', 'status' => 'active', 'deleted_at' => null],
+    ]);
+
+    return $connection;
+}
+
+function fleetopsPruneEvent(string $uuid, ?string $company, int $daysOld, array $extra = []): array
+{
+    $at = Carbon::now()->subDays($daysOld)->toDateTimeString();
+
+    return array_merge([
+        'uuid'       => $uuid, 'company_uuid' => $company, 'event_type' => 'telemetry_update',
+        'payload'    => '{"raw":true}', 'meta' => '{"speed":1}', 'data' => '{"speed":1}',
+        'created_at' => $at, 'updated_at' => $at, 'deleted_at' => null,
+    ], $extra);
+}
+
+function fleetopsPruneDelivery(string $uuid, string $telematic, string $status, int $hoursOld): array
+{
+    $at = Carbon::now()->subHours($hoursOld)->toDateTimeString();
+
+    return [
+        'uuid'         => $uuid, 'telematic_uuid' => $telematic, 'source' => 'poll', 'status' => $status,
+        'payload_hash' => str_repeat('a', 64), 'payload' => 'x', 'received_at' => $at, 'available_at' => $at,
+        'created_at'   => $at, 'updated_at' => $at,
+    ];
+}
+
+function fleetopsPruneRun(string $uuid, string $telematic, string $status, int $daysOld): array
+{
+    $at = Carbon::now()->subDays($daysOld)->toDateTimeString();
+
+    return ['uuid' => $uuid, 'telematic_uuid' => $telematic, 'status' => $status, 'created_at' => $at, 'updated_at' => $at];
+}
+
+afterEach(fn () => Carbon::setTestNow());
+
+test('prune applies each company policy to events, positions and the inbox, and system defaults to orphans', function () {
+    fleetopsPruneBoot();
+    DB::table('device_events')->insert([
+        fleetopsPruneEvent('e-old', 'company-1', 40),
+        fleetopsPruneEvent('e-compact', 'company-1', 10),
+        fleetopsPruneEvent('e-compacted-already', 'company-1', 10, ['payload' => null, 'meta' => null]),
+        fleetopsPruneEvent('e-fresh', 'company-1', 1),
+        fleetopsPruneEvent('e-trashed', 'company-1', 1, ['deleted_at' => Carbon::now()->toDateTimeString()]),
+        fleetopsPruneEvent('e-forever', 'company-2', 400),
+        fleetopsPruneEvent('e-orphan-null', null, 40),
+        fleetopsPruneEvent('e-orphan-gone', 'company-gone', 40),
+        fleetopsPruneEvent('e-orphan-fresh', 'company-gone', 1),
+    ]);
+    DB::table('positions')->insert([
+        ['uuid' => 'p-old', 'company_uuid' => 'company-1', 'created_at' => Carbon::now()->subDays(100)->toDateTimeString(), 'deleted_at' => null],
+        ['uuid' => 'p-fresh', 'company_uuid' => 'company-1', 'created_at' => Carbon::now()->subDays(5)->toDateTimeString(), 'deleted_at' => null],
+        ['uuid' => 'p-trashed', 'company_uuid' => 'company-1', 'created_at' => Carbon::now()->toDateTimeString(), 'deleted_at' => Carbon::now()->toDateTimeString()],
+        ['uuid' => 'p-forever', 'company_uuid' => 'company-2', 'created_at' => Carbon::now()->subDays(1000)->toDateTimeString(), 'deleted_at' => null],
+    ]);
+    DB::table('telematic_deliveries')->insert([
+        fleetopsPruneDelivery('d-processed-old', 'tm-1', 'processed', 30),
+        fleetopsPruneDelivery('d-processed-trashed-connection', 'tm-1-trashed', 'processed', 30),
+        fleetopsPruneDelivery('d-processed-fresh', 'tm-1', 'processed', 2),
+        fleetopsPruneDelivery('d-pending-old', 'tm-1', 'pending', 200),
+        fleetopsPruneDelivery('d-quarantined-old', 'tm-1', 'quarantined', 24 * 8),
+        fleetopsPruneDelivery('d-quarantined-fresh', 'tm-1', 'quarantined', 24 * 2),
+        fleetopsPruneDelivery('d-company-2-long-hours', 'tm-2', 'processed', 30),
+        fleetopsPruneDelivery('d-orphan', 'tm-gone', 'processed', 30),
+    ]);
+    DB::table('telematic_sync_runs')->insert([
+        fleetopsPruneRun('r-old', 'tm-1', 'completed', 10),
+        fleetopsPruneRun('r-fresh', 'tm-1', 'completed', 2),
+        fleetopsPruneRun('r-fetching-old', 'tm-1', 'fetching', 10),
+        fleetopsPruneRun('r-ingesting-old', 'tm-1', 'ingesting', 10),
+        fleetopsPruneRun('r-orphan', 'tm-gone', 'partial', 10),
+    ]);
+
+    $command           = new PruneTelematicsDataProbe();
+    $command->policies = [
+        'company-1' => ['event_retention_days' => 30, 'event_compact_after_days' => 7, 'position_retention_days' => 90, 'processed_retention_hours' => 24, 'quarantine_retention_days' => 7, 'sync_run_retention_days' => 7],
+        'company-2' => ['event_retention_days' => 0, 'event_compact_after_days' => 0, 'position_retention_days' => 0, 'processed_retention_hours' => 48],
+        ''          => ['event_retention_days' => 30, 'processed_retention_hours' => 24, 'sync_run_retention_days' => 7],
+    ];
+
+    expect($command->handle())->toBe(0);
+
+    expect(DB::table('device_events')->orderBy('id')->pluck('uuid')->all())->toBe(['e-compact', 'e-compacted-already', 'e-fresh', 'e-forever', 'e-orphan-fresh']);
+    $compacted = DB::table('device_events')->where('uuid', 'e-compact')->first();
+    expect($compacted->payload)->toBeNull()->and($compacted->meta)->toBeNull()->and($compacted->data)->toBe('{"speed":1}');
+    expect(DB::table('device_events')->where('uuid', 'e-fresh')->value('payload'))->toBe('{"raw":true}');
+    expect(DB::table('positions')->orderBy('id')->pluck('uuid')->all())->toBe(['p-fresh', 'p-forever']);
+    expect(DB::table('telematic_deliveries')->orderBy('uuid')->pluck('uuid')->all())->toBe(['d-company-2-long-hours', 'd-pending-old', 'd-processed-fresh', 'd-quarantined-fresh']);
+    expect(DB::table('telematic_sync_runs')->orderBy('uuid')->pluck('uuid')->all())->toBe(['r-fetching-old', 'r-fresh', 'r-ingesting-old']);
+
+    expect($command->messages)->toContain(
+        ['info', 'company_one device_events: deleted=2 compacted=1 batches=3'],
+        ['info', 'company_one positions: deleted=2 compacted=0 batches=2'],
+        ['info', 'company_one telematic_deliveries: deleted=3 compacted=0 batches=2'],
+        ['info', 'company_one telematic_sync_runs: deleted=1 compacted=0 batches=1'],
+        ['info', 'orphaned device_events: deleted=2 compacted=0 batches=1'],
+        ['info', 'orphaned telematic_deliveries: deleted=1 compacted=0 batches=1'],
+        ['info', 'orphaned telematic_sync_runs: deleted=1 compacted=0 batches=1'],
+        ['info', 'Telematics prune complete: deleted=12 compacted=1 batches=11'],
+    );
+    // Company two kept everything, so it reports nothing.
+    expect(array_filter($command->messages, fn ($message) => str_starts_with($message[1], 'company_two')))->toBe([]);
+});
+
+test('prune bounds each sweep by batch count and reports a capped run', function () {
+    fleetopsPruneBoot();
+    $rows = [];
+    for ($i = 0; $i < 120; $i++) {
+        $rows[] = fleetopsPruneEvent('e-' . $i, 'company-1', 60);
+    }
+    DB::table('device_events')->insert($rows);
+
+    $command                         = new PruneTelematicsDataProbe();
+    $command->options['company']     = 'company_one';
+    $command->options['table']       = ['device_events'];
+    $command->options['batch-size']  = 10; // clamped up to the 100 row floor
+    $command->options['max-batches'] = 1;
+    $command->policies               = ['company-1' => ['event_retention_days' => 30, 'event_compact_after_days' => 0]];
+
+    expect($command->handle())->toBe(0)
+        ->and(DB::table('device_events')->count())->toBe(20)
+        ->and($command->messages)->toContain(
+            ['info', 'company_one device_events: deleted=100 compacted=0 batches=1 capped'],
+            ['info', 'Telematics prune complete: deleted=100 compacted=0 batches=1 (capped; more rows remain for the next run)'],
+        );
+
+    // The next run finishes the backlog; an exact multiple of the batch size is still reported as capped.
+    $command->messages = [];
+    expect($command->handle())->toBe(0)->and(DB::table('device_events')->count())->toBe(0);
+    $command->options['max-batches'] = 50;
+    $command->messages               = [];
+    expect($command->handle())->toBe(0)->and($command->messages)->toContain(['info', 'Telematics prune complete: deleted=0 compacted=0 batches=0']);
+
+    // Compaction is bounded the same way.
+    $rows = [];
+    for ($i = 0; $i < 120; $i++) {
+        $rows[] = fleetopsPruneEvent('c-' . $i, 'company-1', 10);
+    }
+    DB::table('device_events')->insert($rows);
+    $command->options['max-batches'] = 1;
+    $command->policies               = ['company-1' => ['event_retention_days' => 30, 'event_compact_after_days' => 7]];
+    $command->messages               = [];
+    expect($command->handle())->toBe(0)
+        ->and(DB::table('device_events')->whereNull('payload')->count())->toBe(100)
+        ->and($command->messages)->toContain(['info', 'company_one device_events: deleted=0 compacted=100 batches=1 capped']);
+});
+
+test('prune dry runs count without touching rows and honour table and company filters', function () {
+    fleetopsPruneBoot();
+    DB::table('device_events')->insert([
+        fleetopsPruneEvent('e-old-1', 'company-1', 40),
+        fleetopsPruneEvent('e-compact-1', 'company-1', 10),
+        fleetopsPruneEvent('e-old-2', 'company-2', 40),
+    ]);
+    DB::table('positions')->insert([['uuid' => 'p-old', 'company_uuid' => 'company-1', 'created_at' => Carbon::now()->subDays(100)->toDateTimeString()]]);
+
+    $command                     = new PruneTelematicsDataProbe();
+    $command->options['dry-run'] = true;
+    $command->options['company'] = 'company-1';
+    $command->options['table']   = ['device_events', 'positions', 'device_events'];
+    $command->policies           = ['company-1' => ['event_retention_days' => 30, 'event_compact_after_days' => 7, 'position_retention_days' => 90]];
+
+    expect($command->handle())->toBe(0)
+        ->and(DB::table('device_events')->count())->toBe(3)
+        ->and(DB::table('positions')->count())->toBe(1)
+        ->and($command->messages)->toContain(
+            ['info', 'company_one device_events: deleted=1 compacted=1 batches=0'],
+            ['info', 'company_one positions: deleted=1 compacted=0 batches=0'],
+            ['info', 'Telematics prune dry run: deleted=2 compacted=1 batches=0'],
+        );
+
+    // Only the requested table is swept when not a dry run.
+    $command->options['dry-run'] = false;
+    $command->options['table']   = ['positions'];
+    $command->messages           = [];
+    expect($command->handle())->toBe(0)
+        ->and(DB::table('device_events')->count())->toBe(3)
+        ->and(DB::table('positions')->count())->toBe(0);
+});
+
+test('prune rejects unknown tables and companies', function () {
+    fleetopsPruneBoot();
+    $command                   = new PruneTelematicsDataProbe();
+    $command->options['table'] = ['device_events', 'orders'];
+    expect($command->handle())->toBe(PruneTelematicsData::FAILURE)
+        ->and($command->messages)->toContain(['error', 'Unknown table. Valid tables: device_events, positions, telematic_deliveries, telematic_sync_runs.']);
+
+    $command                     = new PruneTelematicsDataProbe();
+    $command->options['company'] = 'company-missing';
+    expect($command->handle())->toBe(PruneTelematicsData::FAILURE)
+        ->and($command->messages)->toContain(['error', 'Company [company-missing] was not found.']);
+});
+
+test('prune takes a bounded lock and yields to a run already in progress', function () {
+    fleetopsPruneBoot();
+    $originalCache = Illuminate\Support\Facades\Cache::getFacadeRoot();
+    try {
+        $store = new class extends Illuminate\Cache\ArrayStore {
+            public array $requestedLocks = [];
+
+            public function lock($name, $seconds = 0, $owner = null)
+            {
+                $this->requestedLocks[] = [$name, $seconds];
+
+                return parent::lock($name, $seconds, $owner);
+            }
+        };
+        Illuminate\Support\Facades\Cache::swap(new Illuminate\Cache\Repository($store));
+
+        $command                     = new PruneTelematicsDataProbe();
+        $command->options['no-lock'] = false;
+        expect($command->handle())->toBe(0)
+            ->and($store->requestedLocks)->toBe([[PruneTelematicsData::LOCK, 840]])
+            ->and($store->locks)->toBe([]);
+
+        expect($store->lock(PruneTelematicsData::LOCK, 840)->get())->toBeTrue();
+        $command->messages = [];
+        expect($command->handle())->toBe(0)
+            ->and($command->messages)->toBe([['warn', 'Another telematics prune run appears to be in progress.']]);
+    } finally {
+        Illuminate\Support\Facades\Cache::swap($originalCache);
+    }
+});
+
+test('prune resolves the live company policy when none is injected', function () {
+    fleetopsPruneBoot();
+    Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy::flush();
+    Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy::$settingsResolver = fn () => ['event_retention_days' => 5];
+    try {
+        DB::table('device_events')->insert([fleetopsPruneEvent('e-old', 'company-1', 6)]);
+        $command = new class extends PruneTelematicsDataProbe {
+            protected function policyFor(?string $companyUuid): Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy
+            {
+                return PruneTelematicsData::policyFor($companyUuid);
+            }
+        };
+        expect($command->handle())->toBe(0)->and(DB::table('device_events')->count())->toBe(0);
+    } finally {
+        Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy::flush();
+        Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy::$settingsResolver = null;
+    }
+});
diff --git a/server/tests/Unit/Jobs/PruneTelematicsDataJobTest.php b/server/tests/Unit/Jobs/PruneTelematicsDataJobTest.php
new file mode 100644
index 000000000..7f99ce05b
--- /dev/null
+++ b/server/tests/Unit/Jobs/PruneTelematicsDataJobTest.php
@@ -0,0 +1,48 @@
+<?php
+
+use Fleetbase\FleetOps\Console\Commands\PruneTelematicsData;
+use Fleetbase\FleetOps\Jobs\PruneTelematicsDataJob;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * The on-demand cleanup job is unique per company and runs the prune command
+ * directly, without the console kernel's command registry.
+ */
+class FleetOpsPruneCommandRunRecorder extends PruneTelematicsData
+{
+    public array $runs = [];
+
+    public function run(InputInterface $input, OutputInterface $output): int
+    {
+        $this->runs[] = (string) $input;
+
+        return 0;
+    }
+}
+
+test('prune job is unique per company and runs the command for that company without the process lock', function () {
+    $recorder = new FleetOpsPruneCommandRunRecorder();
+    app()->instance(PruneTelematicsData::class, $recorder);
+    try {
+        $job = new PruneTelematicsDataJob('company-1');
+        expect($job)->toBeInstanceOf(ShouldQueue::class)->toBeInstanceOf(ShouldBeUnique::class)
+            ->and($job->uniqueId())->toBe('company-1')
+            ->and($job->uniqueFor)->toBe(900)
+            ->and($job->tries)->toBe(1)
+            ->and($job->parameters())->toBe(['--no-lock' => true, '--max-batches' => 200, '--company' => 'company-1']);
+        $job->handle();
+
+        (new PruneTelematicsDataJob(null, 25))->handle();
+        expect((new PruneTelematicsDataJob())->uniqueId())->toBe('all')
+            ->and($recorder->runs)->toBe([
+                '--no-lock=1 --max-batches=200 --company=company-1',
+                '--no-lock=1 --max-batches=25',
+            ])
+            ->and($recorder->getLaravel())->toBe(app());
+    } finally {
+        app()->forgetInstance(PruneTelematicsData::class);
+    }
+});
diff --git a/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php b/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php
new file mode 100644
index 000000000..24e91765e
--- /dev/null
+++ b/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php
@@ -0,0 +1,130 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy;
+use Illuminate\Support\Carbon;
+
+/**
+ * RetentionPolicy layers package config, the admin setting and the company
+ * setting, clamps every value, and caches per company for long-lived workers.
+ */
+function fleetopsRetentionResolver(array $system, array $company, ?array &$calls = null): void
+{
+    $calls                             = [];
+    RetentionPolicy::$settingsResolver = function (string $scope, string $key, mixed $default, ?string $companyUuid) use ($system, $company, &$calls) {
+        $calls[] = [$scope, $key, $companyUuid];
+        expect($key)->toBe(RetentionPolicy::SETTING_KEY);
+
+        return $scope === 'system' ? $system : ($company[$companyUuid] ?? $default);
+    };
+}
+
+beforeEach(function () {
+    RetentionPolicy::flush();
+    RetentionPolicy::$settingsResolver = null;
+    config(['telematics.telemetry' => ['event_retention_days' => 45, 'processed_retention_hours' => 48, 'log_telemetry_activity' => true, 'poll_queue' => 'default']]);
+});
+
+afterEach(function () {
+    RetentionPolicy::flush();
+    RetentionPolicy::$settingsResolver = null;
+    Carbon::setTestNow();
+    config(['telematics.telemetry' => []]);
+});
+
+test('defaults come from package config, overridden by the admin setting, with everything clamped', function () {
+    fleetopsRetentionResolver([], []);
+    expect(RetentionPolicy::defaults())->toBe([
+        'event_retention_days'      => 45,
+        'event_compact_after_days'  => 7,
+        'position_retention_days'   => 90,
+        'processed_retention_hours' => 48,
+        'quarantine_retention_days' => 7,
+        'sync_run_retention_days'   => 7,
+        'log_telemetry_activity'    => true,
+    ]);
+
+    RetentionPolicy::flush();
+    fleetopsRetentionResolver([
+        'event_retention_days'      => 99999,
+        'event_compact_after_days'  => '',
+        'position_retention_days'   => 0,
+        'quarantine_retention_days' => -5,
+        'processed_retention_hours' => null,
+        'log_telemetry_activity'    => 'no',
+        'ignored'                   => 'value',
+    ], []);
+    $defaults = RetentionPolicy::defaults();
+    expect($defaults['event_retention_days'])->toBe(3650)
+        ->and($defaults['event_compact_after_days'])->toBe(7)
+        ->and($defaults['position_retention_days'])->toBe(0)
+        ->and($defaults['quarantine_retention_days'])->toBe(1)
+        ->and($defaults['processed_retention_hours'])->toBe(48)
+        ->and($defaults['log_telemetry_activity'])->toBeFalse()
+        ->and($defaults)->not->toHaveKey('ignored')
+        ->and(RetentionPolicy::keys())->toBe(array_keys(RetentionPolicy::FALLBACKS));
+});
+
+test('company policies layer over the defaults and are cached until flushed', function () {
+    fleetopsRetentionResolver(['position_retention_days' => 30], ['company-1' => ['event_retention_days' => 10, 'log_telemetry_activity' => false]], $calls);
+
+    $policy = RetentionPolicy::forCompany('company-1');
+    expect($policy->get('event_retention_days'))->toBe(10)
+        ->and($policy->get('position_retention_days'))->toBe(30)
+        ->and($policy->get('processed_retention_hours'))->toBe(48)
+        ->and($policy->logsTelemetryActivity())->toBeFalse()
+        ->and($policy->toArray())->toHaveKeys(RetentionPolicy::keys())
+        ->and(RetentionPolicy::forCompany('company-1'))->toBe($policy)
+        ->and(RetentionPolicy::forCompany(null)->toArray())->toBe(RetentionPolicy::defaults())
+        ->and(RetentionPolicy::forCompany('company-2')->get('event_retention_days'))->toBe(45)
+        ->and(array_column($calls, 0))->toBe(['system', 'company', 'company']);
+
+    RetentionPolicy::flush('company-1');
+    RetentionPolicy::forCompany('company-1');
+    RetentionPolicy::forCompany('company-2');
+    expect(count($calls))->toBe(4);
+
+    RetentionPolicy::flush();
+    RetentionPolicy::forCompany('company-2');
+    expect(array_column($calls, 0))->toBe(['system', 'company', 'company', 'company', 'system', 'company']);
+});
+
+test('cutoffs, compaction and deletion rules follow the clamped values', function () {
+    Carbon::setTestNow('2026-09-23 12:00:00 UTC');
+
+    $policy = RetentionPolicy::fromArray(['event_retention_days' => 10, 'event_compact_after_days' => 10, 'processed_retention_hours' => 6, 'position_retention_days' => 0]);
+    expect($policy->deletesEvents())->toBeTrue()
+        ->and($policy->compactsEvents())->toBeFalse()
+        ->and($policy->cutoff('processed_retention_hours')?->toDateTimeString())->toBe('2026-09-23 06:00:00')
+        ->and($policy->cutoff('event_retention_days')?->toDateTimeString())->toBe('2026-09-13 12:00:00')
+        ->and($policy->cutoff('position_retention_days'))->toBeNull()
+        ->and($policy->cutoff('unknown'))->toBeNull()
+        ->and($policy->get('unknown'))->toBeNull();
+
+    expect(RetentionPolicy::fromArray(['event_retention_days' => 10, 'event_compact_after_days' => 3])->compactsEvents())->toBeTrue()
+        ->and(RetentionPolicy::fromArray(['event_retention_days' => 0, 'event_compact_after_days' => 5])->compactsEvents())->toBeTrue()
+        ->and(RetentionPolicy::fromArray(['event_retention_days' => 0, 'event_compact_after_days' => 5])->deletesEvents())->toBeFalse()
+        ->and(RetentionPolicy::fromArray(['event_compact_after_days' => 0])->compactsEvents())->toBeFalse()
+        ->and(RetentionPolicy::fromArray([], ['event_retention_days' => 12])->get('event_retention_days'))->toBe(12)
+        ->and(RetentionPolicy::normalize(['log_telemetry_activity' => '1'], [])['log_telemetry_activity'])->toBeTrue();
+});
+
+test('a failing or malformed settings store falls back to the layer below', function () {
+    RetentionPolicy::$settingsResolver = fn () => throw new RuntimeException('settings unavailable');
+    expect(RetentionPolicy::forCompany('company-1')->get('event_retention_days'))->toBe(45);
+
+    RetentionPolicy::flush();
+    RetentionPolicy::$settingsResolver = fn () => 'not-an-array';
+    expect(RetentionPolicy::defaults()['processed_retention_hours'])->toBe(48);
+});
+
+test('company lookups scope the session for the setting store and restore it afterwards', function () {
+    // Without a resolver the policy reaches Setting, which has no database here and throws.
+    app('session')->put('company', 'previous-company');
+    expect(RetentionPolicy::forCompany('company-9')->get('event_retention_days'))->toBe(45)
+        ->and(app('session')->get('company'))->toBe('previous-company');
+
+    app('session')->forget('company');
+    RetentionPolicy::flush();
+    expect(RetentionPolicy::forCompany('company-9')->get('processed_retention_hours'))->toBe(48)
+        ->and(app('session')->has('company'))->toBeFalse();
+});
diff --git a/server/tests/Unit/Support/Telematics/Retention/TelemetryActivityTest.php b/server/tests/Unit/Support/Telematics/Retention/TelemetryActivityTest.php
new file mode 100644
index 000000000..e4c24e926
--- /dev/null
+++ b/server/tests/Unit/Support/Telematics/Retention/TelemetryActivityTest.php
@@ -0,0 +1,60 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy;
+use Fleetbase\FleetOps\Support\Telematics\Retention\TelemetryActivity;
+use Spatie\Activitylog\ActivityLogger;
+
+/**
+ * Telemetry writes bypass the activity log unless the company opted in, and
+ * still run when no activity logger is available.
+ */
+function fleetopsTelemetryActivityLogger(): ActivityLogger
+{
+    $logger = new class extends ActivityLogger {
+        public int $suppressed = 0;
+
+        public function __construct()
+        {
+        }
+
+        public function withoutLogs(Closure $callback): mixed
+        {
+            $this->suppressed++;
+
+            return $callback();
+        }
+    };
+    app()->instance(ActivityLogger::class, $logger);
+
+    return $logger;
+}
+
+beforeEach(function () {
+    RetentionPolicy::flush();
+    config(['telematics.telemetry' => []]);
+});
+
+afterEach(function () {
+    RetentionPolicy::flush();
+    RetentionPolicy::$settingsResolver = null;
+    app()->forgetInstance(ActivityLogger::class);
+});
+
+test('telemetry activity is suppressed by default and logged when a company opts in', function () {
+    RetentionPolicy::$settingsResolver = fn (string $scope, string $key, mixed $default, ?string $company) => $company === 'verbose' ? ['log_telemetry_activity' => true] : [];
+    $logger                            = fleetopsTelemetryActivityLogger();
+
+    expect(TelemetryActivity::run('quiet', fn () => 'saved'))->toBe('saved')
+        ->and($logger->suppressed)->toBe(1)
+        ->and(TelemetryActivity::run('verbose', fn () => 'logged'))->toBe('logged')
+        ->and($logger->suppressed)->toBe(1)
+        ->and(TelemetryActivity::run(null, fn () => 'system'))->toBe('system')
+        ->and($logger->suppressed)->toBe(2);
+});
+
+test('telemetry writes still run when the activity logger cannot be resolved', function () {
+    RetentionPolicy::$settingsResolver = fn () => [];
+    app()->forgetInstance(ActivityLogger::class);
+
+    expect(TelemetryActivity::run('company-1', fn () => 'unlogged'))->toBe('unlogged');
+});
diff --git a/tests/integration/components/admin/telematics-settings-test.js b/tests/integration/components/admin/telematics-settings-test.js
new file mode 100644
index 000000000..248f44b0e
--- /dev/null
+++ b/tests/integration/components/admin/telematics-settings-test.js
@@ -0,0 +1,54 @@
+import { module, test } from 'qunit';
+import { setupRenderingTest } from 'dummy/tests/helpers';
+import { render, click, fillIn } from '@ember/test-helpers';
+import { hbs } from 'ember-cli-htmlbars';
+import Service from '@ember/service';
+
+class FetchStubService extends Service {
+    posts = [];
+
+    get() {
+        return Promise.resolve({ event_retention_days: 60, position_retention_days: 0, log_telemetry_activity: false });
+    }
+
+    post(url, body) {
+        this.posts.push([url, body]);
+        return Promise.resolve(body);
+    }
+}
+
+class NotificationsStubService extends Service {
+    successes = [];
+
+    success(message) {
+        this.successes.push(message);
+    }
+
+    serverError() {}
+}
+
+module('Integration | Component | admin/telematics-settings', function (hooks) {
+    setupRenderingTest(hooks);
+
+    hooks.beforeEach(function () {
+        this.owner.register('service:fetch', FetchStubService);
+        this.owner.register('service:notifications', NotificationsStubService);
+    });
+
+    test('it loads system defaults and saves them', async function (assert) {
+        await render(hbs`<Admin::TelematicsSettings />`);
+
+        assert.dom('input[type="number"]').exists({ count: 6 });
+        assert.dom('input[type="number"]').hasValue('60');
+
+        await fillIn('input[type="number"]', '45');
+        await click('button.btn-primary');
+
+        const fetch = this.owner.lookup('service:fetch');
+        assert.strictEqual(fetch.posts.length, 1);
+        assert.strictEqual(fetch.posts[0][0], 'fleet-ops/settings/admin-telematics-settings');
+        assert.strictEqual(fetch.posts[0][1].event_retention_days, 45);
+        assert.strictEqual(fetch.posts[0][1].position_retention_days, 0);
+        assert.strictEqual(this.owner.lookup('service:notifications').successes.length, 1);
+    });
+});
diff --git a/tests/unit/controllers/settings/telematics-test.js b/tests/unit/controllers/settings/telematics-test.js
new file mode 100644
index 000000000..e3227bbd5
--- /dev/null
+++ b/tests/unit/controllers/settings/telematics-test.js
@@ -0,0 +1,117 @@
+import { module, test } from 'qunit';
+import { setupTest } from 'dummy/tests/helpers';
+import { settled } from '@ember/test-helpers';
+import Service from '@ember/service';
+
+const SETTINGS = {
+    event_retention_days: 12,
+    event_compact_after_days: 12,
+    position_retention_days: 0,
+    processed_retention_hours: 6,
+    quarantine_retention_days: 3,
+    sync_run_retention_days: 2,
+    log_telemetry_activity: true,
+    defaults: { event_retention_days: 30 },
+    limits: { event_retention_days: [1, 3650] },
+};
+
+const USAGE = {
+    tables: {
+        device_events: { rows: 1200, oldest: '2026-08-01 00:00:00', raw_payload_rows: 300, compactable_rows: 100, avg_row_bytes: 32000, estimated_bytes: 38400000 },
+        positions: { rows: 40, oldest: null },
+        telematic_deliveries: { rows: 0, oldest: null },
+    },
+};
+
+class FetchStubService extends Service {
+    posts = [];
+
+    get(url) {
+        if (url === 'fleet-ops/settings/telematics-settings') {
+            return Promise.resolve(SETTINGS);
+        }
+        if (url === 'fleet-ops/settings/telematics-storage-usage') {
+            return Promise.resolve(USAGE);
+        }
+
+        return Promise.resolve({});
+    }
+
+    post(url, body) {
+        this.posts.push([url, body]);
+        return Promise.resolve({ ...body, status: 'ok' });
+    }
+}
+
+class NotificationsStubService extends Service {
+    successes = [];
+    errors = [];
+
+    success(message) {
+        this.successes.push(message);
+    }
+
+    serverError(error) {
+        this.errors.push(error);
+    }
+}
+
+class CurrentUserStubService extends Service {
+    isAdmin = false;
+}
+
+module('Unit | Controller | settings/telematics', function (hooks) {
+    setupTest(hooks);
+
+    hooks.beforeEach(function () {
+        this.owner.register('service:fetch', FetchStubService);
+        this.owner.register('service:notifications', NotificationsStubService);
+        this.owner.register('service:current-user', CurrentUserStubService);
+    });
+
+    test('it exists', function (assert) {
+        let controller = this.owner.lookup('controller:settings/telematics');
+        assert.ok(controller);
+    });
+
+    test('it loads settings and usage, flags ineffective compaction and saves integers', async function (assert) {
+        const controller = this.owner.lookup('controller:settings/telematics');
+        await settled();
+
+        assert.strictEqual(controller.eventRetentionDays, 12);
+        assert.strictEqual(controller.positionRetentionDays, 0);
+        assert.true(controller.logTelemetryActivity);
+        assert.deepEqual(controller.defaults, { event_retention_days: 30 });
+        assert.true(controller.compactionIneffective, 'compacting at the deletion age is pointless');
+        assert.false(controller.isAdmin);
+
+        assert.deepEqual(
+            controller.usageRows.map((row) => row.table),
+            ['device_events', 'positions', 'telematic_deliveries']
+        );
+        assert.strictEqual(controller.usageRows[0].estimated_bytes, 38400000);
+
+        controller.eventCompactAfterDays = '5';
+        controller.eventRetentionDays = '';
+        controller.processedRetentionHours = 'abc';
+        assert.false(controller.compactionIneffective);
+        await controller.saveSettings.perform();
+
+        const fetch = this.owner.lookup('service:fetch');
+        assert.deepEqual(fetch.posts, [
+            [
+                'fleet-ops/settings/telematics-settings',
+                {
+                    event_retention_days: 0,
+                    event_compact_after_days: 5,
+                    position_retention_days: 0,
+                    processed_retention_hours: 0,
+                    quarantine_retention_days: 3,
+                    sync_run_retention_days: 2,
+                    log_telemetry_activity: true,
+                },
+            ],
+        ]);
+        assert.strictEqual(this.owner.lookup('service:notifications').successes.length, 1);
+    });
+});
diff --git a/tests/unit/routes/settings/telematics-test.js b/tests/unit/routes/settings/telematics-test.js
new file mode 100644
index 000000000..6a055f10e
--- /dev/null
+++ b/tests/unit/routes/settings/telematics-test.js
@@ -0,0 +1,58 @@
+import { module, test } from 'qunit';
+import { setupTest } from 'dummy/tests/helpers';
+import Service from '@ember/service';
+
+class AbilitiesStubService extends Service {
+    allowed = true;
+
+    cannot() {
+        return !this.allowed;
+    }
+}
+
+class HostRouterStubService extends Service {
+    transitions = [];
+
+    transitionTo(route) {
+        this.transitions.push(route);
+        return route;
+    }
+}
+
+class NotificationsStubService extends Service {
+    warnings = [];
+
+    warning(message) {
+        this.warnings.push(message);
+    }
+}
+
+module('Unit | Route | settings/telematics', function (hooks) {
+    setupTest(hooks);
+
+    hooks.beforeEach(function () {
+        this.owner.register('service:abilities', AbilitiesStubService);
+        this.owner.register('service:host-router', HostRouterStubService);
+        this.owner.register('service:notifications', NotificationsStubService);
+    });
+
+    test('it exists', function (assert) {
+        let route = this.owner.lookup('route:settings/telematics');
+        assert.ok(route);
+    });
+
+    test('it lets permitted users through and redirects everyone else', function (assert) {
+        const route = this.owner.lookup('route:settings/telematics');
+        const abilities = this.owner.lookup('service:abilities');
+        const hostRouter = this.owner.lookup('service:host-router');
+        const notifications = this.owner.lookup('service:notifications');
+
+        assert.strictEqual(route.beforeModel(), undefined);
+        assert.deepEqual(hostRouter.transitions, []);
+
+        abilities.allowed = false;
+        assert.strictEqual(route.beforeModel(), 'console.fleet-ops');
+        assert.deepEqual(hostRouter.transitions, ['console.fleet-ops']);
+        assert.strictEqual(notifications.warnings.length, 1);
+    });
+});
diff --git a/translations/en-us.yaml b/translations/en-us.yaml
index 98e50bedd..c93366201 100644
--- a/translations/en-us.yaml
+++ b/translations/en-us.yaml
@@ -114,6 +114,7 @@ menu:
     maintenances: Maintenances
     orchestrator: Orchestrator
     orchestrator-settings: Orchestrator Settings
+    telematics-settings: Telematics Data
 
 trailer:
     navigation-description: Manage towed assets, towing connections, equipment, and telematics.
@@ -2723,6 +2724,48 @@ route-list:
     more-waypoints: more waypoints
 
 settings:
+    telematics:
+        telematics-settings: Telematics Data Retention
+        intro: Telematics polling writes a device event, a position and a delivery envelope for every reporting device on every poll. These rules bound how long each kind of row is kept so storage stays predictable. A value of 0 keeps rows forever.
+        device-events: Device Events
+        event-retention-days: Keep device events for (days)
+        event-retention-days-help: Events older than this are permanently deleted. Applies to telemetry updates and provider alerts alike.
+        event-compact-after-days: Strip raw payloads after (days)
+        event-compact-after-days-help: Events older than this keep their type, severity, location and normalized data, but the raw provider payload is removed. Raw payloads are the bulk of each event's size.
+        compaction-warning: Raw payloads are only stripped from events that are kept. Set this lower than the event retention or set it to 0 to disable compaction.
+        positions: Positions
+        position-retention-days: Keep positions for (days)
+        position-retention-days-help: Vehicle and trailer position history older than this is permanently deleted. Route replay and history views only reach back this far.
+        inbox: Delivery Inbox & Sync Runs
+        processed-retention-hours: Keep processed deliveries for (hours)
+        processed-retention-hours-help: Raw provider batches are stored encrypted until processed and kept briefly for replay and diagnostics. Each batch can be close to a megabyte.
+        quarantine-retention-days: Keep quarantined deliveries for (days)
+        quarantine-retention-days-help: Batches that could not be processed stay available for inspection and replay for this long.
+        sync-run-retention-days: Keep sync run diagnostics for (days)
+        sync-run-retention-days-help: One sync run row is recorded per connection per poll. In-flight runs are never removed.
+        activity-logging: Activity Logging
+        log-telemetry-activity: Log telemetry activity
+        log-telemetry-activity-help: Write telemetry-driven device, event and vehicle saves to the activity log. Off by default; every poll otherwise adds several activity rows per device.
+        storage-usage: Storage Usage
+        table: Table
+        rows: Rows
+        estimated-size: Estimated size
+        oldest: Oldest row
+        not-available: n/a
+        raw-payload-rows: "{count} rows still carry raw payloads, {compactable} eligible for compaction now"
+        refresh: Refresh
+        run-cleanup: Run cleanup now
+        run-cleanup-confirm: This queues a retention run for your organization using the rules above. Rows outside the retention windows are permanently deleted and cannot be recovered. Continue?
+        cleanup-queued: Telematics cleanup has been queued. Usage refreshes shortly.
+        usage-unavailable: Storage usage is not available right now.
+        space-reclaim-note: Sizes are estimates from average row length. Deleting rows frees space inside the database files; run OPTIMIZE TABLE during a maintenance window to return it to the operating system.
+        admin-defaults: System Defaults (administrators)
+        settings-saved: Telematics data settings saved.
+        tables:
+            device_events: Device events
+            positions: Positions
+            telematic_deliveries: Delivery inbox
+            telematic_sync_runs: Sync runs
     avatar-management: Avatar Management
     custom-fields: Custom Fields
     notifications:

From 44c9270a0873a83c0876eb0ee88db2a6a1d0c56e Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Thu, 24 Sep 2026 12:39:57 +0800
Subject: [PATCH 02/24] fix(custom-fields): persist fuel report and service
 area custom field values

Ember Data's REST serializer sends a record under a camelCase root
(`fuelReport`, `serviceArea`). The base controller's payload reader
accepts both spellings, so the ordinary attributes saved, but these two
afterSave hooks read `$request->array('fuel_report.custom_field_values')`
and `'service_area.custom_field_values'` from the raw request, which was
always empty. No custom field value was ever persisted for either
resource; single-word resources (driver, vehicle, ...) were unaffected.

Read the values from the payload the base controller already extracted,
which the after hook receives as its third argument, so the root key's
spelling no longer matters.

Found while testing the ember-ui signature pad custom field on a fuel
report: the upload landed, the report saved, and the value vanished.
---
 .../Controllers/Internal/v1/FuelReportController.php | 12 +++++++++---
 .../Internal/v1/ServiceAreaController.php            | 12 +++++++++---
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/server/src/Http/Controllers/Internal/v1/FuelReportController.php b/server/src/Http/Controllers/Internal/v1/FuelReportController.php
index 9ff460a31..c2e8db2bf 100644
--- a/server/src/Http/Controllers/Internal/v1/FuelReportController.php
+++ b/server/src/Http/Controllers/Internal/v1/FuelReportController.php
@@ -9,6 +9,7 @@
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Illuminate\Http\Request;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Str;
 use Maatwebsite\Excel\Facades\Excel;
 
@@ -23,11 +24,16 @@ class FuelReportController extends FleetOpsController
 
     /**
      * Handle post save transactions.
+     *
+     * Reads the custom field values from the payload the base controller already extracted
+     * rather than from the raw request: Ember Data sends the resource under a camelCase root
+     * (`fuelReport`), so `$request->array('fuel_report.custom_field_values')` was always empty and no
+     * custom field value was ever persisted for this resource.
      */
-    public function afterSave(Request $request, FuelReport $fuelReport)
+    public function afterSave(Request $request, FuelReport $fuelReport, array $input = [])
     {
-        $customFieldValues = $request->array('fuel_report.custom_field_values');
-        if ($customFieldValues) {
+        $customFieldValues = Arr::get($input, 'custom_field_values');
+        if (is_array($customFieldValues) && $customFieldValues) {
             $fuelReport->syncCustomFieldValues($customFieldValues);
         }
     }
diff --git a/server/src/Http/Controllers/Internal/v1/ServiceAreaController.php b/server/src/Http/Controllers/Internal/v1/ServiceAreaController.php
index 320a83265..36926e45a 100644
--- a/server/src/Http/Controllers/Internal/v1/ServiceAreaController.php
+++ b/server/src/Http/Controllers/Internal/v1/ServiceAreaController.php
@@ -7,6 +7,7 @@
 use Fleetbase\FleetOps\Models\ServiceArea;
 use Fleetbase\Http\Requests\ExportRequest;
 use Illuminate\Http\Request;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Str;
 use Maatwebsite\Excel\Facades\Excel;
 
@@ -21,11 +22,16 @@ class ServiceAreaController extends FleetOpsController
 
     /**
      * Handle post save transactions.
+     *
+     * Reads the custom field values from the payload the base controller already extracted
+     * rather than from the raw request: Ember Data sends the resource under a camelCase root
+     * (`serviceArea`), so `$request->array('service_area.custom_field_values')` was always empty and no
+     * custom field value was ever persisted for this resource.
      */
-    public function afterSave(Request $request, ServiceArea $serviceArea)
+    public function afterSave(Request $request, ServiceArea $serviceArea, array $input = [])
     {
-        $customFieldValues = $request->array('service_area.custom_field_values');
-        if ($customFieldValues) {
+        $customFieldValues = Arr::get($input, 'custom_field_values');
+        if (is_array($customFieldValues) && $customFieldValues) {
             $serviceArea->syncCustomFieldValues($customFieldValues);
         }
     }

From 4791b3e707ba05b4cd062201a7a69a14c4b3e150 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Fri, 25 Sep 2026 10:31:03 +0800
Subject: [PATCH 03/24] feat(reporting): report on order items, tracking,
 identifiers and storefront totals

The Orders report table was missing most of what an order report needs, and
several tables referenced columns that do not exist.

Orders
- Order ID / Internal ID now show (core-api hid every *_id column as a key).
- New columns: customer and facilitator kind, dispatched/started flags, time
  window, ad hoc distance, POD method, route optimized, priority, notes.
- Storefront totals from meta as expression columns: storefront, currency,
  subtotal, delivery fee, tip and total (in the currency's smallest unit).
- Summary columns: total/completed/canceled orders (distinct, so they stay right
  when items are joined), order total/average, delivery fees, tips; the
  transaction sums now read transaction.amount instead of a missing orders.amount.
- New relationships: tracking number (+ latest tracking status), order config,
  customer vendor, created by, purchase rate -> service quote, payload return.
- Payload now has its own columns and exposes its items (payload.entities, one
  row per item) with name, SKU, price, product ID, quantity and line total
  from meta, plus the item destination.
- Distance/duration are labelled in meters/seconds (what is stored); the
  km->miles transformer on a meters column is gone.

Other tables
- Drivers: name/email/phone and current_vehicle_uuid do not exist on drivers;
  use the user and vehicle relationships.
- Vehicles: the driver join used a non-existent current_driver_uuid.
- Fuel reports: cost/odometer_reading/report_date do not exist; use amount,
  odometer, metric unit and created_at.
- Every table and item join leaves soft-deleted rows out.

Requires fleetbase/core-api feature/report-framework-enhancements for expression
columns and soft-delete filtering; on older core-api releases the schema still
registers (the new columns fall back to plain computed columns).
---
 .../Reporting/FleetOpsReportSchema.php        | 633 +++++++++++++++---
 server/tests/ReportSchemaContractsTest.php    | 123 +++-
 2 files changed, 654 insertions(+), 102 deletions(-)

diff --git a/server/src/Support/Reporting/FleetOpsReportSchema.php b/server/src/Support/Reporting/FleetOpsReportSchema.php
index dc83928ff..779452bdb 100644
--- a/server/src/Support/Reporting/FleetOpsReportSchema.php
+++ b/server/src/Support/Reporting/FleetOpsReportSchema.php
@@ -47,12 +47,19 @@ public function registerReportSchema(ReportSchemaRegistry $registry): void
 
     /**
      * Create the Orders table definition.
+     *
+     * Money in orders is stored in the currency's smallest unit (e.g. cents): storefront orders
+     * keep their totals in `meta` (`subtotal`, `delivery_fee`, `tip`, `total`) and each line
+     * item is an entity of the order's payload with `meta.quantity` and `meta.subtotal`.
+     *
+     * Selecting line item columns (Payload Items) returns one row per item, so order-level
+     * sums over item rows repeat each order; count orders with Total Orders (a distinct count).
      */
     protected function createOrdersTable(): Table
     {
-        return Table::make('orders')
+        return $this->softDeletes(Table::make('orders'))
             ->label('Orders')
-            ->description('Delivery and service orders')
+            ->description('Delivery and service orders, with their payload items, tracking, assignment and payment')
             ->category('Operations')
             ->extension('fleet-ops')
             ->excludeColumns(['uuid', 'deleted_at']) // Hide foreign keys and system columns
@@ -95,7 +102,20 @@ protected function createOrdersTable(): Table
 
                 Column::make('type', 'string')
                     ->label('Order Type')
-                    ->description('Type of order service')
+                    ->description('Type of order service, e.g. transport or storefront')
+                    ->filterable()
+                    ->sortable()
+                    ->aggregatable(),
+
+                Column::make('customer_type', 'string')
+                    ->label('Customer Kind')
+                    ->description('Whether the customer is a contact or a vendor')
+                    ->filterable()
+                    ->aggregatable(),
+
+                Column::make('facilitator_type', 'string')
+                    ->label('Facilitator Kind')
+                    ->description('Whether the facilitator is a vendor or an integrated vendor')
                     ->filterable()
                     ->aggregatable(),
 
@@ -106,6 +126,12 @@ protected function createOrdersTable(): Table
                     ->sortable()
                     ->aggregatable(),
 
+                Column::make('dispatched', 'boolean')
+                    ->label('Dispatched')
+                    ->description('Whether the order has been dispatched')
+                    ->filterable()
+                    ->aggregatable(),
+
                 Column::make('dispatched_at', 'datetime')
                     ->label('Dispatched At')
                     ->description('When the order was dispatched')
@@ -113,6 +139,12 @@ protected function createOrdersTable(): Table
                     ->sortable()
                     ->aggregatable(),
 
+                Column::make('started', 'boolean')
+                    ->label('Started')
+                    ->description('Whether the order has been started')
+                    ->filterable()
+                    ->aggregatable(),
+
                 Column::make('started_at', 'datetime')
                     ->label('Started At')
                     ->description('When the order was started')
@@ -120,18 +152,29 @@ protected function createOrdersTable(): Table
                     ->sortable()
                     ->aggregatable(),
 
+                Column::make('time_window_start', 'datetime')
+                    ->label('Time Window Start')
+                    ->description('Earliest time the order may be serviced')
+                    ->filterable()
+                    ->sortable(),
+
+                Column::make('time_window_end', 'datetime')
+                    ->label('Time Window End')
+                    ->description('Latest time the order may be serviced')
+                    ->filterable()
+                    ->sortable(),
+
                 Column::make('distance', 'integer')
-                    ->label('Distance (km)')
-                    ->description('Total distance for the order')
+                    ->label('Distance (m)')
+                    ->description('Route distance for the order in meters')
+                    ->filterable()
                     ->aggregatable()
-                    ->sortable()
-                    ->transformer(function ($value) {
-                        return round($value * 0.621371, 2); // Convert km to miles
-                    }),
+                    ->sortable(),
 
                 Column::make('time', 'integer')
-                    ->label('Duration (minutes)')
-                    ->description('Estimated duration in minutes')
+                    ->label('Duration (s)')
+                    ->description('Estimated route duration in seconds')
+                    ->filterable()
                     ->aggregatable()
                     ->sortable(),
 
@@ -144,6 +187,12 @@ protected function createOrdersTable(): Table
                         return $value ? 'Yes' : 'No';
                     }),
 
+                Column::make('adhoc_distance', 'integer')
+                    ->label('Ad Hoc Distance (m)')
+                    ->description('Radius in meters used to offer an ad hoc order to drivers')
+                    ->filterable()
+                    ->sortable(),
+
                 Column::make('pod_required', 'boolean')
                     ->label('POD Required')
                     ->description('Whether proof of delivery is required')
@@ -153,6 +202,31 @@ protected function createOrdersTable(): Table
                         return $value ? 'Yes' : 'No';
                     }),
 
+                Column::make('pod_method', 'string')
+                    ->label('POD Method')
+                    ->description('Proof of delivery method, e.g. scan, signature or photo')
+                    ->filterable()
+                    ->aggregatable(),
+
+                Column::make('is_route_optimized', 'boolean')
+                    ->label('Route Optimized')
+                    ->description('Whether the route was optimized')
+                    ->filterable()
+                    ->aggregatable(),
+
+                Column::make('orchestrator_priority', 'integer')
+                    ->label('Priority')
+                    ->description('Dispatch priority used by the orchestrator')
+                    ->filterable()
+                    ->sortable()
+                    ->aggregatable(),
+
+                Column::make('notes', 'string')
+                    ->label('Notes')
+                    ->description('Order notes')
+                    ->searchable()
+                    ->filterable(),
+
                 Column::make('created_at', 'datetime')
                     ->label('Created At')
                     ->description('When the order was created')
@@ -168,76 +242,218 @@ protected function createOrdersTable(): Table
 
                 Column::make('meta', 'json')
                     ->label('Metadata')
-                    ->description('Order metadata and custom fields')
+                    ->description('Order metadata and custom fields; read a key with JSON_UNQUOTE(JSON_EXTRACT(meta, \'$.key\'))')
                     ->searchable()
                     ->filterable(),
+
+                // Storefront orders keep their checkout totals in meta, in the currency's smallest unit.
+                $this->expression('storefront', "JSON_UNQUOTE(JSON_EXTRACT(meta, '$.storefront'))", 'string')
+                    ->label('Storefront')
+                    ->description('Name of the storefront the order was placed in')
+                    ->filterable()
+                    ->sortable(),
+
+                $this->expression('order_currency', "JSON_UNQUOTE(JSON_EXTRACT(meta, '$.currency'))", 'string')
+                    ->label('Order Currency')
+                    ->description('Currency of the storefront order totals')
+                    ->filterable()
+                    ->sortable(),
+
+                $this->expression('order_subtotal', $this->jsonAmount('meta', 'subtotal'), 'decimal')
+                    ->label('Order Subtotal (minor units)')
+                    ->description('Storefront order subtotal in the currency\'s smallest unit (e.g. cents)')
+                    ->filterable()
+                    ->sortable(),
+
+                $this->expression('order_delivery_fee', $this->jsonAmount('meta', 'delivery_fee'), 'decimal')
+                    ->label('Delivery Fee (minor units)')
+                    ->description('Storefront delivery fee in the currency\'s smallest unit (e.g. cents)')
+                    ->filterable()
+                    ->sortable(),
+
+                $this->expression('order_tip', $this->jsonAmount('meta', 'tip'), 'decimal')
+                    ->label('Tip (minor units)')
+                    ->description('Storefront tip in the currency\'s smallest unit (e.g. cents)')
+                    ->filterable()
+                    ->sortable(),
+
+                $this->expression('order_total', $this->jsonAmount('meta', 'total'), 'decimal')
+                    ->label('Order Total (minor units)')
+                    ->description('Storefront order total in the currency\'s smallest unit (e.g. cents)')
+                    ->filterable()
+                    ->sortable(),
             ])
             ->computedColumns([
-                Column::count('total_orders', 'id')
+                // Distinct, so the count stays right when payload items are selected too.
+                Column::count('total_orders', 'DISTINCT id')
                     ->label('Total Orders')
-                    ->description('Count of orders'),
+                    ->description('Number of orders'),
+
+                Column::computed('completed_orders', "COUNT(DISTINCT CASE WHEN status = 'completed' THEN id END)", 'integer')
+                    ->label('Completed Orders')
+                    ->description('Number of completed orders'),
+
+                Column::computed('canceled_orders', "COUNT(DISTINCT CASE WHEN status = 'canceled' THEN id END)", 'integer')
+                    ->label('Canceled Orders')
+                    ->description('Number of canceled orders'),
 
                 Column::sum('total_distance', 'distance')
-                    ->label('Total Distance')
+                    ->label('Total Distance (m)')
                     ->description('Sum of all order distances'),
 
                 Column::avg('average_distance', 'distance')
-                    ->label('Average Distance')
+                    ->label('Average Distance (m)')
                     ->description('Average distance per order'),
 
                 Column::sum('total_time', 'time')
-                    ->label('Total Time')
+                    ->label('Total Duration (s)')
                     ->description('Sum of all order durations'),
 
                 Column::avg('average_time', 'time')
-                    ->label('Average Time')
+                    ->label('Average Duration (s)')
                     ->description('Average duration per order'),
 
-                Column::sum('total_transaction_amount', 'amount')
-                    ->label('Total Transaction Amount')
-                    ->description('Sum of all transaction amounts'),
+                Column::sum('total_order_amount', 'order_total')
+                    ->label('Order Total Sum (minor units)')
+                    ->description('Sum of storefront order totals'),
+
+                Column::avg('average_order_amount', 'order_total')
+                    ->label('Average Order Total (minor units)')
+                    ->description('Average storefront order total'),
+
+                Column::sum('total_delivery_fees', 'order_delivery_fee')
+                    ->label('Delivery Fees Sum (minor units)')
+                    ->description('Sum of storefront delivery fees'),
+
+                Column::sum('total_tips', 'order_tip')
+                    ->label('Tips Sum (minor units)')
+                    ->description('Sum of storefront tips'),
 
-                Column::avg('average_transaction_amount', 'amount')
-                    ->label('Average Transaction Amount')
+                Column::sum('total_transaction_amount', 'transaction.amount')
+                    ->label('Transaction Amount Sum (minor units)')
+                    ->description('Sum of the orders\' transaction amounts'),
+
+                Column::avg('average_transaction_amount', 'transaction.amount')
+                    ->label('Average Transaction Amount (minor units)')
                     ->description('Average transaction amount per order'),
 
-                Column::count('orders_with_transactions', 'transaction_uuid')
+                Column::count('orders_with_transactions', 'DISTINCT transaction_uuid')
                     ->label('Orders with Transactions')
-                    ->description('Count of orders that have transactions'),
+                    ->description('Number of orders that have a transaction'),
             ])
             ->relationships([
-                // Auto-join relationships for seamless access
+                Relationship::hasAutoJoin('tracking_number', 'tracking_numbers')
+                    ->label('Tracking')
+                    ->description('The order\'s tracking number and its latest tracking status')
+                    ->localKey('tracking_number_uuid')
+                    ->foreignKey('uuid')
+                    ->columns([
+                        Column::make('tracking_number', 'string')->label('Number')->description('Tracking number'),
+                        Column::make('public_id', 'string')->label('ID')->description('Tracking number record identifier'),
+                        Column::make('region', 'string')->label('Region'),
+                    ])
+                    ->with([
+                        Relationship::hasAutoJoin('status', 'tracking_statuses')
+                            ->label('Tracking Status')
+                            ->localKey('status_uuid')
+                            ->foreignKey('uuid')
+                            ->columns([
+                                Column::make('status', 'string')->label('Status'),
+                                Column::make('code', 'string')->label('Code'),
+                                Column::make('details', 'string')->label('Details'),
+                                Column::make('complete', 'boolean')->label('Complete'),
+                                Column::make('city', 'string')->label('City'),
+                                Column::make('province', 'string')->label('Province'),
+                                Column::make('country', 'string')->label('Country'),
+                                Column::make('created_at', 'datetime')->label('Updated At'),
+                            ]),
+                    ]),
+
+                Relationship::hasAutoJoin('order_config', 'order_configs')
+                    ->label('Order Config')
+                    ->description('The order configuration (order type) the order follows')
+                    ->localKey('order_config_uuid')
+                    ->foreignKey('uuid')
+                    ->columns([
+                        Column::make('name', 'string')->label('Name'),
+                        Column::make('key', 'string')->label('Key'),
+                        Column::make('namespace', 'string')->label('Namespace'),
+                    ]),
+
                 Relationship::hasAutoJoin('payload', 'payloads')
                     ->label('Payload')
                     ->localKey('payload_uuid')
                     ->foreignKey('uuid')
+                    ->columns([
+                        Column::make('public_id', 'string')->label('ID')->description('Payload identifier'),
+                        Column::make('type', 'string')->label('Type'),
+                        Column::make('payment_method', 'string')->label('Payment Method'),
+                        Column::make('cod_amount', 'integer')->label('COD Amount (minor units)')->description('Cash on delivery amount in the currency\'s smallest unit'),
+                        Column::make('cod_currency', 'string')->label('COD Currency'),
+                        Column::make('cod_payment_method', 'string')->label('COD Payment Method'),
+                        Column::make('provider', 'string')->label('Provider'),
+                    ])
                     ->with([
                         Relationship::hasAutoJoin('pickup', 'places')
                             ->label('Pickup')
                             ->localKey('pickup_uuid')
                             ->foreignKey('uuid')
-                            ->columns([
-                                Column::make('name', 'string')->label('Name'),
-                                Column::make('street1', 'string')->label('Street'),
-                                Column::make('street2', 'string')->label('Street 2'),
-                                Column::make('city', 'string')->label('City'),
-                                Column::make('province', 'string')->label('Province'),
-                                Column::make('postal_code', 'string')->label('Postal Code'),
-                                Column::make('country', 'string')->label('Country'),
-                            ]),
+                            ->columns($this->placeColumns()),
 
                         Relationship::hasAutoJoin('dropoff', 'places')
                             ->label('Dropoff')
                             ->localKey('dropoff_uuid')
                             ->foreignKey('uuid')
+                            ->columns($this->placeColumns()),
+
+                        Relationship::hasAutoJoin('return', 'places')
+                            ->label('Return')
+                            ->localKey('return_uuid')
+                            ->foreignKey('uuid')
+                            ->columns($this->placeColumns()),
+
+                        // One row per item: the goods, parcels or storefront products in the order.
+                        $this->softDeletes(Relationship::hasAutoJoin('entities', 'entities'))
+                            ->label('Item')
+                            ->description('Items carried by the order (storefront products, parcels, goods); one row per item')
+                            ->localKey('uuid')
+                            ->foreignKey('payload_uuid')
                             ->columns([
-                                Column::make('name', 'string')->label('Name'),
-                                Column::make('street1', 'string')->label('Street'),
-                                Column::make('street2', 'string')->label('Street 2'),
-                                Column::make('city', 'string')->label('City'),
-                                Column::make('province', 'string')->label('Province'),
-                                Column::make('postal_code', 'string')->label('Postal Code'),
-                                Column::make('country', 'string')->label('Country'),
+                                Column::make('public_id', 'string')->label('ID')->description('Item identifier'),
+                                Column::make('internal_id', 'string')->label('Internal ID')->description('Internal reference; the product ID for storefront items'),
+                                Column::make('name', 'string')->label('Name')->aggregatable(),
+                                Column::make('type', 'string')->label('Type')->aggregatable(),
+                                Column::make('description', 'string')->label('Description'),
+                                Column::make('sku', 'string')->label('SKU')->aggregatable(),
+                                Column::make('currency', 'string')->label('Currency'),
+                                Column::make('price', 'decimal')->label('Price (minor units)')->description('Unit price in the currency\'s smallest unit'),
+                                Column::make('sale_price', 'decimal')->label('Sale Price (minor units)')->description('Unit sale price in the currency\'s smallest unit'),
+                                Column::make('declared_value', 'integer')->label('Declared Value (minor units)'),
+                                Column::make('weight', 'decimal')->label('Weight'),
+                                Column::make('weight_unit', 'string')->label('Weight Unit'),
+                                Column::make('length', 'decimal')->label('Length'),
+                                Column::make('width', 'decimal')->label('Width'),
+                                Column::make('height', 'decimal')->label('Height'),
+                                Column::make('dimensions_unit', 'string')->label('Dimensions Unit'),
+                                Column::make('barcode', 'string')->label('Barcode'),
+                                Column::make('meta', 'json')->label('Metadata'),
+                                Column::make('created_at', 'datetime')->label('Created At'),
+                                $this->expression('product_id', "JSON_UNQUOTE(JSON_EXTRACT(meta, '$.product_id'))", 'string')
+                                    ->label('Product ID')
+                                    ->description('Storefront product the item was ordered as'),
+                                $this->expression('quantity', "COALESCE(CAST(JSON_UNQUOTE(JSON_EXTRACT(meta, '$.quantity')) AS DECIMAL(15,2)), 1)", 'decimal')
+                                    ->label('Quantity')
+                                    ->description('Quantity ordered; 1 when the item records none'),
+                                $this->expression('line_total', $this->jsonAmount('meta', 'subtotal'), 'decimal')
+                                    ->label('Line Total (minor units)')
+                                    ->description('Storefront line subtotal (price x quantity, with variants and add-ons) in the currency\'s smallest unit'),
+                            ])
+                            ->with([
+                                Relationship::hasAutoJoin('destination', 'places')
+                                    ->label('Destination')
+                                    ->localKey('destination_uuid')
+                                    ->foreignKey('uuid')
+                                    ->columns($this->placeColumns()),
                             ]),
                     ]),
 
@@ -246,6 +462,8 @@ protected function createOrdersTable(): Table
                     ->localKey('driver_assigned_uuid')
                     ->foreignKey('uuid')
                     ->columns([
+                        Column::make('public_id', 'string')->label('ID')->description('Driver identifier'),
+                        Column::make('internal_id', 'string')->label('Internal ID'),
                         Column::make('drivers_license_number', 'string')->label('License Number'),
                         Column::make('country', 'string')->label('Country'),
                         Column::make('city', 'string')->label('City'),
@@ -268,6 +486,9 @@ protected function createOrdersTable(): Table
                     ->localKey('vehicle_assigned_uuid')
                     ->foreignKey('uuid')
                     ->columns([
+                        Column::make('public_id', 'string')->label('ID')->description('Vehicle identifier'),
+                        Column::make('internal_id', 'string')->label('Internal ID'),
+                        Column::make('name', 'string')->label('Name'),
                         Column::make('make', 'string')->label('Make'),
                         Column::make('model', 'string')->label('Model'),
                         Column::make('year', 'integer')->label('Year'),
@@ -279,9 +500,27 @@ protected function createOrdersTable(): Table
 
                 Relationship::hasAutoJoin('customer', 'contacts')
                     ->label('Customer')
+                    ->description('The customer when it is a contact')
+                    ->localKey('customer_uuid')
+                    ->foreignKey('uuid')
+                    ->columns([
+                        Column::make('public_id', 'string')->label('ID')->description('Customer identifier'),
+                        Column::make('internal_id', 'string')->label('Internal ID'),
+                        Column::make('name', 'string')->label('Name'),
+                        Column::make('title', 'string')->label('Title'),
+                        Column::make('email', 'string')->label('Email'),
+                        Column::make('phone', 'string')->label('Phone'),
+                        Column::make('type', 'string')->label('Type'),
+                    ]),
+
+                Relationship::hasAutoJoin('customer_vendor', 'vendors')
+                    ->label('Customer Vendor')
+                    ->description('The customer when it is a vendor')
                     ->localKey('customer_uuid')
                     ->foreignKey('uuid')
                     ->columns([
+                        Column::make('public_id', 'string')->label('ID')->description('Vendor identifier'),
+                        Column::make('internal_id', 'string')->label('Internal ID'),
                         Column::make('name', 'string')->label('Name'),
                         Column::make('email', 'string')->label('Email'),
                         Column::make('phone', 'string')->label('Phone'),
@@ -289,16 +528,48 @@ protected function createOrdersTable(): Table
                     ]),
 
                 Relationship::hasAutoJoin('facilitator', 'vendors')
-                    ->label('Faciliator')
+                    ->label('Facilitator')
                     ->localKey('facilitator_uuid')
                     ->foreignKey('uuid')
                     ->columns([
+                        Column::make('public_id', 'string')->label('ID')->description('Facilitator identifier'),
+                        Column::make('internal_id', 'string')->label('Internal ID'),
                         Column::make('name', 'string')->label('Name'),
                         Column::make('email', 'string')->label('Email'),
                         Column::make('phone', 'string')->label('Phone'),
                         Column::make('type', 'string')->label('Type'),
                     ]),
 
+                Relationship::hasAutoJoin('created_by', 'users')
+                    ->label('Created By')
+                    ->localKey('created_by_uuid')
+                    ->foreignKey('uuid')
+                    ->columns([
+                        Column::make('name', 'string')->label('Name'),
+                        Column::make('email', 'string')->label('Email'),
+                    ]),
+
+                Relationship::hasAutoJoin('purchase_rate', 'purchase_rates')
+                    ->label('Purchase Rate')
+                    ->description('The service quote purchased for the order')
+                    ->localKey('purchase_rate_uuid')
+                    ->foreignKey('uuid')
+                    ->columns([
+                        Column::make('public_id', 'string')->label('ID')->description('Purchase rate identifier'),
+                        Column::make('status', 'string')->label('Status'),
+                    ])
+                    ->with([
+                        Relationship::hasAutoJoin('service_quote', 'service_quotes')
+                            ->label('Quote')
+                            ->localKey('service_quote_uuid')
+                            ->foreignKey('uuid')
+                            ->columns([
+                                Column::make('public_id', 'string')->label('ID')->description('Service quote identifier'),
+                                Column::make('amount', 'integer')->label('Amount (minor units)')->description('Quoted delivery price in the currency\'s smallest unit'),
+                                Column::make('currency', 'string')->label('Currency'),
+                            ]),
+                    ]),
+
                 Relationship::hasAutoJoin('transaction', 'transactions')
                     ->label('Transaction')
                     ->localKey('transaction_uuid')
@@ -324,15 +595,35 @@ protected function createOrdersTable(): Table
                             ->filterable()
                             ->aggregatable(),
 
+                        Column::make('payment_method', 'string')
+                            ->label('Payment Method')
+                            ->description('Payment method used, e.g. card or cash')
+                            ->filterable()
+                            ->aggregatable(),
+
                         Column::make('amount', 'integer')
-                            ->label('Amount')
-                            ->description('Transaction amount (in cents)')
+                            ->label('Amount (minor units)')
+                            ->description('Transaction amount in the currency\'s smallest unit (e.g. cents)')
                             ->aggregatable()
-                            ->sortable()
-                            ->transformer(function ($value) {
-                                // Convert cents to dollars with 2 decimal places
-                                return number_format($value / 100, 2);
-                            }),
+                            ->sortable(),
+
+                        Column::make('fee_amount', 'integer')
+                            ->label('Fee Amount (minor units)')
+                            ->description('Gateway fee in the currency\'s smallest unit')
+                            ->aggregatable()
+                            ->sortable(),
+
+                        Column::make('tax_amount', 'integer')
+                            ->label('Tax Amount (minor units)')
+                            ->description('Tax in the currency\'s smallest unit')
+                            ->aggregatable()
+                            ->sortable(),
+
+                        Column::make('net_amount', 'integer')
+                            ->label('Net Amount (minor units)')
+                            ->description('Amount after fees in the currency\'s smallest unit')
+                            ->aggregatable()
+                            ->sortable(),
 
                         Column::make('currency', 'string')
                             ->label('Currency')
@@ -369,6 +660,12 @@ protected function createOrdersTable(): Table
                                 return $labels[$value] ?? ucfirst($value);
                             }),
 
+                        Column::make('settlement_status', 'string')
+                            ->label('Settlement Status')
+                            ->description('Whether the transaction has settled')
+                            ->filterable()
+                            ->aggregatable(),
+
                         Column::make('created_at', 'datetime')
                             ->label('Transaction Date')
                             ->description('When the transaction was created')
@@ -378,13 +675,31 @@ protected function createOrdersTable(): Table
                     ])
                     ->with([
                         // Nested relationship for transaction items
-                        Relationship::hasAutoJoin('items', 'transaction_items')
+                        $this->softDeletes(Relationship::hasAutoJoin('items', 'transaction_items'))
                             ->label('Transaction Items')
                             ->localKey('uuid')
                             ->foreignKey('transaction_uuid')
                             ->columns([
-                                Column::make('amount', 'string')
-                                    ->label('Item Amount')
+                                Column::make('description', 'string')
+                                    ->label('Item Description')
+                                    ->description('Line item description')
+                                    ->searchable()
+                                    ->filterable(),
+
+                                Column::make('quantity', 'integer')
+                                    ->label('Item Quantity')
+                                    ->description('Line item quantity')
+                                    ->aggregatable()
+                                    ->sortable(),
+
+                                Column::make('unit_price', 'integer')
+                                    ->label('Item Unit Price (minor units)')
+                                    ->description('Line item unit price')
+                                    ->aggregatable()
+                                    ->sortable(),
+
+                                Column::make('amount', 'integer')
+                                    ->label('Item Amount (minor units)')
                                     ->description('Line item amount')
                                     ->aggregatable()
                                     ->sortable(),
@@ -416,7 +731,7 @@ protected function createOrdersTable(): Table
      */
     protected function createDriversTable(): Table
     {
-        return Table::make('drivers')
+        return $this->softDeletes(Table::make('drivers'))
             ->label('Drivers')
             ->description('Fleet drivers and personnel')
             ->category('Personnel')
@@ -431,24 +746,22 @@ protected function createDriversTable(): Table
                     ->filterable()
                     ->sortable(),
 
-                Column::make('name', 'string')
-                    ->label('Name')
-                    ->description('Driver full name')
+                Column::make('internal_id', 'string')
+                    ->label('Internal ID')
+                    ->description('Internal driver reference')
                     ->searchable()
                     ->filterable()
                     ->sortable(),
 
-                Column::make('email', 'string')
-                    ->label('Email')
-                    ->description('Driver email address')
+                Column::make('drivers_license_number', 'string')
+                    ->label('License Number')
+                    ->description('Driver license number')
                     ->searchable()
-                    ->filterable()
-                    ->sortable(),
+                    ->filterable(),
 
-                Column::make('phone', 'string')
-                    ->label('Phone')
-                    ->description('Driver phone number')
-                    ->searchable()
+                Column::make('license_expiry', 'date')
+                    ->label('License Expiry')
+                    ->description('When the driver license expires')
                     ->filterable()
                     ->sortable(),
 
@@ -477,24 +790,45 @@ protected function createDriversTable(): Table
                         return $value ? 'Yes' : 'No';
                     }),
 
+                Column::make('city', 'string')
+                    ->label('City')
+                    ->filterable()
+                    ->aggregatable(),
+
+                Column::make('country', 'string')
+                    ->label('Country')
+                    ->filterable()
+                    ->aggregatable(),
+
                 Column::make('created_at', 'datetime')
                     ->label('Hired Date')
-                    ->description('When the driver was hired')
+                    ->description('When the driver was added')
                     ->filterable()
                     ->sortable()
                     ->aggregatable(),
             ])
             ->computedColumns([
-                Column::count('total_drivers', 'id')
+                Column::count('total_drivers', 'DISTINCT id')
                     ->label('Total Drivers')
                     ->description('Count of drivers'),
             ])
             ->relationships([
-                Relationship::hasAutoJoin('current_vehicle', 'vehicles')
+                Relationship::hasAutoJoin('user', 'users')
+                    ->label('Driver')
+                    ->localKey('user_uuid')
+                    ->foreignKey('uuid')
+                    ->columns([
+                        Column::make('name', 'string')->label('Name'),
+                        Column::make('email', 'string')->label('Email'),
+                        Column::make('phone', 'string')->label('Phone'),
+                    ]),
+
+                Relationship::hasAutoJoin('vehicle', 'vehicles')
                     ->label('Vehicle')
-                    ->localKey('current_vehicle_uuid')
+                    ->localKey('vehicle_uuid')
                     ->foreignKey('uuid')
                     ->columns([
+                        Column::make('public_id', 'string')->label('Vehicle ID'),
                         Column::make('make', 'string')->label('Vehicle Make'),
                         Column::make('model', 'string')->label('Vehicle Model'),
                         Column::make('plate_number', 'string')->label('Plate Number'),
@@ -507,7 +841,7 @@ protected function createDriversTable(): Table
      */
     protected function createVehiclesTable(): Table
     {
-        return Table::make('vehicles')
+        return $this->softDeletes(Table::make('vehicles'))
             ->label('Vehicles')
             ->description('Fleet vehicles and assets')
             ->category('Fleet')
@@ -522,6 +856,20 @@ protected function createVehiclesTable(): Table
                     ->filterable()
                     ->sortable(),
 
+                Column::make('internal_id', 'string')
+                    ->label('Internal ID')
+                    ->description('Internal vehicle reference')
+                    ->searchable()
+                    ->filterable()
+                    ->sortable(),
+
+                Column::make('name', 'string')
+                    ->label('Name')
+                    ->description('Vehicle name')
+                    ->searchable()
+                    ->filterable()
+                    ->sortable(),
+
                 Column::make('make', 'string')
                     ->label('Make')
                     ->description('Vehicle manufacturer')
@@ -583,19 +931,30 @@ protected function createVehiclesTable(): Table
                     ->aggregatable(),
             ])
             ->computedColumns([
-                Column::count('total_vehicles', 'id')
+                Column::count('total_vehicles', 'DISTINCT id')
                     ->label('Total Vehicles')
                     ->description('Count of vehicles'),
             ])
             ->relationships([
-                Relationship::hasAutoJoin('current_driver', 'drivers')
+                // A driver points at the vehicle they drive (drivers.vehicle_uuid).
+                $this->softDeletes(Relationship::hasAutoJoin('driver', 'drivers'))
                     ->label('Driver')
-                    ->localKey('current_driver_uuid')
-                    ->foreignKey('uuid')
+                    ->localKey('uuid')
+                    ->foreignKey('vehicle_uuid')
                     ->columns([
-                        Column::make('name', 'string')->label('Driver Name'),
-                        Column::make('email', 'string')->label('Driver Email'),
-                        Column::make('phone', 'string')->label('Driver Phone'),
+                        Column::make('public_id', 'string')->label('Driver ID'),
+                        Column::make('status', 'string')->label('Driver Status'),
+                    ])
+                    ->with([
+                        Relationship::hasAutoJoin('user', 'users')
+                            ->label('Driver')
+                            ->localKey('user_uuid')
+                            ->foreignKey('uuid')
+                            ->columns([
+                                Column::make('name', 'string')->label('Name'),
+                                Column::make('email', 'string')->label('Email'),
+                                Column::make('phone', 'string')->label('Phone'),
+                            ]),
                     ]),
             ]);
     }
@@ -605,7 +964,7 @@ protected function createVehiclesTable(): Table
      */
     protected function createAssetsTable(): Table
     {
-        return Table::make('assets')
+        return $this->softDeletes(Table::make('assets'))
             ->label('Trailers and Assets')
             ->description('Independently managed fleet assets; Trailer rows use asset_class trailer')
             ->category('Fleet')
@@ -640,7 +999,7 @@ protected function createAssetsTable(): Table
      */
     protected function createPlacesTable(): Table
     {
-        return Table::make('places')
+        return $this->softDeletes(Table::make('places'))
             ->label('Places')
             ->description('Locations and addresses')
             ->category('Geography')
@@ -706,7 +1065,7 @@ protected function createPlacesTable(): Table
      */
     protected function createContactsTable(): Table
     {
-        return Table::make('contacts')
+        return $this->softDeletes(Table::make('contacts'))
             ->label('Contacts')
             ->description('Customer and vendor contacts')
             ->category('CRM')
@@ -762,7 +1121,7 @@ protected function createContactsTable(): Table
      */
     protected function createVendorsTable(): Table
     {
-        return Table::make('vendors')
+        return $this->softDeletes(Table::make('vendors'))
             ->label('Vendors')
             ->description('Service providers and vendors')
             ->category('CRM')
@@ -818,7 +1177,7 @@ protected function createVendorsTable(): Table
      */
     protected function createFuelReportsTable(): Table
     {
-        return Table::make('fuel_reports')
+        return $this->softDeletes(Table::make('fuel_reports'))
             ->label('Fuel Reports')
             ->description('Vehicle fuel consumption reports')
             ->category('Operations')
@@ -834,17 +1193,23 @@ protected function createFuelReportsTable(): Table
                     ->sortable(),
 
                 Column::make('volume', 'decimal')
-                    ->label('Volume (L)')
-                    ->description('Fuel volume in liters')
+                    ->label('Volume')
+                    ->description('Fuel volume, in the report\'s metric unit')
                     ->aggregatable()
                     ->sortable(),
 
-                Column::make('odometer_reading', 'integer')
+                Column::make('metric_unit', 'string')
+                    ->label('Volume Unit')
+                    ->description('Unit of the fuel volume')
+                    ->filterable()
+                    ->aggregatable(),
+
+                Column::make('odometer', 'integer')
                     ->label('Odometer Reading')
                     ->description('Vehicle odometer reading')
                     ->sortable(),
 
-                Column::make('cost', 'decimal')
+                Column::make('amount', 'decimal')
                     ->label('Cost')
                     ->description('Fuel cost amount')
                     ->aggregatable()
@@ -856,15 +1221,26 @@ protected function createFuelReportsTable(): Table
                     ->filterable()
                     ->aggregatable(),
 
-                Column::make('report_date', 'date')
+                Column::make('status', 'string')
+                    ->label('Status')
+                    ->filterable()
+                    ->aggregatable(),
+
+                Column::make('report', 'string')
+                    ->label('Report')
+                    ->description('Report notes')
+                    ->searchable()
+                    ->filterable(),
+
+                Column::make('created_at', 'datetime')
                     ->label('Report Date')
-                    ->description('Date of fuel report')
+                    ->description('When the fuel report was recorded')
                     ->filterable()
                     ->sortable()
                     ->aggregatable(),
             ])
             ->computedColumns([
-                Column::sum('total_fuel_cost', 'cost')
+                Column::sum('total_fuel_cost', 'amount')
                     ->label('Total Fuel Cost')
                     ->description('Sum of all fuel costs'),
 
@@ -872,7 +1248,7 @@ protected function createFuelReportsTable(): Table
                     ->label('Total Fuel Volume')
                     ->description('Sum of all fuel volumes'),
 
-                Column::avg('average_fuel_cost', 'cost')
+                Column::avg('average_fuel_cost', 'amount')
                     ->label('Average Fuel Cost')
                     ->description('Average fuel cost per report'),
             ])
@@ -882,6 +1258,7 @@ protected function createFuelReportsTable(): Table
                     ->localKey('vehicle_uuid')
                     ->foreignKey('uuid')
                     ->columns([
+                        Column::make('public_id', 'string')->label('Vehicle ID'),
                         Column::make('make', 'string')->label('Vehicle Make'),
                         Column::make('model', 'string')->label('Vehicle Model'),
                         Column::make('plate_number', 'string')->label('Plate Number'),
@@ -892,8 +1269,17 @@ protected function createFuelReportsTable(): Table
                     ->localKey('driver_uuid')
                     ->foreignKey('uuid')
                     ->columns([
-                        Column::make('name', 'string')->label('Driver Name'),
-                        Column::make('email', 'string')->label('Driver Email'),
+                        Column::make('public_id', 'string')->label('Driver ID'),
+                    ])
+                    ->with([
+                        Relationship::hasAutoJoin('user', 'users')
+                            ->label('Driver')
+                            ->localKey('user_uuid')
+                            ->foreignKey('uuid')
+                            ->columns([
+                                Column::make('name', 'string')->label('Name'),
+                                Column::make('email', 'string')->label('Email'),
+                            ]),
                     ]),
             ]);
     }
@@ -903,7 +1289,7 @@ protected function createFuelReportsTable(): Table
      */
     protected function createWorkOrdersTable(): Table
     {
-        return Table::make('work_orders')
+        return $this->softDeletes(Table::make('work_orders'))
             ->label('Work Orders')
             ->description('Maintenance work orders, assignments, budgets, and lifecycle status')
             ->category('Maintenance')
@@ -952,7 +1338,7 @@ protected function createWorkOrdersTable(): Table
      */
     protected function createMaintenancesTable(): Table
     {
-        return Table::make('maintenances')
+        return $this->softDeletes(Table::make('maintenances'))
             ->label('Maintenance History')
             ->description('Completed and scheduled maintenance records with labor, parts, tax, and total cost')
             ->category('Maintenance')
@@ -1013,7 +1399,7 @@ protected function createMaintenancesTable(): Table
      */
     protected function createInspectionSubmissionsTable(): Table
     {
-        return Table::make('inspection_submissions')
+        return $this->softDeletes(Table::make('inspection_submissions'))
             ->label('Inspections')
             ->description('DVIR and inspection submissions, pass/fail status, and linked maintenance follow-up')
             ->category('Maintenance')
@@ -1070,4 +1456,59 @@ protected function createInspectionSubmissionsTable(): Table
                     ]),
             ]);
     }
+
+    /**
+     * Columns reported for a place (pickup, dropoff, return or item destination).
+     */
+    protected function placeColumns(): array
+    {
+        return [
+            Column::make('public_id', 'string')->label('ID'),
+            Column::make('name', 'string')->label('Name'),
+            Column::make('street1', 'string')->label('Street'),
+            Column::make('street2', 'string')->label('Street 2'),
+            Column::make('neighborhood', 'string')->label('Neighborhood'),
+            Column::make('district', 'string')->label('District'),
+            Column::make('city', 'string')->label('City'),
+            Column::make('province', 'string')->label('Province'),
+            Column::make('postal_code', 'string')->label('Postal Code'),
+            Column::make('country', 'string')->label('Country'),
+            Column::make('latitude', 'decimal')->label('Latitude'),
+            Column::make('longitude', 'decimal')->label('Longitude'),
+        ];
+    }
+
+    /**
+     * SQL reading a numeric amount stored under a key of a JSON column.
+     */
+    protected function jsonAmount(string $column, string $key): string
+    {
+        return "CAST(JSON_UNQUOTE(JSON_EXTRACT({$column}, '$.{$key}')) AS DECIMAL(15,2))";
+    }
+
+    /**
+     * A row-level expression column, such as a value read out of a JSON column.
+     *
+     * Core API releases before expression columns only know computed columns; there the
+     * column is still declared, it just cannot be selected on its own.
+     */
+    protected function expression(string $name, string $sql, string $type): Column
+    {
+        // One line: whichever branch runs depends on the installed Core API, not on the test.
+        return method_exists(Column::class, 'expression') ? Column::expression($name, $sql, $type) : Column::computed($name, $sql, $type);
+    }
+
+    /**
+     * Leave soft-deleted rows out of a table or joined relationship, on Core API releases that support it.
+     *
+     * @template T of Table|Relationship
+     *
+     * @param T $schema
+     *
+     * @return T
+     */
+    protected function softDeletes(Table|Relationship $schema): Table|Relationship
+    {
+        return method_exists($schema, 'softDeletes') ? $schema->softDeletes() : $schema;
+    }
 }
diff --git a/server/tests/ReportSchemaContractsTest.php b/server/tests/ReportSchemaContractsTest.php
index b1465b71c..124d9b0a7 100644
--- a/server/tests/ReportSchemaContractsTest.php
+++ b/server/tests/ReportSchemaContractsTest.php
@@ -119,9 +119,10 @@ function fleetOpsReportColumnFlag(Column $column, string $flag): bool
 
 function fleetOpsReportColumnAggregate(Column $column): ?string
 {
+    // The stand-in Column stores the aggregate name; the Core API one only flags it (a bool).
     $aggregate = fleetOpsReportProperty($column, 'aggregate');
 
-    if ($aggregate) {
+    if (is_string($aggregate) && $aggregate !== '') {
         return $aggregate;
     }
 
@@ -242,9 +243,10 @@ function fleetOpsReportRelationship(Table|Relationship $container, string $name)
         ->and(fleetOpsReportTableName(fleetOpsReportRelationship($orders, 'transaction')))->toBe('transactions');
 
     expect(fleetOpsReportTableMeta($tables['drivers'], 'category'))->toBe('Personnel')
-        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($tables['drivers'], 'current_vehicle')))->toBe('vehicles')
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($tables['drivers'], 'vehicle')))->toBe('vehicles')
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($tables['drivers'], 'user')))->toBe('users')
         ->and(fleetOpsReportTableMeta($tables['vehicles'], 'category'))->toBe('Fleet')
-        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($tables['vehicles'], 'current_driver')))->toBe('drivers')
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($tables['vehicles'], 'driver')))->toBe('drivers')
         ->and(fleetOpsReportTableMeta($tables['assets'], 'label'))->toBe('Trailers and Assets')
         ->and(fleetOpsReportTableMeta($tables['assets'], 'category'))->toBe('Fleet')
         ->and(fleetOpsReportColumnFlag(fleetOpsReportColumn($tables['assets'], 'asset_class'), 'filterable'))->toBeTrue()
@@ -265,7 +267,7 @@ function fleetOpsReportRelationship(Table|Relationship $container, string $name)
         ->and(fleetOpsReportTableName(fleetOpsReportRelationship($tables['inspection_submissions'], 'work_order')))->toBe('work_orders');
 });
 
-test('fleetops report schema transformers normalize labels booleans distances and money', function () {
+test('fleetops report schema transformers normalize labels and booleans', function () {
     $registry = new ReportSchemaRegistry();
 
     (new FleetOpsReportSchema())->registerReportSchema($registry);
@@ -278,12 +280,121 @@ function fleetOpsReportRelationship(Table|Relationship $container, string $name)
 
     expect(fleetOpsReportTransform(fleetOpsReportColumn($orders, 'status'), 'driver_assigned'))->toBe('Driver Assigned')
         ->and(fleetOpsReportTransform(fleetOpsReportColumn($orders, 'status'), 'custom_status'))->toBe('Custom_status')
-        ->and(fleetOpsReportTransform(fleetOpsReportColumn($orders, 'distance'), 10))->toBe(6.21)
         ->and(fleetOpsReportTransform(fleetOpsReportColumn($orders, 'adhoc'), true))->toBe('Yes')
         ->and(fleetOpsReportTransform(fleetOpsReportColumn($orders, 'pod_required'), false))->toBe('No')
         ->and(fleetOpsReportTransform(fleetOpsReportColumn($drivers, 'status'), 'suspended'))->toBe('Suspended')
         ->and(fleetOpsReportTransform(fleetOpsReportColumn($drivers, 'online'), false))->toBe('No')
         ->and(fleetOpsReportTransform(fleetOpsReportColumn($vehicles, 'status'), 'out_of_service'))->toBe('Out of Service')
-        ->and(fleetOpsReportTransform(fleetOpsReportColumn($transaction, 'amount'), 12345))->toBe('123.45')
         ->and(fleetOpsReportTransform(fleetOpsReportColumn($transaction, 'status'), 'refunded'))->toBe('Refunded');
 });
+
+function fleetOpsReportColumnNames(Table|Relationship $container): array
+{
+    return array_map(fn (Column $column) => fleetOpsReportSchemaName($column), fleetOpsReportColumns($container));
+}
+
+function fleetOpsReportComputation(Column $column): ?string
+{
+    return fleetOpsReportCallOrProperty($column, 'getComputation', 'computation');
+}
+
+test('fleetops order report schema exposes identifiers tracking items and storefront totals', function () {
+    $registry = new ReportSchemaRegistry();
+
+    (new FleetOpsReportSchema())->registerReportSchema($registry);
+
+    $orders = fleetOpsReportTables($registry)['orders'];
+
+    // Order identifiers and the operational columns reports filter and group on.
+    expect(fleetOpsReportColumnNames($orders))->toContain(
+        'public_id',
+        'internal_id',
+        'status',
+        'type',
+        'scheduled_at',
+        'dispatched_at',
+        'pod_method',
+        'notes',
+        'created_at',
+        'order_total',
+        'order_subtotal',
+        'order_delivery_fee',
+        'order_tip',
+        'order_currency',
+        'storefront',
+    );
+
+    // Storefront totals are read out of the order meta, in the currency's smallest unit.
+    expect(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'order_total')))->toBe("CAST(JSON_UNQUOTE(JSON_EXTRACT(meta, '$.total')) AS DECIMAL(15,2))")
+        ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'storefront')))->toBe("JSON_UNQUOTE(JSON_EXTRACT(meta, '$.storefront'))")
+        ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'total_orders')))->toBe('COUNT(DISTINCT id)')
+        ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'completed_orders')))->toBe("COUNT(DISTINCT CASE WHEN status = 'completed' THEN id END)")
+        ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'total_order_amount')))->toBe('SUM(order_total)')
+        ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'total_transaction_amount')))->toBe('SUM(transaction.amount)');
+
+    $tracking = fleetOpsReportRelationship($orders, 'tracking_number');
+    expect(fleetOpsReportTableName($tracking))->toBe('tracking_numbers')
+        ->and(fleetOpsReportColumnNames($tracking))->toContain('tracking_number', 'public_id')
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($tracking, 'status')))->toBe('tracking_statuses')
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($orders, 'order_config')))->toBe('order_configs')
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($orders, 'customer_vendor')))->toBe('vendors')
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($orders, 'created_by')))->toBe('users')
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship(fleetOpsReportRelationship($orders, 'purchase_rate'), 'service_quote')))->toBe('service_quotes');
+
+    // Payload items: one row per entity, with the storefront quantity and line total from meta.
+    $payload = fleetOpsReportRelationship($orders, 'payload');
+    expect(fleetOpsReportColumnNames($payload))->toContain('public_id', 'type', 'cod_amount')
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($payload, 'return')))->toBe('places');
+
+    $items = fleetOpsReportRelationship($payload, 'entities');
+    expect(fleetOpsReportTableName($items))->toBe('entities')
+        ->and(fleetOpsReportCallOrProperty($items, 'getLocalKey', 'localKey'))->toBe('uuid')
+        ->and(fleetOpsReportCallOrProperty($items, 'getForeignKey', 'foreignKey'))->toBe('payload_uuid')
+        ->and(fleetOpsReportColumnNames($items))->toContain('public_id', 'internal_id', 'name', 'sku', 'price', 'product_id', 'quantity', 'line_total')
+        ->and(fleetOpsReportComputation(fleetOpsReportColumn($items, 'quantity')))->toBe("COALESCE(CAST(JSON_UNQUOTE(JSON_EXTRACT(meta, '$.quantity')) AS DECIMAL(15,2)), 1)")
+        ->and(fleetOpsReportComputation(fleetOpsReportColumn($items, 'line_total')))->toBe("CAST(JSON_UNQUOTE(JSON_EXTRACT(meta, '$.subtotal')) AS DECIMAL(15,2))")
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship($items, 'destination')))->toBe('places');
+
+    // Relationship identifiers
+    expect(fleetOpsReportColumnNames(fleetOpsReportRelationship($orders, 'driver_assigned')))->toContain('public_id')
+        ->and(fleetOpsReportColumnNames(fleetOpsReportRelationship($orders, 'vehicle_assigned')))->toContain('public_id')
+        ->and(fleetOpsReportColumnNames(fleetOpsReportRelationship($orders, 'customer')))->toContain('public_id')
+        ->and(fleetOpsReportColumnNames(fleetOpsReportRelationship($orders, 'facilitator')))->toContain('public_id');
+});
+
+test('fleetops report schema uses the columns the fuel report table actually has', function () {
+    $registry = new ReportSchemaRegistry();
+
+    (new FleetOpsReportSchema())->registerReportSchema($registry);
+
+    $tables = fleetOpsReportTables($registry);
+    $fuel   = $tables['fuel_reports'];
+
+    expect(fleetOpsReportColumnNames($fuel))->toContain('amount', 'odometer', 'metric_unit', 'created_at')
+        ->not->toContain('cost', 'odometer_reading', 'report_date')
+        ->and(fleetOpsReportComputation(fleetOpsReportColumn($fuel, 'total_fuel_cost')))->toBe('SUM(amount)')
+        ->and(fleetOpsReportTableName(fleetOpsReportRelationship(fleetOpsReportRelationship($fuel, 'driver'), 'user')))->toBe('users')
+        ->and(fleetOpsReportColumnNames($tables['drivers']))->not->toContain('name', 'email', 'phone');
+});
+
+test('fleetops report schema leaves soft deleted rows out where the core api supports it', function () {
+    $registry = new ReportSchemaRegistry();
+
+    (new FleetOpsReportSchema())->registerReportSchema($registry);
+
+    $orders = fleetOpsReportTables($registry)['orders'];
+    $items  = fleetOpsReportRelationship(fleetOpsReportRelationship($orders, 'payload'), 'entities');
+
+    if (!method_exists($orders, 'usesSoftDeletes')) {
+        // Older Core API: the schema still registers, without soft-delete filtering.
+        expect($orders)->toBeInstanceOf(Table::class);
+
+        return;
+    }
+
+    expect($orders->usesSoftDeletes())->toBeTrue()
+        ->and($items->usesSoftDeletes())->toBeTrue()
+        ->and(fleetOpsReportRelationship($orders, 'customer')->usesSoftDeletes())->toBeFalse()
+        ->and(fleetOpsReportColumn($orders, 'order_total')->isExpression())->toBeTrue()
+        ->and(fleetOpsReportColumn($orders, 'total_orders')->isAggregate())->toBeTrue();
+});

From 88a802d60e0222299d7b1c8a0a62dc5b1e79ad3e Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Fri, 25 Sep 2026 12:44:09 +0800
Subject: [PATCH 04/24] fix(reporting): drop order and item columns that
 assumed a meta shape

meta has no fixed structure: users, integrations and extensions each put
their own keys there, so a column such as "Order Total" read from
meta.total is empty or wrong for most orders. Remove the columns built on
meta keys (storefront, order currency/subtotal/delivery fee/tip/total, the
order total/average/fee/tip summaries, and item product ID, quantity and
line total). meta stays selectable as raw JSON on orders and items, and a
key is read with a computed column, e.g.
CAST(JSON_UNQUOTE(JSON_EXTRACT(payload.entities.meta, '$.quantity')) AS DECIMAL(15,2)).
---
 .../Reporting/FleetOpsReportSchema.php        | 93 ++-----------------
 server/tests/ReportSchemaContractsTest.php    | 30 +++---
 2 files changed, 20 insertions(+), 103 deletions(-)

diff --git a/server/src/Support/Reporting/FleetOpsReportSchema.php b/server/src/Support/Reporting/FleetOpsReportSchema.php
index 779452bdb..d483de39f 100644
--- a/server/src/Support/Reporting/FleetOpsReportSchema.php
+++ b/server/src/Support/Reporting/FleetOpsReportSchema.php
@@ -48,9 +48,10 @@ public function registerReportSchema(ReportSchemaRegistry $registry): void
     /**
      * Create the Orders table definition.
      *
-     * Money in orders is stored in the currency's smallest unit (e.g. cents): storefront orders
-     * keep their totals in `meta` (`subtotal`, `delivery_fee`, `tip`, `total`) and each line
-     * item is an entity of the order's payload with `meta.quantity` and `meta.subtotal`.
+     * Money is stored in the currency's smallest unit (e.g. cents). `meta` has no fixed shape
+     * (it holds whatever users, integrations and extensions put there), so no column assumes a
+     * key in it; read one with a computed column, e.g.
+     * `CAST(JSON_UNQUOTE(JSON_EXTRACT(meta, '$.total')) AS DECIMAL(15,2))`.
      *
      * Selecting line item columns (Payload Items) returns one row per item, so order-level
      * sums over item rows repeat each order; count orders with Total Orders (a distinct count).
@@ -242,46 +243,9 @@ protected function createOrdersTable(): Table
 
                 Column::make('meta', 'json')
                     ->label('Metadata')
-                    ->description('Order metadata and custom fields; read a key with JSON_UNQUOTE(JSON_EXTRACT(meta, \'$.key\'))')
+                    ->description('Order metadata and custom fields; its keys vary by order, so read one with a computed column, e.g. JSON_UNQUOTE(JSON_EXTRACT(meta, \'$.key\'))')
                     ->searchable()
                     ->filterable(),
-
-                // Storefront orders keep their checkout totals in meta, in the currency's smallest unit.
-                $this->expression('storefront', "JSON_UNQUOTE(JSON_EXTRACT(meta, '$.storefront'))", 'string')
-                    ->label('Storefront')
-                    ->description('Name of the storefront the order was placed in')
-                    ->filterable()
-                    ->sortable(),
-
-                $this->expression('order_currency', "JSON_UNQUOTE(JSON_EXTRACT(meta, '$.currency'))", 'string')
-                    ->label('Order Currency')
-                    ->description('Currency of the storefront order totals')
-                    ->filterable()
-                    ->sortable(),
-
-                $this->expression('order_subtotal', $this->jsonAmount('meta', 'subtotal'), 'decimal')
-                    ->label('Order Subtotal (minor units)')
-                    ->description('Storefront order subtotal in the currency\'s smallest unit (e.g. cents)')
-                    ->filterable()
-                    ->sortable(),
-
-                $this->expression('order_delivery_fee', $this->jsonAmount('meta', 'delivery_fee'), 'decimal')
-                    ->label('Delivery Fee (minor units)')
-                    ->description('Storefront delivery fee in the currency\'s smallest unit (e.g. cents)')
-                    ->filterable()
-                    ->sortable(),
-
-                $this->expression('order_tip', $this->jsonAmount('meta', 'tip'), 'decimal')
-                    ->label('Tip (minor units)')
-                    ->description('Storefront tip in the currency\'s smallest unit (e.g. cents)')
-                    ->filterable()
-                    ->sortable(),
-
-                $this->expression('order_total', $this->jsonAmount('meta', 'total'), 'decimal')
-                    ->label('Order Total (minor units)')
-                    ->description('Storefront order total in the currency\'s smallest unit (e.g. cents)')
-                    ->filterable()
-                    ->sortable(),
             ])
             ->computedColumns([
                 // Distinct, so the count stays right when payload items are selected too.
@@ -313,22 +277,6 @@ protected function createOrdersTable(): Table
                     ->label('Average Duration (s)')
                     ->description('Average duration per order'),
 
-                Column::sum('total_order_amount', 'order_total')
-                    ->label('Order Total Sum (minor units)')
-                    ->description('Sum of storefront order totals'),
-
-                Column::avg('average_order_amount', 'order_total')
-                    ->label('Average Order Total (minor units)')
-                    ->description('Average storefront order total'),
-
-                Column::sum('total_delivery_fees', 'order_delivery_fee')
-                    ->label('Delivery Fees Sum (minor units)')
-                    ->description('Sum of storefront delivery fees'),
-
-                Column::sum('total_tips', 'order_tip')
-                    ->label('Tips Sum (minor units)')
-                    ->description('Sum of storefront tips'),
-
                 Column::sum('total_transaction_amount', 'transaction.amount')
                     ->label('Transaction Amount Sum (minor units)')
                     ->description('Sum of the orders\' transaction amounts'),
@@ -436,17 +384,8 @@ protected function createOrdersTable(): Table
                                 Column::make('height', 'decimal')->label('Height'),
                                 Column::make('dimensions_unit', 'string')->label('Dimensions Unit'),
                                 Column::make('barcode', 'string')->label('Barcode'),
-                                Column::make('meta', 'json')->label('Metadata'),
+                                Column::make('meta', 'json')->label('Metadata')->description('Item metadata; read a key with a computed column, e.g. JSON_EXTRACT(payload.entities.meta, \'$.quantity\')'),
                                 Column::make('created_at', 'datetime')->label('Created At'),
-                                $this->expression('product_id', "JSON_UNQUOTE(JSON_EXTRACT(meta, '$.product_id'))", 'string')
-                                    ->label('Product ID')
-                                    ->description('Storefront product the item was ordered as'),
-                                $this->expression('quantity', "COALESCE(CAST(JSON_UNQUOTE(JSON_EXTRACT(meta, '$.quantity')) AS DECIMAL(15,2)), 1)", 'decimal')
-                                    ->label('Quantity')
-                                    ->description('Quantity ordered; 1 when the item records none'),
-                                $this->expression('line_total', $this->jsonAmount('meta', 'subtotal'), 'decimal')
-                                    ->label('Line Total (minor units)')
-                                    ->description('Storefront line subtotal (price x quantity, with variants and add-ons) in the currency\'s smallest unit'),
                             ])
                             ->with([
                                 Relationship::hasAutoJoin('destination', 'places')
@@ -1478,26 +1417,6 @@ protected function placeColumns(): array
         ];
     }
 
-    /**
-     * SQL reading a numeric amount stored under a key of a JSON column.
-     */
-    protected function jsonAmount(string $column, string $key): string
-    {
-        return "CAST(JSON_UNQUOTE(JSON_EXTRACT({$column}, '$.{$key}')) AS DECIMAL(15,2))";
-    }
-
-    /**
-     * A row-level expression column, such as a value read out of a JSON column.
-     *
-     * Core API releases before expression columns only know computed columns; there the
-     * column is still declared, it just cannot be selected on its own.
-     */
-    protected function expression(string $name, string $sql, string $type): Column
-    {
-        // One line: whichever branch runs depends on the installed Core API, not on the test.
-        return method_exists(Column::class, 'expression') ? Column::expression($name, $sql, $type) : Column::computed($name, $sql, $type);
-    }
-
     /**
      * Leave soft-deleted rows out of a table or joined relationship, on Core API releases that support it.
      *
diff --git a/server/tests/ReportSchemaContractsTest.php b/server/tests/ReportSchemaContractsTest.php
index 124d9b0a7..cbf3838d1 100644
--- a/server/tests/ReportSchemaContractsTest.php
+++ b/server/tests/ReportSchemaContractsTest.php
@@ -298,7 +298,7 @@ function fleetOpsReportComputation(Column $column): ?string
     return fleetOpsReportCallOrProperty($column, 'getComputation', 'computation');
 }
 
-test('fleetops order report schema exposes identifiers tracking items and storefront totals', function () {
+test('fleetops order report schema exposes identifiers tracking and items without assuming a meta shape', function () {
     $registry = new ReportSchemaRegistry();
 
     (new FleetOpsReportSchema())->registerReportSchema($registry);
@@ -316,22 +316,22 @@ function fleetOpsReportComputation(Column $column): ?string
         'pod_method',
         'notes',
         'created_at',
-        'order_total',
-        'order_subtotal',
-        'order_delivery_fee',
-        'order_tip',
-        'order_currency',
-        'storefront',
+        'meta',
     );
 
-    // Storefront totals are read out of the order meta, in the currency's smallest unit.
-    expect(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'order_total')))->toBe("CAST(JSON_UNQUOTE(JSON_EXTRACT(meta, '$.total')) AS DECIMAL(15,2))")
-        ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'storefront')))->toBe("JSON_UNQUOTE(JSON_EXTRACT(meta, '$.storefront'))")
-        ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'total_orders')))->toBe('COUNT(DISTINCT id)')
+    expect(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'total_orders')))->toBe('COUNT(DISTINCT id)')
         ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'completed_orders')))->toBe("COUNT(DISTINCT CASE WHEN status = 'completed' THEN id END)")
-        ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'total_order_amount')))->toBe('SUM(order_total)')
         ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'total_transaction_amount')))->toBe('SUM(transaction.amount)');
 
+    // meta has no fixed shape, so no declared column may read a key out of it; users read
+    // keys with computed columns instead.
+    $computations = array_map(fn (Column $column) => (string) fleetOpsReportComputation($column), [
+        ...fleetOpsReportColumns($orders),
+        ...fleetOpsReportComputedColumns($orders),
+        ...fleetOpsReportColumnsFromRelationships(fleetOpsReportRelationships($orders)),
+    ]);
+    expect(array_filter($computations, fn (string $computation) => str_contains($computation, 'JSON_') || str_contains($computation, 'meta')))->toBe([]);
+
     $tracking = fleetOpsReportRelationship($orders, 'tracking_number');
     expect(fleetOpsReportTableName($tracking))->toBe('tracking_numbers')
         ->and(fleetOpsReportColumnNames($tracking))->toContain('tracking_number', 'public_id')
@@ -350,9 +350,8 @@ function fleetOpsReportComputation(Column $column): ?string
     expect(fleetOpsReportTableName($items))->toBe('entities')
         ->and(fleetOpsReportCallOrProperty($items, 'getLocalKey', 'localKey'))->toBe('uuid')
         ->and(fleetOpsReportCallOrProperty($items, 'getForeignKey', 'foreignKey'))->toBe('payload_uuid')
-        ->and(fleetOpsReportColumnNames($items))->toContain('public_id', 'internal_id', 'name', 'sku', 'price', 'product_id', 'quantity', 'line_total')
-        ->and(fleetOpsReportComputation(fleetOpsReportColumn($items, 'quantity')))->toBe("COALESCE(CAST(JSON_UNQUOTE(JSON_EXTRACT(meta, '$.quantity')) AS DECIMAL(15,2)), 1)")
-        ->and(fleetOpsReportComputation(fleetOpsReportColumn($items, 'line_total')))->toBe("CAST(JSON_UNQUOTE(JSON_EXTRACT(meta, '$.subtotal')) AS DECIMAL(15,2))")
+        ->and(fleetOpsReportColumnNames($items))->toContain('public_id', 'internal_id', 'name', 'sku', 'price', 'sale_price', 'meta')
+        ->and(fleetOpsReportColumnNames($items))->not->toContain('quantity', 'line_total', 'product_id')
         ->and(fleetOpsReportTableName(fleetOpsReportRelationship($items, 'destination')))->toBe('places');
 
     // Relationship identifiers
@@ -395,6 +394,5 @@ function fleetOpsReportComputation(Column $column): ?string
     expect($orders->usesSoftDeletes())->toBeTrue()
         ->and($items->usesSoftDeletes())->toBeTrue()
         ->and(fleetOpsReportRelationship($orders, 'customer')->usesSoftDeletes())->toBeFalse()
-        ->and(fleetOpsReportColumn($orders, 'order_total')->isExpression())->toBeTrue()
         ->and(fleetOpsReportColumn($orders, 'total_orders')->isAggregate())->toBeTrue();
 });

From ebd62cf1cd830974f432b0e1639d69e320d3ea0e Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Fri, 25 Sep 2026 12:58:31 +0800
Subject: [PATCH 05/24] fix(reporting): drop table-name prefixes from column
 labels

A table's own columns no longer repeat the table's name: Orders "Order ID"
and "Order Type" are "ID" and "Type", and every table's public ID is "ID".
Relationship labels are tuned for core-api's whole-name prefixes:
"Tracking Status" (not "Tracking Status Status"), "Service Quote Amount",
"Transaction Gateway ID", "Transaction Item Quantity", "Inspection Form Name",
"Target Vehicle ID".
---
 .../Reporting/FleetOpsReportSchema.php        | 52 +++++++++----------
 server/tests/ReportSchemaContractsTest.php    |  5 ++
 2 files changed, 31 insertions(+), 26 deletions(-)

diff --git a/server/src/Support/Reporting/FleetOpsReportSchema.php b/server/src/Support/Reporting/FleetOpsReportSchema.php
index d483de39f..2b4ff8acd 100644
--- a/server/src/Support/Reporting/FleetOpsReportSchema.php
+++ b/server/src/Support/Reporting/FleetOpsReportSchema.php
@@ -68,7 +68,7 @@ protected function createOrdersTable(): Table
             ->cacheTtl(3600)
             ->columns([
                 Column::make('public_id', 'string')
-                    ->label('Order ID')
+                    ->label('ID')
                     ->description('Public order identifier')
                     ->searchable()
                     ->filterable()
@@ -102,7 +102,7 @@ protected function createOrdersTable(): Table
                     }),
 
                 Column::make('type', 'string')
-                    ->label('Order Type')
+                    ->label('Type')
                     ->description('Type of order service, e.g. transport or storefront')
                     ->filterable()
                     ->sortable()
@@ -306,7 +306,7 @@ protected function createOrdersTable(): Table
                             ->localKey('status_uuid')
                             ->foreignKey('uuid')
                             ->columns([
-                                Column::make('status', 'string')->label('Status'),
+                                Column::make('status', 'string')->label('Tracking Status'),
                                 Column::make('code', 'string')->label('Code'),
                                 Column::make('details', 'string')->label('Details'),
                                 Column::make('complete', 'boolean')->label('Complete'),
@@ -499,7 +499,7 @@ protected function createOrdersTable(): Table
                     ])
                     ->with([
                         Relationship::hasAutoJoin('service_quote', 'service_quotes')
-                            ->label('Quote')
+                            ->label('Service Quote')
                             ->localKey('service_quote_uuid')
                             ->foreignKey('uuid')
                             ->columns([
@@ -522,7 +522,7 @@ protected function createOrdersTable(): Table
                             ->sortable(),
 
                         Column::make('gateway_transaction_id', 'string')
-                            ->label('Gateway Transaction ID')
+                            ->label('Gateway ID')
                             ->description('Transaction ID from payment gateway')
                             ->searchable()
                             ->filterable()
@@ -615,47 +615,47 @@ protected function createOrdersTable(): Table
                     ->with([
                         // Nested relationship for transaction items
                         $this->softDeletes(Relationship::hasAutoJoin('items', 'transaction_items'))
-                            ->label('Transaction Items')
+                            ->label('Transaction Item')
                             ->localKey('uuid')
                             ->foreignKey('transaction_uuid')
                             ->columns([
                                 Column::make('description', 'string')
-                                    ->label('Item Description')
+                                    ->label('Description')
                                     ->description('Line item description')
                                     ->searchable()
                                     ->filterable(),
 
                                 Column::make('quantity', 'integer')
-                                    ->label('Item Quantity')
+                                    ->label('Quantity')
                                     ->description('Line item quantity')
                                     ->aggregatable()
                                     ->sortable(),
 
                                 Column::make('unit_price', 'integer')
-                                    ->label('Item Unit Price (minor units)')
+                                    ->label('Unit Price (minor units)')
                                     ->description('Line item unit price')
                                     ->aggregatable()
                                     ->sortable(),
 
                                 Column::make('amount', 'integer')
-                                    ->label('Item Amount (minor units)')
+                                    ->label('Amount (minor units)')
                                     ->description('Line item amount')
                                     ->aggregatable()
                                     ->sortable(),
 
                                 Column::make('currency', 'string')
-                                    ->label('Item Currency')
+                                    ->label('Currency')
                                     ->description('Line item currency code')
                                     ->filterable(),
 
                                 Column::make('details', 'string')
-                                    ->label('Item Details')
+                                    ->label('Details')
                                     ->description('Detailed description of the line item')
                                     ->searchable()
                                     ->filterable(),
 
                                 Column::make('code', 'string')
-                                    ->label('Item Code')
+                                    ->label('Code')
                                     ->description('Item or SKU code')
                                     ->searchable()
                                     ->filterable()
@@ -679,7 +679,7 @@ protected function createDriversTable(): Table
             ->maxRows(10000)
             ->columns([
                 Column::make('public_id', 'string')
-                    ->label('Driver ID')
+                    ->label('ID')
                     ->description('Public driver identifier')
                     ->searchable()
                     ->filterable()
@@ -789,7 +789,7 @@ protected function createVehiclesTable(): Table
             ->maxRows(10000)
             ->columns([
                 Column::make('public_id', 'string')
-                    ->label('Vehicle ID')
+                    ->label('ID')
                     ->description('Public vehicle identifier')
                     ->searchable()
                     ->filterable()
@@ -911,7 +911,7 @@ protected function createAssetsTable(): Table
             ->excludeColumns(['uuid', 'company_uuid', 'deleted_at', 'meta', 'attributes'])
             ->maxRows(10000)
             ->columns([
-                Column::make('public_id', 'string')->label('Asset ID')->searchable()->filterable()->sortable(),
+                Column::make('public_id', 'string')->label('ID')->searchable()->filterable()->sortable(),
                 Column::make('asset_class', 'string')->label('Asset Class')->filterable()->aggregatable(),
                 Column::make('name', 'string')->label('Name')->searchable()->filterable()->sortable(),
                 Column::make('code', 'string')->label('Code')->searchable()->filterable()->sortable(),
@@ -947,7 +947,7 @@ protected function createPlacesTable(): Table
             ->maxRows(100000)
             ->columns([
                 Column::make('public_id', 'string')
-                    ->label('Place ID')
+                    ->label('ID')
                     ->description('Public place identifier')
                     ->searchable()
                     ->filterable()
@@ -1013,7 +1013,7 @@ protected function createContactsTable(): Table
             ->maxRows(50000)
             ->columns([
                 Column::make('public_id', 'string')
-                    ->label('Contact ID')
+                    ->label('ID')
                     ->description('Public contact identifier')
                     ->searchable()
                     ->filterable()
@@ -1069,7 +1069,7 @@ protected function createVendorsTable(): Table
             ->maxRows(10000)
             ->columns([
                 Column::make('public_id', 'string')
-                    ->label('Vendor ID')
+                    ->label('ID')
                     ->description('Public vendor identifier')
                     ->searchable()
                     ->filterable()
@@ -1125,7 +1125,7 @@ protected function createFuelReportsTable(): Table
             ->maxRows(100000)
             ->columns([
                 Column::make('public_id', 'string')
-                    ->label('Report ID')
+                    ->label('ID')
                     ->description('Public fuel report identifier')
                     ->searchable()
                     ->filterable()
@@ -1236,7 +1236,7 @@ protected function createWorkOrdersTable(): Table
             ->excludeColumns(['uuid', 'deleted_at', 'meta', 'checklist', 'cost_breakdown'])
             ->maxRows(100000)
             ->columns([
-                Column::make('public_id', 'string')->label('Work Order ID')->searchable()->filterable()->sortable(),
+                Column::make('public_id', 'string')->label('ID')->searchable()->filterable()->sortable(),
                 Column::make('code', 'string')->label('Code')->searchable()->filterable()->sortable(),
                 Column::make('subject', 'string')->label('Subject')->searchable()->filterable()->sortable(),
                 Column::make('status', 'string')->label('Status')->filterable()->sortable()->aggregatable(),
@@ -1263,7 +1263,7 @@ protected function createWorkOrdersTable(): Table
                     ->localKey('target_uuid')
                     ->foreignKey('uuid')
                     ->columns([
-                        Column::make('public_id', 'string')->label('Vehicle ID'),
+                        Column::make('public_id', 'string')->label('ID'),
                         Column::make('plate_number', 'string')->label('Plate Number'),
                         Column::make('make', 'string')->label('Make'),
                         Column::make('model', 'string')->label('Model'),
@@ -1285,7 +1285,7 @@ protected function createMaintenancesTable(): Table
             ->excludeColumns(['uuid', 'deleted_at', 'meta', 'line_items', 'attachments'])
             ->maxRows(100000)
             ->columns([
-                Column::make('public_id', 'string')->label('Maintenance ID')->searchable()->filterable()->sortable(),
+                Column::make('public_id', 'string')->label('ID')->searchable()->filterable()->sortable(),
                 Column::make('type', 'string')->label('Type')->filterable()->sortable()->aggregatable(),
                 Column::make('status', 'string')->label('Status')->filterable()->sortable()->aggregatable(),
                 Column::make('priority', 'string')->label('Priority')->filterable()->sortable()->aggregatable(),
@@ -1346,7 +1346,7 @@ protected function createInspectionSubmissionsTable(): Table
             ->excludeColumns(['uuid', 'deleted_at', 'meta', 'location', 'signature', 'attachments'])
             ->maxRows(100000)
             ->columns([
-                Column::make('public_id', 'string')->label('Inspection ID')->searchable()->filterable()->sortable(),
+                Column::make('public_id', 'string')->label('ID')->searchable()->filterable()->sortable(),
                 Column::make('type', 'string')->label('Type')->filterable()->sortable()->aggregatable(),
                 Column::make('status', 'string')->label('Status')->filterable()->sortable()->aggregatable(),
                 Column::make('result', 'string')->label('Result')->filterable()->sortable()->aggregatable(),
@@ -1371,8 +1371,8 @@ protected function createInspectionSubmissionsTable(): Table
                     ->localKey('inspection_form_uuid')
                     ->foreignKey('uuid')
                     ->columns([
-                        Column::make('name', 'string')->label('Form Name'),
-                        Column::make('type', 'string')->label('Form Type'),
+                        Column::make('name', 'string')->label('Name'),
+                        Column::make('type', 'string')->label('Type'),
                     ]),
                 Relationship::hasAutoJoin('vehicle', 'vehicles')
                     ->label('Vehicle')
diff --git a/server/tests/ReportSchemaContractsTest.php b/server/tests/ReportSchemaContractsTest.php
index cbf3838d1..afdae61aa 100644
--- a/server/tests/ReportSchemaContractsTest.php
+++ b/server/tests/ReportSchemaContractsTest.php
@@ -319,6 +319,11 @@ function fleetOpsReportComputation(Column $column): ?string
         'meta',
     );
 
+    // Columns of the table itself are not prefixed with the table's name ("Order ID" → "ID").
+    $label = fn (Column $column) => fleetOpsReportCallOrProperty($column, 'getLabel', 'label');
+    expect($label(fleetOpsReportColumn($orders, 'public_id')))->toBe('ID')
+        ->and($label(fleetOpsReportColumn($orders, 'type')))->toBe('Type');
+
     expect(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'total_orders')))->toBe('COUNT(DISTINCT id)')
         ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'completed_orders')))->toBe("COUNT(DISTINCT CASE WHEN status = 'completed' THEN id END)")
         ->and(fleetOpsReportComputation(fleetOpsReportColumn($orders, 'total_transaction_amount')))->toBe('SUM(transaction.amount)');

From 65e46e869ae60cd2db804e826357ce986128e5c4 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Fri, 25 Sep 2026 15:29:57 +0800
Subject: [PATCH 06/24] feat(dashboard): clean default layout and live-map
 cards in the Live Fleet widget

Default dashboard
- Fleet-ops widgets declare an `order` so the shared default dashboard lays
  out cleanly beside other extensions' widgets: the KPI row (Radar, Active
  Orders, Drivers Online, with ledger's Revenue), ledger's KPI row, the Live
  Fleet Map at full width, then Revenue Trend, Top Drivers and Maintenance
  Overview a third of the width each.
- Earnings and Avg Order Value are no longer defaults (still addable).

Live Fleet widget
- Its marker popups and hover tooltips are now the live map's own cards: the
  driver and vehicle cards moved into shared Map::MarkerCard::Driver/Vehicle
  components (the live map rendered each twice, inline), and the widget uses
  them too.
- /fleet-ops/analytics/live-fleet adds each marker's `card`, the same index
  resource the live map's endpoints return (status, driver, trailers,
  devices, order, speed, heading, location labels).
---
 addon/components/map/leaflet-live-map.hbs     | 246 +-----------------
 addon/components/map/marker-card/driver.hbs   |  57 ++++
 addon/components/map/marker-card/driver.js    |   3 +
 addon/components/map/marker-card/vehicle.hbs  |  78 ++++++
 addon/components/map/marker-card/vehicle.js   |   3 +
 addon/components/widget/live-fleet.hbs        |  48 +---
 addon/extension.js                            |  27 +-
 app/components/map/marker-card/driver.js      |   1 +
 app/components/map/marker-card/vehicle.js     |   1 +
 server/src/Support/Analytics/LiveFleet.php    |  20 +-
 server/tests/AnalyticsRoutesTest.php          |  31 ++-
 .../Unit/Support/Analytics/LiveFleetTest.php  |   6 +
 .../components/map/marker-card/driver-test.js |  35 +++
 .../map/marker-card/vehicle-test.js           |  47 ++++
 tests/unit/extension-test.js                  |  36 +++
 15 files changed, 347 insertions(+), 292 deletions(-)
 create mode 100644 addon/components/map/marker-card/driver.hbs
 create mode 100644 addon/components/map/marker-card/driver.js
 create mode 100644 addon/components/map/marker-card/vehicle.hbs
 create mode 100644 addon/components/map/marker-card/vehicle.js
 create mode 100644 app/components/map/marker-card/driver.js
 create mode 100644 app/components/map/marker-card/vehicle.js
 create mode 100644 tests/integration/components/map/marker-card/driver-test.js
 create mode 100644 tests/integration/components/map/marker-card/vehicle-test.js

diff --git a/addon/components/map/leaflet-live-map.hbs b/addon/components/map/leaflet-live-map.hbs
index a82b064b5..920918b44 100644
--- a/addon/components/map/leaflet-live-map.hbs
+++ b/addon/components/map/leaflet-live-map.hbs
@@ -83,108 +83,10 @@
                         as |marker|
                     >
                         <marker.popup @maxWidth="500" @minWidth="225">
-                            <div class="w-[280px] max-w-[calc(100vw-2rem)] rounded-lg bg-gray-900 shadow-lg p-1.5 text-white">
-                                <div class="flex items-center gap-1.5 text-xs font-semibold mb-1.5">
-                                    <span class="inline-block w-2 h-2 rounded-full {{if driver.online 'bg-green-400' 'bg-red-500'}}"></span>
-                                    <span>{{driver.name}}</span>
-                                    <div
-                                        class="status-badge
-                                            {{if driver.status (dasherize driver.status) 'default'}}-status-badge status-badge-{{if driver.status (dasherize driver.status) 'default'}}
-                                            shadow-none ml-auto"
-                                    >
-                                        <span class="rounded-full text-[9px] px-1.5 py-0.5">{{n-a driver.meta.status_label (smart-humanize driver.status)}}</span>
-                                    </div>
-                                </div>
-                                <div class="grid grid-cols-2 gap-1">
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">ID</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.public_id driver.id}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Phone</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.phone}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Vehicle</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.vehicle_name}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Email</div>
-                                        <div class="text-[11px] text-white leading-tight truncate min-w-0 w-full">{{n-a driver.email}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Order</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.meta.current_order_reference}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Speed</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.meta.speed_label}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Heading</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.meta.heading_label}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Location</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a
-                                                driver.meta.location_coordinates
-                                                (point-coordinates driver.location)
-                                            }}</div>
-                                    </div>
-                                </div>
-                            </div>
+                            <Map::MarkerCard::Driver @driver={{driver}} />
                         </marker.popup>
                         <marker.tooltip @permanent={{false}} @sticky={{true}}>
-                            <div class="w-[280px] max-w-[calc(100vw-2rem)]">
-                                <div class="flex items-center gap-1.5 text-xs font-semibold mb-1.5">
-                                    <span class="inline-block w-2 h-2 rounded-full {{if driver.online 'bg-green-400' 'bg-red-500'}}"></span>
-                                    <span>{{driver.name}}</span>
-                                    <div
-                                        class="status-badge
-                                            {{if driver.status (dasherize driver.status) 'default'}}-status-badge status-badge-{{if driver.status (dasherize driver.status) 'default'}}
-                                            shadow-none ml-auto"
-                                    >
-                                        <span class="rounded-full text-[9px] px-1.5 py-0.5">{{n-a driver.meta.status_label (smart-humanize driver.status)}}</span>
-                                    </div>
-                                </div>
-                                <div class="grid grid-cols-2 gap-1">
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">ID</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.public_id driver.id}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Phone</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.phone}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Vehicle</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.vehicle_name}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Email</div>
-                                        <div class="text-[11px] text-white leading-tight truncate min-w-0 w-full">{{n-a driver.email}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Order</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.meta.current_order_reference}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Speed</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.meta.speed_label}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Heading</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a driver.meta.heading_label}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Location</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a
-                                                driver.meta.location_coordinates
-                                                (point-coordinates driver.location)
-                                            }}</div>
-                                    </div>
-                                </div>
-                            </div>
+                            <Map::MarkerCard::Driver @driver={{driver}} @variant="tooltip" />
                         </marker.tooltip>
                     </layers.tracking-marker>
                 {{/each}}
@@ -202,150 +104,10 @@
                         as |marker|
                     >
                         <marker.popup @permanent={{false}} @sticky={{true}}>
-                            <div class="w-[280px] max-w-[calc(100vw-2rem)] rounded-lg bg-gray-900 shadow-lg p-1.5 text-white">
-                                <div class="flex items-center gap-1.5 text-xs font-semibold mb-1.5">
-                                    <span class="inline-block w-2 h-2 rounded-full {{if vehicle.online 'bg-green-400' 'bg-red-500'}}"></span>
-                                    <span>{{vehicle.displayName}}</span>
-                                    <div
-                                        class="status-badge
-                                            {{if vehicle.status (dasherize vehicle.status) 'default'}}-status-badge status-badge-{{if vehicle.status (dasherize vehicle.status) 'default'}}
-                                            shadow-none ml-auto"
-                                    >
-                                        <span class="rounded-full text-[9px] px-1.5 py-0.5">{{n-a vehicle.meta.status_label}}</span>
-                                    </div>
-                                </div>
-                                <div class="grid grid-cols-2 gap-1">
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Vehicle #</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a
-                                                vehicle.internal_id
-                                                vehicle.public_id
-                                                vehicle.plate_number
-                                                vehicle.serial_number
-                                                vehicle.vin
-                                            }}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Driver</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a vehicle.driver_name}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">{{t "resource.trailers"}}</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">
-                                            {{#each vehicle.trailers as |trailer|}}
-                                                <div class="flex items-center gap-1 min-w-0">
-                                                    <span class="inline-block w-1.5 h-1.5 rounded-full shrink-0 {{if trailer.online 'bg-green-400' 'bg-gray-500'}}"></span>
-                                                    <span class="truncate">{{or trailer.displayName trailer.display_name trailer.name trailer.public_id}}</span>
-                                                </div>
-                                            {{else}}
-                                                -
-                                            {{/each}}
-                                        </div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">{{t "resource.devices"}}</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">
-                                            {{#each vehicle.devices as |device|}}
-                                                <div class="flex items-center gap-1 min-w-0">
-                                                    <span class="inline-block w-1.5 h-1.5 rounded-full shrink-0 {{if device.online 'bg-green-400' 'bg-gray-500'}}"></span>
-                                                    <span class="truncate">{{or device.displayName device.display_name device.name device.device_id device.public_id}}</span>
-                                                </div>
-                                            {{else}}
-                                                -
-                                            {{/each}}
-                                        </div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Order</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a vehicle.meta.current_order_reference}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Speed</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a vehicle.meta.speed_label}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Heading</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a vehicle.meta.heading_label}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Location</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a vehicle.meta.location_coordinates}}</div>
-                                    </div>
-                                </div>
-                            </div>
+                            <Map::MarkerCard::Vehicle @vehicle={{vehicle}} />
                         </marker.popup>
                         <marker.tooltip @permanent={{false}} @sticky={{true}}>
-                            <div class="w-[280px] max-w-[calc(100vw-2rem)]">
-                                <div class="flex items-center gap-1.5 text-xs font-semibold mb-1.5">
-                                    <span class="inline-block w-2 h-2 rounded-full {{if vehicle.online 'bg-green-400' 'bg-red-500'}}"></span>
-                                    <span>{{vehicle.displayName}}</span>
-                                    <div
-                                        class="status-badge
-                                            {{if vehicle.status (dasherize vehicle.status) 'default'}}-status-badge status-badge-{{if vehicle.status (dasherize vehicle.status) 'default'}}
-                                            shadow-none ml-auto"
-                                    >
-                                        <span class="rounded-full text-[9px] px-1.5 py-0.5">{{n-a vehicle.meta.status_label}}</span>
-                                    </div>
-                                </div>
-                                <div class="grid grid-cols-2 gap-1">
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Vehicle #</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a
-                                                vehicle.internal_id
-                                                vehicle.public_id
-                                                vehicle.plate_number
-                                                vehicle.serial_number
-                                                vehicle.vin
-                                            }}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Driver</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a vehicle.driver_name}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">{{t "resource.trailers"}}</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">
-                                            {{#each vehicle.trailers as |trailer|}}
-                                                <div class="flex items-center gap-1 min-w-0">
-                                                    <span class="inline-block w-1.5 h-1.5 rounded-full shrink-0 {{if trailer.online 'bg-green-400' 'bg-gray-500'}}"></span>
-                                                    <span class="truncate">{{or trailer.displayName trailer.display_name trailer.name trailer.public_id}}</span>
-                                                </div>
-                                            {{else}}
-                                                -
-                                            {{/each}}
-                                        </div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">{{t "resource.devices"}}</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">
-                                            {{#each vehicle.devices as |device|}}
-                                                <div class="flex items-center gap-1 min-w-0">
-                                                    <span class="inline-block w-1.5 h-1.5 rounded-full shrink-0 {{if device.online 'bg-green-400' 'bg-gray-500'}}"></span>
-                                                    <span class="truncate">{{or device.displayName device.display_name device.name device.device_id device.public_id}}</span>
-                                                </div>
-                                            {{else}}
-                                                -
-                                            {{/each}}
-                                        </div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Order</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a vehicle.meta.current_order_reference}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Speed</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a vehicle.meta.speed_label}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Heading</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a vehicle.meta.heading_label}}</div>
-                                    </div>
-                                    <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
-                                        <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Location</div>
-                                        <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a vehicle.meta.location_coordinates}}</div>
-                                    </div>
-                                </div>
-                            </div>
+                            <Map::MarkerCard::Vehicle @vehicle={{vehicle}} @variant="tooltip" />
                         </marker.tooltip>
                     </layers.tracking-marker>
                 {{/each}}
diff --git a/addon/components/map/marker-card/driver.hbs b/addon/components/map/marker-card/driver.hbs
new file mode 100644
index 000000000..ff15f7e6d
--- /dev/null
+++ b/addon/components/map/marker-card/driver.hbs
@@ -0,0 +1,57 @@
+{{!
+    The driver card the fleet-ops live map shows in a marker's popup and hover tooltip.
+    Shared with the dashboard's Live Fleet widget so both look the same. @driver is a driver
+    model or its index resource payload (the same attributes, plain JSON).
+    @variant: "popup" (default, a dark panel) or "tooltip" (inherits the tooltip's panel).
+}}
+<div class="w-[280px] max-w-[calc(100vw-2rem)] {{unless (eq @variant 'tooltip') 'rounded-lg bg-gray-900 shadow-lg p-1.5 text-white'}}" ...attributes>
+    <div class="flex items-center gap-1.5 text-xs font-semibold mb-1.5">
+        <span class="inline-block w-2 h-2 rounded-full {{if @driver.online 'bg-green-400' 'bg-red-500'}}"></span>
+        <span>{{@driver.name}}</span>
+        <div
+            class="status-badge
+                {{if @driver.status (dasherize @driver.status) 'default'}}-status-badge status-badge-{{if @driver.status (dasherize @driver.status) 'default'}}
+                shadow-none ml-auto"
+        >
+            <span class="rounded-full text-[9px] px-1.5 py-0.5">{{n-a @driver.meta.status_label (smart-humanize @driver.status)}}</span>
+        </div>
+    </div>
+    <div class="grid grid-cols-2 gap-1">
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">ID</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @driver.public_id @driver.id}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Phone</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @driver.phone}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Vehicle</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @driver.vehicle_name}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Email</div>
+            <div class="text-[11px] text-white leading-tight truncate min-w-0 w-full">{{n-a @driver.email}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Order</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @driver.meta.current_order_reference}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Speed</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @driver.meta.speed_label}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Heading</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @driver.meta.heading_label}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Location</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a
+                    @driver.meta.location_coordinates
+                    (point-coordinates @driver.location)
+                }}</div>
+        </div>
+    </div>
+</div>
+
diff --git a/addon/components/map/marker-card/driver.js b/addon/components/map/marker-card/driver.js
new file mode 100644
index 000000000..fa8505356
--- /dev/null
+++ b/addon/components/map/marker-card/driver.js
@@ -0,0 +1,3 @@
+import templateOnly from '@ember/component/template-only';
+
+export default templateOnly();
diff --git a/addon/components/map/marker-card/vehicle.hbs b/addon/components/map/marker-card/vehicle.hbs
new file mode 100644
index 000000000..a6f5544cc
--- /dev/null
+++ b/addon/components/map/marker-card/vehicle.hbs
@@ -0,0 +1,78 @@
+{{!
+    The vehicle card the fleet-ops live map shows in a marker's popup and hover tooltip.
+    Shared with the dashboard's Live Fleet widget so both look the same. @vehicle is a vehicle
+    model or its index resource payload (the same attributes, plain JSON).
+    @variant: "popup" (default, a dark panel) or "tooltip" (inherits the tooltip's panel).
+}}
+<div class="w-[280px] max-w-[calc(100vw-2rem)] {{unless (eq @variant 'tooltip') 'rounded-lg bg-gray-900 shadow-lg p-1.5 text-white'}}" ...attributes>
+    <div class="flex items-center gap-1.5 text-xs font-semibold mb-1.5">
+        <span class="inline-block w-2 h-2 rounded-full {{if @vehicle.online 'bg-green-400' 'bg-red-500'}}"></span>
+        <span>{{or @vehicle.displayName @vehicle.display_name @vehicle.name}}</span>
+        <div
+            class="status-badge
+                {{if @vehicle.status (dasherize @vehicle.status) 'default'}}-status-badge status-badge-{{if @vehicle.status (dasherize @vehicle.status) 'default'}}
+                shadow-none ml-auto"
+        >
+            <span class="rounded-full text-[9px] px-1.5 py-0.5">{{n-a @vehicle.meta.status_label}}</span>
+        </div>
+    </div>
+    <div class="grid grid-cols-2 gap-1">
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Vehicle #</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a
+                    @vehicle.internal_id
+                    @vehicle.public_id
+                    @vehicle.plate_number
+                    @vehicle.serial_number
+                    @vehicle.vin
+                }}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Driver</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @vehicle.driver_name}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">{{t "resource.trailers"}}</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">
+                {{#each @vehicle.trailers as |trailer|}}
+                    <div class="flex items-center gap-1 min-w-0">
+                        <span class="inline-block w-1.5 h-1.5 rounded-full shrink-0 {{if trailer.online 'bg-green-400' 'bg-gray-500'}}"></span>
+                        <span class="truncate">{{or trailer.displayName trailer.display_name trailer.name trailer.public_id}}</span>
+                    </div>
+                {{else}}
+                    -
+                {{/each}}
+            </div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">{{t "resource.devices"}}</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">
+                {{#each @vehicle.devices as |device|}}
+                    <div class="flex items-center gap-1 min-w-0">
+                        <span class="inline-block w-1.5 h-1.5 rounded-full shrink-0 {{if device.online 'bg-green-400' 'bg-gray-500'}}"></span>
+                        <span class="truncate">{{or device.displayName device.display_name device.name device.device_id device.public_id}}</span>
+                    </div>
+                {{else}}
+                    -
+                {{/each}}
+            </div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Order</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @vehicle.meta.current_order_reference}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Speed</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @vehicle.meta.speed_label}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Heading</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @vehicle.meta.heading_label}}</div>
+        </div>
+        <div class="rounded bg-gray-900 shadow-md px-1.5 py-1 min-w-0">
+            <div class="text-[9px] font-semibold uppercase text-gray-400 leading-none">Location</div>
+            <div class="text-[11px] text-white leading-tight whitespace-normal break-words">{{n-a @vehicle.meta.location_coordinates}}</div>
+        </div>
+    </div>
+</div>
+
diff --git a/addon/components/map/marker-card/vehicle.js b/addon/components/map/marker-card/vehicle.js
new file mode 100644
index 000000000..fa8505356
--- /dev/null
+++ b/addon/components/map/marker-card/vehicle.js
@@ -0,0 +1,3 @@
+import templateOnly from '@ember/component/template-only';
+
+export default templateOnly();
diff --git a/addon/components/widget/live-fleet.hbs b/addon/components/widget/live-fleet.hbs
index 82965680b..01ef5974d 100644
--- a/addon/components/widget/live-fleet.hbs
+++ b/addon/components/widget/live-fleet.hbs
@@ -28,7 +28,8 @@
 
                 {{#if this.load.isIdle}}
                     {{! Drivers — fleetops' rotating tracking-marker matches the operational
-                         live-map's look and animates on heading changes. }}
+                         live-map's look and animates on heading changes. The popup and tooltip
+                         are the live map's own cards, fed from each marker's index-resource card. }}
                     {{#each this.drivers as |driver|}}
                         <layers.tracking-marker
                             @id={{driver.uuid}}
@@ -39,28 +40,11 @@
                             @draggable={{false}}
                             as |marker|
                         >
-                            <marker.popup @maxWidth="240" @minWidth="180">
-                                <div class="flex flex-row gap-2">
-                                    <div class="w-9 h-9 flex-shrink-0">
-                                        <img src={{or driver.avatar_url driver.vehicle_avatar}} alt={{driver.name}} class="rounded-md w-9 h-9 object-cover shadow-sm" />
-                                    </div>
-                                    <div class="flex-1 min-w-0">
-                                        <div class="text-xs font-semibold truncate">{{or driver.name "Driver"}}</div>
-                                        <div class="text-[11px]">
-                                            {{#if driver.current_order_uuid}}
-                                                <span class="text-blue-500"><FaIcon @icon="bolt" class="mr-1" />On order</span>
-                                            {{else if driver.online}}
-                                                <span class="text-green-500"><FaIcon @icon="circle" @size="2xs" class="mr-1" />Online</span>
-                                            {{else}}
-                                                <span class="text-gray-400"><FaIcon @icon="circle" @size="2xs" class="mr-1" />Offline</span>
-                                            {{/if}}
-                                        </div>
-                                        <div class="text-[10px] text-gray-400 mt-0.5 truncate">{{driver.lat}}, {{driver.lng}}</div>
-                                    </div>
-                                </div>
+                            <marker.popup @maxWidth="500" @minWidth="225">
+                                <Map::MarkerCard::Driver @driver={{or driver.card driver}} />
                             </marker.popup>
                             <marker.tooltip @permanent={{false}} @sticky={{true}} @direction="top">
-                                <div class="text-[11px] font-semibold">{{or driver.name "Driver"}}</div>
+                                <Map::MarkerCard::Driver @driver={{or driver.card driver}} @variant="tooltip" />
                             </marker.tooltip>
                         </layers.tracking-marker>
                     {{/each}}
@@ -77,27 +61,11 @@
                             @draggable={{false}}
                             as |marker|
                         >
-                            <marker.popup @maxWidth="240" @minWidth="180">
-                                <div class="flex flex-row gap-2">
-                                    <div class="w-9 h-9 flex-shrink-0">
-                                        <img src={{or vehicle.photo_url vehicle.avatar_url}} alt={{vehicle.name}} class="rounded-md w-9 h-9 object-cover shadow-sm" />
-                                    </div>
-                                    <div class="flex-1 min-w-0">
-                                        <div class="text-xs font-semibold truncate">{{or vehicle.name "Vehicle"}}</div>
-                                        {{#if vehicle.plate_number}}
-                                            <div class="text-[10px] text-gray-500 truncate">{{vehicle.plate_number}}</div>
-                                        {{/if}}
-                                        {{#if vehicle.driver_name}}
-                                            <div class="text-[11px] text-gray-600 dark:text-gray-300 truncate">
-                                                <FaIcon @icon="id-card" class="mr-1 text-gray-400" />{{vehicle.driver_name}}
-                                            </div>
-                                        {{/if}}
-                                        <div class="text-[10px] text-gray-400 mt-0.5 truncate">{{vehicle.lat}}, {{vehicle.lng}}</div>
-                                    </div>
-                                </div>
+                            <marker.popup @maxWidth="500" @minWidth="225">
+                                <Map::MarkerCard::Vehicle @vehicle={{or vehicle.card vehicle}} />
                             </marker.popup>
                             <marker.tooltip @permanent={{false}} @sticky={{true}} @direction="top">
-                                <div class="text-[11px] font-semibold">{{or vehicle.name "Vehicle"}}</div>
+                                <Map::MarkerCard::Vehicle @vehicle={{or vehicle.card vehicle}} @variant="tooltip" />
                             </marker.tooltip>
                         </layers.tracking-marker>
                     {{/each}}
diff --git a/addon/extension.js b/addon/extension.js
index bcf5b4602..925f632f9 100644
--- a/addon/extension.js
+++ b/addon/extension.js
@@ -161,6 +161,14 @@ export default {
     },
 
     registerWidgets(widgetService) {
+        // `order` places a default widget on the default dashboard, which mixes widgets from
+        // every extension; the grid fills rows first-fit, lowest order first (widgets without
+        // one follow). The default layout is:
+        //   10-40    KPI row: Radar, Revenue (ledger, 20), Active Orders, Drivers Online
+        //   41-44    Ledger KPI row: Expenses, Net Income, Outstanding AR, Overdue AR
+        //   50       Live Fleet Map, full width
+        //   60-80    Revenue Trend, Top Drivers, Maintenance Overview, a third of the width each
+        //   150-170  Ledger Recent Financial Activity + Cash Flow Summary | console Blog + GitHub
         const widgets = [
             // Legacy monolithic 13-tile widget — kept registered for one release as
             // users have it pinned to existing dashboards. The new KPI tile widgets
@@ -186,7 +194,7 @@ export default {
                 component: new ExtensionComponent('@fleetbase/fleetops-engine', 'widget/kpi-earnings'),
                 grid_options: { w: 3, h: 4, minW: 3, minH: 4 },
                 category: 'KPI Tiles',
-                default: true,
+                default: false,
             }),
             new Widget({
                 id: 'fleet-ops-kpi-aov-widget',
@@ -196,7 +204,7 @@ export default {
                 component: new ExtensionComponent('@fleetbase/fleetops-engine', 'widget/kpi-aov'),
                 grid_options: { w: 3, h: 4, minW: 3, minH: 4 },
                 category: 'KPI Tiles',
-                default: true,
+                default: false,
             }),
             new Widget({
                 id: 'fleet-ops-kpi-distance-widget',
@@ -216,6 +224,7 @@ export default {
                 component: new ExtensionComponent('@fleetbase/fleetops-engine', 'widget/kpi-active-orders'),
                 grid_options: { w: 3, h: 4, minW: 3, minH: 4 },
                 category: 'KPI Tiles',
+                order: 30,
                 default: true,
             }),
             new Widget({
@@ -226,6 +235,7 @@ export default {
                 component: new ExtensionComponent('@fleetbase/fleetops-engine', 'widget/kpi-drivers-online'),
                 grid_options: { w: 3, h: 4, minW: 3, minH: 4 },
                 category: 'KPI Tiles',
+                order: 40,
                 default: true,
             }),
             new Widget({
@@ -236,6 +246,7 @@ export default {
                 component: new ExtensionComponent('@fleetbase/fleetops-engine', 'widget/radar'),
                 grid_options: { w: 3, h: 4, minW: 3, minH: 4 },
                 category: 'KPI Tiles',
+                order: 10,
                 default: true,
             }),
             new Widget({
@@ -266,8 +277,9 @@ export default {
                 description: 'Real-time driver positions and active routes.',
                 icon: 'map-location-dot',
                 component: new ExtensionComponent('@fleetbase/fleetops-engine', 'widget/live-fleet'),
-                grid_options: { w: 8, h: 11, minW: 8, minH: 8 },
+                grid_options: { w: 12, h: 12, minW: 8, minH: 8 },
                 category: 'Maps',
+                order: 50,
                 default: true,
             }),
             new Widget({
@@ -276,8 +288,9 @@ export default {
                 description: 'Revenue over time with period comparison.',
                 icon: 'chart-line',
                 component: new ExtensionComponent('@fleetbase/fleetops-engine', 'widget/revenue-trend'),
-                grid_options: { w: 4, h: 11, minW: 4, minH: 8 },
+                grid_options: { w: 4, h: 9, minW: 4, minH: 7 },
                 category: 'Analytics',
+                order: 60,
                 default: true,
             }),
             new Widget({
@@ -306,8 +319,9 @@ export default {
                 description: 'Driver leaderboard sortable by orders, on-time %, or distance.',
                 icon: 'medal',
                 component: new ExtensionComponent('@fleetbase/fleetops-engine', 'widget/top-drivers'),
-                grid_options: { w: 6, h: 6, minW: 5, minH: 5 },
+                grid_options: { w: 4, h: 9, minW: 4, minH: 6 },
                 category: 'Analytics',
+                order: 70,
                 default: true,
             }),
             new Widget({
@@ -346,8 +360,9 @@ export default {
                 description: 'Overdue, scheduled, and YTD maintenance spend.',
                 icon: 'wrench',
                 component: new ExtensionComponent('@fleetbase/fleetops-engine', 'widget/maintenance-overview'),
-                grid_options: { w: 6, h: 6, minW: 5, minH: 5 },
+                grid_options: { w: 4, h: 9, minW: 4, minH: 6 },
                 category: 'Analytics',
+                order: 80,
                 default: true,
             }),
             new Widget({
diff --git a/app/components/map/marker-card/driver.js b/app/components/map/marker-card/driver.js
new file mode 100644
index 000000000..233ee41cb
--- /dev/null
+++ b/app/components/map/marker-card/driver.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/map/marker-card/driver';
diff --git a/app/components/map/marker-card/vehicle.js b/app/components/map/marker-card/vehicle.js
new file mode 100644
index 000000000..524d8ad84
--- /dev/null
+++ b/app/components/map/marker-card/vehicle.js
@@ -0,0 +1 @@
+export { default } from '@fleetbase/fleetops-engine/components/map/marker-card/vehicle';
diff --git a/server/src/Support/Analytics/LiveFleet.php b/server/src/Support/Analytics/LiveFleet.php
index 9cfbccca6..1eff6bd5d 100644
--- a/server/src/Support/Analytics/LiveFleet.php
+++ b/server/src/Support/Analytics/LiveFleet.php
@@ -2,10 +2,13 @@
 
 namespace Fleetbase\FleetOps\Support\Analytics;
 
+use Fleetbase\FleetOps\Http\Resources\v1\Index\Driver as DriverIndexResource;
+use Fleetbase\FleetOps\Http\Resources\v1\Index\Vehicle as VehicleIndexResource;
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\FleetOps\Support\Metrics\OrdersInProgressMetric;
+use Illuminate\Http\Resources\Json\JsonResource;
 
 /**
  * Real-time fleet snapshot used as the initial-state payload for Live Fleet Map.
@@ -23,7 +26,8 @@ public function get(): array
 
         // Driver.name is a virtual attribute backed by users.name — eager-load the
         // user so the accessor resolves cleanly without a per-record query.
-        $drivers = Driver::with(['user:uuid,name,avatar_uuid'])
+        // The user and vehicle also feed each marker's card (see card()).
+        $drivers = Driver::with(['user', 'vehicle'])
             ->where('drivers.company_uuid', $companyUuid)
             ->whereNotNull('drivers.location')
             ->where(function ($q) {
@@ -33,7 +37,8 @@ public function get(): array
 
         // Vehicles tracked independently of drivers (telematics-connected rigs may
         // report position without an active driver session).
-        $vehicles = Vehicle::where('company_uuid', $companyUuid)
+        $vehicles = Vehicle::with(['devices', 'driver', 'currentTrailers'])
+            ->where('company_uuid', $companyUuid)
             ->whereNotNull('location')
             ->get();
 
@@ -79,6 +84,7 @@ private function driverPayload(Driver $d): array
             'lat'                => $lat,
             'lng'                => $lng,
             'updated_at'         => $d->last_location_update_at,
+            'card'               => $this->card(new DriverIndexResource($d)),
         ];
     }
 
@@ -98,9 +104,19 @@ private function vehiclePayload(Vehicle $v): array
             'heading'      => (float) ($v->heading ?? 0),
             'lat'          => $lat,
             'lng'          => $lng,
+            'card'         => $this->card(new VehicleIndexResource($v)),
         ];
     }
 
+    /**
+     * What the operational live map shows in a marker's popup and tooltip: the same index
+     * resource its live endpoints return, so the dashboard widget renders identical cards.
+     */
+    private function card(JsonResource $resource): array
+    {
+        return $resource->resolve(request());
+    }
+
     /**
      * Pull [lat, lng] out of whatever shape the spatial accessor handed us.
      * Supports Point objects, [lat, lng] arrays, and {lat, lng} hashes.
diff --git a/server/tests/AnalyticsRoutesTest.php b/server/tests/AnalyticsRoutesTest.php
index 41048f9bf..07f243c14 100644
--- a/server/tests/AnalyticsRoutesTest.php
+++ b/server/tests/AnalyticsRoutesTest.php
@@ -17,6 +17,9 @@
 use Fleetbase\FleetOps\Support\Analytics\TopDrivers;
 use Fleetbase\LaravelMysqlSpatial\Types\Point;
 use Fleetbase\Models\Company;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
 use Illuminate\Http\Request;
 use Illuminate\Support\Carbon;
 
@@ -273,6 +276,16 @@ function fleetOpsAnalyticsControllerRequest(array $input = []): Request
 });
 
 test('live fleet analytics serializes driver and vehicle map payloads', function () {
+    // The markers' cards look up the current order and last known position.
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $connection->statement('create table orders (uuid varchar(64) primary key, public_id varchar(64) null, company_uuid varchar(64) null, driver_assigned_uuid varchar(64) null, vehicle_assigned_uuid varchar(64) null, tracking_number_uuid varchar(64) null, status varchar(64) null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
+    $connection->statement('create table drivers (uuid varchar(64) primary key, public_id varchar(64) null, company_uuid varchar(64) null, user_uuid varchar(64) null, vehicle_uuid varchar(64) null, current_job_uuid varchar(64) null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
+    $connection->statement('create table users (uuid varchar(64) primary key, company_uuid varchar(64) null, name varchar(255) null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
+    $connection->statement('create table positions (uuid varchar(64) primary key, company_uuid varchar(64) null, subject_uuid varchar(64) null, subject_type varchar(255) null, order_uuid varchar(64) null, speed numeric null, heading numeric null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
+    $resolver = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+
     $analytics = new LiveFleet();
 
     $driver                 = new TestFleetOpsLiveFleetDriver();
@@ -308,7 +321,21 @@ function fleetOpsAnalyticsControllerRequest(array $input = []): Request
     $driverPayload->setAccessible(true);
     $vehiclePayload->setAccessible(true);
 
-    expect($driverPayload->invoke($analytics, $driver))->toBe([
+    $driverResult  = $driverPayload->invoke($analytics, $driver);
+    $vehicleResult = $vehiclePayload->invoke($analytics, $vehicle);
+
+    // Each marker carries the live map's card: the same index resource the live endpoints return.
+    expect($driverResult['card'])->toBeArray()
+        ->and($driverResult['card'])->toHaveKeys(['name', 'status', 'phone', 'email', 'online', 'meta'])
+        ->and($driverResult['card']['meta'])->toHaveKeys(['status_label', 'speed_label', 'heading_label', 'location_coordinates', 'current_order_reference'])
+        ->and($driverResult['card']['name'])->toBe('Ada Driver')
+        ->and($vehicleResult['card'])->toHaveKeys(['display_name', 'driver_name', 'plate_number', 'online', 'meta'])
+        ->and($vehicleResult['card']['display_name'])->toBe('Van 7')
+        ->and($vehicleResult['card']['meta'])->toHaveKeys(['status_label', 'speed_label', 'heading_label', 'location_coordinates', 'current_order_reference']);
+
+    unset($driverResult['card'], $vehicleResult['card']);
+
+    expect($driverResult)->toBe([
         'uuid'               => 'driver-uuid',
         'public_id'          => 'driver-public',
         'name'               => 'Ada Driver',
@@ -320,7 +347,7 @@ function fleetOpsAnalyticsControllerRequest(array $input = []): Request
         'lat'                => 1.30,
         'lng'                => 103.80,
         'updated_at'         => '2026-01-01 10:00:00',
-    ])->and($vehiclePayload->invoke($analytics, $vehicle))->toBe([
+    ])->and($vehicleResult)->toBe([
         'uuid'         => 'vehicle-uuid',
         'public_id'    => 'vehicle-public',
         'name'         => 'Van 7',
diff --git a/server/tests/Unit/Support/Analytics/LiveFleetTest.php b/server/tests/Unit/Support/Analytics/LiveFleetTest.php
index e40deac5d..b535f6778 100644
--- a/server/tests/Unit/Support/Analytics/LiveFleetTest.php
+++ b/server/tests/Unit/Support/Analytics/LiveFleetTest.php
@@ -38,6 +38,12 @@ function fleetopsLiveFleetUseInMemoryConnection(): SQLiteConnection
     $connection->statement('create table drivers (uuid varchar(64) primary key, public_id varchar(64) null, user_uuid varchar(64) null, company_uuid varchar(64) null, vehicle_uuid varchar(64) null, current_job_uuid varchar(64) null, avatar_url varchar(255) null, location blob null, heading numeric null, online integer null, last_location_update_at datetime null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
     $connection->statement('create table vehicles (uuid varchar(64) primary key, public_id varchar(64) null, company_uuid varchar(64) null, driver_uuid varchar(64) null, photo_uuid varchar(64) null, avatar_url varchar(255) null, name varchar(255) null, year integer null, make varchar(255) null, model varchar(255) null, trim varchar(255) null, plate_number varchar(64) null, location blob null, heading numeric null, online integer null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
     $connection->statement('create table orders (uuid varchar(64) primary key, public_id varchar(64) null, internal_id varchar(64) null, company_uuid varchar(64) null, driver_assigned_uuid varchar(64) null, status varchar(64) null, tracking_number_uuid varchar(64) null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
+    // Tables the markers' index-resource cards read: devices, coupled trailers and positions.
+    $connection->statement('create table devices (uuid varchar(64) primary key, public_id varchar(64) null, company_uuid varchar(64) null, attachable_uuid varchar(64) null, attachable_type varchar(255) null, name varchar(255) null, device_id varchar(64) null, serial_number varchar(64) null, imei varchar(64) null, provider varchar(64) null, status varchar(64) null, online integer null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
+    $connection->statement('create table asset_connections (uuid varchar(64) primary key, company_uuid varchar(64) null, connector_uuid varchar(64) null, connector_type varchar(255) null, connected_uuid varchar(64) null, connected_type varchar(255) null, connected_at datetime null, disconnected_at datetime null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
+    $connection->statement('create table assets (uuid varchar(64) primary key, public_id varchar(64) null, company_uuid varchar(64) null, asset_class varchar(64) null, name varchar(255) null, code varchar(64) null, type varchar(64) null, status varchar(64) null, plate_number varchar(64) null, online integer null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
+    $connection->statement('create table positions (uuid varchar(64) primary key, company_uuid varchar(64) null, subject_uuid varchar(64) null, subject_type varchar(255) null, order_uuid varchar(64) null, speed numeric null, heading numeric null, coordinates blob null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
+    $connection->statement('create table tracking_numbers (uuid varchar(64) primary key, public_id varchar(64) null, company_uuid varchar(64) null, owner_uuid varchar(64) null, owner_type varchar(255) null, status_uuid varchar(64) null, tracking_number varchar(64) null, region varchar(64) null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
     $connection->statement('create table files (uuid varchar(64) primary key, type varchar(64) null, url varchar(255) null, deleted_at datetime null, created_at datetime null, updated_at datetime null)');
 
     $resolver = new ConnectionResolver([
diff --git a/tests/integration/components/map/marker-card/driver-test.js b/tests/integration/components/map/marker-card/driver-test.js
new file mode 100644
index 000000000..17d6a624c
--- /dev/null
+++ b/tests/integration/components/map/marker-card/driver-test.js
@@ -0,0 +1,35 @@
+import { module, test } from 'qunit';
+import { setupRenderingTest } from 'dummy/tests/helpers';
+import { render } from '@ember/test-helpers';
+import { hbs } from 'ember-cli-htmlbars';
+
+module('Integration | Component | map/marker-card/driver', function (hooks) {
+    setupRenderingTest(hooks);
+
+    test('it shows the driver card from an index-resource payload', async function (assert) {
+        this.set('driver', {
+            name: 'Ada Driver',
+            online: true,
+            status: 'active',
+            public_id: 'driver_public',
+            phone: '+6590000000',
+            vehicle_name: 'Van 7',
+            email: 'ada@example.test',
+            meta: { status_label: 'Active', current_order_reference: 'ORD-1', speed_label: '42 km/h', heading_label: '90 deg', location_coordinates: '1.3 103.8' },
+        });
+
+        await render(hbs`<Map::MarkerCard::Driver @driver={{this.driver}} />`);
+
+        for (const text of ['Ada Driver', 'Active', 'driver_public', '+6590000000', 'Van 7', 'ada@example.test', 'ORD-1', '42 km/h', '90 deg', '1.3 103.8']) {
+            assert.dom(this.element).containsText(text);
+        }
+    });
+
+    test('the tooltip variant drops the dark panel', async function (assert) {
+        this.set('driver', { name: 'Ada Driver', meta: {} });
+
+        await render(hbs`<Map::MarkerCard::Driver @driver={{this.driver}} @variant="tooltip" />`);
+
+        assert.dom('div').doesNotHaveClass('bg-gray-900');
+    });
+});
diff --git a/tests/integration/components/map/marker-card/vehicle-test.js b/tests/integration/components/map/marker-card/vehicle-test.js
new file mode 100644
index 000000000..6bc4fd06d
--- /dev/null
+++ b/tests/integration/components/map/marker-card/vehicle-test.js
@@ -0,0 +1,47 @@
+import { module, test } from 'qunit';
+import { setupRenderingTest } from 'dummy/tests/helpers';
+import { render } from '@ember/test-helpers';
+import { hbs } from 'ember-cli-htmlbars';
+import { setupIntl } from 'ember-intl/test-support';
+
+// The live map passes a vehicle model; the dashboard's Live Fleet widget passes the same
+// index-resource payload as plain JSON. Both must render the same card.
+const VEHICLE = {
+    display_name: 'Van 7',
+    online: true,
+    status: 'in_service',
+    internal_id: 'V-7',
+    driver_name: 'Ada Driver',
+    trailers: [{ display_name: 'Reefer 2', online: true }],
+    devices: [],
+    meta: { status_label: 'In Service', current_order_reference: 'ORD-1', speed_label: '42 km/h', heading_label: '90 deg', location_coordinates: '1.3 103.8' },
+};
+
+module('Integration | Component | map/marker-card/vehicle', function (hooks) {
+    setupRenderingTest(hooks);
+    setupIntl(hooks, 'en-us');
+
+    test('it shows the vehicle card from an index-resource payload', async function (assert) {
+        this.set('vehicle', VEHICLE);
+
+        await render(hbs`<Map::MarkerCard::Vehicle @vehicle={{this.vehicle}} />`);
+
+        assert.dom(this.element).containsText('Van 7', 'the display name falls back to display_name');
+        assert.dom(this.element).containsText('In Service');
+        assert.dom(this.element).containsText('V-7');
+        assert.dom(this.element).containsText('Ada Driver');
+        assert.dom(this.element).containsText('Reefer 2');
+        assert.dom(this.element).containsText('ORD-1');
+        assert.dom(this.element).containsText('42 km/h');
+        assert.dom('div').hasClass('bg-gray-900', 'a popup card is its own dark panel');
+    });
+
+    test('a model display name wins and the tooltip variant drops the panel', async function (assert) {
+        this.set('vehicle', { ...VEHICLE, displayName: 'Van 7 (SBA1234Z)' });
+
+        await render(hbs`<Map::MarkerCard::Vehicle @vehicle={{this.vehicle}} @variant="tooltip" />`);
+
+        assert.dom(this.element).containsText('Van 7 (SBA1234Z)');
+        assert.dom('div').doesNotHaveClass('bg-gray-900', 'the tooltip supplies its own panel');
+    });
+});
diff --git a/tests/unit/extension-test.js b/tests/unit/extension-test.js
index 99106b422..bb568a351 100644
--- a/tests/unit/extension-test.js
+++ b/tests/unit/extension-test.js
@@ -89,4 +89,40 @@ module('Unit | FleetOps extension', function () {
             'default analytics widgets are available'
         );
     });
+
+    test('it lays out the default dashboard: KPI row, full-width map, then three panels', function (assert) {
+        let registered = [];
+        extension.registerWidgets({
+            registerDashboard() {},
+            registerWidgets(id, widgets) {
+                if (id === 'dashboard') registered = widgets.map((widget) => widget.toObject());
+            },
+            registerDefaultWidgets() {},
+        });
+
+        const byId = Object.fromEntries(registered.map((widget) => [widget.id, widget]));
+        const defaults = registered.filter((widget) => widget.default === true).sort((a, b) => a.order - b.order);
+
+        assert.deepEqual(
+            defaults.map((widget) => [widget.id, widget.order]),
+            [
+                ['fleet-ops-radar-widget', 10],
+                ['fleet-ops-kpi-active-orders-widget', 30],
+                ['fleet-ops-kpi-drivers-online-widget', 40],
+                ['fleet-ops-live-fleet-widget', 50],
+                ['fleet-ops-revenue-trend-widget', 60],
+                ['fleet-ops-top-drivers-widget', 70],
+                ['fleet-ops-maintenance-overview-widget', 80],
+            ],
+            'every default widget has a place, leaving 20 for the ledger Revenue tile'
+        );
+        assert.strictEqual(byId['fleet-ops-live-fleet-widget'].grid_options.w, 12, 'the map spans the full width');
+        assert.deepEqual(
+            ['fleet-ops-revenue-trend-widget', 'fleet-ops-top-drivers-widget', 'fleet-ops-maintenance-overview-widget'].map((id) => byId[id].grid_options.w),
+            [4, 4, 4],
+            'the panels share a row'
+        );
+        assert.false(byId['fleet-ops-kpi-earnings-widget'].default, 'Earnings is no longer a default');
+        assert.false(byId['fleet-ops-kpi-aov-widget'].default, 'Avg Order Value is no longer a default');
+    });
 });

From 0eb4528258eca00dd85ac319af91b84ffa6ab68f Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Fri, 25 Sep 2026 16:12:29 +0800
Subject: [PATCH 07/24] chore(release): v0.6.70

---
 RELEASE.md     | 24 ++++++++++++++++--------
 composer.json  |  2 +-
 extension.json |  2 +-
 package.json   |  2 +-
 4 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/RELEASE.md b/RELEASE.md
index 32ebd138d..bc217ab22 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,23 +1,31 @@
-> v0.6.69 ~ "Fleet-Ops tools for Fleetbase AI"
+> v0.6.70 ~ "Order reporting and a cleaner default dashboard"
 
 ---
 ## What's New
-- **Fleet-Ops works with Fleetbase AI tool calling.** Creating orders from the AI prompt works again with the tool-calling assistant, and the assistant can also propose an optimized waypoint sequence for an order and explain what an order or resource import needs. Every change is a preview card the user confirms.
-- **Fleet-Ops console actions.** The assistant can offer to open Fleet-Ops pages and dialogs, such as **Operations › Orders** and **New Order**, as confirmation cards.
-- **Resource search for the assistant.** A `fleetops_search` tool finds orders, vehicles, drivers, work orders, maintenances, devices, sensors and telematics records by id, name, plate, VIN, email or phone.
+- **Report on orders, their items and tracking.** The report builder can answer questions like "Which products sold the most this month?" and "What did orders total this month?".
+  - Orders expose their ID and Internal ID, and relationships for tracking (tracking number, region, latest status), Order Config, Customer Vendor, Created By, Purchase Rate › Service Quote and Payload Return.
+  - `Payload` exposes its items with name, SKU, price, dimensions, metadata and destination. Select an item column for one row per item, or group by one to summarise per product.
+  - Summary columns count orders distinctly, so they stay correct when item rows are selected. Distance, duration and transaction amount have totals and averages.
+  - `meta` has no fixed shape, so no column assumes a key in it. Read keys with a computed column, for example `CAST(JSON_UNQUOTE(JSON_EXTRACT(payload.entities.meta, '$.quantity')) AS DECIMAL(15,2))`.
+  - Column labels drop the table name ("Type", not "Order Type"). Distance and duration are labelled in meters and seconds, and money columns are marked "(minor units)".
+- **A cleaner default dashboard.** Fleet-Ops widgets declare their place on the default dashboard: Radar first, then Active Orders and Drivers Online, a full-width Live Fleet map, and Revenue Trend, Top Drivers and Maintenance side by side.
+- **Live Fleet widget cards match the live map.** Clicking a driver or vehicle on the widget map shows the same card as **Operations › Live Map**.
 
 ---
 ## Fixes
-- AI resource search no longer fails on every call with `Unknown column 'sensor_type'`, and database errors are no longer passed to the model.
+- Custom field values on fuel reports and service areas are saved. They were dropped because the save hooks read the snake_case payload root, while the console sends `fuelReport` and `serviceArea`.
+- The report schema no longer references 13 columns and join keys that don't exist: driver name, email and phone and the driver's vehicle, the vehicle's driver, and the fuel report cost, odometer and date. Transaction summaries sum `transaction.amount`.
+- Every report table, and the item join, leaves soft-deleted rows out on core-api v1.6.64 and later.
 
 ---
 ## Dependencies
-- `@fleetbase/fleetops-data` upgraded to `^0.2.2`, which adds the read-only login state (`is_staff_linked`, `login_status`) to the driver and contact models.
-- `@fleetbase/ember-ui` upgraded to `^0.4.3`, which provides the `btn-auth` style the Track Order button on the login page uses.
+- Order items, JSON totals and soft deletes in reports need `fleetbase/core-api` v1.6.64. The schema still registers on older versions.
+- The report builder and the default dashboard order ship in `@fleetbase/ember-ui` v0.4.4.
 
 ---
 ## Testing
-- Unit tests cover the new AI tools and console commands, and the AI capability registration.
+- Every declared report column and join key was checked against the database schema, and order reports were run against real storefront orders on MySQL in strict mode.
+- Tests cover the report schema at 100% line coverage, the Live Fleet map cards and the default dashboard order.
 
 ---
 ## Need help?
diff --git a/composer.json b/composer.json
index 3907b8527..15f9fc15e 100644
--- a/composer.json
+++ b/composer.json
@@ -1,6 +1,6 @@
 {
     "name": "fleetbase/fleetops-api",
-    "version": "0.6.69",
+    "version": "0.6.70",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "keywords": [
         "fleetbase-extension",
diff --git a/extension.json b/extension.json
index 49ca67ca9..f08a7afde 100644
--- a/extension.json
+++ b/extension.json
@@ -1,6 +1,6 @@
 {
     "name": "Fleet-Ops",
-    "version": "0.6.69",
+    "version": "0.6.70",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "repository": "https://github.com/fleetbase/fleetops",
     "license": "AGPL-3.0-or-later",
diff --git a/package.json b/package.json
index 680462f58..81928af77 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@fleetbase/fleetops-engine",
-    "version": "0.6.69",
+    "version": "0.6.70",
     "description": "Fleet & Transport Management Extension for Fleetbase",
     "fleetbase": {
         "route": "fleet-ops"

From 15e77d0074d429dd9a4ecaae261941bbcb9ca44d Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sat, 26 Sep 2026 14:20:32 +0800
Subject: [PATCH 08/24] fix(settings): resolve company settings without a
 session in queued and console paths

Setting::lookupCompany()/lookupFromCompany() return the default when
session('company') is missing, which is always the case on queue workers
and often in console commands. Switch the reachable call sites to
Setting::lookupForCompany() with the model's company:

- ProcessOperationalAlerts: tracking alert settings from the order company
- NotifyDriverOnShiftChange (ShouldQueue): scheduling settings from the
  schedule company
- VroomOrchestrationEngine: org VROOM settings from the allocated orders'
  company (ProcessAllocationJob is queued), session as fallback
- TrackingOptions/OrderTracker/TrackingIntelligenceService: tracking
  settings from the order company, session as fallback
- CustomerCredentialsMail: portal slug from the customer company

Requires fleetbase/core-api >=1.6.65 (fleetbase/core-api#262).
---
 composer.json                                 |  2 +-
 .../Commands/ProcessOperationalAlerts.php     |  6 +-
 .../Listeners/NotifyDriverOnShiftChange.php   |  6 +-
 server/src/Mail/CustomerCredentialsMail.php   |  2 +-
 .../Engines/VroomOrchestrationEngine.php      | 10 +-
 server/src/Support/OrderTracker.php           |  4 +-
 .../Tracking/TrackingIntelligenceService.php  |  2 +-
 server/src/Tracking/TrackingOptions.php       |  4 +-
 .../NotificationAndMailContractsTest.php      | 28 ++++++
 server/tests/ObserverContractsTest.php        |  2 +-
 .../ProcessOperationalAlertsCommandTest.php   |  4 +-
 .../VroomEngineTransportAndSettingsTest.php   | 19 ++++
 .../MaintainableAndOperationalAlertsTest.php  | 13 ++-
 .../tests/Unit/Support/MoreQuerySeamsTest.php | 13 ++-
 .../TrackingOptionsCompanySettingsTest.php    | 94 +++++++++++++++++++
 15 files changed, 189 insertions(+), 20 deletions(-)
 create mode 100644 server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php

diff --git a/composer.json b/composer.json
index 15f9fc15e..35656bb90 100644
--- a/composer.json
+++ b/composer.json
@@ -25,7 +25,7 @@
         "barryvdh/laravel-dompdf": "^3.1",
         "brick/geo": "0.7.2",
         "cknow/laravel-money": "^7.1",
-        "fleetbase/core-api": "*",
+        "fleetbase/core-api": ">=1.6.65",
         "geocoder-php/google-maps-places-provider": "^1.4",
         "giggsey/libphonenumber-for-php": "^8.13",
         "league/geotools": "^1.1.0",
diff --git a/server/src/Console/Commands/ProcessOperationalAlerts.php b/server/src/Console/Commands/ProcessOperationalAlerts.php
index 18a255a99..c9ae5eab7 100644
--- a/server/src/Console/Commands/ProcessOperationalAlerts.php
+++ b/server/src/Console/Commands/ProcessOperationalAlerts.php
@@ -60,7 +60,7 @@ public function handle(): int
 
                 foreach ($orders as $order) {
                     session(['company' => $order->company_uuid]);
-                    $settings = $this->alertSettings();
+                    $settings = $this->alertSettings($order);
 
                     if ($this->processLateDeparture($order, $settings, $dryRun)) {
                         $triggered++;
@@ -256,9 +256,9 @@ protected function minimumDistanceToRoute(Point $position, array $routePoints):
             ->min() ?? 0;
     }
 
-    protected function alertSettings(): array
+    protected function alertSettings(Order $order): array
     {
-        $settings = Setting::lookupCompany('tracking', []);
+        $settings = Setting::lookupForCompany($order->company_uuid, 'tracking', []);
         $alerts   = data_get($settings, 'alerts', []);
 
         return [
diff --git a/server/src/Listeners/NotifyDriverOnShiftChange.php b/server/src/Listeners/NotifyDriverOnShiftChange.php
index 145c7385b..c7fe03245 100644
--- a/server/src/Listeners/NotifyDriverOnShiftChange.php
+++ b/server/src/Listeners/NotifyDriverOnShiftChange.php
@@ -48,7 +48,7 @@ public function handle($event): void
         }
 
         // Check the company-level scheduling setting
-        $settings     = $this->getSchedulingSettings();
+        $settings     = $this->getSchedulingSettings($schedule->company_uuid);
         $shouldNotify = (bool) data_get($settings, 'notify_drivers_on_shift_change', false);
         if (!$shouldNotify) {
             return;
@@ -66,9 +66,9 @@ protected function getSchedule(ScheduleItem $scheduleItem): ?Schedule
         return $scheduleItem->schedule()->with('subject')->first();
     }
 
-    protected function getSchedulingSettings(): array
+    protected function getSchedulingSettings(?string $companyUuid): array
     {
-        return Setting::lookupFromCompany('fleet-ops.scheduling-settings', []);
+        return Setting::lookupForCompany($companyUuid, 'fleet-ops.scheduling-settings', []);
     }
 
     protected function isCreatedEvent(object $event): bool
diff --git a/server/src/Mail/CustomerCredentialsMail.php b/server/src/Mail/CustomerCredentialsMail.php
index f3dbcdf56..af197524e 100644
--- a/server/src/Mail/CustomerCredentialsMail.php
+++ b/server/src/Mail/CustomerCredentialsMail.php
@@ -72,7 +72,7 @@ public function content(): Content
      */
     private function getCustomerPortalAccessUrl(): string
     {
-        $customerPortalConfig = Setting::lookupFromCompany('customer-portal-config');
+        $customerPortalConfig = Setting::lookupForCompany($this->customer->company_uuid, 'customer-portal-config');
         $accessUrlSlug        = data_get($customerPortalConfig, 'accessUrlSlug', 'customer-portal');
 
         return Utils::consoleUrl($accessUrlSlug ?: 'customer-portal');
diff --git a/server/src/Orchestration/Engines/VroomOrchestrationEngine.php b/server/src/Orchestration/Engines/VroomOrchestrationEngine.php
index 3fdebe4dc..ecb3e74b9 100644
--- a/server/src/Orchestration/Engines/VroomOrchestrationEngine.php
+++ b/server/src/Orchestration/Engines/VroomOrchestrationEngine.php
@@ -37,6 +37,12 @@
  */
 class VroomOrchestrationEngine implements OrchestrationEngineInterface
 {
+    /**
+     * The company whose VROOM settings apply to the current allocation run.
+     * Resolved from the orders so queued runs work without a company session.
+     */
+    protected ?string $companyUuid = null;
+
     public function getName(): string
     {
         return 'VROOM';
@@ -59,6 +65,8 @@ public function getIdentifier(): string
      */
     public function allocate(Collection $orders, Collection $vehicles, array $options = []): array
     {
+        $this->companyUuid = data_get($orders->first(), 'company_uuid');
+
         if (($options['allocation_strategy'] ?? null) === 'capacity_only') {
             return $this->allocateCapacityOnly($orders, $vehicles, $options);
         }
@@ -520,7 +528,7 @@ protected function resolveVroomEndpointMode(): string
     protected function resolveVroomSetting(string $key, $default = null)
     {
         try {
-            $organizationValue = data_get(Setting::lookupCompany('vroom', []), $key);
+            $organizationValue = data_get(Setting::lookupForCompany($this->companyUuid ?? session('company'), 'vroom', []), $key);
             if ($this->hasConfiguredValue($organizationValue)) {
                 return $organizationValue;
             }
diff --git a/server/src/Support/OrderTracker.php b/server/src/Support/OrderTracker.php
index 2aa5f4743..507ec96d0 100644
--- a/server/src/Support/OrderTracker.php
+++ b/server/src/Support/OrderTracker.php
@@ -14,11 +14,11 @@ public function __construct(protected Order $order)
 
     public function eta(array $options = []): array
     {
-        return app(TrackingIntelligenceService::class)->eta($this->order, TrackingOptions::fromArray($options));
+        return app(TrackingIntelligenceService::class)->eta($this->order, TrackingOptions::fromArray($options, $this->order->company_uuid));
     }
 
     public function toArray(array $options = []): array
     {
-        return app(TrackingIntelligenceService::class)->track($this->order, TrackingOptions::fromArray($options));
+        return app(TrackingIntelligenceService::class)->track($this->order, TrackingOptions::fromArray($options, $this->order->company_uuid));
     }
 }
diff --git a/server/src/Tracking/TrackingIntelligenceService.php b/server/src/Tracking/TrackingIntelligenceService.php
index f89cea241..414d9ea7d 100644
--- a/server/src/Tracking/TrackingIntelligenceService.php
+++ b/server/src/Tracking/TrackingIntelligenceService.php
@@ -18,7 +18,7 @@ public function __construct(
 
     public function track(Order $order, array|TrackingOptions $options = []): array
     {
-        $options  = $options instanceof TrackingOptions ? $options : TrackingOptions::fromArray($options);
+        $options  = $options instanceof TrackingOptions ? $options : TrackingOptions::fromArray($options, $order->company_uuid);
         $context  = $this->contextBuilder->build($order, $options);
         $cacheKey = $this->cacheKey($context, $options);
 
diff --git a/server/src/Tracking/TrackingOptions.php b/server/src/Tracking/TrackingOptions.php
index a216cd148..66cca97ac 100644
--- a/server/src/Tracking/TrackingOptions.php
+++ b/server/src/Tracking/TrackingOptions.php
@@ -19,7 +19,7 @@ public function __construct(
     ) {
     }
 
-    public static function fromArray(array $options = []): self
+    public static function fromArray(array $options = [], ?string $companyUuid = null): self
     {
         try {
             $systemSettings = Setting::lookup('fleet-ops.tracking-settings', []);
@@ -30,7 +30,7 @@ public static function fromArray(array $options = []): self
         $config          = array_merge(config('fleetops.tracking', []), is_array($systemSettings) ? $systemSettings : []);
         $companySettings = [];
         try {
-            $companySettings = Setting::lookupCompany('tracking', []);
+            $companySettings = Setting::lookupForCompany($companyUuid ?? session('company'), 'tracking', []);
         } catch (\Throwable) {
             $companySettings = [];
         }
diff --git a/server/tests/NotificationAndMailContractsTest.php b/server/tests/NotificationAndMailContractsTest.php
index 1481b8783..b84abe02d 100644
--- a/server/tests/NotificationAndMailContractsTest.php
+++ b/server/tests/NotificationAndMailContractsTest.php
@@ -675,3 +675,31 @@ public function track(Order $order, mixed $options): array
             'offsetDays' => 7,
         ]);
 });
+
+test('customer credentials mail reads the portal slug from the customer company without a session', function () {
+    app('config')->set('fleetbase.console.host', 'console.fleetbase.test');
+    app('config')->set('fleetbase.console.secure', true);
+    app('config')->set('fleetbase.console.subdomain', null);
+    app('session.store')->forget('company');
+
+    $connection = new Illuminate\Database\SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new Illuminate\Database\ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    Illuminate\Database\Eloquent\Model::setConnectionResolver($resolver);
+    $connection->getSchemaBuilder()->create('settings', function ($blueprint) {
+        $blueprint->increments('id');
+        $blueprint->string('key')->nullable();
+        $blueprint->text('value')->nullable();
+        $blueprint->timestamps();
+    });
+    $connection->table('settings')->insert(['key' => 'company.company-portal.customer-portal-config', 'value' => json_encode(['accessUrlSlug' => 'acme-portal'])]);
+
+    $customer              = new FleetOpsNotificationContactFake();
+    $customer->userForTest = new User();
+    $customer->userForTest->setRawAttributes(['email' => 'customer@example.test'], true);
+    $customer->setRawAttributes(['company_uuid' => 'company-portal'], true);
+
+    $content = fleetOpsNotificationWithEnvironment(fn () => (new CustomerCredentialsMail('plain-secret', $customer))->content());
+
+    expect($content->with['customerPortalUrl'])->toBe('https://console.fleetbase.test/acme-portal');
+});
diff --git a/server/tests/ObserverContractsTest.php b/server/tests/ObserverContractsTest.php
index 38b097fa3..0a15bf65c 100644
--- a/server/tests/ObserverContractsTest.php
+++ b/server/tests/ObserverContractsTest.php
@@ -454,7 +454,7 @@ protected function getSchedule(ScheduleItem $scheduleItem): ?Schedule
         return $this->schedule;
     }
 
-    protected function getSchedulingSettings(): array
+    protected function getSchedulingSettings(?string $companyUuid): array
     {
         return $this->settings;
     }
diff --git a/server/tests/Unit/Console/Commands/ProcessOperationalAlertsCommandTest.php b/server/tests/Unit/Console/Commands/ProcessOperationalAlertsCommandTest.php
index 5da25c5c0..b5a3a20e7 100644
--- a/server/tests/Unit/Console/Commands/ProcessOperationalAlertsCommandTest.php
+++ b/server/tests/Unit/Console/Commands/ProcessOperationalAlertsCommandTest.php
@@ -125,9 +125,9 @@ protected function ordersQuery(Carbon $cutoff)
         return $this->query;
     }
 
-    protected function alertSettings(): array
+    protected function alertSettings(Order $order): array
     {
-        $this->settingsCalls[] = session('company');
+        $this->settingsCalls[] = $order->company_uuid;
 
         return [
             'late_departures'     => ['enabled' => true],
diff --git a/server/tests/Unit/Orchestration/VroomEngineTransportAndSettingsTest.php b/server/tests/Unit/Orchestration/VroomEngineTransportAndSettingsTest.php
index a65d75a31..a1c020e54 100644
--- a/server/tests/Unit/Orchestration/VroomEngineTransportAndSettingsTest.php
+++ b/server/tests/Unit/Orchestration/VroomEngineTransportAndSettingsTest.php
@@ -251,3 +251,22 @@ function fleetopsVroomVehicle(string $publicId, Point $location): Vehicle
     expect($call('resolveVroomBaseUri'))->toBeString()
         ->and($call('resolveVroomApiKey'))->toBeIn([null, '']);
 });
+
+test('allocation resolves organization settings from the orders company without a session', function () {
+    $connection = fleetopsVroomBoot();
+    $connection->table('settings')->insert([
+        ['key' => 'company.company-2.vroom', 'value' => json_encode(['api_host' => 'https://company-two-vroom.test'])],
+    ]);
+
+    $order = fleetopsVroomOrder('order_vroom_queued', fleetopsVroomPlace('p-9', new Point(1.31, 103.81)), null);
+    $order->setAttribute('company_uuid', 'company-2');
+    $vehicle = fleetopsVroomVehicle('vehicle_vroom_queued', new Point(1.20, 103.70));
+
+    Http::fake(['*' => Http::response(['routes' => [], 'unassigned' => [], 'summary' => []], 200)]);
+
+    // Queued allocation runs (ProcessAllocationJob) have no company session
+    session(['company' => null]);
+    (new VroomOrchestrationEngine())->allocate(collect([$order]), collect([$vehicle]));
+
+    Http::assertSent(fn ($request) => str_starts_with($request->url(), 'https://company-two-vroom.test'));
+});
diff --git a/server/tests/Unit/Support/MaintainableAndOperationalAlertsTest.php b/server/tests/Unit/Support/MaintainableAndOperationalAlertsTest.php
index b36e6d8b6..c7d58c2aa 100644
--- a/server/tests/Unit/Support/MaintainableAndOperationalAlertsTest.php
+++ b/server/tests/Unit/Support/MaintainableAndOperationalAlertsTest.php
@@ -184,10 +184,21 @@ function fleetopsMaintainableVehicle(array $attributes = []): Part
     $order = Order::where('uuid', 'order-1')->withoutGlobalScopes()->first();
     expect($probe->callHelper('latestPositionForOrder', $order))->toBeInstanceOf(Position::class);
 
-    $settings = $probe->callHelper('alertSettings');
+    $settings = $probe->callHelper('alertSettings', $order);
     expect($settings['late_departures']['enabled'])->toBeTrue()
         ->and($settings['route_deviations']['distance_threshold_meters'])->toBe(500)
         ->and($settings['prolonged_stoppages']['duration_threshold_minutes'])->toBe(30);
+
+    // Settings resolve from the order's company without a company session
+    $connection->table('settings')->insert([
+        'key'   => 'company.company-1.tracking',
+        'value' => json_encode(['alerts' => ['late_departures' => ['enabled' => false], 'route_deviations' => ['distance_threshold_meters' => 750]]]),
+    ]);
+    session(['company' => null]);
+    $settings = $probe->callHelper('alertSettings', $order);
+    session(['company' => 'company-1']);
+    expect($settings['late_departures']['enabled'])->toBeFalse()
+        ->and($settings['route_deviations']['distance_threshold_meters'])->toBe(750);
 });
 
 test('route point collection normalizes pairs and measures distances', function () {
diff --git a/server/tests/Unit/Support/MoreQuerySeamsTest.php b/server/tests/Unit/Support/MoreQuerySeamsTest.php
index 59f90d6e2..c095ae011 100644
--- a/server/tests/Unit/Support/MoreQuerySeamsTest.php
+++ b/server/tests/Unit/Support/MoreQuerySeamsTest.php
@@ -384,13 +384,22 @@ public function get()
 });
 
 test('shift change listener reads company scheduling settings', function () {
-    fleetopsMoreSeamBoot();
+    $connection = fleetopsMoreSeamBoot();
 
     $class    = Fleetbase\FleetOps\Listeners\NotifyDriverOnShiftChange::class;
     $listener = (new ReflectionClass($class))->newInstanceWithoutConstructor();
 
     // With nothing stored the lookup falls back to the empty default
-    expect(fleetopsMoreSeamInvoke($listener, $class, 'getSchedulingSettings'))->toBe([]);
+    expect(fleetopsMoreSeamInvoke($listener, $class, 'getSchedulingSettings', ['company-seam-2']))->toBe([]);
+
+    // Queued listeners have no company session, so the schedule's company is used
+    $connection->table('settings')->insert(['key' => 'company.company-seam-3.fleet-ops.scheduling-settings', 'value' => json_encode(['notify_drivers_on_shift_change' => true])]);
+    session(['company' => null]);
+    $settings = fleetopsMoreSeamInvoke($listener, $class, 'getSchedulingSettings', ['company-seam-3']);
+    session(['company' => 'company-seam-2']);
+
+    expect($settings)->toBe(['notify_drivers_on_shift_change' => true])
+        ->and(fleetopsMoreSeamInvoke($listener, $class, 'getSchedulingSettings', [null]))->toBe([]);
 });
 
 test('order insights capability builds its own company-scoped order query', function () {
diff --git a/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php b/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php
new file mode 100644
index 000000000..cc2fcf8fd
--- /dev/null
+++ b/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php
@@ -0,0 +1,94 @@
+<?php
+
+if (!function_exists('Fleetbase\Models\session')) {
+    eval('namespace Fleetbase\Models; function session($key = null, $default = null) { if ($key === null) { return new class { public function has($k) { return \session($k) !== null; } public function get($k, $d = null) { return \session($k, $d); } public function missing($k) { return \session($k) === null; } }; } return \session($key, $default); }');
+}
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Support\OrderTracker;
+use Fleetbase\FleetOps\Tracking\TrackingIntelligenceService;
+use Fleetbase\FleetOps\Tracking\TrackingOptions;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model as EloquentModel;
+use Illuminate\Database\SQLiteConnection;
+
+/**
+ * Covers company tracking settings resolution for TrackingOptions: the
+ * order's company is used when there is no company session (queued jobs,
+ * console commands), and the session company remains the fallback.
+ */
+function fleetopsTrackingOptionsBoot(): SQLiteConnection
+{
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    EloquentModel::setConnectionResolver($resolver);
+
+    $connection->getSchemaBuilder()->create('settings', function ($blueprint) {
+        $blueprint->increments('id');
+        $blueprint->string('key')->nullable();
+        $blueprint->text('value')->nullable();
+        $blueprint->timestamps();
+    });
+
+    $connection->table('settings')->insert([
+        ['key' => 'company.company-a.tracking', 'value' => json_encode(['provider' => 'osrm', 'cache_ttl_seconds' => 15])],
+        ['key' => 'company.company-b.tracking', 'value' => json_encode(['provider' => 'calculated', 'cache_ttl_seconds' => 45])],
+    ]);
+
+    session(['company' => null]);
+
+    return $connection;
+}
+
+test('tracking options read the given company settings without a company session', function () {
+    fleetopsTrackingOptionsBoot();
+
+    $options = TrackingOptions::fromArray([], 'company-a');
+
+    expect($options->provider)->toBe('osrm')
+        ->and($options->cacheTtlSeconds)->toBe(15);
+
+    // Explicit options still win over company settings
+    expect(TrackingOptions::fromArray(['provider' => 'google'], 'company-a')->provider)->toBe('google');
+});
+
+test('tracking options fall back to the session company when no company is given', function () {
+    fleetopsTrackingOptionsBoot();
+    session(['company' => 'company-b']);
+
+    $options = TrackingOptions::fromArray([]);
+    session(['company' => null]);
+
+    expect($options->provider)->toBe('calculated')
+        ->and($options->cacheTtlSeconds)->toBe(45);
+});
+
+test('order tracker builds options from the order company', function () {
+    fleetopsTrackingOptionsBoot();
+
+    $service = new class extends TrackingIntelligenceService {
+        public ?TrackingOptions $received = null;
+
+        public function __construct()
+        {
+        }
+
+        public function track(Order $order, array|TrackingOptions $options = []): array
+        {
+            $this->received = $options;
+
+            return [];
+        }
+    };
+    app()->instance(TrackingIntelligenceService::class, $service);
+
+    $order = new Order();
+    $order->setRawAttributes(['uuid' => 'order-tracking-options', 'company_uuid' => 'company-a'], true);
+
+    (new OrderTracker($order))->toArray();
+    app()->forgetInstance(TrackingIntelligenceService::class);
+
+    expect($service->received)->toBeInstanceOf(TrackingOptions::class)
+        ->and($service->received->provider)->toBe('osrm');
+});

From 08e06cc9db12b0581416d4ae86eb938fa5db8b0a Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sun, 27 Sep 2026 14:32:59 +0800
Subject: [PATCH 09/24] fix(permissions): enforce Fleet-Ops permissions on
 unguarded and mis-mapped endpoints

Schema
- Declare resources the UI already checked but the schema never created, which
  left their API unguarded and their screens unreachable for non-admins:
  maintenance-schedule, device, sensor, device-event, telematic, warranty,
  purchase-rate, fuel-provider-connection/-transaction/-sync-run, analytics,
  scheduling-settings, tracking-settings. service-rate gains export.
- Fix the 'action' => 'actions' key on the settings resources, so
  `fleet-ops onboard payments` is actually created.
- Grant the new resources in the built-in policies (FleetManager,
  MaintenanceManager, ServiceRateManager, OperationsAdmin, DispatchManager).

Custom actions (Support\Authorization + #[SkipAuthorizationCheck])
- AuthorizationGuard maps unmatched method names by HTTP verb, so e.g.
  bulk-dispatch required `create order`, unassign-vehicle `create driver` and
  trailer attach `create trailer`. Map them to the schema actions: dispatch,
  cancel, schedule, import, assign-driver-for, update-route-for order;
  assign-order-for / assign-vehicle-for / update-user-for driver;
  attach-/detach-*-for trailer; and update on vehicle, vendor, device,
  telematic, maintenance-schedule, maintenance, work-order and
  fuel-provider-* sub-actions.

Controllers outside the guard
- Analytics and metrics require `view analytics`; live map feeds require list
  order/driver/vehicle/place; orchestrator, manifests, radar writes, customer
  portal logins and Stripe payments now require their permissions.
- Settings writes require the matching *-settings permission; the admin
  tracking/map settings require a system admin.
- Entity editing settings are one platform-wide map: a save now only writes
  the session company's order configs and keeps other companies' entries, and
  reads return only the company's own. Driver onboard settings are pinned to
  the session company instead of a request-supplied company id.
- Navigator link-app returned an API key to unauthenticated callers. The link
  is now a 30 minute signed URL issued only to system admins, and link-app
  rejects unsigned requests.
---
 server/src/Auth/Schemas/FleetOps.php          |  91 +++++++++++++++-
 .../Internal/v1/AnalyticsController.php       |  11 ++
 .../Internal/v1/ContactController.php         |   5 +
 .../Internal/v1/CustomerController.php        |  11 ++
 .../Internal/v1/DeviceController.php          |   8 ++
 .../Internal/v1/DeviceEventController.php     |   5 +
 .../Internal/v1/DriverController.php          |  23 ++++
 .../v1/FuelProviderConnectionController.php   |   8 ++
 .../v1/FuelProviderTransactionController.php  |  11 ++
 .../Internal/v1/InspectionFormController.php  |  11 ++
 .../Internal/v1/LiveController.php            |  15 +++
 .../Internal/v1/MaintenanceController.php     |  11 ++
 .../v1/MaintenanceScheduleController.php      |  11 ++
 .../Internal/v1/ManifestController.php        |  13 +++
 .../Internal/v1/MetricsController.php         |  11 ++
 .../Internal/v1/NavigatorController.php       |  14 ++-
 .../Internal/v1/OrchestrationController.php   |  15 +++
 .../Internal/v1/OrderController.php           |  23 ++++
 .../Internal/v1/PaymentController.php         |   9 ++
 .../Internal/v1/RadarController.php           |  21 ++++
 .../Internal/v1/SettingController.php         |  77 ++++++++++---
 .../Internal/v1/TelematicController.php       |  20 ++++
 .../Internal/v1/TrailerController.php         |  20 ++++
 .../Internal/v1/VehicleController.php         |  20 ++++
 .../Internal/v1/VendorController.php          |  14 +++
 .../Internal/v1/WorkOrderController.php       |   5 +
 server/src/Support/Authorization.php          | 103 ++++++++++++++++++
 server/src/routes.php                         |   6 +-
 28 files changed, 569 insertions(+), 23 deletions(-)
 create mode 100644 server/src/Support/Authorization.php

diff --git a/server/src/Auth/Schemas/FleetOps.php b/server/src/Auth/Schemas/FleetOps.php
index 74bf863ae..084eca17e 100644
--- a/server/src/Auth/Schemas/FleetOps.php
+++ b/server/src/Auth/Schemas/FleetOps.php
@@ -43,7 +43,7 @@ class FleetOps
         ],
         [
             'name'    => 'service-rate',
-            'actions' => ['import'],
+            'actions' => ['import', 'export'],
         ],
         [
             'name'    => 'zone',
@@ -141,6 +141,51 @@ class FleetOps
             'name'    => 'part',
             'actions' => ['export', 'import'],
         ],
+        [
+            'name'    => 'maintenance-schedule',
+            'actions' => ['export', 'import'],
+        ],
+        [
+            'name'    => 'warranty',
+            'actions' => [],
+        ],
+        [
+            'name'    => 'device',
+            'actions' => ['export', 'import'],
+        ],
+        [
+            'name'    => 'sensor',
+            'actions' => ['export', 'import'],
+        ],
+        [
+            'name'    => 'device-event',
+            'actions' => ['export'],
+        ],
+        [
+            'name'    => 'telematic',
+            'actions' => ['export', 'import'],
+        ],
+        [
+            'name'    => 'fuel-provider-connection',
+            'actions' => ['sync'],
+        ],
+        [
+            'name'    => 'fuel-provider-transaction',
+            'actions' => ['review'],
+        ],
+        [
+            'name'    => 'fuel-provider-sync-run',
+            'actions' => [],
+        ],
+        [
+            'name'    => 'purchase-rate',
+            'actions' => [],
+        ],
+        [
+            'name'           => 'analytics', // dashboards, KPI metrics and the live fleet summary
+            'actions'        => [],
+            'remove_actions' => ['create', 'update', 'delete', 'export'],
+        ],
         [
             'name'    => 'custom-field',
             'actions' => [],
@@ -151,29 +196,39 @@ class FleetOps
         ],
         [
             'name'           => 'navigator-settings', // the navigator mobile app used by drivers
-            'action'         => [],
+            'actions'        => [],
             'remove_actions' => ['delete', 'export', 'list', 'create'],
         ],
         [
             'name'           => 'payments',
-            'action'         => ['onboard'],
+            'actions'        => ['onboard'],
             'remove_actions' => ['delete', 'export', 'list', 'create'],
         ],
         [
             'name'           => 'notification-settings',
-            'action'         => [],
+            'actions'        => [],
             'remove_actions' => ['export', 'create'],
         ],
         [
             'name'           => 'routing-settings',
-            'action'         => [],
+            'actions'        => [],
             'remove_actions' => ['export', 'create'],
         ],
         [
             'name'           => 'map-settings',
-            'action'         => [],
+            'actions'        => [],
             'remove_actions' => ['export', 'create'],
         ],
+        [
+            'name'           => 'scheduling-settings',
+            'actions'        => [],
+            'remove_actions' => ['delete', 'export', 'create'],
+        ],
+        [
+            'name'           => 'tracking-settings',
+            'actions'        => [],
+            'remove_actions' => ['delete', 'export', 'create'],
+        ],
     ];
 
     /**
@@ -187,6 +242,9 @@ class FleetOps
                 'see extension',
                 '* order',
                 '* route',
+                'see analytics',
+                'list analytics',
+                'view analytics',
                 'see order-config',
                 'list order-config',
                 'view order-config',
@@ -230,6 +288,12 @@ class FleetOps
                 '* driver',
                 '* vehicle',
                 '* trailer',
+                '* device',
+                '* sensor',
+                '* telematic',
+                'see device-event',
+                'list device-event',
+                'view device-event',
             ],
         ],
         [
@@ -277,6 +341,7 @@ class FleetOps
             'permissions' => [
                 'see extension',
                 '* service-rate',
+                '* purchase-rate',
                 'see order',
                 'list order',
                 'see service-area',
@@ -309,6 +374,8 @@ class FleetOps
                 '* inspection-submission',
                 '* equipment',
                 '* part',
+                '* maintenance-schedule',
+                '* warranty',
                 '* trailer',
                 'see vehicle',
                 'list vehicle',
@@ -336,6 +403,18 @@ class FleetOps
                 '* inspection-submission',
                 '* equipment',
                 '* part',
+                '* maintenance-schedule',
+                '* warranty',
+                '* device',
+                '* sensor',
+                '* device-event',
+                '* telematic',
+                '* fuel-provider-connection',
+                '* fuel-provider-transaction',
+                '* fuel-provider-sync-run',
+                'see analytics',
+                'list analytics',
+                'view analytics',
                 '* trailer',
             ],
         ],
diff --git a/server/src/Http/Controllers/Internal/v1/AnalyticsController.php b/server/src/Http/Controllers/Internal/v1/AnalyticsController.php
index 654be49ab..e88f7f6cd 100644
--- a/server/src/Http/Controllers/Internal/v1/AnalyticsController.php
+++ b/server/src/Http/Controllers/Internal/v1/AnalyticsController.php
@@ -14,6 +14,7 @@
 use Fleetbase\FleetOps\Support\Analytics\OrdersByStatus;
 use Fleetbase\FleetOps\Support\Analytics\RevenueTrend;
 use Fleetbase\FleetOps\Support\Analytics\TopDrivers;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Controllers\Controller;
 use Illuminate\Http\Request;
 
@@ -28,6 +29,16 @@
  */
 class AnalyticsController extends Controller
 {
+    public function __construct()
+    {
+        // Not a resource controller, so AuthorizationGuard cannot resolve a permission for it.
+        $this->middleware(function ($request, $next) {
+            Authorization::authorize('view analytics');
+
+            return $next($request);
+        });
+    }
+
     public function operationsPulse(Request $request)
     {
         return $this->run($request, OperationsPulse::class);
diff --git a/server/src/Http/Controllers/Internal/v1/ContactController.php b/server/src/Http/Controllers/Internal/v1/ContactController.php
index 402fd4eb9..a17605ec2 100644
--- a/server/src/Http/Controllers/Internal/v1/ContactController.php
+++ b/server/src/Http/Controllers/Internal/v1/ContactController.php
@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Exports\ContactExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Http\Resources\v1\Vendor as VendorResource;
@@ -14,6 +15,7 @@
 use Fleetbase\FleetOps\Models\PurchaseRate;
 use Fleetbase\FleetOps\Models\Vendor;
 use Fleetbase\FleetOps\Models\VendorPersonnel;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
@@ -108,8 +110,11 @@ public function getAsCustomer($id)
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function convertToVendor(Request $request, string $id)
     {
+        Authorization::authorize('create vendor');
+
         $contact = $this->contactForVendorConversion($id);
 
         $vendor = $this->runContactConversionTransaction(function () use ($contact, $request) {
diff --git a/server/src/Http/Controllers/Internal/v1/CustomerController.php b/server/src/Http/Controllers/Internal/v1/CustomerController.php
index e17f4c4fd..8c91a537f 100644
--- a/server/src/Http/Controllers/Internal/v1/CustomerController.php
+++ b/server/src/Http/Controllers/Internal/v1/CustomerController.php
@@ -4,6 +4,7 @@
 
 use Fleetbase\FleetOps\Mail\CustomerCredentialsMail;
 use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\ProfileAccountManager;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Models\User;
@@ -15,6 +16,8 @@ class CustomerController extends Controller
 {
     public function createPortalLogin(Request $request)
     {
+        Authorization::authorize('reset-credentials-for customer');
+
         $customer = $this->resolveCustomer($request);
         $user     = $this->resolveCustomerUser($customer);
 
@@ -37,6 +40,8 @@ public function createPortalLogin(Request $request)
 
     public function sendCredentials(Request $request)
     {
+        Authorization::authorize('reset-credentials-for customer');
+
         $customer = $this->resolveCustomer($request);
         $user     = $this->resolveCustomerUser($customer);
 
@@ -59,6 +64,8 @@ public function sendCredentials(Request $request)
 
     public function deactivatePortalLogin(Request $request)
     {
+        Authorization::authorize('reset-credentials-for customer');
+
         $customer = $this->resolveCustomer($request);
         $user     = $customer->user_uuid ? $this->findUser($customer->user_uuid) : null;
 
@@ -79,6 +86,8 @@ public function deactivatePortalLogin(Request $request)
 
     public function reactivatePortalLogin(Request $request)
     {
+        Authorization::authorize('reset-credentials-for customer');
+
         $customer = $this->resolveCustomer($request);
         $user     = $customer->user_uuid ? $this->findUser($customer->user_uuid) : null;
 
@@ -145,6 +154,8 @@ public function reactivatePortalLogin(Request $request)
      */
     public function resetCredentials(Request $request)
     {
+        Authorization::authorize('reset-credentials-for customer');
+
         $customerId      = $request->input('customer');
         $password        = $request->input('password');
         $confirmPassword = $request->input('password_confirmation');
diff --git a/server/src/Http/Controllers/Internal/v1/DeviceController.php b/server/src/Http/Controllers/Internal/v1/DeviceController.php
index 09efcd960..6396af206 100644
--- a/server/src/Http/Controllers/Internal/v1/DeviceController.php
+++ b/server/src/Http/Controllers/Internal/v1/DeviceController.php
@@ -2,11 +2,13 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Exceptions\DeviceAlreadyAttachedException;
 use Fleetbase\FleetOps\Exports\DeviceExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Models\Device;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
 use Illuminate\Http\JsonResponse;
@@ -110,8 +112,11 @@ public static function onFindRecord($query, $request): void
     /**
      * Attach a device to a supported FleetOps resource.
      */
+    #[SkipAuthorizationCheck]
     public function attach(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update device');
+
         $request->validate([
             'vehicle' => 'required_without:attachable_uuid|nullable|string',
         ]);
@@ -152,8 +157,11 @@ public function attach(Request $request, string $id): JsonResponse
     /**
      * Detach a device from its current FleetOps resource.
      */
+    #[SkipAuthorizationCheck]
     public function detach(string $id): JsonResponse
     {
+        Authorization::authorize('update device');
+
         $device = $this->resolveDevice($id);
 
         if (!$device) {
diff --git a/server/src/Http/Controllers/Internal/v1/DeviceEventController.php b/server/src/Http/Controllers/Internal/v1/DeviceEventController.php
index 80b8d8467..3cc196f07 100644
--- a/server/src/Http/Controllers/Internal/v1/DeviceEventController.php
+++ b/server/src/Http/Controllers/Internal/v1/DeviceEventController.php
@@ -2,8 +2,10 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Models\DeviceEvent;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Utils;
 use Illuminate\Http\JsonResponse;
 
@@ -51,8 +53,11 @@ public static function onQueryRecord($query, $request): void
         }
     }
 
+    #[SkipAuthorizationCheck]
     public function markProcessed(string $id): JsonResponse
     {
+        Authorization::authorize('update device-event');
+
         $deviceEvent = DeviceEvent::where('company_uuid', session('company'))
             ->where(function ($query) use ($id) {
                 $query->where('uuid', $id)->orWhere('public_id', $id);
diff --git a/server/src/Http/Controllers/Internal/v1/DriverController.php b/server/src/Http/Controllers/Internal/v1/DriverController.php
index 26203e962..69d47885b 100644
--- a/server/src/Http/Controllers/Internal/v1/DriverController.php
+++ b/server/src/Http/Controllers/Internal/v1/DriverController.php
@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\Exceptions\FleetbaseRequestValidationException;
 use Fleetbase\FleetOps\Exceptions\ProfileIdentityConflictException;
 use Fleetbase\FleetOps\Exports\DriverExport;
@@ -14,6 +15,7 @@
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\ProfileAccountManager;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
@@ -200,8 +202,11 @@ function ($request, &$driver) {
      *
      * @return JsonResponse
      */
+    #[SkipAuthorizationCheck]
     public function sendCredentials(string $id)
     {
+        Authorization::authorize('update-user-for driver');
+
         [$driver, $user, $error] = $this->resolveDriverLogin($id);
         if ($error) {
             return $error;
@@ -221,8 +226,11 @@ public function sendCredentials(string $id)
      *
      * @return JsonResponse
      */
+    #[SkipAuthorizationCheck]
     public function resetCredentials(Request $request, string $id)
     {
+        Authorization::authorize('update-user-for driver');
+
         $password = $request->input('password');
         if (!is_string($password) || strlen($password) < 8) {
             return response()->error('Password must be at least 8 characters.');
@@ -255,8 +263,11 @@ public function resetCredentials(Request $request, string $id)
      *
      * @return JsonResponse
      */
+    #[SkipAuthorizationCheck]
     public function deactivateLogin(string $id)
     {
+        Authorization::authorize('update-user-for driver');
+
         [$driver, $user, $error] = $this->resolveDriverLogin($id);
         if ($error) {
             return $error;
@@ -275,8 +286,11 @@ public function deactivateLogin(string $id)
      *
      * @return JsonResponse
      */
+    #[SkipAuthorizationCheck]
     public function reactivateLogin(string $id)
     {
+        Authorization::authorize('update-user-for driver');
+
         [$driver, $user, $error] = $this->resolveDriverLogin($id);
         if ($error) {
             return $error;
@@ -430,8 +444,11 @@ public function assignedOrders(string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function unassignOrders(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('assign-order-for driver');
+
         $request->validate([
             'orders'   => 'required|array|min:1',
             'orders.*' => 'required|string',
@@ -462,8 +479,11 @@ public function unassignOrders(Request $request, string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function unassignOrder(string $id): JsonResponse
     {
+        Authorization::authorize('assign-order-for driver');
+
         $driver = $this->findDriver($id);
         $order  = $this->currentAssignedOrderForDriver($driver) ?? $driver->getCurrentOrder();
 
@@ -498,8 +518,11 @@ public function assignVehicle(Request $request, string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function unassignVehicle(string $id): JsonResponse
     {
+        Authorization::authorize('assign-vehicle-for driver');
+
         $driver  = $this->findDriver($id);
         $vehicle = $driver->vehicle;
 
diff --git a/server/src/Http/Controllers/Internal/v1/FuelProviderConnectionController.php b/server/src/Http/Controllers/Internal/v1/FuelProviderConnectionController.php
index af7684887..9123b346a 100644
--- a/server/src/Http/Controllers/Internal/v1/FuelProviderConnectionController.php
+++ b/server/src/Http/Controllers/Internal/v1/FuelProviderConnectionController.php
@@ -2,9 +2,11 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Jobs\SyncFuelProviderTransactionsJob;
 use Fleetbase\FleetOps\Models\FuelProviderConnection;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\FuelProviders\FuelProviderService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -38,8 +40,11 @@ public function onBeforeUpdate(Request $request, FuelProviderConnection $connect
         $this->normalizeConnectionInput($input, $connection);
     }
 
+    #[SkipAuthorizationCheck]
     public function testCredentials(Request $request, string $provider): JsonResponse
     {
+        Authorization::authorize('create fuel-provider-connection');
+
         $request->validate([
             'credentials' => 'required|array',
             'environment' => 'nullable|string|in:production,sandbox',
@@ -54,8 +59,11 @@ public function testCredentials(Request $request, string $provider): JsonRespons
         return response()->json($result, data_get($result, 'success') ? 200 : 422);
     }
 
+    #[SkipAuthorizationCheck]
     public function testConnection(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update fuel-provider-connection');
+
         $connection = $this->findConnection($id);
         $result     = $this->fuelProviderService->testConnection($connection);
 
diff --git a/server/src/Http/Controllers/Internal/v1/FuelProviderTransactionController.php b/server/src/Http/Controllers/Internal/v1/FuelProviderTransactionController.php
index 926bd00f5..74ccd0d41 100644
--- a/server/src/Http/Controllers/Internal/v1/FuelProviderTransactionController.php
+++ b/server/src/Http/Controllers/Internal/v1/FuelProviderTransactionController.php
@@ -2,8 +2,10 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Models\FuelProviderTransaction;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\FuelProviders\FuelProviderService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -22,8 +24,11 @@ public static function onQueryRecord($query, $request): void
         $query->with(['vehicle', 'driver', 'fuelReport']);
     }
 
+    #[SkipAuthorizationCheck]
     public function matchVehicle(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update fuel-provider-transaction');
+
         $request->validate(['vehicle' => 'required|string']);
         $transaction = $this->findTransaction($id);
 
@@ -33,8 +38,11 @@ public function matchVehicle(Request $request, string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function matchOrder(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update fuel-provider-transaction');
+
         $request->validate(['order' => 'required|string']);
         $transaction = $this->findTransaction($id);
 
@@ -44,8 +52,11 @@ public function matchOrder(Request $request, string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function reprocess(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update fuel-provider-transaction');
+
         $transaction = $this->findTransaction($id);
 
         return response()->json([
diff --git a/server/src/Http/Controllers/Internal/v1/InspectionFormController.php b/server/src/Http/Controllers/Internal/v1/InspectionFormController.php
index b77373a82..3ff7f8c0b 100644
--- a/server/src/Http/Controllers/Internal/v1/InspectionFormController.php
+++ b/server/src/Http/Controllers/Internal/v1/InspectionFormController.php
@@ -2,12 +2,14 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Http\Resources\v1\InspectionLink as InspectionLinkResource;
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\InspectionForm;
 use Fleetbase\FleetOps\Models\InspectionLink;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\InspectionFormSync;
 use Fleetbase\FleetOps\Support\InspectionLinkPin;
 use Fleetbase\Models\User;
@@ -107,8 +109,11 @@ public function archive(string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function generateLink(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('publish inspection-form');
+
         $form = $this->resolveForm($id)
             ->firstOrFail();
 
@@ -215,8 +220,11 @@ public function links(Request $request, string $id): JsonResponse
     }
 
     /** Take a link out of use, leaving the record of it in the list. */
+    #[SkipAuthorizationCheck]
     public function revokeLink(Request $request, string $id, string $linkId): JsonResponse
     {
+        Authorization::authorize('publish inspection-form');
+
         $form = $this->resolveForm($id)->firstOrFail();
 
         $link = InspectionLink::where('inspection_form_uuid', $form->uuid)
@@ -243,8 +251,11 @@ public function revokeLink(Request $request, string $id, string $linkId): JsonRe
      * A failed delivery answers 200 with `pin_delivery.sent` false and why, so
      * the console shows it as a warning rather than an error.
      */
+    #[SkipAuthorizationCheck]
     public function sendPin(Request $request, string $id, string $linkId): JsonResponse
     {
+        Authorization::authorize('publish inspection-form');
+
         $form      = $this->resolveForm($id)->firstOrFail();
         $validated = $request->validate(['via' => 'required|in:email,sms']);
 
diff --git a/server/src/Http/Controllers/Internal/v1/LiveController.php b/server/src/Http/Controllers/Internal/v1/LiveController.php
index 1d8cdf7ac..5c8e8be74 100644
--- a/server/src/Http/Controllers/Internal/v1/LiveController.php
+++ b/server/src/Http/Controllers/Internal/v1/LiveController.php
@@ -15,6 +15,7 @@
 use Fleetbase\FleetOps\Models\Place;
 use Fleetbase\FleetOps\Models\Route;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\LiveCacheService;
 use Fleetbase\FleetOps\Support\LiveOrderQuery;
 use Fleetbase\FleetOps\Support\Utils;
@@ -37,6 +38,8 @@ class LiveController extends Controller
      */
     public function coordinates()
     {
+        Authorization::authorize('list order');
+
         return LiveCacheService::remember('coordinates', [], function () {
             $coordinates = [];
 
@@ -70,6 +73,8 @@ public function coordinates()
      */
     public function routes()
     {
+        Authorization::authorize('list order');
+
         return LiveCacheService::remember('routes', [], function () {
             // Fetch routes that are not canceled or completed and have an assigned driver
             $routes = Route::where('company_uuid', session('company'))
@@ -107,6 +112,8 @@ function ($q) {
      */
     public function orders(Request $request)
     {
+        Authorization::authorize('list order');
+
         $exclude     = $request->array('exclude');
         $active      = $request->boolean('active');
         $unassigned  = $request->boolean('unassigned');
@@ -142,6 +149,8 @@ public function orders(Request $request)
      */
     public function drivers(Request $request)
     {
+        Authorization::authorize('list driver');
+
         $bounds      = $this->normalizeLiveBounds($request);
         $limit       = $this->normalizeLiveLimit($request);
         $cacheParams = ['bounds' => $bounds, 'limit' => $limit];
@@ -169,6 +178,8 @@ public function drivers(Request $request)
      */
     public function vehicles(Request $request)
     {
+        Authorization::authorize('list vehicle');
+
         $bounds      = $this->normalizeLiveBounds($request);
         $limit       = $this->normalizeLiveLimit($request);
         $cacheParams = ['bounds' => $bounds, 'limit' => $limit];
@@ -197,6 +208,8 @@ public function vehicles(Request $request)
      */
     public function operationsMonitor()
     {
+        Authorization::authorize('list order');
+
         return LiveCacheService::remember('operations-monitor', [], function () {
             $drivers = Driver::where(['company_uuid' => session('company')])
                 ->with(['user', 'vehicle'])
@@ -370,6 +383,8 @@ protected function buildOperationsMonitorFleetTree($fleetNodes): array
      */
     public function places(Request $request)
     {
+        Authorization::authorize('list place');
+
         $bounds = $this->normalizeLiveBounds($request);
         $limit  = $this->normalizeLiveLimit($request);
 
diff --git a/server/src/Http/Controllers/Internal/v1/MaintenanceController.php b/server/src/Http/Controllers/Internal/v1/MaintenanceController.php
index e3153d45c..0f9344a12 100644
--- a/server/src/Http/Controllers/Internal/v1/MaintenanceController.php
+++ b/server/src/Http/Controllers/Internal/v1/MaintenanceController.php
@@ -2,10 +2,12 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Exports\MaintenanceExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Imports\MaintenanceImport;
 use Fleetbase\FleetOps\Models\Maintenance;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Illuminate\Http\JsonResponse;
@@ -67,8 +69,11 @@ public function onFindRecord($builder, $request): void
      * Add a cost line item to a maintenance record.
      * POST /maintenances/{id}/line-items.
      */
+    #[SkipAuthorizationCheck]
     public function addLineItem(string $id, Request $request): JsonResponse
     {
+        Authorization::authorize('update maintenance');
+
         $maintenance = $this->findMaintenanceForLineItem($id);
 
         $validated = $request->validate([
@@ -89,8 +94,11 @@ public function addLineItem(string $id, Request $request): JsonResponse
      * Update a cost line item on a maintenance record.
      * PUT /maintenances/{id}/line-items/{index}.
      */
+    #[SkipAuthorizationCheck]
     public function updateLineItem(string $id, int $index, Request $request): JsonResponse
     {
+        Authorization::authorize('update maintenance');
+
         $maintenance = $this->findMaintenanceForLineItem($id);
 
         $validated = $request->validate([
@@ -121,8 +129,11 @@ public function updateLineItem(string $id, int $index, Request $request): JsonRe
      * Remove a cost line item from a maintenance record.
      * DELETE /maintenances/{id}/line-items/{index}.
      */
+    #[SkipAuthorizationCheck]
     public function removeLineItem(string $id, int $index): JsonResponse
     {
+        Authorization::authorize('update maintenance');
+
         $maintenance = $this->findMaintenanceForLineItem($id);
 
         if (!$maintenance->removeLineItem($index)) {
diff --git a/server/src/Http/Controllers/Internal/v1/MaintenanceScheduleController.php b/server/src/Http/Controllers/Internal/v1/MaintenanceScheduleController.php
index 15cfa292b..fe930c9f8 100644
--- a/server/src/Http/Controllers/Internal/v1/MaintenanceScheduleController.php
+++ b/server/src/Http/Controllers/Internal/v1/MaintenanceScheduleController.php
@@ -2,11 +2,13 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Exports\MaintenanceScheduleExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Imports\MaintenanceScheduleImport;
 use Fleetbase\FleetOps\Models\MaintenanceSchedule;
 use Fleetbase\FleetOps\Models\WorkOrder;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Illuminate\Http\JsonResponse;
@@ -71,8 +73,11 @@ public function import(ImportRequest $request)
      * Pause a maintenance schedule.
      * POST /maintenance-schedules/{id}/pause.
      */
+    #[SkipAuthorizationCheck]
     public function pause(string $id): JsonResponse
     {
+        Authorization::authorize('update maintenance-schedule');
+
         $schedule = $this->findSchedule($id);
 
         $schedule->pause();
@@ -88,8 +93,11 @@ public function pause(string $id): JsonResponse
      * Resume a paused maintenance schedule.
      * POST /maintenance-schedules/{id}/resume.
      */
+    #[SkipAuthorizationCheck]
     public function resume(string $id): JsonResponse
     {
+        Authorization::authorize('update maintenance-schedule');
+
         $schedule = $this->findSchedule($id);
 
         $schedule->resume();
@@ -105,8 +113,11 @@ public function resume(string $id): JsonResponse
      * Manually trigger a work order from a schedule.
      * POST /maintenance-schedules/{id}/trigger.
      */
+    #[SkipAuthorizationCheck]
     public function trigger(string $id, Request $request): JsonResponse
     {
+        Authorization::authorize('update maintenance-schedule');
+
         $schedule  = $this->findSchedule($id);
         $workOrder = $this->createWorkOrderFromSchedule($schedule);
 
diff --git a/server/src/Http/Controllers/Internal/v1/ManifestController.php b/server/src/Http/Controllers/Internal/v1/ManifestController.php
index 80f003605..dbd93c044 100644
--- a/server/src/Http/Controllers/Internal/v1/ManifestController.php
+++ b/server/src/Http/Controllers/Internal/v1/ManifestController.php
@@ -4,6 +4,7 @@
 
 use Fleetbase\FleetOps\Models\Manifest;
 use Fleetbase\FleetOps\Models\ManifestStop;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Controllers\Controller;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -31,6 +32,8 @@ class ManifestController extends Controller
      */
     public function index(Request $request): JsonResponse
     {
+        Authorization::authorize('list order');
+
         $companyUuid = session('company');
         $query       = $this->manifestQueryForCompany($companyUuid);
 
@@ -59,6 +62,8 @@ public function index(Request $request): JsonResponse
      */
     public function show(string $id): JsonResponse
     {
+        Authorization::authorize('view order');
+
         $manifest = $this->manifestQueryByPublicId($id)
             ->with($this->manifestShowRelations())
             ->firstOrFail();
@@ -73,6 +78,8 @@ public function show(string $id): JsonResponse
      */
     public function cancel(string $id): JsonResponse
     {
+        Authorization::authorize('cancel order');
+
         $manifest = $this->manifestQueryByPublicId($id)->firstOrFail();
         $manifest->cancel();
 
@@ -86,6 +93,8 @@ public function cancel(string $id): JsonResponse
      */
     public function destroy(string $id): JsonResponse
     {
+        Authorization::authorize('delete order');
+
         $manifest = $this->manifestQueryByPublicId($id)->firstOrFail();
         $manifest->delete();
 
@@ -99,6 +108,8 @@ public function destroy(string $id): JsonResponse
      */
     public function showStop(string $id): JsonResponse
     {
+        Authorization::authorize('view order');
+
         $stop = $this->manifestStopQueryByPublicId($id)
             ->with(['place', 'order.trackingNumber', 'order.payload.dropoff', 'waypoint'])
             ->firstOrFail();
@@ -115,6 +126,8 @@ public function showStop(string $id): JsonResponse
      */
     public function updateStop(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update order');
+
         $stop = $this->manifestStopQueryByPublicId($id)->firstOrFail();
 
         $allowed = ['status', 'sequence', 'actual_arrival', 'meta'];
diff --git a/server/src/Http/Controllers/Internal/v1/MetricsController.php b/server/src/Http/Controllers/Internal/v1/MetricsController.php
index f61a5e637..4d3b374fd 100644
--- a/server/src/Http/Controllers/Internal/v1/MetricsController.php
+++ b/server/src/Http/Controllers/Internal/v1/MetricsController.php
@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Metrics;
 use Fleetbase\FleetOps\Support\Metrics\Registry;
 use Fleetbase\Http\Controllers\Controller;
@@ -10,6 +11,16 @@
 
 class MetricsController extends Controller
 {
+    public function __construct()
+    {
+        // Not a resource controller, so AuthorizationGuard cannot resolve a permission for it.
+        $this->middleware(function ($request, $next) {
+            Authorization::authorize('view analytics');
+
+            return $next($request);
+        });
+    }
+
     /**
      * Legacy bulk endpoint. Returns a flat map of slug → scalar value for the
      * requested period. Preserved for backward compat; the dashboard widgets
diff --git a/server/src/Http/Controllers/Internal/v1/NavigatorController.php b/server/src/Http/Controllers/Internal/v1/NavigatorController.php
index 868f7b56a..9cf8fb197 100644
--- a/server/src/Http/Controllers/Internal/v1/NavigatorController.php
+++ b/server/src/Http/Controllers/Internal/v1/NavigatorController.php
@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Http\Resources\Organization;
@@ -11,6 +12,7 @@
 use Fleetbase\Models\User;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Redirect;
+use Illuminate\Support\Facades\URL;
 use Illuminate\Support\Str;
 
 class NavigatorController extends Controller
@@ -23,6 +25,12 @@ class NavigatorController extends Controller
      */
     public function linkApp(Request $request)
     {
+        // This route is opened from a phone without a console session, so it is
+        // authorised by the short-lived signature issued by getLinkAppUrl().
+        if (!$request->hasValidRelativeSignature()) {
+            return response()->error('This Navigator link is invalid or has expired. Generate a new one from the console.', 403);
+        }
+
         $adminUser = $this->findAdminUser();
 
         if (!$adminUser || !$adminUser->company) {
@@ -67,8 +75,12 @@ public function linkApp(Request $request)
      */
     public function getLinkAppUrl()
     {
+        Authorization::authorizeAdmin();
+
+        $path = URL::temporarySignedRoute('fleetops.navigator.link-app', now()->addMinutes(30), [], false);
+
         return response()->json([
-            'linkUrl' => url('int/v1/fleet-ops/navigator/link-app'),
+            'linkUrl' => url($path),
         ]);
     }
 
diff --git a/server/src/Http/Controllers/Internal/v1/OrchestrationController.php b/server/src/Http/Controllers/Internal/v1/OrchestrationController.php
index a4e011d47..2e795fd65 100644
--- a/server/src/Http/Controllers/Internal/v1/OrchestrationController.php
+++ b/server/src/Http/Controllers/Internal/v1/OrchestrationController.php
@@ -16,6 +16,7 @@
 use Fleetbase\FleetOps\Orchestration\Engines\DriverAssignmentEngine;
 use Fleetbase\FleetOps\Orchestration\Engines\RouteSequencingEngine;
 use Fleetbase\FleetOps\Orchestration\OrchestrationEngineRegistry;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Models\Setting;
 use Illuminate\Http\JsonResponse;
@@ -54,6 +55,8 @@ public function __construct(protected OrchestrationEngineRegistry $registry)
      */
     public function orders(Request $request): JsonResponse
     {
+        Authorization::authorize('list order');
+
         $companyUuid = $this->companyUuid();
 
         $query = $this->orchestratorOrdersQuery($companyUuid);
@@ -118,6 +121,8 @@ public function orders(Request $request): JsonResponse
      */
     public function run(Request $request): JsonResponse
     {
+        Authorization::authorize('optimize order');
+
         $companyUuid       = $this->companyUuid();
         $mode              = $request->input('mode', 'assign_vehicles');
         $orderIds          = $request->input('order_ids', []);
@@ -323,6 +328,8 @@ public function run(Request $request): JsonResponse
      */
     public function preview(Request $request): JsonResponse
     {
+        Authorization::authorize('list order');
+
         return $this->run($request);
     }
 
@@ -395,6 +402,8 @@ protected function routeSequencingEngine(): RouteSequencingEngine
      */
     public function commit(Request $request): JsonResponse
     {
+        Authorization::authorize('assign-driver-for order');
+
         $assignments   = $request->input('assignments', []);
         $scheduledDate = $request->input('scheduled_date', now()->toDateString());
         $companyUuid   = session('company');
@@ -578,6 +587,8 @@ protected function updateWaypointSequence(string $payloadUuid, string $waypointP
      */
     public function engines(): JsonResponse
     {
+        Authorization::authorize('list order');
+
         return response()->json([
             'engines' => $this->registry->available(),
         ]);
@@ -591,6 +602,8 @@ public function engines(): JsonResponse
      */
     public function orderConfigFields(): JsonResponse
     {
+        Authorization::authorize('list order');
+
         $companyUuid = session('company');
 
         $configs = $this->getOrderConfigFieldConfigs($companyUuid)
@@ -648,6 +661,8 @@ protected function getCustomFieldsForOrderConfig(string $orderConfigUuid)
      */
     public function importOrders(Request $request): JsonResponse
     {
+        Authorization::authorize('import order');
+
         $rows        = $request->input('rows', []);
         $companyUuid = session('company');
 
diff --git a/server/src/Http/Controllers/Internal/v1/OrderController.php b/server/src/Http/Controllers/Internal/v1/OrderController.php
index 2751c2114..6f69fc5cd 100644
--- a/server/src/Http/Controllers/Internal/v1/OrderController.php
+++ b/server/src/Http/Controllers/Internal/v1/OrderController.php
@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\Exceptions\FleetbaseRequestValidationException;
 use Fleetbase\FleetOps\Events\EntityActivityChanged;
 use Fleetbase\FleetOps\Events\EntityCompleted;
@@ -32,6 +33,7 @@
 use Fleetbase\FleetOps\Models\TrackingStatus;
 use Fleetbase\FleetOps\Models\Waypoint;
 use Fleetbase\FleetOps\Notifications\OrderPing;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\ResolvesOrderServiceStops;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
@@ -267,8 +269,11 @@ protected function normalizeCustomerType(array &$input): void
      *
      * @return Response
      */
+    #[SkipAuthorizationCheck]
     public function editOrderRoute(string $id, Request $request)
     {
+        Authorization::authorize('update-route-for order');
+
         $pickup            = $request->input('pickup');
         $dropoff           = $request->input('dropoff');
         $return            = $request->input('return');
@@ -337,8 +342,11 @@ public function editOrderRoute(string $id, Request $request)
      *
      * @return \Illuminate\Http\Response
      */
+    #[SkipAuthorizationCheck]
     public function importFromFiles(Request $request)
     {
+        Authorization::authorize('import order');
+
         $info    = Utils::lookupIp();
         $disk    = $request->input('disk', config('filesystems.default'));
         $files   = $request->input('files');
@@ -409,8 +417,11 @@ public function importFromFiles(Request $request)
      *
      * @return \Illuminate\Http\Response
      */
+    #[SkipAuthorizationCheck]
     public function bulkCancel(Request $request)
     {
+        Authorization::authorize('cancel order');
+
         $request->validate([
             'ids' => ['required', 'array'],
         ]);
@@ -454,8 +465,11 @@ public function bulkCancel(Request $request)
      *
      * @return \Illuminate\Http\Response
      */
+    #[SkipAuthorizationCheck]
     public function bulkDispatch(BulkDispatchRequest $request)
     {
+        Authorization::authorize('dispatch order');
+
         /** @var Order */
         $orders = $this->ordersByUuid($request->input('ids'));
 
@@ -502,8 +516,11 @@ public function bulkDispatch(BulkDispatchRequest $request)
      *
      * @return \Illuminate\Http\Response
      */
+    #[SkipAuthorizationCheck]
     public function bulkAssignDriver(Request $request)
     {
+        Authorization::authorize('assign-driver-for order');
+
         // Validate Inputs
         $data = $this->validateBulkAssignDriverRequest($request);
 
@@ -578,8 +595,11 @@ public function cancel(CancelOrderRequest $request)
      *
      * @return \Illuminate\Http\Response
      */
+    #[SkipAuthorizationCheck]
     public function dispatchOrder(Request $request)
     {
+        Authorization::authorize('dispatch order');
+
         /**
          * @var Order
          */
@@ -1906,8 +1926,11 @@ function ($query) use ($trackingNumber) {
      *
      * @return \Illuminate\Http\Response
      */
+    #[SkipAuthorizationCheck]
     public function scheduleOrder(Request $request)
     {
+        Authorization::authorize('schedule order');
+
         $orderId     = $request->input('order');
         $scheduledAt = $request->input('scheduled_at');
         $driverId    = $request->input('driver_id');
diff --git a/server/src/Http/Controllers/Internal/v1/PaymentController.php b/server/src/Http/Controllers/Internal/v1/PaymentController.php
index 703bbb283..d4e668005 100644
--- a/server/src/Http/Controllers/Internal/v1/PaymentController.php
+++ b/server/src/Http/Controllers/Internal/v1/PaymentController.php
@@ -3,6 +3,7 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\FleetOps\Models\PurchaseRate;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Payment;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Http\Resources\FleetbaseResource;
@@ -21,6 +22,8 @@ class PaymentController extends Controller
      */
     public function hasStripeConnectAccount()
     {
+        Authorization::authorize('view payments');
+
         $company = $this->getCompany();
         if ($company) {
             return $this->jsonResponse([
@@ -43,6 +46,8 @@ public function hasStripeConnectAccount()
      */
     public function getStripeAccount()
     {
+        Authorization::authorize('onboard payments');
+
         $stripe = $this->stripeClient();
 
         try {
@@ -84,6 +89,8 @@ public function getStripeAccount()
      */
     public function getStripeAccountSession(Request $request)
     {
+        Authorization::authorize('onboard payments');
+
         $stripe  = $this->stripeClient();
         $company = $this->getCompany();
 
@@ -112,6 +119,8 @@ public function getStripeAccountSession(Request $request)
      */
     public function getCompanyReceivedPayments(Request $request)
     {
+        Authorization::authorize('view payments');
+
         $limit     = $request->input('limit', 30);
         $query     = PurchaseRate::select(
             [
diff --git a/server/src/Http/Controllers/Internal/v1/RadarController.php b/server/src/Http/Controllers/Internal/v1/RadarController.php
index a43e2d401..6251fd684 100644
--- a/server/src/Http/Controllers/Internal/v1/RadarController.php
+++ b/server/src/Http/Controllers/Internal/v1/RadarController.php
@@ -14,6 +14,7 @@
 use Fleetbase\FleetOps\Models\Trailer;
 use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\FleetOps\Models\WorkOrder;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\LiveOrderQuery;
 use Fleetbase\FleetOps\Support\Radar\RadarAgenda;
 use Fleetbase\FleetOps\Support\Radar\RadarBriefing;
@@ -182,6 +183,8 @@ public function handoverSuggest(Request $request, string $key): JsonResponse
      */
     public function extendShift(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update driver', 'update vehicle');
+
         $minutes = (int) $request->input('minutes', 60);
         if ($minutes < 1 || $minutes > 24 * 60) {
             return response()->json(['error' => 'minutes must be between 1 and 1440.'], 422);
@@ -211,6 +214,8 @@ public function extendShift(Request $request, string $id): JsonResponse
 
     public function acknowledge(Request $request, string $key): JsonResponse
     {
+        Authorization::authorize('update driver', 'update vehicle');
+
         return $this->act($request, $key, function (Alert $row) use ($request) {
             RadarItemState::acknowledge($row, $this->actor($request));
         });
@@ -218,6 +223,8 @@ public function acknowledge(Request $request, string $key): JsonResponse
 
     public function snooze(Request $request, string $key): JsonResponse
     {
+        Authorization::authorize('update driver', 'update vehicle');
+
         $minutes = $this->snoozeMinutes($request);
         if ($minutes === null) {
             return response()->json(['error' => 'Pass minutes (1 to ' . (self::SNOOZE_MAX_DAYS * 1440) . ') or a future until date.'], 422);
@@ -230,6 +237,8 @@ public function snooze(Request $request, string $key): JsonResponse
 
     public function wake(Request $request, string $key): JsonResponse
     {
+        Authorization::authorize('update driver', 'update vehicle');
+
         return $this->act($request, $key, function (Alert $row) {
             RadarItemState::wake($row);
         }, false);
@@ -237,6 +246,8 @@ public function wake(Request $request, string $key): JsonResponse
 
     public function assign(Request $request, string $key): JsonResponse
     {
+        Authorization::authorize('update driver', 'update vehicle');
+
         $company  = $this->companyUuid($request);
         $assignee = null;
 
@@ -254,6 +265,8 @@ public function assign(Request $request, string $key): JsonResponse
 
     public function plan(Request $request, string $key): JsonResponse
     {
+        Authorization::authorize('update driver', 'update vehicle');
+
         $plannedAt = null;
         if ($request->filled('planned_at')) {
             $plannedAt = RadarRules::carbon($request->input('planned_at'));
@@ -273,6 +286,8 @@ public function plan(Request $request, string $key): JsonResponse
      */
     public function resolve(Request $request, string $key): JsonResponse
     {
+        Authorization::authorize('update driver', 'update vehicle');
+
         $parsed = RadarRules::parseKey($key);
         if (!$parsed || $parsed[0] !== 'notice') {
             return response()->json(['error' => 'Only notices resolve by hand; other items close when their record changes.'], 422);
@@ -288,6 +303,8 @@ public function resolve(Request $request, string $key): JsonResponse
      */
     public function bulk(Request $request): JsonResponse
     {
+        Authorization::authorize('update driver', 'update vehicle');
+
         $keys   = array_values(array_filter((array) $request->input('keys', []), 'is_string'));
         $action = (string) $request->input('action');
 
@@ -350,6 +367,8 @@ public function bulk(Request $request): JsonResponse
      */
     public function storeNotice(Request $request): JsonResponse
     {
+        Authorization::authorize('update driver', 'update vehicle');
+
         $message  = trim((string) $request->input('message'));
         $severity = in_array($request->input('severity'), [RadarRules::SEVERITY_CRITICAL, RadarRules::SEVERITY_WARNING, RadarRules::SEVERITY_INFO], true) ? $request->input('severity') : RadarRules::SEVERITY_INFO;
         $dueAt    = $request->filled('due_at') ? RadarRules::carbon($request->input('due_at')) : null;
@@ -392,6 +411,8 @@ public function storeNotice(Request $request): JsonResponse
 
     public function destroyNotice(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update driver', 'update vehicle');
+
         $company = $this->companyUuid($request);
         $alert   = $this->findNotice($company, $id);
 
diff --git a/server/src/Http/Controllers/Internal/v1/SettingController.php b/server/src/Http/Controllers/Internal/v1/SettingController.php
index 3a1c568e5..75d1cb175 100644
--- a/server/src/Http/Controllers/Internal/v1/SettingController.php
+++ b/server/src/Http/Controllers/Internal/v1/SettingController.php
@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Tracking\TrackingProviderRegistry;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Models\Setting;
@@ -21,37 +22,56 @@ class SettingController extends Controller
      */
     public function saveEntityEditingSettings(Request $request)
     {
-        $entityEditingSettings  = $request->input('entityEditingSettings', []);
+        Authorization::authorize('update navigator-settings');
 
-        // Save entity editing settings
-        $this->configureSetting('fleet-ops.entity-editing-settings', $entityEditingSettings);
+        // The setting is one platform-wide map keyed by order config id. Only this
+        // company's order configs may be written, and other companies' entries are kept.
+        $ownKeys  = $this->companyOrderConfigKeys();
+        $incoming = array_intersect_key((array) $request->input('entityEditingSettings', []), array_flip($ownKeys));
+        $existing = (array) ($this->settingValue('fleet-ops.entity-editing-settings') ?? []);
+        $merged   = array_merge(array_diff_key($existing, array_flip($ownKeys)), $incoming);
 
-        return response()->json(['entityEditingSettings' => $entityEditingSettings]);
+        $this->configureSetting('fleet-ops.entity-editing-settings', $merged);
+
+        return response()->json(['entityEditingSettings' => $incoming]);
     }
 
     /**
-     * Retrieve entity editing settings.
+     * Retrieve entity editing settings for this company's order configs.
      *
      * @return \Illuminate\Http\JsonResponse
      */
     public function getEntityEditingSettings()
     {
-        $entityEditingSettings  = $this->settingValue('fleet-ops.entity-editing-settings');
-        if (!$entityEditingSettings) {
-            $entityEditingSettings = [];
-        }
+        $entityEditingSettings = (array) ($this->settingValue('fleet-ops.entity-editing-settings') ?? []);
+        $entityEditingSettings = array_intersect_key($entityEditingSettings, array_flip($this->companyOrderConfigKeys()));
 
         return response()->json(['entityEditingSettings' => $entityEditingSettings]);
     }
 
     /**
-     * Retrieve driver onboard settings.
+     * Ids (uuid and public id) of the session company's order configs.
+     */
+    protected function companyOrderConfigKeys(): array
+    {
+        return \Fleetbase\FleetOps\Models\OrderConfig::where('company_uuid', session('company'))
+            ->get(['uuid', 'public_id'])
+            ->flatMap(fn ($config) => array_filter([$config->uuid, $config->public_id]))
+            ->values()
+            ->all();
+    }
+
+    /**
+     * Retrieve driver onboard settings for the session company.
+     *
+     * The route still carries a company id for backwards compatibility, but only
+     * the session company's settings are ever returned.
      *
      * @return \Illuminate\Http\JsonResponse
      */
-    public function getDriverOnboardSettings($companyId)
+    public function getDriverOnboardSettings($companyId = null)
     {
-        $driverOnboardSettings  = $this->settingValue('fleet-ops.driver-onboard-settings.' . $companyId);
+        $driverOnboardSettings  = $this->settingValue('fleet-ops.driver-onboard-settings.' . session('company'));
         if (!$driverOnboardSettings) {
             $driverOnboardSettings = [];
         }
@@ -66,9 +86,12 @@ public function getDriverOnboardSettings($companyId)
      */
     public function savedDriverOnboardSettings(Request $request)
     {
-        $driverOnboardSettings = $request->array('driverOnboardSettings', []);
+        Authorization::authorize('update navigator-settings');
 
-        if ($driverOnboardSettings['enableDriverOnboardFromApp'] == false) {
+        $driverOnboardSettings              = $request->array('driverOnboardSettings', []);
+        $driverOnboardSettings['companyId'] = session('company');
+
+        if (empty($driverOnboardSettings['enableDriverOnboardFromApp'])) {
             $driverOnboardSettings['driverMustProvideOnboardDoucments'] = false;
             $driverOnboardSettings['requiredOnboardDocuments']          = [];
             $driverOnboardSettings['driverOnboardAppMethod']            = '';
@@ -82,6 +105,8 @@ public function savedDriverOnboardSettings(Request $request)
 
     public function saveCustomerEnabledOrderConfigs(Request $request)
     {
+        Authorization::authorize('update order-config');
+
         $enabledOrderConfigs = array_values($request->array('enabledOrderConfigs'));
         $this->configureCompanySetting('fleet-ops.customer-enabled-order-configs', $enabledOrderConfigs);
 
@@ -97,6 +122,8 @@ public function getCustomerEnabledOrderConfigs()
 
     public function saveCustomerPortalPaymentConfig(Request $request)
     {
+        Authorization::authorize('update payments');
+
         $paymentsConfig = $request->array('paymentsConfig');
         $this->configureCompanySetting('fleet-ops.customer-payments-configs', $paymentsConfig);
 
@@ -147,6 +174,8 @@ public function getNotificationRegistry()
      */
     public function saveNotificationSettings(Request $request)
     {
+        Authorization::authorize('update notification-settings');
+
         $notificationSettings = $request->input('notificationSettings');
         if (!is_array($notificationSettings)) {
             throw new \Exception('Invalid notification settings data.');
@@ -185,6 +214,8 @@ public function getNotificationSettings()
      */
     public function saveRoutingSettings(Request $request)
     {
+        Authorization::authorize('update routing-settings');
+
         $displayEngine      = $request->input('display_engine', $request->input('router', 'osrm'));
         $optimizationEngine = $request->input('optimization_engine', $displayEngine);
         $unit               = $request->input('unit', 'km');
@@ -237,6 +268,8 @@ public function getRoutingSettings()
      */
     public function saveTrackingSettings(Request $request)
     {
+        Authorization::authorize('update tracking-settings');
+
         $config    = $this->trackingDefaults();
         $fallbacks = $request->input('fallbacks', data_get($config, 'fallbacks', ['osrm', 'calculated']));
         if (is_string($fallbacks)) {
@@ -286,6 +319,8 @@ public function getTrackingSettings()
 
     public function getAdminTrackingSettings()
     {
+        Authorization::authorizeAdmin();
+
         return response()->json(array_merge($this->trackingDefaults(), [
             'providers' => $this->trackingProviderOptions(),
         ]));
@@ -293,6 +328,8 @@ public function getAdminTrackingSettings()
 
     public function saveAdminTrackingSettings(Request $request)
     {
+        Authorization::authorizeAdmin();
+
         $config    = config('fleetops.tracking', []);
         $fallbacks = $request->input('fallbacks', data_get($config, 'fallbacks', ['osrm', 'calculated']));
         if (is_string($fallbacks)) {
@@ -361,6 +398,8 @@ public function getMapSettings()
      */
     public function saveMapSettings(Request $request)
     {
+        Authorization::authorize('update map-settings');
+
         $settings = $request->input('settings', []);
 
         // The API key is managed at the system level via core-api — strip it
@@ -377,6 +416,8 @@ public function saveMapSettings(Request $request)
 
     public function getAdminMapSettings()
     {
+        Authorization::authorizeAdmin();
+
         $defaults = [
             'mapProvider'     => 'leaflet',
             'googleMapsMapId' => '',
@@ -387,6 +428,8 @@ public function getAdminMapSettings()
 
     public function saveAdminMapSettings(Request $request)
     {
+        Authorization::authorizeAdmin();
+
         $allowedProviders = ['leaflet', 'google'];
         $mapProvider      = $request->input('mapProvider', 'leaflet');
         if (!in_array($mapProvider, $allowedProviders)) {
@@ -473,6 +516,8 @@ public function getSchedulingSettings()
      */
     public function saveSchedulingSettings(Request $request)
     {
+        Authorization::authorize('update scheduling-settings');
+
         $settings = [
             'horizon_days'                   => (int) $request->input('horizon_days', 60),
             'default_shift_duration'         => (int) $request->input('default_shift_duration', 8),
@@ -512,6 +557,8 @@ public function getOrchestratorSettings()
      */
     public function saveOrchestratorSettings(Request $request)
     {
+        Authorization::authorize('update routing-settings');
+
         $settings = [
             'allocation_engine'           => $request->input('allocation_engine', 'vroom'),
             'auto_allocate_on_create'     => (bool) $request->input('auto_allocate_on_create', false),
@@ -548,6 +595,8 @@ public function getOrchestratorCardFields()
      */
     public function saveOrchestratorCardFields(Request $request)
     {
+        Authorization::authorize('update routing-settings');
+
         $settings = $request->input('settings', []);
 
         $normalized = [
diff --git a/server/src/Http/Controllers/Internal/v1/TelematicController.php b/server/src/Http/Controllers/Internal/v1/TelematicController.php
index acb8dc5fa..7d778a565 100644
--- a/server/src/Http/Controllers/Internal/v1/TelematicController.php
+++ b/server/src/Http/Controllers/Internal/v1/TelematicController.php
@@ -2,9 +2,11 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Exports\TelematicExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
 use Fleetbase\FleetOps\Support\Telematics\TelematicService;
 use Fleetbase\Http\Requests\ExportRequest;
@@ -71,8 +73,11 @@ public function providers(): JsonResponse
     /**
      * Test connection to provider.
      */
+    #[SkipAuthorizationCheck]
     public function testConnection(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update telematic');
+
         $telematic = $this->findTelematic($id);
 
         $async = $request->input('async', false);
@@ -89,8 +94,11 @@ public function testConnection(Request $request, string $id): JsonResponse
     /**
      * Test connection to provider.
      */
+    #[SkipAuthorizationCheck]
     public function testCredentials(Request $request, string $key): JsonResponse
     {
+        Authorization::authorize('create telematic');
+
         $credentials = $request->array('credentials', []);
         $async       = $request->input('async', false);
 
@@ -120,8 +128,11 @@ public function testCredentials(Request $request, string $key): JsonResponse
     /**
      * Discover devices from provider.
      */
+    #[SkipAuthorizationCheck]
     public function discover(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update telematic');
+
         $telematic = $this->findTelematic($id);
 
         $jobId = $this->telematicService->discoverDevices($telematic, [
@@ -181,8 +192,11 @@ public function logs(Request $request, string $id): JsonResponse
     /**
      * Link a device to a telematic.
      */
+    #[SkipAuthorizationCheck]
     public function linkDevice(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update telematic');
+
         $telematic = $this->findTelematic($id);
 
         $request->validate([
@@ -199,8 +213,11 @@ public function linkDevice(Request $request, string $id): JsonResponse
         ], 201);
     }
 
+    #[SkipAuthorizationCheck]
     public function telemetryWebhook(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update telematic');
+
         $telematic = $this->findTelematic($id);
         $provider  = $this->registry->resolve($telematic->provider);
         abort_unless($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface, 422);
@@ -248,8 +265,11 @@ public function telemetryDiagnostics(string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function replayTelemetryDelivery(string $id, string $delivery): JsonResponse
     {
+        Authorization::authorize('update telematic');
+
         $telematic = $this->findTelematic($id);
         $provider  = $this->registry->resolve($telematic->provider);
         abort_unless($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface, 422);
diff --git a/server/src/Http/Controllers/Internal/v1/TrailerController.php b/server/src/Http/Controllers/Internal/v1/TrailerController.php
index 728cd1cc8..029b4a417 100644
--- a/server/src/Http/Controllers/Internal/v1/TrailerController.php
+++ b/server/src/Http/Controllers/Internal/v1/TrailerController.php
@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Exceptions\DeviceAlreadyAttachedException;
 use Fleetbase\FleetOps\Exports\TrailerExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
@@ -13,6 +14,7 @@
 use Fleetbase\FleetOps\Models\Equipment;
 use Fleetbase\FleetOps\Models\Trailer;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Fleetbase\Support\Resolve;
@@ -69,8 +71,11 @@ protected function deleteTrailerRecord($id, Request $request)
     /**
      * Attach the trailer to a vehicle. Re-attaching to the same vehicle is idempotent.
      */
+    #[SkipAuthorizationCheck]
     public function attach(Request $request, string $id)
     {
+        Authorization::authorize('attach-vehicle-for trailer');
+
         $request->validate(['vehicle' => ['required', 'string'], 'position' => ['nullable', 'integer', 'min:1']]);
 
         $trailer = $this->resolveTrailer($id);
@@ -134,8 +139,11 @@ public function attach(Request $request, string $id)
     /**
      * End the active towing connection. Detaching an unattached trailer is a no-op.
      */
+    #[SkipAuthorizationCheck]
     public function detach(string $id)
     {
+        Authorization::authorize('detach-vehicle-for trailer');
+
         $trailer = $this->resolveTrailer($id);
 
         if (!$trailer) {
@@ -157,8 +165,11 @@ public function detach(string $id)
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function attachDevice(Request $request, string $id)
     {
+        Authorization::authorize('attach-device-for trailer');
+
         $request->validate(['device' => ['required', 'string']]);
 
         $trailer = $this->resolveTrailer($id);
@@ -186,8 +197,11 @@ public function attachDevice(Request $request, string $id)
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function detachDevice(Request $request, string $id)
     {
+        Authorization::authorize('detach-device-for trailer');
+
         $request->validate(['device' => ['required', 'string']]);
 
         $trailer = $this->resolveTrailer($id);
@@ -215,8 +229,11 @@ public function detachDevice(Request $request, string $id)
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function attachEquipment(Request $request, string $id)
     {
+        Authorization::authorize('attach-equipment-for trailer');
+
         $request->validate(['equipment' => ['required', 'string']]);
 
         $trailer   = $this->resolveTrailer($id);
@@ -242,8 +259,11 @@ public function attachEquipment(Request $request, string $id)
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function detachEquipment(Request $request, string $id)
     {
+        Authorization::authorize('detach-equipment-for trailer');
+
         $request->validate(['equipment' => ['required', 'string']]);
 
         $trailer   = $this->resolveTrailer($id);
diff --git a/server/src/Http/Controllers/Internal/v1/VehicleController.php b/server/src/Http/Controllers/Internal/v1/VehicleController.php
index 9678a9b3b..ccb861e71 100644
--- a/server/src/Http/Controllers/Internal/v1/VehicleController.php
+++ b/server/src/Http/Controllers/Internal/v1/VehicleController.php
@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Exceptions\DeviceAlreadyAttachedException;
 use Fleetbase\FleetOps\Exports\VehicleExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
@@ -12,6 +13,7 @@
 use Fleetbase\FleetOps\Models\Equipment;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Fleetbase\Support\Resolve;
@@ -111,8 +113,11 @@ public function assignDriver(Request $request, string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function unassignDriver(string $id): JsonResponse
     {
+        Authorization::authorize('assign-driver-for vehicle');
+
         $vehicle = $this->findVehicle($id);
         $vehicle->unassignDriver();
         $vehicle->load(['driver', 'devices']);
@@ -143,8 +148,11 @@ public function assignedOrders(string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function unassignOrders(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update vehicle');
+
         $request->validate([
             'orders'   => 'required|array|min:1',
             'orders.*' => 'required|string',
@@ -179,8 +187,11 @@ public function unassignOrders(Request $request, string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function attachDevice(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update vehicle');
+
         $request->validate(['device' => 'required|string']);
 
         $deviceId = $request->input('device');
@@ -219,8 +230,11 @@ public function attachDevice(Request $request, string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function detachDevice(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update vehicle');
+
         $request->validate(['device' => 'required|string']);
 
         $deviceId = $request->input('device');
@@ -265,8 +279,11 @@ public function detachDevice(Request $request, string $id): JsonResponse
      * Attach equipment to the vehicle. Equipment can only be equipped to one asset at a
      * time, so attaching moves it from any previous vehicle or trailer.
      */
+    #[SkipAuthorizationCheck]
     public function attachEquipment(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update vehicle');
+
         $request->validate(['equipment' => 'required|string']);
 
         $vehicle   = $this->resolveVehicle($id);
@@ -292,8 +309,11 @@ public function attachEquipment(Request $request, string $id): JsonResponse
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function detachEquipment(Request $request, string $id): JsonResponse
     {
+        Authorization::authorize('update vehicle');
+
         $request->validate(['equipment' => 'required|string']);
 
         $vehicle   = $this->resolveVehicle($id);
diff --git a/server/src/Http/Controllers/Internal/v1/VendorController.php b/server/src/Http/Controllers/Internal/v1/VendorController.php
index a4e02a2ea..7cc3d69d5 100644
--- a/server/src/Http/Controllers/Internal/v1/VendorController.php
+++ b/server/src/Http/Controllers/Internal/v1/VendorController.php
@@ -2,6 +2,7 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Exports\VendorExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Http\Resources\v1\Contact as ContactResource;
@@ -10,6 +11,7 @@
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Vendor;
 use Fleetbase\FleetOps\Models\VendorPersonnel;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Illuminate\Http\Request;
@@ -128,8 +130,11 @@ public function import(ImportRequest $request)
      *
      * @return \Illuminate\Http\Response
      */
+    #[SkipAuthorizationCheck]
     public function assignDriver(string $id, Request $request)
     {
+        Authorization::authorize('update vendor');
+
         // Validate only param
         if (!$request->isUuid('driver')) {
             return response()->error('No driver selected to assign to vendor.');
@@ -160,8 +165,11 @@ public function assignDriver(string $id, Request $request)
      *
      * @return \Illuminate\Http\Response
      */
+    #[SkipAuthorizationCheck]
     public function removeDriver(string $id, Request $request)
     {
+        Authorization::authorize('update vendor');
+
         // Validate only param
         if (!$request->isUuid('driver')) {
             return response()->error('No driver selected to remove from vendor.');
@@ -197,8 +205,11 @@ public function vendorPersonnels(string $vendorId)
         return response()->json(['personnels' => $personnels->values()]);
     }
 
+    #[SkipAuthorizationCheck]
     public function addVendorPersonnel(Request $request, string $vendorId)
     {
+        Authorization::authorize('update vendor');
+
         $vendor  = $this->findVendorByIdOrFail($vendorId);
         $contact = $this->resolveOrCreatePersonnelContact($request);
 
@@ -220,8 +231,11 @@ public function addVendorPersonnel(Request $request, string $vendorId)
         ]);
     }
 
+    #[SkipAuthorizationCheck]
     public function removeVendorPersonnel(string $vendorId, string $contactId)
     {
+        Authorization::authorize('update vendor');
+
         $vendor  = $this->findVendorByIdOrFail($vendorId);
         $contact = $this->findContactByIdOrFail($contactId);
 
diff --git a/server/src/Http/Controllers/Internal/v1/WorkOrderController.php b/server/src/Http/Controllers/Internal/v1/WorkOrderController.php
index 51d917245..2bb304fa0 100644
--- a/server/src/Http/Controllers/Internal/v1/WorkOrderController.php
+++ b/server/src/Http/Controllers/Internal/v1/WorkOrderController.php
@@ -2,11 +2,13 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
+use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Exports\WorkOrderExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Imports\WorkOrderImport;
 use Fleetbase\FleetOps\Mail\WorkOrderDispatched;
 use Fleetbase\FleetOps\Models\WorkOrder;
+use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Illuminate\Http\JsonResponse;
@@ -80,8 +82,11 @@ protected function importFile(WorkOrderImport $import, string $path, string $dis
      * Send a work order email to the assigned vendor.
      * POST /work-orders/{id}/send.
      */
+    #[SkipAuthorizationCheck]
     public function sendEmail(string $id): JsonResponse
     {
+        Authorization::authorize('update work-order');
+
         $workOrder = $this->workOrderForEmail($id);
 
         // Resolve recipient email from the assignee (vendor or contact)
diff --git a/server/src/Support/Authorization.php b/server/src/Support/Authorization.php
new file mode 100644
index 000000000..9b8f22d9d
--- /dev/null
+++ b/server/src/Support/Authorization.php
@@ -0,0 +1,103 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\Models\Permission;
+use Fleetbase\Support\Auth;
+use Illuminate\Http\Exceptions\HttpResponseException;
+
+/**
+ * Explicit Fleet-Ops permission checks for endpoints that AuthorizationGuard
+ * cannot resolve correctly on its own: controllers that are not resource
+ * controllers, and custom actions whose method name does not match a schema
+ * action (for example `bulkDispatch`, which the guard maps to `create order`).
+ *
+ * Mirrors the guard's semantics:
+ *  - platform admins always pass;
+ *  - a permission is granted by its exact name, `fleet-ops * {resource}` or `fleet-ops *`;
+ *  - while the resource has no permission rows at all (the schema has not been
+ *    seeded yet) the check passes, exactly like an unguarded resource.
+ *
+ * Methods that call this must carry `#[SkipAuthorizationCheck]` so the guard
+ * does not also demand its own (wrong) permission.
+ */
+class Authorization
+{
+    public const SERVICE = 'fleet-ops';
+
+    /**
+     * Abort with a 401 JSON response unless the user holds at least one of the permissions.
+     *
+     * @param string ...$permissions Short form `{action} {resource}`, e.g. `dispatch order`
+     *
+     * @throws HttpResponseException
+     */
+    public static function authorize(string ...$permissions): void
+    {
+        if (static::canAny(...$permissions)) {
+            return;
+        }
+
+        throw new HttpResponseException(response()->json(['errors' => ['User is not authorized to ' . $permissions[0]]], 401));
+    }
+
+    /**
+     * Abort with a 401 JSON response unless the current user is a platform administrator.
+     *
+     * @throws HttpResponseException
+     */
+    public static function authorizeAdmin(): void
+    {
+        $user = static::user();
+        if ($user && $user->isAdmin()) {
+            return;
+        }
+
+        throw new HttpResponseException(response()->json(['errors' => ['This action requires a system administrator']], 401));
+    }
+
+    public static function canAny(string ...$permissions): bool
+    {
+        $user = static::user();
+        if (!$user) {
+            return false;
+        }
+
+        if ($user->isAdmin()) {
+            return true;
+        }
+
+        foreach ($permissions as $permission) {
+            if (static::can($permission)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    public static function can(string $permission): bool
+    {
+        [$action, $resource] = explode(' ', $permission, 2);
+
+        // Same test as Auth::isResourceGuarded(): no permission rows for the resource yet.
+        if (!Permission::where('name', 'like', static::SERVICE . ' % ' . $resource)->exists()) {
+            return true;
+        }
+
+        try {
+            return Auth::can(static::SERVICE . " {$action} {$resource}");
+        } catch (\Throwable $e) {
+            return false;
+        }
+    }
+
+    protected static function user()
+    {
+        try {
+            return Auth::getUserFromSession();
+        } catch (\Throwable $e) {
+            return null;
+        }
+    }
+}
diff --git a/server/src/routes.php b/server/src/routes.php
index 631bccc92..7adeec662 100644
--- a/server/src/routes.php
+++ b/server/src/routes.php
@@ -405,8 +405,10 @@ function ($router) {
                 $router->group(
                     ['prefix' => 'v1/fleet-ops/navigator', 'namespace' => 'v1'],
                     function ($router) {
-                        $router->get('get-link-app', 'NavigatorController@getLinkAppUrl');
-                        $router->get('link-app', 'NavigatorController@linkApp');
+                        // Opened from the Navigator app's QR scan without a session;
+                        // NavigatorController::linkApp() requires a valid signature.
+                        $router->get('link-app', 'NavigatorController@linkApp')->name('fleetops.navigator.link-app');
+                        $router->get('get-link-app', 'NavigatorController@getLinkAppUrl')->middleware(['fleetbase.protected']);
                     }
                 );
 

From b560a1b77b9cc39d7c5c544cbb2573dd1dd18572 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sun, 27 Sep 2026 14:33:00 +0800
Subject: [PATCH 10/24] fix(permissions): guard Fleet-Ops routes, actions and
 navigation by permission

- List guards on every index route that lacked one (orders, routes, trailers,
  fuel transactions, integrated vendors, all maintenance and connectivity
  routes, analytics, settings) and create/view/update guards on new, details
  and edit routes. Orders is the landing route, so it forwards users without
  `list order` to the first area they can open.
- Index New/Import/Export buttons, bulk actions and row actions pass their
  permission; the order details menu hides actions the user cannot perform.
- Sidebar hub items keep their permissions, branch defaults skip routes the
  user cannot open, and items use the schema's resource names (analytics,
  fuel-provider-*, list custom-field/avatar). Reports use the iam report
  permissions that the core reports API enforces.
- Header shortcuts carry their module permission; the virtual route honours
  menu item permissions.
- Live map layers check singular resource names (list vehicle, not vehicles),
  so non-admin users see their layers.
- Maintenance details/edit redirects used route names without the
  console.fleet-ops prefix and threw; fixed.
---
 addon/components/fuel-integration/hub.hbs     |  2 +-
 addon/components/layout/fleet-ops-sidebar.js  | 48 +++++++++++++------
 addon/components/map/leaflet-live-map.js      |  3 +-
 addon/components/telematic/hub.hbs            |  2 +-
 addon/controllers/analytics/reports/index.js  |  5 ++
 .../controllers/connectivity/devices/index.js |  4 ++
 .../connectivity/fuel-providers/index.js      | 10 ++--
 .../controllers/connectivity/sensors/index.js |  4 ++
 .../connectivity/telematics/index.js          |  4 ++
 .../maintenance/equipment/index.js            | 15 ++++--
 .../maintenance/inspection-forms/index.js     |  4 +-
 .../inspection-submissions/index.js           | 10 +++-
 .../maintenance/maintenances/index.js         |  4 ++
 addon/controllers/maintenance/parts/index.js  | 15 ++++--
 .../maintenance/schedules/index.js            | 21 ++++++--
 .../maintenance/work-orders/index.js          | 15 ++++--
 .../controllers/management/contacts/index.js  |  4 ++
 addon/controllers/management/drivers/index.js |  4 ++
 addon/controllers/management/fleets/index.js  |  4 ++
 .../management/fuel-reports/index.js          |  4 ++
 .../management/fuel-transactions/index.js     | 16 ++++---
 addon/controllers/management/issues/index.js  |  4 ++
 addon/controllers/management/places/index.js  |  4 ++
 .../controllers/management/vehicles/index.js  |  4 ++
 addon/controllers/management/vendors/index.js |  4 ++
 addon/controllers/operations/orders/index.js  |  7 +++
 .../operations/orders/index/details.js        | 31 +++++++++++-
 .../operations/service-rates/index.js         |  3 ++
 addon/extension.js                            | 11 +++++
 addon/routes/analytics/index.js               | 15 +++++-
 addon/routes/analytics/reports.js             | 15 +++++-
 .../routes/analytics/reports/index/details.js |  2 +-
 addon/routes/analytics/reports/index/edit.js  |  2 +-
 addon/routes/analytics/reports/index/new.js   | 15 +++++-
 addon/routes/connectivity/devices.js          | 15 +++++-
 .../routes/connectivity/devices/index/new.js  | 15 +++++-
 addon/routes/connectivity/events.js           | 15 +++++-
 addon/routes/connectivity/fuel-providers.js   | 15 +++++-
 .../connectivity/fuel-providers/details.js    |  9 ++++
 .../fuel-providers/details/transactions.js    | 12 +++++
 .../connectivity/fuel-providers/edit.js       |  9 ++++
 .../routes/connectivity/fuel-providers/new.js | 15 +++++-
 addon/routes/connectivity/sensors.js          | 15 +++++-
 .../routes/connectivity/sensors/index/new.js  | 15 +++++-
 addon/routes/connectivity/telematics.js       | 15 +++++-
 addon/routes/connectivity/telematics/new.js   | 15 +++++-
 addon/routes/connectivity/tracking.js         | 15 +++++-
 addon/routes/maintenance/equipment.js         | 15 +++++-
 .../maintenance/equipment/index/details.js    |  4 +-
 .../maintenance/equipment/index/edit.js       |  4 +-
 .../routes/maintenance/equipment/index/new.js | 15 +++++-
 addon/routes/maintenance/index.js             | 15 +++++-
 addon/routes/maintenance/inspection-forms.js  | 15 +++++-
 .../inspection-forms/index/details.js         | 11 ++++-
 .../inspection-forms/index/edit.js            | 11 ++++-
 .../maintenance/inspection-forms/index/new.js | 15 +++++-
 .../maintenance/inspection-submissions.js     | 15 +++++-
 .../inspection-submissions/index/details.js   | 11 ++++-
 .../inspection-submissions/index/edit.js      | 11 ++++-
 .../inspection-submissions/index/new.js       | 15 +++++-
 addon/routes/maintenance/maintenances.js      | 15 +++++-
 .../maintenance/maintenances/index/details.js |  4 +-
 .../maintenance/maintenances/index/edit.js    |  4 +-
 .../maintenance/maintenances/index/new.js     | 15 +++++-
 addon/routes/maintenance/parts.js             | 15 +++++-
 .../routes/maintenance/parts/index/details.js |  4 +-
 addon/routes/maintenance/parts/index/edit.js  |  4 +-
 addon/routes/maintenance/parts/index/new.js   | 15 +++++-
 addon/routes/maintenance/schedules.js         | 16 ++++++-
 .../maintenance/schedules/index/details.js    |  4 +-
 .../maintenance/schedules/index/edit.js       |  4 +-
 .../routes/maintenance/schedules/index/new.js | 16 ++++++-
 addon/routes/maintenance/work-orders.js       | 15 +++++-
 .../maintenance/work-orders/index/details.js  |  4 +-
 .../maintenance/work-orders/index/edit.js     |  4 +-
 .../maintenance/work-orders/index/new.js      | 15 +++++-
 addon/routes/management/fuel-transactions.js  | 15 +++++-
 .../fuel-transactions/index/details.js        |  9 ++++
 addon/routes/management/index.js              | 13 +++++
 addon/routes/management/trailers.js           | 16 +++++++
 addon/routes/management/vendors/integrated.js | 15 +++++-
 .../management/vendors/integrated/details.js  | 15 +++++-
 .../management/vendors/integrated/edit.js     | 15 +++++-
 .../management/vendors/integrated/new.js      | 15 +++++-
 addon/routes/operations/orders.js             | 41 +++++++++++++++-
 addon/routes/operations/routes.js             | 15 +++++-
 .../routes/operations/routes/index/details.js | 15 +++++-
 addon/routes/operations/routes/index/new.js   | 13 +++++
 addon/routes/operations/service-rates.js      | 15 +++++-
 .../operations/service-rates/index/new.js     | 11 +++++
 addon/routes/settings/avatars.js              | 15 +++++-
 addon/routes/settings/custom-fields.js        | 15 +++++-
 addon/routes/settings/map.js                  | 15 +++++-
 addon/routes/settings/notifications.js        | 11 +++++
 addon/routes/settings/orchestrator.js         |  2 +-
 addon/routes/settings/payments/index.js       |  2 +-
 addon/routes/settings/routing.js              | 15 +++++-
 addon/routes/settings/scheduling.js           | 15 +++++-
 addon/routes/virtual.js                       | 11 +++++
 99 files changed, 1010 insertions(+), 120 deletions(-)
 create mode 100644 addon/routes/management/trailers.js

diff --git a/addon/components/fuel-integration/hub.hbs b/addon/components/fuel-integration/hub.hbs
index 183657974..65ad63610 100644
--- a/addon/components/fuel-integration/hub.hbs
+++ b/addon/components/fuel-integration/hub.hbs
@@ -17,7 +17,7 @@
                 </div>
                 <div class="flex flex-shrink-0 items-center gap-2 whitespace-nowrap">
                     <Button @icon="refresh" @size="sm" @helpText={{t "common.reload"}} @onClick={{@onRefresh}} />
-                    <Button @icon="plus" @text="Connect Integration" @type="primary" @size="sm" @onClick={{this.createIntegration}} />
+                    <Button @icon="plus" @text="Connect Integration" @type="primary" @size="sm" @permission="fleet-ops create fuel-provider-connection" @onClick={{this.createIntegration}} />
                 </div>
             </div>
         </section>
diff --git a/addon/components/layout/fleet-ops-sidebar.js b/addon/components/layout/fleet-ops-sidebar.js
index 0abf9056f..faf84a74d 100644
--- a/addon/components/layout/fleet-ops-sidebar.js
+++ b/addon/components/layout/fleet-ops-sidebar.js
@@ -151,14 +151,14 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
             this.createItem('menu.contacts', 'address-book', 'management.contacts', 'fleet-ops list contact', 'fleet-ops see contact'),
             this.createItem('menu.places', 'location-dot', 'management.places', 'fleet-ops list place', 'fleet-ops see place'),
             this.createItem('menu.fuel-reports', 'gas-pump', 'management.fuel-reports', 'fleet-ops list fuel-report', 'fleet-ops see fuel-report'),
-            this.createItem('menu.fuel-transactions', 'credit-card', 'management.fuel-transactions', 'fleet-ops list fuel-report', 'fleet-ops see fuel-report'),
+            this.createItem('menu.fuel-transactions', 'credit-card', 'management.fuel-transactions', 'fleet-ops list fuel-provider-transaction', 'fleet-ops see fuel-provider-transaction'),
             this.createItem('menu.issues', 'triangle-exclamation', 'management.issues', 'fleet-ops list issue', 'fleet-ops see issue'),
         ]);
     }
 
     get maintenanceItems() {
         return this.withRegistryItems('maintenance', [
-            this.createHubItem('Maintenance Hub', 'wrench', 'maintenance.index', 'fleet-ops list maintenance-schedule', 'fleet-ops see maintenance-schedule', [
+            this.createHubItem('Maintenance Hub', 'wrench', 'maintenance.index', 'fleet-ops list work-order', 'fleet-ops see work-order', [
                 'maintenance hub',
                 'service readiness',
                 'maintenance control panel',
@@ -182,7 +182,9 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
     get connectivityItems() {
         return this.withRegistryItems('connectivity', [
             this.createHubItem(this.intl.t('menu.telematics'), 'satellite-dish', 'connectivity.telematics', 'fleet-ops list telematic', 'fleet-ops see telematic', ['connectivity hub']),
-            this.createItem('menu.fuel-providers', 'gas-pump', 'connectivity.fuel-providers', 'fleet-ops list fuel-report', 'fleet-ops see fuel-report', ['fuel integrations']),
+            this.createItem('menu.fuel-providers', 'gas-pump', 'connectivity.fuel-providers', 'fleet-ops list fuel-provider-connection', 'fleet-ops see fuel-provider-connection', [
+                'fuel integrations',
+            ]),
             this.createItem('menu.devices', 'hard-drive', 'connectivity.devices', 'fleet-ops list device', 'fleet-ops see device'),
             this.createItem('menu.sensors', 'temperature-full', 'connectivity.sensors', 'fleet-ops list sensor', 'fleet-ops see sensor'),
             this.createItem('menu.events', 'stream', 'connectivity.events', 'fleet-ops list device-event', 'fleet-ops see device-event'),
@@ -191,18 +193,14 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
 
     get analyticsItems() {
         return this.withRegistryItems('analytics', [
-            this.createHubItem('Dashboard', 'chart-line', 'analytics.index', 'iam list report', 'fleet-ops see report', ['dashboard', 'fleetops dashboard', 'metrics']),
-            this.createItem('menu.reports', 'file-import', 'analytics.reports', 'iam list report', 'fleet-ops see report'),
+            this.createHubItem('Dashboard', 'chart-line', 'analytics.index', 'fleet-ops view analytics', 'fleet-ops see analytics', ['dashboard', 'fleetops dashboard', 'metrics']),
+            this.createItem('menu.reports', 'file-import', 'analytics.reports', 'iam list report', 'iam see report'),
         ]);
     }
 
     get settingsItems() {
         return this.withRegistryItems('settings', [
-            this.createHubItem('Settings Hub', 'sliders', 'settings.index', 'fleet-ops view navigator-settings', 'fleet-ops see navigator-settings', [
-                'settings hub',
-                'configuration dashboard',
-                'setup focus',
-            ]),
+            this.createHubItem('Settings Hub', 'sliders', 'settings.index', null, null, ['settings hub', 'configuration dashboard', 'setup focus']),
             this.createItem('menu.navigator-app', 'location-arrow', 'settings.navigator-app', 'fleet-ops view navigator-settings', 'fleet-ops see navigator-settings'),
             this.createItem('menu.map', 'map', 'settings.map', 'fleet-ops view map-settings', 'fleet-ops see map-settings'),
             this.createItem('menu.payments', 'cash-register', 'settings.payments', 'fleet-ops view payments', 'fleet-ops see payments'),
@@ -210,8 +208,8 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
             this.createItem('menu.routing', 'route', 'settings.routing', 'fleet-ops view routing-settings', 'fleet-ops see routing-settings'),
             this.createItem('menu.orchestrator', 'circle-nodes', 'settings.orchestrator', 'fleet-ops view routing-settings', 'fleet-ops see routing-settings'),
             this.createItem('menu.scheduling', 'calendar-days', 'settings.scheduling', 'fleet-ops view scheduling-settings', 'fleet-ops see scheduling-settings'),
-            this.createItem('menu.custom-fields', 'pen-to-square', 'settings.custom-fields', 'fleet-ops view custom-field', 'fleet-ops see custom-field'),
-            this.createItem('menu.avatars', 'icons', 'settings.avatars', 'fleet-ops view avatar', 'fleet-ops see avatar'),
+            this.createItem('menu.custom-fields', 'pen-to-square', 'settings.custom-fields', 'fleet-ops list custom-field', 'fleet-ops see custom-field'),
+            this.createItem('menu.avatars', 'icons', 'settings.avatars', 'fleet-ops list avatar', 'fleet-ops see avatar'),
         ]);
     }
 
@@ -265,18 +263,36 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
     }
 
     createBranch({ id, label, icon, route, defaultRoute, requiresVisibleChildren = false, children, keywords = [] }) {
+        const visibleChildren = children.filter((item) => item.visible !== false);
+
         return {
             id,
             label,
             icon,
             route: this.fullRoute(route),
-            defaultRoute: this.fullRoute(defaultRoute),
+            defaultRoute: this.resolveDefaultRoute(this.fullRoute(defaultRoute), visibleChildren),
             requiresVisibleChildren,
-            children: children.filter((item) => item.visible !== false),
+            children: visibleChildren,
             keywords,
         };
     }
 
+    /**
+     * Keep the branch's default route when the user may open it; otherwise fall back to the
+     * first child route they are permitted to open, so clicking the branch does not land on a
+     * route guard that bounces them back out.
+     */
+    resolveDefaultRoute(defaultRoute, children = []) {
+        const permitted = (item) => [item.visiblePermission, item.permission].every((permission) => !permission || this.abilities.can(permission));
+        const defaultChild = children.find((item) => item.route === defaultRoute);
+
+        if (!defaultChild || permitted(defaultChild)) {
+            return defaultRoute;
+        }
+
+        return children.find((item) => item.route && permitted(item))?.route ?? defaultRoute;
+    }
+
     createItem(intl, icon, route, permission, ability, keywords = []) {
         return {
             priority: this.defaultPriorityForRoute(route),
@@ -290,7 +306,7 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
         };
     }
 
-    createHubItem(label, icon, route, _permission, _ability, keywords = []) {
+    createHubItem(label, icon, route, permission, ability, keywords = []) {
         return {
             pinnedFirst: true,
             priority: this.defaultPriorityForRoute(route),
@@ -298,6 +314,8 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
             description: label,
             icon,
             route: this.fullRoute(route),
+            permission,
+            visiblePermission: ability,
             isNavigationHub: true,
             keywords: [label, route, ...keywords].filter(Boolean),
         };
diff --git a/addon/components/map/leaflet-live-map.js b/addon/components/map/leaflet-live-map.js
index ae7727f8a..ded9fcd65 100644
--- a/addon/components/map/leaflet-live-map.js
+++ b/addon/components/map/leaflet-live-map.js
@@ -298,7 +298,8 @@ export default class MapLeafletLiveMapComponent extends Component {
     }
 
     @task *loadResource(path, options = {}) {
-        if (this.abilities.cannot(`fleet-ops list ${path}`)) return [];
+        // Permissions use the singular resource name (e.g. `fleet-ops list vehicle`), not the plural endpoint path.
+        if (this.abilities.cannot(`fleet-ops list ${singularize(path)}`)) return [];
 
         if (path === 'service-areas') {
             const serviceAreas = yield this.serviceAreaActions.loadAll.perform();
diff --git a/addon/components/telematic/hub.hbs b/addon/components/telematic/hub.hbs
index ad094657c..a567a6c97 100644
--- a/addon/components/telematic/hub.hbs
+++ b/addon/components/telematic/hub.hbs
@@ -15,7 +15,7 @@
                 </div>
                 <div class="flex flex-shrink-0 items-center gap-2 whitespace-nowrap">
                     <Button @icon="refresh" @size="sm" @helpText={{t "common.reload"}} @onClick={{this.refresh}} />
-                    <Button @icon="plus" @text="Connect Provider" @type="primary" @size="sm" @onClick={{this.telematicActions.transition.create}} />
+                    <Button @icon="plus" @text="Connect Provider" @type="primary" @size="sm" @permission="fleet-ops create telematic" @onClick={{this.telematicActions.transition.create}} />
                 </div>
             </div>
         </section>
diff --git a/addon/controllers/analytics/reports/index.js b/addon/controllers/analytics/reports/index.js
index 489324109..56052e63c 100644
--- a/addon/controllers/analytics/reports/index.js
+++ b/addon/controllers/analytics/reports/index.js
@@ -29,6 +29,7 @@ export default class AnalyticsReportsIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.reportActions.transition.create,
+                permission: 'iam create report',
             },
         ];
     }
@@ -39,6 +40,7 @@ export default class AnalyticsReportsIndexController extends Controller {
                 label: 'Delete selected...',
                 class: 'text-red-500',
                 fn: this.reportActions.bulkDelete,
+                permission: 'iam delete report',
             },
         ];
     }
@@ -81,10 +83,12 @@ export default class AnalyticsReportsIndexController extends Controller {
                     {
                         label: 'View report...',
                         fn: this.reportActions.transition.view,
+                        permission: 'iam view report',
                     },
                     {
                         label: 'Edit report...',
                         fn: this.reportActions.transition.edit,
+                        permission: 'iam update report',
                     },
                     {
                         separator: true,
@@ -92,6 +96,7 @@ export default class AnalyticsReportsIndexController extends Controller {
                     {
                         label: 'Delete report...',
                         fn: this.reportActions.delete,
+                        permission: 'iam delete report',
                     },
                 ],
                 sortable: false,
diff --git a/addon/controllers/connectivity/devices/index.js b/addon/controllers/connectivity/devices/index.js
index dcb7c2536..b971d6681 100644
--- a/addon/controllers/connectivity/devices/index.js
+++ b/addon/controllers/connectivity/devices/index.js
@@ -65,12 +65,14 @@ export default class ConnectivityDevicesIndexController extends Controller {
             type: 'primary',
             icon: 'plus',
             onClick: this.deviceActions.transition.create,
+            permission: 'fleet-ops create device',
         },
         {
             text: this.intl.t('common.import'),
             type: 'magic',
             icon: 'upload',
             onClick: this.deviceActions.import,
+            permission: 'fleet-ops import device',
         },
         {
             text: this.intl.t('common.export'),
@@ -78,6 +80,7 @@ export default class ConnectivityDevicesIndexController extends Controller {
             iconClass: 'rotate-icon-45',
             wrapperClass: 'hidden md:flex',
             onClick: this.deviceActions.export,
+            permission: 'fleet-ops export device',
         },
     ];
 
@@ -87,6 +90,7 @@ export default class ConnectivityDevicesIndexController extends Controller {
             label: 'Delete selected...',
             class: 'text-red-500',
             fn: this.deviceActions.bulkDelete,
+            permission: 'fleet-ops delete device',
         },
     ];
 
diff --git a/addon/controllers/connectivity/fuel-providers/index.js b/addon/controllers/connectivity/fuel-providers/index.js
index f0ef5a0c8..5b4ffe9fb 100644
--- a/addon/controllers/connectivity/fuel-providers/index.js
+++ b/addon/controllers/connectivity/fuel-providers/index.js
@@ -40,6 +40,7 @@ export default class ConnectivityFuelProvidersIndexController extends Controller
                 text: 'Connect Integration',
                 type: 'primary',
                 onClick: () => this.fuelIntegrationActions.transition.create(),
+                permission: 'fleet-ops create fuel-provider-connection',
             },
         ];
     }
@@ -51,6 +52,7 @@ export default class ConnectivityFuelProvidersIndexController extends Controller
             {
                 label: `Sync ${selected.length} selected`,
                 fn: () => selected.forEach((connection) => this.syncConnection(connection)),
+                permission: 'fleet-ops sync fuel-provider-connection',
             },
         ];
     }
@@ -125,11 +127,11 @@ export default class ConnectivityFuelProvidersIndexController extends Controller
                 sticky: 'right',
                 width: 60,
                 actions: [
-                    { label: 'Open Integration', fn: this.openConnection },
-                    { label: 'Edit Settings', fn: this.editConnection },
+                    { label: 'Open Integration', fn: this.openConnection, permission: 'fleet-ops view fuel-provider-connection' },
+                    { label: 'Edit Settings', fn: this.editConnection, permission: 'fleet-ops update fuel-provider-connection' },
                     { separator: true },
-                    { label: 'Test Connection', fn: this.testConnection },
-                    { label: 'Sync Transactions', fn: this.syncConnection },
+                    { label: 'Test Connection', fn: this.testConnection, permission: 'fleet-ops update fuel-provider-connection' },
+                    { label: 'Sync Transactions', fn: this.syncConnection, permission: 'fleet-ops sync fuel-provider-connection' },
                 ],
                 sortable: false,
                 filterable: false,
diff --git a/addon/controllers/connectivity/sensors/index.js b/addon/controllers/connectivity/sensors/index.js
index 4ed9390a1..492a537d1 100644
--- a/addon/controllers/connectivity/sensors/index.js
+++ b/addon/controllers/connectivity/sensors/index.js
@@ -92,12 +92,14 @@ export default class ConnectivitySensorsIndexController extends Controller {
             type: 'primary',
             icon: 'plus',
             onClick: this.sensorActions.transition.create,
+            permission: 'fleet-ops create sensor',
         },
         {
             text: this.intl.t('common.import'),
             type: 'magic',
             icon: 'upload',
             onClick: this.sensorActions.import,
+            permission: 'fleet-ops import sensor',
         },
         {
             text: this.intl.t('common.export'),
@@ -105,6 +107,7 @@ export default class ConnectivitySensorsIndexController extends Controller {
             iconClass: 'rotate-icon-45',
             wrapperClass: 'hidden md:flex',
             onClick: this.sensorActions.export,
+            permission: 'fleet-ops export sensor',
         },
     ];
 
@@ -114,6 +117,7 @@ export default class ConnectivitySensorsIndexController extends Controller {
             label: 'Delete selected...',
             class: 'text-red-500',
             fn: this.sensorActions.bulkDelete,
+            permission: 'fleet-ops delete sensor',
         },
     ];
 
diff --git a/addon/controllers/connectivity/telematics/index.js b/addon/controllers/connectivity/telematics/index.js
index 37369823a..c44ba0556 100644
--- a/addon/controllers/connectivity/telematics/index.js
+++ b/addon/controllers/connectivity/telematics/index.js
@@ -38,12 +38,14 @@ export default class ConnectivityTelematicsIndexController extends Controller {
             type: 'primary',
             icon: 'plus',
             onClick: this.telematicActions.transition.create,
+            permission: 'fleet-ops create telematic',
         },
         {
             text: this.intl.t('common.import'),
             type: 'magic',
             icon: 'upload',
             onClick: this.telematicActions.import,
+            permission: 'fleet-ops import telematic',
         },
         {
             text: this.intl.t('common.export'),
@@ -51,6 +53,7 @@ export default class ConnectivityTelematicsIndexController extends Controller {
             iconClass: 'rotate-icon-45',
             wrapperClass: 'hidden md:flex',
             onClick: this.telematicActions.export,
+            permission: 'fleet-ops export telematic',
         },
     ];
 
@@ -60,6 +63,7 @@ export default class ConnectivityTelematicsIndexController extends Controller {
             label: 'Delete selected...',
             class: 'text-red-500',
             fn: this.telematicActions.bulkDelete,
+            permission: 'fleet-ops delete telematic',
         },
     ];
 
diff --git a/addon/controllers/maintenance/equipment/index.js b/addon/controllers/maintenance/equipment/index.js
index 7c020cfb7..d0a95dac0 100644
--- a/addon/controllers/maintenance/equipment/index.js
+++ b/addon/controllers/maintenance/equipment/index.js
@@ -46,14 +46,21 @@ export default class MaintenanceEquipmentIndexController extends Controller {
                 helpText: 'Change the layout',
             },
             { icon: 'refresh', onClick: this.equipmentActions.refresh, helpText: this.intl.t('common.refresh') },
-            { text: this.intl.t('common.new'), type: 'primary', icon: 'plus', onClick: this.equipmentActions.transition.create },
-            { text: this.intl.t('common.import'), type: 'magic', icon: 'upload', onClick: this.equipmentActions.import },
-            { text: this.intl.t('common.export'), icon: 'long-arrow-up', iconClass: 'rotate-icon-45', wrapperClass: 'hidden md:flex', onClick: this.equipmentActions.export },
+            { text: this.intl.t('common.new'), type: 'primary', icon: 'plus', onClick: this.equipmentActions.transition.create, permission: 'fleet-ops create equipment' },
+            { text: this.intl.t('common.import'), type: 'magic', icon: 'upload', onClick: this.equipmentActions.import, permission: 'fleet-ops import equipment' },
+            {
+                text: this.intl.t('common.export'),
+                icon: 'long-arrow-up',
+                iconClass: 'rotate-icon-45',
+                wrapperClass: 'hidden md:flex',
+                onClick: this.equipmentActions.export,
+                permission: 'fleet-ops export equipment',
+            },
         ];
     }
 
     get bulkActions() {
-        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.equipmentActions.bulkDelete }];
+        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.equipmentActions.bulkDelete, permission: 'fleet-ops delete equipment' }];
     }
 
     get columns() {
diff --git a/addon/controllers/maintenance/inspection-forms/index.js b/addon/controllers/maintenance/inspection-forms/index.js
index 53d812903..f7fb1c0ff 100644
--- a/addon/controllers/maintenance/inspection-forms/index.js
+++ b/addon/controllers/maintenance/inspection-forms/index.js
@@ -17,12 +17,12 @@ export default class MaintenanceInspectionFormsIndexController extends Controlle
     get actionButtons() {
         return [
             { icon: 'refresh', onClick: this.inspectionFormActions.refresh, helpText: this.intl.t('common.refresh') },
-            { text: this.intl.t('common.new'), type: 'primary', icon: 'plus', onClick: this.inspectionFormActions.transition.create },
+            { text: this.intl.t('common.new'), type: 'primary', icon: 'plus', onClick: this.inspectionFormActions.transition.create, permission: 'fleet-ops create inspection-form' },
         ];
     }
 
     get bulkActions() {
-        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.inspectionFormActions.bulkDelete }];
+        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.inspectionFormActions.bulkDelete, permission: 'fleet-ops delete inspection-form' }];
     }
 
     get columns() {
diff --git a/addon/controllers/maintenance/inspection-submissions/index.js b/addon/controllers/maintenance/inspection-submissions/index.js
index 888898dc5..0cfa6bd70 100644
--- a/addon/controllers/maintenance/inspection-submissions/index.js
+++ b/addon/controllers/maintenance/inspection-submissions/index.js
@@ -23,12 +23,18 @@ export default class MaintenanceInspectionSubmissionsIndexController extends Con
     get actionButtons() {
         return [
             { icon: 'refresh', onClick: this.inspectionSubmissionActions.refresh, helpText: this.intl.t('common.refresh') },
-            { text: this.intl.t('common.new'), type: 'primary', icon: 'plus', onClick: this.inspectionSubmissionActions.transition.create },
+            {
+                text: this.intl.t('common.new'),
+                type: 'primary',
+                icon: 'plus',
+                onClick: this.inspectionSubmissionActions.transition.create,
+                permission: 'fleet-ops create inspection-submission',
+            },
         ];
     }
 
     get bulkActions() {
-        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.inspectionSubmissionActions.bulkDelete }];
+        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.inspectionSubmissionActions.bulkDelete, permission: 'fleet-ops delete inspection-submission' }];
     }
 
     get columns() {
diff --git a/addon/controllers/maintenance/maintenances/index.js b/addon/controllers/maintenance/maintenances/index.js
index 88d817048..a0d75c580 100644
--- a/addon/controllers/maintenance/maintenances/index.js
+++ b/addon/controllers/maintenance/maintenances/index.js
@@ -31,12 +31,14 @@ export default class MaintenanceMaintenancesIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.maintenanceActions.transition.create,
+                permission: 'fleet-ops create maintenance',
             },
             {
                 text: this.intl.t('common.import'),
                 type: 'magic',
                 icon: 'upload',
                 onClick: this.maintenanceActions.import,
+                permission: 'fleet-ops import maintenance',
             },
             {
                 text: this.intl.t('common.export'),
@@ -44,6 +46,7 @@ export default class MaintenanceMaintenancesIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.maintenanceActions.export,
+                permission: 'fleet-ops export maintenance',
             },
         ];
     }
@@ -55,6 +58,7 @@ export default class MaintenanceMaintenancesIndexController extends Controller {
                 label: 'Delete selected...',
                 class: 'text-red-500',
                 fn: this.maintenanceActions.bulkDelete,
+                permission: 'fleet-ops delete maintenance',
             },
         ];
     }
diff --git a/addon/controllers/maintenance/parts/index.js b/addon/controllers/maintenance/parts/index.js
index 3a44dfb5e..55bfc41c2 100644
--- a/addon/controllers/maintenance/parts/index.js
+++ b/addon/controllers/maintenance/parts/index.js
@@ -46,14 +46,21 @@ export default class MaintenancePartsIndexController extends Controller {
                 helpText: 'Change the layout',
             },
             { icon: 'refresh', onClick: this.partActions.refresh, helpText: this.intl.t('common.refresh') },
-            { text: this.intl.t('common.new'), type: 'primary', icon: 'plus', onClick: this.partActions.transition.create },
-            { text: this.intl.t('common.import'), type: 'magic', icon: 'upload', onClick: this.partActions.import },
-            { text: this.intl.t('common.export'), icon: 'long-arrow-up', iconClass: 'rotate-icon-45', wrapperClass: 'hidden md:flex', onClick: this.partActions.export },
+            { text: this.intl.t('common.new'), type: 'primary', icon: 'plus', onClick: this.partActions.transition.create, permission: 'fleet-ops create part' },
+            { text: this.intl.t('common.import'), type: 'magic', icon: 'upload', onClick: this.partActions.import, permission: 'fleet-ops import part' },
+            {
+                text: this.intl.t('common.export'),
+                icon: 'long-arrow-up',
+                iconClass: 'rotate-icon-45',
+                wrapperClass: 'hidden md:flex',
+                onClick: this.partActions.export,
+                permission: 'fleet-ops export part',
+            },
         ];
     }
 
     get bulkActions() {
-        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.partActions.bulkDelete }];
+        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.partActions.bulkDelete, permission: 'fleet-ops delete part' }];
     }
 
     get columns() {
diff --git a/addon/controllers/maintenance/schedules/index.js b/addon/controllers/maintenance/schedules/index.js
index 094af86ef..16f4b098f 100644
--- a/addon/controllers/maintenance/schedules/index.js
+++ b/addon/controllers/maintenance/schedules/index.js
@@ -151,14 +151,27 @@ export default class MaintenanceSchedulesIndexController extends Controller {
                 helpText: this.intl.t('common.change-layout'),
             },
             { icon: 'refresh', onClick: this.maintenanceScheduleActions.refresh, helpText: this.intl.t('common.refresh') },
-            { text: this.intl.t('common.new'), type: 'primary', icon: 'plus', onClick: this.maintenanceScheduleActions.transition.create },
-            { text: this.intl.t('common.import'), type: 'magic', icon: 'upload', onClick: this.maintenanceScheduleActions.import },
-            { text: this.intl.t('common.export'), icon: 'long-arrow-up', iconClass: 'rotate-icon-45', wrapperClass: 'hidden md:flex', onClick: this.maintenanceScheduleActions.export },
+            {
+                text: this.intl.t('common.new'),
+                type: 'primary',
+                icon: 'plus',
+                onClick: this.maintenanceScheduleActions.transition.create,
+                permission: 'fleet-ops create maintenance-schedule',
+            },
+            { text: this.intl.t('common.import'), type: 'magic', icon: 'upload', onClick: this.maintenanceScheduleActions.import, permission: 'fleet-ops import maintenance-schedule' },
+            {
+                text: this.intl.t('common.export'),
+                icon: 'long-arrow-up',
+                iconClass: 'rotate-icon-45',
+                wrapperClass: 'hidden md:flex',
+                onClick: this.maintenanceScheduleActions.export,
+                permission: 'fleet-ops export maintenance-schedule',
+            },
         ];
     }
 
     get bulkActions() {
-        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.maintenanceScheduleActions.bulkDelete }];
+        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.maintenanceScheduleActions.bulkDelete, permission: 'fleet-ops delete maintenance-schedule' }];
     }
 
     get columns() {
diff --git a/addon/controllers/maintenance/work-orders/index.js b/addon/controllers/maintenance/work-orders/index.js
index fbc789696..082cb8ead 100644
--- a/addon/controllers/maintenance/work-orders/index.js
+++ b/addon/controllers/maintenance/work-orders/index.js
@@ -21,14 +21,21 @@ export default class MaintenanceWorkOrdersIndexController extends Controller {
     get actionButtons() {
         return [
             { icon: 'refresh', onClick: this.workOrderActions.refresh, helpText: this.intl.t('common.refresh') },
-            { text: this.intl.t('common.new'), type: 'primary', icon: 'plus', onClick: this.workOrderActions.transition.create },
-            { text: this.intl.t('common.import'), type: 'magic', icon: 'upload', onClick: this.workOrderActions.import },
-            { text: this.intl.t('common.export'), icon: 'long-arrow-up', iconClass: 'rotate-icon-45', wrapperClass: 'hidden md:flex', onClick: this.workOrderActions.export },
+            { text: this.intl.t('common.new'), type: 'primary', icon: 'plus', onClick: this.workOrderActions.transition.create, permission: 'fleet-ops create work-order' },
+            { text: this.intl.t('common.import'), type: 'magic', icon: 'upload', onClick: this.workOrderActions.import, permission: 'fleet-ops import work-order' },
+            {
+                text: this.intl.t('common.export'),
+                icon: 'long-arrow-up',
+                iconClass: 'rotate-icon-45',
+                wrapperClass: 'hidden md:flex',
+                onClick: this.workOrderActions.export,
+                permission: 'fleet-ops export work-order',
+            },
         ];
     }
 
     get bulkActions() {
-        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.workOrderActions.bulkDelete }];
+        return [{ label: 'Delete selected...', class: 'text-red-500', fn: this.workOrderActions.bulkDelete, permission: 'fleet-ops delete work-order' }];
     }
 
     get columns() {
diff --git a/addon/controllers/management/contacts/index.js b/addon/controllers/management/contacts/index.js
index 0756dd08e..056a1a696 100644
--- a/addon/controllers/management/contacts/index.js
+++ b/addon/controllers/management/contacts/index.js
@@ -62,12 +62,14 @@ export default class ManagementContactsIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.contactActions.transition.create,
+                permission: 'fleet-ops create contact',
             },
             {
                 text: this.intl.t('common.import'),
                 type: 'magic',
                 icon: 'upload',
                 onClick: this.contactActions.import,
+                permission: 'fleet-ops import contact',
             },
             {
                 text: this.intl.t('common.export'),
@@ -75,6 +77,7 @@ export default class ManagementContactsIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.contactActions.export,
+                permission: 'fleet-ops export contact',
             },
         ];
     }
@@ -88,6 +91,7 @@ export default class ManagementContactsIndexController extends Controller {
                 label: this.intl.t('common.delete-selected-count', { count: selected.length }),
                 class: 'text-red-500',
                 fn: this.contactActions.bulkDelete,
+                permission: 'fleet-ops delete contact',
             },
         ];
     }
diff --git a/addon/controllers/management/drivers/index.js b/addon/controllers/management/drivers/index.js
index 9762122d6..30612981f 100644
--- a/addon/controllers/management/drivers/index.js
+++ b/addon/controllers/management/drivers/index.js
@@ -103,12 +103,14 @@ export default class ManagementDriversIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.driverActions.transition.create,
+                permission: 'fleet-ops create driver',
             },
             {
                 text: this.intl.t('common.import'),
                 type: 'magic',
                 icon: 'upload',
                 onClick: this.driverActions.import,
+                permission: 'fleet-ops import driver',
             },
             {
                 text: this.intl.t('common.export'),
@@ -116,6 +118,7 @@ export default class ManagementDriversIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.driverActions.export,
+                permission: 'fleet-ops export driver',
             },
         ];
     }
@@ -129,6 +132,7 @@ export default class ManagementDriversIndexController extends Controller {
                 label: this.intl.t('common.delete-selected-count', { count: selected.length }),
                 class: 'text-red-500',
                 fn: this.driverActions.bulkDelete,
+                permission: 'fleet-ops delete driver',
             },
         ];
     }
diff --git a/addon/controllers/management/fleets/index.js b/addon/controllers/management/fleets/index.js
index 910dbaea3..80f6d84ae 100644
--- a/addon/controllers/management/fleets/index.js
+++ b/addon/controllers/management/fleets/index.js
@@ -42,12 +42,14 @@ export default class ManagementFleetsIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.fleetActions.transition.create,
+                permission: 'fleet-ops create fleet',
             },
             {
                 text: this.intl.t('common.import'),
                 type: 'magic',
                 icon: 'upload',
                 onClick: this.fleetActions.import,
+                permission: 'fleet-ops import fleet',
             },
             {
                 text: this.intl.t('common.export'),
@@ -55,6 +57,7 @@ export default class ManagementFleetsIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.fleetActions.export,
+                permission: 'fleet-ops export fleet',
             },
         ];
     }
@@ -68,6 +71,7 @@ export default class ManagementFleetsIndexController extends Controller {
                 label: this.intl.t('common.delete-selected-count', { count: selected.length }),
                 class: 'text-red-500',
                 fn: this.fleetActions.bulkDelete,
+                permission: 'fleet-ops delete fleet',
             },
         ];
     }
diff --git a/addon/controllers/management/fuel-reports/index.js b/addon/controllers/management/fuel-reports/index.js
index 1374cfcaf..cdf74dfbe 100644
--- a/addon/controllers/management/fuel-reports/index.js
+++ b/addon/controllers/management/fuel-reports/index.js
@@ -56,12 +56,14 @@ export default class ManagementFuelReportsIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.fuelReportActions.transition.create,
+                permission: 'fleet-ops create fuel-report',
             },
             {
                 text: this.intl.t('common.import'),
                 type: 'magic',
                 icon: 'upload',
                 onClick: this.fuelReportActions.import,
+                permission: 'fleet-ops import fuel-report',
             },
             {
                 text: this.intl.t('common.export'),
@@ -69,6 +71,7 @@ export default class ManagementFuelReportsIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.fuelReportActions.export,
+                permission: 'fleet-ops export fuel-report',
             },
         ];
     }
@@ -82,6 +85,7 @@ export default class ManagementFuelReportsIndexController extends Controller {
                 label: this.intl.t('common.delete-selected-count', { count: selected.length }),
                 class: 'text-red-500',
                 fn: this.fuelReportActions.bulkDelete,
+                permission: 'fleet-ops delete fuel-report',
             },
         ];
     }
diff --git a/addon/controllers/management/fuel-transactions/index.js b/addon/controllers/management/fuel-transactions/index.js
index e6873351a..30e940e3e 100644
--- a/addon/controllers/management/fuel-transactions/index.js
+++ b/addon/controllers/management/fuel-transactions/index.js
@@ -71,6 +71,7 @@ export default class ManagementFuelTransactionsIndexController extends Controlle
                 icon: 'gas-pump',
                 text: 'Fuel Integrations',
                 onClick: () => this.hostRouter.transitionTo('console.fleet-ops.connectivity.fuel-providers.index'),
+                permission: 'fleet-ops list fuel-provider-connection',
             },
         ];
     }
@@ -86,6 +87,7 @@ export default class ManagementFuelTransactionsIndexController extends Controlle
             {
                 label: `Reprocess ${selected.length} selected`,
                 fn: () => this.confirmAction('reprocess', selected),
+                permission: 'fleet-ops update fuel-provider-transaction',
             },
         ];
     }
@@ -196,14 +198,14 @@ export default class ManagementFuelTransactionsIndexController extends Controlle
                 sticky: 'right',
                 width: 60,
                 actions: [
-                    { label: 'Review Details', fn: this.openDetails },
-                    { label: 'Open Fuel Report', fn: this.openFuelReport, isVisible: (transaction) => Boolean(transaction.fuel_report_id) },
+                    { label: 'Review Details', fn: this.openDetails, permission: 'fleet-ops view fuel-provider-transaction' },
+                    { label: 'Open Fuel Report', fn: this.openFuelReport, isVisible: (transaction) => Boolean(transaction.fuel_report_id), permission: 'fleet-ops view fuel-report' },
                     { separator: true },
-                    { label: 'Match to Vehicle', fn: this.matchVehicle },
-                    { label: 'Match to Order', fn: this.matchOrder },
-                    { label: 'Reprocess / Rematch', fn: (transaction) => this.confirmAction('reprocess', transaction) },
-                    { label: 'Ignore Transaction', fn: (transaction) => this.confirmAction('ignored', transaction) },
-                    { label: 'Mark Reviewed', fn: (transaction) => this.confirmAction('reviewed', transaction) },
+                    { label: 'Match to Vehicle', fn: this.matchVehicle, permission: 'fleet-ops update fuel-provider-transaction' },
+                    { label: 'Match to Order', fn: this.matchOrder, permission: 'fleet-ops update fuel-provider-transaction' },
+                    { label: 'Reprocess / Rematch', fn: (transaction) => this.confirmAction('reprocess', transaction), permission: 'fleet-ops update fuel-provider-transaction' },
+                    { label: 'Ignore Transaction', fn: (transaction) => this.confirmAction('ignored', transaction), permission: 'fleet-ops review fuel-provider-transaction' },
+                    { label: 'Mark Reviewed', fn: (transaction) => this.confirmAction('reviewed', transaction), permission: 'fleet-ops review fuel-provider-transaction' },
                 ],
                 sortable: false,
                 filterable: false,
diff --git a/addon/controllers/management/issues/index.js b/addon/controllers/management/issues/index.js
index 9c3cfaecd..5774b8865 100644
--- a/addon/controllers/management/issues/index.js
+++ b/addon/controllers/management/issues/index.js
@@ -56,12 +56,14 @@ export default class ManagementIssuesIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.issueActions.transition.create,
+                permission: 'fleet-ops create issue',
             },
             {
                 text: this.intl.t('common.import'),
                 type: 'magic',
                 icon: 'upload',
                 onClick: this.issueActions.import,
+                permission: 'fleet-ops import issue',
             },
             {
                 text: this.intl.t('common.export'),
@@ -69,6 +71,7 @@ export default class ManagementIssuesIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.issueActions.export,
+                permission: 'fleet-ops export issue',
             },
         ];
     }
@@ -82,6 +85,7 @@ export default class ManagementIssuesIndexController extends Controller {
                 label: this.intl.t('common.delete-selected-count', { count: selected.length }),
                 class: 'text-red-500',
                 fn: this.issueActions.bulkDelete,
+                permission: 'fleet-ops delete issue',
             },
         ];
     }
diff --git a/addon/controllers/management/places/index.js b/addon/controllers/management/places/index.js
index f4236ea31..6fdc416b4 100644
--- a/addon/controllers/management/places/index.js
+++ b/addon/controllers/management/places/index.js
@@ -34,12 +34,14 @@ export default class ManagementPlacesIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.placeActions.transition.create,
+                permission: 'fleet-ops create place',
             },
             {
                 text: this.intl.t('common.import'),
                 type: 'magic',
                 icon: 'upload',
                 onClick: this.placeActions.import,
+                permission: 'fleet-ops import place',
             },
             {
                 text: this.intl.t('common.export'),
@@ -47,6 +49,7 @@ export default class ManagementPlacesIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.placeActions.export,
+                permission: 'fleet-ops export place',
             },
         ];
     }
@@ -60,6 +63,7 @@ export default class ManagementPlacesIndexController extends Controller {
                 label: this.intl.t('common.delete-selected-count', { count: selected.length }),
                 class: 'text-red-500',
                 fn: this.placeActions.bulkDelete,
+                permission: 'fleet-ops delete place',
             },
         ];
     }
diff --git a/addon/controllers/management/vehicles/index.js b/addon/controllers/management/vehicles/index.js
index 1662a134a..1e63fbf4d 100644
--- a/addon/controllers/management/vehicles/index.js
+++ b/addon/controllers/management/vehicles/index.js
@@ -102,12 +102,14 @@ export default class ManagementVehiclesIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.vehicleActions.transition.create,
+                permission: 'fleet-ops create vehicle',
             },
             {
                 text: this.intl.t('common.import'),
                 type: 'magic',
                 icon: 'upload',
                 onClick: this.vehicleActions.import,
+                permission: 'fleet-ops import vehicle',
             },
             {
                 text: this.intl.t('common.export'),
@@ -115,6 +117,7 @@ export default class ManagementVehiclesIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.vehicleActions.export,
+                permission: 'fleet-ops export vehicle',
             },
         ];
     }
@@ -128,6 +131,7 @@ export default class ManagementVehiclesIndexController extends Controller {
                 label: this.intl.t('common.delete-selected-count', { count: selected.length }),
                 class: 'text-red-500',
                 fn: this.vehicleActions.bulkDelete,
+                permission: 'fleet-ops delete vehicle',
             },
         ];
     }
diff --git a/addon/controllers/management/vendors/index.js b/addon/controllers/management/vendors/index.js
index 03d941bbe..e76a713ee 100644
--- a/addon/controllers/management/vendors/index.js
+++ b/addon/controllers/management/vendors/index.js
@@ -83,12 +83,14 @@ export default class ManagementVendorsIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.vendorActions.transition.create,
+                permission: 'fleet-ops create vendor',
             },
             {
                 text: this.intl.t('common.import'),
                 type: 'magic',
                 icon: 'upload',
                 onClick: this.vendorActions.import,
+                permission: 'fleet-ops import vendor',
             },
             {
                 text: this.intl.t('common.export'),
@@ -96,6 +98,7 @@ export default class ManagementVendorsIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.vendorActions.export,
+                permission: 'fleet-ops export vendor',
             },
         ];
     }
@@ -109,6 +112,7 @@ export default class ManagementVendorsIndexController extends Controller {
                 label: this.intl.t('common.delete-selected-count', { count: selected.length }),
                 class: 'text-red-500',
                 fn: this.vendorActions.bulkDelete,
+                permission: 'fleet-ops delete vendor',
             },
         ];
     }
diff --git a/addon/controllers/operations/orders/index.js b/addon/controllers/operations/orders/index.js
index 5b40c7bc8..ab9563a89 100644
--- a/addon/controllers/operations/orders/index.js
+++ b/addon/controllers/operations/orders/index.js
@@ -86,6 +86,7 @@ export default class OperationsOrdersIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.orderActions.transition.create,
+                permission: 'fleet-ops create order',
             },
             {
                 text: this.intl.t('common.export'),
@@ -93,12 +94,14 @@ export default class OperationsOrdersIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.orderActions.export,
+                permission: 'fleet-ops export order',
             },
             {
                 text: this.intl.t('common.import'),
                 icon: 'file-import',
                 wrapperClass: 'hidden md:flex',
                 onClick: () => this.orderActions.importOrders({ onImportComplete: this.orderActions.refresh }),
+                permission: 'fleet-ops import order',
             },
         ];
     }
@@ -110,23 +113,27 @@ export default class OperationsOrdersIndexController extends Controller {
                 label: this.intl.t('common.cancel-resource', { resource: this.intl.t('resource.orders') }),
                 icon: 'ban',
                 fn: this.orderActions.bulkCancel,
+                permission: 'fleet-ops cancel order',
             },
             {
                 label: this.intl.t('common.delete-resource', { resource: this.intl.t('resource.orders') }),
                 icon: 'trash',
                 class: 'text-red-500',
                 fn: this.orderActions.bulkDelete,
+                permission: 'fleet-ops delete order',
             },
             { separator: true },
             {
                 label: this.intl.t('common.dispatch-orders'),
                 icon: 'rocket',
                 fn: this.orderActions.bulkDispatch,
+                permission: 'fleet-ops dispatch order',
             },
             {
                 label: this.intl.t('common.assign-drivers'),
                 icon: 'user-plus',
                 fn: this.orderActions.bulkAssignDriver,
+                permission: 'fleet-ops assign-driver-for order',
             },
         ];
     }
diff --git a/addon/controllers/operations/orders/index/details.js b/addon/controllers/operations/orders/index/details.js
index 188ec9256..333846cc9 100644
--- a/addon/controllers/operations/orders/index/details.js
+++ b/addon/controllers/operations/orders/index/details.js
@@ -17,6 +17,7 @@ export default class OperationsOrdersIndexDetailsController extends Controller {
     @service hostRouter;
     @service universe;
     @service sidebar;
+    @service abilities;
     @tracked routingControl;
     @tracked routingCompleted = false;
     @tracked realtimeOrderPublicId = null;
@@ -90,12 +91,14 @@ export default class OperationsOrdersIndexDetailsController extends Controller {
                     {
                         text: 'Edit details',
                         icon: 'pencil',
+                        permission: 'fleet-ops update order',
                         disabled: this.model.status === 'canceled',
                         fn: () => this.orderActions.editOrderDetails(this.model),
                     },
                     {
                         text: 'Update activity',
                         icon: 'signal',
+                        permission: 'fleet-ops update order',
                         disabled: this.model.status === 'canceled',
                         fn: () =>
                             this.orderActions.updateActivity(this.model, {
@@ -105,12 +108,14 @@ export default class OperationsOrdersIndexDetailsController extends Controller {
                     {
                         text: this.model.has_driver_assigned ? 'Unassign driver' : 'Assign driver',
                         icon: this.model.has_driver_assigned ? 'user-xmark' : 'edit',
+                        permission: 'fleet-ops assign-driver-for order',
                         disabled: this.model.has_driver_assigned ? !this.model.hasActiveStatus || !this.model.driver_assigned : !this.model.hasActiveStatus,
                         fn: () => (this.model.has_driver_assigned ? this.orderActions.unassignDriver(this.model) : this.orderActions.assignDriver(this.model)),
                     },
                     {
                         text: 'View order label',
                         icon: 'file-invoice',
+                        permission: 'fleet-ops view order',
                         fn: () => this.orderActions.viewLabel(this.model),
                     },
                     {
@@ -133,6 +138,7 @@ export default class OperationsOrdersIndexDetailsController extends Controller {
                         text: 'Cancel order',
                         icon: 'ban',
                         class: 'text-danger',
+                        permission: 'fleet-ops cancel order',
                         disabled: this.model.status === 'canceled',
                         fn: () => this.orderActions.cancel(this.model),
                     },
@@ -140,6 +146,7 @@ export default class OperationsOrdersIndexDetailsController extends Controller {
                         text: 'Delete order',
                         icon: 'trash',
                         class: 'text-danger',
+                        permission: 'fleet-ops delete order',
                         fn: () =>
                             this.orderActions.delete(this.model, {
                                 taskOptions: {
@@ -151,7 +158,29 @@ export default class OperationsOrdersIndexDetailsController extends Controller {
                     },
                 ].filter(Boolean),
             },
-        ];
+        ].map((actionButton) => ({ ...actionButton, items: this.permittedMenuItems(actionButton.items) }));
+    }
+
+    /**
+     * The panel header dropdown renders `items` as-is and ignores `permission`, so items the
+     * user is not permitted to use are removed here, along with any separators left dangling.
+     */
+    permittedMenuItems(items = []) {
+        const permitted = items.filter((item) => !item.permission || this.abilities.can(item.permission));
+        const result = permitted.reduce((list, item) => {
+            if (item.separator && (list.length === 0 || list[list.length - 1].separator)) {
+                return list;
+            }
+
+            list.push(item);
+            return list;
+        }, []);
+
+        if (result.length && result[result.length - 1].separator) {
+            result.pop();
+        }
+
+        return result;
     }
 
     @action handleActivityModalFinish(options) {
diff --git a/addon/controllers/operations/service-rates/index.js b/addon/controllers/operations/service-rates/index.js
index cdb91974f..52413130a 100644
--- a/addon/controllers/operations/service-rates/index.js
+++ b/addon/controllers/operations/service-rates/index.js
@@ -29,6 +29,7 @@ export default class OperationsServiceRatesIndexController extends Controller {
                 type: 'primary',
                 icon: 'plus',
                 onClick: this.serviceRateActions.transition.create,
+                permission: 'fleet-ops create service-rate',
             },
             {
                 text: this.intl.t('common.export'),
@@ -36,6 +37,7 @@ export default class OperationsServiceRatesIndexController extends Controller {
                 iconClass: 'rotate-icon-45',
                 wrapperClass: 'hidden md:flex',
                 onClick: this.serviceRateActions.export,
+                permission: 'fleet-ops export service-rate',
             },
         ];
     }
@@ -47,6 +49,7 @@ export default class OperationsServiceRatesIndexController extends Controller {
                 label: 'Delete selected...',
                 class: 'text-red-500',
                 fn: this.serviceRateActions.bulkDelete,
+                permission: 'fleet-ops delete service-rate',
             },
         ];
     }
diff --git a/addon/extension.js b/addon/extension.js
index 925f632f9..cd43c6763 100644
--- a/addon/extension.js
+++ b/addon/extension.js
@@ -18,66 +18,77 @@ export default {
                     description: 'Everything across resources, maintenance and staffing that needs a decision today.',
                     icon: 'satellite-dish',
                     route: 'console.fleet-ops.management.index',
+                    permission: 'fleet-ops list driver',
                 },
                 {
                     title: 'Orders',
                     description: 'Create, dispatch, and track delivery orders in real time.',
                     icon: 'boxes-stacked',
                     route: 'console.fleet-ops.operations.orders',
+                    permission: 'fleet-ops list order',
                 },
                 {
                     title: 'Places',
                     description: 'Manage saved locations, addresses, and points of interest.',
                     icon: 'location-dot',
                     route: 'console.fleet-ops.management.places',
+                    permission: 'fleet-ops list place',
                 },
                 {
                     title: 'Drivers',
                     description: 'Manage driver profiles, assignments, and live locations.',
                     icon: 'id-card',
                     route: 'console.fleet-ops.management.drivers',
+                    permission: 'fleet-ops list driver',
                 },
                 {
                     title: 'Vehicles',
                     description: 'View and manage your vehicle fleet and telematics.',
                     icon: 'truck',
                     route: 'console.fleet-ops.management.vehicles',
+                    permission: 'fleet-ops list vehicle',
                 },
                 {
                     title: intlService.t('menu.trailers'),
                     description: intlService.t('trailer.navigation-description'),
                     icon: 'trailer',
                     route: 'console.fleet-ops.management.trailers',
+                    permission: 'fleet-ops list trailer',
                 },
                 {
                     title: 'Fleets',
                     description: 'Organise drivers and vehicles into operational fleets.',
                     icon: 'layer-group',
                     route: 'console.fleet-ops.management.fleets',
+                    permission: 'fleet-ops list fleet',
                 },
                 {
                     title: 'Service Rates',
                     description: 'Configure pricing rules and service rate cards.',
                     icon: 'tags',
                     route: 'console.fleet-ops.operations.service-rates',
+                    permission: 'fleet-ops list service-rate',
                 },
                 {
                     title: 'Devices',
                     description: 'Manage connected telematics devices and their sensor data.',
                     icon: 'microchip',
                     route: 'console.fleet-ops.connectivity.devices',
+                    permission: 'fleet-ops list device',
                 },
                 {
                     title: 'Reports',
                     description: 'Generate and review operational analytics reports.',
                     icon: 'chart-bar',
                     route: 'console.fleet-ops.analytics.reports',
+                    permission: 'iam list report',
                 },
                 {
                     title: 'Orchestrator',
                     description: 'Intelligently allocate and dispatch orders to available drivers.',
                     icon: 'diagram-project',
                     route: 'console.fleet-ops.operations.orchestrator',
+                    permission: 'fleet-ops list order',
                 },
             ],
         });
diff --git a/addon/routes/analytics/index.js b/addon/routes/analytics/index.js
index 3d64374e9..7f2d927d2 100644
--- a/addon/routes/analytics/index.js
+++ b/addon/routes/analytics/index.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class AnalyticsIndexRoute extends Route {}
+export default class AnalyticsIndexRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view analytics')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/analytics/reports.js b/addon/routes/analytics/reports.js
index fdd1396cf..da2b0f72f 100644
--- a/addon/routes/analytics/reports.js
+++ b/addon/routes/analytics/reports.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class AnalyticsReportsRoute extends Route {}
+export default class AnalyticsReportsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('iam list report')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/analytics/reports/index/details.js b/addon/routes/analytics/reports/index/details.js
index aafa2b55a..d2d163626 100644
--- a/addon/routes/analytics/reports/index/details.js
+++ b/addon/routes/analytics/reports/index/details.js
@@ -17,7 +17,7 @@ export default class AnalyticsReportsIndexDetailsRoute extends Route {
     }
 
     beforeModel() {
-        if (this.abilities.cannot('fleet-ops view report')) {
+        if (this.abilities.cannot('iam view report')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
             return this.hostRouter.transitionTo('console.fleet-ops.analytics.reports.index');
         }
diff --git a/addon/routes/analytics/reports/index/edit.js b/addon/routes/analytics/reports/index/edit.js
index 4ca59d92a..99e510235 100644
--- a/addon/routes/analytics/reports/index/edit.js
+++ b/addon/routes/analytics/reports/index/edit.js
@@ -17,7 +17,7 @@ export default class AnalyticsReportsIndexEditRoute extends Route {
     }
 
     beforeModel() {
-        if (this.abilities.cannot('fleet-ops update report')) {
+        if (this.abilities.cannot('iam update report')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
             return this.hostRouter.transitionTo('console.fleet-ops.analytics.reports.index');
         }
diff --git a/addon/routes/analytics/reports/index/new.js b/addon/routes/analytics/reports/index/new.js
index 3bd42eb9d..88d4d9e1f 100644
--- a/addon/routes/analytics/reports/index/new.js
+++ b/addon/routes/analytics/reports/index/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class AnalyticsReportsIndexNewRoute extends Route {}
+export default class AnalyticsReportsIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('iam create report')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.analytics.reports.index');
+        }
+    }
+}
diff --git a/addon/routes/connectivity/devices.js b/addon/routes/connectivity/devices.js
index f5a216674..e1fe1539e 100644
--- a/addon/routes/connectivity/devices.js
+++ b/addon/routes/connectivity/devices.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ConnectivityDevicesRoute extends Route {}
+export default class ConnectivityDevicesRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list device')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/connectivity/devices/index/new.js b/addon/routes/connectivity/devices/index/new.js
index 8c69bb213..450685ce7 100644
--- a/addon/routes/connectivity/devices/index/new.js
+++ b/addon/routes/connectivity/devices/index/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ConnectivityDevicesIndexNewRoute extends Route {}
+export default class ConnectivityDevicesIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create device')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.connectivity.devices.index');
+        }
+    }
+}
diff --git a/addon/routes/connectivity/events.js b/addon/routes/connectivity/events.js
index 4f6e2b6e1..aaf94573c 100644
--- a/addon/routes/connectivity/events.js
+++ b/addon/routes/connectivity/events.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ConnectivityEventsRoute extends Route {}
+export default class ConnectivityEventsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list device-event')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/connectivity/fuel-providers.js b/addon/routes/connectivity/fuel-providers.js
index 0d9c95fc7..95897b8f8 100644
--- a/addon/routes/connectivity/fuel-providers.js
+++ b/addon/routes/connectivity/fuel-providers.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ConnectivityFuelProvidersRoute extends Route {}
+export default class ConnectivityFuelProvidersRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list fuel-provider-connection')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/connectivity/fuel-providers/details.js b/addon/routes/connectivity/fuel-providers/details.js
index 04be2351a..f974a05c8 100644
--- a/addon/routes/connectivity/fuel-providers/details.js
+++ b/addon/routes/connectivity/fuel-providers/details.js
@@ -6,6 +6,15 @@ export default class ConnectivityFuelProvidersIndexDetailsRoute extends Route {
     @service store;
     @service notifications;
     @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view fuel-provider-connection')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.connectivity.fuel-providers.index');
+        }
+    }
 
     setupController(controller, model) {
         super.setupController(controller, model);
diff --git a/addon/routes/connectivity/fuel-providers/details/transactions.js b/addon/routes/connectivity/fuel-providers/details/transactions.js
index 6a457461f..0addb38f7 100644
--- a/addon/routes/connectivity/fuel-providers/details/transactions.js
+++ b/addon/routes/connectivity/fuel-providers/details/transactions.js
@@ -4,6 +4,18 @@ import { action } from '@ember/object';
 
 export default class FuelIntegrationTransactionsRoute extends Route {
     @service store;
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list fuel-provider-transaction')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.connectivity.fuel-providers.index');
+        }
+    }
+
     queryParams = Object.fromEntries(['page', 'limit', 'sort', 'query', 'sync_status', 'vehicle', 'transaction_at'].map((key) => [key, { refreshModel: true }]));
     model(params) {
         const connection = this.modelFor('connectivity.fuel-providers.details');
diff --git a/addon/routes/connectivity/fuel-providers/edit.js b/addon/routes/connectivity/fuel-providers/edit.js
index 8d72929c4..478c81e75 100644
--- a/addon/routes/connectivity/fuel-providers/edit.js
+++ b/addon/routes/connectivity/fuel-providers/edit.js
@@ -6,6 +6,15 @@ export default class ConnectivityFuelProvidersIndexEditRoute extends Route {
     @service store;
     @service notifications;
     @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops update fuel-provider-connection')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.connectivity.fuel-providers.index');
+        }
+    }
 
     @action error(error) {
         this.notifications.serverError(error);
diff --git a/addon/routes/connectivity/fuel-providers/new.js b/addon/routes/connectivity/fuel-providers/new.js
index b3605cce0..f20b9af67 100644
--- a/addon/routes/connectivity/fuel-providers/new.js
+++ b/addon/routes/connectivity/fuel-providers/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ConnectivityFuelProvidersIndexNewRoute extends Route {}
+export default class ConnectivityFuelProvidersIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create fuel-provider-connection')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.connectivity.fuel-providers.index');
+        }
+    }
+}
diff --git a/addon/routes/connectivity/sensors.js b/addon/routes/connectivity/sensors.js
index f3bc70a81..9bc86da27 100644
--- a/addon/routes/connectivity/sensors.js
+++ b/addon/routes/connectivity/sensors.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ConnectivitySensorsRoute extends Route {}
+export default class ConnectivitySensorsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list sensor')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/connectivity/sensors/index/new.js b/addon/routes/connectivity/sensors/index/new.js
index 836d72730..d23d3cafe 100644
--- a/addon/routes/connectivity/sensors/index/new.js
+++ b/addon/routes/connectivity/sensors/index/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ConnectivitySensorsIndexNewRoute extends Route {}
+export default class ConnectivitySensorsIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create sensor')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.connectivity.sensors.index');
+        }
+    }
+}
diff --git a/addon/routes/connectivity/telematics.js b/addon/routes/connectivity/telematics.js
index 68fd97c7c..39e33321e 100644
--- a/addon/routes/connectivity/telematics.js
+++ b/addon/routes/connectivity/telematics.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ConnectivityTelematicsRoute extends Route {}
+export default class ConnectivityTelematicsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list telematic')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/connectivity/telematics/new.js b/addon/routes/connectivity/telematics/new.js
index f993f7b19..0c6d68dd9 100644
--- a/addon/routes/connectivity/telematics/new.js
+++ b/addon/routes/connectivity/telematics/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ConnectivityTelematicsNewRoute extends Route {}
+export default class ConnectivityTelematicsNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create telematic')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.connectivity.telematics.index');
+        }
+    }
+}
diff --git a/addon/routes/connectivity/tracking.js b/addon/routes/connectivity/tracking.js
index 81d44b954..de24cdf6f 100644
--- a/addon/routes/connectivity/tracking.js
+++ b/addon/routes/connectivity/tracking.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ConnectivityTrackingRoute extends Route {}
+export default class ConnectivityTrackingRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list vehicle')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/equipment.js b/addon/routes/maintenance/equipment.js
index 3a5bb687a..cec17bfb6 100644
--- a/addon/routes/maintenance/equipment.js
+++ b/addon/routes/maintenance/equipment.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceEquipmentRoute extends Route {}
+export default class MaintenanceEquipmentRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list equipment')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/equipment/index/details.js b/addon/routes/maintenance/equipment/index/details.js
index 43035ca49..7f8efa9b7 100644
--- a/addon/routes/maintenance/equipment/index/details.js
+++ b/addon/routes/maintenance/equipment/index/details.js
@@ -12,14 +12,14 @@ export default class MaintenanceEquipmentIndexDetailsRoute extends Route {
     @action error(error) {
         this.notifications.serverError(error);
         if (typeof error.message === 'string' && error.message.endsWith('not found')) {
-            return this.hostRouter.transitionTo('maintenance.equipment.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.equipment.index');
         }
     }
 
     beforeModel() {
         if (this.abilities.cannot('fleet-ops view equipment')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
-            return this.hostRouter.transitionTo('maintenance.equipment.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.equipment.index');
         }
     }
 
diff --git a/addon/routes/maintenance/equipment/index/edit.js b/addon/routes/maintenance/equipment/index/edit.js
index 136ea947c..51e06996b 100644
--- a/addon/routes/maintenance/equipment/index/edit.js
+++ b/addon/routes/maintenance/equipment/index/edit.js
@@ -12,14 +12,14 @@ export default class MaintenanceEquipmentIndexEditRoute extends Route {
     @action error(error) {
         this.notifications.serverError(error);
         if (typeof error.message === 'string' && error.message.endsWith('not found')) {
-            return this.hostRouter.transitionTo('maintenance.equipment.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.equipment.index');
         }
     }
 
     beforeModel() {
         if (this.abilities.cannot('fleet-ops update equipment')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
-            return this.hostRouter.transitionTo('maintenance.equipment.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.equipment.index');
         }
     }
 
diff --git a/addon/routes/maintenance/equipment/index/new.js b/addon/routes/maintenance/equipment/index/new.js
index 965997967..aee969df0 100644
--- a/addon/routes/maintenance/equipment/index/new.js
+++ b/addon/routes/maintenance/equipment/index/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceEquipmentIndexNewRoute extends Route {}
+export default class MaintenanceEquipmentIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create equipment')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.equipment.index');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/index.js b/addon/routes/maintenance/index.js
index 04e2df618..767e3e292 100644
--- a/addon/routes/maintenance/index.js
+++ b/addon/routes/maintenance/index.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceIndexRoute extends Route {}
+export default class MaintenanceIndexRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list work-order')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/inspection-forms.js b/addon/routes/maintenance/inspection-forms.js
index 97a8c467a..b427120f6 100644
--- a/addon/routes/maintenance/inspection-forms.js
+++ b/addon/routes/maintenance/inspection-forms.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceInspectionFormsRoute extends Route {}
+export default class MaintenanceInspectionFormsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list inspection-form')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/inspection-forms/index/details.js b/addon/routes/maintenance/inspection-forms/index/details.js
index 202e83766..25f0e46b6 100644
--- a/addon/routes/maintenance/inspection-forms/index/details.js
+++ b/addon/routes/maintenance/inspection-forms/index/details.js
@@ -6,6 +6,15 @@ export default class MaintenanceInspectionFormsIndexDetailsRoute extends Route {
     @service store;
     @service hostRouter;
     @service notifications;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view inspection-form')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.inspection-forms.index');
+        }
+    }
 
     model({ public_id }) {
         return this.store.findRecord('inspection-form', public_id);
@@ -13,6 +22,6 @@ export default class MaintenanceInspectionFormsIndexDetailsRoute extends Route {
 
     @action error(error) {
         this.notifications.serverError(error);
-        return this.hostRouter.transitionTo('maintenance.inspection-forms.index');
+        return this.hostRouter.transitionTo('console.fleet-ops.maintenance.inspection-forms.index');
     }
 }
diff --git a/addon/routes/maintenance/inspection-forms/index/edit.js b/addon/routes/maintenance/inspection-forms/index/edit.js
index f8b15d6dd..531d9819c 100644
--- a/addon/routes/maintenance/inspection-forms/index/edit.js
+++ b/addon/routes/maintenance/inspection-forms/index/edit.js
@@ -6,6 +6,15 @@ export default class MaintenanceInspectionFormsIndexEditRoute extends Route {
     @service store;
     @service hostRouter;
     @service notifications;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops update inspection-form')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.inspection-forms.index');
+        }
+    }
 
     model({ public_id }) {
         return this.store.findRecord('inspection-form', public_id);
@@ -13,6 +22,6 @@ export default class MaintenanceInspectionFormsIndexEditRoute extends Route {
 
     @action error(error) {
         this.notifications.serverError(error);
-        return this.hostRouter.transitionTo('maintenance.inspection-forms.index');
+        return this.hostRouter.transitionTo('console.fleet-ops.maintenance.inspection-forms.index');
     }
 }
diff --git a/addon/routes/maintenance/inspection-forms/index/new.js b/addon/routes/maintenance/inspection-forms/index/new.js
index 96a813892..b4867f549 100644
--- a/addon/routes/maintenance/inspection-forms/index/new.js
+++ b/addon/routes/maintenance/inspection-forms/index/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceInspectionFormsIndexNewRoute extends Route {}
+export default class MaintenanceInspectionFormsIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create inspection-form')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.inspection-forms.index');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/inspection-submissions.js b/addon/routes/maintenance/inspection-submissions.js
index 73b235dce..028acfb78 100644
--- a/addon/routes/maintenance/inspection-submissions.js
+++ b/addon/routes/maintenance/inspection-submissions.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceInspectionSubmissionsRoute extends Route {}
+export default class MaintenanceInspectionSubmissionsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list inspection-submission')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/inspection-submissions/index/details.js b/addon/routes/maintenance/inspection-submissions/index/details.js
index ebb148013..faa1cddbd 100644
--- a/addon/routes/maintenance/inspection-submissions/index/details.js
+++ b/addon/routes/maintenance/inspection-submissions/index/details.js
@@ -6,6 +6,15 @@ export default class MaintenanceInspectionSubmissionsIndexDetailsRoute extends R
     @service store;
     @service hostRouter;
     @service notifications;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view inspection-submission')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.inspection-submissions.index');
+        }
+    }
 
     model({ public_id }) {
         return this.store.findRecord('inspection-submission', public_id);
@@ -13,6 +22,6 @@ export default class MaintenanceInspectionSubmissionsIndexDetailsRoute extends R
 
     @action error(error) {
         this.notifications.serverError(error);
-        return this.hostRouter.transitionTo('maintenance.inspection-submissions.index');
+        return this.hostRouter.transitionTo('console.fleet-ops.maintenance.inspection-submissions.index');
     }
 }
diff --git a/addon/routes/maintenance/inspection-submissions/index/edit.js b/addon/routes/maintenance/inspection-submissions/index/edit.js
index 9e6f0bb2f..424b900eb 100644
--- a/addon/routes/maintenance/inspection-submissions/index/edit.js
+++ b/addon/routes/maintenance/inspection-submissions/index/edit.js
@@ -6,6 +6,15 @@ export default class MaintenanceInspectionSubmissionsIndexEditRoute extends Rout
     @service store;
     @service hostRouter;
     @service notifications;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops update inspection-submission')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.inspection-submissions.index');
+        }
+    }
 
     model({ public_id }) {
         return this.store.findRecord('inspection-submission', public_id);
@@ -13,6 +22,6 @@ export default class MaintenanceInspectionSubmissionsIndexEditRoute extends Rout
 
     @action error(error) {
         this.notifications.serverError(error);
-        return this.hostRouter.transitionTo('maintenance.inspection-submissions.index');
+        return this.hostRouter.transitionTo('console.fleet-ops.maintenance.inspection-submissions.index');
     }
 }
diff --git a/addon/routes/maintenance/inspection-submissions/index/new.js b/addon/routes/maintenance/inspection-submissions/index/new.js
index f5c57fe09..c27872ab3 100644
--- a/addon/routes/maintenance/inspection-submissions/index/new.js
+++ b/addon/routes/maintenance/inspection-submissions/index/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceInspectionSubmissionsIndexNewRoute extends Route {}
+export default class MaintenanceInspectionSubmissionsIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create inspection-submission')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.inspection-submissions.index');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/maintenances.js b/addon/routes/maintenance/maintenances.js
index c38f607a0..67e4ade75 100644
--- a/addon/routes/maintenance/maintenances.js
+++ b/addon/routes/maintenance/maintenances.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceMaintenancesRoute extends Route {}
+export default class MaintenanceMaintenancesRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list maintenance')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/maintenances/index/details.js b/addon/routes/maintenance/maintenances/index/details.js
index 564b2777a..8bdbd46bc 100644
--- a/addon/routes/maintenance/maintenances/index/details.js
+++ b/addon/routes/maintenance/maintenances/index/details.js
@@ -12,14 +12,14 @@ export default class MaintenanceMaintenancesIndexDetailsRoute extends Route {
     @action error(error) {
         this.notifications.serverError(error);
         if (typeof error.message === 'string' && error.message.endsWith('not found')) {
-            return this.hostRouter.transitionTo('maintenance.maintenances.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.maintenances.index');
         }
     }
 
     beforeModel() {
         if (this.abilities.cannot('fleet-ops view maintenance')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
-            return this.hostRouter.transitionTo('maintenance.maintenances.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.maintenances.index');
         }
     }
 
diff --git a/addon/routes/maintenance/maintenances/index/edit.js b/addon/routes/maintenance/maintenances/index/edit.js
index 5c81bd470..ec801d142 100644
--- a/addon/routes/maintenance/maintenances/index/edit.js
+++ b/addon/routes/maintenance/maintenances/index/edit.js
@@ -12,14 +12,14 @@ export default class MaintenanceMaintenancesIndexEditRoute extends Route {
     @action error(error) {
         this.notifications.serverError(error);
         if (typeof error.message === 'string' && error.message.endsWith('not found')) {
-            return this.hostRouter.transitionTo('maintenance.maintenances.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.maintenances.index');
         }
     }
 
     beforeModel() {
         if (this.abilities.cannot('fleet-ops update maintenance')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
-            return this.hostRouter.transitionTo('maintenance.maintenances.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.maintenances.index');
         }
     }
 
diff --git a/addon/routes/maintenance/maintenances/index/new.js b/addon/routes/maintenance/maintenances/index/new.js
index 8bcba94e0..5a5e18f24 100644
--- a/addon/routes/maintenance/maintenances/index/new.js
+++ b/addon/routes/maintenance/maintenances/index/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceMaintenancesIndexNewRoute extends Route {}
+export default class MaintenanceMaintenancesIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create maintenance')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.maintenances.index');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/parts.js b/addon/routes/maintenance/parts.js
index 4d1a7132e..5850590f6 100644
--- a/addon/routes/maintenance/parts.js
+++ b/addon/routes/maintenance/parts.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenancePartsRoute extends Route {}
+export default class MaintenancePartsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list part')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/parts/index/details.js b/addon/routes/maintenance/parts/index/details.js
index 9b27d7a72..5a311fb5c 100644
--- a/addon/routes/maintenance/parts/index/details.js
+++ b/addon/routes/maintenance/parts/index/details.js
@@ -12,14 +12,14 @@ export default class MaintenancePartsIndexDetailsRoute extends Route {
     @action error(error) {
         this.notifications.serverError(error);
         if (typeof error.message === 'string' && error.message.endsWith('not found')) {
-            return this.hostRouter.transitionTo('maintenance.parts.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.parts.index');
         }
     }
 
     beforeModel() {
         if (this.abilities.cannot('fleet-ops view part')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
-            return this.hostRouter.transitionTo('maintenance.parts.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.parts.index');
         }
     }
 
diff --git a/addon/routes/maintenance/parts/index/edit.js b/addon/routes/maintenance/parts/index/edit.js
index 0ee51d4a5..18c9c8bbb 100644
--- a/addon/routes/maintenance/parts/index/edit.js
+++ b/addon/routes/maintenance/parts/index/edit.js
@@ -12,14 +12,14 @@ export default class MaintenancePartsIndexEditRoute extends Route {
     @action error(error) {
         this.notifications.serverError(error);
         if (typeof error.message === 'string' && error.message.endsWith('not found')) {
-            return this.hostRouter.transitionTo('maintenance.parts.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.parts.index');
         }
     }
 
     beforeModel() {
         if (this.abilities.cannot('fleet-ops update part')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
-            return this.hostRouter.transitionTo('maintenance.parts.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.parts.index');
         }
     }
 
diff --git a/addon/routes/maintenance/parts/index/new.js b/addon/routes/maintenance/parts/index/new.js
index 667dd94d8..022d147ee 100644
--- a/addon/routes/maintenance/parts/index/new.js
+++ b/addon/routes/maintenance/parts/index/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenancePartsIndexNewRoute extends Route {}
+export default class MaintenancePartsIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create part')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.parts.index');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/schedules.js b/addon/routes/maintenance/schedules.js
index bcc5af8f2..4de37c319 100644
--- a/addon/routes/maintenance/schedules.js
+++ b/addon/routes/maintenance/schedules.js
@@ -1,2 +1,16 @@
 import Route from '@ember/routing/route';
-export default class MaintenanceSchedulesRoute extends Route {}
+import { inject as service } from '@ember/service';
+
+export default class MaintenanceSchedulesRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list maintenance-schedule')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/schedules/index/details.js b/addon/routes/maintenance/schedules/index/details.js
index a222442e8..45048a427 100644
--- a/addon/routes/maintenance/schedules/index/details.js
+++ b/addon/routes/maintenance/schedules/index/details.js
@@ -10,13 +10,13 @@ export default class MaintenanceSchedulesIndexDetailsRoute extends Route {
     @action error(error) {
         this.notifications.serverError(error);
         if (typeof error.message === 'string' && error.message.endsWith('not found')) {
-            return this.hostRouter.transitionTo('maintenance.schedules.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.schedules.index');
         }
     }
     beforeModel() {
         if (this.abilities.cannot('fleet-ops view maintenance-schedule')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
-            return this.hostRouter.transitionTo('maintenance.schedules.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.schedules.index');
         }
     }
     model({ public_id }) {
diff --git a/addon/routes/maintenance/schedules/index/edit.js b/addon/routes/maintenance/schedules/index/edit.js
index 65d160fdb..44023fc6e 100644
--- a/addon/routes/maintenance/schedules/index/edit.js
+++ b/addon/routes/maintenance/schedules/index/edit.js
@@ -10,13 +10,13 @@ export default class MaintenanceSchedulesIndexEditRoute extends Route {
     @action error(error) {
         this.notifications.serverError(error);
         if (typeof error.message === 'string' && error.message.endsWith('not found')) {
-            return this.hostRouter.transitionTo('maintenance.schedules.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.schedules.index');
         }
     }
     beforeModel() {
         if (this.abilities.cannot('fleet-ops update maintenance-schedule')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
-            return this.hostRouter.transitionTo('maintenance.schedules.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.schedules.index');
         }
     }
     model({ public_id }) {
diff --git a/addon/routes/maintenance/schedules/index/new.js b/addon/routes/maintenance/schedules/index/new.js
index f0ce7286b..8ed97541c 100644
--- a/addon/routes/maintenance/schedules/index/new.js
+++ b/addon/routes/maintenance/schedules/index/new.js
@@ -1,2 +1,16 @@
 import Route from '@ember/routing/route';
-export default class MaintenanceSchedulesIndexNewRoute extends Route {}
+import { inject as service } from '@ember/service';
+
+export default class MaintenanceSchedulesIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create maintenance-schedule')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.schedules.index');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/work-orders.js b/addon/routes/maintenance/work-orders.js
index 13587f950..b9e40da18 100644
--- a/addon/routes/maintenance/work-orders.js
+++ b/addon/routes/maintenance/work-orders.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceWorkOrdersRoute extends Route {}
+export default class MaintenanceWorkOrdersRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list work-order')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/maintenance/work-orders/index/details.js b/addon/routes/maintenance/work-orders/index/details.js
index 6cbee3e24..52738d3f2 100644
--- a/addon/routes/maintenance/work-orders/index/details.js
+++ b/addon/routes/maintenance/work-orders/index/details.js
@@ -12,14 +12,14 @@ export default class MaintenanceWorkOrdersIndexDetailsRoute extends Route {
     @action error(error) {
         this.notifications.serverError(error);
         if (typeof error.message === 'string' && error.message.endsWith('not found')) {
-            return this.hostRouter.transitionTo('maintenance.work-orders.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.work-orders.index');
         }
     }
 
     beforeModel() {
         if (this.abilities.cannot('fleet-ops view work-order')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
-            return this.hostRouter.transitionTo('maintenance.work-orders.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.work-orders.index');
         }
     }
 
diff --git a/addon/routes/maintenance/work-orders/index/edit.js b/addon/routes/maintenance/work-orders/index/edit.js
index b5a3c8899..1ccfe4bdd 100644
--- a/addon/routes/maintenance/work-orders/index/edit.js
+++ b/addon/routes/maintenance/work-orders/index/edit.js
@@ -12,14 +12,14 @@ export default class MaintenanceWorkOrdersIndexEditRoute extends Route {
     @action error(error) {
         this.notifications.serverError(error);
         if (typeof error.message === 'string' && error.message.endsWith('not found')) {
-            return this.hostRouter.transitionTo('maintenance.work-orders.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.work-orders.index');
         }
     }
 
     beforeModel() {
         if (this.abilities.cannot('fleet-ops update work-order')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
-            return this.hostRouter.transitionTo('maintenance.work-orders.index');
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.work-orders.index');
         }
     }
 
diff --git a/addon/routes/maintenance/work-orders/index/new.js b/addon/routes/maintenance/work-orders/index/new.js
index 7757b0a10..fbe3da463 100644
--- a/addon/routes/maintenance/work-orders/index/new.js
+++ b/addon/routes/maintenance/work-orders/index/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class MaintenanceWorkOrdersIndexNewRoute extends Route {}
+export default class MaintenanceWorkOrdersIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create work-order')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.maintenance.work-orders.index');
+        }
+    }
+}
diff --git a/addon/routes/management/fuel-transactions.js b/addon/routes/management/fuel-transactions.js
index 4f0de54b6..c463fb850 100644
--- a/addon/routes/management/fuel-transactions.js
+++ b/addon/routes/management/fuel-transactions.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ManagementFuelTransactionsRoute extends Route {}
+export default class ManagementFuelTransactionsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list fuel-provider-transaction')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/management/fuel-transactions/index/details.js b/addon/routes/management/fuel-transactions/index/details.js
index 05d202d42..b251e2e57 100644
--- a/addon/routes/management/fuel-transactions/index/details.js
+++ b/addon/routes/management/fuel-transactions/index/details.js
@@ -7,6 +7,15 @@ export default class ManagementFuelTransactionsIndexDetailsRoute extends Route {
     @service store;
     @service notifications;
     @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view fuel-provider-transaction')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.management.fuel-transactions.index');
+        }
+    }
 
     @action error(error) {
         this.notifications.serverError(error);
diff --git a/addon/routes/management/index.js b/addon/routes/management/index.js
index 0a4dcd62b..63f8af741 100644
--- a/addon/routes/management/index.js
+++ b/addon/routes/management/index.js
@@ -1,6 +1,19 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
 export default class ManagementIndexRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list driver')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+
     queryParams = {
         view: { refreshModel: false },
         status: { refreshModel: false },
diff --git a/addon/routes/management/trailers.js b/addon/routes/management/trailers.js
new file mode 100644
index 000000000..0b4992833
--- /dev/null
+++ b/addon/routes/management/trailers.js
@@ -0,0 +1,16 @@
+import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
+
+export default class ManagementTrailersRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list trailer')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/management/vendors/integrated.js b/addon/routes/management/vendors/integrated.js
index 0d90aa4ff..b86b8ac6d 100644
--- a/addon/routes/management/vendors/integrated.js
+++ b/addon/routes/management/vendors/integrated.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ManagementVendorsIntegratedRoute extends Route {}
+export default class ManagementVendorsIntegratedRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list integrated-vendor')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.management.vendors.index');
+        }
+    }
+}
diff --git a/addon/routes/management/vendors/integrated/details.js b/addon/routes/management/vendors/integrated/details.js
index 2c1b8c9b6..e4cb44ae5 100644
--- a/addon/routes/management/vendors/integrated/details.js
+++ b/addon/routes/management/vendors/integrated/details.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ManagementVendorsIntegratedDetailsRoute extends Route {}
+export default class ManagementVendorsIntegratedDetailsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view integrated-vendor')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.management.vendors.index');
+        }
+    }
+}
diff --git a/addon/routes/management/vendors/integrated/edit.js b/addon/routes/management/vendors/integrated/edit.js
index 5167d56f4..5131805c8 100644
--- a/addon/routes/management/vendors/integrated/edit.js
+++ b/addon/routes/management/vendors/integrated/edit.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ManagementVendorsIntegratedEditRoute extends Route {}
+export default class ManagementVendorsIntegratedEditRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops update integrated-vendor')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.management.vendors.index');
+        }
+    }
+}
diff --git a/addon/routes/management/vendors/integrated/new.js b/addon/routes/management/vendors/integrated/new.js
index 1a9ea38c9..1c57c5cc8 100644
--- a/addon/routes/management/vendors/integrated/new.js
+++ b/addon/routes/management/vendors/integrated/new.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class ManagementVendorsIntegratedNewRoute extends Route {}
+export default class ManagementVendorsIntegratedNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create integrated-vendor')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.management.vendors.index');
+        }
+    }
+}
diff --git a/addon/routes/operations/orders.js b/addon/routes/operations/orders.js
index 4d5b88ed7..f4cc46d1e 100644
--- a/addon/routes/operations/orders.js
+++ b/addon/routes/operations/orders.js
@@ -1,3 +1,42 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class OperationsOrdersRoute extends Route {}
+/**
+ * Orders are the FleetOps landing route (`console.fleet-ops` resolves here), so a user
+ * without `fleet-ops list order` cannot be sent back to `console.fleet-ops` - that would
+ * loop. Instead they are forwarded to the first FleetOps area they are permitted to list,
+ * falling back to the console when there is none.
+ */
+const FALLBACK_ROUTES = [
+    ['fleet-ops list driver', 'console.fleet-ops.management.drivers'],
+    ['fleet-ops list vehicle', 'console.fleet-ops.management.vehicles'],
+    ['fleet-ops list trailer', 'console.fleet-ops.management.trailers'],
+    ['fleet-ops list fleet', 'console.fleet-ops.management.fleets'],
+    ['fleet-ops list place', 'console.fleet-ops.management.places'],
+    ['fleet-ops list contact', 'console.fleet-ops.management.contacts'],
+    ['fleet-ops list vendor', 'console.fleet-ops.management.vendors'],
+    ['fleet-ops list fuel-report', 'console.fleet-ops.management.fuel-reports'],
+    ['fleet-ops list issue', 'console.fleet-ops.management.issues'],
+    ['fleet-ops list work-order', 'console.fleet-ops.maintenance.work-orders'],
+    ['fleet-ops list device', 'console.fleet-ops.connectivity.devices'],
+    ['iam list report', 'console.fleet-ops.analytics.reports'],
+];
+
+export default class OperationsOrdersRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list order')) {
+            const fallback = FALLBACK_ROUTES.find(([permission]) => this.abilities.can(permission));
+            if (fallback) {
+                return this.hostRouter.transitionTo(fallback[1]);
+            }
+
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console');
+        }
+    }
+}
diff --git a/addon/routes/operations/routes.js b/addon/routes/operations/routes.js
index de8587326..bb6a52e38 100644
--- a/addon/routes/operations/routes.js
+++ b/addon/routes/operations/routes.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class OperationsRoutesRoute extends Route {}
+export default class OperationsRoutesRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list route')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/operations/routes/index/details.js b/addon/routes/operations/routes/index/details.js
index 9ede890da..bf504a0d2 100644
--- a/addon/routes/operations/routes/index/details.js
+++ b/addon/routes/operations/routes/index/details.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class OperationsRoutesIndexDetailsRoute extends Route {}
+export default class OperationsRoutesIndexDetailsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view route')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.operations.routes.index');
+        }
+    }
+}
diff --git a/addon/routes/operations/routes/index/new.js b/addon/routes/operations/routes/index/new.js
index 3974d9c2c..b2ca429af 100644
--- a/addon/routes/operations/routes/index/new.js
+++ b/addon/routes/operations/routes/index/new.js
@@ -1,6 +1,19 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
 export default class OperationsRoutesIndexNewRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create route')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.operations.routes.index');
+        }
+    }
+
     queryParams = {
         selectedOrders: {
             refreshModel: false,
diff --git a/addon/routes/operations/service-rates.js b/addon/routes/operations/service-rates.js
index 83628deb6..e46ea3081 100644
--- a/addon/routes/operations/service-rates.js
+++ b/addon/routes/operations/service-rates.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class OperationsServiceRatesRoute extends Route {}
+export default class OperationsServiceRatesRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list service-rate')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/operations/service-rates/index/new.js b/addon/routes/operations/service-rates/index/new.js
index 81ceee92f..0659118ce 100644
--- a/addon/routes/operations/service-rates/index/new.js
+++ b/addon/routes/operations/service-rates/index/new.js
@@ -3,6 +3,17 @@ import { inject as service } from '@ember/service';
 
 export default class OperationsServiceRatesIndexNewRoute extends Route {
     @service store;
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops create service-rate')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops.operations.service-rates.index');
+        }
+    }
 
     async setupController(controller) {
         super.setupController(...arguments);
diff --git a/addon/routes/settings/avatars.js b/addon/routes/settings/avatars.js
index 22582c4e8..a6cef9606 100644
--- a/addon/routes/settings/avatars.js
+++ b/addon/routes/settings/avatars.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class SettingsAvatarsRoute extends Route {}
+export default class SettingsAvatarsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list avatar')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/settings/custom-fields.js b/addon/routes/settings/custom-fields.js
index 9563a887e..a2bb3fcbc 100644
--- a/addon/routes/settings/custom-fields.js
+++ b/addon/routes/settings/custom-fields.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class SettingsCustomFieldsRoute extends Route {}
+export default class SettingsCustomFieldsRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops list custom-field')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/settings/map.js b/addon/routes/settings/map.js
index 51f072976..6b1c6caaa 100644
--- a/addon/routes/settings/map.js
+++ b/addon/routes/settings/map.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class SettingsMapRoute extends Route {}
+export default class SettingsMapRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view map-settings')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/settings/notifications.js b/addon/routes/settings/notifications.js
index 9258c98f6..665c8a638 100644
--- a/addon/routes/settings/notifications.js
+++ b/addon/routes/settings/notifications.js
@@ -4,6 +4,17 @@ import { hash } from 'rsvp';
 
 export default class SettingsNotificationsRoute extends Route {
     @service fetch;
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view notification-settings')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
 
     model() {
         return hash({
diff --git a/addon/routes/settings/orchestrator.js b/addon/routes/settings/orchestrator.js
index f5109bd46..b6a474dd9 100644
--- a/addon/routes/settings/orchestrator.js
+++ b/addon/routes/settings/orchestrator.js
@@ -14,7 +14,7 @@ export default class SettingsOrchestratorRoute extends Route {
     @service hostRouter;
 
     beforeModel() {
-        if (this.abilities.cannot('fleet-ops list order')) {
+        if (this.abilities.cannot('fleet-ops view routing-settings')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
             return this.hostRouter.transitionTo('console.fleet-ops');
         }
diff --git a/addon/routes/settings/payments/index.js b/addon/routes/settings/payments/index.js
index bab0e134c..6925e7aa4 100644
--- a/addon/routes/settings/payments/index.js
+++ b/addon/routes/settings/payments/index.js
@@ -16,7 +16,7 @@ export default class SettingsPaymentsIndexRoute extends Route {
     };
 
     beforeModel() {
-        if (this.abilities.cannot('fleet-ops list purchase-rate')) {
+        if (this.abilities.cannot('fleet-ops view payments')) {
             this.notifications.warning(this.intl.t('common.unauthorized-access'));
             return this.hostRouter.transitionTo('console.fleet-ops');
         }
diff --git a/addon/routes/settings/routing.js b/addon/routes/settings/routing.js
index cd75821fb..bc5a75e59 100644
--- a/addon/routes/settings/routing.js
+++ b/addon/routes/settings/routing.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class SettingsRoutingRoute extends Route {}
+export default class SettingsRoutingRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view routing-settings')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/settings/scheduling.js b/addon/routes/settings/scheduling.js
index c6411b241..c64c6b68b 100644
--- a/addon/routes/settings/scheduling.js
+++ b/addon/routes/settings/scheduling.js
@@ -1,3 +1,16 @@
 import Route from '@ember/routing/route';
+import { inject as service } from '@ember/service';
 
-export default class SettingsSchedulingRoute extends Route {}
+export default class SettingsSchedulingRoute extends Route {
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
+
+    beforeModel() {
+        if (this.abilities.cannot('fleet-ops view scheduling-settings')) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
+}
diff --git a/addon/routes/virtual.js b/addon/routes/virtual.js
index b79b4e462..bbd17220e 100644
--- a/addon/routes/virtual.js
+++ b/addon/routes/virtual.js
@@ -4,6 +4,10 @@ import { inject as service } from '@ember/service';
 export default class VirtualRoute extends Route {
     @service universe;
     @service('universe/menu-service') menuService;
+    @service notifications;
+    @service hostRouter;
+    @service abilities;
+    @service intl;
 
     queryParams = {
         view: {
@@ -15,4 +19,11 @@ export default class VirtualRoute extends Route {
         const view = this.universe.getViewFromTransition(transition);
         return this.menuService.lookupMenuItem('engine:fleet-ops', slug, view, section);
     }
+
+    afterModel(menuItem) {
+        if (menuItem?.permission && this.abilities.cannot(menuItem.permission)) {
+            this.notifications.warning(this.intl.t('common.unauthorized-access'));
+            return this.hostRouter.transitionTo('console.fleet-ops');
+        }
+    }
 }

From 44da70863e3d304125e8612ac49a6d8c4fdcbb3e Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Sun, 27 Sep 2026 14:42:23 +0800
Subject: [PATCH 11/24] refactor(permissions): declare method permissions and
 enforce them as controller middleware

- Move the explicit checks out of method bodies into a declarative map:
  FleetOpsController registers `$methodPermissions` (method => permission) as
  controller middleware via the AuthorizesMethods trait, and non-resource
  controllers call authorizeMethods() in their constructor. Behaviour through
  the router is unchanged; unit tests that call controller methods directly
  keep exercising the endpoint logic.
- Navigator links are signed with an HMAC over the expiry
  (NavigatorController::linkSignature) instead of Laravel's signed routes, so
  the link no longer depends on a named route or the URL generator.
- Tests: signed/unsigned/tampered/expired Navigator links; entity editing
  settings keep other companies' entries and ignore keys for foreign order
  configs; driver onboard settings ignore a request-supplied company id.
---
 .../Http/Controllers/FleetOpsController.php   | 21 +++++++
 .../Internal/v1/ContactController.php         | 12 +++-
 .../Internal/v1/CustomerController.php        | 25 +++++----
 .../Internal/v1/DeviceController.php          | 15 +++--
 .../Internal/v1/DeviceEventController.php     | 12 +++-
 .../Internal/v1/DriverController.php          | 29 +++++-----
 .../v1/FuelProviderConnectionController.php   | 15 +++--
 .../v1/FuelProviderTransactionController.php  | 18 +++---
 .../Internal/v1/InspectionFormController.php  | 18 +++---
 .../Internal/v1/LiveController.php            | 31 ++++++-----
 .../Internal/v1/MaintenanceController.php     | 18 +++---
 .../v1/MaintenanceScheduleController.php      | 18 +++---
 .../Internal/v1/ManifestController.php        | 28 +++++-----
 .../Internal/v1/NavigatorController.php       | 43 ++++++++++++---
 .../Internal/v1/OrchestrationController.php   | 27 ++++-----
 .../Internal/v1/OrderController.php           | 29 +++++-----
 .../Internal/v1/PaymentController.php         | 22 +++++---
 .../Internal/v1/RadarController.php           | 40 +++++++-------
 .../Internal/v1/SettingController.php         | 55 ++++++++-----------
 .../Internal/v1/TelematicController.php       | 27 ++++-----
 .../Internal/v1/TrailerController.php         | 27 ++++-----
 .../Internal/v1/VehicleController.php         | 27 ++++-----
 .../Internal/v1/VendorController.php          | 21 ++++---
 .../Internal/v1/WorkOrderController.php       | 12 +++-
 server/src/Traits/AuthorizesMethods.php       | 37 +++++++++++++
 server/src/routes.php                         |  2 +-
 .../NavigatorControllerContractsTest.php      | 40 ++++++++++++--
 .../tests/SettingControllerContractsTest.php  | 27 ++++++---
 28 files changed, 437 insertions(+), 259 deletions(-)
 create mode 100644 server/src/Traits/AuthorizesMethods.php

diff --git a/server/src/Http/Controllers/FleetOpsController.php b/server/src/Http/Controllers/FleetOpsController.php
index fadafc391..dbad90ef7 100644
--- a/server/src/Http/Controllers/FleetOpsController.php
+++ b/server/src/Http/Controllers/FleetOpsController.php
@@ -2,12 +2,33 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers;
 
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\FleetbaseController;
+use Illuminate\Database\Eloquent\Model;
 
 class FleetOpsController extends FleetbaseController
 {
+    use AuthorizesMethods;
+
     /**
      * The package namespace used to resolve from.
      */
     public string $namespace = '\\Fleetbase\\FleetOps';
+
+    /**
+     * Explicit permissions for custom actions, keyed by controller method, e.g.
+     * `['bulkDispatch' => 'dispatch order']`. Those methods also carry
+     * `#[SkipAuthorizationCheck]` so AuthorizationGuard does not demand the
+     * permission it would otherwise infer from the HTTP verb.
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [];
+
+    public function __construct(?Model $model = null, ?string $resource = null)
+    {
+        parent::__construct($model, $resource);
+
+        $this->authorizeMethods($this->methodPermissions);
+    }
 }
diff --git a/server/src/Http/Controllers/Internal/v1/ContactController.php b/server/src/Http/Controllers/Internal/v1/ContactController.php
index a17605ec2..f4b3346f2 100644
--- a/server/src/Http/Controllers/Internal/v1/ContactController.php
+++ b/server/src/Http/Controllers/Internal/v1/ContactController.php
@@ -15,7 +15,6 @@
 use Fleetbase\FleetOps\Models\PurchaseRate;
 use Fleetbase\FleetOps\Models\Vendor;
 use Fleetbase\FleetOps\Models\VendorPersonnel;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
@@ -28,6 +27,15 @@
 
 class ContactController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'convertToVendor' => 'create vendor',
+    ];
+
     /**
      * The resource to query.
      *
@@ -113,8 +121,6 @@ public function getAsCustomer($id)
     #[SkipAuthorizationCheck]
     public function convertToVendor(Request $request, string $id)
     {
-        Authorization::authorize('create vendor');
-
         $contact = $this->contactForVendorConversion($id);
 
         $vendor = $this->runContactConversionTransaction(function () use ($contact, $request) {
diff --git a/server/src/Http/Controllers/Internal/v1/CustomerController.php b/server/src/Http/Controllers/Internal/v1/CustomerController.php
index 8c91a537f..b20ed00b4 100644
--- a/server/src/Http/Controllers/Internal/v1/CustomerController.php
+++ b/server/src/Http/Controllers/Internal/v1/CustomerController.php
@@ -4,8 +4,8 @@
 
 use Fleetbase\FleetOps\Mail\CustomerCredentialsMail;
 use Fleetbase\FleetOps\Models\Contact;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\ProfileAccountManager;
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Models\User;
 use Illuminate\Http\Request;
@@ -14,10 +14,21 @@
 
 class CustomerController extends Controller
 {
-    public function createPortalLogin(Request $request)
+    use AuthorizesMethods;
+
+    public function __construct()
     {
-        Authorization::authorize('reset-credentials-for customer');
+        $this->authorizeMethods([
+            'createPortalLogin'     => 'reset-credentials-for customer',
+            'sendCredentials'       => 'reset-credentials-for customer',
+            'deactivatePortalLogin' => 'reset-credentials-for customer',
+            'reactivatePortalLogin' => 'reset-credentials-for customer',
+            'resetCredentials'      => 'reset-credentials-for customer',
+        ]);
+    }
 
+    public function createPortalLogin(Request $request)
+    {
         $customer = $this->resolveCustomer($request);
         $user     = $this->resolveCustomerUser($customer);
 
@@ -40,8 +51,6 @@ public function createPortalLogin(Request $request)
 
     public function sendCredentials(Request $request)
     {
-        Authorization::authorize('reset-credentials-for customer');
-
         $customer = $this->resolveCustomer($request);
         $user     = $this->resolveCustomerUser($customer);
 
@@ -64,8 +73,6 @@ public function sendCredentials(Request $request)
 
     public function deactivatePortalLogin(Request $request)
     {
-        Authorization::authorize('reset-credentials-for customer');
-
         $customer = $this->resolveCustomer($request);
         $user     = $customer->user_uuid ? $this->findUser($customer->user_uuid) : null;
 
@@ -86,8 +93,6 @@ public function deactivatePortalLogin(Request $request)
 
     public function reactivatePortalLogin(Request $request)
     {
-        Authorization::authorize('reset-credentials-for customer');
-
         $customer = $this->resolveCustomer($request);
         $user     = $customer->user_uuid ? $this->findUser($customer->user_uuid) : null;
 
@@ -154,8 +159,6 @@ public function reactivatePortalLogin(Request $request)
      */
     public function resetCredentials(Request $request)
     {
-        Authorization::authorize('reset-credentials-for customer');
-
         $customerId      = $request->input('customer');
         $password        = $request->input('password');
         $confirmPassword = $request->input('password_confirmation');
diff --git a/server/src/Http/Controllers/Internal/v1/DeviceController.php b/server/src/Http/Controllers/Internal/v1/DeviceController.php
index 6396af206..ce969fbc2 100644
--- a/server/src/Http/Controllers/Internal/v1/DeviceController.php
+++ b/server/src/Http/Controllers/Internal/v1/DeviceController.php
@@ -8,7 +8,6 @@
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Models\Device;
 use Fleetbase\FleetOps\Models\Vehicle;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
 use Illuminate\Http\JsonResponse;
@@ -19,6 +18,16 @@
 
 class DeviceController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'attach' => 'update device',
+        'detach' => 'update device',
+    ];
+
     /**
      * The resource to query.
      *
@@ -115,8 +124,6 @@ public static function onFindRecord($query, $request): void
     #[SkipAuthorizationCheck]
     public function attach(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update device');
-
         $request->validate([
             'vehicle' => 'required_without:attachable_uuid|nullable|string',
         ]);
@@ -160,8 +167,6 @@ public function attach(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function detach(string $id): JsonResponse
     {
-        Authorization::authorize('update device');
-
         $device = $this->resolveDevice($id);
 
         if (!$device) {
diff --git a/server/src/Http/Controllers/Internal/v1/DeviceEventController.php b/server/src/Http/Controllers/Internal/v1/DeviceEventController.php
index 3cc196f07..8735cc042 100644
--- a/server/src/Http/Controllers/Internal/v1/DeviceEventController.php
+++ b/server/src/Http/Controllers/Internal/v1/DeviceEventController.php
@@ -5,12 +5,20 @@
 use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Models\DeviceEvent;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Utils;
 use Illuminate\Http\JsonResponse;
 
 class DeviceEventController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'markProcessed' => 'update device-event',
+    ];
+
     /**
      * The resource to query.
      *
@@ -56,8 +64,6 @@ public static function onQueryRecord($query, $request): void
     #[SkipAuthorizationCheck]
     public function markProcessed(string $id): JsonResponse
     {
-        Authorization::authorize('update device-event');
-
         $deviceEvent = DeviceEvent::where('company_uuid', session('company'))
             ->where(function ($query) use ($id) {
                 $query->where('uuid', $id)->orWhere('public_id', $id);
diff --git a/server/src/Http/Controllers/Internal/v1/DriverController.php b/server/src/Http/Controllers/Internal/v1/DriverController.php
index 69d47885b..87d591cee 100644
--- a/server/src/Http/Controllers/Internal/v1/DriverController.php
+++ b/server/src/Http/Controllers/Internal/v1/DriverController.php
@@ -15,7 +15,6 @@
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Vehicle;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\ProfileAccountManager;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
@@ -35,6 +34,20 @@
 class DriverController extends FleetOpsController
 {
     use Traits\DriverSchedulingTrait;
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'sendCredentials'  => 'update-user-for driver',
+        'resetCredentials' => 'update-user-for driver',
+        'deactivateLogin'  => 'update-user-for driver',
+        'reactivateLogin'  => 'update-user-for driver',
+        'unassignOrders'   => 'assign-order-for driver',
+        'unassignOrder'    => 'assign-order-for driver',
+        'unassignVehicle'  => 'assign-vehicle-for driver',
+    ];
     /**
      * The resource to query.
      *
@@ -205,8 +218,6 @@ function ($request, &$driver) {
     #[SkipAuthorizationCheck]
     public function sendCredentials(string $id)
     {
-        Authorization::authorize('update-user-for driver');
-
         [$driver, $user, $error] = $this->resolveDriverLogin($id);
         if ($error) {
             return $error;
@@ -229,8 +240,6 @@ public function sendCredentials(string $id)
     #[SkipAuthorizationCheck]
     public function resetCredentials(Request $request, string $id)
     {
-        Authorization::authorize('update-user-for driver');
-
         $password = $request->input('password');
         if (!is_string($password) || strlen($password) < 8) {
             return response()->error('Password must be at least 8 characters.');
@@ -266,8 +275,6 @@ public function resetCredentials(Request $request, string $id)
     #[SkipAuthorizationCheck]
     public function deactivateLogin(string $id)
     {
-        Authorization::authorize('update-user-for driver');
-
         [$driver, $user, $error] = $this->resolveDriverLogin($id);
         if ($error) {
             return $error;
@@ -289,8 +296,6 @@ public function deactivateLogin(string $id)
     #[SkipAuthorizationCheck]
     public function reactivateLogin(string $id)
     {
-        Authorization::authorize('update-user-for driver');
-
         [$driver, $user, $error] = $this->resolveDriverLogin($id);
         if ($error) {
             return $error;
@@ -447,8 +452,6 @@ public function assignedOrders(string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function unassignOrders(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('assign-order-for driver');
-
         $request->validate([
             'orders'   => 'required|array|min:1',
             'orders.*' => 'required|string',
@@ -482,8 +485,6 @@ public function unassignOrders(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function unassignOrder(string $id): JsonResponse
     {
-        Authorization::authorize('assign-order-for driver');
-
         $driver = $this->findDriver($id);
         $order  = $this->currentAssignedOrderForDriver($driver) ?? $driver->getCurrentOrder();
 
@@ -521,8 +522,6 @@ public function assignVehicle(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function unassignVehicle(string $id): JsonResponse
     {
-        Authorization::authorize('assign-vehicle-for driver');
-
         $driver  = $this->findDriver($id);
         $vehicle = $driver->vehicle;
 
diff --git a/server/src/Http/Controllers/Internal/v1/FuelProviderConnectionController.php b/server/src/Http/Controllers/Internal/v1/FuelProviderConnectionController.php
index 9123b346a..df99e25e3 100644
--- a/server/src/Http/Controllers/Internal/v1/FuelProviderConnectionController.php
+++ b/server/src/Http/Controllers/Internal/v1/FuelProviderConnectionController.php
@@ -6,7 +6,6 @@
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Jobs\SyncFuelProviderTransactionsJob;
 use Fleetbase\FleetOps\Models\FuelProviderConnection;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\FuelProviders\FuelProviderService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -15,6 +14,16 @@
 
 class FuelProviderConnectionController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'testCredentials' => 'create fuel-provider-connection',
+        'testConnection'  => 'update fuel-provider-connection',
+    ];
+
     public $resource = 'fuel_provider_connection';
 
     public function __construct(protected FuelProviderService $fuelProviderService)
@@ -43,8 +52,6 @@ public function onBeforeUpdate(Request $request, FuelProviderConnection $connect
     #[SkipAuthorizationCheck]
     public function testCredentials(Request $request, string $provider): JsonResponse
     {
-        Authorization::authorize('create fuel-provider-connection');
-
         $request->validate([
             'credentials' => 'required|array',
             'environment' => 'nullable|string|in:production,sandbox',
@@ -62,8 +69,6 @@ public function testCredentials(Request $request, string $provider): JsonRespons
     #[SkipAuthorizationCheck]
     public function testConnection(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update fuel-provider-connection');
-
         $connection = $this->findConnection($id);
         $result     = $this->fuelProviderService->testConnection($connection);
 
diff --git a/server/src/Http/Controllers/Internal/v1/FuelProviderTransactionController.php b/server/src/Http/Controllers/Internal/v1/FuelProviderTransactionController.php
index 74ccd0d41..b219793ff 100644
--- a/server/src/Http/Controllers/Internal/v1/FuelProviderTransactionController.php
+++ b/server/src/Http/Controllers/Internal/v1/FuelProviderTransactionController.php
@@ -5,13 +5,23 @@
 use Fleetbase\Attributes\SkipAuthorizationCheck;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Models\FuelProviderTransaction;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\FuelProviders\FuelProviderService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 
 class FuelProviderTransactionController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'matchVehicle' => 'update fuel-provider-transaction',
+        'matchOrder'   => 'update fuel-provider-transaction',
+        'reprocess'    => 'update fuel-provider-transaction',
+    ];
+
     public $resource = 'fuel_provider_transaction';
 
     public function __construct(protected FuelProviderService $fuelProviderService)
@@ -27,8 +37,6 @@ public static function onQueryRecord($query, $request): void
     #[SkipAuthorizationCheck]
     public function matchVehicle(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update fuel-provider-transaction');
-
         $request->validate(['vehicle' => 'required|string']);
         $transaction = $this->findTransaction($id);
 
@@ -41,8 +49,6 @@ public function matchVehicle(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function matchOrder(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update fuel-provider-transaction');
-
         $request->validate(['order' => 'required|string']);
         $transaction = $this->findTransaction($id);
 
@@ -55,8 +61,6 @@ public function matchOrder(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function reprocess(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update fuel-provider-transaction');
-
         $transaction = $this->findTransaction($id);
 
         return response()->json([
diff --git a/server/src/Http/Controllers/Internal/v1/InspectionFormController.php b/server/src/Http/Controllers/Internal/v1/InspectionFormController.php
index 3ff7f8c0b..f7766cbbd 100644
--- a/server/src/Http/Controllers/Internal/v1/InspectionFormController.php
+++ b/server/src/Http/Controllers/Internal/v1/InspectionFormController.php
@@ -9,7 +9,6 @@
 use Fleetbase\FleetOps\Models\InspectionForm;
 use Fleetbase\FleetOps\Models\InspectionLink;
 use Fleetbase\FleetOps\Models\Vehicle;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\InspectionFormSync;
 use Fleetbase\FleetOps\Support\InspectionLinkPin;
 use Fleetbase\Models\User;
@@ -18,6 +17,17 @@
 
 class InspectionFormController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'generateLink' => 'publish inspection-form',
+        'revokeLink'   => 'publish inspection-form',
+        'sendPin'      => 'publish inspection-form',
+    ];
+
     /**
      * The resource to query.
      *
@@ -112,8 +122,6 @@ public function archive(string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function generateLink(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('publish inspection-form');
-
         $form = $this->resolveForm($id)
             ->firstOrFail();
 
@@ -223,8 +231,6 @@ public function links(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function revokeLink(Request $request, string $id, string $linkId): JsonResponse
     {
-        Authorization::authorize('publish inspection-form');
-
         $form = $this->resolveForm($id)->firstOrFail();
 
         $link = InspectionLink::where('inspection_form_uuid', $form->uuid)
@@ -254,8 +260,6 @@ public function revokeLink(Request $request, string $id, string $linkId): JsonRe
     #[SkipAuthorizationCheck]
     public function sendPin(Request $request, string $id, string $linkId): JsonResponse
     {
-        Authorization::authorize('publish inspection-form');
-
         $form      = $this->resolveForm($id)->firstOrFail();
         $validated = $request->validate(['via' => 'required|in:email,sms']);
 
diff --git a/server/src/Http/Controllers/Internal/v1/LiveController.php b/server/src/Http/Controllers/Internal/v1/LiveController.php
index 5c8e8be74..690960baf 100644
--- a/server/src/Http/Controllers/Internal/v1/LiveController.php
+++ b/server/src/Http/Controllers/Internal/v1/LiveController.php
@@ -15,10 +15,10 @@
 use Fleetbase\FleetOps\Models\Place;
 use Fleetbase\FleetOps\Models\Route;
 use Fleetbase\FleetOps\Models\Vehicle;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\LiveCacheService;
 use Fleetbase\FleetOps\Support\LiveOrderQuery;
 use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\Controller;
 use Illuminate\Http\Request;
 
@@ -27,6 +27,21 @@
  */
 class LiveController extends Controller
 {
+    use AuthorizesMethods;
+
+    public function __construct()
+    {
+        $this->authorizeMethods([
+            'coordinates'           => 'list order',
+            'routes'                => 'list order',
+            'orders'                => 'list order',
+            'drivers'               => 'list driver',
+            'vehicles'              => 'list vehicle',
+            'operationsMonitor'     => 'list order',
+            'places'                => 'list place',
+        ]);
+    }
+
     protected const DEFAULT_VIEWPORT_LIMIT    = 500;
     protected const MAX_VIEWPORT_LIMIT        = 1000;
     protected const VIEWPORT_BOUNDS_PRECISION = 4;
@@ -38,8 +53,6 @@ class LiveController extends Controller
      */
     public function coordinates()
     {
-        Authorization::authorize('list order');
-
         return LiveCacheService::remember('coordinates', [], function () {
             $coordinates = [];
 
@@ -73,8 +86,6 @@ public function coordinates()
      */
     public function routes()
     {
-        Authorization::authorize('list order');
-
         return LiveCacheService::remember('routes', [], function () {
             // Fetch routes that are not canceled or completed and have an assigned driver
             $routes = Route::where('company_uuid', session('company'))
@@ -112,8 +123,6 @@ function ($q) {
      */
     public function orders(Request $request)
     {
-        Authorization::authorize('list order');
-
         $exclude     = $request->array('exclude');
         $active      = $request->boolean('active');
         $unassigned  = $request->boolean('unassigned');
@@ -149,8 +158,6 @@ public function orders(Request $request)
      */
     public function drivers(Request $request)
     {
-        Authorization::authorize('list driver');
-
         $bounds      = $this->normalizeLiveBounds($request);
         $limit       = $this->normalizeLiveLimit($request);
         $cacheParams = ['bounds' => $bounds, 'limit' => $limit];
@@ -178,8 +185,6 @@ public function drivers(Request $request)
      */
     public function vehicles(Request $request)
     {
-        Authorization::authorize('list vehicle');
-
         $bounds      = $this->normalizeLiveBounds($request);
         $limit       = $this->normalizeLiveLimit($request);
         $cacheParams = ['bounds' => $bounds, 'limit' => $limit];
@@ -208,8 +213,6 @@ public function vehicles(Request $request)
      */
     public function operationsMonitor()
     {
-        Authorization::authorize('list order');
-
         return LiveCacheService::remember('operations-monitor', [], function () {
             $drivers = Driver::where(['company_uuid' => session('company')])
                 ->with(['user', 'vehicle'])
@@ -383,8 +386,6 @@ protected function buildOperationsMonitorFleetTree($fleetNodes): array
      */
     public function places(Request $request)
     {
-        Authorization::authorize('list place');
-
         $bounds = $this->normalizeLiveBounds($request);
         $limit  = $this->normalizeLiveLimit($request);
 
diff --git a/server/src/Http/Controllers/Internal/v1/MaintenanceController.php b/server/src/Http/Controllers/Internal/v1/MaintenanceController.php
index 0f9344a12..4205c2fe9 100644
--- a/server/src/Http/Controllers/Internal/v1/MaintenanceController.php
+++ b/server/src/Http/Controllers/Internal/v1/MaintenanceController.php
@@ -7,7 +7,6 @@
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Imports\MaintenanceImport;
 use Fleetbase\FleetOps\Models\Maintenance;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Illuminate\Http\JsonResponse;
@@ -17,6 +16,17 @@
 
 class MaintenanceController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'addLineItem'    => 'update maintenance',
+        'updateLineItem' => 'update maintenance',
+        'removeLineItem' => 'update maintenance',
+    ];
+
     /**
      * The resource to query.
      *
@@ -72,8 +82,6 @@ public function onFindRecord($builder, $request): void
     #[SkipAuthorizationCheck]
     public function addLineItem(string $id, Request $request): JsonResponse
     {
-        Authorization::authorize('update maintenance');
-
         $maintenance = $this->findMaintenanceForLineItem($id);
 
         $validated = $request->validate([
@@ -97,8 +105,6 @@ public function addLineItem(string $id, Request $request): JsonResponse
     #[SkipAuthorizationCheck]
     public function updateLineItem(string $id, int $index, Request $request): JsonResponse
     {
-        Authorization::authorize('update maintenance');
-
         $maintenance = $this->findMaintenanceForLineItem($id);
 
         $validated = $request->validate([
@@ -132,8 +138,6 @@ public function updateLineItem(string $id, int $index, Request $request): JsonRe
     #[SkipAuthorizationCheck]
     public function removeLineItem(string $id, int $index): JsonResponse
     {
-        Authorization::authorize('update maintenance');
-
         $maintenance = $this->findMaintenanceForLineItem($id);
 
         if (!$maintenance->removeLineItem($index)) {
diff --git a/server/src/Http/Controllers/Internal/v1/MaintenanceScheduleController.php b/server/src/Http/Controllers/Internal/v1/MaintenanceScheduleController.php
index fe930c9f8..083ef8aad 100644
--- a/server/src/Http/Controllers/Internal/v1/MaintenanceScheduleController.php
+++ b/server/src/Http/Controllers/Internal/v1/MaintenanceScheduleController.php
@@ -8,7 +8,6 @@
 use Fleetbase\FleetOps\Imports\MaintenanceScheduleImport;
 use Fleetbase\FleetOps\Models\MaintenanceSchedule;
 use Fleetbase\FleetOps\Models\WorkOrder;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Illuminate\Http\JsonResponse;
@@ -24,6 +23,17 @@
 
 class MaintenanceScheduleController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'pause'   => 'update maintenance-schedule',
+        'resume'  => 'update maintenance-schedule',
+        'trigger' => 'update maintenance-schedule',
+    ];
+
     /**
      * The resource to query.
      *
@@ -76,8 +86,6 @@ public function import(ImportRequest $request)
     #[SkipAuthorizationCheck]
     public function pause(string $id): JsonResponse
     {
-        Authorization::authorize('update maintenance-schedule');
-
         $schedule = $this->findSchedule($id);
 
         $schedule->pause();
@@ -96,8 +104,6 @@ public function pause(string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function resume(string $id): JsonResponse
     {
-        Authorization::authorize('update maintenance-schedule');
-
         $schedule = $this->findSchedule($id);
 
         $schedule->resume();
@@ -116,8 +122,6 @@ public function resume(string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function trigger(string $id, Request $request): JsonResponse
     {
-        Authorization::authorize('update maintenance-schedule');
-
         $schedule  = $this->findSchedule($id);
         $workOrder = $this->createWorkOrderFromSchedule($schedule);
 
diff --git a/server/src/Http/Controllers/Internal/v1/ManifestController.php b/server/src/Http/Controllers/Internal/v1/ManifestController.php
index dbd93c044..42329337d 100644
--- a/server/src/Http/Controllers/Internal/v1/ManifestController.php
+++ b/server/src/Http/Controllers/Internal/v1/ManifestController.php
@@ -4,7 +4,7 @@
 
 use Fleetbase\FleetOps\Models\Manifest;
 use Fleetbase\FleetOps\Models\ManifestStop;
-use Fleetbase\FleetOps\Support\Authorization;
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\Controller;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
@@ -24,6 +24,20 @@
  */
 class ManifestController extends Controller
 {
+    use AuthorizesMethods;
+
+    public function __construct()
+    {
+        $this->authorizeMethods([
+            'index'      => 'list order',
+            'show'       => 'view order',
+            'cancel'     => 'cancel order',
+            'destroy'    => 'delete order',
+            'showStop'   => 'view order',
+            'updateStop' => 'update order',
+        ]);
+    }
+
     /**
      * List manifests for the current company.
      * Supports filtering by status, driver_id, vehicle_id, and scheduled_date.
@@ -32,8 +46,6 @@ class ManifestController extends Controller
      */
     public function index(Request $request): JsonResponse
     {
-        Authorization::authorize('list order');
-
         $companyUuid = session('company');
         $query       = $this->manifestQueryForCompany($companyUuid);
 
@@ -62,8 +74,6 @@ public function index(Request $request): JsonResponse
      */
     public function show(string $id): JsonResponse
     {
-        Authorization::authorize('view order');
-
         $manifest = $this->manifestQueryByPublicId($id)
             ->with($this->manifestShowRelations())
             ->firstOrFail();
@@ -78,8 +88,6 @@ public function show(string $id): JsonResponse
      */
     public function cancel(string $id): JsonResponse
     {
-        Authorization::authorize('cancel order');
-
         $manifest = $this->manifestQueryByPublicId($id)->firstOrFail();
         $manifest->cancel();
 
@@ -93,8 +101,6 @@ public function cancel(string $id): JsonResponse
      */
     public function destroy(string $id): JsonResponse
     {
-        Authorization::authorize('delete order');
-
         $manifest = $this->manifestQueryByPublicId($id)->firstOrFail();
         $manifest->delete();
 
@@ -108,8 +114,6 @@ public function destroy(string $id): JsonResponse
      */
     public function showStop(string $id): JsonResponse
     {
-        Authorization::authorize('view order');
-
         $stop = $this->manifestStopQueryByPublicId($id)
             ->with(['place', 'order.trackingNumber', 'order.payload.dropoff', 'waypoint'])
             ->firstOrFail();
@@ -126,8 +130,6 @@ public function showStop(string $id): JsonResponse
      */
     public function updateStop(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update order');
-
         $stop = $this->manifestStopQueryByPublicId($id)->firstOrFail();
 
         $allowed = ['status', 'sequence', 'actual_arrival', 'meta'];
diff --git a/server/src/Http/Controllers/Internal/v1/NavigatorController.php b/server/src/Http/Controllers/Internal/v1/NavigatorController.php
index 9cf8fb197..2da2fdc5e 100644
--- a/server/src/Http/Controllers/Internal/v1/NavigatorController.php
+++ b/server/src/Http/Controllers/Internal/v1/NavigatorController.php
@@ -2,8 +2,8 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Utils;
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Http\Resources\Organization;
 use Fleetbase\Models\ApiCredential;
@@ -12,11 +12,23 @@
 use Fleetbase\Models\User;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Redirect;
-use Illuminate\Support\Facades\URL;
 use Illuminate\Support\Str;
 
 class NavigatorController extends Controller
 {
+    use AuthorizesMethods;
+    /**
+     * How long a Navigator link issued from the console stays valid.
+     */
+    public const LINK_TTL_MINUTES = 30;
+
+    public function __construct()
+    {
+        $this->authorizeMethods([
+            'getLinkAppUrl' => 'admin',
+        ]);
+    }
+
     /**
      * Redirects to the Fleetbase Navigator app using a deep link.
      * Automatically detects the platform (iOS or Android) and uses the correct URI scheme.
@@ -27,7 +39,7 @@ public function linkApp(Request $request)
     {
         // This route is opened from a phone without a console session, so it is
         // authorised by the short-lived signature issued by getLinkAppUrl().
-        if (!$request->hasValidRelativeSignature()) {
+        if (!$this->hasValidLinkSignature($request)) {
             return response()->error('This Navigator link is invalid or has expired. Generate a new one from the console.', 403);
         }
 
@@ -75,12 +87,13 @@ public function linkApp(Request $request)
      */
     public function getLinkAppUrl()
     {
-        Authorization::authorizeAdmin();
-
-        $path = URL::temporarySignedRoute('fleetops.navigator.link-app', now()->addMinutes(30), [], false);
+        $expires = now()->addMinutes(static::LINK_TTL_MINUTES)->getTimestamp();
 
         return response()->json([
-            'linkUrl' => url($path),
+            'linkUrl' => url('int/v1/fleet-ops/navigator/link-app') . '?' . http_build_query([
+                'expires'   => $expires,
+                'signature' => static::linkSignature($expires),
+            ]),
         ]);
     }
 
@@ -201,4 +214,20 @@ protected function driverOnboardSettings(): mixed
     {
         return Setting::where('key', 'fleet-ops.driver-onboard')->value('value');
     }
+
+    /**
+     * HMAC signature for a Navigator link expiring at the given unix timestamp.
+     */
+    public static function linkSignature(int $expires): string
+    {
+        return hash_hmac('sha256', 'fleet-ops.navigator.link-app|' . $expires, (string) config('app.key'));
+    }
+
+    protected function hasValidLinkSignature(Request $request): bool
+    {
+        $expires   = (int) $request->query('expires');
+        $signature = (string) $request->query('signature');
+
+        return $signature !== '' && $expires >= time() && hash_equals(static::linkSignature($expires), $signature);
+    }
 }
diff --git a/server/src/Http/Controllers/Internal/v1/OrchestrationController.php b/server/src/Http/Controllers/Internal/v1/OrchestrationController.php
index 2e795fd65..965960a58 100644
--- a/server/src/Http/Controllers/Internal/v1/OrchestrationController.php
+++ b/server/src/Http/Controllers/Internal/v1/OrchestrationController.php
@@ -16,7 +16,7 @@
 use Fleetbase\FleetOps\Orchestration\Engines\DriverAssignmentEngine;
 use Fleetbase\FleetOps\Orchestration\Engines\RouteSequencingEngine;
 use Fleetbase\FleetOps\Orchestration\OrchestrationEngineRegistry;
-use Fleetbase\FleetOps\Support\Authorization;
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Models\Setting;
 use Illuminate\Http\JsonResponse;
@@ -40,8 +40,19 @@
  */
 class OrchestrationController extends Controller
 {
+    use AuthorizesMethods;
+
     public function __construct(protected OrchestrationEngineRegistry $registry)
     {
+        $this->authorizeMethods([
+            'orders'                => 'list order',
+            'run'                   => 'optimize order',
+            'preview'               => 'list order',
+            'commit'                => 'assign-driver-for order',
+            'engines'               => 'list order',
+            'orderConfigFields'     => 'list order',
+            'importOrders'          => 'import order',
+        ]);
     }
 
     /**
@@ -55,8 +66,6 @@ public function __construct(protected OrchestrationEngineRegistry $registry)
      */
     public function orders(Request $request): JsonResponse
     {
-        Authorization::authorize('list order');
-
         $companyUuid = $this->companyUuid();
 
         $query = $this->orchestratorOrdersQuery($companyUuid);
@@ -121,8 +130,6 @@ public function orders(Request $request): JsonResponse
      */
     public function run(Request $request): JsonResponse
     {
-        Authorization::authorize('optimize order');
-
         $companyUuid       = $this->companyUuid();
         $mode              = $request->input('mode', 'assign_vehicles');
         $orderIds          = $request->input('order_ids', []);
@@ -328,8 +335,6 @@ public function run(Request $request): JsonResponse
      */
     public function preview(Request $request): JsonResponse
     {
-        Authorization::authorize('list order');
-
         return $this->run($request);
     }
 
@@ -402,8 +407,6 @@ protected function routeSequencingEngine(): RouteSequencingEngine
      */
     public function commit(Request $request): JsonResponse
     {
-        Authorization::authorize('assign-driver-for order');
-
         $assignments   = $request->input('assignments', []);
         $scheduledDate = $request->input('scheduled_date', now()->toDateString());
         $companyUuid   = session('company');
@@ -587,8 +590,6 @@ protected function updateWaypointSequence(string $payloadUuid, string $waypointP
      */
     public function engines(): JsonResponse
     {
-        Authorization::authorize('list order');
-
         return response()->json([
             'engines' => $this->registry->available(),
         ]);
@@ -602,8 +603,6 @@ public function engines(): JsonResponse
      */
     public function orderConfigFields(): JsonResponse
     {
-        Authorization::authorize('list order');
-
         $companyUuid = session('company');
 
         $configs = $this->getOrderConfigFieldConfigs($companyUuid)
@@ -661,8 +660,6 @@ protected function getCustomFieldsForOrderConfig(string $orderConfigUuid)
      */
     public function importOrders(Request $request): JsonResponse
     {
-        Authorization::authorize('import order');
-
         $rows        = $request->input('rows', []);
         $companyUuid = session('company');
 
diff --git a/server/src/Http/Controllers/Internal/v1/OrderController.php b/server/src/Http/Controllers/Internal/v1/OrderController.php
index 6f69fc5cd..32b762c42 100644
--- a/server/src/Http/Controllers/Internal/v1/OrderController.php
+++ b/server/src/Http/Controllers/Internal/v1/OrderController.php
@@ -33,7 +33,6 @@
 use Fleetbase\FleetOps\Models\TrackingStatus;
 use Fleetbase\FleetOps\Models\Waypoint;
 use Fleetbase\FleetOps\Notifications\OrderPing;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\ResolvesOrderServiceStops;
 use Fleetbase\FleetOps\Support\Utils;
 use Fleetbase\Http\Requests\ExportRequest;
@@ -55,6 +54,20 @@
 class OrderController extends FleetOpsController
 {
     use ResolvesOrderServiceStops;
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'editOrderRoute'   => 'update-route-for order',
+        'importFromFiles'  => 'import order',
+        'bulkCancel'       => 'cancel order',
+        'bulkDispatch'     => 'dispatch order',
+        'bulkAssignDriver' => 'assign-driver-for order',
+        'dispatchOrder'    => 'dispatch order',
+        'scheduleOrder'    => 'schedule order',
+    ];
 
     /**
      * The resource to query.
@@ -272,8 +285,6 @@ protected function normalizeCustomerType(array &$input): void
     #[SkipAuthorizationCheck]
     public function editOrderRoute(string $id, Request $request)
     {
-        Authorization::authorize('update-route-for order');
-
         $pickup            = $request->input('pickup');
         $dropoff           = $request->input('dropoff');
         $return            = $request->input('return');
@@ -345,8 +356,6 @@ public function editOrderRoute(string $id, Request $request)
     #[SkipAuthorizationCheck]
     public function importFromFiles(Request $request)
     {
-        Authorization::authorize('import order');
-
         $info    = Utils::lookupIp();
         $disk    = $request->input('disk', config('filesystems.default'));
         $files   = $request->input('files');
@@ -420,8 +429,6 @@ public function importFromFiles(Request $request)
     #[SkipAuthorizationCheck]
     public function bulkCancel(Request $request)
     {
-        Authorization::authorize('cancel order');
-
         $request->validate([
             'ids' => ['required', 'array'],
         ]);
@@ -468,8 +475,6 @@ public function bulkCancel(Request $request)
     #[SkipAuthorizationCheck]
     public function bulkDispatch(BulkDispatchRequest $request)
     {
-        Authorization::authorize('dispatch order');
-
         /** @var Order */
         $orders = $this->ordersByUuid($request->input('ids'));
 
@@ -519,8 +524,6 @@ public function bulkDispatch(BulkDispatchRequest $request)
     #[SkipAuthorizationCheck]
     public function bulkAssignDriver(Request $request)
     {
-        Authorization::authorize('assign-driver-for order');
-
         // Validate Inputs
         $data = $this->validateBulkAssignDriverRequest($request);
 
@@ -598,8 +601,6 @@ public function cancel(CancelOrderRequest $request)
     #[SkipAuthorizationCheck]
     public function dispatchOrder(Request $request)
     {
-        Authorization::authorize('dispatch order');
-
         /**
          * @var Order
          */
@@ -1929,8 +1930,6 @@ function ($query) use ($trackingNumber) {
     #[SkipAuthorizationCheck]
     public function scheduleOrder(Request $request)
     {
-        Authorization::authorize('schedule order');
-
         $orderId     = $request->input('order');
         $scheduledAt = $request->input('scheduled_at');
         $driverId    = $request->input('driver_id');
diff --git a/server/src/Http/Controllers/Internal/v1/PaymentController.php b/server/src/Http/Controllers/Internal/v1/PaymentController.php
index d4e668005..03ac407f3 100644
--- a/server/src/Http/Controllers/Internal/v1/PaymentController.php
+++ b/server/src/Http/Controllers/Internal/v1/PaymentController.php
@@ -3,8 +3,8 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
 use Fleetbase\FleetOps\Models\PurchaseRate;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Payment;
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Http\Resources\FleetbaseResource;
 use Fleetbase\Support\Auth;
@@ -13,6 +13,18 @@
 
 class PaymentController extends Controller
 {
+    use AuthorizesMethods;
+
+    public function __construct()
+    {
+        $this->authorizeMethods([
+            'hasStripeConnectAccount'        => 'view payments',
+            'getStripeAccount'               => 'onboard payments',
+            'getStripeAccountSession'        => 'onboard payments',
+            'getCompanyReceivedPayments'     => 'view payments',
+        ]);
+    }
+
     /**
      * Checks if the currently authenticated company has an associated Stripe Connect account.
      *
@@ -22,8 +34,6 @@ class PaymentController extends Controller
      */
     public function hasStripeConnectAccount()
     {
-        Authorization::authorize('view payments');
-
         $company = $this->getCompany();
         if ($company) {
             return $this->jsonResponse([
@@ -46,8 +56,6 @@ public function hasStripeConnectAccount()
      */
     public function getStripeAccount()
     {
-        Authorization::authorize('onboard payments');
-
         $stripe = $this->stripeClient();
 
         try {
@@ -89,8 +97,6 @@ public function getStripeAccount()
      */
     public function getStripeAccountSession(Request $request)
     {
-        Authorization::authorize('onboard payments');
-
         $stripe  = $this->stripeClient();
         $company = $this->getCompany();
 
@@ -119,8 +125,6 @@ public function getStripeAccountSession(Request $request)
      */
     public function getCompanyReceivedPayments(Request $request)
     {
-        Authorization::authorize('view payments');
-
         $limit     = $request->input('limit', 30);
         $query     = PurchaseRate::select(
             [
diff --git a/server/src/Http/Controllers/Internal/v1/RadarController.php b/server/src/Http/Controllers/Internal/v1/RadarController.php
index 6251fd684..9cd1e7961 100644
--- a/server/src/Http/Controllers/Internal/v1/RadarController.php
+++ b/server/src/Http/Controllers/Internal/v1/RadarController.php
@@ -14,12 +14,12 @@
 use Fleetbase\FleetOps\Models\Trailer;
 use Fleetbase\FleetOps\Models\Vehicle;
 use Fleetbase\FleetOps\Models\WorkOrder;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\LiveOrderQuery;
 use Fleetbase\FleetOps\Support\Radar\RadarAgenda;
 use Fleetbase\FleetOps\Support\Radar\RadarBriefing;
 use Fleetbase\FleetOps\Support\Radar\RadarItemState;
 use Fleetbase\FleetOps\Support\Radar\RadarRules;
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Models\Alert;
 use Fleetbase\Models\CompanyUser;
@@ -43,6 +43,24 @@
  */
 class RadarController extends Controller
 {
+    use AuthorizesMethods;
+
+    public function __construct()
+    {
+        $this->authorizeMethods([
+            'extendShift'       => ['update driver', 'update vehicle'],
+            'acknowledge'       => ['update driver', 'update vehicle'],
+            'snooze'            => ['update driver', 'update vehicle'],
+            'wake'              => ['update driver', 'update vehicle'],
+            'assign'            => ['update driver', 'update vehicle'],
+            'plan'              => ['update driver', 'update vehicle'],
+            'resolve'           => ['update driver', 'update vehicle'],
+            'bulk'              => ['update driver', 'update vehicle'],
+            'storeNotice'       => ['update driver', 'update vehicle'],
+            'destroyNotice'     => ['update driver', 'update vehicle'],
+        ]);
+    }
+
     public const RESOLVED_WINDOW_DAYS = 7;
     public const SNOOZE_MAX_DAYS      = 90;
 
@@ -183,8 +201,6 @@ public function handoverSuggest(Request $request, string $key): JsonResponse
      */
     public function extendShift(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update driver', 'update vehicle');
-
         $minutes = (int) $request->input('minutes', 60);
         if ($minutes < 1 || $minutes > 24 * 60) {
             return response()->json(['error' => 'minutes must be between 1 and 1440.'], 422);
@@ -214,8 +230,6 @@ public function extendShift(Request $request, string $id): JsonResponse
 
     public function acknowledge(Request $request, string $key): JsonResponse
     {
-        Authorization::authorize('update driver', 'update vehicle');
-
         return $this->act($request, $key, function (Alert $row) use ($request) {
             RadarItemState::acknowledge($row, $this->actor($request));
         });
@@ -223,8 +237,6 @@ public function acknowledge(Request $request, string $key): JsonResponse
 
     public function snooze(Request $request, string $key): JsonResponse
     {
-        Authorization::authorize('update driver', 'update vehicle');
-
         $minutes = $this->snoozeMinutes($request);
         if ($minutes === null) {
             return response()->json(['error' => 'Pass minutes (1 to ' . (self::SNOOZE_MAX_DAYS * 1440) . ') or a future until date.'], 422);
@@ -237,8 +249,6 @@ public function snooze(Request $request, string $key): JsonResponse
 
     public function wake(Request $request, string $key): JsonResponse
     {
-        Authorization::authorize('update driver', 'update vehicle');
-
         return $this->act($request, $key, function (Alert $row) {
             RadarItemState::wake($row);
         }, false);
@@ -246,8 +256,6 @@ public function wake(Request $request, string $key): JsonResponse
 
     public function assign(Request $request, string $key): JsonResponse
     {
-        Authorization::authorize('update driver', 'update vehicle');
-
         $company  = $this->companyUuid($request);
         $assignee = null;
 
@@ -265,8 +273,6 @@ public function assign(Request $request, string $key): JsonResponse
 
     public function plan(Request $request, string $key): JsonResponse
     {
-        Authorization::authorize('update driver', 'update vehicle');
-
         $plannedAt = null;
         if ($request->filled('planned_at')) {
             $plannedAt = RadarRules::carbon($request->input('planned_at'));
@@ -286,8 +292,6 @@ public function plan(Request $request, string $key): JsonResponse
      */
     public function resolve(Request $request, string $key): JsonResponse
     {
-        Authorization::authorize('update driver', 'update vehicle');
-
         $parsed = RadarRules::parseKey($key);
         if (!$parsed || $parsed[0] !== 'notice') {
             return response()->json(['error' => 'Only notices resolve by hand; other items close when their record changes.'], 422);
@@ -303,8 +307,6 @@ public function resolve(Request $request, string $key): JsonResponse
      */
     public function bulk(Request $request): JsonResponse
     {
-        Authorization::authorize('update driver', 'update vehicle');
-
         $keys   = array_values(array_filter((array) $request->input('keys', []), 'is_string'));
         $action = (string) $request->input('action');
 
@@ -367,8 +369,6 @@ public function bulk(Request $request): JsonResponse
      */
     public function storeNotice(Request $request): JsonResponse
     {
-        Authorization::authorize('update driver', 'update vehicle');
-
         $message  = trim((string) $request->input('message'));
         $severity = in_array($request->input('severity'), [RadarRules::SEVERITY_CRITICAL, RadarRules::SEVERITY_WARNING, RadarRules::SEVERITY_INFO], true) ? $request->input('severity') : RadarRules::SEVERITY_INFO;
         $dueAt    = $request->filled('due_at') ? RadarRules::carbon($request->input('due_at')) : null;
@@ -411,8 +411,6 @@ public function storeNotice(Request $request): JsonResponse
 
     public function destroyNotice(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update driver', 'update vehicle');
-
         $company = $this->companyUuid($request);
         $alert   = $this->findNotice($company, $id);
 
diff --git a/server/src/Http/Controllers/Internal/v1/SettingController.php b/server/src/Http/Controllers/Internal/v1/SettingController.php
index 75d1cb175..fd992f00d 100644
--- a/server/src/Http/Controllers/Internal/v1/SettingController.php
+++ b/server/src/Http/Controllers/Internal/v1/SettingController.php
@@ -2,8 +2,8 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Tracking\TrackingProviderRegistry;
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\Controller;
 use Fleetbase\Models\Setting;
 use Fleetbase\Support\Auth;
@@ -15,6 +15,29 @@
  */
 class SettingController extends Controller
 {
+    use AuthorizesMethods;
+
+    public function __construct()
+    {
+        $this->authorizeMethods([
+            'saveEntityEditingSettings'               => 'update navigator-settings',
+            'savedDriverOnboardSettings'              => 'update navigator-settings',
+            'saveCustomerEnabledOrderConfigs'         => 'update order-config',
+            'saveCustomerPortalPaymentConfig'         => 'update payments',
+            'saveNotificationSettings'                => 'update notification-settings',
+            'saveRoutingSettings'                     => 'update routing-settings',
+            'saveTrackingSettings'                    => 'update tracking-settings',
+            'getAdminTrackingSettings'                => 'admin',
+            'saveAdminTrackingSettings'               => 'admin',
+            'saveMapSettings'                         => 'update map-settings',
+            'getAdminMapSettings'                     => 'admin',
+            'saveAdminMapSettings'                    => 'admin',
+            'saveSchedulingSettings'                  => 'update scheduling-settings',
+            'saveOrchestratorSettings'                => 'update routing-settings',
+            'saveOrchestratorCardFields'              => 'update routing-settings',
+        ]);
+    }
+
     /**
      * Save entity editing settings.
      *
@@ -22,8 +45,6 @@ class SettingController extends Controller
      */
     public function saveEntityEditingSettings(Request $request)
     {
-        Authorization::authorize('update navigator-settings');
-
         // The setting is one platform-wide map keyed by order config id. Only this
         // company's order configs may be written, and other companies' entries are kept.
         $ownKeys  = $this->companyOrderConfigKeys();
@@ -86,8 +107,6 @@ public function getDriverOnboardSettings($companyId = null)
      */
     public function savedDriverOnboardSettings(Request $request)
     {
-        Authorization::authorize('update navigator-settings');
-
         $driverOnboardSettings              = $request->array('driverOnboardSettings', []);
         $driverOnboardSettings['companyId'] = session('company');
 
@@ -105,8 +124,6 @@ public function savedDriverOnboardSettings(Request $request)
 
     public function saveCustomerEnabledOrderConfigs(Request $request)
     {
-        Authorization::authorize('update order-config');
-
         $enabledOrderConfigs = array_values($request->array('enabledOrderConfigs'));
         $this->configureCompanySetting('fleet-ops.customer-enabled-order-configs', $enabledOrderConfigs);
 
@@ -122,8 +139,6 @@ public function getCustomerEnabledOrderConfigs()
 
     public function saveCustomerPortalPaymentConfig(Request $request)
     {
-        Authorization::authorize('update payments');
-
         $paymentsConfig = $request->array('paymentsConfig');
         $this->configureCompanySetting('fleet-ops.customer-payments-configs', $paymentsConfig);
 
@@ -174,8 +189,6 @@ public function getNotificationRegistry()
      */
     public function saveNotificationSettings(Request $request)
     {
-        Authorization::authorize('update notification-settings');
-
         $notificationSettings = $request->input('notificationSettings');
         if (!is_array($notificationSettings)) {
             throw new \Exception('Invalid notification settings data.');
@@ -214,8 +227,6 @@ public function getNotificationSettings()
      */
     public function saveRoutingSettings(Request $request)
     {
-        Authorization::authorize('update routing-settings');
-
         $displayEngine      = $request->input('display_engine', $request->input('router', 'osrm'));
         $optimizationEngine = $request->input('optimization_engine', $displayEngine);
         $unit               = $request->input('unit', 'km');
@@ -268,8 +279,6 @@ public function getRoutingSettings()
      */
     public function saveTrackingSettings(Request $request)
     {
-        Authorization::authorize('update tracking-settings');
-
         $config    = $this->trackingDefaults();
         $fallbacks = $request->input('fallbacks', data_get($config, 'fallbacks', ['osrm', 'calculated']));
         if (is_string($fallbacks)) {
@@ -319,8 +328,6 @@ public function getTrackingSettings()
 
     public function getAdminTrackingSettings()
     {
-        Authorization::authorizeAdmin();
-
         return response()->json(array_merge($this->trackingDefaults(), [
             'providers' => $this->trackingProviderOptions(),
         ]));
@@ -328,8 +335,6 @@ public function getAdminTrackingSettings()
 
     public function saveAdminTrackingSettings(Request $request)
     {
-        Authorization::authorizeAdmin();
-
         $config    = config('fleetops.tracking', []);
         $fallbacks = $request->input('fallbacks', data_get($config, 'fallbacks', ['osrm', 'calculated']));
         if (is_string($fallbacks)) {
@@ -398,8 +403,6 @@ public function getMapSettings()
      */
     public function saveMapSettings(Request $request)
     {
-        Authorization::authorize('update map-settings');
-
         $settings = $request->input('settings', []);
 
         // The API key is managed at the system level via core-api — strip it
@@ -416,8 +419,6 @@ public function saveMapSettings(Request $request)
 
     public function getAdminMapSettings()
     {
-        Authorization::authorizeAdmin();
-
         $defaults = [
             'mapProvider'     => 'leaflet',
             'googleMapsMapId' => '',
@@ -428,8 +429,6 @@ public function getAdminMapSettings()
 
     public function saveAdminMapSettings(Request $request)
     {
-        Authorization::authorizeAdmin();
-
         $allowedProviders = ['leaflet', 'google'];
         $mapProvider      = $request->input('mapProvider', 'leaflet');
         if (!in_array($mapProvider, $allowedProviders)) {
@@ -516,8 +515,6 @@ public function getSchedulingSettings()
      */
     public function saveSchedulingSettings(Request $request)
     {
-        Authorization::authorize('update scheduling-settings');
-
         $settings = [
             'horizon_days'                   => (int) $request->input('horizon_days', 60),
             'default_shift_duration'         => (int) $request->input('default_shift_duration', 8),
@@ -557,8 +554,6 @@ public function getOrchestratorSettings()
      */
     public function saveOrchestratorSettings(Request $request)
     {
-        Authorization::authorize('update routing-settings');
-
         $settings = [
             'allocation_engine'           => $request->input('allocation_engine', 'vroom'),
             'auto_allocate_on_create'     => (bool) $request->input('auto_allocate_on_create', false),
@@ -595,8 +590,6 @@ public function getOrchestratorCardFields()
      */
     public function saveOrchestratorCardFields(Request $request)
     {
-        Authorization::authorize('update routing-settings');
-
         $settings = $request->input('settings', []);
 
         $normalized = [
diff --git a/server/src/Http/Controllers/Internal/v1/TelematicController.php b/server/src/Http/Controllers/Internal/v1/TelematicController.php
index 7d778a565..4f056da5b 100644
--- a/server/src/Http/Controllers/Internal/v1/TelematicController.php
+++ b/server/src/Http/Controllers/Internal/v1/TelematicController.php
@@ -6,7 +6,6 @@
 use Fleetbase\FleetOps\Exports\TelematicExport;
 use Fleetbase\FleetOps\Http\Controllers\FleetOpsController;
 use Fleetbase\FleetOps\Models\Telematic;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\FleetOps\Support\Telematics\TelematicProviderRegistry;
 use Fleetbase\FleetOps\Support\Telematics\TelematicService;
 use Fleetbase\Http\Requests\ExportRequest;
@@ -18,6 +17,20 @@
 
 class TelematicController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'testConnection'          => 'update telematic',
+        'testCredentials'         => 'create telematic',
+        'discover'                => 'update telematic',
+        'linkDevice'              => 'update telematic',
+        'telemetryWebhook'        => 'update telematic',
+        'replayTelemetryDelivery' => 'update telematic',
+    ];
+
     /**
      * The resource to query.
      *
@@ -76,8 +89,6 @@ public function providers(): JsonResponse
     #[SkipAuthorizationCheck]
     public function testConnection(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update telematic');
-
         $telematic = $this->findTelematic($id);
 
         $async = $request->input('async', false);
@@ -97,8 +108,6 @@ public function testConnection(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function testCredentials(Request $request, string $key): JsonResponse
     {
-        Authorization::authorize('create telematic');
-
         $credentials = $request->array('credentials', []);
         $async       = $request->input('async', false);
 
@@ -131,8 +140,6 @@ public function testCredentials(Request $request, string $key): JsonResponse
     #[SkipAuthorizationCheck]
     public function discover(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update telematic');
-
         $telematic = $this->findTelematic($id);
 
         $jobId = $this->telematicService->discoverDevices($telematic, [
@@ -195,8 +202,6 @@ public function logs(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function linkDevice(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update telematic');
-
         $telematic = $this->findTelematic($id);
 
         $request->validate([
@@ -216,8 +221,6 @@ public function linkDevice(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function telemetryWebhook(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update telematic');
-
         $telematic = $this->findTelematic($id);
         $provider  = $this->registry->resolve($telematic->provider);
         abort_unless($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface, 422);
@@ -268,8 +271,6 @@ public function telemetryDiagnostics(string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function replayTelemetryDelivery(string $id, string $delivery): JsonResponse
     {
-        Authorization::authorize('update telematic');
-
         $telematic = $this->findTelematic($id);
         $provider  = $this->registry->resolve($telematic->provider);
         abort_unless($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface, 422);
diff --git a/server/src/Http/Controllers/Internal/v1/TrailerController.php b/server/src/Http/Controllers/Internal/v1/TrailerController.php
index 029b4a417..841ab10e8 100644
--- a/server/src/Http/Controllers/Internal/v1/TrailerController.php
+++ b/server/src/Http/Controllers/Internal/v1/TrailerController.php
@@ -14,7 +14,6 @@
 use Fleetbase\FleetOps\Models\Equipment;
 use Fleetbase\FleetOps\Models\Trailer;
 use Fleetbase\FleetOps\Models\Vehicle;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Fleetbase\Support\Resolve;
@@ -25,6 +24,20 @@
 
 class TrailerController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'attach'          => 'attach-vehicle-for trailer',
+        'detach'          => 'detach-vehicle-for trailer',
+        'attachDevice'    => 'attach-device-for trailer',
+        'detachDevice'    => 'detach-device-for trailer',
+        'attachEquipment' => 'attach-equipment-for trailer',
+        'detachEquipment' => 'detach-equipment-for trailer',
+    ];
+
     /**
      * The resource to query.
      *
@@ -74,8 +87,6 @@ protected function deleteTrailerRecord($id, Request $request)
     #[SkipAuthorizationCheck]
     public function attach(Request $request, string $id)
     {
-        Authorization::authorize('attach-vehicle-for trailer');
-
         $request->validate(['vehicle' => ['required', 'string'], 'position' => ['nullable', 'integer', 'min:1']]);
 
         $trailer = $this->resolveTrailer($id);
@@ -142,8 +153,6 @@ public function attach(Request $request, string $id)
     #[SkipAuthorizationCheck]
     public function detach(string $id)
     {
-        Authorization::authorize('detach-vehicle-for trailer');
-
         $trailer = $this->resolveTrailer($id);
 
         if (!$trailer) {
@@ -168,8 +177,6 @@ public function detach(string $id)
     #[SkipAuthorizationCheck]
     public function attachDevice(Request $request, string $id)
     {
-        Authorization::authorize('attach-device-for trailer');
-
         $request->validate(['device' => ['required', 'string']]);
 
         $trailer = $this->resolveTrailer($id);
@@ -200,8 +207,6 @@ public function attachDevice(Request $request, string $id)
     #[SkipAuthorizationCheck]
     public function detachDevice(Request $request, string $id)
     {
-        Authorization::authorize('detach-device-for trailer');
-
         $request->validate(['device' => ['required', 'string']]);
 
         $trailer = $this->resolveTrailer($id);
@@ -232,8 +237,6 @@ public function detachDevice(Request $request, string $id)
     #[SkipAuthorizationCheck]
     public function attachEquipment(Request $request, string $id)
     {
-        Authorization::authorize('attach-equipment-for trailer');
-
         $request->validate(['equipment' => ['required', 'string']]);
 
         $trailer   = $this->resolveTrailer($id);
@@ -262,8 +265,6 @@ public function attachEquipment(Request $request, string $id)
     #[SkipAuthorizationCheck]
     public function detachEquipment(Request $request, string $id)
     {
-        Authorization::authorize('detach-equipment-for trailer');
-
         $request->validate(['equipment' => ['required', 'string']]);
 
         $trailer   = $this->resolveTrailer($id);
diff --git a/server/src/Http/Controllers/Internal/v1/VehicleController.php b/server/src/Http/Controllers/Internal/v1/VehicleController.php
index ccb861e71..b8f113d93 100644
--- a/server/src/Http/Controllers/Internal/v1/VehicleController.php
+++ b/server/src/Http/Controllers/Internal/v1/VehicleController.php
@@ -13,7 +13,6 @@
 use Fleetbase\FleetOps\Models\Equipment;
 use Fleetbase\FleetOps\Models\Order;
 use Fleetbase\FleetOps\Models\Vehicle;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Fleetbase\Support\Resolve;
@@ -27,6 +26,20 @@
 
 class VehicleController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'unassignDriver'  => 'assign-driver-for vehicle',
+        'unassignOrders'  => 'update vehicle',
+        'attachDevice'    => 'update vehicle',
+        'detachDevice'    => 'update vehicle',
+        'attachEquipment' => 'update vehicle',
+        'detachEquipment' => 'update vehicle',
+    ];
+
     /**
      * The resource to query.
      *
@@ -116,8 +129,6 @@ public function assignDriver(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function unassignDriver(string $id): JsonResponse
     {
-        Authorization::authorize('assign-driver-for vehicle');
-
         $vehicle = $this->findVehicle($id);
         $vehicle->unassignDriver();
         $vehicle->load(['driver', 'devices']);
@@ -151,8 +162,6 @@ public function assignedOrders(string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function unassignOrders(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update vehicle');
-
         $request->validate([
             'orders'   => 'required|array|min:1',
             'orders.*' => 'required|string',
@@ -190,8 +199,6 @@ public function unassignOrders(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function attachDevice(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update vehicle');
-
         $request->validate(['device' => 'required|string']);
 
         $deviceId = $request->input('device');
@@ -233,8 +240,6 @@ public function attachDevice(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function detachDevice(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update vehicle');
-
         $request->validate(['device' => 'required|string']);
 
         $deviceId = $request->input('device');
@@ -282,8 +287,6 @@ public function detachDevice(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function attachEquipment(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update vehicle');
-
         $request->validate(['equipment' => 'required|string']);
 
         $vehicle   = $this->resolveVehicle($id);
@@ -312,8 +315,6 @@ public function attachEquipment(Request $request, string $id): JsonResponse
     #[SkipAuthorizationCheck]
     public function detachEquipment(Request $request, string $id): JsonResponse
     {
-        Authorization::authorize('update vehicle');
-
         $request->validate(['equipment' => 'required|string']);
 
         $vehicle   = $this->resolveVehicle($id);
diff --git a/server/src/Http/Controllers/Internal/v1/VendorController.php b/server/src/Http/Controllers/Internal/v1/VendorController.php
index 7cc3d69d5..69c100da2 100644
--- a/server/src/Http/Controllers/Internal/v1/VendorController.php
+++ b/server/src/Http/Controllers/Internal/v1/VendorController.php
@@ -11,7 +11,6 @@
 use Fleetbase\FleetOps\Models\Driver;
 use Fleetbase\FleetOps\Models\Vendor;
 use Fleetbase\FleetOps\Models\VendorPersonnel;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Illuminate\Http\Request;
@@ -21,6 +20,18 @@
 
 class VendorController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'assignDriver'          => 'update vendor',
+        'removeDriver'          => 'update vendor',
+        'addVendorPersonnel'    => 'update vendor',
+        'removeVendorPersonnel' => 'update vendor',
+    ];
+
     /**
      * The resource to query.
      *
@@ -133,8 +144,6 @@ public function import(ImportRequest $request)
     #[SkipAuthorizationCheck]
     public function assignDriver(string $id, Request $request)
     {
-        Authorization::authorize('update vendor');
-
         // Validate only param
         if (!$request->isUuid('driver')) {
             return response()->error('No driver selected to assign to vendor.');
@@ -168,8 +177,6 @@ public function assignDriver(string $id, Request $request)
     #[SkipAuthorizationCheck]
     public function removeDriver(string $id, Request $request)
     {
-        Authorization::authorize('update vendor');
-
         // Validate only param
         if (!$request->isUuid('driver')) {
             return response()->error('No driver selected to remove from vendor.');
@@ -208,8 +215,6 @@ public function vendorPersonnels(string $vendorId)
     #[SkipAuthorizationCheck]
     public function addVendorPersonnel(Request $request, string $vendorId)
     {
-        Authorization::authorize('update vendor');
-
         $vendor  = $this->findVendorByIdOrFail($vendorId);
         $contact = $this->resolveOrCreatePersonnelContact($request);
 
@@ -234,8 +239,6 @@ public function addVendorPersonnel(Request $request, string $vendorId)
     #[SkipAuthorizationCheck]
     public function removeVendorPersonnel(string $vendorId, string $contactId)
     {
-        Authorization::authorize('update vendor');
-
         $vendor  = $this->findVendorByIdOrFail($vendorId);
         $contact = $this->findContactByIdOrFail($contactId);
 
diff --git a/server/src/Http/Controllers/Internal/v1/WorkOrderController.php b/server/src/Http/Controllers/Internal/v1/WorkOrderController.php
index 2bb304fa0..28d37e315 100644
--- a/server/src/Http/Controllers/Internal/v1/WorkOrderController.php
+++ b/server/src/Http/Controllers/Internal/v1/WorkOrderController.php
@@ -8,7 +8,6 @@
 use Fleetbase\FleetOps\Imports\WorkOrderImport;
 use Fleetbase\FleetOps\Mail\WorkOrderDispatched;
 use Fleetbase\FleetOps\Models\WorkOrder;
-use Fleetbase\FleetOps\Support\Authorization;
 use Fleetbase\Http\Requests\ExportRequest;
 use Fleetbase\Http\Requests\ImportRequest;
 use Illuminate\Http\JsonResponse;
@@ -18,6 +17,15 @@
 
 class WorkOrderController extends FleetOpsController
 {
+    /**
+     * Permissions for methods AuthorizationGuard cannot map to a schema action (see FleetOpsController).
+     *
+     * @var array<string, string|string[]>
+     */
+    protected array $methodPermissions = [
+        'sendEmail' => 'update work-order',
+    ];
+
     /**
      * The resource to query.
      *
@@ -85,8 +93,6 @@ protected function importFile(WorkOrderImport $import, string $path, string $dis
     #[SkipAuthorizationCheck]
     public function sendEmail(string $id): JsonResponse
     {
-        Authorization::authorize('update work-order');
-
         $workOrder = $this->workOrderForEmail($id);
 
         // Resolve recipient email from the assignee (vendor or contact)
diff --git a/server/src/Traits/AuthorizesMethods.php b/server/src/Traits/AuthorizesMethods.php
new file mode 100644
index 000000000..ee4c24181
--- /dev/null
+++ b/server/src/Traits/AuthorizesMethods.php
@@ -0,0 +1,37 @@
+<?php
+
+namespace Fleetbase\FleetOps\Traits;
+
+use Fleetbase\FleetOps\Support\Authorization;
+
+/**
+ * Registers controller middleware that enforces an explicit permission per method.
+ *
+ * Used for endpoints AuthorizationGuard cannot resolve on its own: methods on
+ * resource controllers whose names do not match a schema action (these also carry
+ * `#[SkipAuthorizationCheck]`) and every method of controllers that are not
+ * resource controllers.
+ *
+ * Map values are one permission in short form (`dispatch order`), a list of
+ * permissions of which the user needs any one, or `admin` for system administrators.
+ */
+trait AuthorizesMethods
+{
+    /**
+     * @param array<string, string|string[]> $map method name => permission(s)
+     */
+    protected function authorizeMethods(array $map): void
+    {
+        foreach ($map as $method => $permissions) {
+            $this->middleware(function ($request, $next) use ($permissions) {
+                if ($permissions === 'admin') {
+                    Authorization::authorizeAdmin();
+                } else {
+                    Authorization::authorize(...(array) $permissions);
+                }
+
+                return $next($request);
+            })->only($method);
+        }
+    }
+}
diff --git a/server/src/routes.php b/server/src/routes.php
index 7adeec662..dce00734d 100644
--- a/server/src/routes.php
+++ b/server/src/routes.php
@@ -407,7 +407,7 @@ function ($router) {
                     function ($router) {
                         // Opened from the Navigator app's QR scan without a session;
                         // NavigatorController::linkApp() requires a valid signature.
-                        $router->get('link-app', 'NavigatorController@linkApp')->name('fleetops.navigator.link-app');
+                        $router->get('link-app', 'NavigatorController@linkApp');
                         $router->get('get-link-app', 'NavigatorController@getLinkAppUrl')->middleware(['fleetbase.protected']);
                     }
                 );
diff --git a/server/tests/NavigatorControllerContractsTest.php b/server/tests/NavigatorControllerContractsTest.php
index 0b2060cf0..216804e17 100644
--- a/server/tests/NavigatorControllerContractsTest.php
+++ b/server/tests/NavigatorControllerContractsTest.php
@@ -137,17 +137,24 @@ function fleetopsNavigatorCredential(string $key = 'flb_live_key'): ApiCredentia
     return $credential;
 }
 
+function fleetopsNavigatorSignedQuery(): array
+{
+    $expires = time() + 600;
+
+    return ['expires' => $expires, 'signature' => NavigatorController::linkSignature($expires)];
+}
+
 test('navigator controller builds android and ios app link redirects', function () {
     $company                   = fleetopsNavigatorCompany();
     $controller                = new FleetOpsNavigatorControllerProbe();
     $controller->adminUser     = fleetopsNavigatorUser($company);
     $controller->apiCredential = fleetopsNavigatorCredential('flb_live_navigator');
 
-    $android = $controller->linkApp(Request::create('/navigator/link-app', 'GET', [], [], [], [
+    $android = $controller->linkApp(Request::create('/navigator/link-app', 'GET', fleetopsNavigatorSignedQuery(), [], [], [
         'HTTP_USER_AGENT' => 'Mozilla/5.0 Android',
     ]))->getData(true);
 
-    $ios = $controller->linkApp(Request::create('/navigator/link-app', 'GET', [], [], [], [
+    $ios = $controller->linkApp(Request::create('/navigator/link-app', 'GET', fleetopsNavigatorSignedQuery(), [], [], [
         'HTTP_USER_AGENT' => 'Mozilla/5.0 iPhone',
     ]))->getData(true);
 
@@ -169,11 +176,32 @@ function fleetopsNavigatorCredential(string $key = 'flb_live_key'): ApiCredentia
     $controller            = new FleetOpsNavigatorControllerProbe();
     $controller->adminUser = fleetopsNavigatorUser(null);
 
-    $response = $controller->linkApp(new Request());
+    $response = $controller->linkApp(Request::create('/navigator/link-app', 'GET', fleetopsNavigatorSignedQuery()));
 
     expect($response->getData(true))->toBe(['error' => 'Organization for linking not found.']);
 });
 
+test('navigator controller refuses unsigned, tampered and expired app links before touching credentials', function () {
+    $company                   = fleetopsNavigatorCompany();
+    $controller                = new FleetOpsNavigatorControllerProbe();
+    $controller->adminUser     = fleetopsNavigatorUser($company);
+    $controller->apiCredential = fleetopsNavigatorCredential('flb_live_navigator');
+
+    $expired  = time() - 60;
+    $requests = [
+        'unsigned' => Request::create('/navigator/link-app', 'GET'),
+        'tampered' => Request::create('/navigator/link-app', 'GET', ['signature' => 'forged'] + fleetopsNavigatorSignedQuery()),
+        'expired'  => Request::create('/navigator/link-app', 'GET', ['expires' => $expired, 'signature' => NavigatorController::linkSignature($expired)]),
+    ];
+
+    foreach ($requests as $request) {
+        $response = $controller->linkApp($request);
+        expect($response->getData(true))->toBe(['error' => 'This Navigator link is invalid or has expired. Generate a new one from the console.']);
+    }
+
+    expect($controller->credentialLookups)->toBe([]);
+});
+
 test('navigator controller exposes link url settings and current organization token lookup branches', function () {
     $controller                = new FleetOpsNavigatorControllerProbe();
     $controller->apiCredential = fleetopsNavigatorCredential('flb_test_key');
@@ -194,7 +222,11 @@ function fleetopsNavigatorCredential(string $key = 'flb_live_key'): ApiCredentia
     ]);
     $missing = $controller->getCurrentOrganization($secretRequest);
 
-    expect($linkUrl)->toBe(['linkUrl' => 'http://localhost/int/v1/fleet-ops/navigator/link-app'])
+    parse_str((string) parse_url($linkUrl['linkUrl'], PHP_URL_QUERY), $linkQuery);
+
+    expect($linkUrl['linkUrl'])->toStartWith('http://localhost/int/v1/fleet-ops/navigator/link-app?')
+        ->and($linkQuery['signature'])->toBe(NavigatorController::linkSignature((int) $linkQuery['expires']))
+        ->and((int) $linkQuery['expires'])->toBeGreaterThan(time())
         ->and($settings)->toBe(['enabled' => true, 'invite_code_required' => false])
         ->and($organization)->toBeInstanceOf(Organization::class)
         ->and($controller->credentialLookups)->toContain(
diff --git a/server/tests/SettingControllerContractsTest.php b/server/tests/SettingControllerContractsTest.php
index 1163a5f36..7e161c835 100644
--- a/server/tests/SettingControllerContractsTest.php
+++ b/server/tests/SettingControllerContractsTest.php
@@ -8,6 +8,7 @@ class FleetOpsSettingControllerProbe extends SettingController
     public array $configured            = [];
     public array $configuredCompany     = [];
     public array $settingValues         = [];
+    public array $orderConfigKeys       = [];
     public array $settings              = [];
     public array $companySettings       = [];
     public array $lookupCompanySettings = [];
@@ -34,6 +35,11 @@ protected function configureCompanySetting(string $key, mixed $value): mixed
         return null;
     }
 
+    protected function companyOrderConfigKeys(): array
+    {
+        return $this->orderConfigKeys;
+    }
+
     protected function settingValue(string $key): mixed
     {
         return $this->settingValues[$key] ?? null;
@@ -107,16 +113,22 @@ function fleetopsJsonPayload(mixed $response): array
 }
 
 test('setting controller persists and returns basic company settings through configured keys', function () {
-    $controller = new FleetOpsSettingControllerProbe();
-
-    $entityPayload = fleetopsJsonPayload($controller->saveEntityEditingSettings(new Request([
-        'entityEditingSettings' => ['orders' => ['editable' => true]],
+    session(['company' => 'company-1']);
+    $controller                  = new FleetOpsSettingControllerProbe();
+    $controller->orderConfigKeys = ['orders'];
+
+    // The setting is one platform-wide map keyed by order config: another company's entry must survive,
+    // and this company cannot write keys for order configs it does not own.
+    $controller->settingValues['fleet-ops.entity-editing-settings'] = ['foreign-config' => ['editable' => true]];
+    $entityPayload                                                  = fleetopsJsonPayload($controller->saveEntityEditingSettings(new Request([
+        'entityEditingSettings' => ['orders' => ['editable' => true], 'foreign-config' => ['editable' => false]],
     ])));
-    $controller->settingValues['fleet-ops.entity-editing-settings'] = ['orders' => ['editable' => false]];
+    $controller->settingValues['fleet-ops.entity-editing-settings'] = ['orders' => ['editable' => false], 'foreign-config' => ['editable' => true]];
 
+    // A request-supplied company id is ignored in favour of the session company.
     $disabledDriverPayload = fleetopsJsonPayload($controller->savedDriverOnboardSettings(new Request([
         'driverOnboardSettings' => [
-            'companyId'                         => 'company-1',
+            'companyId'                         => 'company-2',
             'enableDriverOnboardFromApp'        => false,
             'driverMustProvideOnboardDoucments' => true,
             'requiredOnboardDocuments'          => ['license'],
@@ -137,7 +149,7 @@ function fleetopsJsonPayload(mixed $response): array
     $controller->company                                                = (object) ['stripe_connect_id' => 'acct_123'];
 
     expect($entityPayload)->toBe(['entityEditingSettings' => ['orders' => ['editable' => true]]])
-        ->and($controller->configured['fleet-ops.entity-editing-settings'])->toBe(['orders' => ['editable' => true]])
+        ->and($controller->configured['fleet-ops.entity-editing-settings'])->toBe(['foreign-config' => ['editable' => true], 'orders' => ['editable' => true]])
         ->and(fleetopsJsonPayload($controller->getEntityEditingSettings()))->toBe(['entityEditingSettings' => ['orders' => ['editable' => false]]])
         ->and(fleetopsJsonPayload((new FleetOpsSettingControllerProbe())->getEntityEditingSettings()))->toBe(['entityEditingSettings' => []])
         ->and($disabledDriverPayload['driverOnboardSettings'])->toMatchArray([
@@ -148,6 +160,7 @@ function fleetopsJsonPayload(mixed $response): array
             'driverOnboardAppMethod'            => '',
         ])
         ->and($controller->configured['fleet-ops.driver-onboard-settings.company-1'])->toBe($disabledDriverPayload['driverOnboardSettings'])
+        ->and($controller->configured)->not->toHaveKey('fleet-ops.driver-onboard-settings.company-2')
         ->and(fleetopsJsonPayload($controller->getDriverOnboardSettings('company-1')))->toBe(['driverOnboardSettings' => ['enableDriverOnboardFromApp' => true]])
         ->and(fleetopsJsonPayload((new FleetOpsSettingControllerProbe())->getDriverOnboardSettings('missing')))->toBe(['driverOnboardSettings' => []])
         ->and($enabledConfigs)->toBe(['order-express', 'order-freight'])

From 67059ba17b2b98c30cf4addd9c5d050ee4c49735 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 14:26:46 +0800
Subject: [PATCH 12/24] fix: polish telematics settings and bound storage usage
 loading

---
 .../components/admin/telematics-settings.hbs  | 65 ++++++++++++-------
 addon/components/admin/telematics-settings.js |  6 +-
 addon/controllers/settings/index.js           |  6 +-
 addon/controllers/settings/telematics.js      | 20 +++---
 addon/extension.js                            |  2 +-
 addon/templates/settings/telematics.hbs       | 25 +++----
 .../Internal/v1/SettingController.php         | 19 ++++--
 translations/en-us.yaml                       | 21 +++---
 8 files changed, 94 insertions(+), 70 deletions(-)

diff --git a/addon/components/admin/telematics-settings.hbs b/addon/components/admin/telematics-settings.hbs
index 6c225c74b..377ab01ae 100644
--- a/addon/components/admin/telematics-settings.hbs
+++ b/addon/components/admin/telematics-settings.hbs
@@ -1,44 +1,59 @@
 <div class="space-y-6">
-    {{#unless @embedded}}
-        <InfoBlock @type="info" @icon="circle-info" class="mb-4">
-            Configure system-wide telematics data retention defaults here. Organizations can override these values from Fleet-Ops &rsaquo; Settings &rsaquo; Telematics Data. A value of 0 keeps rows forever.
-        </InfoBlock>
-    {{/unless}}
+    <InfoBlock @type="info" @icon="circle-info" class="mb-4">
+        Configure system-wide telematics defaults here. Organizations can override these values from Fleet-Ops &rsaquo; Settings &rsaquo; Telematics. A retention value of 0 keeps records forever.
+    </InfoBlock>
 
-    <ContentPanel @title="Retention Defaults" @open={{true}} @wrapperClass="bordered-classic">
+    <ContentPanel @title="System Device Events Retention Defaults" @open={{true}} @wrapperClass="bordered-classic">
         <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
             <InputGroup @name="Device Event Retention (days)" @helpText="Delete telemetry events older than this. 0 keeps them forever.">
                 <Input @type="number" @value={{this.eventRetentionDays}} min="0" max="3650" class="form-input w-full" />
             </InputGroup>
-            <InputGroup @name="Strip Raw Payloads After (days)" @helpText="Remove the raw provider payload from kept events after this many days. 0 disables compaction.">
+            <InputGroup @name="Device Event Raw Payload Retention (days)" @helpText="Remove the raw provider payload from kept events after this many days. 0 disables compaction.">
                 <Input @type="number" @value={{this.eventCompactAfterDays}} min="0" max="3650" class="form-input w-full" />
             </InputGroup>
-            <InputGroup @name="Position Retention (days)" @helpText="Delete vehicle and trailer positions older than this. 0 keeps them forever.">
+        </div>
+    </ContentPanel>
+
+    <ContentPanel @title="System Position History Retention Defaults" @open={{true}} @wrapperClass="bordered-classic">
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <InputGroup @name="Position History Retention (days)" @helpText="Delete vehicle and trailer positions older than this. 0 keeps them forever.">
                 <Input @type="number" @value={{this.positionRetentionDays}} min="0" max="3650" class="form-input w-full" />
             </InputGroup>
-            <InputGroup @name="Processed Deliveries (hours)" @helpText="Delete processed delivery envelopes older than this.">
+        </div>
+    </ContentPanel>
+
+    <ContentPanel @title="System Delivery Inbox and Sync Run Retention Defaults" @open={{true}} @wrapperClass="bordered-classic">
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+            <InputGroup @name="Processed Delivery Retention (hours)" @helpText="Delete processed delivery envelopes older than this.">
                 <Input @type="number" @value={{this.processedRetentionHours}} min="0" max="720" class="form-input w-full" />
             </InputGroup>
-            <InputGroup @name="Quarantined Deliveries (days)" @helpText="Delete quarantined delivery envelopes older than this.">
+            <InputGroup @name="Quarantined Delivery Retention (days)" @helpText="Delete quarantined delivery envelopes older than this.">
                 <Input @type="number" @value={{this.quarantineRetentionDays}} min="0" max="365" class="form-input w-full" />
             </InputGroup>
-            <InputGroup @name="Sync Runs (days)" @helpText="Delete finished sync run diagnostics older than this.">
+            <InputGroup @name="Sync Run Diagnostics Retention (days)" @helpText="Delete finished sync run diagnostics older than this.">
                 <Input @type="number" @value={{this.syncRunRetentionDays}} min="0" max="365" class="form-input w-full" />
             </InputGroup>
         </div>
-        <InputGroup @name="Log Telemetry Activity" @helpText="Write telemetry-driven device, event and vehicle saves to the activity log. Off by default; every poll otherwise adds several activity rows per device.">
-            <Toggle @isToggled={{this.logTelemetryActivity}} @onToggle={{fn (mut this.logTelemetryActivity)}} />
-        </InputGroup>
-        <div class="flex justify-end mt-4">
-            <Button
-                @type="primary"
-                @size="sm"
-                @icon="save"
-                @text="Save Defaults"
-                @onClick={{perform this.saveSettings}}
-                @disabled={{this.saveSettings.isRunning}}
-                @isLoading={{or this.saveSettings.isRunning this.loadSettings.isRunning}}
-            />
-        </div>
     </ContentPanel>
+
+    <ContentPanel @title="System Activity Logging Defaults" @open={{true}} @wrapperClass="bordered-classic">
+        <Toggle
+            @label="Log Telemetry Activity by Default"
+            @helpText="Write telemetry-driven device, event and vehicle saves to the activity log. Off by default; every poll otherwise adds several activity rows per device."
+            @isToggled={{this.logTelemetryActivity}}
+            @onToggle={{fn (mut this.logTelemetryActivity)}}
+        />
+    </ContentPanel>
+
+    <div class="flex justify-end">
+        <Button
+            @type="primary"
+            @size="sm"
+            @icon="save"
+            @text="Save System Defaults"
+            @onClick={{perform this.saveSettings}}
+            @disabled={{this.saveSettings.isRunning}}
+            @isLoading={{or this.saveSettings.isRunning this.loadSettings.isRunning}}
+        />
+    </div>
 </div>
diff --git a/addon/components/admin/telematics-settings.js b/addon/components/admin/telematics-settings.js
index c030990f9..5ceedc041 100644
--- a/addon/components/admin/telematics-settings.js
+++ b/addon/components/admin/telematics-settings.js
@@ -4,8 +4,8 @@ import { inject as service } from '@ember/service';
 import { task } from 'ember-concurrency';
 
 /**
- * System-wide telematics retention defaults, applied to every company that
- * has not set its own values from Fleet-Ops > Settings > Telematics Data.
+ * System-wide telematics defaults, applied to every company that
+ * has not set its own values from Fleet-Ops > Settings > Telematics.
  */
 export default class AdminTelematicsSettingsComponent extends Component {
     @service fetch;
@@ -36,7 +36,7 @@ export default class AdminTelematicsSettingsComponent extends Component {
         try {
             const settings = yield this.fetch.post('fleet-ops/settings/admin-telematics-settings', this.settingsPayload);
             this.applySettings(settings);
-            this.notifications.success('Telematics retention defaults saved.');
+            this.notifications.success('System telematics settings saved.');
         } catch (error) {
             this.notifications.serverError(error);
         }
diff --git a/addon/controllers/settings/index.js b/addon/controllers/settings/index.js
index 771f45f0c..1837ae8d0 100644
--- a/addon/controllers/settings/index.js
+++ b/addon/controllers/settings/index.js
@@ -28,7 +28,7 @@ export default class SettingsIndexController extends Controller {
             description: 'Keep commerce, metadata, and visual conventions aligned.',
             links: [
                 { label: 'Payments', route: 'settings.payments', icon: 'cash-register', description: 'Payment setup for operational commerce workflows.' },
-                { label: 'Telematics Data', route: 'settings.telematics', icon: 'database', description: 'Retention and storage for telemetry events, positions, and delivery history.' },
+                { label: 'Telematics', route: 'settings.telematics', icon: 'database', description: 'Organization telematics settings, data retention, storage usage, and activity logging.' },
                 { label: 'Custom Fields', route: 'settings.custom-fields', icon: 'pen-to-square', description: 'Operational metadata fields for Fleet-Ops records.' },
                 { label: 'Avatars', route: 'settings.avatars', icon: 'icons', description: 'Visual assets for driver, vehicle, and map displays.' },
             ],
@@ -115,10 +115,10 @@ export default class SettingsIndexController extends Controller {
             description: 'Manage schedule templates and timing rules for planned work.',
         },
         {
-            label: 'Telematics Data',
+            label: 'Telematics',
             icon: 'database',
             slug: 'fleet-ops/settings/telematics',
-            title: 'Telematics data settings',
+            title: 'Telematics Settings',
             description: 'Control how long telemetry events, positions, and delivery history are kept.',
         },
         {
diff --git a/addon/controllers/settings/telematics.js b/addon/controllers/settings/telematics.js
index 712f9c6ba..b58537bc9 100644
--- a/addon/controllers/settings/telematics.js
+++ b/addon/controllers/settings/telematics.js
@@ -18,7 +18,6 @@ export default class SettingsTelematicsController extends Controller {
     @service fetch;
     @service notifications;
     @service intl;
-    @service currentUser;
     @service modalsManager;
 
     /** Days to keep device events; 0 keeps them forever. */
@@ -49,10 +48,6 @@ export default class SettingsTelematicsController extends Controller {
     /** Per-table storage usage reported by the API. */
     @tracked usage = null;
 
-    get isAdmin() {
-        return this.currentUser.isAdmin === true;
-    }
-
     /** Compaction is pointless once events are deleted at the same age or sooner. */
     get compactionIneffective() {
         const retention = Number(this.eventRetentionDays);
@@ -115,11 +110,18 @@ export default class SettingsTelematicsController extends Controller {
     /**
      * Load per-table storage usage for the current company.
      */
-    @task *loadUsage() {
+    @task({ drop: true }) *loadUsage() {
+        const abortController = new AbortController();
+        const requestTimeout = setTimeout(() => abortController.abort(), 30000);
+
         try {
-            this.usage = yield this.fetch.get('fleet-ops/settings/telematics-storage-usage');
-        } catch {
-            this.usage = null;
+            // Pass the signal as request data; fetch.get options do not forward it.
+            this.usage = yield this.fetch.request('fleet-ops/settings/telematics-storage-usage?include_payload_counts=0', 'GET', { signal: abortController.signal });
+        } catch (error) {
+            this.notifications.serverError(abortController.signal.aborted ? new Error(this.intl.t('settings.telematics.usage-unavailable')) : error);
+        } finally {
+            clearTimeout(requestTimeout);
+            abortController.abort();
         }
     }
 
diff --git a/addon/extension.js b/addon/extension.js
index 0ddec59dd..4dca7ab9a 100644
--- a/addon/extension.js
+++ b/addon/extension.js
@@ -113,7 +113,7 @@ export default {
                     component: new ExtensionComponent('@fleetbase/fleetops-engine', 'admin/navigator-app'),
                 }),
                 new MenuItem({
-                    title: 'Telematics Data',
+                    title: 'Telematics',
                     icon: 'database',
                     component: new ExtensionComponent('@fleetbase/fleetops-engine', 'admin/telematics-settings'),
                 }),
diff --git a/addon/templates/settings/telematics.hbs b/addon/templates/settings/telematics.hbs
index f8595f9f4..4b358e1ba 100644
--- a/addon/templates/settings/telematics.hbs
+++ b/addon/templates/settings/telematics.hbs
@@ -54,15 +54,25 @@
 
             {{! ── Activity logging ─────────────────────────────────────────── }}
             <ContentPanel @title={{t "settings.telematics.activity-logging"}} @open={{true}} @wrapperClass="bordered-classic">
-                <InputGroup @name={{t "settings.telematics.log-telemetry-activity"}} @helpText={{t "settings.telematics.log-telemetry-activity-help"}}>
-                    <Toggle @isToggled={{this.logTelemetryActivity}} @onToggle={{fn (mut this.logTelemetryActivity)}} />
-                </InputGroup>
+                <Toggle
+                    @label={{t "settings.telematics.log-telemetry-activity"}}
+                    @helpText={{t "settings.telematics.log-telemetry-activity-help"}}
+                    @isToggled={{this.logTelemetryActivity}}
+                    @onToggle={{fn (mut this.logTelemetryActivity)}}
+                />
             </ContentPanel>
 
             {{! ── Storage usage ────────────────────────────────────────────── }}
             <ContentPanel @title={{t "settings.telematics.storage-usage"}} @open={{true}} @wrapperClass="bordered-classic">
                 <div class="flex items-center justify-end gap-2 mb-3">
-                    <Button @size="xs" @icon="rotate" @text={{t "settings.telematics.refresh"}} @onClick={{perform this.loadUsage}} @isLoading={{this.loadUsage.isRunning}} />
+                    <Button
+                        @size="xs"
+                        @icon="rotate"
+                        @text={{t "settings.telematics.refresh"}}
+                        @onClick={{perform this.loadUsage}}
+                        @disabled={{this.loadUsage.isRunning}}
+                        @isLoading={{this.loadUsage.isRunning}}
+                    />
                     <Button
                         @type="danger"
                         @size="xs"
@@ -115,13 +125,6 @@
                 {{/if}}
             </ContentPanel>
 
-            {{! ── System defaults (administrators) ────────────────────────── }}
-            {{#if this.isAdmin}}
-                <ContentPanel @title={{t "settings.telematics.admin-defaults"}} @open={{false}} @wrapperClass="bordered-classic">
-                    <Admin::TelematicsSettings @embedded={{true}} />
-                </ContentPanel>
-            {{/if}}
-
         </div>
     </div>
     <Spacer @height="600px" />
diff --git a/server/src/Http/Controllers/Internal/v1/SettingController.php b/server/src/Http/Controllers/Internal/v1/SettingController.php
index f1b6cf078..0b5de7684 100644
--- a/server/src/Http/Controllers/Internal/v1/SettingController.php
+++ b/server/src/Http/Controllers/Internal/v1/SettingController.php
@@ -38,6 +38,8 @@ public function __construct()
             'saveSchedulingSettings'                  => 'update scheduling-settings',
             'saveOrchestratorSettings'                => 'update routing-settings',
             'saveOrchestratorCardFields'              => 'update routing-settings',
+            'getAdminTelematicsSettings'              => 'admin',
+            'saveAdminTelematicsSettings'             => 'admin',
         ]);
     }
 
@@ -752,7 +754,6 @@ public function getTelematicsStorageUsage()
         }
 
         $companyUuid = $company->uuid;
-        $policy      = RetentionPolicy::normalize((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, []), $this->telematicsDefaults());
         $telematics  = $this->companyTelematicUuids($companyUuid);
         $byCompany   = fn ($query) => $query->where('company_uuid', $companyUuid);
         $byInbox     = fn ($query) => $query->whereIn('telematic_uuid', $telematics);
@@ -764,12 +765,16 @@ public function getTelematicsStorageUsage()
             'telematic_sync_runs'  => $telematics ? $this->tableUsage('telematic_sync_runs', $byInbox, 'created_at') : ['rows' => 0, 'oldest' => null],
         ];
 
-        // Events still carrying raw provider payloads, and how many of them compaction would strip now.
-        $tables['device_events']['raw_payload_rows'] = $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload'));
-        $compactAfter                                = (int) $policy['event_compact_after_days'];
-        $tables['device_events']['compactable_rows'] = $compactAfter > 0
-            ? $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload')->where('created_at', '<', now()->subDays($compactAfter)->toDateTimeString()))
-            : 0;
+        // Payload counts scan the JSON-bearing event rows. The storage table can
+        // omit these details to use only indexed counts and ages on large histories.
+        if (request()->boolean('include_payload_counts', true)) {
+            $policy                                      = RetentionPolicy::normalize((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, []), $this->telematicsDefaults());
+            $tables['device_events']['raw_payload_rows'] = $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload'));
+            $compactAfter                                = (int) $policy['event_compact_after_days'];
+            $tables['device_events']['compactable_rows'] = $compactAfter > 0
+                ? $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload')->where('created_at', '<', now()->subDays($compactAfter)->toDateTimeString()))
+                : 0;
+        }
 
         foreach ($this->averageRowLengths(array_keys($tables)) as $table => $length) {
             $tables[$table]['avg_row_bytes']   = $length;
diff --git a/translations/en-us.yaml b/translations/en-us.yaml
index c93366201..0c046185b 100644
--- a/translations/en-us.yaml
+++ b/translations/en-us.yaml
@@ -114,7 +114,7 @@ menu:
     maintenances: Maintenances
     orchestrator: Orchestrator
     orchestrator-settings: Orchestrator Settings
-    telematics-settings: Telematics Data
+    telematics-settings: Telematics
 
 trailer:
     navigation-description: Manage towed assets, towing connections, equipment, and telematics.
@@ -2725,28 +2725,28 @@ route-list:
 
 settings:
     telematics:
-        telematics-settings: Telematics Data Retention
-        intro: Telematics polling writes a device event, a position and a delivery envelope for every reporting device on every poll. These rules bound how long each kind of row is kept so storage stays predictable. A value of 0 keeps rows forever.
-        device-events: Device Events
+        telematics-settings: Telematics Settings
+        intro: Configure telematics data retention and activity logging for your organization. These values override the system defaults managed by your administrator. A retention value of 0 keeps records forever.
+        device-events: Device Events Retention
         event-retention-days: Keep device events for (days)
         event-retention-days-help: Events older than this are permanently deleted. Applies to telemetry updates and provider alerts alike.
         event-compact-after-days: Strip raw payloads after (days)
         event-compact-after-days-help: Events older than this keep their type, severity, location and normalized data, but the raw provider payload is removed. Raw payloads are the bulk of each event's size.
         compaction-warning: Raw payloads are only stripped from events that are kept. Set this lower than the event retention or set it to 0 to disable compaction.
-        positions: Positions
+        positions: Position History Retention
         position-retention-days: Keep positions for (days)
         position-retention-days-help: Vehicle and trailer position history older than this is permanently deleted. Route replay and history views only reach back this far.
-        inbox: Delivery Inbox & Sync Runs
+        inbox: Delivery Inbox & Sync Run Retention
         processed-retention-hours: Keep processed deliveries for (hours)
         processed-retention-hours-help: Raw provider batches are stored encrypted until processed and kept briefly for replay and diagnostics. Each batch can be close to a megabyte.
         quarantine-retention-days: Keep quarantined deliveries for (days)
         quarantine-retention-days-help: Batches that could not be processed stay available for inspection and replay for this long.
         sync-run-retention-days: Keep sync run diagnostics for (days)
         sync-run-retention-days-help: One sync run row is recorded per connection per poll. In-flight runs are never removed.
-        activity-logging: Activity Logging
+        activity-logging: Telemetry Activity Logging
         log-telemetry-activity: Log telemetry activity
         log-telemetry-activity-help: Write telemetry-driven device, event and vehicle saves to the activity log. Off by default; every poll otherwise adds several activity rows per device.
-        storage-usage: Storage Usage
+        storage-usage: Telematics Storage Usage
         table: Table
         rows: Rows
         estimated-size: Estimated size
@@ -2757,10 +2757,9 @@ settings:
         run-cleanup: Run cleanup now
         run-cleanup-confirm: This queues a retention run for your organization using the rules above. Rows outside the retention windows are permanently deleted and cannot be recovered. Continue?
         cleanup-queued: Telematics cleanup has been queued. Usage refreshes shortly.
-        usage-unavailable: Storage usage is not available right now.
+        usage-unavailable: Storage usage could not be loaded. Select Refresh to try again.
         space-reclaim-note: Sizes are estimates from average row length. Deleting rows frees space inside the database files; run OPTIMIZE TABLE during a maintenance window to return it to the operating system.
-        admin-defaults: System Defaults (administrators)
-        settings-saved: Telematics data settings saved.
+        settings-saved: Telematics settings saved.
         tables:
             device_events: Device events
             positions: Positions

From e06863a92b7bbd8054c06f15043a3f27302b35ab Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 14:43:03 +0800
Subject: [PATCH 13/24] fix: bound telematics storage queries and polish
 settings navigation

---
 addon/components/layout/fleet-ops-sidebar.js  |   2 +-
 addon/controllers/settings/index.js           |   4 +-
 addon/extension.js                            |   2 +-
 addon/templates/settings/telematics.hbs       |  16 +-
 .../Internal/v1/SettingController.php         | 141 +++++++++++++++---
 .../tests/SettingControllerContractsTest.php  |  11 ++
 translations/en-us.yaml                       |   3 +-
 7 files changed, 147 insertions(+), 32 deletions(-)

diff --git a/addon/components/layout/fleet-ops-sidebar.js b/addon/components/layout/fleet-ops-sidebar.js
index 0a0516da4..8a2e67bad 100644
--- a/addon/components/layout/fleet-ops-sidebar.js
+++ b/addon/components/layout/fleet-ops-sidebar.js
@@ -208,7 +208,7 @@ export default class LayoutFleetOpsSidebarComponent extends Component {
             this.createItem('menu.routing', 'route', 'settings.routing', 'fleet-ops view routing-settings', 'fleet-ops see routing-settings'),
             this.createItem('menu.orchestrator', 'circle-nodes', 'settings.orchestrator', 'fleet-ops view routing-settings', 'fleet-ops see routing-settings'),
             this.createItem('menu.scheduling', 'calendar-days', 'settings.scheduling', 'fleet-ops view scheduling-settings', 'fleet-ops see scheduling-settings'),
-            this.createItem('menu.telematics-settings', 'database', 'settings.telematics', 'fleet-ops view telematics-settings', 'fleet-ops see telematics-settings'),
+            this.createItem('menu.telematics-settings', 'satellite-dish', 'settings.telematics', 'fleet-ops view telematics-settings', 'fleet-ops see telematics-settings'),
             this.createItem('menu.custom-fields', 'pen-to-square', 'settings.custom-fields', 'fleet-ops list custom-field', 'fleet-ops see custom-field'),
             this.createItem('menu.avatars', 'icons', 'settings.avatars', 'fleet-ops list avatar', 'fleet-ops see avatar'),
         ]);
diff --git a/addon/controllers/settings/index.js b/addon/controllers/settings/index.js
index 1837ae8d0..fe24faff3 100644
--- a/addon/controllers/settings/index.js
+++ b/addon/controllers/settings/index.js
@@ -28,7 +28,7 @@ export default class SettingsIndexController extends Controller {
             description: 'Keep commerce, metadata, and visual conventions aligned.',
             links: [
                 { label: 'Payments', route: 'settings.payments', icon: 'cash-register', description: 'Payment setup for operational commerce workflows.' },
-                { label: 'Telematics', route: 'settings.telematics', icon: 'database', description: 'Organization telematics settings, data retention, storage usage, and activity logging.' },
+                { label: 'Telematics', route: 'settings.telematics', icon: 'satellite-dish', description: 'Organization telematics settings, data retention, storage usage, and activity logging.' },
                 { label: 'Custom Fields', route: 'settings.custom-fields', icon: 'pen-to-square', description: 'Operational metadata fields for Fleet-Ops records.' },
                 { label: 'Avatars', route: 'settings.avatars', icon: 'icons', description: 'Visual assets for driver, vehicle, and map displays.' },
             ],
@@ -116,7 +116,7 @@ export default class SettingsIndexController extends Controller {
         },
         {
             label: 'Telematics',
-            icon: 'database',
+            icon: 'satellite-dish',
             slug: 'fleet-ops/settings/telematics',
             title: 'Telematics Settings',
             description: 'Control how long telemetry events, positions, and delivery history are kept.',
diff --git a/addon/extension.js b/addon/extension.js
index 4dca7ab9a..5aebbad9c 100644
--- a/addon/extension.js
+++ b/addon/extension.js
@@ -114,7 +114,7 @@ export default {
                 }),
                 new MenuItem({
                     title: 'Telematics',
-                    icon: 'database',
+                    icon: 'satellite-dish',
                     component: new ExtensionComponent('@fleetbase/fleetops-engine', 'admin/telematics-settings'),
                 }),
             ],
diff --git a/addon/templates/settings/telematics.hbs b/addon/templates/settings/telematics.hbs
index 4b358e1ba..4d0c44fea 100644
--- a/addon/templates/settings/telematics.hbs
+++ b/addon/templates/settings/telematics.hbs
@@ -10,7 +10,7 @@
     />
 </Layout::Section::Header>
 <Layout::Section::Body class="overflow-y-scroll-i h-full">
-    <div class="container mx-auto h-screen">
+    <div class="container mx-auto">
         <div class="max-w-3xl my-10 mx-auto space-y-6">
 
             <InfoBlock @type="info" @icon="circle-info">
@@ -105,8 +105,16 @@
                                                 </div>
                                             {{/if}}
                                         </td>
-                                        <td class="py-2 pr-3 text-right">{{format-number row.rows}}</td>
-                                        <td class="py-2 pr-3 text-right">{{#if row.estimated_bytes}}{{format-bytes row.estimated_bytes}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
+                                        <td class="py-2 pr-3 text-right">
+                                            {{#if (eq row.rows null)}}
+                                                {{t "settings.telematics.not-available"}}
+                                            {{else if row.rows_estimated}}
+                                                {{t "settings.telematics.estimated-rows" count=(format-number row.rows)}}
+                                            {{else}}
+                                                {{format-number row.rows}}
+                                            {{/if}}
+                                        </td>
+                                        <td class="py-2 pr-3 text-right">{{#if (or row.estimated_bytes (eq row.estimated_bytes 0))}}{{format-bytes row.estimated_bytes}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
                                         <td class="py-2 text-xs">{{#if row.oldest}}{{row.oldest}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
                                     </tr>
                                 {{/each}}
@@ -127,5 +135,5 @@
 
         </div>
     </div>
-    <Spacer @height="600px" />
+    <Spacer @height="200px" />
 </Layout::Section::Body>
diff --git a/server/src/Http/Controllers/Internal/v1/SettingController.php b/server/src/Http/Controllers/Internal/v1/SettingController.php
index 0b5de7684..b7655c8af 100644
--- a/server/src/Http/Controllers/Internal/v1/SettingController.php
+++ b/server/src/Http/Controllers/Internal/v1/SettingController.php
@@ -10,6 +10,8 @@
 use Fleetbase\Models\Setting;
 use Fleetbase\Support\Auth;
 use Fleetbase\Support\NotificationRegistry;
+use Illuminate\Database\MySqlConnection;
+use Illuminate\Database\QueryException;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
 
@@ -741,8 +743,9 @@ public function saveAdminTelematicsSettings(Request $request)
     /**
      * Report how much telematics data the current company holds per table.
      *
-     * Row counts are exact; sizes are estimates from the table's average row
-     * length because InnoDB does not account space per tenant.
+     * Exact counts have a database execution deadline. Large histories fall
+     * back to explicitly marked, company-scoped query-plan estimates. Sizes
+     * use average row length because InnoDB does not account space per tenant.
      *
      * @return \Illuminate\Http\JsonResponse
      */
@@ -765,20 +768,31 @@ public function getTelematicsStorageUsage()
             'telematic_sync_runs'  => $telematics ? $this->tableUsage('telematic_sync_runs', $byInbox, 'created_at') : ['rows' => 0, 'oldest' => null],
         ];
 
-        // Payload counts scan the JSON-bearing event rows. The storage table can
-        // omit these details to use only indexed counts and ages on large histories.
-        if (request()->boolean('include_payload_counts', true)) {
-            $policy                                      = RetentionPolicy::normalize((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, []), $this->telematicsDefaults());
-            $tables['device_events']['raw_payload_rows'] = $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload'));
-            $compactAfter                                = (int) $policy['event_compact_after_days'];
-            $tables['device_events']['compactable_rows'] = $compactAfter > 0
-                ? $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload')->where('created_at', '<', now()->subDays($compactAfter)->toDateTimeString()))
-                : 0;
+        // Payload details require reading JSON-bearing rows, so they are opt-in
+        // and omitted if they cannot be counted within the database deadline.
+        if (request()->boolean('include_payload_counts', false)) {
+            try {
+                $policy          = RetentionPolicy::normalize((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, []), $this->telematicsDefaults());
+                $rawPayloadRows  = $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload'));
+                $compactAfter    = (int) $policy['event_compact_after_days'];
+                $compactableRows = $compactAfter > 0
+                    ? $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload')->where('created_at', '<', now()->subDays($compactAfter)->toDateTimeString()))
+                    : 0;
+
+                $tables['device_events']['raw_payload_rows'] = $rawPayloadRows;
+                $tables['device_events']['compactable_rows'] = $compactableRows;
+            } catch (QueryException $exception) {
+                if (!$this->isStorageUsageTimeout($exception)) {
+                    throw $exception;
+                }
+            }
         }
 
         foreach ($this->averageRowLengths(array_keys($tables)) as $table => $length) {
-            $tables[$table]['avg_row_bytes']   = $length;
-            $tables[$table]['estimated_bytes'] = (int) ($tables[$table]['rows'] * $length);
+            $tables[$table]['avg_row_bytes'] = $length;
+            if ($tables[$table]['rows'] !== null) {
+                $tables[$table]['estimated_bytes'] = (int) ($tables[$table]['rows'] * $length);
+            }
         }
 
         return response()->json([
@@ -819,10 +833,45 @@ protected function telematicsDefaults(): array
 
     protected function tableUsage(string $table, \Closure $scope, string $ageColumn): array
     {
-        return [
-            'rows'   => $this->tableCount($table, $scope),
-            'oldest' => $this->tableOldest($table, $scope, $ageColumn),
-        ];
+        if (!in_array(DB::connection()->getDriverName(), ['mysql', 'mariadb'], true)) {
+            return [
+                'rows'   => $this->tableCount($table, $scope),
+                'oldest' => $this->tableOldest($table, $scope, $ageColumn),
+            ];
+        }
+
+        $query = $scope(DB::table($table));
+        $query->selectRaw('COUNT(*) AS row_count, MIN(' . $query->getGrammar()->wrap($ageColumn) . ') AS oldest');
+
+        try {
+            $usage = $this->storageUsageSelect($query->toSql(), $query->getBindings())[0];
+
+            return [
+                'rows'   => (int) $usage->row_count,
+                'oldest' => $usage->oldest === null ? null : (string) $usage->oldest,
+            ];
+        } catch (QueryException $exception) {
+            if (!$this->isStorageUsageTimeout($exception)) {
+                throw $exception;
+            }
+        }
+
+        // EXPLAIN does not execute the history scan. Keep the original tenant
+        // filter: whole-table InnoDB row counts include other companies' data.
+        $estimate = null;
+        $query    = $scope(DB::table($table))->select($ageColumn);
+        try {
+            $plan = $this->storageUsageSelect($query->toSql(), $query->getBindings(), true)[0] ?? null;
+            if (isset($plan->rows)) {
+                $estimate = max(0, (int) round((float) $plan->rows * (float) ($plan->filtered ?? 100) / 100));
+            }
+        } catch (QueryException $exception) {
+            if (!$this->isStorageUsageTimeout($exception)) {
+                throw $exception;
+            }
+        }
+
+        return ['rows' => $estimate, 'oldest' => null, 'rows_estimated' => true];
     }
 
     protected function companyTelematicUuids(string $companyUuid): array
@@ -832,7 +881,10 @@ protected function companyTelematicUuids(string $companyUuid): array
 
     protected function tableCount(string $table, \Closure $scope): int
     {
-        return (int) $scope(DB::table($table))->count();
+        $query = $scope(DB::table($table))->selectRaw('COUNT(*) AS row_count');
+        $usage = $this->storageUsageSelect($query->toSql(), $query->getBindings())[0];
+
+        return (int) $usage->row_count;
     }
 
     protected function tableOldest(string $table, \Closure $scope, string $column): ?string
@@ -842,6 +894,41 @@ protected function tableOldest(string $table, \Closure $scope, string $column):
         return $oldest ? (string) $oldest : null;
     }
 
+    /**
+     * Bound each MySQL/MariaDB scan to one second without changing persistent
+     * connection settings. A browser abort alone leaves database work running.
+     */
+    protected function storageUsageSelect(string $sql, array $bindings = [], bool $explain = false): array
+    {
+        $connection = DB::connection();
+        $driver     = $connection->getDriverName();
+        $isMariaDb  = $driver === 'mariadb';
+
+        if ($connection instanceof MySqlConnection) {
+            $isMariaDb = method_exists($connection, 'isMaria')
+                ? $connection->isMaria()
+                : stripos((string) $connection->getReadPdo()->getAttribute(\PDO::ATTR_SERVER_VERSION), 'MariaDB') !== false;
+        }
+
+        if ($isMariaDb) {
+            $sql = 'SET STATEMENT max_statement_time=1 FOR ' . ($explain ? 'EXPLAIN ' : '') . $sql;
+        } else {
+            if ($driver === 'mysql') {
+                $sql = preg_replace('/^select\b/i', 'SELECT /*+ MAX_EXECUTION_TIME(1000) */', $sql, 1);
+            }
+            if ($explain) {
+                $sql = 'EXPLAIN ' . $sql;
+            }
+        }
+
+        return $connection->select($sql, $bindings);
+    }
+
+    protected function isStorageUsageTimeout(QueryException $exception): bool
+    {
+        return in_array((int) ($exception->errorInfo[1] ?? 0), [3024, 1969], true);
+    }
+
     /**
      * Average row length per table from InnoDB statistics. Empty on other drivers.
      *
@@ -850,16 +937,24 @@ protected function tableOldest(string $table, \Closure $scope, string $column):
     protected function averageRowLengths(array $tables): array
     {
         $connection = DB::connection();
-        if ($connection->getDriverName() !== 'mysql') {
+        if (!in_array($connection->getDriverName(), ['mysql', 'mariadb'], true)) {
             return [];
         }
 
         $prefix       = $connection->getTablePrefix();
         $placeholders = implode(', ', array_fill(0, count($tables), '?'));
-        $rows         = $connection->select(
-            'SELECT TABLE_NAME AS name, AVG_ROW_LENGTH AS length FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (' . $placeholders . ')',
-            array_map(fn ($table) => $prefix . $table, $tables)
-        );
+        try {
+            $rows = $this->storageUsageSelect(
+                'SELECT TABLE_NAME AS name, AVG_ROW_LENGTH AS length FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (' . $placeholders . ')',
+                array_map(fn ($table) => $prefix . $table, $tables)
+            );
+        } catch (QueryException $exception) {
+            if (!$this->isStorageUsageTimeout($exception)) {
+                throw $exception;
+            }
+
+            return [];
+        }
 
         $lengths = [];
         foreach ($rows as $row) {
diff --git a/server/tests/SettingControllerContractsTest.php b/server/tests/SettingControllerContractsTest.php
index e24b75ac3..11f9e13c4 100644
--- a/server/tests/SettingControllerContractsTest.php
+++ b/server/tests/SettingControllerContractsTest.php
@@ -97,6 +97,14 @@ protected function companyTelematicUuids(string $companyUuid): array
         return $this->telematicUuids[$companyUuid] ?? [];
     }
 
+    protected function tableUsage(string $table, Closure $scope, string $ageColumn): array
+    {
+        return [
+            'rows'   => $this->tableCount($table, $scope),
+            'oldest' => $this->tableOldest($table, $scope, $ageColumn),
+        ];
+    }
+
     protected function tableCount(string $table, Closure $scope): int
     {
         $this->countScopes[] = $table;
@@ -540,6 +548,8 @@ function fleetopsJsonPayload(mixed $response): array
 });
 
 test('telematics storage usage reports rows, age, compaction backlog and estimated size per table', function () {
+    $originalRequest = app('request');
+    app()->instance('request', new Request(['include_payload_counts' => true]));
     Illuminate\Support\Carbon::setTestNow('2026-09-23 12:00:00 UTC');
     try {
         $controller                 = new FleetOpsSettingControllerProbe();
@@ -579,6 +589,7 @@ function fleetopsJsonPayload(mixed $response): array
             ->and(fleetopsJsonPayload($queued)['status'])->toBe('queued')
             ->and($controller->pruned)->toBe(['company-1']);
     } finally {
+        app()->instance('request', $originalRequest);
         Illuminate\Support\Carbon::setTestNow();
     }
 });
diff --git a/translations/en-us.yaml b/translations/en-us.yaml
index 0c046185b..ccffd2dbc 100644
--- a/translations/en-us.yaml
+++ b/translations/en-us.yaml
@@ -2749,6 +2749,7 @@ settings:
         storage-usage: Telematics Storage Usage
         table: Table
         rows: Rows
+        estimated-rows: "{count} (estimated)"
         estimated-size: Estimated size
         oldest: Oldest row
         not-available: n/a
@@ -2758,7 +2759,7 @@ settings:
         run-cleanup-confirm: This queues a retention run for your organization using the rules above. Rows outside the retention windows are permanently deleted and cannot be recovered. Continue?
         cleanup-queued: Telematics cleanup has been queued. Usage refreshes shortly.
         usage-unavailable: Storage usage could not be loaded. Select Refresh to try again.
-        space-reclaim-note: Sizes are estimates from average row length. Deleting rows frees space inside the database files; run OPTIMIZE TABLE during a maintenance window to return it to the operating system.
+        space-reclaim-note: Row counts marked as estimated use database statistics for your organization. Sizes are estimates from average row length. Deleting records frees space for reuse within the database; physical disk usage may not decrease immediately.
         settings-saved: Telematics settings saved.
         tables:
             device_events: Device events

From c137ef1f8e30902f0350d219c8491c991e3fab20 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 14:50:35 +0800
Subject: [PATCH 14/24] fix: space and align telematics oldest row column

---
 addon/templates/settings/telematics.hbs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/addon/templates/settings/telematics.hbs b/addon/templates/settings/telematics.hbs
index 4d0c44fea..8bda07cc3 100644
--- a/addon/templates/settings/telematics.hbs
+++ b/addon/templates/settings/telematics.hbs
@@ -91,7 +91,7 @@
                                     <th class="py-2 pr-3">{{t "settings.telematics.table"}}</th>
                                     <th class="py-2 pr-3 text-right">{{t "settings.telematics.rows"}}</th>
                                     <th class="py-2 pr-3 text-right">{{t "settings.telematics.estimated-size"}}</th>
-                                    <th class="py-2">{{t "settings.telematics.oldest"}}</th>
+                                    <th class="py-2 pl-6 text-left whitespace-nowrap">{{t "settings.telematics.oldest"}}</th>
                                 </tr>
                             </thead>
                             <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
@@ -115,7 +115,7 @@
                                             {{/if}}
                                         </td>
                                         <td class="py-2 pr-3 text-right">{{#if (or row.estimated_bytes (eq row.estimated_bytes 0))}}{{format-bytes row.estimated_bytes}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
-                                        <td class="py-2 text-xs">{{#if row.oldest}}{{row.oldest}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
+                                        <td class="py-2 pl-6 text-left text-xs whitespace-nowrap">{{#if row.oldest}}{{row.oldest}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
                                     </tr>
                                 {{/each}}
                             </tbody>

From e101833ca7e8e997a47b3f7ffdcba442539d1483 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 15:00:24 +0800
Subject: [PATCH 15/24] fix: separate customer history preferences from system
 telematics policy

---
 .../components/admin/telematics-settings.hbs  | 117 +++++++++++--
 addon/components/admin/telematics-settings.js |  73 +++++++-
 addon/controllers/settings/index.js           |   4 +-
 addon/controllers/settings/telematics.js      | 156 +++++-------------
 addon/templates/settings/telematics.hbs       | 145 ++++------------
 server/config/telemetry.php                   |   7 +-
 server/src/Auth/Schemas/FleetOps.php          |   6 +-
 .../Internal/v1/SettingController.php         |  76 +++++++--
 .../Telematics/Retention/RetentionPolicy.php  |  96 ++++++++---
 .../Retention/TelemetryActivity.php           |   2 +-
 .../tests/SettingControllerContractsTest.php  |  67 +++++---
 .../Retention/RetentionPolicyTest.php         |  68 ++++++--
 .../Retention/TelemetryActivityTest.php       |  16 +-
 translations/en-us.yaml                       |  11 +-
 14 files changed, 516 insertions(+), 328 deletions(-)

diff --git a/addon/components/admin/telematics-settings.hbs b/addon/components/admin/telematics-settings.hbs
index 377ab01ae..a39646d6c 100644
--- a/addon/components/admin/telematics-settings.hbs
+++ b/addon/components/admin/telematics-settings.hbs
@@ -1,45 +1,55 @@
 <div class="space-y-6">
     <InfoBlock @type="info" @icon="circle-info" class="mb-4">
-        Configure system-wide telematics defaults here. Organizations can override these values from Fleet-Ops &rsaquo; Settings &rsaquo; Telematics. A retention value of 0 keeps records forever.
+        Configure telematics retention policy and activity logging for all organizations. Organizations can choose device event and position history retention within these limits from Fleet-Ops &rsaquo; Settings &rsaquo; Telematics.
+        A maximum takes precedence over organization preferences, inherited defaults and requests to keep history forever. Reducing a maximum can delete existing history at the next cleanup.
     </InfoBlock>
 
-    <ContentPanel @title="System Device Events Retention Defaults" @open={{true}} @wrapperClass="bordered-classic">
+    <ContentPanel @title="System Device Events Retention Policy" @open={{true}} @wrapperClass="bordered-classic">
         <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-            <InputGroup @name="Device Event Retention (days)" @helpText="Delete telemetry events older than this. 0 keeps them forever.">
+            <InputGroup @name="Default Device Event Retention (days)" @helpText="Retention for organizations that inherit the system default. 0 keeps history forever, subject to the maximum below.">
                 <Input @type="number" @value={{this.eventRetentionDays}} min="0" max="3650" class="form-input w-full" />
             </InputGroup>
-            <InputGroup @name="Device Event Raw Payload Retention (days)" @helpText="Remove the raw provider payload from kept events after this many days. 0 disables compaction.">
-                <Input @type="number" @value={{this.eventCompactAfterDays}} min="0" max="3650" class="form-input w-full" />
+            <InputGroup @name="Maximum Device Event Retention (days)" @helpText="The longest any organization can keep device events. 0 sets no maximum and allows organizations to keep history forever.">
+                <Input @type="number" @value={{this.maxEventRetentionDays}} min="0" max="3650" class="form-input w-full" />
             </InputGroup>
         </div>
     </ContentPanel>
 
-    <ContentPanel @title="System Position History Retention Defaults" @open={{true}} @wrapperClass="bordered-classic">
+    <ContentPanel @title="System Position History Retention Policy" @open={{true}} @wrapperClass="bordered-classic">
         <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-            <InputGroup @name="Position History Retention (days)" @helpText="Delete vehicle and trailer positions older than this. 0 keeps them forever.">
+            <InputGroup @name="Default Position History Retention (days)" @helpText="Retention for organizations that inherit the system default. 0 keeps history forever, subject to the maximum below.">
                 <Input @type="number" @value={{this.positionRetentionDays}} min="0" max="3650" class="form-input w-full" />
             </InputGroup>
+            <InputGroup @name="Maximum Position History Retention (days)" @helpText="The longest any organization can keep vehicle and trailer positions. 0 sets no maximum and allows organizations to keep history forever.">
+                <Input @type="number" @value={{this.maxPositionRetentionDays}} min="0" max="3650" class="form-input w-full" />
+            </InputGroup>
         </div>
     </ContentPanel>
 
-    <ContentPanel @title="System Delivery Inbox and Sync Run Retention Defaults" @open={{true}} @wrapperClass="bordered-classic">
+    <ContentPanel @title="System Device Event Raw Payload Retention" @open={{true}} @wrapperClass="bordered-classic">
+        <InputGroup @name="Device Event Raw Payload Retention (days)" @helpText="Remove raw provider payloads from retained device events across all organizations after this many days. 0 disables compaction. This does not change how long the event history itself is kept.">
+            <Input @type="number" @value={{this.eventCompactAfterDays}} min="0" max="3650" class="form-input w-full" />
+        </InputGroup>
+    </ContentPanel>
+
+    <ContentPanel @title="System Delivery Inbox and Sync Run Retention Policy" @open={{true}} @wrapperClass="bordered-classic">
         <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
-            <InputGroup @name="Processed Delivery Retention (hours)" @helpText="Delete processed delivery envelopes older than this.">
+            <InputGroup @name="Processed Delivery Retention (hours)" @helpText="Delete processed delivery envelopes across all organizations after this many hours. 0 keeps them forever.">
                 <Input @type="number" @value={{this.processedRetentionHours}} min="0" max="720" class="form-input w-full" />
             </InputGroup>
-            <InputGroup @name="Quarantined Delivery Retention (days)" @helpText="Delete quarantined delivery envelopes older than this.">
+            <InputGroup @name="Quarantined Delivery Retention (days)" @helpText="Delete quarantined delivery envelopes across all organizations after this many days. 0 keeps them forever.">
                 <Input @type="number" @value={{this.quarantineRetentionDays}} min="0" max="365" class="form-input w-full" />
             </InputGroup>
-            <InputGroup @name="Sync Run Diagnostics Retention (days)" @helpText="Delete finished sync run diagnostics older than this.">
+            <InputGroup @name="Sync Run Diagnostics Retention (days)" @helpText="Delete finished sync run diagnostics across all organizations after this many days. 0 keeps them forever.">
                 <Input @type="number" @value={{this.syncRunRetentionDays}} min="0" max="365" class="form-input w-full" />
             </InputGroup>
         </div>
     </ContentPanel>
 
-    <ContentPanel @title="System Activity Logging Defaults" @open={{true}} @wrapperClass="bordered-classic">
+    <ContentPanel @title="System Telemetry Activity Logging" @open={{true}} @wrapperClass="bordered-classic">
         <Toggle
-            @label="Log Telemetry Activity by Default"
-            @helpText="Write telemetry-driven device, event and vehicle saves to the activity log. Off by default; every poll otherwise adds several activity rows per device."
+            @label="Log Telemetry Activity"
+            @helpText="Write telemetry-driven device, event and vehicle saves to the activity log for all organizations. Every poll can add several activity rows per device."
             @isToggled={{this.logTelemetryActivity}}
             @onToggle={{fn (mut this.logTelemetryActivity)}}
         />
@@ -50,10 +60,85 @@
             @type="primary"
             @size="sm"
             @icon="save"
-            @text="Save System Defaults"
+            @text="Save System Policy"
             @onClick={{perform this.saveSettings}}
-            @disabled={{this.saveSettings.isRunning}}
+            @disabled={{or this.saveSettings.isRunning this.loadSettings.isRunning (not this.settingsLoaded)}}
             @isLoading={{or this.saveSettings.isRunning this.loadSettings.isRunning}}
         />
     </div>
+
+    <ContentPanel @title={{t "settings.telematics.storage-usage"}} @open={{true}} @wrapperClass="bordered-classic">
+        <p class="mb-3 text-sm text-gray-600 dark:text-gray-300">
+            Storage diagnostics and manual cleanup apply only to the currently selected Console organization{{#if this.usage.company.name}}: <strong>{{this.usage.company.name}}</strong>{{/if}}.
+            Cleanup uses the saved system policy and the organization's history preferences within that policy.
+        </p>
+        <div class="flex items-center justify-end gap-2 mb-3">
+            <Button
+                @size="xs"
+                @icon="rotate"
+                @text={{t "settings.telematics.refresh"}}
+                @onClick={{perform this.loadUsage}}
+                @disabled={{this.loadUsage.isRunning}}
+                @isLoading={{this.loadUsage.isRunning}}
+            />
+            <Button
+                @type="danger"
+                @size="xs"
+                @icon="broom"
+                @text={{t "settings.telematics.run-cleanup"}}
+                @onClick={{this.confirmRunCleanup}}
+                @disabled={{or this.runCleanup.isRunning this.loadSettings.isRunning (not this.settingsLoaded)}}
+                @isLoading={{this.runCleanup.isRunning}}
+            />
+        </div>
+        {{#if this.usageRows.length}}
+            <div class="overflow-x-auto">
+                <table class="w-full text-sm">
+                    <thead>
+                        <tr class="text-left text-xs uppercase text-gray-500 dark:text-gray-400">
+                            <th class="py-2 pr-3">{{t "settings.telematics.table"}}</th>
+                            <th class="py-2 pr-3 text-right">{{t "settings.telematics.rows"}}</th>
+                            <th class="py-2 pr-3 text-right">{{t "settings.telematics.estimated-size"}}</th>
+                            <th class="py-2 pl-6 text-left whitespace-nowrap">{{t "settings.telematics.oldest"}}</th>
+                        </tr>
+                    </thead>
+                    <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
+                        {{#each this.usageRows as |row|}}
+                            <tr class="text-gray-800 dark:text-gray-100">
+                                <td class="py-2 pr-3">
+                                    <div class="font-medium">{{row.label}}</div>
+                                    {{#if row.raw_payload_rows}}
+                                        <div class="text-xs text-gray-500 dark:text-gray-400">
+                                            {{t "settings.telematics.raw-payload-rows" count=(format-number row.raw_payload_rows) compactable=(format-number row.compactable_rows)}}
+                                        </div>
+                                    {{/if}}
+                                </td>
+                                <td class="py-2 pr-3 text-right">
+                                    {{#if (eq row.rows null)}}
+                                        {{t "settings.telematics.not-available"}}
+                                    {{else if row.rows_estimated}}
+                                        {{t "settings.telematics.estimated-rows" count=(format-number row.rows)}}
+                                    {{else}}
+                                        {{format-number row.rows}}
+                                    {{/if}}
+                                </td>
+                                <td class="py-2 pr-3 text-right">{{#if (or row.estimated_bytes (eq row.estimated_bytes 0))}}{{format-bytes row.estimated_bytes}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
+                                <td class="py-2 pl-6 text-left text-xs whitespace-nowrap">{{#if row.oldest}}{{row.oldest}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
+                            </tr>
+                        {{/each}}
+                    </tbody>
+                </table>
+            </div>
+            <p class="mt-3 text-xs text-gray-500 dark:text-gray-400">{{t "settings.telematics.space-reclaim-note"}}</p>
+        {{else if this.loadUsage.isRunning}}
+            <div class="flex items-center justify-center py-8">
+                <Spinner />
+            </div>
+        {{else}}
+            <div class="text-center py-8 text-sm text-gray-400 dark:text-gray-500">
+                {{t "settings.telematics.usage-unavailable"}}
+            </div>
+        {{/if}}
+    </ContentPanel>
+    <Spacer @height="200px" />
 </div>
diff --git a/addon/components/admin/telematics-settings.js b/addon/components/admin/telematics-settings.js
index 5ceedc041..b628bccf7 100644
--- a/addon/components/admin/telematics-settings.js
+++ b/addon/components/admin/telematics-settings.js
@@ -1,38 +1,51 @@
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
 import { inject as service } from '@ember/service';
-import { task } from 'ember-concurrency';
+import { action } from '@ember/object';
+import { task, timeout } from 'ember-concurrency';
 
 /**
- * System-wide telematics defaults, applied to every company that
- * has not set its own values from Fleet-Ops > Settings > Telematics.
+ * System-wide telematics policy and operational controls. Storage diagnostics
+ * and manual cleanup are scoped to the current Console organization.
  */
 export default class AdminTelematicsSettingsComponent extends Component {
     @service fetch;
     @service notifications;
+    @service intl;
+    @service modalsManager;
     @tracked eventRetentionDays = 30;
+    @tracked maxEventRetentionDays = 0;
     @tracked eventCompactAfterDays = 7;
     @tracked positionRetentionDays = 90;
+    @tracked maxPositionRetentionDays = 0;
     @tracked processedRetentionHours = 24;
     @tracked quarantineRetentionDays = 7;
     @tracked syncRunRetentionDays = 7;
     @tracked logTelemetryActivity = false;
+    @tracked settingsLoaded = false;
+    @tracked usage = null;
 
     constructor() {
         super(...arguments);
         this.loadSettings.perform();
+        this.loadUsage.perform();
     }
 
-    @task *loadSettings() {
+    @task({ drop: true }) *loadSettings() {
         try {
             const settings = yield this.fetch.get('fleet-ops/settings/admin-telematics-settings');
             this.applySettings(settings);
+            this.settingsLoaded = true;
         } catch (error) {
             this.notifications.serverError(error);
         }
     }
 
-    @task *saveSettings() {
+    @task({ drop: true }) *saveSettings() {
+        if (!this.settingsLoaded) {
+            return;
+        }
+
         try {
             const settings = yield this.fetch.post('fleet-ops/settings/admin-telematics-settings', this.settingsPayload);
             this.applySettings(settings);
@@ -42,11 +55,59 @@ export default class AdminTelematicsSettingsComponent extends Component {
         }
     }
 
+    /** Load storage usage for the current Console organization. */
+    @task({ drop: true }) *loadUsage() {
+        const abortController = new AbortController();
+        const requestTimeout = setTimeout(() => abortController.abort(), 30000);
+
+        try {
+            // Pass the signal as request data; fetch.get options do not forward it.
+            this.usage = yield this.fetch.request('fleet-ops/settings/telematics-storage-usage?include_payload_counts=0', 'GET', { signal: abortController.signal });
+        } catch (error) {
+            this.notifications.serverError(abortController.signal.aborted ? new Error(this.intl.t('settings.telematics.usage-unavailable')) : error);
+        } finally {
+            clearTimeout(requestTimeout);
+            abortController.abort();
+        }
+    }
+
+    /** Queue cleanup for the current organization using the saved policy. */
+    @task({ drop: true }) *runCleanup() {
+        try {
+            yield this.fetch.post('fleet-ops/settings/telematics-retention/run');
+            this.notifications.success(this.intl.t('settings.telematics.cleanup-queued'));
+            yield timeout(5000);
+            yield this.loadUsage.perform();
+        } catch (error) {
+            this.notifications.serverError(error);
+        }
+    }
+
+    @action confirmRunCleanup() {
+        return this.modalsManager.confirm({
+            title: this.intl.t('settings.telematics.run-cleanup'),
+            body: this.intl.t('settings.telematics.run-cleanup-confirm'),
+            acceptButtonText: this.intl.t('settings.telematics.run-cleanup'),
+            acceptButtonIcon: 'broom',
+            onConfirm: () => this.runCleanup.perform(),
+        });
+    }
+
+    get usageRows() {
+        const tables = this.usage?.tables ?? {};
+
+        return ['device_events', 'positions', 'telematic_deliveries', 'telematic_sync_runs']
+            .filter((table) => tables[table])
+            .map((table) => ({ table, label: this.intl.t(`settings.telematics.tables.${table}`), ...tables[table] }));
+    }
+
     get settingsPayload() {
         return {
             event_retention_days: this.toInteger(this.eventRetentionDays),
+            max_event_retention_days: this.maxEventRetentionDays,
             event_compact_after_days: this.toInteger(this.eventCompactAfterDays),
             position_retention_days: this.toInteger(this.positionRetentionDays),
+            max_position_retention_days: this.maxPositionRetentionDays,
             processed_retention_hours: this.toInteger(this.processedRetentionHours),
             quarantine_retention_days: this.toInteger(this.quarantineRetentionDays),
             sync_run_retention_days: this.toInteger(this.syncRunRetentionDays),
@@ -60,8 +121,10 @@ export default class AdminTelematicsSettingsComponent extends Component {
         }
 
         this.eventRetentionDays = settings.event_retention_days ?? this.eventRetentionDays;
+        this.maxEventRetentionDays = settings.max_event_retention_days ?? this.maxEventRetentionDays;
         this.eventCompactAfterDays = settings.event_compact_after_days ?? this.eventCompactAfterDays;
         this.positionRetentionDays = settings.position_retention_days ?? this.positionRetentionDays;
+        this.maxPositionRetentionDays = settings.max_position_retention_days ?? this.maxPositionRetentionDays;
         this.processedRetentionHours = settings.processed_retention_hours ?? this.processedRetentionHours;
         this.quarantineRetentionDays = settings.quarantine_retention_days ?? this.quarantineRetentionDays;
         this.syncRunRetentionDays = settings.sync_run_retention_days ?? this.syncRunRetentionDays;
diff --git a/addon/controllers/settings/index.js b/addon/controllers/settings/index.js
index fe24faff3..e7ec33afb 100644
--- a/addon/controllers/settings/index.js
+++ b/addon/controllers/settings/index.js
@@ -28,7 +28,7 @@ export default class SettingsIndexController extends Controller {
             description: 'Keep commerce, metadata, and visual conventions aligned.',
             links: [
                 { label: 'Payments', route: 'settings.payments', icon: 'cash-register', description: 'Payment setup for operational commerce workflows.' },
-                { label: 'Telematics', route: 'settings.telematics', icon: 'satellite-dish', description: 'Organization telematics settings, data retention, storage usage, and activity logging.' },
+                { label: 'Telematics', route: 'settings.telematics', icon: 'satellite-dish', description: 'Device event and position history preferences within the system retention policy.' },
                 { label: 'Custom Fields', route: 'settings.custom-fields', icon: 'pen-to-square', description: 'Operational metadata fields for Fleet-Ops records.' },
                 { label: 'Avatars', route: 'settings.avatars', icon: 'icons', description: 'Visual assets for driver, vehicle, and map displays.' },
             ],
@@ -119,7 +119,7 @@ export default class SettingsIndexController extends Controller {
             icon: 'satellite-dish',
             slug: 'fleet-ops/settings/telematics',
             title: 'Telematics Settings',
-            description: 'Control how long telemetry events, positions, and delivery history are kept.',
+            description: 'Choose how long your organization keeps device events and position history.',
         },
         {
             label: 'Custom Fields',
diff --git a/addon/controllers/settings/telematics.js b/addon/controllers/settings/telematics.js
index b58537bc9..d0dad8a6b 100644
--- a/addon/controllers/settings/telematics.js
+++ b/addon/controllers/settings/telematics.js
@@ -2,101 +2,68 @@ import Controller from '@ember/controller';
 import { tracked } from '@glimmer/tracking';
 import { inject as service } from '@ember/service';
 import { action } from '@ember/object';
-import { task, timeout } from 'ember-concurrency';
-
-/**
- * Settings::TelematicsController
- *
- * Company-level data retention for telematics ingestion:
- *   - How long device events are kept, and when their raw provider payloads are stripped
- *   - How long positions are kept
- *   - How long processed and quarantined delivery envelopes and sync runs are kept
- *   - Whether telemetry-driven saves are written to the activity log
- * plus a read-only view of the rows each table holds and an on-demand cleanup run.
- */
+import { task } from 'ember-concurrency';
+
+/** Organization history preferences, subject to the system retention policy. */
 export default class SettingsTelematicsController extends Controller {
     @service fetch;
     @service notifications;
     @service intl;
-    @service modalsManager;
 
-    /** Days to keep device events; 0 keeps them forever. */
     @tracked eventRetentionDays = 30;
-
-    /** Days after which raw payload/meta blobs are stripped from kept events; 0 disables compaction. */
-    @tracked eventCompactAfterDays = 7;
-
-    /** Days to keep positions; 0 keeps them forever. */
     @tracked positionRetentionDays = 90;
-
-    /** Hours to keep processed delivery envelopes. */
-    @tracked processedRetentionHours = 24;
-
-    /** Days to keep quarantined delivery envelopes. */
-    @tracked quarantineRetentionDays = 7;
-
-    /** Days to keep sync run diagnostics. */
-    @tracked syncRunRetentionDays = 7;
-
-    /** Whether telemetry-driven saves are written to the activity log. */
-    @tracked logTelemetryActivity = false;
-
-    /** System defaults and clamp limits reported by the API. */
+    @tracked useDefaultEventRetention = true;
+    @tracked useDefaultPositionRetention = true;
     @tracked defaults = {};
-    @tracked limits = {};
+    @tracked policy = {};
+    @tracked settingsLoaded = false;
+
+    get eventRetentionMinimum() {
+        return this.policy.max_event_retention_days > 0 ? 1 : 0;
+    }
 
-    /** Per-table storage usage reported by the API. */
-    @tracked usage = null;
+    get eventRetentionMaximum() {
+        return this.policy.max_event_retention_days > 0 ? this.policy.max_event_retention_days : 3650;
+    }
 
-    /** Compaction is pointless once events are deleted at the same age or sooner. */
-    get compactionIneffective() {
-        const retention = Number(this.eventRetentionDays);
-        const compactAfter = Number(this.eventCompactAfterDays);
+    get positionRetentionMinimum() {
+        return this.policy.max_position_retention_days > 0 ? 1 : 0;
+    }
 
-        return retention > 0 && compactAfter > 0 && compactAfter >= retention;
+    get positionRetentionMaximum() {
+        return this.policy.max_position_retention_days > 0 ? this.policy.max_position_retention_days : 3650;
     }
 
-    get usageRows() {
-        const tables = this.usage?.tables ?? {};
+    get eventRetentionPolicyHelp() {
+        return this.retentionPolicyHelp(this.policy.max_event_retention_days);
+    }
 
-        return ['device_events', 'positions', 'telematic_deliveries', 'telematic_sync_runs']
-            .filter((table) => tables[table])
-            .map((table) => ({ table, label: this.intl.t(`settings.telematics.tables.${table}`), ...tables[table] }));
+    get positionRetentionPolicyHelp() {
+        return this.retentionPolicyHelp(this.policy.max_position_retention_days);
     }
 
     get settingsPayload() {
         return {
-            event_retention_days: this.toInteger(this.eventRetentionDays),
-            event_compact_after_days: this.toInteger(this.eventCompactAfterDays),
-            position_retention_days: this.toInteger(this.positionRetentionDays),
-            processed_retention_hours: this.toInteger(this.processedRetentionHours),
-            quarantine_retention_days: this.toInteger(this.quarantineRetentionDays),
-            sync_run_retention_days: this.toInteger(this.syncRunRetentionDays),
-            log_telemetry_activity: Boolean(this.logTelemetryActivity),
+            event_retention_days: this.useDefaultEventRetention ? null : this.eventRetentionDays,
+            position_retention_days: this.useDefaultPositionRetention ? null : this.positionRetentionDays,
         };
     }
 
     constructor() {
         super(...arguments);
         this.getSettings.perform();
-        this.loadUsage.perform();
     }
 
-    /**
-     * Load retention settings from the backend.
-     */
     @task *getSettings() {
         try {
             const settings = yield this.fetch.get('fleet-ops/settings/telematics-settings');
             this.applySettings(settings);
-        } catch {
-            // Settings may not exist yet — use defaults silently
+            this.settingsLoaded = true;
+        } catch (error) {
+            this.notifications.serverError(error);
         }
     }
 
-    /**
-     * Save retention settings to the backend.
-     */
     @task *saveSettings() {
         try {
             const settings = yield this.fetch.post('fleet-ops/settings/telematics-settings', this.settingsPayload);
@@ -107,67 +74,32 @@ export default class SettingsTelematicsController extends Controller {
         }
     }
 
-    /**
-     * Load per-table storage usage for the current company.
-     */
-    @task({ drop: true }) *loadUsage() {
-        const abortController = new AbortController();
-        const requestTimeout = setTimeout(() => abortController.abort(), 30000);
-
-        try {
-            // Pass the signal as request data; fetch.get options do not forward it.
-            this.usage = yield this.fetch.request('fleet-ops/settings/telematics-storage-usage?include_payload_counts=0', 'GET', { signal: abortController.signal });
-        } catch (error) {
-            this.notifications.serverError(abortController.signal.aborted ? new Error(this.intl.t('settings.telematics.usage-unavailable')) : error);
-        } finally {
-            clearTimeout(requestTimeout);
-            abortController.abort();
+    @action setUseDefaultEventRetention(enabled) {
+        this.useDefaultEventRetention = enabled;
+        if (enabled) {
+            this.eventRetentionDays = this.defaults.event_retention_days ?? this.eventRetentionDays;
         }
     }
 
-    /**
-     * Queue an immediate retention run for the current company, then refresh usage.
-     */
-    @task *runCleanup() {
-        try {
-            yield this.fetch.post('fleet-ops/settings/telematics-retention/run');
-            this.notifications.success(this.intl.t('settings.telematics.cleanup-queued'));
-            yield timeout(5000);
-            yield this.loadUsage.perform();
-        } catch (error) {
-            this.notifications.serverError(error);
+    @action setUseDefaultPositionRetention(enabled) {
+        this.useDefaultPositionRetention = enabled;
+        if (enabled) {
+            this.positionRetentionDays = this.defaults.position_retention_days ?? this.positionRetentionDays;
         }
     }
 
-    @action confirmRunCleanup() {
-        return this.modalsManager.confirm({
-            title: this.intl.t('settings.telematics.run-cleanup'),
-            body: this.intl.t('settings.telematics.run-cleanup-confirm'),
-            acceptButtonText: this.intl.t('settings.telematics.run-cleanup'),
-            acceptButtonIcon: 'broom',
-            onConfirm: () => this.runCleanup.perform(),
-        });
-    }
-
     applySettings(settings = {}) {
-        if (!settings) {
-            return;
-        }
-
         this.eventRetentionDays = settings.event_retention_days ?? this.eventRetentionDays;
-        this.eventCompactAfterDays = settings.event_compact_after_days ?? this.eventCompactAfterDays;
         this.positionRetentionDays = settings.position_retention_days ?? this.positionRetentionDays;
-        this.processedRetentionHours = settings.processed_retention_hours ?? this.processedRetentionHours;
-        this.quarantineRetentionDays = settings.quarantine_retention_days ?? this.quarantineRetentionDays;
-        this.syncRunRetentionDays = settings.sync_run_retention_days ?? this.syncRunRetentionDays;
-        this.logTelemetryActivity = settings.log_telemetry_activity ?? this.logTelemetryActivity;
+        this.useDefaultEventRetention = (settings.preferences?.event_retention_days ?? null) === null;
+        this.useDefaultPositionRetention = (settings.preferences?.position_retention_days ?? null) === null;
         this.defaults = settings.defaults ?? this.defaults;
-        this.limits = settings.limits ?? this.limits;
+        this.policy = settings.policy ?? this.policy;
     }
 
-    toInteger(value) {
-        const number = parseInt(value, 10);
-
-        return Number.isFinite(number) && number > 0 ? number : 0;
+    retentionPolicyHelp(maximum) {
+        return maximum > 0
+            ? this.intl.t('settings.telematics.history-policy-maximum', { days: maximum })
+            : this.intl.t('settings.telematics.history-policy-unlimited');
     }
 }
diff --git a/addon/templates/settings/telematics.hbs b/addon/templates/settings/telematics.hbs
index 8bda07cc3..3e08deaa2 100644
--- a/addon/templates/settings/telematics.hbs
+++ b/addon/templates/settings/telematics.hbs
@@ -5,134 +5,61 @@
         @icon="save"
         @text={{t "common.save-changes"}}
         @onClick={{perform this.saveSettings}}
-        @disabled={{this.saveSettings.isRunning}}
+        @disabled={{or this.saveSettings.isRunning this.getSettings.isRunning (not this.settingsLoaded)}}
         @isLoading={{or this.saveSettings.isRunning this.getSettings.isRunning}}
+        @permission="fleet-ops update telematics-settings"
     />
 </Layout::Section::Header>
 <Layout::Section::Body class="overflow-y-scroll-i h-full">
     <div class="container mx-auto">
         <div class="max-w-3xl my-10 mx-auto space-y-6">
-
             <InfoBlock @type="info" @icon="circle-info">
                 {{t "settings.telematics.intro"}}
             </InfoBlock>
 
-            {{! ── Device events ────────────────────────────────────────────── }}
             <ContentPanel @title={{t "settings.telematics.device-events"}} @open={{true}} @wrapperClass="bordered-classic">
-                <InputGroup @name={{t "settings.telematics.event-retention-days"}} @helpText={{t "settings.telematics.event-retention-days-help"}}>
-                    <Input @type="number" @value={{this.eventRetentionDays}} min="0" max="3650" class="w-full form-input" />
+                <InputGroup>
+                    <Toggle
+                        @label={{t "settings.telematics.use-system-default"}}
+                        @isToggled={{this.useDefaultEventRetention}}
+                        @onToggle={{this.setUseDefaultEventRetention}}
+                        @disabled={{not this.settingsLoaded}}
+                    />
                 </InputGroup>
-                <InputGroup @name={{t "settings.telematics.event-compact-after-days"}} @helpText={{t "settings.telematics.event-compact-after-days-help"}}>
-                    <Input @type="number" @value={{this.eventCompactAfterDays}} min="0" max="3650" class="w-full form-input" />
+                <InputGroup @name={{t "settings.telematics.event-retention-days"}} @helpText={{t "settings.telematics.event-retention-days-help"}}>
+                    <Input
+                        @type="number"
+                        @value={{this.eventRetentionDays}}
+                        min={{this.eventRetentionMinimum}}
+                        max={{this.eventRetentionMaximum}}
+                        disabled={{or this.useDefaultEventRetention (not this.settingsLoaded)}}
+                        class="w-full form-input"
+                    />
                 </InputGroup>
-                {{#if this.compactionIneffective}}
-                    <InfoBlock @type="warning" @icon="triangle-exclamation">
-                        {{t "settings.telematics.compaction-warning"}}
-                    </InfoBlock>
-                {{/if}}
+                <p class="text-xs text-gray-500 dark:text-gray-400">{{this.eventRetentionPolicyHelp}}</p>
             </ContentPanel>
 
-            {{! ── Positions ────────────────────────────────────────────────── }}
             <ContentPanel @title={{t "settings.telematics.positions"}} @open={{true}} @wrapperClass="bordered-classic">
-                <InputGroup @name={{t "settings.telematics.position-retention-days"}} @helpText={{t "settings.telematics.position-retention-days-help"}}>
-                    <Input @type="number" @value={{this.positionRetentionDays}} min="0" max="3650" class="w-full form-input" />
-                </InputGroup>
-            </ContentPanel>
-
-            {{! ── Delivery inbox & sync runs ───────────────────────────────── }}
-            <ContentPanel @title={{t "settings.telematics.inbox"}} @open={{true}} @wrapperClass="bordered-classic">
-                <InputGroup @name={{t "settings.telematics.processed-retention-hours"}} @helpText={{t "settings.telematics.processed-retention-hours-help"}}>
-                    <Input @type="number" @value={{this.processedRetentionHours}} min="0" max="720" class="w-full form-input" />
-                </InputGroup>
-                <InputGroup @name={{t "settings.telematics.quarantine-retention-days"}} @helpText={{t "settings.telematics.quarantine-retention-days-help"}}>
-                    <Input @type="number" @value={{this.quarantineRetentionDays}} min="0" max="365" class="w-full form-input" />
-                </InputGroup>
-                <InputGroup @name={{t "settings.telematics.sync-run-retention-days"}} @helpText={{t "settings.telematics.sync-run-retention-days-help"}}>
-                    <Input @type="number" @value={{this.syncRunRetentionDays}} min="0" max="365" class="w-full form-input" />
-                </InputGroup>
-            </ContentPanel>
-
-            {{! ── Activity logging ─────────────────────────────────────────── }}
-            <ContentPanel @title={{t "settings.telematics.activity-logging"}} @open={{true}} @wrapperClass="bordered-classic">
-                <Toggle
-                    @label={{t "settings.telematics.log-telemetry-activity"}}
-                    @helpText={{t "settings.telematics.log-telemetry-activity-help"}}
-                    @isToggled={{this.logTelemetryActivity}}
-                    @onToggle={{fn (mut this.logTelemetryActivity)}}
-                />
-            </ContentPanel>
-
-            {{! ── Storage usage ────────────────────────────────────────────── }}
-            <ContentPanel @title={{t "settings.telematics.storage-usage"}} @open={{true}} @wrapperClass="bordered-classic">
-                <div class="flex items-center justify-end gap-2 mb-3">
-                    <Button
-                        @size="xs"
-                        @icon="rotate"
-                        @text={{t "settings.telematics.refresh"}}
-                        @onClick={{perform this.loadUsage}}
-                        @disabled={{this.loadUsage.isRunning}}
-                        @isLoading={{this.loadUsage.isRunning}}
+                <InputGroup>
+                    <Toggle
+                        @label={{t "settings.telematics.use-system-default"}}
+                        @isToggled={{this.useDefaultPositionRetention}}
+                        @onToggle={{this.setUseDefaultPositionRetention}}
+                        @disabled={{not this.settingsLoaded}}
                     />
-                    <Button
-                        @type="danger"
-                        @size="xs"
-                        @icon="broom"
-                        @text={{t "settings.telematics.run-cleanup"}}
-                        @onClick={{this.confirmRunCleanup}}
-                        @disabled={{this.runCleanup.isRunning}}
-                        @isLoading={{this.runCleanup.isRunning}}
+                </InputGroup>
+                <InputGroup @name={{t "settings.telematics.position-retention-days"}} @helpText={{t "settings.telematics.position-retention-days-help"}}>
+                    <Input
+                        @type="number"
+                        @value={{this.positionRetentionDays}}
+                        min={{this.positionRetentionMinimum}}
+                        max={{this.positionRetentionMaximum}}
+                        disabled={{or this.useDefaultPositionRetention (not this.settingsLoaded)}}
+                        class="w-full form-input"
                     />
-                </div>
-                {{#if this.usageRows.length}}
-                    <div class="overflow-x-auto">
-                        <table class="w-full text-sm">
-                            <thead>
-                                <tr class="text-left text-xs uppercase text-gray-500 dark:text-gray-400">
-                                    <th class="py-2 pr-3">{{t "settings.telematics.table"}}</th>
-                                    <th class="py-2 pr-3 text-right">{{t "settings.telematics.rows"}}</th>
-                                    <th class="py-2 pr-3 text-right">{{t "settings.telematics.estimated-size"}}</th>
-                                    <th class="py-2 pl-6 text-left whitespace-nowrap">{{t "settings.telematics.oldest"}}</th>
-                                </tr>
-                            </thead>
-                            <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
-                                {{#each this.usageRows as |row|}}
-                                    <tr class="text-gray-800 dark:text-gray-100">
-                                        <td class="py-2 pr-3">
-                                            <div class="font-medium">{{row.label}}</div>
-                                            {{#if row.raw_payload_rows}}
-                                                <div class="text-xs text-gray-500 dark:text-gray-400">
-                                                    {{t "settings.telematics.raw-payload-rows" count=(format-number row.raw_payload_rows) compactable=(format-number row.compactable_rows)}}
-                                                </div>
-                                            {{/if}}
-                                        </td>
-                                        <td class="py-2 pr-3 text-right">
-                                            {{#if (eq row.rows null)}}
-                                                {{t "settings.telematics.not-available"}}
-                                            {{else if row.rows_estimated}}
-                                                {{t "settings.telematics.estimated-rows" count=(format-number row.rows)}}
-                                            {{else}}
-                                                {{format-number row.rows}}
-                                            {{/if}}
-                                        </td>
-                                        <td class="py-2 pr-3 text-right">{{#if (or row.estimated_bytes (eq row.estimated_bytes 0))}}{{format-bytes row.estimated_bytes}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
-                                        <td class="py-2 pl-6 text-left text-xs whitespace-nowrap">{{#if row.oldest}}{{row.oldest}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
-                                    </tr>
-                                {{/each}}
-                            </tbody>
-                        </table>
-                    </div>
-                    <p class="mt-3 text-xs text-gray-500 dark:text-gray-400">{{t "settings.telematics.space-reclaim-note"}}</p>
-                {{else if this.loadUsage.isRunning}}
-                    <div class="flex items-center justify-center py-8">
-                        <Spinner />
-                    </div>
-                {{else}}
-                    <div class="text-center py-8 text-sm text-gray-400 dark:text-gray-500">
-                        {{t "settings.telematics.usage-unavailable"}}
-                    </div>
-                {{/if}}
+                </InputGroup>
+                <p class="text-xs text-gray-500 dark:text-gray-400">{{this.positionRetentionPolicyHelp}}</p>
             </ContentPanel>
-
         </div>
     </div>
     <Spacer @height="200px" />
diff --git a/server/config/telemetry.php b/server/config/telemetry.php
index 2dd3ead6a..1a6cf8828 100644
--- a/server/config/telemetry.php
+++ b/server/config/telemetry.php
@@ -13,14 +13,17 @@
     'batch_size'                => env('TELEMATICS_BATCH_SIZE', 100),
     'max_payload_bytes'         => 2097152,
     'max_pending_deliveries'    => 10000,
-    // Retention defaults. Companies override these from Fleet-Ops > Settings > Telematics;
-    // administrators override the system defaults from the admin console. 0 keeps rows forever.
+    // Administrators control infrastructure retention and activity logging.
+    // Companies may choose event/position history retention within the maximums.
+    // A maximum of 0 imposes no cap and permits unlimited history (retention 0).
     'processed_retention_hours' => 24,
     'quarantine_retention_days' => 7,
     'sync_run_retention_days'   => 7,
     'event_retention_days'      => 30,
     'event_compact_after_days'  => 7,
     'position_retention_days'   => 90,
+    'max_event_retention_days'  => 0,
+    'max_position_retention_days' => 0,
     'log_telemetry_activity'    => false,
     'prune_batch_size'          => 1000,
     'prune_max_batches'         => 50,
diff --git a/server/src/Auth/Schemas/FleetOps.php b/server/src/Auth/Schemas/FleetOps.php
index 95cd81d73..8a652e2f0 100644
--- a/server/src/Auth/Schemas/FleetOps.php
+++ b/server/src/Auth/Schemas/FleetOps.php
@@ -230,7 +230,7 @@ class FleetOps
             'remove_actions' => ['delete', 'export', 'create'],
         ],
         [
-            'name'           => 'telematics-settings', // data retention and storage for telematics ingestion
+            'name'           => 'telematics-settings', // organization device event and position history preferences
             'action'         => [],
             'remove_actions' => ['export', 'create'],
         ],
@@ -439,7 +439,7 @@ class FleetOps
         ],
         [
             'name'        => 'TelematicsSettingsManager',
-            'description' => 'Policy for managing telematics data retention and storage settings.',
+            'description' => 'Policy for managing organization telematics history preferences.',
             'permissions' => [
                 'see extension',
                 '* telematics-settings',
@@ -547,7 +547,7 @@ class FleetOps
         ],
         [
             'name'        => 'Telematics Settings Manager',
-            'description' => 'Role responsible for managing telematics data retention and storage settings.',
+            'description' => 'Role responsible for managing organization telematics history preferences.',
             'policies'    => [
                 'TelematicsSettingsManager',
             ],
diff --git a/server/src/Http/Controllers/Internal/v1/SettingController.php b/server/src/Http/Controllers/Internal/v1/SettingController.php
index b7655c8af..529bc7749 100644
--- a/server/src/Http/Controllers/Internal/v1/SettingController.php
+++ b/server/src/Http/Controllers/Internal/v1/SettingController.php
@@ -42,6 +42,10 @@ public function __construct()
             'saveOrchestratorCardFields'              => 'update routing-settings',
             'getAdminTelematicsSettings'              => 'admin',
             'saveAdminTelematicsSettings'             => 'admin',
+            'getTelematicsSettings'                   => 'view telematics-settings',
+            'saveTelematicsSettings'                  => 'update telematics-settings',
+            'getTelematicsStorageUsage'               => 'admin',
+            'runTelematicsRetention'                  => 'admin',
         ]);
     }
 
@@ -678,7 +682,7 @@ protected function trackingProviderOptions(): array
     }
 
     /**
-     * Retrieve telematics data retention settings for the current company.
+     * Retrieve customer history preferences for the current company.
      *
      * Company values fall back to the system defaults (admin setting over
      * package config); the response carries both so the UI can show them.
@@ -687,29 +691,40 @@ protected function trackingProviderOptions(): array
      */
     public function getTelematicsSettings()
     {
-        $defaults = $this->telematicsDefaults();
-        $settings = RetentionPolicy::normalize((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, []), $defaults);
+        if (!$this->currentCompany()) {
+            return response()->error('No company session.', 401);
+        }
 
-        return response()->json(array_merge($settings, [
-            'defaults' => $defaults,
-            'limits'   => RetentionPolicy::LIMITS,
-        ]));
+        return response()->json($this->telematicsCompanySettings((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, [])));
     }
 
     /**
-     * Save telematics data retention settings for the current company.
+     * Save customer history preferences within the administrator's policy.
      *
      * @return \Illuminate\Http\JsonResponse
      */
     public function saveTelematicsSettings(Request $request)
     {
-        $settings = RetentionPolicy::normalize($request->only(RetentionPolicy::keys()), $this->telematicsDefaults());
-        $this->configureCompanySetting(RetentionPolicy::SETTING_KEY, $settings);
-        RetentionPolicy::flush($this->currentCompany()?->uuid);
+        $company = $this->currentCompany();
+        if (!$company) {
+            return response()->error('No company session.', 401);
+        }
+
+        $request->validate([
+            'event_retention_days'    => ['nullable', 'integer', 'min:0', 'max:3650'],
+            'position_retention_days' => ['nullable', 'integer', 'min:0', 'max:3650'],
+        ]);
 
-        return response()->json(array_merge($settings, [
+        $defaults    = $this->telematicsDefaults();
+        $preferences = RetentionPolicy::companyPreferences($request->only(RetentionPolicy::HISTORY_KEYS));
+        $effective   = RetentionPolicy::fromCompanyPreferences($preferences, $defaults)->toArray();
+        $preferences = array_intersect_key($effective, $preferences);
+        $this->configureCompanySetting(RetentionPolicy::SETTING_KEY, $preferences);
+        RetentionPolicy::flush($company->uuid);
+
+        return response()->json(array_merge($this->telematicsCompanySettings($preferences, $defaults), [
             'status'  => 'ok',
-            'message' => 'Telematics settings successfully saved.',
+            'message' => 'Telematics history preferences successfully saved.',
         ]));
     }
 
@@ -732,8 +747,12 @@ public function getAdminTelematicsSettings()
      */
     public function saveAdminTelematicsSettings(Request $request)
     {
-        $config   = array_intersect_key((array) config('telematics.telemetry', []), RetentionPolicy::FALLBACKS);
-        $settings = RetentionPolicy::normalize($request->only(RetentionPolicy::keys()), RetentionPolicy::normalize($config, RetentionPolicy::FALLBACKS));
+        $request->validate([
+            'max_event_retention_days'    => ['sometimes', 'integer', 'min:0', 'max:3650'],
+            'max_position_retention_days' => ['sometimes', 'integer', 'min:0', 'max:3650'],
+        ]);
+
+        $settings = RetentionPolicy::normalize($request->only(RetentionPolicy::keys()), $this->telematicsDefaults());
         $this->configureSetting(RetentionPolicy::SETTING_KEY, $settings);
         RetentionPolicy::flush();
 
@@ -772,10 +791,10 @@ public function getTelematicsStorageUsage()
         // and omitted if they cannot be counted within the database deadline.
         if (request()->boolean('include_payload_counts', false)) {
             try {
-                $policy          = RetentionPolicy::normalize((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, []), $this->telematicsDefaults());
+                $policy          = RetentionPolicy::fromCompanyPreferences((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, []), $this->telematicsDefaults());
                 $rawPayloadRows  = $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload'));
-                $compactAfter    = (int) $policy['event_compact_after_days'];
-                $compactableRows = $compactAfter > 0
+                $compactAfter    = (int) $policy->get('event_compact_after_days');
+                $compactableRows = $policy->compactsEvents()
                     ? $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload')->where('created_at', '<', now()->subDays($compactAfter)->toDateTimeString()))
                     : 0;
 
@@ -797,6 +816,7 @@ public function getTelematicsStorageUsage()
 
         return response()->json([
             'tables'       => $tables,
+            'company'      => ['uuid' => $company->uuid, 'name' => $company->name ?? null],
             'generated_at' => now()->toISOString(),
         ]);
     }
@@ -831,6 +851,26 @@ protected function telematicsDefaults(): array
         return RetentionPolicy::normalize((array) $this->lookupSetting(RetentionPolicy::SETTING_KEY, []), RetentionPolicy::normalize($config, RetentionPolicy::FALLBACKS));
     }
 
+    /**
+     * Customer responses expose history choices and constraints, never internal
+     * ingestion, cleanup, storage or activity logging configuration.
+     */
+    protected function telematicsCompanySettings(array $stored, ?array $defaults = null): array
+    {
+        $defaults    = $defaults ?? $this->telematicsDefaults();
+        $history     = array_flip(RetentionPolicy::HISTORY_KEYS);
+        $preferences = RetentionPolicy::companyPreferences($stored);
+        $effective   = RetentionPolicy::fromCompanyPreferences($preferences, $defaults)->toArray();
+        $inherited   = RetentionPolicy::fromCompanyPreferences([], $defaults)->toArray();
+
+        return array_merge(array_intersect_key($effective, $history), [
+            'preferences' => array_merge(array_fill_keys(RetentionPolicy::HISTORY_KEYS, null), $preferences),
+            'defaults'    => array_intersect_key($inherited, $history),
+            'policy'      => array_intersect_key($defaults, array_flip(array_values(RetentionPolicy::MAXIMUMS))),
+            'limits'      => array_intersect_key(RetentionPolicy::LIMITS, $history),
+        ]);
+    }
+
     protected function tableUsage(string $table, \Closure $scope, string $ageColumn): array
     {
         if (!in_array(DB::connection()->getDriverName(), ['mysql', 'mariadb'], true)) {
diff --git a/server/src/Support/Telematics/Retention/RetentionPolicy.php b/server/src/Support/Telematics/Retention/RetentionPolicy.php
index a693112e4..0e67fe53f 100644
--- a/server/src/Support/Telematics/Retention/RetentionPolicy.php
+++ b/server/src/Support/Telematics/Retention/RetentionPolicy.php
@@ -8,9 +8,9 @@
 /**
  * Resolves how long a company keeps telematics data.
  *
- * Values resolve in three layers: the package config (`telematics.telemetry`),
- * the system-wide admin setting, then the company setting. Every numeric value
- * is clamped to its limits; zero always means "keep forever".
+ * Administrators control retention policy and infrastructure settings. Companies
+ * may override event and position history retention within the system maximums.
+ * Zero means "keep forever" only when the administrator has not set a maximum.
  */
 final class RetentionPolicy
 {
@@ -19,27 +19,39 @@ final class RetentionPolicy
     /** Cached policies are refreshed after this many seconds so saved settings reach long-lived workers. */
     public const CACHE_TTL_SECONDS = 60;
 
+    public const HISTORY_KEYS = ['event_retention_days', 'position_retention_days'];
+
+    public const MAXIMUMS = [
+        'event_retention_days'    => 'max_event_retention_days',
+        'position_retention_days' => 'max_position_retention_days',
+    ];
+
     /** @var array<string, array{0: int, 1: int}> */
     public const LIMITS = [
-        'event_retention_days'      => [1, 3650],
-        'event_compact_after_days'  => [1, 3650],
-        'position_retention_days'   => [1, 3650],
-        'processed_retention_hours' => [1, 720],
-        'quarantine_retention_days' => [1, 365],
-        'sync_run_retention_days'   => [1, 365],
+        'event_retention_days'        => [1, 3650],
+        'event_compact_after_days'    => [1, 3650],
+        'position_retention_days'     => [1, 3650],
+        'processed_retention_hours'   => [1, 720],
+        'quarantine_retention_days'   => [1, 365],
+        'sync_run_retention_days'     => [1, 365],
+        'max_event_retention_days'    => [1, 3650],
+        'max_position_retention_days' => [1, 3650],
     ];
 
     public const BOOLEANS = ['log_telemetry_activity'];
 
     /** Used when neither config nor settings provide a value. */
     public const FALLBACKS = [
-        'event_retention_days'      => 30,
-        'event_compact_after_days'  => 7,
-        'position_retention_days'   => 90,
-        'processed_retention_hours' => 24,
-        'quarantine_retention_days' => 7,
-        'sync_run_retention_days'   => 7,
-        'log_telemetry_activity'    => false,
+        'event_retention_days'        => 30,
+        'event_compact_after_days'    => 7,
+        'position_retention_days'     => 90,
+        'processed_retention_hours'   => 24,
+        'quarantine_retention_days'   => 7,
+        'sync_run_retention_days'     => 7,
+        // A separate, opt-in cap preserves existing history when upgrading.
+        'max_event_retention_days'    => 0,
+        'max_position_retention_days' => 0,
+        'log_telemetry_activity'      => false,
     ];
 
     /**
@@ -85,7 +97,7 @@ public static function defaults(): array
     public static function forCompany(?string $companyUuid): self
     {
         if (!$companyUuid) {
-            return new self(self::defaults());
+            return self::fromCompanyPreferences([]);
         }
 
         $cached = self::$companyCache[$companyUuid] ?? null;
@@ -94,16 +106,48 @@ public static function forCompany(?string $companyUuid): self
         }
 
         $defaults = self::defaults();
-        $policy   = new self(self::normalize(self::resolve('company', $companyUuid), $defaults));
+        $policy   = self::fromCompanyPreferences(self::resolve('company', $companyUuid), $defaults);
 
-        self::$companyCache[$companyUuid] = ['policy' => $policy, 'expires' => time() + self::CACHE_TTL_SECONDS];
+        // A policy must not extend the lifetime of system defaults it inherited.
+        self::$companyCache[$companyUuid] = ['policy' => $policy, 'expires' => self::$defaultsCache['expires']];
 
         return $policy;
     }
 
     public static function fromArray(array $values, ?array $base = null): self
     {
-        return new self(self::normalize($values, $base ?? self::FALLBACKS));
+        return new self(self::applyMaximums(self::normalize($values, $base ?? self::FALLBACKS)));
+    }
+
+    /**
+     * Keep only explicit, valid customer history preferences. Missing or null
+     * values remain absent so later changes to the system defaults are inherited.
+     */
+    public static function companyPreferences(array $input): array
+    {
+        $preferences = [];
+        foreach (self::HISTORY_KEYS as $key) {
+            $value = $input[$key] ?? null;
+            if ($value === null || $value === '' || is_bool($value) || filter_var($value, FILTER_VALIDATE_INT) === false) {
+                continue;
+            }
+
+            [$min, $max]       = self::LIMITS[$key];
+            $value             = (int) $value;
+            $preferences[$key] = $value === 0 ? 0 : max($min, min($max, $value));
+        }
+
+        return $preferences;
+    }
+
+    /**
+     * Legacy company overrides for ingestion, payloads and logging are ignored.
+     * Apply caps after inheritance so unlimited or overly long defaults cannot
+     * bypass an administrator's maximum either.
+     */
+    public static function fromCompanyPreferences(array $preferences, ?array $defaults = null): self
+    {
+        return self::fromArray(self::companyPreferences($preferences), $defaults ?? self::defaults());
     }
 
     /**
@@ -182,6 +226,18 @@ public function toArray(): array
         return $this->values;
     }
 
+    private static function applyMaximums(array $values): array
+    {
+        foreach (self::MAXIMUMS as $key => $maximumKey) {
+            $maximum = $values[$maximumKey];
+            if ($maximum > 0 && ($values[$key] === 0 || $values[$key] > $maximum)) {
+                $values[$key] = $maximum;
+            }
+        }
+
+        return $values;
+    }
+
     private static function pick(array $input, array $base, string $key): mixed
     {
         if (array_key_exists($key, $input) && $input[$key] !== null && $input[$key] !== '') {
diff --git a/server/src/Support/Telematics/Retention/TelemetryActivity.php b/server/src/Support/Telematics/Retention/TelemetryActivity.php
index adbaccab1..57072710d 100644
--- a/server/src/Support/Telematics/Retention/TelemetryActivity.php
+++ b/server/src/Support/Telematics/Retention/TelemetryActivity.php
@@ -6,7 +6,7 @@
 
 /**
  * Runs telemetry-driven writes with activity logging suppressed unless the
- * company opted in. Every poll saves the device, event, position and vehicle,
+ * system administrator enabled it. Every poll saves the device, event, position and vehicle,
  * which otherwise writes several activity rows per device per minute.
  */
 final class TelemetryActivity
diff --git a/server/tests/SettingControllerContractsTest.php b/server/tests/SettingControllerContractsTest.php
index 11f9e13c4..047172318 100644
--- a/server/tests/SettingControllerContractsTest.php
+++ b/server/tests/SettingControllerContractsTest.php
@@ -497,21 +497,21 @@ function fleetopsJsonPayload(mixed $response): array
         ->and($defaults['leafletDarkTileUrl'])->toBe('');
 });
 
-test('telematics settings layer package config, admin defaults and company overrides with clamping', function () {
+test('telematics settings expose only customer history preferences within administrator limits', function () {
     config(['telematics.telemetry' => ['event_retention_days' => 45, 'processed_retention_hours' => 48, 'log_telemetry_activity' => false, 'poll_queue' => 'default']]);
     $controller                                                    = new FleetOpsSettingControllerProbe();
-    $controller->settings['fleet-ops.telematics-settings']         = ['position_retention_days' => 120, 'event_retention_days' => 99999];
+    $controller->company                                           = (object) ['uuid' => 'company-1'];
+    $controller->settings['fleet-ops.telematics-settings']         = ['position_retention_days' => 120, 'event_retention_days' => 99999, 'max_event_retention_days' => 60];
     $controller->companySettings['fleet-ops.telematics-settings']  = ['event_compact_after_days' => 3, 'log_telemetry_activity' => '1'];
 
     $settings = fleetopsJsonPayload($controller->getTelematicsSettings());
-    expect($settings['event_retention_days'])->toBe(3650)
+    expect($settings['event_retention_days'])->toBe(60)
         ->and($settings['position_retention_days'])->toBe(120)
-        ->and($settings['event_compact_after_days'])->toBe(3)
-        ->and($settings['processed_retention_hours'])->toBe(48)
-        ->and($settings['log_telemetry_activity'])->toBeTrue()
-        ->and($settings['defaults']['event_compact_after_days'])->toBe(7)
-        ->and($settings['defaults']['log_telemetry_activity'])->toBeFalse()
-        ->and($settings['limits'])->toBe(Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy::LIMITS);
+        ->and($settings)->not->toHaveKeys(['event_compact_after_days', 'processed_retention_hours', 'log_telemetry_activity'])
+        ->and($settings['preferences'])->toBe(['event_retention_days' => null, 'position_retention_days' => null])
+        ->and($settings['defaults'])->toBe(['event_retention_days' => 60, 'position_retention_days' => 120])
+        ->and($settings['policy'])->toBe(['max_event_retention_days' => 60, 'max_position_retention_days' => 0])
+        ->and($settings['limits'])->toBe(['event_retention_days' => [1, 3650], 'position_retention_days' => [1, 3650]]);
 
     $saved = fleetopsJsonPayload($controller->saveTelematicsSettings(new Request([
         'event_retention_days'      => '0',
@@ -521,29 +521,51 @@ function fleetopsJsonPayload(mixed $response): array
         'unexpected'                => 'ignored',
     ])));
     expect($saved['status'])->toBe('ok')
-        ->and($saved['event_retention_days'])->toBe(0)
-        ->and($saved['event_compact_after_days'])->toBe(1)
-        ->and($saved['processed_retention_hours'])->toBe(720)
+        ->and($saved['event_retention_days'])->toBe(60)
         ->and($saved['position_retention_days'])->toBe(120)
-        ->and($saved['log_telemetry_activity'])->toBeFalse()
-        ->and($controller->configuredCompany['fleet-ops.telematics-settings'])->not->toHaveKey('unexpected')
-        ->and($controller->configuredCompany['fleet-ops.telematics-settings']['quarantine_retention_days'])->toBe(7);
+        ->and($saved['preferences'])->toBe(['event_retention_days' => 60, 'position_retention_days' => null])
+        ->and($saved)->not->toHaveKeys(['event_compact_after_days', 'processed_retention_hours', 'log_telemetry_activity'])
+        ->and($controller->configuredCompany['fleet-ops.telematics-settings'])->toBe(['event_retention_days' => 60]);
 
     $admin = fleetopsJsonPayload($controller->getAdminTelematicsSettings());
-    expect($admin['event_retention_days'])->toBe(3650)->and($admin['limits'])->toHaveKey('sync_run_retention_days');
-
-    $savedAdmin = fleetopsJsonPayload($controller->saveAdminTelematicsSettings(new Request(['event_retention_days' => 60, 'sync_run_retention_days' => 0])));
+    expect($admin['event_retention_days'])->toBe(3650)
+        ->and($admin['limits'])->toHaveKeys(['sync_run_retention_days', 'max_event_retention_days', 'max_position_retention_days'])
+        ->and($admin['log_telemetry_activity'])->toBeFalse();
+
+    $savedAdmin = fleetopsJsonPayload($controller->saveAdminTelematicsSettings(new Request([
+        'event_retention_days'        => 60,
+        'sync_run_retention_days'     => 0,
+        'max_event_retention_days'    => 90,
+        'max_position_retention_days' => 45,
+        'log_telemetry_activity'      => true,
+    ])));
     expect($savedAdmin['event_retention_days'])->toBe(60)
         ->and($savedAdmin['sync_run_retention_days'])->toBe(0)
         ->and($savedAdmin['processed_retention_hours'])->toBe(48)
-        ->and($controller->configured['fleet-ops.telematics-settings']['position_retention_days'])->toBe(90);
+        ->and($savedAdmin['max_event_retention_days'])->toBe(90)
+        ->and($savedAdmin['max_position_retention_days'])->toBe(45)
+        ->and($savedAdmin['log_telemetry_activity'])->toBeTrue()
+        ->and($controller->configured['fleet-ops.telematics-settings']['position_retention_days'])->toBe(120);
+
+    $partialAdmin = fleetopsJsonPayload($controller->saveAdminTelematicsSettings(new Request(['log_telemetry_activity' => false])));
+    expect($partialAdmin['max_event_retention_days'])->toBe(90)
+        ->and($partialAdmin['max_position_retention_days'])->toBe(45);
+
+    $inherited = fleetopsJsonPayload($controller->saveTelematicsSettings(new Request(['event_retention_days' => null, 'position_retention_days' => null])));
+    expect($inherited['event_retention_days'])->toBe(60)
+        ->and($inherited['position_retention_days'])->toBe(45)
+        ->and($inherited['preferences'])->toBe(['event_retention_days' => null, 'position_retention_days' => null])
+        ->and($controller->configuredCompany['fleet-ops.telematics-settings'])->toBe([]);
     config(['telematics.telemetry' => []]);
 });
 
-test('telematics storage usage and cleanup require a company session', function () {
+test('telematics customer settings, storage usage and cleanup require a company session', function () {
     $controller = new FleetOpsSettingControllerProbe();
-    expect($controller->getTelematicsStorageUsage()->getStatusCode())->toBe(401)
+    expect($controller->getTelematicsSettings()->getStatusCode())->toBe(401)
+        ->and($controller->saveTelematicsSettings(new Request())->getStatusCode())->toBe(401)
+        ->and($controller->getTelematicsStorageUsage()->getStatusCode())->toBe(401)
         ->and($controller->runTelematicsRetention()->getStatusCode())->toBe(401)
+        ->and($controller->configuredCompany)->toBe([])
         ->and($controller->pruned)->toBe([]);
 });
 
@@ -571,12 +593,13 @@ function fleetopsJsonPayload(mixed $response): array
             ->and($usage['tables']['positions'])->toBe(['rows' => 40, 'oldest' => null, 'avg_row_bytes' => 700, 'estimated_bytes' => 28000])
             ->and($usage['tables']['telematic_deliveries'])->toBe(['rows' => 6, 'oldest' => null])
             ->and($usage['tables']['telematic_sync_runs']['rows'])->toBe(3)
+            ->and($usage['company'])->toBe(['uuid' => 'company-1', 'name' => null])
             ->and($usage['generated_at'])->toBe('2026-09-23T12:00:00.000000Z')
             ->and($controller->countScopes)->toBe(['device_events', 'positions', 'telematic_deliveries', 'telematic_sync_runs', 'device_events', 'device_events']);
 
         // Without connections the inbox tables are reported empty; compaction disabled skips the backlog count.
         $controller->telematicUuids                                    = [];
-        $controller->companySettings['fleet-ops.telematics-settings']  = ['event_compact_after_days' => 0];
+        $controller->settings['fleet-ops.telematics-settings']         = ['event_compact_after_days' => 0];
         $controller->countScopes                                       = [];
         $usage                                                         = fleetopsJsonPayload($controller->getTelematicsStorageUsage());
         expect($usage['tables']['telematic_deliveries'])->toBe(['rows' => 0, 'oldest' => null])
diff --git a/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php b/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php
index 24e91765e..00b24b480 100644
--- a/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php
+++ b/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php
@@ -4,8 +4,8 @@
 use Illuminate\Support\Carbon;
 
 /**
- * RetentionPolicy layers package config, the admin setting and the company
- * setting, clamps every value, and caches per company for long-lived workers.
+ * RetentionPolicy combines administrator policy with allowed company history
+ * preferences, enforces maximums, and caches policies for long-lived workers.
  */
 function fleetopsRetentionResolver(array $system, array $company, ?array &$calls = null): void
 {
@@ -34,13 +34,15 @@ function fleetopsRetentionResolver(array $system, array $company, ?array &$calls
 test('defaults come from package config, overridden by the admin setting, with everything clamped', function () {
     fleetopsRetentionResolver([], []);
     expect(RetentionPolicy::defaults())->toBe([
-        'event_retention_days'      => 45,
-        'event_compact_after_days'  => 7,
-        'position_retention_days'   => 90,
-        'processed_retention_hours' => 48,
-        'quarantine_retention_days' => 7,
-        'sync_run_retention_days'   => 7,
-        'log_telemetry_activity'    => true,
+        'event_retention_days'        => 45,
+        'event_compact_after_days'    => 7,
+        'position_retention_days'     => 90,
+        'processed_retention_hours'   => 48,
+        'quarantine_retention_days'   => 7,
+        'sync_run_retention_days'     => 7,
+        'max_event_retention_days'    => 0,
+        'max_position_retention_days' => 0,
+        'log_telemetry_activity'      => true,
     ]);
 
     RetentionPolicy::flush();
@@ -71,7 +73,7 @@ function fleetopsRetentionResolver(array $system, array $company, ?array &$calls
     expect($policy->get('event_retention_days'))->toBe(10)
         ->and($policy->get('position_retention_days'))->toBe(30)
         ->and($policy->get('processed_retention_hours'))->toBe(48)
-        ->and($policy->logsTelemetryActivity())->toBeFalse()
+        ->and($policy->logsTelemetryActivity())->toBeTrue()
         ->and($policy->toArray())->toHaveKeys(RetentionPolicy::keys())
         ->and(RetentionPolicy::forCompany('company-1'))->toBe($policy)
         ->and(RetentionPolicy::forCompany(null)->toArray())->toBe(RetentionPolicy::defaults())
@@ -88,6 +90,52 @@ function fleetopsRetentionResolver(array $system, array $company, ?array &$calls
     expect(array_column($calls, 0))->toBe(['system', 'company', 'company', 'company', 'system', 'company']);
 });
 
+test('company history respects admin maximums and cannot override infrastructure or logging', function () {
+    fleetopsRetentionResolver([
+        'event_retention_days'        => 0,
+        'position_retention_days'     => 90,
+        'max_event_retention_days'    => 30,
+        'max_position_retention_days' => 45,
+        'log_telemetry_activity'      => false,
+    ], [
+        'company-1' => [
+            'event_retention_days'        => 0,
+            'position_retention_days'     => 120,
+            'max_event_retention_days'    => 0,
+            'max_position_retention_days' => 0,
+            'event_compact_after_days'    => 0,
+            'processed_retention_hours'   => 0,
+            'quarantine_retention_days'   => 0,
+            'sync_run_retention_days'     => 0,
+            'log_telemetry_activity'      => true,
+        ],
+        'company-2' => ['event_retention_days' => 5, 'position_retention_days' => 15],
+    ]);
+
+    $policy = RetentionPolicy::forCompany('company-1');
+    expect($policy->get('event_retention_days'))->toBe(30)
+        ->and($policy->get('position_retention_days'))->toBe(45)
+        ->and($policy->get('event_compact_after_days'))->toBe(7)
+        ->and($policy->get('processed_retention_hours'))->toBe(48)
+        ->and($policy->get('quarantine_retention_days'))->toBe(7)
+        ->and($policy->get('sync_run_retention_days'))->toBe(7)
+        ->and($policy->logsTelemetryActivity())->toBeFalse()
+        ->and(RetentionPolicy::forCompany('company-2')->get('event_retention_days'))->toBe(5)
+        ->and(RetentionPolicy::forCompany('company-2')->get('position_retention_days'))->toBe(15)
+        ->and(RetentionPolicy::forCompany('inherited')->get('event_retention_days'))->toBe(30)
+        ->and(RetentionPolicy::forCompany('inherited')->get('position_retention_days'))->toBe(45)
+        ->and(RetentionPolicy::forCompany(null)->get('event_retention_days'))->toBe(30);
+});
+
+test('unconfigured maximums preserve unlimited history and null preferences inherit defaults', function () {
+    fleetopsRetentionResolver([], ['company-1' => ['event_retention_days' => 0, 'position_retention_days' => null]]);
+
+    expect(RetentionPolicy::forCompany('company-1')->get('event_retention_days'))->toBe(0)
+        ->and(RetentionPolicy::forCompany('company-1')->get('position_retention_days'))->toBe(90)
+        ->and(RetentionPolicy::companyPreferences(['event_retention_days' => 'invalid', 'position_retention_days' => false]))->toBe([])
+        ->and(RetentionPolicy::companyPreferences(['event_retention_days' => null, 'position_retention_days' => '', 'log_telemetry_activity' => true]))->toBe([]);
+});
+
 test('cutoffs, compaction and deletion rules follow the clamped values', function () {
     Carbon::setTestNow('2026-09-23 12:00:00 UTC');
 
diff --git a/server/tests/Unit/Support/Telematics/Retention/TelemetryActivityTest.php b/server/tests/Unit/Support/Telematics/Retention/TelemetryActivityTest.php
index e4c24e926..ff1e69a05 100644
--- a/server/tests/Unit/Support/Telematics/Retention/TelemetryActivityTest.php
+++ b/server/tests/Unit/Support/Telematics/Retention/TelemetryActivityTest.php
@@ -5,7 +5,7 @@
 use Spatie\Activitylog\ActivityLogger;
 
 /**
- * Telemetry writes bypass the activity log unless the company opted in, and
+ * Telemetry writes bypass the activity log unless an administrator enabled it, and
  * still run when no activity logger is available.
  */
 function fleetopsTelemetryActivityLogger(): ActivityLogger
@@ -40,16 +40,24 @@ public function withoutLogs(Closure $callback): mixed
     app()->forgetInstance(ActivityLogger::class);
 });
 
-test('telemetry activity is suppressed by default and logged when a company opts in', function () {
+test('telemetry activity follows the system policy and ignores legacy company overrides', function () {
     RetentionPolicy::$settingsResolver = fn (string $scope, string $key, mixed $default, ?string $company) => $company === 'verbose' ? ['log_telemetry_activity' => true] : [];
     $logger                            = fleetopsTelemetryActivityLogger();
 
     expect(TelemetryActivity::run('quiet', fn () => 'saved'))->toBe('saved')
         ->and($logger->suppressed)->toBe(1)
+        ->and(TelemetryActivity::run('verbose', fn () => 'saved'))->toBe('saved')
+        ->and($logger->suppressed)->toBe(2)
+        ->and(TelemetryActivity::run(null, fn () => 'system'))->toBe('system')
+        ->and($logger->suppressed)->toBe(3);
+
+    RetentionPolicy::flush();
+    RetentionPolicy::$settingsResolver = fn (string $scope) => ['log_telemetry_activity' => $scope === 'system'];
+
+    expect(TelemetryActivity::run('quiet', fn () => 'logged'))->toBe('logged')
         ->and(TelemetryActivity::run('verbose', fn () => 'logged'))->toBe('logged')
-        ->and($logger->suppressed)->toBe(1)
         ->and(TelemetryActivity::run(null, fn () => 'system'))->toBe('system')
-        ->and($logger->suppressed)->toBe(2);
+        ->and($logger->suppressed)->toBe(3);
 });
 
 test('telemetry writes still run when the activity logger cannot be resolved', function () {
diff --git a/translations/en-us.yaml b/translations/en-us.yaml
index ccffd2dbc..2d7c0ebe1 100644
--- a/translations/en-us.yaml
+++ b/translations/en-us.yaml
@@ -2726,7 +2726,10 @@ route-list:
 settings:
     telematics:
         telematics-settings: Telematics Settings
-        intro: Configure telematics data retention and activity logging for your organization. These values override the system defaults managed by your administrator. A retention value of 0 keeps records forever.
+        intro: Choose how long your organization keeps device events and position history within the limits set by your system administrator.
+        use-system-default: Use system default
+        history-policy-maximum: "Your administrator allows up to {days} days of history. Unlimited retention is not available."
+        history-policy-unlimited: Your administrator allows unlimited history. Set the retention period to 0 to keep history forever.
         device-events: Device Events Retention
         event-retention-days: Keep device events for (days)
         event-retention-days-help: Events older than this are permanently deleted. Applies to telemetry updates and provider alerts alike.
@@ -2756,10 +2759,10 @@ settings:
         raw-payload-rows: "{count} rows still carry raw payloads, {compactable} eligible for compaction now"
         refresh: Refresh
         run-cleanup: Run cleanup now
-        run-cleanup-confirm: This queues a retention run for your organization using the rules above. Rows outside the retention windows are permanently deleted and cannot be recovered. Continue?
-        cleanup-queued: Telematics cleanup has been queued. Usage refreshes shortly.
+        run-cleanup-confirm: This queues cleanup for the organization currently selected in Console, using the saved system policy and its effective history preferences. Expired records are permanently deleted and cannot be recovered. Continue?
+        cleanup-queued: Telematics cleanup has been queued for the selected organization. Usage refreshes shortly.
         usage-unavailable: Storage usage could not be loaded. Select Refresh to try again.
-        space-reclaim-note: Row counts marked as estimated use database statistics for your organization. Sizes are estimates from average row length. Deleting records frees space for reuse within the database; physical disk usage may not decrease immediately.
+        space-reclaim-note: Usage applies to the organization currently selected in Console. Row counts marked as estimated use that organization's database query statistics. Sizes use shared-table average row lengths. Deleting records frees space for reuse within the database; physical disk usage may not decrease immediately.
         settings-saved: Telematics settings saved.
         tables:
             device_events: Device events

From 901d73401f9555a9d691391fcf1554f6fa6d2a6b Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 15:23:49 +0800
Subject: [PATCH 16/24] fix: persist telematics policy limits and clean up
 system-wide

---
 .../components/admin/telematics-settings.hbs  |   5 +-
 addon/components/admin/telematics-settings.js |  25 ++-
 addon/controllers/settings/telematics.js      |  22 +-
 addon/routes/settings/telematics.js           |   5 +
 addon/templates/settings/telematics.hbs       |   8 +-
 docs/AFAQY.md                                 |   2 +-
 docs/TELEMATICS_QUEUES.md                     |   2 +-
 docs/TELEMETRY_ARCHITECTURE.md                |  34 ++-
 .../Console/Commands/PruneTelematicsData.php  |  20 +-
 .../Internal/v1/SettingController.php         | 204 ++++++++++++------
 .../Jobs/DispatchTelematicsRetentionJobs.php  |  70 ++++++
 server/src/Jobs/PruneTelematicsDataJob.php    |  25 ++-
 .../Telematics/Retention/RetentionPolicy.php  |  12 ++
 .../tests/SettingControllerContractsTest.php  | 204 ++++++++++++------
 .../PruneTelematicsDataCommandTest.php        |  28 +++
 .../DispatchTelematicsRetentionJobsTest.php   |  57 +++++
 .../Unit/Jobs/PruneTelematicsDataJobTest.php  |  14 +-
 .../Retention/RetentionPolicyTest.php         |  12 ++
 translations/en-us.yaml                       |  12 +-
 19 files changed, 588 insertions(+), 173 deletions(-)
 create mode 100644 server/src/Jobs/DispatchTelematicsRetentionJobs.php
 create mode 100644 server/tests/Unit/Jobs/DispatchTelematicsRetentionJobsTest.php

diff --git a/addon/components/admin/telematics-settings.hbs b/addon/components/admin/telematics-settings.hbs
index a39646d6c..ff6c3bffe 100644
--- a/addon/components/admin/telematics-settings.hbs
+++ b/addon/components/admin/telematics-settings.hbs
@@ -69,8 +69,7 @@
 
     <ContentPanel @title={{t "settings.telematics.storage-usage"}} @open={{true}} @wrapperClass="bordered-classic">
         <p class="mb-3 text-sm text-gray-600 dark:text-gray-300">
-            Storage diagnostics and manual cleanup apply only to the currently selected Console organization{{#if this.usage.company.name}}: <strong>{{this.usage.company.name}}</strong>{{/if}}.
-            Cleanup uses the saved system policy and the organization's history preferences within that policy.
+            Storage usage includes telematics data across all organizations. Cleanup applies system-wide, using the saved system policy and each organization's history preferences within that policy.
         </p>
         <div class="flex items-center justify-end gap-2 mb-3">
             <Button
@@ -87,7 +86,7 @@
                 @icon="broom"
                 @text={{t "settings.telematics.run-cleanup"}}
                 @onClick={{this.confirmRunCleanup}}
-                @disabled={{or this.runCleanup.isRunning this.loadSettings.isRunning (not this.settingsLoaded)}}
+                @disabled={{or this.runCleanup.isRunning this.loadSettings.isRunning this.saveSettings.isRunning (not this.settingsLoaded)}}
                 @isLoading={{this.runCleanup.isRunning}}
             />
         </div>
diff --git a/addon/components/admin/telematics-settings.js b/addon/components/admin/telematics-settings.js
index b628bccf7..37db5c303 100644
--- a/addon/components/admin/telematics-settings.js
+++ b/addon/components/admin/telematics-settings.js
@@ -5,8 +5,7 @@ import { action } from '@ember/object';
 import { task, timeout } from 'ember-concurrency';
 
 /**
- * System-wide telematics policy and operational controls. Storage diagnostics
- * and manual cleanup are scoped to the current Console organization.
+ * System-wide telematics policy, storage diagnostics and operational controls.
  */
 export default class AdminTelematicsSettingsComponent extends Component {
     @service fetch;
@@ -55,14 +54,18 @@ export default class AdminTelematicsSettingsComponent extends Component {
         }
     }
 
-    /** Load storage usage for the current Console organization. */
+    /** Load system-wide storage usage across all organizations. */
     @task({ drop: true }) *loadUsage() {
         const abortController = new AbortController();
         const requestTimeout = setTimeout(() => abortController.abort(), 30000);
 
         try {
             // Pass the signal as request data; fetch.get options do not forward it.
-            this.usage = yield this.fetch.request('fleet-ops/settings/telematics-storage-usage?include_payload_counts=0', 'GET', { signal: abortController.signal });
+            const usage = yield this.fetch.request('fleet-ops/settings/telematics-storage-usage?include_payload_counts=0', 'GET', { signal: abortController.signal });
+            if (usage?.scope !== 'system') {
+                throw new Error(this.intl.t('settings.telematics.usage-unavailable'));
+            }
+            this.usage = usage;
         } catch (error) {
             this.notifications.serverError(abortController.signal.aborted ? new Error(this.intl.t('settings.telematics.usage-unavailable')) : error);
         } finally {
@@ -71,10 +74,13 @@ export default class AdminTelematicsSettingsComponent extends Component {
         }
     }
 
-    /** Queue cleanup for the current organization using the saved policy. */
+    /** Queue cleanup for all organizations using the saved policy. */
     @task({ drop: true }) *runCleanup() {
         try {
-            yield this.fetch.post('fleet-ops/settings/telematics-retention/run');
+            const cleanup = yield this.fetch.post('fleet-ops/settings/telematics-retention/run');
+            if (cleanup?.scope !== 'system') {
+                throw new Error(this.intl.t('settings.telematics.cleanup-unavailable'));
+            }
             this.notifications.success(this.intl.t('settings.telematics.cleanup-queued'));
             yield timeout(5000);
             yield this.loadUsage.perform();
@@ -116,8 +122,11 @@ export default class AdminTelematicsSettingsComponent extends Component {
     }
 
     applySettings(settings = {}) {
-        if (!settings) {
-            return;
+        if (
+            !Object.prototype.hasOwnProperty.call(settings ?? {}, 'max_event_retention_days') ||
+            !Object.prototype.hasOwnProperty.call(settings ?? {}, 'max_position_retention_days')
+        ) {
+            throw new Error(this.intl.t('settings.telematics.settings-unavailable'));
         }
 
         this.eventRetentionDays = settings.event_retention_days ?? this.eventRetentionDays;
diff --git a/addon/controllers/settings/telematics.js b/addon/controllers/settings/telematics.js
index d0dad8a6b..d4c5bf2b8 100644
--- a/addon/controllers/settings/telematics.js
+++ b/addon/controllers/settings/telematics.js
@@ -49,12 +49,9 @@ export default class SettingsTelematicsController extends Controller {
         };
     }
 
-    constructor() {
-        super(...arguments);
-        this.getSettings.perform();
-    }
+    @task({ restartable: true }) *getSettings() {
+        this.settingsLoaded = false;
 
-    @task *getSettings() {
         try {
             const settings = yield this.fetch.get('fleet-ops/settings/telematics-settings');
             this.applySettings(settings);
@@ -64,7 +61,11 @@ export default class SettingsTelematicsController extends Controller {
         }
     }
 
-    @task *saveSettings() {
+    @task({ drop: true }) *saveSettings() {
+        if (!this.settingsLoaded) {
+            return;
+        }
+
         try {
             const settings = yield this.fetch.post('fleet-ops/settings/telematics-settings', this.settingsPayload);
             this.applySettings(settings);
@@ -89,6 +90,15 @@ export default class SettingsTelematicsController extends Controller {
     }
 
     applySettings(settings = {}) {
+        const has = (object, key) => Object.prototype.hasOwnProperty.call(object ?? {}, key);
+        const hasHistoryMetadata = ['event_retention_days', 'position_retention_days'].every(
+            (key) => has(settings?.preferences, key) && has(settings?.defaults, key) && has(settings?.policy, `max_${key}`)
+        );
+
+        if (!hasHistoryMetadata) {
+            throw new Error(this.intl.t('settings.telematics.settings-unavailable'));
+        }
+
         this.eventRetentionDays = settings.event_retention_days ?? this.eventRetentionDays;
         this.positionRetentionDays = settings.position_retention_days ?? this.positionRetentionDays;
         this.useDefaultEventRetention = (settings.preferences?.event_retention_days ?? null) === null;
diff --git a/addon/routes/settings/telematics.js b/addon/routes/settings/telematics.js
index 73e817fd3..db07e66d8 100644
--- a/addon/routes/settings/telematics.js
+++ b/addon/routes/settings/telematics.js
@@ -13,4 +13,9 @@ export default class SettingsTelematicsRoute extends Route {
             return this.hostRouter.transitionTo('console.fleet-ops');
         }
     }
+
+    setupController(controller) {
+        super.setupController(...arguments);
+        controller.getSettings.perform();
+    }
 }
diff --git a/addon/templates/settings/telematics.hbs b/addon/templates/settings/telematics.hbs
index 3e08deaa2..e6bd60696 100644
--- a/addon/templates/settings/telematics.hbs
+++ b/addon/templates/settings/telematics.hbs
@@ -36,7 +36,9 @@
                         class="w-full form-input"
                     />
                 </InputGroup>
-                <p class="text-xs text-gray-500 dark:text-gray-400">{{this.eventRetentionPolicyHelp}}</p>
+                {{#if this.settingsLoaded}}
+                    <p class="text-xs text-gray-500 dark:text-gray-400">{{this.eventRetentionPolicyHelp}}</p>
+                {{/if}}
             </ContentPanel>
 
             <ContentPanel @title={{t "settings.telematics.positions"}} @open={{true}} @wrapperClass="bordered-classic">
@@ -58,7 +60,9 @@
                         class="w-full form-input"
                     />
                 </InputGroup>
-                <p class="text-xs text-gray-500 dark:text-gray-400">{{this.positionRetentionPolicyHelp}}</p>
+                {{#if this.settingsLoaded}}
+                    <p class="text-xs text-gray-500 dark:text-gray-400">{{this.positionRetentionPolicyHelp}}</p>
+                {{/if}}
             </ContentPanel>
         </div>
     </div>
diff --git a/docs/AFAQY.md b/docs/AFAQY.md
index 5b515efd3..591ba27bd 100644
--- a/docs/AFAQY.md
+++ b/docs/AFAQY.md
@@ -57,7 +57,7 @@ Existing provider interfaces and vehicle/trailer event names remain compatible.
 
 The public receiver remains `POST webhooks/telematics/afaqy?telematic=...&key=...` under the application's API prefix. A new `device.telemetry_updated` broadcast identifies the device; an open device panel reloads its authorized resource and refetches after socket reconnection. Company broadcast identity comes from the persisted asset, not a worker session. Map movement uses the existing vehicle/trailer events, rejects older source timestamps, and reloads visible telemetry assets after socket reconnection with at most five concurrent requests.
 
-Configure shared queues, retention, limits, and freshness under `telematics.telemetry` using `server/config/telemetry.php`. `TELEMATICS_BATCH_SIZE` controls units per ingestion delivery (default 100); `TELEMATICS_REQUEST_TIMEOUT_SECONDS` controls the bounded polling request timeout (default 45 seconds). AFAQY's adapter switches and optional queue overrides remain under `telematics.afaqy` in `server/config/afaqy.php`. Defaults: two MiB per webhook, 10,000 pending deliveries per connection, stale-position thresholds 120 seconds with ignition on and 600 seconds with ignition off/unknown. Retention (processed payloads 24 hours, quarantined deliveries seven days, device events 30 days, positions 90 days) is applied by `fleetops:prune-telematics-data` and is configured per company in Fleet-Ops → Settings → Telematics Data, with system defaults in the admin console; the config values are only the fallback. See `docs/TELEMETRY_ARCHITECTURE.md` § Retention. Each device's metadata records the effective threshold. Connection status categories remain unchanged.
+Configure shared queues, retention, limits, and freshness under `telematics.telemetry` using `server/config/telemetry.php`. `TELEMATICS_BATCH_SIZE` controls units per ingestion delivery (default 100); `TELEMATICS_REQUEST_TIMEOUT_SECONDS` controls the bounded polling request timeout (default 45 seconds). AFAQY's adapter switches and optional queue overrides remain under `telematics.afaqy` in `server/config/afaqy.php`. Defaults: two MiB per webhook, 10,000 pending deliveries per connection, stale-position thresholds 120 seconds with ignition on and 600 seconds with ignition off/unknown. Retention (processed payloads 24 hours, quarantined deliveries seven days, device events 30 days, positions 90 days) is applied by `fleetops:prune-telematics-data`. Administrators configure retention policy, logging, system storage diagnostics and system cleanup in Admin → Fleet-Ops Config → Telematics. Organizations choose only event and position history preferences within those limits in Fleet-Ops → Settings → Telematics; config values are the fallback. See `docs/TELEMETRY_ARCHITECTURE.md` § Retention. Each device's metadata records the effective threshold. Connection status categories remain unchanged.
 
 ## Incident verification
 
diff --git a/docs/TELEMATICS_QUEUES.md b/docs/TELEMATICS_QUEUES.md
index d1d9239f4..5957dbda2 100644
--- a/docs/TELEMATICS_QUEUES.md
+++ b/docs/TELEMATICS_QUEUES.md
@@ -14,7 +14,7 @@ nothing changes: every job and broadcast stays on the same queue as before.
 | Setting | Default | Work routed |
 | --- | --- | --- |
 | `TELEMATICS_POLL_QUEUE` | `default` | Scheduled and manual polls (`PollTelematicTelemetry`), legacy device discovery (`SyncTelematicDevicesJob`), and queued connection tests (`TestTelematicConnectionJob`). |
-| `TELEMATICS_INGESTION_QUEUE` | `default` | Applying polled or pushed positions (`ProcessTelematicDelivery`), including jobs re-queued by `fleetops:drain-telematic-inbox` and manual replays, and on-demand retention runs (`PruneTelematicsDataJob`, queued by "Run cleanup now" in Settings → Telematics Data). |
+| `TELEMATICS_INGESTION_QUEUE` | `default` | Applying polled or pushed positions (`ProcessTelematicDelivery`), including jobs re-queued by `fleetops:drain-telematic-inbox` and manual replays, and on-demand retention runs (`PruneTelematicsDataJob`, queued by "Run system cleanup" in Admin → Fleet-Ops Config → Telematics). |
 | `TELEMATICS_BROADCAST_QUEUE` | unset | Live-map broadcasts created by telematics ingestion: `DeviceTelemetryUpdated`, and `VehicleLocationChanged` / `TrailerLocationChanged` when a device is attached. When unset, broadcasts use the queue connection's default queue. |
 
 `TELEMATICS_BROADCAST_QUEUE` affects only broadcasts that telematics ingestion
diff --git a/docs/TELEMETRY_ARCHITECTURE.md b/docs/TELEMETRY_ARCHITECTURE.md
index fcc570da6..80737af13 100644
--- a/docs/TELEMETRY_ARCHITECTURE.md
+++ b/docs/TELEMETRY_ARCHITECTURE.md
@@ -64,13 +64,37 @@ policy resolved by `Support\Telematics\Retention\RetentionPolicy`:
 | Layer | Source | Where it is edited |
 |---|---|---|
 | Package config | `server/config/telemetry.php` | deployment |
-| System defaults | setting `fleet-ops.telematics-settings` | Admin console → Fleet-Ops Config → Telematics Data |
-| Company policy | `company.<uuid>.fleet-ops.telematics-settings` | Fleet-Ops → Settings → Telematics Data |
+| System policy | setting `fleet-ops.telematics-settings` | Admin console → Fleet-Ops Config → Telematics |
+| Company history preferences | `company.<uuid>.fleet-ops.telematics-settings` | Fleet-Ops → Settings → Telematics |
 
 Defaults: device events 30 days, raw payload/meta stripped ("compacted") after
 7 days, positions 90 days, processed deliveries 24 hours, quarantined deliveries
-7 days, sync runs 7 days. `0` keeps rows forever. Values are clamped to
-`RetentionPolicy::LIMITS`.
+7 days, sync runs 7 days. Organizations can choose only device event and position
+history retention, or inherit the system defaults. Administrators own raw payload,
+delivery, sync-run retention and telemetry activity logging.
+
+`max_event_retention_days` and `max_position_retention_days` constrain every
+organization's history, including inherited defaults. A maximum of `0` allows
+unlimited history; a history preference of `0` keeps records forever only while
+that maximum is unset. Setting a finite maximum replaces saved unlimited or longer
+preferences with that maximum. Missing preferences continue to inherit. Values
+are also clamped to `RetentionPolicy::LIMITS`.
+
+Admin storage diagnostics cover the entire system, including organizations the
+administrator does not belong to. System cleanup queues work for every
+organization plus orphaned records, with each organization's effective policy
+applied independently. Storage sizes include table data and indexes; database row
+estimates are labeled. Cleanup is asynchronous, so refreshing usage does not mean
+all queued work has finished.
+
+Manual system cleanup requires an asynchronous queue connection and a worker for
+`telematics.telemetry.ingestion_queue`. A synchronous or disabled queue is rejected
+instead of running every organization's cleanup inside the HTTP request.
+
+Deploy the frontend and backend together and reload Octane and queue workers after
+updating the backend. In linked development checkouts, Octane's watch paths must
+include `packages/fleetops/server`; watching only the host API directory leaves
+previously loaded controllers and policies running.
 
 Rules the sweep follows:
 
@@ -96,7 +120,7 @@ Rules the sweep follows:
 
 Two write-amplification fixes accompany the sweep: `device_events.meta` stores only
 the normalized block (the raw unit lives once, in `payload`), and telemetry-driven
-saves run inside `activity()->withoutLogs()` unless the company enables
+saves run inside `activity()->withoutLogs()` unless the system administrator enables
 "Log telemetry activity". `DrainTelematicInbox` now only recovers deliveries and
 finishes interrupted runs.
 
diff --git a/server/src/Console/Commands/PruneTelematicsData.php b/server/src/Console/Commands/PruneTelematicsData.php
index 98a6de4e6..492003f11 100644
--- a/server/src/Console/Commands/PruneTelematicsData.php
+++ b/server/src/Console/Commands/PruneTelematicsData.php
@@ -23,6 +23,7 @@ class PruneTelematicsData extends Command
 
     protected $signature = 'fleetops:prune-telematics-data
         {--company= : Only prune data for this company (uuid or public id)}
+        {--orphans-only : Only prune data without an existing company or connection}
         {--table=* : Only prune these tables (device_events, positions, telematic_deliveries, telematic_sync_runs)}
         {--batch-size=1000 : Rows per delete or update statement}
         {--max-batches=50 : Maximum batches per table per company per run}
@@ -55,12 +56,20 @@ public function handle(): int
         }
 
         try {
+            // Queue workers may have cached settings before an administrator saved a new policy.
+            RetentionPolicy::flush();
             $this->batchSize  = max(100, min(5000, (int) $this->option('batch-size') ?: 1000));
             $this->maxBatches = max(1, (int) $this->option('max-batches') ?: 50);
             $this->dryRun     = (bool) $this->option('dry-run');
 
-            $only      = ((string) $this->option('company')) ?: null;
-            $companies = $this->companies($only);
+            $only        = ((string) $this->option('company')) ?: null;
+            $orphansOnly = (bool) $this->option('orphans-only');
+            if ($only && $orphansOnly) {
+                $this->error('Choose either --company or --orphans-only.');
+
+                return self::FAILURE;
+            }
+            $companies = $orphansOnly ? new Collection() : $this->companies($only);
             if ($only && $companies->isEmpty()) {
                 $this->error(sprintf('Company [%s] was not found.', $only));
 
@@ -144,7 +153,12 @@ protected function pruneOrphans(RetentionPolicy $policy, array $tables): array
         $rows = fn ($query) => $query->where(function ($where) {
             $where->whereNull('company_uuid')->orWhereNotIn('company_uuid', DB::table('companies')->select('uuid'));
         });
-        $inbox = fn ($query) => $query->whereNotIn('telematic_uuid', DB::table('telematics')->select('uuid'));
+        $inbox = fn ($query) => $query->whereNotExists(function ($connections) use ($query) {
+            $connections->selectRaw('1')
+                ->from('telematics')
+                ->join('companies', 'companies.uuid', '=', 'telematics.company_uuid')
+                ->whereColumn('telematics.uuid', $query->from . '.telematic_uuid');
+        });
 
         return $this->prune($rows, $inbox, $policy, $tables);
     }
diff --git a/server/src/Http/Controllers/Internal/v1/SettingController.php b/server/src/Http/Controllers/Internal/v1/SettingController.php
index 529bc7749..afe3a7525 100644
--- a/server/src/Http/Controllers/Internal/v1/SettingController.php
+++ b/server/src/Http/Controllers/Internal/v1/SettingController.php
@@ -2,8 +2,9 @@
 
 namespace Fleetbase\FleetOps\Http\Controllers\Internal\v1;
 
-use Fleetbase\FleetOps\Jobs\PruneTelematicsDataJob;
+use Fleetbase\FleetOps\Jobs\DispatchTelematicsRetentionJobs;
 use Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy;
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Queue;
 use Fleetbase\FleetOps\Tracking\TrackingProviderRegistry;
 use Fleetbase\FleetOps\Traits\AuthorizesMethods;
 use Fleetbase\Http\Controllers\Controller;
@@ -715,14 +716,17 @@ public function saveTelematicsSettings(Request $request)
             'position_retention_days' => ['nullable', 'integer', 'min:0', 'max:3650'],
         ]);
 
-        $defaults    = $this->telematicsDefaults();
-        $preferences = RetentionPolicy::companyPreferences($request->only(RetentionPolicy::HISTORY_KEYS));
-        $effective   = RetentionPolicy::fromCompanyPreferences($preferences, $defaults)->toArray();
-        $preferences = array_intersect_key($effective, $preferences);
-        $this->configureCompanySetting(RetentionPolicy::SETTING_KEY, $preferences);
+        $saved = $this->withTelematicsPolicyLock(function () use ($request) {
+            $preferences = RetentionPolicy::constrainCompanyPreferences($request->only(RetentionPolicy::HISTORY_KEYS), $this->telematicsDefaults());
+
+            return $this->configureCompanySetting(RetentionPolicy::SETTING_KEY, $preferences);
+        });
+        if ($saved === false) {
+            return response()->error('Unable to save telematics history preferences.', 500);
+        }
         RetentionPolicy::flush($company->uuid);
 
-        return response()->json(array_merge($this->telematicsCompanySettings($preferences, $defaults), [
+        return response()->json(array_merge($this->getTelematicsSettings()->getData(true), [
             'status'  => 'ok',
             'message' => 'Telematics history preferences successfully saved.',
         ]));
@@ -752,50 +756,54 @@ public function saveAdminTelematicsSettings(Request $request)
             'max_position_retention_days' => ['sometimes', 'integer', 'min:0', 'max:3650'],
         ]);
 
-        $settings = RetentionPolicy::normalize($request->only(RetentionPolicy::keys()), $this->telematicsDefaults());
-        $this->configureSetting(RetentionPolicy::SETTING_KEY, $settings);
-        RetentionPolicy::flush();
+        try {
+            $settings = $this->withTelematicsPolicyLock(function () use ($request) {
+                $settings = RetentionPolicy::normalize($request->only(RetentionPolicy::keys()), $this->telematicsDefaults());
+                $this->configureSetting(RetentionPolicy::SETTING_KEY, $settings);
+
+                return $settings;
+            });
+            $this->reconcileTelematicsCompanyPreferences($settings);
+        } finally {
+            RetentionPolicy::flush();
+        }
 
         return response()->json($this->getAdminTelematicsSettings()->getData(true));
     }
 
     /**
-     * Report how much telematics data the current company holds per table.
+     * Report system-wide telematics storage, including data without an owner.
      *
-     * Exact counts have a database execution deadline. Large histories fall
-     * back to explicitly marked, company-scoped query-plan estimates. Sizes
-     * use average row length because InnoDB does not account space per tenant.
+     * Use table statistics for MySQL/MariaDB instead of scanning every tenant's
+     * history. Oldest-row lookups and fallback counts have a database deadline.
      *
      * @return \Illuminate\Http\JsonResponse
      */
     public function getTelematicsStorageUsage()
     {
-        $company = $this->currentCompany();
-        if (!$company) {
-            return response()->error('No company session.', 401);
-        }
-
-        $companyUuid = $company->uuid;
-        $telematics  = $this->companyTelematicUuids($companyUuid);
-        $byCompany   = fn ($query) => $query->where('company_uuid', $companyUuid);
-        $byInbox     = fn ($query) => $query->whereIn('telematic_uuid', $telematics);
-
-        $tables = [
-            'device_events'        => $this->tableUsage('device_events', $byCompany, 'created_at'),
-            'positions'            => $this->tableUsage('positions', $byCompany, 'created_at'),
-            'telematic_deliveries' => $telematics ? $this->tableUsage('telematic_deliveries', $byInbox, 'received_at') : ['rows' => 0, 'oldest' => null],
-            'telematic_sync_runs'  => $telematics ? $this->tableUsage('telematic_sync_runs', $byInbox, 'created_at') : ['rows' => 0, 'oldest' => null],
+        $ageColumns = [
+            'device_events'        => 'created_at',
+            'positions'            => 'created_at',
+            'telematic_deliveries' => 'received_at',
+            'telematic_sync_runs'  => 'created_at',
         ];
+        $statistics = $this->storageTableStatistics(array_keys($ageColumns));
+        $allRows    = fn ($query) => $query;
+        $tables     = [];
+        foreach ($ageColumns as $table => $ageColumn) {
+            $tables[$table] = isset($statistics[$table])
+                ? array_merge($statistics[$table], ['oldest' => $this->tableOldest($table, $allRows, $ageColumn)])
+                : $this->tableUsage($table, $allRows, $ageColumn);
+        }
 
         // Payload details require reading JSON-bearing rows, so they are opt-in
         // and omitted if they cannot be counted within the database deadline.
         if (request()->boolean('include_payload_counts', false)) {
             try {
-                $policy          = RetentionPolicy::fromCompanyPreferences((array) $this->lookupFromCompanySetting(RetentionPolicy::SETTING_KEY, []), $this->telematicsDefaults());
-                $rawPayloadRows  = $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload'));
-                $compactAfter    = (int) $policy->get('event_compact_after_days');
-                $compactableRows = $policy->compactsEvents()
-                    ? $this->tableCount('device_events', fn ($query) => $byCompany($query)->whereNotNull('payload')->where('created_at', '<', now()->subDays($compactAfter)->toDateTimeString()))
+                $rawPayloadRows  = $this->tableCount('device_events', fn ($query) => $query->whereNotNull('payload'));
+                $compactAfter    = (int) $this->telematicsDefaults()['event_compact_after_days'];
+                $compactableRows = $compactAfter > 0
+                    ? $this->tableCount('device_events', fn ($query) => $query->whereNotNull('payload')->where('created_at', '<', now()->subDays($compactAfter)->toDateTimeString()))
                     : 0;
 
                 $tables['device_events']['raw_payload_rows'] = $rawPayloadRows;
@@ -807,37 +815,32 @@ public function getTelematicsStorageUsage()
             }
         }
 
-        foreach ($this->averageRowLengths(array_keys($tables)) as $table => $length) {
-            $tables[$table]['avg_row_bytes'] = $length;
-            if ($tables[$table]['rows'] !== null) {
-                $tables[$table]['estimated_bytes'] = (int) ($tables[$table]['rows'] * $length);
-            }
-        }
-
         return response()->json([
             'tables'       => $tables,
-            'company'      => ['uuid' => $company->uuid, 'name' => $company->name ?? null],
+            'scope'        => 'system',
             'generated_at' => now()->toISOString(),
         ]);
     }
 
     /**
-     * Queue an immediate retention run for the current company.
+     * Queue retention for all companies and orphaned data, independent of session company.
      *
      * @return \Illuminate\Http\JsonResponse
      */
     public function runTelematicsRetention()
     {
-        $company = $this->currentCompany();
-        if (!$company) {
-            return response()->error('No company session.', 401);
+        $connection = (string) config('queue.default', 'sync');
+        $driver     = config('queue.connections.' . $connection . '.driver', $connection);
+        if (in_array($driver, ['sync', 'null'], true)) {
+            return response()->error('System-wide telematics cleanup requires an asynchronous queue connection and a running queue worker.', 503);
         }
 
-        $this->dispatchTelematicsPrune($company->uuid);
+        $this->dispatchTelematicsPrune();
 
         return response()->json([
             'status'  => 'queued',
-            'message' => 'Telematics cleanup has been queued.',
+            'scope'   => 'system',
+            'message' => 'System-wide telematics cleanup has been queued.',
         ], 202);
     }
 
@@ -859,7 +862,7 @@ protected function telematicsCompanySettings(array $stored, ?array $defaults = n
     {
         $defaults    = $defaults ?? $this->telematicsDefaults();
         $history     = array_flip(RetentionPolicy::HISTORY_KEYS);
-        $preferences = RetentionPolicy::companyPreferences($stored);
+        $preferences = RetentionPolicy::constrainCompanyPreferences($stored, $defaults);
         $effective   = RetentionPolicy::fromCompanyPreferences($preferences, $defaults)->toArray();
         $inherited   = RetentionPolicy::fromCompanyPreferences([], $defaults)->toArray();
 
@@ -871,6 +874,66 @@ protected function telematicsCompanySettings(array $stored, ?array $defaults = n
         ]);
     }
 
+    /**
+     * Serialize policy changes with a customer's policy lookup and preference
+     * write, so a request cannot save an old unlimited choice after a new cap.
+     * The empty row is only a lock anchor and keeps config fallbacks intact.
+     */
+    protected function withTelematicsPolicyLock(\Closure $callback): mixed
+    {
+        $setting = new Setting();
+        if (!$setting->newQuery()->where('key', RetentionPolicy::SETTING_KEY)->exists()) {
+            $setting->newQuery()->insertOrIgnore(['key' => RetentionPolicy::SETTING_KEY, 'value' => '[]']);
+        }
+
+        return $setting->getConnection()->transaction(function () use ($setting, $callback) {
+            $setting->newQuery()->where('key', RetentionPolicy::SETTING_KEY)->lockForUpdate()->firstOrFail();
+
+            return $callback();
+        }, 3);
+    }
+
+    /**
+     * A newly imposed maximum replaces existing unlimited or longer explicit
+     * choices for every organization. Keep inherited preferences absent so they
+     * continue following future system defaults. Process settings in bounded
+     * batches rather than loading every organization or its telemetry history.
+     */
+    protected function reconcileTelematicsCompanyPreferences(array $defaults): void
+    {
+        $maximums = array_intersect_key($defaults, array_flip(array_values(RetentionPolicy::MAXIMUMS)));
+        if (!array_filter($maximums, fn ($maximum) => $maximum > 0)) {
+            return;
+        }
+
+        Setting::query()
+            ->where('key', 'like', 'company.%.' . RetentionPolicy::SETTING_KEY)
+            ->select('id')
+            ->chunkById(200, function ($settings) {
+                foreach ($settings as $setting) {
+                    // Lock policy then company, as customer saves do. Reread
+                    // both so a later admin change or customer preference is
+                    // never overwritten using an earlier batch's snapshot.
+                    $this->withTelematicsPolicyLock(function () use ($setting) {
+                        $current = Setting::query()->whereKey($setting->getKey())->lockForUpdate()->first();
+                        if (!$current) {
+                            return;
+                        }
+
+                        $stored      = (array) $current->value;
+                        $preferences = RetentionPolicy::companyPreferences($stored);
+                        $constrained = RetentionPolicy::constrainCompanyPreferences($preferences, $this->telematicsDefaults());
+                        if ($preferences === $constrained) {
+                            return;
+                        }
+
+                        $current->value = array_replace($stored, $constrained);
+                        $current->save();
+                    });
+                }
+            });
+    }
+
     protected function tableUsage(string $table, \Closure $scope, string $ageColumn): array
     {
         if (!in_array(DB::connection()->getDriverName(), ['mysql', 'mariadb'], true)) {
@@ -896,8 +959,8 @@ protected function tableUsage(string $table, \Closure $scope, string $ageColumn)
             }
         }
 
-        // EXPLAIN does not execute the history scan. Keep the original tenant
-        // filter: whole-table InnoDB row counts include other companies' data.
+        // EXPLAIN does not execute the history scan. The caller's scope is
+        // preserved when metadata is unavailable and a count reaches its deadline.
         $estimate = null;
         $query    = $scope(DB::table($table))->select($ageColumn);
         try {
@@ -914,11 +977,6 @@ protected function tableUsage(string $table, \Closure $scope, string $ageColumn)
         return ['rows' => $estimate, 'oldest' => null, 'rows_estimated' => true];
     }
 
-    protected function companyTelematicUuids(string $companyUuid): array
-    {
-        return DB::table('telematics')->where('company_uuid', $companyUuid)->pluck('uuid')->all();
-    }
-
     protected function tableCount(string $table, \Closure $scope): int
     {
         $query = $scope(DB::table($table))->selectRaw('COUNT(*) AS row_count');
@@ -929,7 +987,17 @@ protected function tableCount(string $table, \Closure $scope): int
 
     protected function tableOldest(string $table, \Closure $scope, string $column): ?string
     {
-        $oldest = $scope(DB::table($table))->min($column);
+        $query = $scope(DB::table($table));
+        $query->selectRaw('MIN(' . $query->getGrammar()->wrap($column) . ') AS oldest');
+        try {
+            $oldest = $this->storageUsageSelect($query->toSql(), $query->getBindings())[0]->oldest ?? null;
+        } catch (QueryException $exception) {
+            if (!$this->isStorageUsageTimeout($exception)) {
+                throw $exception;
+            }
+
+            return null;
+        }
 
         return $oldest ? (string) $oldest : null;
     }
@@ -970,11 +1038,11 @@ protected function isStorageUsageTimeout(QueryException $exception): bool
     }
 
     /**
-     * Average row length per table from InnoDB statistics. Empty on other drivers.
+     * Whole-table row estimates and allocated data/index bytes. Empty on other drivers.
      *
-     * @return array<string, int>
+     * @return array<string, array<string, int|bool|null>>
      */
-    protected function averageRowLengths(array $tables): array
+    protected function storageTableStatistics(array $tables): array
     {
         $connection = DB::connection();
         if (!in_array($connection->getDriverName(), ['mysql', 'mariadb'], true)) {
@@ -985,7 +1053,7 @@ protected function averageRowLengths(array $tables): array
         $placeholders = implode(', ', array_fill(0, count($tables), '?'));
         try {
             $rows = $this->storageUsageSelect(
-                'SELECT TABLE_NAME AS name, AVG_ROW_LENGTH AS length FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (' . $placeholders . ')',
+                'SELECT TABLE_NAME AS name, TABLE_ROWS AS row_count, DATA_LENGTH AS data_bytes, INDEX_LENGTH AS index_bytes FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME IN (' . $placeholders . ')',
                 array_map(fn ($table) => $prefix . $table, $tables)
             );
         } catch (QueryException $exception) {
@@ -996,17 +1064,21 @@ protected function averageRowLengths(array $tables): array
             return [];
         }
 
-        $lengths = [];
+        $statistics = [];
         foreach ($rows as $row) {
-            $lengths[substr($row->name, strlen($prefix))] = (int) $row->length;
+            $statistics[substr($row->name, strlen($prefix))] = [
+                'rows'            => $row->row_count === null ? null : (int) $row->row_count,
+                'rows_estimated'  => true,
+                'estimated_bytes' => $row->data_bytes === null || $row->index_bytes === null ? null : (int) $row->data_bytes + (int) $row->index_bytes,
+            ];
         }
 
-        return $lengths;
+        return $statistics;
     }
 
-    protected function dispatchTelematicsPrune(string $companyUuid): void
+    protected function dispatchTelematicsPrune(): void
     {
-        PruneTelematicsDataJob::dispatch($companyUuid);
+        Queue::dispatch(new DispatchTelematicsRetentionJobs());
     }
 
     protected function configureSetting(string $key, mixed $value): mixed
diff --git a/server/src/Jobs/DispatchTelematicsRetentionJobs.php b/server/src/Jobs/DispatchTelematicsRetentionJobs.php
new file mode 100644
index 000000000..c8b44dfd2
--- /dev/null
+++ b/server/src/Jobs/DispatchTelematicsRetentionJobs.php
@@ -0,0 +1,70 @@
+<?php
+
+namespace Fleetbase\FleetOps\Jobs;
+
+use Fleetbase\FleetOps\Support\Telematics\Telemetry\Queue;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Fan out system-wide cleanup in small pages, without a session or membership scope.
+ * Each company has its own bounded prune job so one large backlog cannot prevent
+ * other organizations from being processed within a shared worker timeout.
+ */
+class DispatchTelematicsRetentionJobs implements ShouldQueue, ShouldBeUnique
+{
+    use Dispatchable;
+    use InteractsWithQueue;
+    use Queueable;
+
+    public const PAGE_SIZE = 100;
+
+    public int $uniqueFor = 900;
+    public int $tries     = 3;
+    public int $timeout   = 60;
+
+    public function __construct(public int $afterCompanyId = 0, public int $maxBatches = 200)
+    {
+        $this->onQueue(config('telematics.telemetry.ingestion_queue', 'default'));
+    }
+
+    public function uniqueId(): string
+    {
+        return 'after-company:' . $this->afterCompanyId;
+    }
+
+    public function handle(): void
+    {
+        $companies = $this->companies();
+        foreach ($companies as $company) {
+            $this->queueJob(new PruneTelematicsDataJob($company->uuid, $this->maxBatches));
+        }
+
+        if ($companies->count() === self::PAGE_SIZE) {
+            $this->queueJob(new self((int) $companies->last()->id, $this->maxBatches));
+
+            return;
+        }
+
+        $this->queueJob(new PruneTelematicsDataJob(null, $this->maxBatches, true));
+    }
+
+    protected function companies(): Collection
+    {
+        return DB::table('companies')
+            ->where('id', '>', $this->afterCompanyId)
+            ->orderBy('id')
+            ->limit(self::PAGE_SIZE)
+            ->get(['id', 'uuid']);
+    }
+
+    protected function queueJob(ShouldBeUnique $job): void
+    {
+        Queue::dispatch($job);
+    }
+}
diff --git a/server/src/Jobs/PruneTelematicsDataJob.php b/server/src/Jobs/PruneTelematicsDataJob.php
index 0df14789d..6b1b6b060 100644
--- a/server/src/Jobs/PruneTelematicsDataJob.php
+++ b/server/src/Jobs/PruneTelematicsDataJob.php
@@ -12,7 +12,7 @@
 use Symfony\Component\Console\Output\BufferedOutput;
 
 /**
- * Runs the telematics prune for one company on demand ("Run cleanup now").
+ * Runs a bounded telematics prune for one company or orphaned data.
  *
  * The command is executed directly rather than through the console kernel so a
  * worker started before this package version can still run it.
@@ -23,17 +23,22 @@ class PruneTelematicsDataJob implements ShouldQueue, ShouldBeUnique
     use InteractsWithQueue;
     use Queueable;
 
-    public int $uniqueFor = 900;
-    public int $tries     = 1;
-    public int $timeout   = 600;
+    public int $uniqueFor      = 900;
+    public int $tries          = 1;
+    // Finish or fail before Laravel's baseline Redis retry_after of 90 seconds.
+    public int $timeout        = 80;
+    public bool $failOnTimeout = true;
+    public bool $orphansOnly   = false;
 
-    public function __construct(public ?string $companyUuid = null, public int $maxBatches = 200)
+    public function __construct(public ?string $companyUuid = null, public int $maxBatches = 200, bool $orphansOnly = false)
     {
+        $this->orphansOnly = $orphansOnly;
+        $this->onQueue(config('telematics.telemetry.ingestion_queue', 'default'));
     }
 
     public function uniqueId(): string
     {
-        return $this->companyUuid ?? 'all';
+        return $this->orphansOnly ? 'orphans' : ($this->companyUuid ?? 'all');
     }
 
     /**
@@ -45,6 +50,9 @@ public function parameters(): array
         if ($this->companyUuid) {
             $parameters['--company'] = $this->companyUuid;
         }
+        if ($this->orphansOnly) {
+            $parameters['--orphans-only'] = true;
+        }
 
         return $parameters;
     }
@@ -53,7 +61,10 @@ public function handle(): void
     {
         $command = $this->command();
         $command->setLaravel(app());
-        $command->run(new ArrayInput($this->parameters()), new BufferedOutput());
+        $exitCode = $command->run(new ArrayInput($this->parameters()), new BufferedOutput());
+        if ($exitCode !== PruneTelematicsData::SUCCESS) {
+            throw new \RuntimeException('Telematics cleanup failed with exit code ' . $exitCode . '.');
+        }
     }
 
     protected function command(): PruneTelematicsData
diff --git a/server/src/Support/Telematics/Retention/RetentionPolicy.php b/server/src/Support/Telematics/Retention/RetentionPolicy.php
index 0e67fe53f..7b1c77751 100644
--- a/server/src/Support/Telematics/Retention/RetentionPolicy.php
+++ b/server/src/Support/Telematics/Retention/RetentionPolicy.php
@@ -150,6 +150,18 @@ public static function fromCompanyPreferences(array $preferences, ?array $defaul
         return self::fromArray(self::companyPreferences($preferences), $defaults ?? self::defaults());
     }
 
+    /**
+     * Return the explicit history choices after applying the administrator's
+     * maximums. Inherited values stay absent, and an allowed zero stays explicit.
+     */
+    public static function constrainCompanyPreferences(array $preferences, ?array $defaults = null): array
+    {
+        $preferences = self::companyPreferences($preferences);
+        $effective   = self::fromCompanyPreferences($preferences, $defaults)->toArray();
+
+        return array_intersect_key($effective, $preferences);
+    }
+
     /**
      * Clamp and cast user input, filling gaps from `$base`.
      */
diff --git a/server/tests/SettingControllerContractsTest.php b/server/tests/SettingControllerContractsTest.php
index 047172318..bfe60a305 100644
--- a/server/tests/SettingControllerContractsTest.php
+++ b/server/tests/SettingControllerContractsTest.php
@@ -17,6 +17,7 @@ class FleetOpsSettingControllerProbe extends SettingController
     public array $notifications         = [];
     public array $providers             = [];
     public string $googleMapsApiKey     = '';
+    public array $reconciledTelematicsDefaults = [];
 
     protected function configureSetting(string $key, mixed $value): mixed
     {
@@ -65,6 +66,16 @@ protected function currentCompany(): mixed
         return $this->company;
     }
 
+    protected function reconcileTelematicsCompanyPreferences(array $defaults): void
+    {
+        $this->reconciledTelematicsDefaults = $defaults;
+    }
+
+    protected function withTelematicsPolicyLock(Closure $callback): mixed
+    {
+        return $callback();
+    }
+
     protected function notificationNotifiables(): array
     {
         return $this->notifiables;
@@ -85,20 +96,17 @@ protected function googleMapsApiKey(): string
         return $this->googleMapsApiKey;
     }
 
-    public array $telematicUuids = [];
-    public array $counts         = [];
-    public array $oldest         = [];
-    public array $rowLengths     = [];
-    public array $countScopes    = [];
-    public array $pruned         = [];
-
-    protected function companyTelematicUuids(string $companyUuid): array
-    {
-        return $this->telematicUuids[$companyUuid] ?? [];
-    }
+    public array $counts          = [];
+    public array $oldest          = [];
+    public array $tableStatistics = [];
+    public array $countScopes     = [];
+    public array $pruned          = [];
 
     protected function tableUsage(string $table, Closure $scope, string $ageColumn): array
     {
+        // System storage must not add company or connection filters.
+        $scope(new stdClass());
+
         return [
             'rows'   => $this->tableCount($table, $scope),
             'oldest' => $this->tableOldest($table, $scope, $ageColumn),
@@ -117,14 +125,14 @@ protected function tableOldest(string $table, Closure $scope, string $column): ?
         return $this->oldest[$table] ?? null;
     }
 
-    protected function averageRowLengths(array $tables): array
+    protected function storageTableStatistics(array $tables): array
     {
-        return $this->rowLengths;
+        return $this->tableStatistics;
     }
 
-    protected function dispatchTelematicsPrune(string $companyUuid): void
+    protected function dispatchTelematicsPrune(): void
     {
-        $this->pruned[] = $companyUuid;
+        $this->pruned[] = 'system';
     }
 }
 
@@ -545,6 +553,8 @@ function fleetopsJsonPayload(mixed $response): array
         ->and($savedAdmin['max_event_retention_days'])->toBe(90)
         ->and($savedAdmin['max_position_retention_days'])->toBe(45)
         ->and($savedAdmin['log_telemetry_activity'])->toBeTrue()
+        ->and($controller->reconciledTelematicsDefaults['max_event_retention_days'])->toBe(90)
+        ->and($controller->reconciledTelematicsDefaults['max_position_retention_days'])->toBe(45)
         ->and($controller->configured['fleet-ops.telematics-settings']['position_retention_days'])->toBe(120);
 
     $partialAdmin = fleetopsJsonPayload($controller->saveAdminTelematicsSettings(new Request(['log_telemetry_activity' => false])));
@@ -559,65 +569,101 @@ function fleetopsJsonPayload(mixed $response): array
     config(['telematics.telemetry' => []]);
 });
 
-test('telematics customer settings, storage usage and cleanup require a company session', function () {
+test('explicit unlimited customer history stays distinct from inheritance and reads back with current maximums', function () {
+    $controller          = new FleetOpsSettingControllerProbe();
+    $controller->company = (object) ['uuid' => 'company-1'];
+
+    $saved = fleetopsJsonPayload($controller->saveTelematicsSettings(new Request([
+        'event_retention_days'    => 0,
+        'position_retention_days' => null,
+    ])));
+    expect($saved['event_retention_days'])->toBe(0)
+        ->and($saved['preferences'])->toBe(['event_retention_days' => 0, 'position_retention_days' => null])
+        ->and($controller->configuredCompany['fleet-ops.telematics-settings'])->toBe(['event_retention_days' => 0])
+        ->and(fleetopsJsonPayload($controller->getTelematicsSettings())['preferences'])->toBe($saved['preferences']);
+
+    $controller->settings['fleet-ops.telematics-settings'] = ['max_event_retention_days' => 90, 'max_position_retention_days' => 360];
+    $loaded = fleetopsJsonPayload($controller->getTelematicsSettings());
+    expect($loaded['event_retention_days'])->toBe(90)
+        ->and($loaded['preferences'])->toBe(['event_retention_days' => 90, 'position_retention_days' => null])
+        ->and($loaded['policy'])->toBe(['max_event_retention_days' => 90, 'max_position_retention_days' => 360]);
+});
+
+test('telematics customer settings require a company session', function () {
     $controller = new FleetOpsSettingControllerProbe();
     expect($controller->getTelematicsSettings()->getStatusCode())->toBe(401)
         ->and($controller->saveTelematicsSettings(new Request())->getStatusCode())->toBe(401)
-        ->and($controller->getTelematicsStorageUsage()->getStatusCode())->toBe(401)
-        ->and($controller->runTelematicsRetention()->getStatusCode())->toBe(401)
         ->and($controller->configuredCompany)->toBe([])
         ->and($controller->pruned)->toBe([]);
 });
 
-test('telematics storage usage reports rows, age, compaction backlog and estimated size per table', function () {
-    $originalRequest = app('request');
+test('admin telematics storage and cleanup cover the system without a company session', function () {
+    $originalRequest     = app('request');
+    $originalQueueConfig = config('queue', []);
+    config(['queue.default' => 'database', 'queue.connections.database.driver' => 'database']);
     app()->instance('request', new Request(['include_payload_counts' => true]));
     Illuminate\Support\Carbon::setTestNow('2026-09-23 12:00:00 UTC');
     try {
-        $controller                 = new FleetOpsSettingControllerProbe();
-        $controller->company        = (object) ['uuid' => 'company-1'];
-        $controller->telematicUuids = ['company-1' => ['tm-1']];
-        $controller->counts         = ['device_events' => 500, 'positions' => 40, 'telematic_deliveries' => 6, 'telematic_sync_runs' => 3];
-        $controller->oldest         = ['device_events' => '2026-08-01 00:00:00'];
-        $controller->rowLengths     = ['device_events' => 32000, 'positions' => 700];
+        $controller                  = new FleetOpsSettingControllerProbe();
+        $controller->counts          = ['device_events' => 500, 'positions' => 40, 'telematic_deliveries' => 6, 'telematic_sync_runs' => 3];
+        $controller->oldest          = ['device_events' => '2026-08-01 00:00:00'];
+        $controller->tableStatistics = [
+            'device_events' => ['rows' => 500, 'rows_estimated' => true, 'estimated_bytes' => 16000000],
+            'positions'    => ['rows' => 40, 'rows_estimated' => true, 'estimated_bytes' => 28000],
+        ];
 
         $usage = fleetopsJsonPayload($controller->getTelematicsStorageUsage());
         expect($usage['tables']['device_events'])->toBe([
             'rows'             => 500,
+            'rows_estimated'   => true,
+            'estimated_bytes'  => 16000000,
             'oldest'           => '2026-08-01 00:00:00',
             'raw_payload_rows' => 500,
             'compactable_rows' => 500,
-            'avg_row_bytes'    => 32000,
-            'estimated_bytes'  => 16000000,
         ])
-            ->and($usage['tables']['positions'])->toBe(['rows' => 40, 'oldest' => null, 'avg_row_bytes' => 700, 'estimated_bytes' => 28000])
+            ->and($usage['tables']['positions'])->toBe(['rows' => 40, 'rows_estimated' => true, 'estimated_bytes' => 28000, 'oldest' => null])
             ->and($usage['tables']['telematic_deliveries'])->toBe(['rows' => 6, 'oldest' => null])
             ->and($usage['tables']['telematic_sync_runs']['rows'])->toBe(3)
-            ->and($usage['company'])->toBe(['uuid' => 'company-1', 'name' => null])
+            ->and($usage['scope'])->toBe('system')
+            ->and($usage)->not->toHaveKey('company')
             ->and($usage['generated_at'])->toBe('2026-09-23T12:00:00.000000Z')
-            ->and($controller->countScopes)->toBe(['device_events', 'positions', 'telematic_deliveries', 'telematic_sync_runs', 'device_events', 'device_events']);
-
-        // Without connections the inbox tables are reported empty; compaction disabled skips the backlog count.
-        $controller->telematicUuids                                    = [];
-        $controller->settings['fleet-ops.telematics-settings']         = ['event_compact_after_days' => 0];
-        $controller->countScopes                                       = [];
-        $usage                                                         = fleetopsJsonPayload($controller->getTelematicsStorageUsage());
-        expect($usage['tables']['telematic_deliveries'])->toBe(['rows' => 0, 'oldest' => null])
-            ->and($usage['tables']['telematic_sync_runs'])->toBe(['rows' => 0, 'oldest' => null])
+            ->and($controller->countScopes)->toBe(['telematic_deliveries', 'telematic_sync_runs', 'device_events', 'device_events']);
+
+        // Missing metadata uses bounded full-table counts, independent of any organization's connections.
+        $controller->tableStatistics                          = [];
+        $controller->settings['fleet-ops.telematics-settings'] = ['event_compact_after_days' => 0];
+        $controller->countScopes                              = [];
+        $usage                                                = fleetopsJsonPayload($controller->getTelematicsStorageUsage());
+        expect($usage['tables']['telematic_deliveries'])->toBe(['rows' => 6, 'oldest' => null])
+            ->and($usage['tables']['telematic_sync_runs'])->toBe(['rows' => 3, 'oldest' => null])
             ->and($usage['tables']['device_events']['compactable_rows'])->toBe(0)
-            ->and($controller->countScopes)->toBe(['device_events', 'positions', 'device_events']);
+            ->and($controller->countScopes)->toBe(['device_events', 'positions', 'telematic_deliveries', 'telematic_sync_runs', 'device_events']);
 
         $queued = $controller->runTelematicsRetention();
         expect($queued->getStatusCode())->toBe(202)
             ->and(fleetopsJsonPayload($queued)['status'])->toBe('queued')
-            ->and($controller->pruned)->toBe(['company-1']);
+            ->and(fleetopsJsonPayload($queued)['scope'])->toBe('system')
+            ->and($controller->pruned)->toBe(['system']);
     } finally {
         app()->instance('request', $originalRequest);
+        config(['queue' => $originalQueueConfig]);
         Illuminate\Support\Carbon::setTestNow();
     }
 });
 
-test('telematics storage helpers query the database and size rows from InnoDB statistics on MySQL', function () {
+test('system cleanup does not run an entire platform inline on a synchronous queue', function () {
+    $originalQueueConfig = config('queue', []);
+    try {
+        config(['queue.default' => 'sync', 'queue.connections.sync.driver' => 'sync']);
+        $controller = new FleetOpsSettingControllerProbe();
+        expect($controller->runTelematicsRetention()->getStatusCode())->toBe(503)
+            ->and($controller->pruned)->toBe([]);
+    } finally {
+        config(['queue' => $originalQueueConfig]);
+    }
+});
+
+test('telematics storage helpers query all rows and allocated table bytes from MySQL statistics', function () {
     $connection = new class(new PDO('sqlite::memory:')) extends Illuminate\Database\SQLiteConnection {
         public string $driver = 'sqlite';
         public array $selects = [];
@@ -633,7 +679,7 @@ public function select($query, $bindings = [], $useReadPdo = true)
                 $this->selects[] = [$query, $bindings];
 
                 // information_schema reports prefixed table names.
-                return [(object) ['name' => $bindings[0], 'length' => '32000'], (object) ['name' => $bindings[1], 'length' => 700]];
+                return [(object) ['name' => $bindings[0], 'row_count' => '500', 'data_bytes' => '16000000', 'index_bytes' => '5000'], (object) ['name' => $bindings[1], 'row_count' => 40, 'data_bytes' => 28000, 'index_bytes' => 2000]];
             }
 
             return parent::select($query, $bindings, $useReadPdo);
@@ -677,30 +723,26 @@ public function __call($method, $arguments)
         ]);
 
         $controller = new class extends SettingController {
-            public function telematics(string $company): array
-            {
-                return $this->companyTelematicUuids($company);
-            }
-
             public function usage(string $table, Closure $scope, string $column): array
             {
                 return $this->tableUsage($table, $scope, $column);
             }
 
-            public function lengths(array $tables): array
+            public function statistics(array $tables): array
             {
-                return $this->averageRowLengths($tables);
+                return $this->storageTableStatistics($tables);
             }
         };
-        $byCompany = fn ($query) => $query->where('company_uuid', 'company-1');
-        expect($controller->telematics('company-1'))->toBe(['tm-1'])
-            ->and($controller->usage('device_events', $byCompany, 'created_at'))->toBe(['rows' => 2, 'oldest' => '2026-08-01 00:00:00'])
+        expect($controller->usage('device_events', fn ($query) => $query, 'created_at'))->toBe(['rows' => 3, 'oldest' => '2026-07-01 00:00:00'])
             ->and($controller->usage('device_events', fn ($query) => $query->where('company_uuid', 'none'), 'created_at'))->toBe(['rows' => 0, 'oldest' => null])
-            ->and($controller->lengths(['device_events', 'positions']))->toBe([]);
+            ->and($controller->statistics(['device_events', 'positions']))->toBe([]);
 
         $connection->driver = 'mysql';
         $connection->setTablePrefix('fb_');
-        expect($controller->lengths(['device_events', 'positions']))->toBe(['device_events' => 32000, 'positions' => 700])
+        expect($controller->statistics(['device_events', 'positions']))->toBe([
+            'device_events' => ['rows' => 500, 'rows_estimated' => true, 'estimated_bytes' => 16005000],
+            'positions'    => ['rows' => 40, 'rows_estimated' => true, 'estimated_bytes' => 30000],
+        ])
             ->and($connection->selects[0][1])->toBe(['fb_device_events', 'fb_positions'])
             ->and($connection->selects[0][0])->toContain('TABLE_NAME IN (?, ?)');
     } finally {
@@ -713,18 +755,50 @@ public function lengths(array $tables): array
     }
 });
 
-test('telematics cleanup dispatches the unique prune job for the company', function () {
-    Fleetbase\TestSupport\DispatchRecorder::$dispatched = [];
-    $controller                                         = new class extends SettingController {
-        public function prune(string $company): void
+test('admin telematics cleanup dispatches the system-wide fanout job', function () {
+    $controller = new class extends SettingController {
+        public function prune(): void
         {
-            $this->dispatchTelematicsPrune($company);
+            $this->dispatchTelematicsPrune();
         }
     };
-    $controller->prune('company-1');
+    $originalCache       = Illuminate\Support\Facades\Cache::getFacadeRoot();
+    $originalCacheConfig = config('cache', []);
+    $dispatcherContract  = Illuminate\Contracts\Bus\Dispatcher::class;
+    $originalDispatcher  = app()->bound($dispatcherContract) ? app($dispatcherContract) : null;
+    try {
+        config(['cache.default' => 'array', 'cache.stores.array' => ['driver' => 'array']]);
+        Illuminate\Support\Facades\Cache::swap(new Illuminate\Cache\CacheManager(app()));
+        $dispatcher = new class(app()) extends Illuminate\Bus\Dispatcher {
+            public array $jobs = [];
+            public bool $fail = true;
 
-    expect(Fleetbase\TestSupport\DispatchRecorder::$dispatched)->toBe([
-        ['job' => Fleetbase\FleetOps\Jobs\PruneTelematicsDataJob::class, 'arguments' => ['company-1']],
-    ]);
-    Fleetbase\TestSupport\DispatchRecorder::$dispatched = [];
+            public function dispatch($command)
+            {
+                if ($this->fail) {
+                    throw new RuntimeException('Broker unavailable');
+                }
+                $this->jobs[] = $command;
+
+                return $command;
+            }
+        };
+        app()->instance($dispatcherContract, $dispatcher);
+
+        expect(fn () => $controller->prune())->toThrow(RuntimeException::class, 'Broker unavailable');
+        $dispatcher->fail = false;
+        $controller->prune();
+        $controller->prune();
+        expect($dispatcher->jobs)->toHaveCount(1)
+            ->and($dispatcher->jobs[0])->toBeInstanceOf(Fleetbase\FleetOps\Jobs\DispatchTelematicsRetentionJobs::class)
+            ->and($dispatcher->jobs[0]->afterCompanyId)->toBe(0);
+    } finally {
+        Illuminate\Support\Facades\Cache::swap($originalCache);
+        config(['cache' => $originalCacheConfig]);
+        if ($originalDispatcher) {
+            app()->instance($dispatcherContract, $originalDispatcher);
+        } else {
+            app()->forgetInstance($dispatcherContract);
+        }
+    }
 });
diff --git a/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php b/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php
index bcd228f80..f842dd6a4 100644
--- a/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php
+++ b/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php
@@ -106,6 +106,34 @@ function fleetopsPruneRun(string $uuid, string $telematic, string $status, int $
 
 afterEach(fn () => Carbon::setTestNow());
 
+test('orphan cleanup reaches missing connections and connections whose organization no longer exists', function () {
+    fleetopsPruneBoot();
+    DB::table('telematics')->insert(['uuid' => 'tm-orphan-company', 'company_uuid' => 'company-gone', 'provider' => 'afaqy', 'status' => 'disabled']);
+    DB::table('device_events')->insert([
+        fleetopsPruneEvent('e-unowned', null, 40),
+        fleetopsPruneEvent('e-owned', 'company-1', 40),
+    ]);
+    DB::table('telematic_deliveries')->insert([
+        fleetopsPruneDelivery('d-missing-connection', 'tm-gone', 'processed', 48),
+        fleetopsPruneDelivery('d-missing-company', 'tm-orphan-company', 'processed', 48),
+        fleetopsPruneDelivery('d-active-company', 'tm-1', 'processed', 48),
+        fleetopsPruneDelivery('d-orphan-pending', 'tm-gone', 'pending', 48),
+    ]);
+    DB::table('telematic_sync_runs')->insert([
+        fleetopsPruneRun('r-missing-connection', 'tm-gone', 'completed', 10),
+        fleetopsPruneRun('r-missing-company', 'tm-orphan-company', 'completed', 10),
+        fleetopsPruneRun('r-active-company', 'tm-1', 'completed', 10),
+        fleetopsPruneRun('r-orphan-in-flight', 'tm-gone', 'ingesting', 10),
+    ]);
+
+    $command = new PruneTelematicsDataProbe();
+    $command->options['orphans-only'] = true;
+    expect($command->handle())->toBe(PruneTelematicsData::SUCCESS)
+        ->and(DB::table('device_events')->pluck('uuid')->all())->toBe(['e-owned'])
+        ->and(DB::table('telematic_deliveries')->orderBy('uuid')->pluck('uuid')->all())->toBe(['d-active-company', 'd-orphan-pending'])
+        ->and(DB::table('telematic_sync_runs')->orderBy('uuid')->pluck('uuid')->all())->toBe(['r-active-company', 'r-orphan-in-flight']);
+});
+
 test('prune applies each company policy to events, positions and the inbox, and system defaults to orphans', function () {
     fleetopsPruneBoot();
     DB::table('device_events')->insert([
diff --git a/server/tests/Unit/Jobs/DispatchTelematicsRetentionJobsTest.php b/server/tests/Unit/Jobs/DispatchTelematicsRetentionJobsTest.php
new file mode 100644
index 000000000..2114fcbab
--- /dev/null
+++ b/server/tests/Unit/Jobs/DispatchTelematicsRetentionJobsTest.php
@@ -0,0 +1,57 @@
+<?php
+
+use Fleetbase\FleetOps\Jobs\DispatchTelematicsRetentionJobs;
+use Fleetbase\FleetOps\Jobs\PruneTelematicsDataJob;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
+use Illuminate\Support\Collection;
+
+class FleetOpsTelematicsRetentionDispatchProbe extends DispatchTelematicsRetentionJobs
+{
+    public array $dispatched = [];
+    public array $companyRows = [];
+
+    protected function companies(): Collection
+    {
+        return collect($this->companyRows);
+    }
+
+    protected function queueJob(ShouldBeUnique $job): void
+    {
+        $this->dispatched[] = $job;
+    }
+}
+
+test('system cleanup fans out a bounded page and continues from its last company', function () {
+    $job = new FleetOpsTelematicsRetentionDispatchProbe(200, 25);
+    $job->companyRows = array_map(fn ($id) => (object) ['id' => $id, 'uuid' => 'company-' . $id], range(201, 300));
+    $job->handle();
+
+    $prunes = array_slice($job->dispatched, 0, 100);
+    expect($prunes)->toHaveCount(100)
+        ->and(array_map(fn ($prune) => $prune->companyUuid, $prunes))->toBe(array_map(fn ($id) => 'company-' . $id, range(201, 300)));
+    foreach ($prunes as $prune) {
+        expect($prune)->toBeInstanceOf(PruneTelematicsDataJob::class)
+            ->and($prune->maxBatches)->toBe(25)
+            ->and($prune->orphansOnly)->toBeFalse();
+    }
+    $nextPage = $job->dispatched[100];
+    expect($nextPage)->toBeInstanceOf(DispatchTelematicsRetentionJobs::class)
+        ->and($nextPage->afterCompanyId)->toBe(300)
+        ->and($nextPage->maxBatches)->toBe(25)
+        ->and($nextPage->uniqueId())->not->toBe($job->uniqueId())
+        ->and($nextPage->queue)->toBe(config('telematics.telemetry.ingestion_queue', 'default'));
+});
+
+test('the final system cleanup page queues an orphan pass even when there are no companies', function () {
+    foreach ([[], [(object) ['id' => 1001, 'uuid' => 'company-1001']]] as $companies) {
+        $job = new FleetOpsTelematicsRetentionDispatchProbe(1000);
+        $job->companyRows = $companies;
+        $job->handle();
+
+        expect($job->dispatched)->toHaveCount(count($companies) + 1);
+        $orphans = $job->dispatched[count($companies)];
+        expect($orphans)->toBeInstanceOf(PruneTelematicsDataJob::class)
+            ->and($orphans->companyUuid)->toBeNull()
+            ->and($orphans->orphansOnly)->toBeTrue();
+    }
+});
diff --git a/server/tests/Unit/Jobs/PruneTelematicsDataJobTest.php b/server/tests/Unit/Jobs/PruneTelematicsDataJobTest.php
index 7f99ce05b..b04b8903d 100644
--- a/server/tests/Unit/Jobs/PruneTelematicsDataJobTest.php
+++ b/server/tests/Unit/Jobs/PruneTelematicsDataJobTest.php
@@ -14,12 +14,13 @@
 class FleetOpsPruneCommandRunRecorder extends PruneTelematicsData
 {
     public array $runs = [];
+    public int $exitCode = 0;
 
     public function run(InputInterface $input, OutputInterface $output): int
     {
         $this->runs[] = (string) $input;
 
-        return 0;
+        return $this->exitCode;
     }
 }
 
@@ -32,16 +33,27 @@ public function run(InputInterface $input, OutputInterface $output): int
             ->and($job->uniqueId())->toBe('company-1')
             ->and($job->uniqueFor)->toBe(900)
             ->and($job->tries)->toBe(1)
+            ->and($job->timeout)->toBeLessThan(90)
+            ->and($job->failOnTimeout)->toBeTrue()
+            ->and($job->queue)->toBe(config('telematics.telemetry.ingestion_queue', 'default'))
             ->and($job->parameters())->toBe(['--no-lock' => true, '--max-batches' => 200, '--company' => 'company-1']);
         $job->handle();
 
         (new PruneTelematicsDataJob(null, 25))->handle();
+        $orphans = new PruneTelematicsDataJob(null, 25, true);
+        $orphans->handle();
         expect((new PruneTelematicsDataJob())->uniqueId())->toBe('all')
+            ->and($orphans->uniqueId())->toBe('orphans')
+            ->and($orphans->parameters())->toBe(['--no-lock' => true, '--max-batches' => 25, '--orphans-only' => true])
             ->and($recorder->runs)->toBe([
                 '--no-lock=1 --max-batches=200 --company=company-1',
                 '--no-lock=1 --max-batches=25',
+                '--no-lock=1 --max-batches=25 --orphans-only=1',
             ])
             ->and($recorder->getLaravel())->toBe(app());
+
+        $recorder->exitCode = PruneTelematicsData::FAILURE;
+        expect(fn () => $job->handle())->toThrow(RuntimeException::class, 'Telematics cleanup failed with exit code 1.');
     } finally {
         app()->forgetInstance(PruneTelematicsData::class);
     }
diff --git a/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php b/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php
index 00b24b480..ef1ad772b 100644
--- a/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php
+++ b/server/tests/Unit/Support/Telematics/Retention/RetentionPolicyTest.php
@@ -136,6 +136,18 @@ function fleetopsRetentionResolver(array $system, array $company, ?array &$calls
         ->and(RetentionPolicy::companyPreferences(['event_retention_days' => null, 'position_retention_days' => '', 'log_telemetry_activity' => true]))->toBe([]);
 });
 
+test('constrained preferences keep zero explicit when allowed and replace it when an administrator imposes a maximum', function () {
+    $preferences = ['event_retention_days' => 0, 'position_retention_days' => null];
+    expect(RetentionPolicy::constrainCompanyPreferences($preferences, RetentionPolicy::FALLBACKS))->toBe(['event_retention_days' => 0]);
+
+    $defaults = array_replace(RetentionPolicy::FALLBACKS, ['max_event_retention_days' => 90, 'max_position_retention_days' => 360]);
+    $bounded  = RetentionPolicy::constrainCompanyPreferences($preferences, $defaults);
+    expect($bounded)->toBe(['event_retention_days' => 90])
+        ->and(RetentionPolicy::constrainCompanyPreferences(['event_retention_days' => 30, 'position_retention_days' => 720], $defaults))->toBe(['event_retention_days' => 30, 'position_retention_days' => 360])
+        ->and(RetentionPolicy::constrainCompanyPreferences([], $defaults))->toBe([])
+        ->and(RetentionPolicy::constrainCompanyPreferences($bounded, RetentionPolicy::FALLBACKS))->toBe(['event_retention_days' => 90]);
+});
+
 test('cutoffs, compaction and deletion rules follow the clamped values', function () {
     Carbon::setTestNow('2026-09-23 12:00:00 UTC');
 
diff --git a/translations/en-us.yaml b/translations/en-us.yaml
index 2d7c0ebe1..ae122c471 100644
--- a/translations/en-us.yaml
+++ b/translations/en-us.yaml
@@ -2749,7 +2749,7 @@ settings:
         activity-logging: Telemetry Activity Logging
         log-telemetry-activity: Log telemetry activity
         log-telemetry-activity-help: Write telemetry-driven device, event and vehicle saves to the activity log. Off by default; every poll otherwise adds several activity rows per device.
-        storage-usage: Telematics Storage Usage
+        storage-usage: System Telematics Storage Usage
         table: Table
         rows: Rows
         estimated-rows: "{count} (estimated)"
@@ -2758,12 +2758,14 @@ settings:
         not-available: n/a
         raw-payload-rows: "{count} rows still carry raw payloads, {compactable} eligible for compaction now"
         refresh: Refresh
-        run-cleanup: Run cleanup now
-        run-cleanup-confirm: This queues cleanup for the organization currently selected in Console, using the saved system policy and its effective history preferences. Expired records are permanently deleted and cannot be recovered. Continue?
-        cleanup-queued: Telematics cleanup has been queued for the selected organization. Usage refreshes shortly.
+        run-cleanup: Run system cleanup
+        run-cleanup-confirm: This queues telematics cleanup across all organizations, using the saved system policy and each organization's effective history preferences. Expired records are permanently deleted and cannot be recovered. Continue?
+        cleanup-queued: Telematics cleanup has been queued across all organizations. Usage refreshes shortly; cleanup may still be running.
+        cleanup-unavailable: System-wide telematics cleanup could not be confirmed. Please try again.
         usage-unavailable: Storage usage could not be loaded. Select Refresh to try again.
-        space-reclaim-note: Usage applies to the organization currently selected in Console. Row counts marked as estimated use that organization's database query statistics. Sizes use shared-table average row lengths. Deleting records frees space for reuse within the database; physical disk usage may not decrease immediately.
+        space-reclaim-note: Usage includes all telematics data across the system. Row counts marked as estimated use database statistics. Sizes include table data and indexes. Deleting records frees space for reuse within the database; physical disk usage may not decrease immediately.
         settings-saved: Telematics settings saved.
+        settings-unavailable: Telematics settings could not be loaded. Please try again.
         tables:
             device_events: Device events
             positions: Positions

From d105d6e7a2c4c512c7de1e604f1f8482ffb6722e Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 15:24:35 +0800
Subject: [PATCH 17/24] fix: right-align oldest telematics storage rows

---
 addon/components/admin/telematics-settings.hbs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/addon/components/admin/telematics-settings.hbs b/addon/components/admin/telematics-settings.hbs
index ff6c3bffe..e415ce894 100644
--- a/addon/components/admin/telematics-settings.hbs
+++ b/addon/components/admin/telematics-settings.hbs
@@ -98,7 +98,7 @@
                             <th class="py-2 pr-3">{{t "settings.telematics.table"}}</th>
                             <th class="py-2 pr-3 text-right">{{t "settings.telematics.rows"}}</th>
                             <th class="py-2 pr-3 text-right">{{t "settings.telematics.estimated-size"}}</th>
-                            <th class="py-2 pl-6 text-left whitespace-nowrap">{{t "settings.telematics.oldest"}}</th>
+                            <th class="py-2 pl-6 text-right whitespace-nowrap">{{t "settings.telematics.oldest"}}</th>
                         </tr>
                     </thead>
                     <tbody class="divide-y divide-gray-100 dark:divide-gray-700">
@@ -122,7 +122,7 @@
                                     {{/if}}
                                 </td>
                                 <td class="py-2 pr-3 text-right">{{#if (or row.estimated_bytes (eq row.estimated_bytes 0))}}{{format-bytes row.estimated_bytes}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
-                                <td class="py-2 pl-6 text-left text-xs whitespace-nowrap">{{#if row.oldest}}{{row.oldest}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
+                                <td class="py-2 pl-6 text-right text-xs whitespace-nowrap">{{#if row.oldest}}{{row.oldest}}{{else}}{{t "settings.telematics.not-available"}}{{/if}}</td>
                             </tr>
                         {{/each}}
                     </tbody>

From d5a305fdb1709561511a1ac2e0c697d7849dd666 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 16:54:54 +0800
Subject: [PATCH 18/24] fix: restore public orchestration and release checks

---
 addon/components/admin/telematics-settings.js |  5 +--
 addon/controllers/settings/index.js           |  7 +++-
 addon/controllers/settings/telematics.js      |  4 +-
 .../Api/v1/OrchestrationController.php        |  9 ++++
 ...nalImportExportControllerContractsTest.php | 13 +++---
 .../tests/OrchestratorConsumableApiTest.php   | 42 +++++++++++++++++++
 6 files changed, 64 insertions(+), 16 deletions(-)

diff --git a/addon/components/admin/telematics-settings.js b/addon/components/admin/telematics-settings.js
index 37db5c303..f2d19d9ba 100644
--- a/addon/components/admin/telematics-settings.js
+++ b/addon/components/admin/telematics-settings.js
@@ -122,10 +122,7 @@ export default class AdminTelematicsSettingsComponent extends Component {
     }
 
     applySettings(settings = {}) {
-        if (
-            !Object.prototype.hasOwnProperty.call(settings ?? {}, 'max_event_retention_days') ||
-            !Object.prototype.hasOwnProperty.call(settings ?? {}, 'max_position_retention_days')
-        ) {
+        if (!Object.prototype.hasOwnProperty.call(settings ?? {}, 'max_event_retention_days') || !Object.prototype.hasOwnProperty.call(settings ?? {}, 'max_position_retention_days')) {
             throw new Error(this.intl.t('settings.telematics.settings-unavailable'));
         }
 
diff --git a/addon/controllers/settings/index.js b/addon/controllers/settings/index.js
index e7ec33afb..586754c08 100644
--- a/addon/controllers/settings/index.js
+++ b/addon/controllers/settings/index.js
@@ -28,7 +28,12 @@ export default class SettingsIndexController extends Controller {
             description: 'Keep commerce, metadata, and visual conventions aligned.',
             links: [
                 { label: 'Payments', route: 'settings.payments', icon: 'cash-register', description: 'Payment setup for operational commerce workflows.' },
-                { label: 'Telematics', route: 'settings.telematics', icon: 'satellite-dish', description: 'Device event and position history preferences within the system retention policy.' },
+                {
+                    label: 'Telematics',
+                    route: 'settings.telematics',
+                    icon: 'satellite-dish',
+                    description: 'Device event and position history preferences within the system retention policy.',
+                },
                 { label: 'Custom Fields', route: 'settings.custom-fields', icon: 'pen-to-square', description: 'Operational metadata fields for Fleet-Ops records.' },
                 { label: 'Avatars', route: 'settings.avatars', icon: 'icons', description: 'Visual assets for driver, vehicle, and map displays.' },
             ],
diff --git a/addon/controllers/settings/telematics.js b/addon/controllers/settings/telematics.js
index d4c5bf2b8..9700fe77c 100644
--- a/addon/controllers/settings/telematics.js
+++ b/addon/controllers/settings/telematics.js
@@ -108,8 +108,6 @@ export default class SettingsTelematicsController extends Controller {
     }
 
     retentionPolicyHelp(maximum) {
-        return maximum > 0
-            ? this.intl.t('settings.telematics.history-policy-maximum', { days: maximum })
-            : this.intl.t('settings.telematics.history-policy-unlimited');
+        return maximum > 0 ? this.intl.t('settings.telematics.history-policy-maximum', { days: maximum }) : this.intl.t('settings.telematics.history-policy-unlimited');
     }
 }
diff --git a/server/src/Http/Controllers/Api/v1/OrchestrationController.php b/server/src/Http/Controllers/Api/v1/OrchestrationController.php
index f6f5b9c27..025e7afd2 100644
--- a/server/src/Http/Controllers/Api/v1/OrchestrationController.php
+++ b/server/src/Http/Controllers/Api/v1/OrchestrationController.php
@@ -3,6 +3,7 @@
 namespace Fleetbase\FleetOps\Http\Controllers\Api\v1;
 
 use Fleetbase\FleetOps\Http\Controllers\Internal\v1\OrchestrationController as InternalOrchestrationController;
+use Fleetbase\FleetOps\Orchestration\OrchestrationEngineRegistry;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 
@@ -14,6 +15,14 @@
  */
 class OrchestrationController extends InternalOrchestrationController
 {
+    public function __construct(OrchestrationEngineRegistry $registry)
+    {
+        // The fleetbase.api route group authenticates API credentials and establishes
+        // their company scope. Console IAM middleware belongs to the internal
+        // workbench, not to these organization-credential endpoints.
+        $this->registry = $registry;
+    }
+
     public function run(Request $request): JsonResponse
     {
         return $this->publicResponse(parent::run($request));
diff --git a/server/tests/InternalImportExportControllerContractsTest.php b/server/tests/InternalImportExportControllerContractsTest.php
index 4994461e0..db8282592 100644
--- a/server/tests/InternalImportExportControllerContractsTest.php
+++ b/server/tests/InternalImportExportControllerContractsTest.php
@@ -269,14 +269,11 @@ function fleetopsExportSelections(object $export): array
     $controller = new FleetOpsInternalFuelReportControllerProbe();
     $fuelReport = new FleetOpsInternalFuelReportAfterSaveFake();
 
-    $controller->afterSave(new Request([
-        'fuel_report' => [
-            'custom_field_values' => [
-                ['key' => 'receipt_number', 'value' => 'R-100'],
-            ],
-        ],
-    ]), $fuelReport);
-    $controller->afterSave(new Request(['fuel_report' => ['custom_field_values' => []]]), $fuelReport);
+    $input = ['custom_field_values' => [['key' => 'receipt_number', 'value' => 'R-100']]];
+    $controller->afterSave(new Request(['fuelReport' => $input]), $fuelReport, $input);
+    $controller->afterSave(new Request(), $fuelReport, ['custom_field_values' => []]);
+    $controller->afterSave(new Request(), $fuelReport, ['custom_field_values' => 'invalid']);
+    $controller->afterSave(new Request(), $fuelReport);
 
     expect($fuelReport->synced)->toBe([
         [
diff --git a/server/tests/OrchestratorConsumableApiTest.php b/server/tests/OrchestratorConsumableApiTest.php
index c2638a460..6e283484c 100644
--- a/server/tests/OrchestratorConsumableApiTest.php
+++ b/server/tests/OrchestratorConsumableApiTest.php
@@ -2,6 +2,8 @@
 
 use Fleetbase\FleetOps\Http\Controllers\Api\v1\OrchestrationController;
 use Fleetbase\FleetOps\Orchestration\OrchestrationEngineRegistry;
+use Illuminate\Http\Exceptions\HttpResponseException;
+use Illuminate\Http\Request;
 
 function sanitize_orchestrator_payload(array $payload): array
 {
@@ -72,3 +74,43 @@ function assert_no_internal_orchestrator_identifiers(array $payload): void
     expect($routes)->toContain("\$router->post('run', 'OrchestrationController@run');");
     expect($routes)->toContain("\$router->post('commit', 'OrchestrationController@commit');");
 });
+
+test('public orchestration uses API authentication without inheriting console IAM middleware', function () {
+    $registry = new OrchestrationEngineRegistry();
+    $public   = new OrchestrationController($registry);
+    $internal = new Fleetbase\FleetOps\Http\Controllers\Internal\v1\OrchestrationController($registry);
+
+    expect($public->getMiddleware())->toBe([]);
+
+    // An API-key request has no console IAM role. The internal workbench must
+    // still refuse this actor; its middleware must not leak onto the API class.
+    app('session.store')->flush();
+    $request = Request::create('/int/v1/fleet-ops/orchestrator/run', 'POST');
+    app()->instance('request', $request);
+    foreach (['run', 'commit'] as $method) {
+        $guard = collect($internal->getMiddleware())->first(fn ($entry) => in_array($method, $entry['options']['only'], true));
+        expect($guard)->not->toBeNull();
+
+        try {
+            $guard['middleware']($request, fn () => throw new RuntimeException('Unauthorized request reached the workbench'));
+            test()->fail('The internal workbench must require a permitted user');
+        } catch (HttpResponseException $error) {
+            expect($error->getResponse()->getStatusCode())->toBe(401);
+        }
+    }
+});
+
+test('public orchestration resolves tenant scope from the authenticated session, never request input', function () {
+    $controller = new OrchestrationController(new OrchestrationEngineRegistry());
+    $company    = new ReflectionMethod($controller, 'companyUuid');
+    $company->setAccessible(true);
+    $request = Request::create('/v1/orchestrator/run', 'POST', ['company_uuid' => 'other-company']);
+    app()->instance('request', $request);
+
+    session(['company' => 'credential-company']);
+    expect($company->invoke($controller))->toBe('credential-company');
+
+    session(['company' => 'next-credential-company']);
+    expect($company->invoke($controller))->toBe('next-credential-company');
+    app('session.store')->flush();
+});

From 2f3a592665c3bc3ced0247e6e3f46292f386171d Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 17:02:09 +0800
Subject: [PATCH 19/24] fix: keep company settings compatible with released
 core

---
 .../src/Console/Commands/ProcessOperationalAlerts.php |  2 +-
 server/src/Listeners/NotifyDriverOnShiftChange.php    |  2 +-
 server/src/Mail/CustomerCredentialsMail.php           |  3 ++-
 .../Engines/VroomOrchestrationEngine.php              |  3 ++-
 server/src/Tracking/TrackingOptions.php               |  3 ++-
 server/tests/NotificationAndMailContractsTest.php     | 11 +++++++----
 .../VroomEngineTransportAndSettingsTest.php           |  9 +++++----
 .../Tracking/TrackingOptionsCompanySettingsTest.php   |  5 +++--
 8 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/server/src/Console/Commands/ProcessOperationalAlerts.php b/server/src/Console/Commands/ProcessOperationalAlerts.php
index c9ae5eab7..2dde1eaea 100644
--- a/server/src/Console/Commands/ProcessOperationalAlerts.php
+++ b/server/src/Console/Commands/ProcessOperationalAlerts.php
@@ -258,7 +258,7 @@ protected function minimumDistanceToRoute(Point $position, array $routePoints):
 
     protected function alertSettings(Order $order): array
     {
-        $settings = Setting::lookupForCompany($order->company_uuid, 'tracking', []);
+        $settings = $order->company_uuid ? Setting::lookup('company.' . $order->company_uuid . '.tracking', []) : [];
         $alerts   = data_get($settings, 'alerts', []);
 
         return [
diff --git a/server/src/Listeners/NotifyDriverOnShiftChange.php b/server/src/Listeners/NotifyDriverOnShiftChange.php
index c7fe03245..0af620b80 100644
--- a/server/src/Listeners/NotifyDriverOnShiftChange.php
+++ b/server/src/Listeners/NotifyDriverOnShiftChange.php
@@ -68,7 +68,7 @@ protected function getSchedule(ScheduleItem $scheduleItem): ?Schedule
 
     protected function getSchedulingSettings(?string $companyUuid): array
     {
-        return Setting::lookupForCompany($companyUuid, 'fleet-ops.scheduling-settings', []);
+        return $companyUuid ? Setting::lookup('company.' . $companyUuid . '.fleet-ops.scheduling-settings', []) : [];
     }
 
     protected function isCreatedEvent(object $event): bool
diff --git a/server/src/Mail/CustomerCredentialsMail.php b/server/src/Mail/CustomerCredentialsMail.php
index af197524e..34cf9fc7c 100644
--- a/server/src/Mail/CustomerCredentialsMail.php
+++ b/server/src/Mail/CustomerCredentialsMail.php
@@ -72,7 +72,8 @@ public function content(): Content
      */
     private function getCustomerPortalAccessUrl(): string
     {
-        $customerPortalConfig = Setting::lookupForCompany($this->customer->company_uuid, 'customer-portal-config');
+        $companyUuid          = $this->customer->company_uuid;
+        $customerPortalConfig = $companyUuid ? Setting::lookup('company.' . $companyUuid . '.customer-portal-config') : null;
         $accessUrlSlug        = data_get($customerPortalConfig, 'accessUrlSlug', 'customer-portal');
 
         return Utils::consoleUrl($accessUrlSlug ?: 'customer-portal');
diff --git a/server/src/Orchestration/Engines/VroomOrchestrationEngine.php b/server/src/Orchestration/Engines/VroomOrchestrationEngine.php
index ecb3e74b9..8b8356146 100644
--- a/server/src/Orchestration/Engines/VroomOrchestrationEngine.php
+++ b/server/src/Orchestration/Engines/VroomOrchestrationEngine.php
@@ -528,7 +528,8 @@ protected function resolveVroomEndpointMode(): string
     protected function resolveVroomSetting(string $key, $default = null)
     {
         try {
-            $organizationValue = data_get(Setting::lookupForCompany($this->companyUuid ?? session('company'), 'vroom', []), $key);
+            $companyUuid       = $this->companyUuid ?? session('company');
+            $organizationValue = $companyUuid ? data_get(Setting::lookup('company.' . $companyUuid . '.vroom', []), $key) : null;
             if ($this->hasConfiguredValue($organizationValue)) {
                 return $organizationValue;
             }
diff --git a/server/src/Tracking/TrackingOptions.php b/server/src/Tracking/TrackingOptions.php
index 66cca97ac..6e3f5f5fc 100644
--- a/server/src/Tracking/TrackingOptions.php
+++ b/server/src/Tracking/TrackingOptions.php
@@ -30,7 +30,8 @@ public static function fromArray(array $options = [], ?string $companyUuid = nul
         $config          = array_merge(config('fleetops.tracking', []), is_array($systemSettings) ? $systemSettings : []);
         $companySettings = [];
         try {
-            $companySettings = Setting::lookupForCompany($companyUuid ?? session('company'), 'tracking', []);
+            $companyUuid     = $companyUuid ?? session('company');
+            $companySettings = $companyUuid ? Setting::lookup('company.' . $companyUuid . '.tracking', []) : [];
         } catch (\Throwable) {
             $companySettings = [];
         }
diff --git a/server/tests/NotificationAndMailContractsTest.php b/server/tests/NotificationAndMailContractsTest.php
index b84abe02d..8539b5620 100644
--- a/server/tests/NotificationAndMailContractsTest.php
+++ b/server/tests/NotificationAndMailContractsTest.php
@@ -676,11 +676,11 @@ public function track(Order $order, mixed $options): array
         ]);
 });
 
-test('customer credentials mail reads the portal slug from the customer company without a session', function () {
+test('customer credentials mail reads the portal slug from the customer company regardless of session', function (?string $sessionCompany) {
     app('config')->set('fleetbase.console.host', 'console.fleetbase.test');
     app('config')->set('fleetbase.console.secure', true);
     app('config')->set('fleetbase.console.subdomain', null);
-    app('session.store')->forget('company');
+    app('session.store')->put('company', $sessionCompany);
 
     $connection = new Illuminate\Database\SQLiteConnection(new PDO('sqlite::memory:'));
     $resolver   = new Illuminate\Database\ConnectionResolver(['default' => $connection, 'mysql' => $connection]);
@@ -692,7 +692,10 @@ public function track(Order $order, mixed $options): array
         $blueprint->text('value')->nullable();
         $blueprint->timestamps();
     });
-    $connection->table('settings')->insert(['key' => 'company.company-portal.customer-portal-config', 'value' => json_encode(['accessUrlSlug' => 'acme-portal'])]);
+    $connection->table('settings')->insert([
+        ['key' => 'company.company-portal.customer-portal-config', 'value' => json_encode(['accessUrlSlug' => 'acme-portal'])],
+        ['key' => 'company.other-company.customer-portal-config', 'value' => json_encode(['accessUrlSlug' => 'other-portal'])],
+    ]);
 
     $customer              = new FleetOpsNotificationContactFake();
     $customer->userForTest = new User();
@@ -702,4 +705,4 @@ public function track(Order $order, mixed $options): array
     $content = fleetOpsNotificationWithEnvironment(fn () => (new CustomerCredentialsMail('plain-secret', $customer))->content());
 
     expect($content->with['customerPortalUrl'])->toBe('https://console.fleetbase.test/acme-portal');
-});
+})->with([null, 'other-company']);
diff --git a/server/tests/Unit/Orchestration/VroomEngineTransportAndSettingsTest.php b/server/tests/Unit/Orchestration/VroomEngineTransportAndSettingsTest.php
index a1c020e54..40fefa5d8 100644
--- a/server/tests/Unit/Orchestration/VroomEngineTransportAndSettingsTest.php
+++ b/server/tests/Unit/Orchestration/VroomEngineTransportAndSettingsTest.php
@@ -252,10 +252,11 @@ function fleetopsVroomVehicle(string $publicId, Point $location): Vehicle
         ->and($call('resolveVroomApiKey'))->toBeIn([null, '']);
 });
 
-test('allocation resolves organization settings from the orders company without a session', function () {
+test('allocation resolves organization settings from the orders company regardless of session', function (?string $sessionCompany) {
     $connection = fleetopsVroomBoot();
     $connection->table('settings')->insert([
         ['key' => 'company.company-2.vroom', 'value' => json_encode(['api_host' => 'https://company-two-vroom.test'])],
+        ['key' => 'company.company-1.vroom', 'value' => json_encode(['api_host' => 'https://company-one-vroom.test'])],
     ]);
 
     $order = fleetopsVroomOrder('order_vroom_queued', fleetopsVroomPlace('p-9', new Point(1.31, 103.81)), null);
@@ -264,9 +265,9 @@ function fleetopsVroomVehicle(string $publicId, Point $location): Vehicle
 
     Http::fake(['*' => Http::response(['routes' => [], 'unassigned' => [], 'summary' => []], 200)]);
 
-    // Queued allocation runs (ProcessAllocationJob) have no company session
-    session(['company' => null]);
+    // Background allocation must not depend on an absent or unrelated session.
+    session(['company' => $sessionCompany]);
     (new VroomOrchestrationEngine())->allocate(collect([$order]), collect([$vehicle]));
 
     Http::assertSent(fn ($request) => str_starts_with($request->url(), 'https://company-two-vroom.test'));
-});
+})->with([null, 'company-1']);
diff --git a/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php b/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php
index cc2fcf8fd..225e3bb40 100644
--- a/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php
+++ b/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php
@@ -41,8 +41,9 @@ function fleetopsTrackingOptionsBoot(): SQLiteConnection
     return $connection;
 }
 
-test('tracking options read the given company settings without a company session', function () {
+test('tracking options read the given company settings regardless of session', function (?string $sessionCompany) {
     fleetopsTrackingOptionsBoot();
+    session(['company' => $sessionCompany]);
 
     $options = TrackingOptions::fromArray([], 'company-a');
 
@@ -51,7 +52,7 @@ function fleetopsTrackingOptionsBoot(): SQLiteConnection
 
     // Explicit options still win over company settings
     expect(TrackingOptions::fromArray(['provider' => 'google'], 'company-a')->provider)->toBe('google');
-});
+})->with([null, 'company-b']);
 
 test('tracking options fall back to the session company when no company is given', function () {
     fleetopsTrackingOptionsBoot();

From 85bafa0104f1d0b5889917f6458e4b6e7d7b7865 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 17:06:44 +0800
Subject: [PATCH 20/24] fix: restore Core company settings API for coordinated
 release

---
 server/src/Console/Commands/ProcessOperationalAlerts.php      | 2 +-
 server/src/Listeners/NotifyDriverOnShiftChange.php            | 2 +-
 server/src/Mail/CustomerCredentialsMail.php                   | 3 +--
 server/src/Orchestration/Engines/VroomOrchestrationEngine.php | 3 +--
 server/src/Tracking/TrackingOptions.php                       | 3 +--
 5 files changed, 5 insertions(+), 8 deletions(-)

diff --git a/server/src/Console/Commands/ProcessOperationalAlerts.php b/server/src/Console/Commands/ProcessOperationalAlerts.php
index 2dde1eaea..c9ae5eab7 100644
--- a/server/src/Console/Commands/ProcessOperationalAlerts.php
+++ b/server/src/Console/Commands/ProcessOperationalAlerts.php
@@ -258,7 +258,7 @@ protected function minimumDistanceToRoute(Point $position, array $routePoints):
 
     protected function alertSettings(Order $order): array
     {
-        $settings = $order->company_uuid ? Setting::lookup('company.' . $order->company_uuid . '.tracking', []) : [];
+        $settings = Setting::lookupForCompany($order->company_uuid, 'tracking', []);
         $alerts   = data_get($settings, 'alerts', []);
 
         return [
diff --git a/server/src/Listeners/NotifyDriverOnShiftChange.php b/server/src/Listeners/NotifyDriverOnShiftChange.php
index 0af620b80..c7fe03245 100644
--- a/server/src/Listeners/NotifyDriverOnShiftChange.php
+++ b/server/src/Listeners/NotifyDriverOnShiftChange.php
@@ -68,7 +68,7 @@ protected function getSchedule(ScheduleItem $scheduleItem): ?Schedule
 
     protected function getSchedulingSettings(?string $companyUuid): array
     {
-        return $companyUuid ? Setting::lookup('company.' . $companyUuid . '.fleet-ops.scheduling-settings', []) : [];
+        return Setting::lookupForCompany($companyUuid, 'fleet-ops.scheduling-settings', []);
     }
 
     protected function isCreatedEvent(object $event): bool
diff --git a/server/src/Mail/CustomerCredentialsMail.php b/server/src/Mail/CustomerCredentialsMail.php
index 34cf9fc7c..af197524e 100644
--- a/server/src/Mail/CustomerCredentialsMail.php
+++ b/server/src/Mail/CustomerCredentialsMail.php
@@ -72,8 +72,7 @@ public function content(): Content
      */
     private function getCustomerPortalAccessUrl(): string
     {
-        $companyUuid          = $this->customer->company_uuid;
-        $customerPortalConfig = $companyUuid ? Setting::lookup('company.' . $companyUuid . '.customer-portal-config') : null;
+        $customerPortalConfig = Setting::lookupForCompany($this->customer->company_uuid, 'customer-portal-config');
         $accessUrlSlug        = data_get($customerPortalConfig, 'accessUrlSlug', 'customer-portal');
 
         return Utils::consoleUrl($accessUrlSlug ?: 'customer-portal');
diff --git a/server/src/Orchestration/Engines/VroomOrchestrationEngine.php b/server/src/Orchestration/Engines/VroomOrchestrationEngine.php
index 8b8356146..ecb3e74b9 100644
--- a/server/src/Orchestration/Engines/VroomOrchestrationEngine.php
+++ b/server/src/Orchestration/Engines/VroomOrchestrationEngine.php
@@ -528,8 +528,7 @@ protected function resolveVroomEndpointMode(): string
     protected function resolveVroomSetting(string $key, $default = null)
     {
         try {
-            $companyUuid       = $this->companyUuid ?? session('company');
-            $organizationValue = $companyUuid ? data_get(Setting::lookup('company.' . $companyUuid . '.vroom', []), $key) : null;
+            $organizationValue = data_get(Setting::lookupForCompany($this->companyUuid ?? session('company'), 'vroom', []), $key);
             if ($this->hasConfiguredValue($organizationValue)) {
                 return $organizationValue;
             }
diff --git a/server/src/Tracking/TrackingOptions.php b/server/src/Tracking/TrackingOptions.php
index 6e3f5f5fc..66cca97ac 100644
--- a/server/src/Tracking/TrackingOptions.php
+++ b/server/src/Tracking/TrackingOptions.php
@@ -30,8 +30,7 @@ public static function fromArray(array $options = [], ?string $companyUuid = nul
         $config          = array_merge(config('fleetops.tracking', []), is_array($systemSettings) ? $systemSettings : []);
         $companySettings = [];
         try {
-            $companyUuid     = $companyUuid ?? session('company');
-            $companySettings = $companyUuid ? Setting::lookup('company.' . $companyUuid . '.tracking', []) : [];
+            $companySettings = Setting::lookupForCompany($companyUuid ?? session('company'), 'tracking', []);
         } catch (\Throwable) {
             $companySettings = [];
         }

From 999b956a3b2d5fdf2f2afc128207d565e8dab4f0 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 17:56:54 +0800
Subject: [PATCH 21/24] test: cover authorization and isolate telematics
 request fixtures

---
 .../tests/SettingControllerContractsTest.php  |   9 +-
 .../tests/Unit/Support/AuthorizationTest.php  | 128 ++++++++++++++++++
 2 files changed, 135 insertions(+), 2 deletions(-)
 create mode 100644 server/tests/Unit/Support/AuthorizationTest.php

diff --git a/server/tests/SettingControllerContractsTest.php b/server/tests/SettingControllerContractsTest.php
index bfe60a305..bfba1ffbc 100644
--- a/server/tests/SettingControllerContractsTest.php
+++ b/server/tests/SettingControllerContractsTest.php
@@ -598,7 +598,8 @@ function fleetopsJsonPayload(mixed $response): array
 });
 
 test('admin telematics storage and cleanup cover the system without a company session', function () {
-    $originalRequest     = app('request');
+    $hadRequest          = app()->bound('request');
+    $originalRequest     = $hadRequest ? app('request') : null;
     $originalQueueConfig = config('queue', []);
     config(['queue.default' => 'database', 'queue.connections.database.driver' => 'database']);
     app()->instance('request', new Request(['include_payload_counts' => true]));
@@ -645,7 +646,11 @@ function fleetopsJsonPayload(mixed $response): array
             ->and(fleetopsJsonPayload($queued)['scope'])->toBe('system')
             ->and($controller->pruned)->toBe(['system']);
     } finally {
-        app()->instance('request', $originalRequest);
+        if ($hadRequest) {
+            app()->instance('request', $originalRequest);
+        } else {
+            app()->forgetInstance('request');
+        }
         config(['queue' => $originalQueueConfig]);
         Illuminate\Support\Carbon::setTestNow();
     }
diff --git a/server/tests/Unit/Support/AuthorizationTest.php b/server/tests/Unit/Support/AuthorizationTest.php
new file mode 100644
index 000000000..edbae6a3c
--- /dev/null
+++ b/server/tests/Unit/Support/AuthorizationTest.php
@@ -0,0 +1,128 @@
+<?php
+
+use Fleetbase\FleetOps\Support\Authorization;
+use Fleetbase\FleetOps\Traits\AuthorizesMethods;
+use Fleetbase\Models\User;
+use Illuminate\Database\ConnectionResolver;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\SQLiteConnection;
+use Illuminate\Http\Exceptions\HttpResponseException;
+use Illuminate\Http\Request;
+use Illuminate\Routing\Controller;
+
+if (!function_exists('Fleetbase\\Support\\auth')) {
+    eval('namespace Fleetbase\\Support; function auth() { return \\app("fleetops.authorization.test-auth"); }');
+}
+
+if (!function_exists('Fleetbase\\Support\\session')) {
+    eval('namespace Fleetbase\\Support; function session($key = null, $default = null) { return \\session($key, $default); }');
+}
+
+class FleetOpsAuthorizationUser extends User
+{
+    public array $grantedPermissions        = [];
+    public bool $permissionStoreUnavailable = false;
+
+    public function hasPermissionTo($permission, $guardName = null): bool
+    {
+        if ($this->permissionStoreUnavailable) {
+            throw new RuntimeException('Permission store unavailable');
+        }
+
+        return in_array($permission->name, $this->grantedPermissions, true);
+    }
+}
+
+beforeEach(function () {
+    $connection = new SQLiteConnection(new PDO('sqlite::memory:'));
+    $resolver   = new ConnectionResolver(['mysql' => $connection]);
+    $resolver->setDefaultConnection('mysql');
+    Model::setConnectionResolver($resolver);
+    config()->set('auth.defaults.guard', 'sanctum');
+    config()->set('permission.table_names.permissions', 'permissions');
+    $connection->getSchemaBuilder()->create('permissions', function ($table) {
+        $table->string('id')->primary();
+        $table->string('name');
+        $table->string('guard_name')->default('sanctum');
+    });
+    $connection->table('permissions')->insert([
+        ['id' => 'optimize', 'name' => 'fleet-ops optimize order'],
+        ['id' => 'dispatch', 'name' => 'fleet-ops dispatch order'],
+        ['id' => 'resource', 'name' => 'fleet-ops * order'],
+        ['id' => 'service', 'name' => 'fleet-ops *'],
+    ]);
+    session(['user' => null]);
+    $this->user = new FleetOpsAuthorizationUser();
+    $this->user->setRawAttributes(['type' => 'user'], true);
+    $this->auth = new class($this->user) {
+        public bool $unavailable = false;
+
+        public function __construct(public ?User $currentUser)
+        {
+        }
+
+        public function user(): ?User
+        {
+            if ($this->unavailable) {
+                throw new RuntimeException('Session unavailable');
+            }
+
+            return $this->currentUser;
+        }
+    };
+    app()->instance('fleetops.authorization.test-auth', $this->auth);
+});
+
+test('operation authorization accepts exact and wildcard grants', function (string $grant) {
+    $this->user->grantedPermissions = [$grant];
+
+    expect(Authorization::canAny('optimize order'))->toBeTrue();
+    Authorization::authorize('optimize order');
+})->with(['fleet-ops optimize order', 'fleet-ops * order', 'fleet-ops *']);
+
+test('operation authorization accepts any requested permission and rejects missing grants', function () {
+    $this->user->grantedPermissions = ['fleet-ops dispatch order'];
+
+    expect(Authorization::canAny('optimize order'))->toBeFalse()
+        ->and(Authorization::canAny('optimize order', 'dispatch order'))->toBeTrue()
+        ->and(Authorization::canAny('list unseeded-resource'))->toBeTrue();
+    expect(fn () => Authorization::authorize('optimize order'))->toThrow(HttpResponseException::class);
+
+    $this->user->permissionStoreUnavailable = true;
+    expect(Authorization::canAny('dispatch order'))->toBeFalse();
+});
+
+test('platform administrators pass operations while system settings reject ordinary users', function () {
+    expect(fn () => Authorization::authorizeAdmin())->toThrow(HttpResponseException::class);
+    $this->user->setAttribute('type', 'admin');
+    expect(Authorization::canAny('optimize order'))->toBeTrue();
+    Authorization::authorizeAdmin();
+});
+
+test('authorization fails closed when the authenticated user is missing or cannot be read', function () {
+    $this->auth->currentUser = null;
+    expect(Authorization::canAny('optimize order'))->toBeFalse();
+    expect(fn () => Authorization::authorizeAdmin())->toThrow(HttpResponseException::class);
+    $this->auth->unavailable = true;
+    expect(Authorization::canAny('optimize order'))->toBeFalse();
+});
+
+test('controller middleware applies the mapped operation and administrator checks', function () {
+    $controller = new class extends Controller {
+        use AuthorizesMethods;
+
+        public function __construct()
+        {
+            $this->authorizeMethods(['optimize' => ['optimize order', 'dispatch order'], 'settings' => 'admin']);
+        }
+    };
+    $middleware                     = $controller->getMiddleware();
+    $request                        = Request::create('/');
+    $this->user->grantedPermissions = ['fleet-ops dispatch order'];
+
+    expect($middleware[0]['options']['only'])->toBe(['optimize'])
+        ->and($middleware[0]['middleware']($request, fn ($nextRequest) => $nextRequest))->toBe($request);
+    expect(fn () => $middleware[1]['middleware']($request, fn () => 'allowed'))->toThrow(HttpResponseException::class);
+    $this->user->setAttribute('type', 'admin');
+    expect($middleware[1]['middleware']($request, fn () => 'allowed'))->toBe('allowed');
+});

From 779dc0c742ac4979a8e2e9a5fef5de4d51fa97a0 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 17:58:15 +0800
Subject: [PATCH 22/24] ci: resolve release dependencies in API contracts

---
 .github/workflows/postman.yml | 14 +++++---------
 .github/workflows/server.yml  |  3 ++-
 2 files changed, 7 insertions(+), 10 deletions(-)

diff --git a/.github/workflows/postman.yml b/.github/workflows/postman.yml
index 24e38fe88..d58143299 100644
--- a/.github/workflows/postman.yml
+++ b/.github/workflows/postman.yml
@@ -5,14 +5,9 @@ name: API Contract (Postman)
 # fleetbase/fleetbase. Requires org secrets POSTMAN_API_KEY + _GITHUB_AUTH_TOKEN
 # (inherited); no-ops until POSTMAN_API_KEY is set.
 #
-# Deliberately unpinned. The reusable workflow defaults to booting fleetbase/fleetbase@main
-# against fleetbase/fleetbase-api:latest, so every release is picked up automatically and
-# there is no ref here to remember to bump. Each run records the image digest it actually
-# resolved in its job summary, so a result stays traceable. To reproduce an older run:
-#
-#   with:
-#     fleetbase-ref: v0.7.53
-#     api-image: fleetbase/fleetbase-api:v0.7.53
+# Pin the workflow and host checkout together so branch installation resolves the
+# required published Core release before migrating and exercising this module.
+# The workflow records the API image digest and resolved dependencies for traceability.
 
 on:
   push:
@@ -25,8 +20,9 @@ permissions:
 
 jobs:
   contract:
-    uses: fleetbase/fleetbase/.github/workflows/api-contract.yml@main
+    uses: fleetbase/fleetbase/.github/workflows/api-contract.yml@880c7392c67c93e3a65f01916d7a04036c098935
     with:
+      fleetbase-ref: 880c7392c67c93e3a65f01916d7a04036c098935
       collections: "Fleetbase API"
       build-from-source: false
       # Without this the run tests the version of fleetbase/fleetops-api baked into the
diff --git a/.github/workflows/server.yml b/.github/workflows/server.yml
index 84eb44839..e9699443b 100644
--- a/.github/workflows/server.yml
+++ b/.github/workflows/server.yml
@@ -14,7 +14,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Setup PHP
       uses: shivammathur/setup-php@v2
@@ -53,6 +53,7 @@ jobs:
       run: php scripts/coverage-summary.php coverage/clover.xml --fail-under=100
 
     - name: Upload Coverage Baseline
+      if: ${{ always() && hashFiles('coverage/clover.xml') != '' }}
       uses: actions/upload-artifact@v4
       with:
         name: fleetops-coverage-clover

From 60016b3dd7b1f25ab919e8d23536ddb2ff9e5c77 Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 18:07:12 +0800
Subject: [PATCH 23/24] test: pass normalized custom fields to service area
 lifecycle

---
 server/tests/SmallControllerContractsTest.php | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/server/tests/SmallControllerContractsTest.php b/server/tests/SmallControllerContractsTest.php
index 682ba2c18..a55c96d93 100644
--- a/server/tests/SmallControllerContractsTest.php
+++ b/server/tests/SmallControllerContractsTest.php
@@ -383,11 +383,14 @@ function fleetopsSmallExportSelections(object $export): array
 });
 
 test('service area zone and getting started controllers expose small lifecycle contracts', function () {
-    $serviceArea = new FleetOpsControllerCustomFieldModelFake();
-    (new ServiceAreaController())->afterSave(new Request([
-        'service_area' => ['custom_field_values' => [['key' => 'area_code', 'value' => 'A1']]],
-    ]), $serviceArea);
-    (new ServiceAreaController())->afterSave(new Request(['service_area' => ['custom_field_values' => []]]), $serviceArea);
+    $serviceArea        = new FleetOpsControllerCustomFieldModelFake();
+    $serviceAreaRequest = new Request([
+        'serviceArea' => ['custom_field_values' => [['key' => 'area_code', 'value' => 'raw-request-value']]],
+    ]);
+    (new ServiceAreaController())->afterSave($serviceAreaRequest, $serviceArea, [
+        'custom_field_values' => [['key' => 'area_code', 'value' => 'A1']],
+    ]);
+    (new ServiceAreaController())->afterSave($serviceAreaRequest, $serviceArea, ['custom_field_values' => []]);
 
     $zone = new FleetOpsControllerZoneFake();
     (new ZoneController())->afterSave(new Request([

From ec6ab05b1814a8d4f73f22d22376192d3bfbe94d Mon Sep 17 00:00:00 2001
From: "Ronald A. Richardson" <me@ron.dev>
Date: Mon, 28 Sep 2026 18:24:30 +0800
Subject: [PATCH 24/24] test: cover telematics policy persistence and storage
 deadlines

---
 .../Internal/v1/SettingController.php         |   4 +-
 .../Internal/SettingControllerHelpersTest.php |  71 +++++++++++
 .../TelematicsStorageDeadlinesTest.php        | 119 ++++++++++++++++++
 .../tests/SettingControllerContractsTest.php  |  83 +++++++++---
 .../PruneTelematicsDataCommandTest.php        |  13 +-
 .../DispatchTelematicsRetentionJobsTest.php   |  63 +++++++++-
 .../tests/Unit/Support/AuthorizationTest.php  |  14 +++
 .../TrackingOptionsCompanySettingsTest.php    |  14 +++
 8 files changed, 355 insertions(+), 26 deletions(-)
 create mode 100644 server/tests/Feature/Http/Internal/TelematicsStorageDeadlinesTest.php

diff --git a/server/src/Http/Controllers/Internal/v1/SettingController.php b/server/src/Http/Controllers/Internal/v1/SettingController.php
index afe3a7525..296363a07 100644
--- a/server/src/Http/Controllers/Internal/v1/SettingController.php
+++ b/server/src/Http/Controllers/Internal/v1/SettingController.php
@@ -1013,9 +1013,7 @@ protected function storageUsageSelect(string $sql, array $bindings = [], bool $e
         $isMariaDb  = $driver === 'mariadb';
 
         if ($connection instanceof MySqlConnection) {
-            $isMariaDb = method_exists($connection, 'isMaria')
-                ? $connection->isMaria()
-                : stripos((string) $connection->getReadPdo()->getAttribute(\PDO::ATTR_SERVER_VERSION), 'MariaDB') !== false;
+            $isMariaDb = stripos((string) $connection->getReadPdo()->getAttribute(\PDO::ATTR_SERVER_VERSION), 'MariaDB') !== false;
         }
 
         if ($isMariaDb) {
diff --git a/server/tests/Feature/Http/Internal/SettingControllerHelpersTest.php b/server/tests/Feature/Http/Internal/SettingControllerHelpersTest.php
index 8556b0b4f..ccd6651ea 100644
--- a/server/tests/Feature/Http/Internal/SettingControllerHelpersTest.php
+++ b/server/tests/Feature/Http/Internal/SettingControllerHelpersTest.php
@@ -131,3 +131,74 @@ public function __call($method, $arguments)
         ->and($helper('notificationsByPackage', 'fleet-ops'))->toBeArray()
         ->and($helper('trackingProviders'))->toBeArray();
 });
+
+test('history policy reconciliation clamps every organization and preserves inherited and internal settings', function () {
+    $connection = fleetopsSettingHelpersBoot();
+    $key        = Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy::SETTING_KEY;
+    $controller = new class extends SettingController {
+        public ?Closure $beforeLock = null;
+
+        public function reconcile(array $defaults): void
+        {
+            $this->reconcileTelematicsCompanyPreferences($defaults);
+        }
+
+        public function lock(Closure $callback): mixed
+        {
+            return parent::withTelematicsPolicyLock($callback);
+        }
+
+        protected function withTelematicsPolicyLock(Closure $callback): mixed
+        {
+            if ($this->beforeLock) {
+                ($this->beforeLock)();
+                $this->beforeLock = null;
+            }
+
+            return parent::withTelematicsPolicyLock($callback);
+        }
+
+        protected function telematicsDefaults(): array
+        {
+            return ['max_event_retention_days' => 90, 'max_position_retention_days' => 360];
+        }
+    };
+    // The first write creates the lock anchor; subsequent writes reuse it.
+    expect($controller->lock(fn () => 'saved'))->toBe('saved');
+    expect($controller->lock(fn () => $connection->transactionLevel()))->toBe(1)
+        ->and($connection->table('settings')->where('key', $key)->count())->toBe(1);
+    foreach ([
+        'a' => ['event_retention_days' => 0, 'position_retention_days' => 900, 'log_telemetry_activity' => true],
+        'b' => ['event_retention_days' => 30],
+        'c' => [],
+    ] as $company => $preferences) {
+        $connection->table('settings')->insert(['key' => "company.$company.$key", 'value' => json_encode($preferences)]);
+    }
+    $controller->reconcile(['max_event_retention_days' => 0, 'max_position_retention_days' => 0]);
+    $read = fn ($company) => json_decode($connection->table('settings')->where('key', "company.$company.$key")->value('value'), true);
+    expect($read('a')['event_retention_days'])->toBe(0);
+    $controller->reconcile(['max_event_retention_days' => 90, 'max_position_retention_days' => 360]);
+    expect($read('a'))->toBe(['event_retention_days' => 90, 'position_retention_days' => 360, 'log_telemetry_activity' => true])
+        ->and($read('b'))->toBe(['event_retention_days' => 30])->and($read('c'))->toBe([]);
+    // A tenant removed after the batch is read must not be recreated.
+    $controller->beforeLock = fn () => $connection->table('settings')->where('key', "company.a.$key")->delete();
+    $controller->reconcile(['max_event_retention_days' => 90]);
+    expect($connection->table('settings')->where('key', "company.a.$key")->exists())->toBeFalse();
+});
+
+test('company order configuration keys exclude other tenants and deleted configurations', function () {
+    $connection = fleetopsSettingHelpersBoot();
+    $connection->getSchemaBuilder()->create('order_configs', function ($table) {
+        $table->increments('id');
+        $table->string('uuid');
+        $table->string('public_id')->nullable();
+        $table->string('company_uuid');
+        $table->softDeletes();
+    });
+    $connection->table('order_configs')->insert([
+        ['uuid' => 'own', 'public_id' => 'own-public', 'company_uuid' => 'company-1', 'deleted_at' => null],
+        ['uuid' => 'other', 'public_id' => 'other-public', 'company_uuid' => 'company-2', 'deleted_at' => null],
+        ['uuid' => 'deleted', 'public_id' => null, 'company_uuid' => 'company-1', 'deleted_at' => '2026-01-01'],
+    ]);
+    expect((new ReflectionMethod(SettingController::class, 'companyOrderConfigKeys'))->invoke(new SettingController()))->toBe(['own', 'own-public']);
+});
diff --git a/server/tests/Feature/Http/Internal/TelematicsStorageDeadlinesTest.php b/server/tests/Feature/Http/Internal/TelematicsStorageDeadlinesTest.php
new file mode 100644
index 000000000..46cf39f51
--- /dev/null
+++ b/server/tests/Feature/Http/Internal/TelematicsStorageDeadlinesTest.php
@@ -0,0 +1,119 @@
+<?php
+
+use Fleetbase\FleetOps\Http\Controllers\Internal\v1\SettingController;
+use Illuminate\Database\MySqlConnection;
+use Illuminate\Database\QueryException;
+use Illuminate\Support\Facades\DB;
+
+class FleetOpsStorageDeadlineConnection extends MySqlConnection
+{
+    public array $queries   = [];
+    public array $responses = [];
+    public bool $maria      = false;
+
+    public function getReadPdo()
+    {
+        return new class($this->maria) extends PDO {
+            public function __construct(private bool $maria)
+            {
+            }
+
+            public function getAttribute(int $attribute): mixed
+            {
+                if ($attribute !== PDO::ATTR_SERVER_VERSION) {
+                    throw new LogicException('Only the database server version should be read');
+                }
+
+                return $this->maria ? '10.11.8-MariaDB' : '8.0.40';
+            }
+        };
+    }
+
+    public function select($query, $bindings = [], $useReadPdo = true)
+    {
+        $this->queries[] = [$query, $bindings];
+        $response        = array_shift($this->responses) ?? [];
+        if ($response instanceof Throwable) {
+            throw $response;
+        }
+
+        return $response;
+    }
+}
+
+function fleetopsStorageQueryError(int $code): QueryException
+{
+    $error            = new PDOException('Database query failed');
+    $error->errorInfo = ['HY000', $code, 'Database query failed'];
+
+    return new QueryException('mysql', 'select history', [], $error);
+}
+
+beforeEach(function () {
+    $this->originalDb = app()->bound('db') ? app('db') : null;
+    $this->connection = new FleetOpsStorageDeadlineConnection(new PDO('sqlite::memory:'), '', '', ['driver' => 'mysql']);
+    $connection       = $this->connection;
+    app()->instance('db', new class($connection) {
+        public function __construct(public $database)
+        {
+        }
+
+        public function connection($name = null)
+        {
+            return $this->database;
+        }
+
+        public function __call($method, $args)
+        {
+            return $this->database->{$method}(...$args);
+        }
+    });
+    DB::clearResolvedInstance('db');
+    $this->controller = new SettingController();
+    $this->invoke     = fn ($method, ...$arguments) => (new ReflectionMethod(SettingController::class, $method))->invoke($this->controller, ...$arguments);
+    $this->scope      = fn ($query) => $query->where('company_uuid', 'company-a');
+});
+
+afterEach(function () {
+    if ($this->originalDb) {
+        app()->instance('db', $this->originalDb);
+    } else {
+        app()->forgetInstance('db');
+    }
+    DB::clearResolvedInstance('db');
+});
+
+test('storage scans enforce driver specific deadlines while preserving bindings', function (bool $maria) {
+    $this->connection->maria     = $maria;
+    $this->connection->responses = [[(object) ['row_count' => '4', 'oldest' => '2026-01-01']], [(object) ['rows' => 4]]];
+    expect(($this->invoke)('tableUsage', 'device_events', $this->scope, 'created_at'))->toBe(['rows' => 4, 'oldest' => '2026-01-01']);
+    ($this->invoke)('storageUsageSelect', 'select * from device_events where company_uuid = ?', ['company-a'], true);
+    expect($this->connection->queries[0][1])->toBe(['company-a'])
+        ->and($this->connection->queries[0][0])->toStartWith($maria ? 'SET STATEMENT max_statement_time=1 FOR select' : 'SELECT /*+ MAX_EXECUTION_TIME(1000) */')
+        ->and($this->connection->queries[1][0])->toStartWith($maria ? 'SET STATEMENT max_statement_time=1 FOR EXPLAIN select' : 'EXPLAIN SELECT /*+ MAX_EXECUTION_TIME(1000) */')
+        ->and($this->connection->queries[1][1])->toBe(['company-a']);
+})->with([false, true]);
+
+test('timed out counts use a scoped query plan estimate instead of another history scan', function () {
+    $this->connection->responses = [fleetopsStorageQueryError(3024), [(object) ['rows' => 101, 'filtered' => 25]]];
+    expect(($this->invoke)('tableUsage', 'device_events', $this->scope, 'created_at'))->toBe(['rows' => 25, 'oldest' => null, 'rows_estimated' => true])
+        ->and($this->connection->queries[1][0])->toStartWith('EXPLAIN SELECT')
+        ->and($this->connection->queries[1][1])->toBe(['company-a']);
+    $this->connection->responses = [fleetopsStorageQueryError(1969), fleetopsStorageQueryError(1969)];
+    expect(($this->invoke)('tableUsage', 'device_events', $this->scope, 'created_at'))->toBe(['rows' => null, 'oldest' => null, 'rows_estimated' => true]);
+});
+
+test('storage queries suppress only timeout errors and retain real database failures', function () {
+    foreach (['tableUsage', 'tableOldest'] as $method) {
+        $this->connection->responses = [fleetopsStorageQueryError(1146)];
+        expect(fn () => ($this->invoke)($method, 'device_events', $this->scope, 'created_at'))->toThrow(QueryException::class);
+    }
+    $this->connection->responses = [fleetopsStorageQueryError(3024), fleetopsStorageQueryError(1146)];
+    expect(fn () => ($this->invoke)('tableUsage', 'device_events', $this->scope, 'created_at'))->toThrow(QueryException::class);
+    $this->connection->responses = [fleetopsStorageQueryError(3024)];
+    expect(($this->invoke)('tableOldest', 'device_events', $this->scope, 'created_at'))->toBeNull();
+    $this->connection->responses = [fleetopsStorageQueryError(1969)];
+    expect(($this->invoke)('storageTableStatistics', ['device_events']))->toBe([]);
+    $this->connection->responses = [fleetopsStorageQueryError(1146)];
+    expect(fn () => ($this->invoke)('storageTableStatistics', ['device_events']))->toThrow(QueryException::class);
+});
diff --git a/server/tests/SettingControllerContractsTest.php b/server/tests/SettingControllerContractsTest.php
index bfba1ffbc..5989948c1 100644
--- a/server/tests/SettingControllerContractsTest.php
+++ b/server/tests/SettingControllerContractsTest.php
@@ -5,18 +5,18 @@
 
 class FleetOpsSettingControllerProbe extends SettingController
 {
-    public array $configured            = [];
-    public array $configuredCompany     = [];
-    public array $settingValues         = [];
-    public array $orderConfigKeys       = [];
-    public array $settings              = [];
-    public array $companySettings       = [];
-    public array $lookupCompanySettings = [];
-    public mixed $company               = null;
-    public array $notifiables           = [];
-    public array $notifications         = [];
-    public array $providers             = [];
-    public string $googleMapsApiKey     = '';
+    public array $configured                   = [];
+    public array $configuredCompany            = [];
+    public array $settingValues                = [];
+    public array $orderConfigKeys              = [];
+    public array $settings                     = [];
+    public array $companySettings              = [];
+    public array $lookupCompanySettings        = [];
+    public mixed $company                      = null;
+    public array $notifiables                  = [];
+    public array $notifications                = [];
+    public array $providers                    = [];
+    public string $googleMapsApiKey            = '';
     public array $reconciledTelematicsDefaults = [];
 
     protected function configureSetting(string $key, mixed $value): mixed
@@ -583,7 +583,7 @@ function fleetopsJsonPayload(mixed $response): array
         ->and(fleetopsJsonPayload($controller->getTelematicsSettings())['preferences'])->toBe($saved['preferences']);
 
     $controller->settings['fleet-ops.telematics-settings'] = ['max_event_retention_days' => 90, 'max_position_retention_days' => 360];
-    $loaded = fleetopsJsonPayload($controller->getTelematicsSettings());
+    $loaded                                                = fleetopsJsonPayload($controller->getTelematicsSettings());
     expect($loaded['event_retention_days'])->toBe(90)
         ->and($loaded['preferences'])->toBe(['event_retention_days' => 90, 'position_retention_days' => null])
         ->and($loaded['policy'])->toBe(['max_event_retention_days' => 90, 'max_position_retention_days' => 360]);
@@ -610,7 +610,7 @@ function fleetopsJsonPayload(mixed $response): array
         $controller->oldest          = ['device_events' => '2026-08-01 00:00:00'];
         $controller->tableStatistics = [
             'device_events' => ['rows' => 500, 'rows_estimated' => true, 'estimated_bytes' => 16000000],
-            'positions'    => ['rows' => 40, 'rows_estimated' => true, 'estimated_bytes' => 28000],
+            'positions'     => ['rows' => 40, 'rows_estimated' => true, 'estimated_bytes' => 28000],
         ];
 
         $usage = fleetopsJsonPayload($controller->getTelematicsStorageUsage());
@@ -631,10 +631,10 @@ function fleetopsJsonPayload(mixed $response): array
             ->and($controller->countScopes)->toBe(['telematic_deliveries', 'telematic_sync_runs', 'device_events', 'device_events']);
 
         // Missing metadata uses bounded full-table counts, independent of any organization's connections.
-        $controller->tableStatistics                          = [];
+        $controller->tableStatistics                           = [];
         $controller->settings['fleet-ops.telematics-settings'] = ['event_compact_after_days' => 0];
-        $controller->countScopes                              = [];
-        $usage                                                = fleetopsJsonPayload($controller->getTelematicsStorageUsage());
+        $controller->countScopes                               = [];
+        $usage                                                 = fleetopsJsonPayload($controller->getTelematicsStorageUsage());
         expect($usage['tables']['telematic_deliveries'])->toBe(['rows' => 6, 'oldest' => null])
             ->and($usage['tables']['telematic_sync_runs'])->toBe(['rows' => 3, 'oldest' => null])
             ->and($usage['tables']['device_events']['compactable_rows'])->toBe(0)
@@ -746,7 +746,7 @@ public function statistics(array $tables): array
         $connection->setTablePrefix('fb_');
         expect($controller->statistics(['device_events', 'positions']))->toBe([
             'device_events' => ['rows' => 500, 'rows_estimated' => true, 'estimated_bytes' => 16005000],
-            'positions'    => ['rows' => 40, 'rows_estimated' => true, 'estimated_bytes' => 30000],
+            'positions'     => ['rows' => 40, 'rows_estimated' => true, 'estimated_bytes' => 30000],
         ])
             ->and($connection->selects[0][1])->toBe(['fb_device_events', 'fb_positions'])
             ->and($connection->selects[0][0])->toContain('TABLE_NAME IN (?, ?)');
@@ -776,7 +776,7 @@ public function prune(): void
         Illuminate\Support\Facades\Cache::swap(new Illuminate\Cache\CacheManager(app()));
         $dispatcher = new class(app()) extends Illuminate\Bus\Dispatcher {
             public array $jobs = [];
-            public bool $fail = true;
+            public bool $fail  = true;
 
             public function dispatch($command)
             {
@@ -807,3 +807,48 @@ public function dispatch($command)
         }
     }
 });
+
+test('customer history save reports a failed persistence operation', function () {
+    $controller = new class extends FleetOpsSettingControllerProbe {
+        protected function configureCompanySetting(string $key, mixed $value): mixed
+        {
+            return false;
+        }
+    };
+    $controller->company = (object) ['uuid' => 'company-a'];
+    $response            = $controller->saveTelematicsSettings(Request::create('/', 'POST', ['event_retention_days' => 0]));
+    expect($response->getStatusCode())->toBe(500);
+});
+
+test('optional payload counts omit timeouts but surface other database errors', function () {
+    $hadRequest = app()->bound('request');
+    $original   = $hadRequest ? app('request') : null;
+    app()->instance('request', Request::create('/', 'GET', ['include_payload_counts' => true]));
+    try {
+        $controller = new class extends FleetOpsSettingControllerProbe {
+            public int $errorCode = 3024;
+
+            protected function tableUsage(string $table, Closure $scope, string $ageColumn): array
+            {
+                return ['rows' => 5, 'oldest' => null];
+            }
+
+            protected function tableCount(string $table, Closure $scope): int
+            {
+                $error            = new PDOException('Query failed');
+                $error->errorInfo = ['HY000', $this->errorCode, 'Query failed'];
+                throw new Illuminate\Database\QueryException('mysql', 'select payload', [], $error);
+            }
+        };
+        $data = $controller->getTelematicsStorageUsage()->getData(true);
+        expect($data['scope'])->toBe('system')->and($data['tables']['device_events'])->toBe(['rows' => 5, 'oldest' => null]);
+        $controller->errorCode = 1146;
+        expect(fn () => $controller->getTelematicsStorageUsage())->toThrow(Illuminate\Database\QueryException::class);
+    } finally {
+        if ($hadRequest) {
+            app()->instance('request', $original);
+        } else {
+            app()->forgetInstance('request');
+        }
+    }
+});
diff --git a/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php b/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php
index f842dd6a4..9a06a0c4a 100644
--- a/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php
+++ b/server/tests/Unit/Console/PruneTelematicsDataCommandTest.php
@@ -126,7 +126,7 @@ function fleetopsPruneRun(string $uuid, string $telematic, string $status, int $
         fleetopsPruneRun('r-orphan-in-flight', 'tm-gone', 'ingesting', 10),
     ]);
 
-    $command = new PruneTelematicsDataProbe();
+    $command                          = new PruneTelematicsDataProbe();
     $command->options['orphans-only'] = true;
     expect($command->handle())->toBe(PruneTelematicsData::SUCCESS)
         ->and(DB::table('device_events')->pluck('uuid')->all())->toBe(['e-owned'])
@@ -340,3 +340,14 @@ protected function policyFor(?string $companyUuid): Fleetbase\FleetOps\Support\T
         Fleetbase\FleetOps\Support\Telematics\Retention\RetentionPolicy::$settingsResolver = null;
     }
 });
+
+test('prune rejects conflicting company and orphan scopes without deleting history', function () {
+    fleetopsPruneBoot();
+    DB::table('device_events')->insert([fleetopsPruneEvent('keep', 'company-1', 400)]);
+    $command                          = new PruneTelematicsDataProbe();
+    $command->options['company']      = 'company-1';
+    $command->options['orphans-only'] = true;
+    expect($command->handle())->toBe(PruneTelematicsData::FAILURE)
+        ->and($command->messages)->toContain(['error', 'Choose either --company or --orphans-only.'])
+        ->and(DB::table('device_events')->count())->toBe(1);
+});
diff --git a/server/tests/Unit/Jobs/DispatchTelematicsRetentionJobsTest.php b/server/tests/Unit/Jobs/DispatchTelematicsRetentionJobsTest.php
index 2114fcbab..6dd2350d7 100644
--- a/server/tests/Unit/Jobs/DispatchTelematicsRetentionJobsTest.php
+++ b/server/tests/Unit/Jobs/DispatchTelematicsRetentionJobsTest.php
@@ -7,7 +7,7 @@
 
 class FleetOpsTelematicsRetentionDispatchProbe extends DispatchTelematicsRetentionJobs
 {
-    public array $dispatched = [];
+    public array $dispatched  = [];
     public array $companyRows = [];
 
     protected function companies(): Collection
@@ -22,7 +22,7 @@ protected function queueJob(ShouldBeUnique $job): void
 }
 
 test('system cleanup fans out a bounded page and continues from its last company', function () {
-    $job = new FleetOpsTelematicsRetentionDispatchProbe(200, 25);
+    $job              = new FleetOpsTelematicsRetentionDispatchProbe(200, 25);
     $job->companyRows = array_map(fn ($id) => (object) ['id' => $id, 'uuid' => 'company-' . $id], range(201, 300));
     $job->handle();
 
@@ -44,7 +44,7 @@ protected function queueJob(ShouldBeUnique $job): void
 
 test('the final system cleanup page queues an orphan pass even when there are no companies', function () {
     foreach ([[], [(object) ['id' => 1001, 'uuid' => 'company-1001']]] as $companies) {
-        $job = new FleetOpsTelematicsRetentionDispatchProbe(1000);
+        $job              = new FleetOpsTelematicsRetentionDispatchProbe(1000);
         $job->companyRows = $companies;
         $job->handle();
 
@@ -55,3 +55,60 @@ protected function queueJob(ShouldBeUnique $job): void
             ->and($orphans->orphansOnly)->toBeTrue();
     }
 });
+
+test('system cleanup reads all companies in bounded id order and dispatches through the queue', function () {
+    $originalDb         = app()->bound('db') ? app('db') : null;
+    $originalCache      = Illuminate\Support\Facades\Cache::getFacadeRoot();
+    $originalConfig     = config('cache', []);
+    $contract           = Illuminate\Contracts\Bus\Dispatcher::class;
+    $originalDispatcher = app()->bound($contract) ? app($contract) : null;
+    $connection         = new Illuminate\Database\SQLiteConnection(new PDO('sqlite::memory:'));
+    $connection->getSchemaBuilder()->create('companies', function ($table) {
+        $table->integer('id');
+        $table->string('uuid');
+    });
+    foreach (array_reverse(range(1, 103)) as $id) {
+        $connection->table('companies')->insert(['id' => $id, 'uuid' => 'tenant-' . $id]);
+    }
+    app()->instance('db', $connection);
+    Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+    config(['cache.default' => 'array', 'cache.stores.array' => ['driver' => 'array']]);
+    Illuminate\Support\Facades\Cache::swap(new Illuminate\Cache\CacheManager(app()));
+    $dispatcher = new class(app()) extends Illuminate\Bus\Dispatcher {
+        public array $jobs = [];
+
+        public function dispatch($command)
+        {
+            $this->jobs[] = $command;
+
+            return $command;
+        }
+    };
+    app()->instance($contract, $dispatcher);
+    try {
+        (new DispatchTelematicsRetentionJobs(1, 7))->handle();
+        expect($dispatcher->jobs)->toHaveCount(101)
+            ->and($dispatcher->jobs[0]->companyUuid)->toBe('tenant-2')
+            ->and($dispatcher->jobs[99]->companyUuid)->toBe('tenant-101')
+            ->and($dispatcher->jobs[100]->afterCompanyId)->toBe(101);
+        $dispatcher->jobs[100]->handle();
+        expect($dispatcher->jobs)->toHaveCount(104)
+            ->and($dispatcher->jobs[101]->companyUuid)->toBe('tenant-102')
+            ->and($dispatcher->jobs[102]->companyUuid)->toBe('tenant-103')
+            ->and($dispatcher->jobs[103]->orphansOnly)->toBeTrue();
+    } finally {
+        if ($originalDb) {
+            app()->instance('db', $originalDb);
+        } else {
+            app()->forgetInstance('db');
+        }
+        Illuminate\Support\Facades\DB::clearResolvedInstance('db');
+        Illuminate\Support\Facades\Cache::swap($originalCache);
+        config(['cache' => $originalConfig]);
+        if ($originalDispatcher) {
+            app()->instance($contract, $originalDispatcher);
+        } else {
+            app()->forgetInstance($contract);
+        }
+    }
+});
diff --git a/server/tests/Unit/Support/AuthorizationTest.php b/server/tests/Unit/Support/AuthorizationTest.php
index edbae6a3c..100d13d24 100644
--- a/server/tests/Unit/Support/AuthorizationTest.php
+++ b/server/tests/Unit/Support/AuthorizationTest.php
@@ -126,3 +126,17 @@ public function __construct()
     $this->user->setAttribute('type', 'admin');
     expect($middleware[1]['middleware']($request, fn () => 'allowed'))->toBe('allowed');
 });
+
+test('analytics controllers enforce authorization before invoking their next middleware', function (string $class) {
+    $connection = Model::getConnectionResolver()->connection();
+    $connection->table('permissions')->insert(['id' => 'analytics', 'name' => 'fleet-ops view analytics']);
+    $controller = new $class();
+    $middleware = $controller->getMiddleware()[0]['middleware'];
+    $request    = Request::create('/analytics');
+    expect(fn () => $middleware($request, fn () => 'private analytics'))->toThrow(HttpResponseException::class);
+    $this->user->grantedPermissions = ['fleet-ops view analytics'];
+    expect($middleware($request, fn ($forwarded) => $forwarded))->toBe($request);
+})->with([
+    Fleetbase\FleetOps\Http\Controllers\Internal\v1\AnalyticsController::class,
+    Fleetbase\FleetOps\Http\Controllers\Internal\v1\MetricsController::class,
+]);
diff --git a/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php b/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php
index 225e3bb40..a064509c8 100644
--- a/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php
+++ b/server/tests/Unit/Tracking/TrackingOptionsCompanySettingsTest.php
@@ -93,3 +93,17 @@ public function track(Order $order, array|TrackingOptions $options = []): array
     expect($service->received)->toBeInstanceOf(TrackingOptions::class)
         ->and($service->received->provider)->toBe('osrm');
 });
+
+test('tracking remains available with configured defaults when the settings database is unavailable', function () {
+    $connection = fleetopsTrackingOptionsBoot();
+    $connection->getSchemaBuilder()->drop('settings');
+    $original = config('fleetops.tracking', []);
+    try {
+        config(['fleetops.tracking' => ['provider' => 'calculated', 'cache_ttl_seconds' => 17]]);
+        $options = TrackingOptions::fromArray([], 'uncached-unavailable-company');
+        expect($options->provider)->toBe('calculated')->and($options->cacheTtlSeconds)->toBe(17);
+        expect(TrackingOptions::fromArray(['provider' => 'osrm'], 'uncached-unavailable-company')->provider)->toBe('osrm');
+    } finally {
+        config(['fleetops.tracking' => $original]);
+    }
+});